Add more information about using KDE2.

- Anti-aliased fonts
  - KDM
  - Setting up X to choose between GNOME and KDE

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.19 2001/06/22 22:02:19 dd Exp $
+     $FreeBSD: doc/en_US.ISO8859-1/books/handbook/x11/chapter.sgml,v 1.20 2001/06/23 00:24:42 dd Exp $
 -->
 
 <chapter id="x11">
@@ -1343,49 +1343,49 @@ For further configuration, refer to /usr/X11R6/lib/X11/doc/README.Config.</scree
     </para>
 
     <para>For <application>XFree86</application> 3.3.X you will need
-    to run a separate TrueType font
+      to run a separate TrueType font
-    server. <application>Xfstt</application> is commonly used for this
+      server. <application>Xfstt</application> is commonly used for
-    purpose. To install <application>Xfstt</application> on your
+      this purpose. To install <application>Xfstt</application> on
-    FreeBSD system simply install the port from
+      your FreeBSD system simply install the port from
-    <filename>/usr/ports/x11-servers/Xfstt</filename></para>
+      <filename>/usr/ports/x11-servers/Xfstt</filename></para>
 
     <para>You should now make a directory for your TrueType fonts
-    (e.g. <filename>/usr/X11R6/lib/X11/fonts/TrueType</filename>) and
+      (e.g. <filename>/usr/X11R6/lib/X11/fonts/TrueType</filename>)
-    copy all of your TrueType fonts into this directory. Keep in mind
+      and copy all of your TrueType fonts into this directory. Keep in
-    that you can not take TrueType fonts directly from a Macintosh;
+      mind that you can not take TrueType fonts directly from a
-    they must be in Unix/DOS/Windows format for use by
+      Macintosh; they must be in Unix/DOS/Windows format for use by
-    <application>XFree86</application>. Once you have copied the files
+      <application>XFree86</application>. Once you have copied the
-    into this directory you need to use
+      files into this directory you need to use
-    <application>ttmkfdir</application> to create a
+      <application>ttmkfdir</application> to create a
-    <filename>fonts.dir</filename> file so that the X font renderer
+      <filename>fonts.dir</filename> file so that the X font renderer
-    knows that you've installed these new files. There is a FreeBSD
+      knows that you've installed these new files. There is a FreeBSD
-    port for <application>ttmkfdir</application> in
+      port for <application>ttmkfdir</application> in
-    <filename>/usr/ports/x11-fonts/ttmkfdir</filename>.</para>
+      <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>
 
     <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. The easiest way to do this is to add the following entries
-    into your <filename>~/.xinitrc</filename> file.</para>
+      into your <filename>~/.xinitrc</filename> file.</para>
 <screen>
     &prompt.user; <userinput>xset fp+ /usr/X11R6/lib/X11/fonts/TrueType</userinput>
     &prompt.user; <userinput>xset fp rehash</userinput>
 </screen>
 
     <para>That's it. Now Netscape, Gimp, StarOffice, and all of your
-    other X applications should now recognize your installed TrueType
+      other X applications should now recognize your installed
-    fonts. Extremely small fonts (as with text in a high resolution
+      TrueType fonts. Extremely small fonts (as with text in a high
-    display on a web page) and extremely large fonts (within
+      resolution display on a web page) and extremely large fonts
-    StarOffice) will look much better now.</para>
+      (within StarOffice) will look much better now.</para>
 
-    <para>Anti-aliasing: Starting with XFree86 4.0.2, XFree86 does now
+    <para>Starting with version 4.0.2, XFree86 supports antialiased
-    support antialiased fonts.  As of now, a lot of software does not
+      fonts.  Currently, most software has not been updated to take
-    take advantage of it, but Qt (the toolkit for the KDE desktop) does;
+      advantage of this new functionality.  However, Qt (the toolkit
-    so if you are running this version of XFree86 (or higher), Qt 2.3
+      for the KDE desktop) does; so if you are running XFree86 4.0.2
-    (or higher) and KDE, all your KDE/Qt applications will use
+      (or higher), Qt 2.3 (or higher) and KDE, all your KDE/Qt
-    anti-aliased fonts.</para>
+      applications will use anti-aliased fonts.</para>
 
     </sect2>
   </sect1>
