Add very useful information about configuring anti-aliasing with XFree86

4.0.2 and above, and the xfce window manager.

Submitted by:	Rahul Siddharthan <rsidd@physics.iisc.ernet.in>

en_US.ISO8859-1/books/handbook/x11/chapter.sgml

@@ -1,7 +1,7 @@
 <!--
      The FreeBSD Documentation Project
 
-     $FreeBSD: doc/en_US.ISO8859-1/books/handbook/x11/chapter.sgml,v 1.23 2001/07/06 13:03:06 dd Exp $
+     $FreeBSD: doc/en_US.ISO8859-1/books/handbook/x11/chapter.sgml,v 1.24 2001/07/11 16:07:50 murray Exp $
 -->
 
 <chapter id="x11">
@@ -1529,16 +1529,58 @@ EndSection</programlisting>
   <sect1 id="x-fonts">
     <title>Using Fonts in XFree86</title>
 
-    <sect2 id="truetype">
+    <sect2 id="type1">
-    <title>TrueType Fonts</title>
+    <title>Type1 Fonts</title>
-
     <para>The default fonts that ship with
     <application>XFree86</application> are less than ideal for typical
     desktop publishing applications.  Large presentation fonts show up
     jagged and unprofessional looking and small fonts in Netscape are
-    almost completely unintelligible.  Fortunately,
+    almost completely unintelligible.  However, there are several
+    free, high quality Type1 (PostScript) fonts available which 
+    can be readily used
+    with <application>XFree86</application>, either version 3.x or 
+    version 4.x.  For instance, the URW font collection 
+    (<filename>/usr/ports/x11-fonts/urwfonts</filename>) includes
+    high quality versions of standard type1 fonts (Times Roman, 
+    Helvetica, Palatino and others).  The Freefont collection
+    (<filename>/usr/ports/x11-fonts/freefont</filename>) includes
+    many more fonts, but most of them are intended for use in 
+    graphics software such as the Gimp, and are not complete 
+    enough to serve as screen fonts.  In addition,
     <application>XFree86</application> can be configured to use
-    TrueType fonts with a minimum of effort.</para>
+    TrueType fonts with a minimum of effort: see the
+    <link linkend="truetype">section on TrueType fonts</link> later.</para>
+
+    <para>To install the above Type1 font collections, all you have
+    to do is
+<screen>
+&prompt.root; <userinput>cd /usr/ports/x11-fonts/urwfonts</userinput>
+&prompt.root; <userinput>make install clean</userinput> </screen>
+    and likewise with the freefont or other collections.  To tell the X server
+    that these fonts exist, you can add an appropriate line
+    to your <filename>XF86Config</filename> file (in
+    <filename>/etc/</filename> for <application>XFree86</application>
+    version 3, or in <filename>/etc/X11/</filename> for version 4), 
+    which reads
+<screen> FontPath "/usr/X11R6/lib/X11/fonts/URW/" </screen>
+    Alternatively, at the command line in your X session you can write
+<screen>
+&prompt.user; <userinput>xset fp+ /usr/X11R6/lib/X11/fonts/URW</userinput>
+&prompt.user; <userinput>xset fp rehash</userinput>
+</screen>
+    This will work but will be lost when you log out from this
+    session, unless you add it to your startup file
+    (<filename>~/.xinitrc</filename> for a normal startx session,
+    or <filename>~/.xsession</filename> when logging in through a
+    graphical login manager like <application>XDM</application>).  
+    A third way is to use the new 
+    XftConfig file: see the
+    section on <link linkend="antialias">anti-aliasing</link>, later.
+    </para>
+    </sect2>
+
+    <sect2 id="truetype">
+    <title>TrueType Fonts</title>
 
     <para><application>XFree86</application> 4.0 has built in support
     for rendering TrueType fonts.  There are two different modules
@@ -1570,26 +1612,107 @@ EndSection</programlisting>
       port for <application>ttmkfdir</application> in
       <filename>/usr/ports/x11-fonts/ttmkfdir</filename>.</para>
 <screen>&prompt.root; <userinput>cd /usr/X11R6/lib/X11/fonts/TrueType</userinput>
-    &prompt.root; <userinput>ttmkfdir > fonts.dir</userinput></screen>
+&prompt.root; <userinput>ttmkfdir > fonts.dir</userinput></screen>
 
     <para>Now you need to add your TrueType directory to your fonts
