Skip site navigation (1)Skip section navigation (2)
Date:      Sun, 4 May 2003 19:07:07 -0400 (EDT)
From:      Joe Marcus Clarke <marcus@FreeBSD.org>
To:        FreeBSD-gnats-submit@FreeBSD.org
Subject:   docs/51770: [PATCH] Update anti-alias font section of handbook
Message-ID:  <200305042307.h44N77UY014499@shumai.marcuscom.com>
Resent-Message-ID: <200305042310.h44NAHG8057819@freefall.freebsd.org>

next in thread | raw e-mail | index | archive | help

>Number:         51770
>Category:       docs
>Synopsis:       [PATCH] Update anti-alias font section of handbook
>Confidential:   no
>Severity:       non-critical
>Priority:       high
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          update
>Submitter-Id:   current-users
>Arrival-Date:   Sun May 04 16:10:16 PDT 2003
>Closed-Date:
>Last-Modified:
>Originator:     Joe Marcus Clarke
>Release:        FreeBSD 4.8-STABLE i386
>Organization:
MarcusCom, Inc.
>Environment:
System: FreeBSD shumai.marcuscom.com 4.8-STABLE FreeBSD 4.8-STABLE #9: Wed Apr 30 00:31:53 EDT 2003 marcus@shumai.marcuscom.com:/usr/obj/usr/src/sys/SHUMAI i386


	
>Description:
The anti-aliased fonts section of the handbook is severely out of date.
It still discusses the old XftConfig style of enable anti-aliasing.  All of
this has been pushed into fontconfig.  Attached is a diff to the x11
chapter of the handbook that brings this section in line with
Xft+fontconfig as well as updates the GNOME anti-aliasing section for
GNOME 2.
>How-To-Repeat:
	
>Fix:

	

--- chapter.sgml.diff begins here ---
Index: chapter.sgml
===================================================================
RCS file: /home/dcvs/doc/en_US.ISO8859-1/books/handbook/x11/chapter.sgml,v
retrieving revision 1.110
diff -u -r1.110 chapter.sgml
--- doc/en_US.ISO8859-1/books/handbook/x11/chapter.sgml	29 Apr 2003 20:47:06 -0000	1.110
+++ doc/en_US.ISO8859-1/books/handbook/x11/chapter.sgml	4 May 2003 23:02:40 -0000
@@ -693,46 +693,65 @@
     <sect2 id="antialias">
     <title>Anti-Aliased Fonts</title>
 
-    <para>Starting with version 4.0.2, <application>XFree86</application>
-      supports anti-aliased
-      fonts.  Currently, most software has not been updated to take
-      advantage of this new functionality.  However, Qt (the toolkit
-      for the <application>KDE</application> desktop) does; so if
-      <application>XFree86 4.0.2</application> is used
-      (or higher), Qt 2.3 (or higher) and <application>KDE</application>,
-      all KDE/Qt applications can be made to use anti-aliased
-      fonts.</para>
-
-    <para>To configure anti-aliasing, create (or edit, if
-      it already exists) the file
-      <filename>/usr/X11R6/lib/X11/XftConfig</filename>.  Several
-      advanced things can be done with this file; this section
-      describes only the simplest possibilities.</para>
-
-     <para>First, tell the X server about the fonts that are to be
-      anti-aliased.  For each font directory, add a line similar
-      to this:</para>
-
-      <programlisting>dir "/usr/X11R6/lib/X11/fonts/Type1"</programlisting>
-
-    <para>Likewise for the other font directories (URW, TrueType, etc)
-      containing fonts to be anti-aliased.  Anti-aliasing makes
-      sense only for scalable fonts (basically, Type1 and TrueType) so
-      do not include bitmap font directories here.  The
-      directories included here can now be commented out
-      of the <filename>XF86Config</filename> file.</para>
+    <para>Anti-aliasing has been available in 
+      <application>XFree86</application> since 4.0.2.  However
+      it was not easy to configure as it is in 
+      <application>XFree86</application> 4.3.0.  Starting in version 4.3.0, 
+      all fonts in <filename>/usr/X11R6/lib/X11/fonts/</filename> and
+      <filename>~/.fonts/</filename> are automatically 
+      made available for anti-aliasing to Xft-aware applications.  Not
+      all applications are Xft-aware yet, but many have received Xft support.
+      Examples of Xft-aware applications include Qt 2.3 and higher (the 
+      toolkit for the <application>KDE</application> desktop), 
+      Gtk+ 2.0 and higher (the toolkit for the 
+      <application>GNOME</application> desktop), and Mozilla 1.2 and higher.
+    </para>
+
+    <para>In order to control which fonts are anti-aliased, or to configure
+      anti-aliasing properties, create (or edit, if it already exists) the
+      file <filename>/usr/X11R6/etc/fonts/local.conf</filename>.  Several 
+      adavanced features of the Xft font system can be tuned using this file; 
+      this section describes only some simple possibilities.  For more details, 
+      please see fonts-conf(5).</para>
+
+     <para>This file must be in XML format.  Pay careful attention to case,
+       and make sure all tags are properly closed.  The file begins with
+       the usual XML header followed by a DOCTYPE definition, and
+       then the &lt;fontconfig&gt; tag:</para>
+
+      <programlisting>
+        &lt;?xml version="1.0"?&gt;
+        &lt;!DOCTYPE fontconfig SYSTEM "fonts.dtd"&gt;
+        &lt;fontconfig&gt;
+      </programlisting>
+
+     <para>As previously stated, all fonts in
+       <filename>/usr/X11R6/lib/X11/fonts/</filename> as well as
+       <filename>~/.fonts/</filename> are already made available
+       to Xft-aware applications.  If you wish to add another directory
+       outside of these two directory trees, add a line similar to the
+       following to <filename>/usr/X11R6/etc/fonts/local.conf</filename>:
+     </para>
+
+      <programlisting>&lt;dir&gt;/path/to/my/fonts&lt;/dir&gt;
+      </programlisting>
 
     <para>Anti-aliasing makes borders slightly fuzzy, which makes very
       small text more readable and removes <quote>staircases</quote> from
       large text, but can cause eyestrain if applied to normal text.  To