@@ -1655,6 +1655,23 @@ DisplayManager.requestPort:     0
 
         <para>That's it. Now just type 'startx' and you will be in the
           GNOME desktop environment.</para>
+        <para> Note: if you're running a display manager like xdm,
+          this will not work.  Instead, you should create an
+          executable <filename>.xsession</filename> file with the same
+          command in it.  To do this, edit your file (if you already
+          have one) and replace the existing wm command with
+          <filename>/usr/X11R6/bin/gnome-wm</filename>; or
+          else,</para>
+
+        <screen>&prompt.root; <userinput>echo "#!/bin/sh" > ~/.xsession</userinput>
+&prompt.root; <userinput>echo "/usr/X11R6/bin/gnome-wm" >> ~/.xsession</userinput>
+&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
+          <link linkend="x11-wm-kde2-details">KDE2 details</link>
+          explains how to do this for <filename>kdm</filename>, the
+          display manager of KDE.</para>
       </sect3>
     </sect2>
 
@@ -1692,24 +1709,183 @@ DisplayManager.requestPort:     0
         <title>Installing KDE2</title>
    
         <para>At the time this was written, a package for kde2 doesn't
-          exist yet. No problem!  We'll just use the ports to install
+          exist yet. No problem!  The ports tree hides all the
-          it. To install KDE2, do this:</para>
+          complexity of building a package from source.  To install
+          KDE2, do this :</para>
 
         <screen>&prompt.root; <userinput>cd /usr/ports/x11/kde2</userinput>
 &prompt.root; <userinput>make install clean</userinput></screen>
 
-        <para>That fetched all the necessary files from the internet,
+        <para>This command will fetch all the necessary files from the
-          compiled kde2, installed kde2, and cleaned up after itself
+          Internet, configure and compile KDE2, install the
-          after the install.</para>
+          applications, and then clean up after itself.</para>
 
         <para>Now you're going to have to tell the X server to launch
-          kde2 instead of a default window manager. Do this by typing
+          KDE2 instead of a default window manager. Do this by typing
           this:</para>
 
         <screen>&prompt.root; <userinput>echo "/usr/X11R6/bin/startkde" > ~/.xinitrc</userinput></screen>
 