-      path. The easiest way to do this is to add the following entries
+      path. This is just the same as described above for <link
-      into your <filename>~/.xinitrc</filename> file.</para>
+      linkend="type1">Type1</link> fonts, that is, use
 <screen>&prompt.user; <userinput>xset fp+ /usr/X11R6/lib/X11/fonts/TrueType</userinput>
-    &prompt.user; <userinput>xset fp rehash</userinput></screen>
+&prompt.user; <userinput>xset fp rehash</userinput></screen>
+      or add a FontPath line to the <filename>XF86Config</filename> file.</para>
 
     <para>That's it. Now Netscape, Gimp, StarOffice, and all of your
       other X applications should now recognize your installed
       TrueType fonts. Extremely small fonts (as with text in a high
       resolution display on a web page) and extremely large fonts
       (within StarOffice) will look much better now.</para>
+    </sect2>
 
-    <para>Starting with version 4.0.2, XFree86 supports antialiased
+    <sect2 id="antialias">
+    <title>Anti-Aliasing your fonts</title>
+
+    <para>Starting with version 4.0.2, XFree86 supports anti-aliased
       fonts.  Currently, most software has not been updated to take
       advantage of this new functionality.  However, Qt (the toolkit
       for the KDE desktop) does; so if you are running XFree86 4.0.2
       (or higher), Qt 2.3 (or higher) and KDE, all your KDE/Qt