-      exclude point sizes between 9 and 13 from anti-aliasing, include
+      exclude point sizes smaller than 14 point from anti-aliasing, include
       these lines:</para>
 
-      <programlisting>match
-  any size > 8
-  any size < 14
-edit
-  antialias = false;</programlisting>
+      <programlisting>
+        &lt;match target="font"&gt;
+            &lt;test name="size" compare="less"&gt;
+                &lt;double&gt;14&lt;/double&gt;
+            &lt;/test&gt;
+            &lt;edit name="antialias" mode="assign"&gt;
+                &lt;bool&gt;false&lt;/bool&gt;
+            &lt;/edit&gt;
+        &lt;/match&gt;
+      </programlisting>
 
     <para>Spacing for some monospaced fonts may also be inappropriate
       with anti-aliasing.  This seems to be an issue with
@@ -740,44 +759,80 @@
       this is to force the spacing for such fonts to be 100.  Add the
       following lines:</para>
 
-      <programlisting>match any family == "fixed"      edit family =+ "mono";
-match any family == "console"    edit family =+ "mono";</programlisting>
+     <programlisting>
+       &lt;match target="pattern" name="family"&gt;
+           &lt;test qual="any" name="family"&gt;
+               &lt;string&gt;fixed&lt;/string&gt;
+           &lt;edit name="family" mode="assign"&gt;
+               &lt;string&gt;mono&lt;/string&gt;
+           &lt;/edit&gt;
+        &lt;/match&gt;
+        &lt;match target="pattern" name="family"&gt;
+            &lt;test qual="any" name="family"&gt;
+                &lt;string&gt;console&lt;/string&gt;
+            &lt;edit name="family" mode="assign"&gt;
+                &lt;string&gt;mono&lt;/string&gt;
+            &lt;/edit&gt;
+        &lt;/match&gt;
+      </programlisting>
 
       <para>(this aliases the other common names for fixed fonts as
        <literal>"mono"</literal>), and then add:</para>
 
