&os; and FreeBSD-5 section cleanup.
[dragonfly.git] / en / books / handbook / x11 / chapter.sgml
1 <!--
2      The FreeBSD Documentation Project
3
4      $FreeBSD: doc/en_US.ISO8859-1/books/handbook/x11/chapter.sgml,v 1.136 2004/04/18 00:30:53 ale Exp $
5      $DragonFly: doc/en/books/handbook/x11/chapter.sgml,v 1.3 2004/07/19 15:37:52 justin Exp $
6 -->
7
8 <chapter id="x11">
9   <title>The X Window System</title>
10
11   <sect1 id="x11-synopsis">
12     <title>Synopsis</title>
13
14     <para>&os; uses <application>&xfree86;</application> to provide users with
15       a powerful graphical user interface.  <application>&xfree86;</application>
16       is an open-source implementation of the X Window System.  This chapter
17       will cover installation and configuration of
18       <application>&xfree86;</application> on a &os; system.  For more
19       information on <application>&xfree86;</application> and video hardware that
20       it supports, check the <ulink
21         url="http://www.XFree86.org/">&xfree86;</ulink> web site.</para>
22
23     <para>After reading this chapter, you will know:</para>
24
25     <itemizedlist>
26       <listitem>
27         <para>The various components of the X Window System, and how they
28           interoperate.</para>
29       </listitem>
30
31       <listitem>
32         <para>How to install and configure
33           <application>&xfree86;</application>.</para>
34       </listitem>
35
36       <listitem>
37         <para>How to install and use different window managers.</para>
38       </listitem>
39
40       <listitem>
41         <para>How to use &truetype; fonts in
42           <application>&xfree86;</application>.</para>
43       </listitem>
44
45       <listitem>
46         <para>How to set up your system for graphical logins
47           (<application>XDM</application>).</para>
48       </listitem>
49     </itemizedlist>
50
51     <para>Before reading this chapter, you should:</para>
52
53     <itemizedlist>
54       <listitem><para>Know how to install additional third-party
55         software (<xref linkend="ports">).</para></listitem>
56     </itemizedlist>
57   </sect1>
58
59   <sect1 id="x-understanding">
60     <title>Understanding X</title>
61
62     <para>Using X for the first time can be somewhat of a shock to someone
63       familiar with other graphical environments, such as &microsoft.windows; or
64       &macos;.</para>
65
66     <para>It is not necessary to understand all of the details of various
67       X components and how they interact; however, some basic knowledge makes
68       it possible to take advantage of X's strengths.</para>
69
70     <sect2>
71       <title>Why X?</title>
72
73       <para>X is not the first window system written for &unix;, but it is the
74         most popular.  X's original development team had worked on another
75         window system before writing X.  That system's name was
76         <quote>W</quote> (for <quote>Window</quote>).  X is just the next
77         letter in the Roman alphabet.</para>
78
79       <para>X can be called <quote>X</quote>, <quote>X Window System</quote>,
80           <quote>X11</quote>, and other terms.  Calling X11
81           <quote>X Windows</quote> can offend some people;
82           see &man.X.7; for a bit more insight on this.</para>
83     </sect2>
84
85     <sect2>
86       <title>The X Client/Server Model</title>
87
88       <para>X was designed from the beginning to be network-centric, and
89         adopts a <quote>client-server</quote> model.  In the X model, the
90         <quote>X server</quote> runs on the computer that has the keyboard,
91         monitor, and mouse attached.  The server is responsible for managing
92         the display, handling input from the keyboard and mouse, and so on.
93         Each X application (such as <application>XTerm</application>, or
94         <application>&netscape;</application>) is a <quote>client</quote>.  A
95         client sends messages to the server such as <quote>Please draw a
96           window at these coordinates</quote>, and the server sends back
97           messages such as <quote>The user just clicked on the OK
98           button</quote>.</para>
99
100       <para>If there is only one computer involved, such as in a home or small
101         office environment, the X server and the X clients will be running on
102         the same computer.  However, it is perfectly possible to run the X
103         server on a less powerful desktop computer, and run X applications
104         (the clients) on, say, the powerful and expensive machine that serves
105         the office.  In this scenario the communication between the X client
106         and server takes place over the network.</para>
107
108       <para>This confuses some people, because the X terminology is
109         exactly backward to what they expect.  They expect the <quote>X
110           server</quote> to be the big powerful machine down the hall, and
111         the <quote>X client</quote> to be the machine on their desk.</para>
112
113       <para>Remember that the X server is the machine with the monitor and
114         keyboard, and the X clients are the programs that display the
115         windows.</para>
116
117       <para>There is nothing in the protocol that forces the client and
118         server machines to be running the same operating system, or even to
119         be running on the same type of computer.  It is certainly possible to
120         run an X server on &microsoft.windows; or Apple's &macos;, and there are
121         various free and commercial applications available that do exactly
122         that.</para>
123
124       <para>The X server that ships with &os; is called
125         <application>&xfree86;</application>, and is available for free, under a
126         license very similar to the &os; license.  Commercial X servers for
127         FreeBSD are also available, and ought to work with &os; .
128         (Unconfirmed as of this writing.)</para>
129     </sect2>
130
131     <sect2>
132       <title>The Window Manager</title>
133
134       <para>The X design philosophy is much like the &unix; design philosophy,
135         <quote>tools, not policy</quote>.  This means that X does not try to
136         dictate how a task is to be accomplished.  Instead, tools are provided
137         to the user, and it is the user's responsibility to decide how to use
138         those tools.</para>
139
140       <para>This philosophy extends to X not dictating what windows should
141         look like on screen, how to move them around with the mouse, what
142         keystrokes should be used to move between windows (i.e.,
143         <keycombo action="simul">
144           <keycap>Alt</keycap>
145           <keycap>Tab</keycap>
146         </keycombo>, in the case of &microsoft.windows;), what the title bars
147         on each window should look like, whether or not they have close
148         buttons on them, and so on.</para>
149
150       <para>Instead, X delegates this responsibility to an application called
151         a <quote>Window Manager</quote>.  There are dozens of window
152         managers available for X: <application>AfterStep</application>,
153         <application>Blackbox</application>, <application>ctwm</application>,
154         <application>Enlightenment</application>,
155         <application>fvwm</application>, <application>Sawfish</application>,
156         <application>twm</application>,
157         <application>Window Maker</application>, and more.  Each of these
158         window managers provides a different look and feel; some of them
159         support <quote>virtual desktops</quote>; some of them allow customized
160         keystrokes to manage the desktop; some have a <quote>Start</quote>
161         button or similar device; some are <quote>themeable</quote>, allowing
162         a complete change of look-and-feel by applying a new theme.  These
163         window managers, and many more, are available in the
164         <filename>x11-wm</filename> category of the Ports Collection.</para>
165
166       <para>In addition, the <application>KDE</application> and
167         <application>GNOME</application> desktop environments both have their
168         own window managers which integrate with the desktop.</para>
169
170       <para>Each window manager also has a different configuration mechanism;
171         some expect configuration file written by hand, others feature
172         GUI tools for most of the configuration tasks; at least one
173         (<application>sawfish</application>) has a configuration file written
174         in a dialect of the Lisp language.</para>
175
176       <note>
177         <title>Focus Policy</title>
178
179         <para>Another feature the window manager is responsible for is the
180           mouse <quote>focus policy</quote>.  Every windowing system
181           needs some means of choosing a window to be actively receiving
182           keystrokes, and should visibly indicate which window is active as
183           well.</para>
184
185         <para>A familiar focus policy is called <quote>click-to-focus</quote>.
186           This is the model utilized by &microsoft.windows;, in which a window
187           becomes active upon receiving a mouse click.</para>
188
189         <para>X does not support any particular focus policy.  Instead, the
190           window manager controls which window has the focus at any one time.
191           Different window managers will support different focus methods.  All
192           of them support click to focus, and the majority of them support
193           several others.</para>
194
195         <para>The most popular focus policies are:</para>
196
197         <variablelist>
198           <varlistentry>
199             <term>focus-follows-mouse</term>
200
201             <listitem>
202               <para>The window that is under the mouse pointer is the
203                 window that has the focus.  This may not necessarily be
204                 the window that is on top of all the other windows.
205                 The focus is changed by pointing at another window, there
206                 is no need to click in it as well.</para>
207             </listitem>
208           </varlistentry>
209
210           <varlistentry>
211             <term>sloppy-focus</term>
212
213             <listitem>
214               <para>This policy is a small extension to focus-follows-mouse.
215                 With focus-follows-mouse, if the mouse is moved over the
216                 root window (or background) then no window has the focus,
217                 and keystrokes are simply lost.  With sloppy-focus, focus is
218                 only changed when the cursor enters a new window, and not
219                 when exiting the current window.</para>
220             </listitem>
221           </varlistentry>
222
223           <varlistentry>
224             <term>click-to-focus</term>
225
226             <listitem>
227               <para>The active window is selected by mouse click.  The
228                 window may then be <quote>raised</quote>, and appear in
229                 front of all other windows.  All keystrokes will now be
230                 directed to this window, even if the cursor is moved to
231                 another window.</para>
232             </listitem>
233           </varlistentry>
234         </variablelist>
235
236         <para>Many window managers support other policies, as well as
237           variations on these.  Be sure to consult the documentation for
238           the window manager itself.</para>
239       </note>
240     </sect2>
241
242     <sect2>
243       <title>Widgets</title>
244
245       <para>The X approach of providing tools and not policy extends to the
246         widgets seen on screen in each application.</para>
247
248       <para><quote>Widget</quote> is a term for all the items in the user
249         interface that can be clicked or manipulated in some way; buttons,
250         check boxes, radio buttons, icons, lists, and so on.  &microsoft.windows;
251         calls these <quote>controls</quote>.</para>
252
253       <para>&microsoft.windows; and Apple's &macos; both have a very rigid widget
254         policy.  Application developers are supposed to ensure that their
255         applications share a common look and feel.  With X, it was not
256         considered sensible to mandate a particular graphical style, or set
257         of widgets to adhere to.</para>
258
259       <para>As a result, do not expect X applications to have a common
260         look and feel.  There are several popular widget sets and
261         variations, including the original Athena widget set from MIT,
262         <application>&motif;</application> (on which the widget set in
263         &microsoft.windows; was modeled, all bevelled edges and three shades of
264         grey), <application>OpenLook</application>, and others.</para>
265
266       <para>Most newer X applications today will use a modern-looking widget
267         set, either Qt, used by <application>KDE</application>, or
268         <application>GTK</application>, used by the
269         <application>GNOME</application>
270         project.  In this respect, there is some convergence in
271         look-and-feel of the &unix; desktop, which certainly makes things
272         easier for the novice user.</para>
273     </sect2>
274   </sect1>
275
276   <sect1 id="x-install">
277     <title>Installing &xfree86;</title>
278
279     <para>Before installing <application>&xfree86;</application>, decide on which
280       version to run.  <application>&xfree86; 3.X</application> is a maintenance
281       branch of <application>&xfree86;</application> development.  It is very
282       stable, and it supports a huge number of graphics cards.  However, no new
283       development is being done on the software.  <application>&xfree86;
284       4.X</application> is a complete redesign of the system with many new
285       features such as better support for fonts and anti-aliasing.
286       Unfortunately this new architecture requires that the video drivers be
287       rewritten, and some of the older cards that were supported in 3.X are not
288       yet supported in 4.X.  As all new developments and support for new
289       graphics cards are done on that branch, <application>&xfree86;
290       4.X</application> is now the default version of the X Window System on
291       &os;.</para>
292
293     <para>Alternatively, either version of <application>&xfree86;</application>
294       can be installed directly from the FreeBSD binaries provided on the
295       <ulink url="http://www.XFree86.org/">&xfree86; web site</ulink>.  A binary
296       package to use with &man.pkg.add.1; tool is also available for
297       <application>&xfree86; 4.X</application>.  When the remote fetching
298       feature of &man.pkg.add.1; is used, the version number of the
299       package must be removed.  &man.pkg.add.1; will automatically fetch
300       the latest version of the application.  So to fetch and install the
301       package of <application>&xfree86; 4.X</application>, simply type:</para>
302
303     <screen>&prompt.root; <userinput>pkg_add -r XFree86</userinput></screen>
304
305     <para>You can also use the ports collection to install
306       <application>&xfree86; 4.X</application>, for that you simply need
307       to type the following commands:</para>
308
309     <screen>&prompt.root; <userinput>cd /usr/ports/x11/XFree86-4</userinput>
310 &prompt.root; <userinput>make install clean</userinput></screen>
311
312     <note><para>The examples above will install the complete
313       <application>&xfree86;</application> distribution including the
314       servers, clients, fonts etc.  Separate packages and ports for
315       different parts of <application>&xfree86; 4.X</application> are also
316       available.</para></note>
317
318     <para>The rest of this chapter will explain how to configure
319       <application>&xfree86;</application>, and how to set up a productive desktop
320       environment.</para>
321
322 <!-- Easiest way is from sysinstall for XFree86 4.X -->
323
324   </sect1>
325
326   <sect1 id="x-config">
327     <sect1info>
328       <authorgroup>
329         <author>
330           <firstname>Christopher</firstname>
331           <surname>Shumway</surname>
332           <contrib>Contributed by </contrib>
333           <!-- July 2001 -->
334         </author>
335       </authorgroup>
336     </sect1info>
337     <title>&xfree86; Configuration</title>
338
339
340     <indexterm><primary>XFree86 4.X</primary></indexterm>
341     <indexterm><primary>XFree86</primary></indexterm>
342
343     <sect2>
344       <title>Before Starting</title>
345
346       <para>Before configuration of <application>&xfree86; 4.X</application>,
347         the following information about the target system is needed:</para>
348
349       <itemizedlist>
350         <listitem><para>Monitor specifications</para></listitem>
351         <listitem><para>Video Adapter chipset</para></listitem>
352         <listitem><para>Video Adapter memory</para></listitem>
353       </itemizedlist>
354
355       <indexterm><primary>horizontal scan rate</primary></indexterm>
356       <indexterm><primary>vertical scan rate</primary></indexterm>
357
358       <para>The specifications for the monitor are used by
359         <application>&xfree86;</application> to determine the resolution and
360         refresh rate to run at.  These specifications can usually be
361         obtained from the documentation that came with the monitor or from
362         the manufacturer's website.  There are two ranges of numbers that
363         are needed, the horizontal scan rate and the vertical synchronization
364         rate.</para>
365
366       <para>The video adapter's chipset defines what driver module
367         <application>&xfree86;</application> uses to talk to the graphics
368         hardware.  With most chipsets, this can be automatically
369         determined, but it is still useful to know in case the automatic
370         detection does not work correctly.</para>
371
372       <para>Video memory on the graphic adapter determines the
373         resolution and color depth which the system can run at.  This is
374         important to know so the user knows the limitations of the
375         system.</para>
376
377     </sect2>
378
379     <sect2>
380       <title>Configuring &xfree86; 4.X</title>
381
382       <para>Configuration of <application>&xfree86; 4.X</application> is
383         a multi-step process.  The first step is to build an initial
384         configuration file with the <option>-configure</option> option to
385         <application>&xfree86;</application>.  As the super user, simply
386         run:</para>
387
388       <screen>&prompt.root; <userinput>XFree86 -configure</userinput></screen>
389
390       <para>This will generate a skeleton
391         <application>&xfree86;</application> configuration file in the
392         <filename>/root</filename> directory called
393         <filename>XF86Config.new</filename> (in fact the directory used
394         is the one covered by the environment variable <envar>$HOME</envar>,
395         and it will depend from the way you got the superuser rights).  The
396         <application>&xfree86;</application> program will attempt to probe
397         the graphics hardware on the system and will write a
398         configuration file to load the proper drivers for the detected
399         hardware on the target system.</para>
400
401       <para>The next step is to test the existing
402         configuration to verify that <application>&xfree86;</application>
403         can work with the graphics
404         hardware on the target system.  To perform this task, the user
405         needs to run:</para>
406
407       <screen>&prompt.root; <userinput>XFree86 -xf86config XF86Config.new</userinput></screen>
408
409       <para>If a black and grey grid and an X mouse cursor appear,
410         the configuration was successful.  To exit the test, just press
411         <keycombo action="simul">
412           <keycap>Ctrl</keycap>
413           <keycap>Alt</keycap>
414           <keycap>Backspace</keycap>
415         </keycombo> simultaneously.</para>
416
417         <note><para>If the mouse does not work, be sure the device
418           has been configured.  See &man.moused.8 for more information</para></note>
419
420       <indexterm><primary>XFree86 4 Tuning</primary></indexterm>
421
422       <para>Next, tune the <filename>XF86Config.new</filename>
423         configuration file to taste.  Open the file in a text editor such
424         as &man.emacs.1; or &man.ee.1;.  First, add the
425         frequencies for the target system's monitor.  These are usually
426         expressed as a horizontal and vertical synchronization rate.  These
427         values are added to the <filename>XF86Config.new</filename> file
428         under the <literal>"Monitor"</literal> section:</para>
429
430       <programlisting>Section "Monitor"
431         Identifier   "Monitor0"
432         VendorName   "Monitor Vendor"
433         ModelName    "Monitor Model"
434         HorizSync    30-107
435         VertRefresh  48-120
436 EndSection</programlisting>
437
438       <para>The <varname>HorizSync</varname> and
439         <varname>VertRefresh</varname> keywords may not exist in the
440         configuration file.  If they do not, they need to be added, with
441         the correct horizontal synchronization rate placed after the
442         <varname>HorizSync</varname> keyword and the vertical
443         synchronization rate after the <varname>VertRefresh</varname>
444         keyword.  In the example above the target monitor's rates were
445         entered.</para>
446
447       <para>X allows DPMS (Energy Star) features to be used with capable
448         monitors. The &man.xset.1; program controls the time-outs and can force
449         standby, suspend, or off modes.  If you wish to enable DPMS features
450         for your monitor, you must add the following line to the monitor
451         section:</para>
452
453       <programlisting>
454         Option       "DPMS"</programlisting>
455
456       <indexterm>
457         <primary><command>XF86Config</command></primary>
458       </indexterm>
459
460       <para>While the <filename>XF86Config.new</filename>
461         configuration file is still open in an editor, select
462         the default resolution and color depth desired.  This is
463         defined in the <literal>"Screen"</literal> section:</para>
464
465       <programlisting>Section "Screen"
466         Identifier "Screen0"
467         Device     "Card0"
468         Monitor    "Monitor0"
469         DefaultDepth 24
470         SubSection "Display"
471                 Depth     24
472                 Modes     "1024x768"
473         EndSubSection
474 EndSection</programlisting>
475
476       <para>The <varname>DefaultDepth</varname> keyword describes
477         the color depth to run at by default.  This can be overridden
478         with the <command>-bpp</command> command line switch to
479         &man.XFree86.1;.
480         The <varname>Modes</varname> keyword
481         describes the resolution to run at for the given color depth.
482         Note that only VESA standard modes are supported as defined by
483         the target system's graphics hardware.
484         In the example above, the default color depth is twenty-four
485         bits per pixel.  At this color depth, the accepted resolution is
486         one thousand twenty-four pixels by seven hundred and sixty-eight
487         pixels.</para>
488
489       <para>Finally, write the configuration file and test it using
490         the test mode given above.  If all is well, the configuration
491         file needs to be installed in a common location where
492         &man.XFree86.1;
493         can find it.
494         This is typically <filename>/etc/X11/XF86Config</filename> or
495         <filename>/usr/X11R6/etc/X11/XF86Config</filename>.</para>
496
497       <screen>&prompt.root; <userinput>cp XF86Config.new /etc/X11/XF86Config</userinput></screen>
498
499       <para>Once the configuration file has been placed in a common
500         location, configuration is complete.  In order to start
501         <application>&xfree86; 4.X</application> with &man.startx.1;,
502         install the <filename role="package">x11/wrapper</filename> port.
503         <application>&xfree86; 4.X</application> can also be started with
504         &man.xdm.1;.</para>
505
506       <note><para>There is also a graphical tool for configuration,
507         &man.xf86cfg.1;, that comes with the
508         <application>&xfree86; 4.X</application> distribution.  It
509         allows to interactively define your configuration by choosing
510         the appropriate drivers and settings.  This program can be used under console as well, just use the command <command>xf86cfg -textmode</command>.  For more details,
511         refer to the &man.xf86cfg.1; manual page.</para></note>
512
513     </sect2>
514
515     <sect2>
516       <title>Advanced Configuration Topics</title>
517
518       <sect3>
519         <title>Configuration with &intel; i810 Graphics Chipsets</title>
520
521         <indexterm><primary>Intel i810 graphic chipset</primary></indexterm>
522
523         <para>Configuration with &intel; i810 integrated chipsets
524           requires the <devicename>agpgart</devicename>
525           AGP programming interface for <application>&xfree86;</application>
526           to drive the card.  The &man.agp.4; driver is in the
527           <filename>GENERIC</filename> kernel since releases
528           4.8-RELEASE and 5.0-RELEASE.  On prior releases, you will
529           have to add the following line:</para>
530
531         <programlisting>device agp</programlisting>
532
533         <para>in your kernel configuration file and rebuild a new
534           kernel.  Instead, you may want to load
535           the <filename>agp.ko</filename> kernel module
536           automatically with the &man.loader.8; at boot time.
537           For that, simply add this line to
538           <filename>/boot/loader.conf</filename>:</para>
539
540         <programlisting>agp_load="YES"</programlisting>
541
542         <para>Next, a
543           device node needs to be created for the
544           programming interface.  To create the AGP device node, run
545           &man.MAKEDEV.8; in the <filename>/dev</filename>
546           directory:</para>
547
548         <screen>&prompt.root; <userinput>cd /dev</userinput>
549 &prompt.root; <userinput>sh MAKEDEV agpgart</userinput></screen>
550
551         <para>This will allow configuration of the hardware as any other
552           graphics board.  Note on systems without the &man.agp.4;
553           driver compiled in the kernel, trying to load the module
554           with &man.kldload.8; will not work.  This driver has to be
555           in the kernel at boot time through being compiled in or
556           using <filename>/boot/loader.conf</filename>.</para>
557
558         <para>If you are using <application>&xfree86; 4.1.0</application> (or
559           later) and messages about unresolved symbols like
560           <literal>fbPictureInit</literal> appear, try adding the
561           following line after <literal>Driver "i810"</literal> in the
562           <application>&xfree86;</application> configuration file:</para>
563         <programlisting>Option "NoDDC"</programlisting>
564       </sect3>
565     </sect2>
566   </sect1>
567
568   <sect1 id="x-fonts">
569     <sect1info>
570       <authorgroup>
571         <author>
572           <firstname>Murray</firstname>
573           <surname>Stokely</surname>
574           <contrib>Contributed by </contrib>
575         </author>
576       </authorgroup>
577     </sect1info>
578     <title>Using Fonts in &xfree86;</title>
579
580     <sect2 id="type1">
581     <title>Type1 Fonts</title>
582     <para>The default fonts that ship with
583     <application>&xfree86;</application> are less than ideal for typical
584     desktop publishing applications.  Large presentation fonts show up
585     jagged and unprofessional looking, and small fonts in
586     <application>&netscape;</application> are almost completely unintelligible.
587     However, there are several free, high quality Type1 (&postscript;) fonts
588     available which can be readily used
589     with <application>&xfree86;</application>, either version 3.X or
590     version 4.X.  For instance, the URW font collection
591     (<filename role="package">x11-fonts/urwfonts</filename>) includes
592     high quality versions of standard type1 fonts (<trademark class="registered">Times Roman</trademark>,
593     <trademark class="registered">Helvetica</trademark>, <trademark class="registered">Palatino</trademark> and others).  The Freefonts collection
594     (<filename role="package">x11-fonts/freefonts</filename>) includes
595     many more fonts, but most of them are intended for use in
596     graphics software such as the <application>Gimp</application>, and are not
597     complete enough to serve as screen fonts.  In addition,
598     <application>&xfree86;</application> can be configured to use
599     &truetype; fonts with a minimum of effort: see the
600     <link linkend="truetype">section on &truetype; fonts</link> later.</para>
601
602     <para>To install the above Type1 font collections from the ports
603         collection, run the following commands:</para>
604
605     <screen>&prompt.root; <userinput>cd /usr/ports/x11-fonts/urwfonts</userinput>
606 &prompt.root; <userinput>make install clean</userinput></screen>
607
608     <para>And likewise with the freefont or other collections.  To tell the X
609       server that these fonts exist, add an appropriate line to the
610       <filename>XF86Config</filename> file (in <filename>/etc/</filename> for
611       <application>&xfree86;</application> version 3, or in
612       <filename>/etc/X11/</filename> for version 4), which reads:</para>
613
614       <programlisting>FontPath "/usr/X11R6/lib/X11/fonts/URW/"</programlisting>
615
616       <para>Alternatively, at the command line in the X session
617         run:</para>
618
619       <screen>&prompt.user; <userinput>xset fp+ /usr/X11R6/lib/X11/fonts/URW</userinput>
620 &prompt.user; <userinput>xset fp rehash</userinput></screen>
621
622       <para>This will work but will be lost when the X session is closed,
623     unless it is added to the startup file (<filename>~/.xinitrc</filename>
624     for a normal <command>startx</command> session,
625     or <filename>~/.xsession</filename> when logging in through a
626     graphical login manager like <application>XDM</application>).
627     A third way is to use the new
628     <filename>XftConfig</filename> file: see the
629     section on <link linkend="antialias">anti-aliasing</link>.
630     </para>
631     </sect2>
632
633     <sect2 id="truetype">
634     <title>&truetype; Fonts</title>
635
636     <indexterm><primary>TrueType Fonts</primary></indexterm>
637     <indexterm><primary>fonts</primary>
638       <secondary>TrueType</secondary>
639     </indexterm>
640
641     <para><application>&xfree86; 4.X</application> has built in support
642     for rendering &truetype; fonts.  There are two different modules
643     that can enable this functionality.  The freetype module is used
644     in this example because it is more consistent with the other font
645     rendering back-ends.  To enable the freetype module just add the
646     following line to the <literal>"Module"</literal> section of the
647     <filename>/etc/X11/XF86Config</filename> file.</para>
648
649     <programlisting>Load  "freetype"</programlisting>
650
651     <para>For <application>&xfree86; 3.3.X</application>, a separate
652       &truetype; font server is needed.
653       <application>Xfstt</application> is commonly used for
654       this purpose.  To install <application>Xfstt</application>,
655       simply install the port
656       <filename role="package">x11-servers/Xfstt</filename>.</para>
657
658     <para>Now make a directory for the &truetype; fonts (for example,
659       <filename>/usr/X11R6/lib/X11/fonts/TrueType</filename>)
660       and copy all of the &truetype; fonts into this directory.  Keep in
661       mind that &truetype; fonts cannot be directly taken from a
662       &macintosh;; they must be in &unix;/DOS/&windows; format for use by
663       <application>&xfree86;</application>.  Once the files have been
664       copied into this directory, use
665       <application>ttmkfdir</application> to create a
666       <filename>fonts.dir</filename> file, so that the X font renderer
667       knows that these new files have been installed.
668       <command>ttmkfdir</command> is available from the FreeBSD
669       Ports Collection as
670       <filename role="package">x11-fonts/ttmkfdir</filename>.</para>
671
672     <screen>&prompt.root; <userinput>cd /usr/X11R6/lib/X11/fonts/TrueType</userinput>
673 &prompt.root; <userinput>ttmkfdir > fonts.dir</userinput></screen>
674
675     <para>Now add the &truetype; directory to the font
676       path.  This is just the same as described above for <link
677       linkend="type1">Type1</link> fonts, that is, use</para>
678
679     <screen>&prompt.user; <userinput>xset fp+ /usr/X11R6/lib/X11/fonts/TrueType</userinput>
680 &prompt.user; <userinput>xset fp rehash</userinput></screen>
681
682     <para>or add a <option>FontPath</option> line to the
683        <filename>XF86Config</filename> file.</para>
684
685       <para>That's it.  Now <application>&netscape;</application>,
686         <application>Gimp</application>,
687         <application>&staroffice;</application>, and all of the other X
688         applications should now recognize the installed &truetype;
689         fonts.  Extremely small fonts (as with text in a high resolution
690         display on a web page) and extremely large fonts (within
691         <application>&staroffice;</application>) will look much better
692         now.</para>
693     </sect2>
694
695     <sect2 id="antialias">
696     <sect2info>
697       <authorgroup>
698         <author>
699           <firstname>Joe Marcus</firstname>
700           <surname>Clarke</surname>
701           <contrib>Updated for &xfree86; 4.3 by </contrib>
702           <!-- May 2003 -->
703         </author>
704       </authorgroup>
705     </sect2info>
706     <title>Anti-Aliased Fonts</title>
707
708     <indexterm><primary>anti-aliased fonts</primary></indexterm>
709     <indexterm><primary>fonts</primary>
710       <secondary>anti-aliased</secondary></indexterm>
711
712     <para>Anti-aliasing has been available in
713       <application>&xfree86;</application> since 4.0.2.  However, font
714       configuration was cumbersome before the introduction of
715       <application>&xfree86;</application> 4.3.0.  Starting in version 4.3.0, 
716       all fonts in <filename>/usr/X11R6/lib/X11/fonts/</filename> and
717       <filename>~/.fonts/</filename> are automatically 
718       made available for anti-aliasing to Xft-aware applications.  Not
719       all applications are Xft-aware yet, but many have received Xft support.
720       Examples of Xft-aware applications include Qt 2.3 and higher (the 
721       toolkit for the <application>KDE</application> desktop), 
722       Gtk+ 2.0 and higher (the toolkit for the 
723       <application>GNOME</application> desktop), and 
724       <application>Mozilla</application> 1.2 and higher.
725     </para>
726
727     <para>In order to control which fonts are anti-aliased, or to
728       configure anti-aliasing properties, create (or edit, if it
729       already exists) the file
730       <filename>/usr/X11R6/etc/fonts/local.conf</filename>.  Several
731       advanced features of the Xft font system can be tuned using
732       this file; this section describes only some simple
733       possibilities.  For more details, please see
734       &man.fonts-conf.5;.</para>
735
736     <indexterm><primary>XML</primary></indexterm>
737
738     <para>This file must be in XML format.  Pay careful attention to
739       case, and make sure all tags are properly closed.  The file
740       begins with the usual XML header followed by a DOCTYPE
741       definition, and then the <literal>&lt;fontconfig&gt;</literal> tag:</para>
742
743     <programlisting>
744       &lt;?xml version="1.0"?&gt;
745       &lt;!DOCTYPE fontconfig SYSTEM "fonts.dtd"&gt;
746       &lt;fontconfig&gt;
747     </programlisting>
748
749     <para>As previously stated, all fonts in
750       <filename>/usr/X11R6/lib/X11/fonts/</filename> as well as
751       <filename>~/.fonts/</filename> are already made available to
752       Xft-aware applications.  If you wish to add another directory
753       outside of these two directory trees, add a line similar to the
754       following to
755       <filename>/usr/X11R6/etc/fonts/local.conf</filename>:</para>
756
757     <programlisting>&lt;dir&gt;/path/to/my/fonts&lt;/dir&gt;</programlisting>
758
759     <para>After adding new fonts, and especially new font directories,
760       you should run the following command to rebuild the font
761       caches:</para>
762
763     <screen>&prompt.root; <userinput>fc-cache -f</userinput></screen>
764
765     <para>Anti-aliasing makes borders slightly fuzzy, which makes very
766       small text more readable and removes <quote>staircases</quote> from
767       large text, but can cause eyestrain if applied to normal text.  To
768       exclude point sizes smaller than 14 point from anti-aliasing, include
769       these lines:</para>
770
771       <programlisting>        &lt;match target="font"&gt;
772             &lt;test name="size" compare="less"&gt;
773                 &lt;double&gt;14&lt;/double&gt;
774             &lt;/test&gt;
775             &lt;edit name="antialias" mode="assign"&gt;
776                 &lt;bool&gt;false&lt;/bool&gt;
777             &lt;/edit&gt;
778         &lt;/match&gt;</programlisting>
779
780     <indexterm><primary>fonts</primary>
781       <secondary>spacing</secondary></indexterm>
782
783     <para>Spacing for some monospaced fonts may also be inappropriate
784       with anti-aliasing.  This seems to be an issue with
785       <application>KDE</application>, in particular.  One possible fix for
786       this is to force the spacing for such fonts to be 100.  Add the
787       following lines:</para>
788
789      <programlisting>       &lt;match target="pattern" name="family"&gt;
790            &lt;test qual="any" name="family"&gt;
791                &lt;string&gt;fixed&lt;/string&gt;
792            &lt;/test&gt;
793            &lt;edit name="family" mode="assign"&gt;
794                &lt;string&gt;mono&lt;/string&gt;
795            &lt;/edit&gt;
796         &lt;/match&gt;
797         &lt;match target="pattern" name="family"&gt;
798             &lt;test qual="any" name="family"&gt;
799                 &lt;string&gt;console&lt;/string&gt;
800             &lt;/test&gt;
801             &lt;edit name="family" mode="assign"&gt;
802                 &lt;string&gt;mono&lt;/string&gt;
803             &lt;/edit&gt;
804         &lt;/match&gt;</programlisting>
805
806       <para>(this aliases the other common names for fixed fonts as
807         <literal>"mono"</literal>), and then add:</para>
808
809       <programlisting>         &lt;match target="pattern" name="family"&gt;
810              &lt;test qual="any" name="family"&gt;
811                  &lt;string&gt;mono&lt;/string&gt;
812              &lt;/test&gt;
813              &lt;edit name="spacing" mode="assign"&gt;
814                  &lt;int&gt;100&lt;/int&gt;
815              &lt;/edit&gt;
816          &lt;/match&gt;      </programlisting>
817
818       <para>Certain fonts, such as Helvetica, may have a problem when
819         anti-aliased.  Usually this manifests itself as a font that
820         seems cut in half vertically.  At worst, it may cause
821         applications such as <application>Mozilla</application> to
822         crash.  To avoid this, consider adding the following to
823         <filename>local.conf</filename>:</para>
824
825       <programlisting>         &lt;match target="pattern" name="family"&gt;
826              &lt;test qual="any" name="family"&gt;
827                  &lt;string&gt;Helvetica&lt;/string&gt;
828              &lt;/test&gt;
829              &lt;edit name="family" mode="assign"&gt;
830                  &lt;string&gt;sans-serif&lt;/string&gt;
831              &lt;/edit&gt;
832          &lt;/match&gt;        </programlisting>
833
834       <para>Once you have finished editing
835         <filename>local.conf</filename> make sure you end the file
836         with the <literal>&lt;/fontconfig&gt;</literal> tag.  Not doing this will cause
837         your changes to be ignored.</para>
838
839        <para>The default font set that comes with 
840          <application>&xfree86;</application> is not very
841          desirable when it comes to anti-aliasing.  A much better
842          set of default fonts can be found in the 
843          <filename role="package">x11-fonts/bitstream-vera</filename>
844          port.  This port will install a
845          <filename>/usr/X11R6/etc/fonts/local.conf</filename> file
846          if one does not exist already.  If the file does exist,
847          the port will create a <filename>/usr/X11R6/etc/fonts/local.conf-vera
848          </filename> file.  Merge the contents of this file into
849          <filename>/usr/X11R6/etc/fonts/local.conf</filename>, and the 
850          Bitstream fonts will automatically replace the default 
851          <application>&xfree86;</application> Serif, Sans Serif, and Monospaced 
852          fonts.</para>
853
854        <para>Finally, users can add their own settings via their personal 
855         <filename>.fonts.conf</filename> files.  To do this, each user should 
856         simply create a <filename>~/.fonts.conf</filename>.  This file must 
857         also be in XML format.</para>
858
859        <indexterm><primary>LCD screen</primary></indexterm>
860        <indexterm><primary>Fonts</primary>
861          <secondary>LCD screen</secondary></indexterm>
862
863        <para>One last point: with an LCD screen, sub-pixel sampling may be
864         desired.  This basically treats the (horizontally separated)
865         red, green and blue components separately to improve the horizontal
866         resolution; the results can be dramatic.  To enable this, add the
867         line somewhere in the <filename>local.conf</filename> file:</para>
868
869        <programlisting>
870          &lt;match target="font"&gt;
871              &lt;test qual="all" name="rgba"&gt;
872                  &lt;const&gt;unknown&lt;/const&gt;
873              &lt;/test&gt;
874              &lt;edit name="rgba" mode="assign"&gt;
875                  &lt;const&gt;rgb&lt;/const&gt;
876              &lt;/edit&gt;
877          &lt;/match&gt;
878        </programlisting>
879
880        <note><para>Depending on the sort of display,
881          <literal>rgb</literal> may need to be changed to <literal>bgr</literal>,
882          <literal>vrgb</literal> or <literal>vbgr</literal>: experiment and
883          see which works best.</para></note>
884
885        <indexterm><primary>Mozilla</primary></indexterm>
886        <indexterm><primary>web browsers</primary>
887          <secondary>Mozilla</secondary>
888          <see>Mozilla</see></indexterm>
889
890        <para>Anti-aliasing should be enabled the next time the X
891          server is started.  However, programs must know how to take
892          advantage of it.  At present, the Qt toolkit does,
893          so the entire <application>KDE</application> environment can
894          use anti-aliased fonts (see <xref
895          linkend="x11-wm-kde-antialias"> on
896          <application>KDE</application> for details).  Gtk+ and 
897          <application>GNOME</application> can also be made to use 
898          anti-aliasing via the <quote>Font</quote> capplet (see <xref
899          linkend="x11-wm-gnome-antialias"> for details).  By default,
900          <application>Mozilla</application> 1.2 and greater will 
901          automatically use anti-aliasing. To disable this, rebuild 
902          <application>Mozilla</application> with the
903          <makevar>-DWITHOUT_XFT</makevar> flag.</para>
904     </sect2>
905   </sect1>
906
907   <sect1 id="x-xdm">
908     <sect1info>
909       <authorgroup>
910         <author>
911           <firstname>Seth</firstname>
912           <surname>Kingsley</surname>
913           <contrib>Contributed by </contrib>
914         </author>
915       </authorgroup>
916     </sect1info>
917     <title>The X Display Manager</title>
918     <sect2>
919       <title>Overview</title>
920
921       <indexterm><primary>X Display Manager</primary></indexterm>
922       <para>The X Display Manager (<application>XDM</application>) is
923         an optional part of the X Window System that is used for login
924         session management.  This is useful for several types of
925         situations, including minimal <quote>X Terminals</quote>,
926         desktops, and large network display
927         servers.  Since the X Window System is network and protocol
928         independent, there are a wide variety of possible configurations
929         for running X clients and servers on different machines
930         connected by a network.  <application>XDM</application> provides
931         a graphical interface for choosing which display server to
932         connect to, and entering authorization information such as a
933         login and password combination.</para>
934
935       <para>Think of <application>XDM</application> as
936         providing the same functionality to the user as the
937         &man.getty.8; utility (see <xref linkend="term-config"> for
938           details).  That is, it performs system logins to the display
939           being connected to and then runs a session manager on behalf of
940           the user (usually an X window
941           manager).  <application>XDM</application> then waits for this
942           program to exit, signaling that the user is done and should be
943           logged out of the display.  At this point,
944           <application>XDM</application> can display the login and display
945           chooser screens for the next user to login.</para>
946     </sect2>
947
948     <sect2>
949       <title>Using XDM</title>
950
951       <para>The <application>XDM</application> daemon program is
952         located in <filename>/usr/X11R6/bin/xdm</filename>.  This program
953         can be run at any time as <username>root</username> and it will
954         start managing the X display on the local machine.  If
955         <application>XDM</application> is to be run every
956         time the machine boots up, a convenient way to do this is by
957         adding an entry to <filename>/etc/ttys</filename>.  For more
958         information about the format and usage of this file, see <xref
959         linkend="term-etcttys">.  There is a line in the default
960         <filename>/etc/ttys</filename> file for running the
961         <application>XDM</application> daemon on a virtual terminal:</para>
962
963       <screen>ttyv8   "/usr/X11R6/bin/xdm -nodaemon"  xterm   off secure</screen>
964
965       <para>By default this entry is disabled; in order to enable it
966         change field 5 from <literal>off</literal> to
967         <literal>on</literal> and restart &man.init.8; using the
968         directions in <xref linkend="term-hup">.  The first field, the
969         name of the terminal this program will manage, is
970         <literal>ttyv8</literal>.  This means that
971         <application>XDM</application> will start running on the 9th
972         virtual terminal.</para>
973     </sect2>
974
975     <sect2>
976       <title>Configuring XDM</title>
977
978       <para>The <application>XDM</application> configuration directory
979         is located in <filename>/usr/X11R6/lib/X11/xdm</filename>.  In
980         this directory there are several files used to change the
981         behavior and appearance of
982         <application>XDM</application>.  Typically these files will
983         be found:</para>
984
985         <informaltable frame="none">
986           <tgroup cols="2">
987             <thead>
988               <row>
989                 <entry>File</entry>
990                 <entry>Description</entry>
991               </row>
992             </thead>
993
994             <tbody>
995               <row>
996                 <entry><filename>Xaccess</filename></entry>
997                 <entry>Client authorization ruleset.</entry>
998               </row>
999
1000               <row>
1001                 <entry><filename>Xresources</filename></entry>
1002                 <entry>Default X resource values.</entry>
1003               </row>
1004
1005               <row>
1006                 <entry><filename>Xservers</filename></entry>
1007                 <entry>List of remote and local displays to manage.</entry>
1008               </row>
1009
1010               <row>
1011                 <entry><filename>Xsession</filename></entry>
1012                 <entry>Default session script for logins.</entry>
1013               </row>
1014
1015               <row>
1016                 <entry><filename>Xsetup_</filename>*</entry>
1017                 <entry>Script to launch applications before the login
1018                   interface.</entry>
1019               </row>
1020
1021               <row>
1022                 <entry><filename>xdm-config</filename></entry>
1023                 <entry>Global configuration for all displays running on
1024                   this machine.</entry>
1025               </row>
1026
1027               <row>
1028                 <entry><filename>xdm-errors</filename></entry>
1029                 <entry>Errors generated by the server program.</entry>
1030               </row>
1031
1032               <row>
1033                 <entry><filename>xdm-pid</filename></entry>
1034                 <entry>The process ID of the currently running XDM.</entry>
1035               </row>
1036             </tbody>
1037           </tgroup>
1038         </informaltable>
1039
1040       <para>Also in this directory are a few scripts and programs used
1041         to set up the desktop when <application>XDM</application> is
1042         running.  The purpose of each of these files will be briefly
1043         described.  The exact syntax and usage of all of these files is
1044         described in &man.xdm.1;.</para>
1045
1046       <para>The default configuration is a simple rectangular login
1047         window with the hostname of the machine displayed at the top in
1048         a large font and <quote>Login:</quote> and
1049         <quote>Password:</quote> prompts below.  This is a good starting
1050         point for changing the look and feel of
1051         <application>XDM</application> screens.</para>
1052
1053       <sect3>
1054         <title>Xaccess</title>
1055
1056         <para>The protocol for connecting to
1057           <application>XDM</application> controlled displays is called
1058           the X Display Manager Connection Protocol (XDMCP).  This file
1059           is a ruleset for controlling XDMCP connections from remote
1060           machines.  By default, it allows any client to connect, but
1061           that does not matter unless the <filename>xdm-config</filename>
1062           is changed to listen for remote connections.</para>
1063       </sect3>
1064
1065       <sect3>
1066         <title>Xresources</title>
1067         <para>This is an application-defaults file for the display
1068           chooser and the login screens.  This is where the appearance
1069           of the login program can be modified.  The format is identical
1070           to the app-defaults file described in the
1071           <application>&xfree86;</application> documentation.</para>
1072       </sect3>
1073
1074       <sect3>
1075         <title>Xservers</title>
1076         <para>This is a list of the remote displays the chooser should
1077           provide as choices.</para>
1078       </sect3>
1079
1080       <sect3>
1081         <title>Xsession</title>
1082         <para>This is the default session script for
1083           <application>XDM</application> to run after a user has logged
1084           in.  Normally each user will have a customized session script
1085           in <filename>~/.xsession</filename> that overrides this
1086           script.</para>
1087       </sect3>
1088
1089       <sect3>
1090         <title>Xsetup_*</title>
1091         <para>These will be run automatically before displaying the
1092           chooser or login interfaces.  There is a script for each
1093           display being used, named <filename>Xsetup_</filename> followed
1094           by the local display number (for instance
1095           <filename>Xsetup_0</filename>).  Typically these scripts will
1096           run one or two programs in the background such as
1097           <command>xconsole</command>.</para>
1098       </sect3>
1099
1100       <sect3>
1101         <title>xdm-config</title>
1102         <para>This contains settings in the form of app-defaults
1103           that are applicable to every display that this installation
1104           manages.</para>
1105       </sect3>
1106
1107       <sect3>
1108         <title>xdm-errors</title>
1109         <para>This contains the output of the X servers that
1110           <application>XDM</application> is trying to run.  If a display
1111           that <application>XDM</application> is trying to start hangs
1112           for some reason, this is a good place to look for error
1113           messages.  These messages are also written to the user's
1114           <filename>~/.xsession-errors</filename> file on a per-session
1115           basis.</para>
1116       </sect3>
1117     </sect2>
1118
1119     <sect2>
1120       <title>Running a Network Display Server</title>
1121
1122       <para>In order for other clients to connect to the display
1123         server, edit the access control rules, and enable the connection
1124         listener.  By default these are set to conservative values.
1125         To make <application>XDM</application> listen for connections,
1126         first comment out a line in the <filename>xdm-config</filename>
1127         file:</para>
1128
1129       <screen>! SECURITY: do not listen for XDMCP or Chooser requests
1130 ! Comment out this line if you want to manage X terminals with xdm
1131 DisplayManager.requestPort:     0</screen>
1132
1133       <para>and then restart <application>XDM</application>.  Remember that
1134         comments in app-defaults files begin with a <quote>!</quote>
1135         character, not the usual <quote>#</quote>.  More strict
1136         access controls may be desired.  Look at the example
1137         entries in <filename>Xaccess</filename>, and refer to the
1138         &man.xdm.1; manual page.</para>
1139     </sect2>
1140
1141      <sect2>
1142         <title>Replacements for XDM</title>
1143
1144         <para>Several replacements for the default
1145           <application>XDM</application> program exist.  One of them,
1146           <application>KDM</application> (bundled with
1147           <application>KDE</application>) is described later in this
1148           chapter.  <application>KDM</application> offers many visual
1149           improvements and cosmetic frills, as well as the
1150           functionality to allow users to choose their window manager
1151           of choice at login time.</para>
1152      </sect2>
1153   </sect1>
1154
1155   <sect1 id="x11-wm">
1156     <sect1info>
1157       <authorgroup>
1158         <author>
1159           <firstname>Valentino</firstname>
1160           <surname>Vaschetto</surname>
1161           <contrib>Contributed by </contrib>
1162         </author>
1163         <!-- June 2001 -->
1164       </authorgroup>
1165     </sect1info>
1166
1167     <title>Desktop Environments</title>
1168
1169     <para>This section describes the different desktop environments
1170       available for X on &os; .  A <quote>desktop environment</quote>
1171       can mean anything ranging from a simple window manager to a
1172       complete suite of desktop applications, such as
1173       <application>KDE</application> or <application>GNOME</application>.
1174     </para>
1175
1176     <sect2 id="x11-wm-gnome">
1177       <title>GNOME</title>
1178
1179       <sect3 id="x11-wm-gnome-about">
1180         <title>About GNOME</title>
1181
1182         <indexterm><primary>GNOME</primary></indexterm>
1183         <para><application>GNOME</application> is a user-friendly
1184           desktop environment that enables users to easily use and
1185           configure their computers.  <application>GNOME</application>
1186           includes a panel (for starting applications and displaying
1187           status), a desktop (where data and applications can be
1188           placed), a set of standard desktop tools and applications, and
1189           a set of conventions that make it easy for applications to
1190           cooperate and be consistent with each other.  Users of other
1191           operating systems or environments should feel right at home
1192           using the powerful graphics-driven environment that
1193           <application>GNOME</application> provides.  </para>
1194       </sect3>
1195
1196       <sect3 id="x11-wm-gnome-install">
1197         <title>Installing GNOME</title>
1198
1199         <para>The easiest way to install
1200           <application>GNOME</application> is with a package or 
1201           through the ports collection:</para>
1202
1203         <para>To install the <application>GNOME</application> package
1204           from the network, simply type:</para>
1205
1206         <screen>&prompt.root; <userinput>pkg_add -r gnome2</userinput></screen>
1207
1208         <para>To build <application>GNOME</application> from source, use
1209           the ports tree:</para>
1210
1211         <screen>&prompt.root; <userinput>cd /usr/ports/x11/gnome2</userinput>
1212 &prompt.root; <userinput>make install clean</userinput></screen>
1213
1214         <para>Once <application>GNOME</application> is installed,
1215           the X server must be told to start
1216           <application>GNOME</application> instead of a default window
1217           manager.  If a custom <filename>.xinitrc</filename> is already in
1218           place, simply replace the line that starts the current window
1219           manager with one that starts
1220           <application>/usr/X11R6/bin/gnome-session</application> instead.
1221           If nothing special has been done to configuration file,
1222           then it is enough to simply type:</para>
1223
1224         <screen>&prompt.user; <userinput>echo "/usr/X11R6/bin/gnome-session" &gt; ~/.xinitrc</userinput></screen>
1225
1226         <para>Next, type <command>startx</command>, and the
1227           <application>GNOME</application> desktop environment will be
1228           started.</para>
1229
1230         <note><para>If a display manager, like
1231           <application>XDM</application>, is being used, this will not work.
1232           Instead, create an executable <filename>.xsession</filename>
1233           file with the same command in it.  To do this, edit the file
1234           and replace the existing window manager command with
1235           <application>/usr/X11R6/bin/gnome-session</application>:
1236           </para></note>
1237
1238         <screen>&prompt.user; <userinput>echo "#!/bin/sh" > ~/.xsession</userinput>
1239 &prompt.user; <userinput>echo "/usr/X11R6/bin/gnome-session" >> ~/.xsession</userinput>
1240 &prompt.user; <userinput>chmod +x ~/.xsession</userinput></screen>
1241
1242         <para>Another option is to configure the display manager to
1243           allow choosing the window manager at login time; the section on
1244           <link linkend="x11-wm-kde-details">KDE details</link>
1245           explains how to do this for <application>kdm</application>, the
1246           display manager of <application>KDE</application>.</para>
1247       </sect3>
1248
1249       <sect3 id="x11-wm-gnome-antialias">
1250         <title>Anti-aliased Fonts with GNOME</title>
1251
1252         <indexterm><primary>GNOME</primary>
1253           <secondary>anti-aliased fonts</secondary></indexterm>
1254         <para>Starting with version 4.0.2, <application>&xfree86;</application>
1255           supports anti-aliasing via its <quote>RENDER</quote> extension.
1256           Gtk+ 2.0 and greater (the toolkit used by
1257           <application>GNOME</application>) can make use of this
1258           functionality.  Configuring anti-aliasing is described in
1259           <xref linkend="antialias">.  So, with up-to-date software,
1260           anti-aliasing is possible within the
1261           <application>GNOME</application> desktop.  Just go to
1262           <menuchoice>
1263             <guimenu>Applications</guimenu>
1264             <guisubmenu>Desktop Preferences</guisubmenu>
1265             <guimenuitem>Font</guimenuitem></menuchoice>, and select either
1266           <guibutton>Best shapes</guibutton>, 
1267           <guibutton>Best contrast</guibutton>, or
1268           <guibutton>Subpixel smoothing (LCDs)</guibutton>.  For a
1269           Gtk+ application that is not part of the 
1270           <application>GNOME</application> desktop, set the
1271           environment variable <varname>GDK_USE_XFT</varname> to
1272           <literal>1</literal> before launching the program.</para>
1273       </sect3>
1274     </sect2>
1275
1276     <sect2 id="x11-wm-kde">
1277       <title>KDE</title>
1278
1279       <indexterm><primary>KDE</primary></indexterm>
1280       <sect3 id="x11-wm-kde-about">
1281         <title>About KDE</title>
1282
1283         <para><application>KDE</application> is an easy to use
1284           contemporary desktop environment.  Some of the things that
1285           <application>KDE</application> brings to the user are:</para>
1286
1287         <itemizedlist>
1288           <listitem>
1289             <para>A beautiful contemporary desktop</para>
1290           </listitem>
1291
1292           <listitem>
1293             <para>A desktop exhibiting complete network transparency</para>
1294           </listitem>
1295
1296           <listitem>
1297             <para>An integrated help system allowing for convenient,
1298               consistent access to help on the use of the
1299               <application>KDE</application> desktop and its
1300               applications</para>
1301           </listitem>
1302
1303           <listitem>
1304             <para>Consistent look and feel of all
1305               <application>KDE</application> applications</para>
1306           </listitem>
1307
1308           <listitem>
1309             <para>Standardized menu and toolbars, keybindings, color-schemes,
1310               etc.</para>
1311           </listitem>
1312
1313           <listitem>
1314             <para>Internationalization: <application>KDE</application>
1315               is available in more than 40 languages</para>
1316           </listitem>
1317
1318           <listitem>
1319             <para>Centralized consisted dialog driven desktop
1320               configuration</para>
1321           </listitem>
1322
1323           <listitem>
1324             <para>A great number of useful
1325               <application>KDE</application> applications</para>
1326           </listitem>
1327         </itemizedlist>
1328
1329         <para><application>KDE</application> has an office application
1330           suite based on <application>KDE</application>'s
1331           <quote>KParts</quote> technology consisting
1332           of a spread-sheet, a presentation application, an organizer, a
1333           news client and more.  <application>KDE</application> also
1334           comes with a web browser called
1335           <application>Konqueror</application>, which represents
1336           a solid competitor to other existing web browsers on &unix;
1337           systems.  More information on <application>KDE</application>
1338           can be found on the <ulink url="http://www.kde.org/">KDE
1339           website</ulink>.  </para>
1340       </sect3>
1341
1342       <sect3 id="x11-wm-kde-install">
1343         <title>Installing KDE</title>
1344
1345         <para>Just as with <application>GNOME</application> or any
1346           other desktop environment, the easiest way to install
1347           <application>KDE</application> is from a package
1348           or from the ports collection:</para>
1349
1350         <para>To install the <application>KDE</application> package
1351           from the network, simply type:</para>
1352
1353         <screen>&prompt.root; <userinput>pkg_add -r kde</userinput></screen>
1354
1355         <para>&man.pkg.add.1; will automatically fetch the latest version
1356           of the application.</para>
1357
1358         <para>To build <application>KDE</application> from source,
1359           use the ports tree:</para>
1360
1361         <screen>&prompt.root; <userinput>cd /usr/ports/x11/kde3</userinput>
1362 &prompt.root; <userinput>make install clean</userinput></screen>
1363
1364         <para>After <application>KDE</application> has been installed,
1365           the X server must be told to launch this application
1366           instead of the default window manager.  This is accomplished
1367           by editing the <filename>.xinitrc</filename> file:</para>
1368
1369         <screen>&prompt.user; <userinput>echo "exec startkde" &gt; ~/.xinitrc</userinput></screen>
1370
1371         <para>Now, whenever the X Window System is invoked with
1372           <command>startx</command>,
1373           <application>KDE</application> will be the desktop.</para>
1374
1375         <para>If a display manager such as
1376           <application>xdm</application> is being used, the
1377           configuration is slightly different.  Edit the
1378           <filename>.xsession</filename> file instead.  Instructions
1379           for <application>kdm</application> are described later in
1380           this chapter.</para>
1381       </sect3>
1382     </sect2>
1383
1384     <sect2 id="x11-wm-kde-details">
1385         <title>More Details on KDE</title>
1386
1387         <para>Now that <application>KDE</application> is installed on
1388           the system, most things can be discovered through the
1389           help pages, or just by pointing and clicking at various menus.
1390           &windows; or &mac; users will feel quite at home.</para>
1391
1392         <para>The best reference for <application>KDE</application> is
1393           the on-line documentation.  <application>KDE</application>
1394           comes with its own web browser,
1395           <application>Konqueror</application>, dozens of useful
1396           applications, and extensive documentation.  The remainder of
1397           this section discusses the technical items that are
1398           difficult to learn by random exploration.</para>
1399
1400       <sect3 id="x11-wm-kde-kdm">
1401         <title>The KDE Display Manager</title>
1402
1403         <indexterm><primary>KDE</primary>
1404           <secondary>display manager</secondary></indexterm>
1405         <para>An administrator of a multi-user system may wish to have
1406           a graphical login screen to welcome users.
1407           <link linkend="x-xdm"><filename>xdm</filename></link> can be
1408           used, as described earlier.  However,
1409           <application>KDE</application> includes an
1410           alternative, <application>kdm</application>, which is designed
1411           to look more attractive and include more login-time options.
1412           In particular, users can easily choose (via a menu) which
1413           desktop environment (<application>KDE</application>,
1414           <application>GNOME</application>, or something else) to run
1415           after logging on.</para>
1416
1417         <para>To begin with, run the <application>KDE</application>
1418           control panel, <command>kcontrol</command>, as
1419           <username>root</username>.  It is generally considered
1420           unsafe to run the entire X environment as
1421           <username>root</username>.  Instead, run the window manager
1422           as a normal user, open a terminal window (such as
1423           <filename>xterm</filename> or <application>KDE</application>'s
1424           <filename>konsole</filename>), become <username>root</username>
1425           with <userinput>su</userinput> (the user must be in the
1426           <groupname>wheel</groupname>
1427           group in <filename>/etc/group</filename> for this), and then
1428           type <userinput>kcontrol</userinput>.</para>
1429
1430         <para>Click on the icon on the left marked
1431           <guibutton>System</guibutton>, then on <guibutton>Login
1432           manager</guibutton>.  On the right there are
1433           various configurable options, which the
1434           <application>KDE</application> manual will explain in greater
1435           detail.  Click on <guibutton>sessions</guibutton> on the right.
1436           Click <guibutton>New type</guibutton> to add various window
1437           managers and desktop environments.  These are just labels,
1438           so they can say <application>KDE</application> and
1439           <application>GNOME</application> rather than
1440           <application>startkde</application> or
1441           <application>gnome-session</application>.
1442           Include a label <literal>failsafe</literal>.</para>
1443
1444         <para>Play with the other menus as well, they are mainly
1445           cosmetic and self-explanatory.  When you are done, click on
1446           <guibutton>Apply</guibutton> at the bottom, and quit the
1447           control center.</para>
1448
1449         <para>To make sure <application>kdm</application> understands
1450           what the labels (<application>KDE</application>,
1451           <application>GNOME</application> etc) mean, edit the files used
1452           by <link linkend="x-xdm">xdm</link>.
1453           <note><para>In <application>KDE 2.2</application> this has
1454             changed: <application>kdm</application> now uses its own
1455             configuration files.  Please see the <application>KDE
1456             2.2</application> documentation for details.</para>
1457           </note>
1458           In a terminal window, as <username>root</username>,
1459           edit the file
1460           <filename>/usr/X11R6/lib/X11/xdm/Xsession</filename>.  There is
1461           a section in the middle like this:</para>
1462
1463         <screen>case $# in
1464 1)
1465         case $1 in
1466         failsafe)
1467                 exec xterm -geometry 80x24-0-0
1468                 ;;
1469         esac
1470 esac</screen>
1471
1472         <para>A few lines need to be added to this section.
1473           Assuming the labels from used were <quote>KDE</quote> and
1474           <quote>GNOME</quote>,
1475           use the following:</para>
1476
1477         <screen>case $# in
1478 1)
1479         case $1 in
1480         kde)
1481                 exec /usr/local/bin/startkde
1482                 ;;
1483         GNOME)
1484                 exec /usr/X11R6/bin/gnome-session
1485                 ;;
1486         failsafe)
1487                 exec xterm -geometry 80x24-0-0
1488                 ;;
1489         esac
1490 esac</screen>
1491
1492         <para>For the <application>KDE</application>
1493           login-time desktop background to be honored,
1494           the following line needs to be added to
1495           <filename>/usr/X11R6/lib/X11/xdm/Xsetup_0</filename>:</para>
1496
1497         <screen>/usr/local/bin/kdmdesktop</screen>
1498
1499         <para>Now, make sure <application>kdm</application> is listed in
1500           <filename>/etc/ttys</filename> to be started at the next bootup.
1501           To do this, simply follow the instructions from the previous
1502           section on <link linkend="x-xdm">xdm</link> and replace
1503           references to the <command>/usr/X11R6/bin/xdm</command>
1504           program with <command>/usr/local/bin/kdm</command>.</para>
1505       </sect3>
1506
1507       <sect3 id="x11-wm-kde-antialias">
1508         <title>Anti-aliased Fonts</title>
1509
1510         <indexterm><primary>KDE</primary>
1511           <secondary>anti-aliased fonts</secondary></indexterm>
1512         <para>Starting with version 4.0.2,
1513           <application>&xfree86;</application> supports anti-aliasing via
1514           its <quote>RENDER</quote> extension, and starting with version 2.3,
1515           Qt (the toolkit used by <application>KDE</application>) supports
1516           this extension.  Configuring this is described in <xref
1517           linkend="antialias"> on antialiasing X11 fonts.  So, with
1518           up-to-date software, anti-aliasing is possible on a
1519           <application>KDE</application> desktop.  Just go to the KDE
1520           menu, go to
1521           <menuchoice>
1522             <guimenu>Preferences</guimenu>
1523             <guisubmenu>Look and Feel</guisubmenu>
1524             <guimenuitem>Fonts</guimenuitem></menuchoice>, and click on the check box
1525           <guibutton>Use Anti-Aliasing for Fonts and Icons</guibutton>.
1526           For a Qt application which is not part of
1527           <application>KDE</application>, the environment variable
1528           <varname>QT_XFT</varname> needs to be set to <literal>true</literal>
1529           before starting the program.</para>
1530
1531        </sect3>
1532      </sect2>
1533
1534      <sect2 id="x11-wm-xfce">
1535          <title>XFce</title>
1536        <sect3 id="x11-wm-xfce-about">
1537          <title>About XFce</title>
1538
1539         <para><application>XFce</application> is a desktop environment
1540           based on the GTK
1541           toolkit used by <application>GNOME</application>, but is much
1542           more lightweight and meant for those who want a simple,
1543           efficient desktop which is nevertheless easy to use and
1544           configure.  Visually, it looks very much like
1545           <application>CDE</application>, found on commercial &unix;
1546           systems.  Some of <application>XFce</application>'s features
1547           are:</para>
1548
1549          <itemizedlist>
1550            <listitem>
1551              <para>A simple, easy-to-handle desktop</para>
1552            </listitem>
1553
1554            <listitem>
1555              <para>Fully configurable via mouse, with drag and
1556                drop, etc </para>
1557            </listitem>
1558
1559            <listitem>
1560              <para>Main panel similar to <application>CDE</application>, with
1561                menus, applets and applications launchers</para>
1562            </listitem>
1563
1564            <listitem>
1565              <para>Integrated window manager, file manager, sound manager,
1566                <application>GNOME</application> compliance module, and other
1567                things</para>
1568            </listitem>
1569
1570            <listitem>
1571              <para>Themeable (since it uses GTK)</para>
1572            </listitem>
1573
1574            <listitem>
1575              <para>Fast, light and efficient: ideal for older/slower machines
1576                or machines with memory limitations</para>
1577            </listitem>
1578          </itemizedlist>
1579
1580          <para>More information on <application>XFce</application>
1581           can be found on the <ulink url="http://www.xfce.org/">XFce
1582             website</ulink>.</para>
1583        </sect3>
1584
1585        <sect3 id="x11-wm-xfce-install">
1586          <title>Installing XFce</title>
1587
1588         <para>A binary package for <application>XFce</application>
1589           exists (at the time of writing).  To install, simply type:</para>
1590
1591         <screen>&prompt.root; <userinput>pkg_add -r xfce4</userinput></screen>
1592
1593         <para>Alternatively, to build from source, use the ports
1594           collection:</para>
1595
1596         <screen>&prompt.root; <userinput>cd /usr/ports/x11-wm/xfce4</userinput>
1597 &prompt.root; <userinput>make install clean</userinput></screen>
1598
1599         <para>Now, tell the X server to launch
1600          <application>XFce</application> the next time X is started.
1601          Simply type this:</para>
1602
1603         <screen>&prompt.user; <userinput>echo "/usr/X11R6/bin/startxfce4" &gt; ~/.xinitrc</userinput></screen>
1604
1605         <para>The next time X is started,
1606           <application>XFce</application> will be the desktop.
1607           As before, if a display manager like
1608           <filename>xdm</filename> is being used, create an
1609           <filename>.xsession</filename>, as described in the
1610           section on <link linkend="x11-wm-gnome">GNOME</link>, but
1611           with the <filename>/usr/X11R6/bin/startxfce4</filename>
1612           command; or, configure the display manager to allow
1613           choosing a desktop at login time, as explained in
1614           the section on <link linkend="x11-wm-kde-kdm">kdm</link>.</para>
1615       </sect3>
1616     </sect2>
1617   </sect1>
1618
1619 </chapter>
1620
1621 <!--
1622      Local Variables:
1623      mode: sgml
1624      sgml-declaration: "../chapter.decl"
1625      sgml-indent-data: t
1626      sgml-omittag: nil
1627      sgml-always-quote-attributes: t
1628      sgml-parent-document: ("../book.sgml" "part" "chapter")
1629      End:
1630 -->