-        <para>Now everytime you go into X-Windows, kde2 will be your
+        <para>Now everytime you go into X-Windows, KDE2 will be your
-          desktop.</para>
+          desktop.  (Note: this will not work if you're logging in via
+          a display manager like <filename>xdm</filename>.  In that
+          case you have two options: create an
+          <filename>.xsession</filename> file as described in the
+          section on <link linkend="x11-wm-gnome">GNOME</link>, but
+          with the <filename>/usr/X11R6/bin/startkde</filename>
+          command instead of the <filename>gnome-wm</filename>
+          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>
+      </sect3>
+    </sect2>
+    <sect2 id="x11-wm-kde2-details">
+        <title>More details on KDE2</title>
+
+        <para>Now that KDE2 is installed on your system, you'll find
+          that you can learn a lot from its help pages, or just by
+          pointing and clicking at various menus.  Windows or Mac
+          users will feel quite at home.</para>
+
+        <para>The best reference for KDE is the on-line documentation.
+          KDE comes with its own web browser, Konqueror, dozens of
+          useful applications, and extensive documentation.  This
+          section only discusses somewhat technical things which are
+          difficult to learn just by random exploration.</para>
+
+      <sect3 id="x11-wm-kde2-kdm">
+        <title>The KDE desktop 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.
+          You can use <link
+          linkend="x-xdm"><filename>xdm</filename></link>, as
+          described earlier.  However, KDE includes an alternative,
+          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
+          adventurous and you want this added flexibility and visual
+          appeal, read on.</para>
+
+	<para>To begin with, run the KDE2 control panel,
+	  <filename>kcontrol</filename>, as root.  Note: it is
+	  generally considered unsafe to run your entire X environment
+	  as root.  Instead, run your window manager as a normal user,
+	  open a terminal window (such as <filename>xterm</filename>
+	  or KDE's <filename>konsole</filename>, become root with
+	  <userinput>su</userinput> (you need to be in the "wheel"
+	  group in <filename>/etc/group</filename> for this), and then
+	  type <userinput>kcontrol</userinput>.</para>
+
+	<para> Click on the icon on the left marked "System", then on
+	  "Login manager".  On the right you'll see various
+	  configurable options, which the KDE manual will explain in
+	  greater detail.  Click on "sessions" on the right.
+	  Depending on what window managers or desktop environments
+	  you have currently installed, you can type their names in
+	  "New type" and add them.  (These are just labels so far, not
+	  commands, so you can write "KDE" and "GNOME" rather than
+	  "startkde" or "gnome-wm".)  Include a label
+	  "failsafe".</para>
+
+	<para> Play with the other menus as you like (those are mainly
+          cosmetic and self-explanatory).  When you're done, click on
+          "Apply" at the bottom, and quit the control center.</para>
+
+        <para> To make sure kdm understands what your above labels
+          (KDE, GNOME etc) mean, you need to edit some more files: the
+          same ones used by <link linkend="x-xdm">xdm</link>.  In your
+          terminal window, as root, edit the file
+          <filename>/usr/X11R6/lib/X11/xdm/Xsession</filename>.  You
+          will come across a section in the middle looking like this
+          (by default):</para>
+<screen>
+case $# in
+1)
+        case $1 in
+        failsafe)
+                exec xterm -geometry 80x24-0-0
+                ;;
+        esac
+esac
+</screen>
+        <para>You will need to add a few lines to this section.
+	  Assuming the labels you gave earlier were KDE2 and GNOME,
+	  the following will do:</para>
+<screen>
+case $# in
+1)
+        case $1 in
+        KDE2)
+                exec /usr/X11R6/bin/startkde
+                ;;
+        GNOME)
+                exec /usr/X11R6/bin/gnome-wm
+                ;;
+        failsafe)
+                exec xterm -geometry 80x24-0-0
+                ;;
+        esac
+esac
+</screen>
+
+        <para>To make sure your KDE choice of a login-time desktop
+          background is also honored, you will need to add the
+          following line to
+          <filename>/usr/X11R6/lib/X11/xdm/Xsetup_0</filename>:</para>
+        <screen>
+        /usr/X11R6/bin/kdmdesktop
+        </screen>
+
+        <para>Now, you need only to make sure kdm is started at the
+          next bootup.  To learn how to do this, read the section on
+          <link linkend="x-xdm">xdm</link>, and do the same thing
+          replacing references to the <filename>xdm</filename> program
+          by <filename>kdm</filename>.</para>
+
+        <para>That's it. Your next login screen should have a pretty
+          face and lots of menus.</para>
+
+      </sect3>
+      <sect3 id="x11-wm-kde2-antialias">
+        <title>Anti-aliased fonts</title>
+
+        <para>Tired of blocky staircase edges to your fonts under X11?
+          Tired of unreadable text in web browsers?  Well, no
+          more.</para>
+
+        <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,
+          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>
+
+        <para>A caveat: anti-aliasing works by replacing sharp
+          black/white borders of fonts by shades of grey, in effect
+          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,
+          but configuring it should become much easier with time.  It
+          is also available with the GNOME desktop using patches to
+          the gtk+ toolkit; since these patches break
+          internationalisation support, they are not officially
+          included at present.</para>
+
       </sect3>
     </sect2>
   </sect1>