-      applications will use anti-aliased fonts.</para>
+      applications can be made to use anti-aliased fonts.</para>
+
+    <para>To configure anti-aliasing, you need to 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, you need to tell the X server about the fonts which you
+      want anti-aliased. To do that, for each font directory you have
+      a line, which looks like
+<screen>dir "/usr/X11R6/lib/X11/Type1"</screen>
+      and likewise for the other font directories (URW, truetype, etc) 
+      containing fonts you'd like anti-aliased.  Anti-aliasing makes
+      sense only for scalable fonts (basically, Type1 and TrueType) so
+      don't include bitmap font directories here.  The
+      directories which you included here can now be commented out 
+      of your <filename>XF86Config</filename> file.</para>
+
+     <para>Next, you may not want to anti-alias normal-sized text.
+      (Antialiasing makes borders slightly fuzzy, which makes very
+      small text more readable and removes "staircases" from large text,
+      but can cause eyestrain if applied to normal text.)  To exclude
+      point sizes between 9 and 13 from anti-aliasing, include the
+      lines
+<screen>
+match
+  any size > 8
+  any size < 14
+edit
+  antialias = false;
+</screen>
+       You may also find that the spacing for some monospaced fonts
+       gets messed up when you turn on anti-aliasing.  This seems to
+       be an issue with KDE, in particular.  One possible fix for this
+       is to force the spacing for such fonts to be 100: add the
+       following lines
+<screen>
+match any family == "fixed"      edit family =+ "mono";
+match any family == "console"    edit family =+ "mono";
+</screen>
+       (this aliases the other common names for fixed fonts as "mono"),
+       and then
+<screen>
+match any family == "mono" edit spacing = 100;
+</screen>
+       Supposing you want to use the Lucidux fonts whenever monospaced 
+       fonts are required (these look nice, and don't seem to suffer
+       from the spacing problem), you could replace that last line
+       with 
+<screen>
+match any family == "mono"       edit family += "LuciduxMono";
+match any family == "Lucidux Mono"      edit family += "LuciduxMono";
+match any family == "LuciduxMono"       edit family =+ "Lucidux Mono";
+</screen> 
+       (the last lines alias different equivalent family names).</para>
+
+       <para>Finally, you want to allow users to add commands to this
+        file, via their personal <filename>.xftconfig</filename>
+        files.  To do this, add a last line,
+<screen>
+includeif  "~/.xftconfig"
+</screen>
+       </para>
+ 
+       <para>That's all; anti-aliasing should be enabled the next
+        time you start the X server.  However, note that your programs must
+        know how to take advantage of it.  At the present time, the toolkit
+        Qt does, so the entire KDE environment can use anti-aliased fonts
+        (see <xref linkend="x11-wm-kde2-antialias"> on KDE 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.</para>
+
+       <para>Anti-aliasing is still new to FreeBSD and XFree86;
+        configuring it should get easier with time, and it will soon be
+        supported by many more applications.</para>
 
     </sect2>
   </sect1>
@@ -1601,7 +1724,7 @@ EndSection</programlisting>
       <para>The X Display Manager (XDM) is an optional part of the X
 	Window System that is used for login session management. This is
 	useful for several types of situations, including minimal
-	<quote>X Terminals</quote> (see section
+	<quote>X Terminals</quote> (see 
 	<xref linkend="term-x">), desktops, and large network display
 	servers. Since the X Window System is network and protocol
 	independent, there are a wide variety of possible configurations
@@ -1802,6 +1925,18 @@ DisplayManager.requestPort:     0</screen>
 	<filename>Xaccess</filename> file, and refer to the &man.xdm.1;
 	manual page.</para>
     </sect2>
+
+     <sect2>
+        <title>Replacements for XDM</title>
+        <para>Several replacements for the default XDM program exist. 
+        One of them, KDM (bundled with KDE) is described in a later
+        <link linkend="x11-wm-kde2-kdm">section</link>.  Apart from
+        various visual improvements and cosmetic frills, it can be
+        easily configured to let users choose their window manager of
+        choice at the time they log in.</para>
+     </sect2>
+
+
   </sect1>
 
   <sect1 id="x11-wm">
@@ -1851,7 +1986,7 @@ DisplayManager.requestPort:     0</screen>
           you haven't added anything special to your configuration
           file, then it is enough to simply type:</para>
 
-        <screen>&prompt.root; <userinput>echo "/usr/X11R6/bin/gnome-wm" > ~/.xinirc</userinput></screen>
+        <screen>&prompt.root; <userinput>echo "/usr/X11R6/bin/gnome-wm" > ~/.xinitrc</userinput></screen>
 
         <para>That's it. Type 'startx' and you will be in the
           GNOME desktop environment.</para>
@@ -1868,7 +2003,7 @@ DisplayManager.requestPort:     0</screen>
 &prompt.root; <userinput>chmod +x ~/.xsession</userinput></screen>
 
         <para>Another option is to configure your display manager to
-          allow choosing the window manager at runtime; the section on
+          allow choosing the window manager at login time; the section on
           <link linkend="x11-wm-kde2-details">KDE2 details</link>
           explains how to do this for <filename>kdm</filename>, the
           display manager of KDE.</para>
@@ -1937,7 +2072,7 @@ DisplayManager.requestPort:     0</screen>
           command; or, configure your display manager to allow
           choosing a desktop at login time.  Below it is explained how
           to do this for <filename>kdm</filename>, KDE's display
-          manager.</para>
+          manager.)</para>
       </sect3>
     </sect2>
     <sect2 id="x11-wm-kde2-details">
@@ -1955,7 +2090,7 @@ DisplayManager.requestPort:     0</screen>
           difficult to learn just by random exploration.</para>
 
       <sect3 id="x11-wm-kde2-kdm">
-        <title>The KDE desktop manager</title>
+        <title>The KDE display manager</title>
 
         <para>If you're an administrator on a multi-user system, you
           may like to have a graphical login screen to welcome users.
@@ -1965,7 +2100,7 @@ DisplayManager.requestPort:     0</screen>
           kdm, which is designed to look more attractive and include
           more login-time options.  In particular, users can easily
           choose (via a menu) which desktop environment (KDE2, GNOME,
-          or something else) to run at runtime.  If you're slightly
+          or something else) to run after logging on.  If you're slightly
           adventurous and you want this added flexibility and visual
           appeal, read on.</para>
 
@@ -2053,32 +2188,82 @@ esac</screen>
         <para>Starting with version 4.0.2, XFree86 supports
           anti-aliasing via its "RENDER" extension, and starting with
           version 2.3, Qt (the toolkit used by KDE) supports this
-          extension.  So if you're running up-to-date software,
+          extension.  Configuring this is described in <xref
+          linkend="antialias"> on  antialiasing X11 fonts.
+          So if you're running up-to-date software,
           anti-aliasing is possible on your KDE2 desktop.  Just go to
           your KDE2 menu, go to Preferences -> Look and Feel -> Style,
           and click on the checkbox "Use Anti-Aliasing for Fonts and
