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 <fontconfig> tag:</para>
+
+ <programlisting>
+ <?xml version="1.0"?>
+ <!DOCTYPE fontconfig SYSTEM "fonts.dtd">
+ <fontconfig>
+ </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><dir>/path/to/my/fonts</dir>
+ </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>
+ <match target="font">
+ <test name="size" compare="less">
+ <double>14</double>
+ </test>
+ <edit name="antialias" mode="assign">
+ <bool>false</bool>
+ </edit>
+ </match>
+ </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>
+ <match target="pattern" name="family">
+ <test qual="any" name="family">
+ <string>fixed</string>
+ <edit name="family" mode="assign">
+ <string>mono</string>
+ </edit>
+ </match>
+ <match target="pattern" name="family">
+ <test qual="any" name="family">
+ <string>console</string>
+ <edit name="family" mode="assign">
+ <string>mono</string>
+ </edit>
+ </match>
+ </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>
+ <match target="pattern" name="family">
+ <test qual="any" name="family">
+ <string>mono</string>
+ <edit name="spacing" mode="assign">
+ <int>100</int>
+ </edit>
+ </match>
+ </programlisting>
+
+ <para>Once you have finished editing <filename>local.conf</filename>
+ make sure you end the file with the </fontconfig> 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>
+ <match target="font">
+ <test qual="all" name="rgba">
+ <const>unknown</const>
+ </test>
+ <edit name="rgba" mode="assign">
+ <const>rgb</const>
+ </edit>
+ </match>
+ </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> ->
+ <guimenuitem>Desktop Preferences</guimenuitem> ->
+ <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>