-      <programlisting>match any family == "mono" edit spacing = 100;</programlisting>
-
-      <para>Supposing the
-        <literal>Lucidux</literal> fonts as desired whenever
-        monospaced fonts are required (these look nice, and do not seem
-        to suffer from the spacing problem), replace that last
-        line with these:</para>
-
-      <programlisting>match any family == "mono"       edit family += "LuciduxMono";
-match any family == "Lucidux Mono"      edit family += "LuciduxMono";
-match any family == "LuciduxMono"       edit family =+ "Lucidux Mono";</programlisting>
-
-       <para>(the last lines alias different equivalent family names).</para>
-
-       <para>Finally, it is nice to allow users to add commands to this
-        file, via their personal <filename>.xftconfig</filename>
-        files.  To do this, add a last line:</para>
-
-       <programlisting>includeif  "~/.xftconfig"</programlisting>
+       <programlisting>
+         &lt;match target="pattern" name="family"&gt;
+             &lt;test qual="any" name="family"&gt;
+                 &lt;string&gt;mono&lt;/string&gt;
+             &lt;edit name="spacing" mode="assign"&gt;
+                 &lt;int&gt;100&lt;/int&gt;
+             &lt;/edit&gt;
+         &lt;/match&gt;
+      </programlisting>
+
+       <para>Once you have finished editing <filename>local.conf</filename>
+         make sure you end the file with the &lt;/fontconfig&gt; tag.
+	 Not doing this will cause your changes to be ignored.</para>
+
+       <para>The default font set that comes with 
+         <application>XFree86</application> is not very
+         desirable when it comes to anti-aliasing.  A much better
+	 set of default fonts can be found in the 
+	 <filename role="package">x11-fonts/bitstream-vera</filename>
+	 port.  This port will install a
+	 <filename>/usr/X11R6/etc/fonts/local.conf</filename> file
+	 if one does not exist already.  If the file does exist,
+	 the port will create a <filename>/usr/X11R6/etc/fonts/local.conf-vera
+	 </filename> file.  Merge the contents of this file into
+	 <filename>/usr/X11R6/etc/fonts/local.conf</filename>, and the 
+	 Bitstream fonts will automatically replace the default 
+	 <application>XFree86</application> Serif, Sans Serif, and Monospaced 
+	 fonts.</para>
+
+       <para>Finally, users can add their own settings via their personal 
+        <filename>.fonts.conf</filename> files.  To do this, each user should 
+	simply create a <filename>~/.fonts.conf</filename>.  This file must 
+	also be in XML format.</para>
 
        <para>One last point: with an LCD screen, sub-pixel sampling may be
         desired.  This basically treats the (horizontally separated)
         red, green and blue components separately to improve the horizontal
         resolution; the results can be dramatic.  To enable this, add the
-        line somewhere in the <filename>XftConfig</filename> file:</para>
-
-       <programlisting>match edit rgba=rgb;</programlisting>
+        line somewhere in the <filename>local.conf</filename> file:</para>
 
-       <para>(depending on the sort of display, the last word may need to
-	be changed from <quote>rgb</quote> to <quote>bgr</quote>,
-	<quote>vrgb</quote> or <quote>vbgr</quote>: experiment and see which
-	works best.)</para>
+       <programlisting>
+         &lt;match target="font"&gt;
+             &lt;test qual="all" name="rgba"&gt;
+                 &lt;const&gt;unknown&lt;/const&gt;
+             &lt;/test&gt;
+             &lt;edit name="rgba" mode="assign"&gt;
+                 &lt;const&gt;rgb&lt;/const&gt;
+             &lt;/edit&gt;
+         &lt;/match&gt;
+       </programlisting>
+
+       <para>(depending on the sort of display, <quote>rgb</quote> may need to
+	to <quote>bgr</quote>, <quote>vrgb</quote> or <quote>vbgr</quote>: 
+	experiment and see which works best.)</para>
 
        <para>Anti-aliasing should be enabled the next time the X server is
         started.  However, note that programs must know how to take
@@ -786,17 +841,12 @@
         can use anti-aliased fonts
         (see <xref linkend="x11-wm-kde-antialias"> on
         <application>KDE</application> for
-        details); there are patches for GTK+ to do the same,
-        so if compiled against such a patched GTK+, the GNOME environment
-        and Mozilla can also use anti-aliased fonts.  In fact, there
-	is now a port called <filename role="package">x11/gdkxft</filename>
-	which allows one to use antialiased fonts without recompiling: see
-        <xref linkend="x11-wm-gnome-antialias"> for details.</para>
-
-       <para>Anti-aliasing is still new to FreeBSD and
-        <application>XFree86</application>;
-        configuring it should get easier with time, and it will soon be
-        supported by many more applications.</para>
+        details).  Gtk+ and GNOME can also be made to use anti-aliasing
+	via the <quote>Font</quote> capplet (see
+	<xref linkend="x11-wm-gnome-antialias"> for details).  By default,
+	Mozilla 1.2 and greater will automatically use anti-aliasing.
+	To disable this, rebuild Mozilla with the 
+	<quote>-DWITHOUT_XFT</quote> flag.</para>
     </sect2>
   </sect1>
 