-          Icons".  That's all.</para>
+          Icons".  That's all.  If you're running a Qt application
+          which is not part of KDE, you may need to set the
+          environment variable QT_XFT to true before starting your
+          program.</para>
 
-        <para>A caveat: anti-aliasing works by replacing sharp
+       </sect3>
-          black/white borders of fonts by shades of grey, in effect
+     </sect2>
-          finely blurring them.  This makes very small fonts more
-          readable, and improves the appearance of very large fonts,
-          but normal-sized fonts when anti-aliased can strain the eyes
-          over long periods of time.  It is possible to configure the
-          X font server to anti-alias only certain fonts and only for
-          certain (ranges of) font sizes; this involves editing the
-          file <filename>/usr/X11R6/lib/X11/Xftconfig</filename>.  For
-          details, consult, for instance, the <ulink
-          url="http://keithp.com/~keithp/render/Xft.tutorial">tutorial</ulink>
-          by Keith Packard (who introduced the "RENDER"
-          extension).</para>
 
-        <para>Anti-aliasing is still new to the FreeBSD/XFree86 world,
+     <sect2 id="x11-wm-xfce">
-          but configuring it should become much easier with time.  It
+         <title>XFCE</title>
-          is also available with the GNOME desktop using patches to
+       <sect3 id="x11-wm-xfce-about">
-          the gtk+ toolkit; since these patches break
+         <title>About XFCE</title>
-          internationalisation support, they are not officially
+         <para>XFCE is based on the gtk+ toolkit used by GNOME, but is
-          included at present.</para>
+           much more lightweight and meant for those who want a simple,
+           efficient desktop which is nevertheless easy to use and
+           configure.  Visually, it looks very much like CDE, found on
+           commercial Unix systems.
+           Some of XFCE's features are:</para>
+
+         <itemizedlist>
+           <listitem><para>A simple, easy-to-handle desktop</para></listitem>
+           <listitem><para>Fully configurable via mouse, with drag and
+               drop, etc </para></listitem>
+           <listitem><para>Main panel similar to CDE, with menus, applets and
+ app launchers</para></listitem>
+           <listitem><para>Integrated window manager, file manager,
+ sound manager, GNOME compliance module, and other things</para></listitem>
+           <listitem><para> Themable (since it uses gtk+) </para></listitem>
+           <listitem><para> Fast, light and efficient: ideal for
+ older/slower machines or machiens with memory limitations</para></listitem>
+         </itemizedlist>
+
+         <para> More information on
+           XFCE can be found on the <ulink url="http://www.xfce.org">XFCE
+           website</ulink>.</para>
+       </sect3>
+       <sect3 id="x11-wm-xfce-install">
+         <title>Installing XFCE</title>
+   
+         <para>A binary package for xfce exists (at the time of
+           writing). To install, simply do this:</para>
+
+         <screen>&prompt.root; <userinput>pkg_add -r xfce</userinput></screen>
+
+         <para> Alternatively, you may prefer to build from source.
+           The ports tree comes to the rescue again: </para>
+
+         <screen>&prompt.root; <userinput>cd /usr/ports/x11-wm/xfce</userinput>
+ &prompt.root; <userinput>make install clean</userinput></screen>
+
+         <para> All necessary source packages (including dependencies)
+           will be automagically fetched, built and installed, and
+           the build areas cleaned up afterwards.</para>
+
+         <para>Now you want to tell the X server to launch
+           XFCE the next time you start X. Simply type
+           this:</para>
+
+         <screen>&prompt.root; <userinput>echo "/usr/X11R6/bin/startxfce" > ~/.xinitrc</userinput></screen>
+
+         <para>The next time you start X, XFCE will be your
+           desktop.  (Note, as before:
+           if you're logging in via a display manager like
+           <filename>xdm</filename>,  you should either create an
+           <filename>.xsession</filename>, as described in the
+           section on <link linkend="x11-wm-gnome">GNOME</link>, but
+           with the <filename>/usr/X11R6/bin/startxfce</filename>
+           command; or, configure your display manager to allow
+           choosing a desktop at login time, as explained in
+           the section on <link linkend="x11-wm-kde2-kdm">kdm</link>.)</para>
 
       </sect3>
     </sect2>