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