@@ -1104,12 +1154,12 @@
         <para>To install the <application>GNOME</application> package
           from the network, simply type:</para>
 
-        <screen>&prompt.root; <userinput>pkg_add -r gnome</userinput></screen>
+        <screen>&prompt.root; <userinput>pkg_add -r gnome2</userinput></screen>
 
         <para>To build <application>GNOME</application> from source, use
           the ports tree:</para>
 
-        <screen>&prompt.root; <userinput>cd /usr/ports/x11/gnome</userinput>
+        <screen>&prompt.root; <userinput>cd /usr/ports/x11/gnome2</userinput>
 &prompt.root; <userinput>make install clean</userinput></screen>
 
         <para>Once <application>GNOME</application> is installed,
@@ -1150,47 +1200,24 @@
       <sect3 id="x11-wm-gnome-antialias">
         <title>Anti-aliased fonts with GNOME</title>
 
-        <para>While anti-aliased fonts made their first appearance on
-	  <application>XFree86</application> desktops in the
-	  <application>KDE</application> environment and are supported there
-	  in the standard installation, it is also possible to use them with
-	  GTK applications such as the <application>GNOME</application>
-	  environment.  The most straightforward way is probably by
-          using the <application>libgdkxft</application> library, in
-	  the <filename role="package">x11/gdkxft</filename> port.  After
-	  installing this port, read the
-          <filename>/usr/X11R6/share/doc/gdkxft/README</filename> file
-          carefully.</para>
-
-        <para>Then, all that is needed is to tell GTK
-          applications to look for their font-rendering functions in
-          <filename>libgdkxft.so</filename> before looking in the
-          standard place, <filename>libgdk.so</filename>.  This is
-          easily accomplished by setting an environment variable to
-          point to the right place; with the Bourne shell
-          (<application>/bin/sh</application>) or similar shells, type
-          the command (to start <application>The Gimp</application>,
-          say)</para>
-
-	<screen>&prompt.user; <userinput>LD_PRELOAD=/usr/X11R6/lib/libgdkxft.so gimp</userinput></screen>
-
-        <para>and with csh and similar shells, type</para>
-
-	<screen>&prompt.user; <userinput>setenv LD_PRELOAD /usr/X11R6/lib/libgdkxft.so</userinput>
-&prompt.user; <userinput>gimp</userinput></screen>
-
-        <para>Or, the commands</para>
-
-	<programlisting>LD_PRELOAD=/usr/X11R6/lib/libgdkxft.so
-export LD_PRELOAD</programlisting>
-
-        <para>can be put into <filename>.xinitrc</filename>,
-          <filename>.xsession</filename> or in the appropriate
-          place(s) in
-          <filename>/usr/X11R6/lib/X11/xdm/Xsession</filename>,
-          depending on how X is normally started.  However, this
-          short-cut may cause problems if Linux GTK binaries are
-          run.</para>
+	<para>Starting with version 4.0.2, <application>XFree86</application>
+	  supports anti-aliasing via its <quote>RENDER</quote> extension.
+	  Gtk+ 2.0 and greater (the toolkit used by
+	  <application>GNOME</application> can make use of this
+	  functionality.  Configuring anti-aliasing is described in
+	  <xref linkend="antialias">.  So, with up-to-date software,
+	  anti-aliasing is possible within the
+	  <application>GNOME</application> desktop.  Just go to
+	  <guimenuitem>Applications</guimenuitem> -&gt;
+	  <guimenuitem>Desktop Preferences</guimenuitem> -&gt;
+	  <guimenuitem>Font</guimenuitem>, and select either
+	  <guibutton>Best shapes</guibutton>, 
+	  <guibutton>Best contrast</guibutton>, or
+	  <guibutton>Subpixel smoothing (LCDs)</guibutton>.  For a
+	  Gtk+ application that is not part of the 
+	  <application>GNOME</application> desktop, set the
+	  environment variable <varname>GDK_USE_XFT</varname> to
+	  <literal>1</literal> before launching the program.</para>
       </sect3>
     </sect2>
 
--- chapter.sgml.diff ends here ---


>Release-Note:
>Audit-Trail:
>Unformatted:



Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200305042307.h44N77UY014499>