Attachment 167191 Details for Bug 207347 – Fixing on screen

[patch] Fixing on screen

difflasterror.diff (text/plain), 159.32 KB, created by harrij15 on 2016-02-19 18:14:46 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: harrij15

Created: 2016-02-19 18:14:46 UTC

Size: 159.32 KB

patch

obsolete

>Index: chapter.xml
>===================================================================
>--- chapter.xml	(revision 48199)
>+++ chapter.xml	(working copy)
>@@ -1,2118 +1,2117 @@
>-<?xml version="1.0" encoding="iso-8859-1"?>
>-
>-<chapter xmlns="http://docbook.org/ns/docbook"
>-  xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
>-  xml:id="x11">
>-  
>-
>-  <title>The X Window System</title>
>-
>-  <sect1 xml:id="x11-synopsis">
>-    <title>Synopsis</title>
>-
>-    <para>An installation of &os; using
>-      <application>bsdinstall</application> does not automatically
>-      install a graphical user interface.  This chapter describes how
>-      to install and configure <application>&xorg;</application>,
>-      which provides the open source X Window System used to provide a
>-      graphical environment.  It then describes how to find and
>-      install a desktop environment or window manager.</para>
>-
>-    <note>
>-      <para>Users who prefer an installation method that automatically
>-	configures the <application>&xorg;</application> and offers a
>-	choice of window managers during installation should refer to
>-	the <link xlink:href="http://www.pcbsd.org/">pcbsd.org</link>
>-	website.</para>
>-    </note>
>-
>-    <para>For more information on the video hardware that
>-      <application>&xorg;</application> supports, refer to the <link
>-	xlink:href="http://www.x.org/">x.org</link> website.</para>
>-
>-    <para>After reading this chapter, you will know:</para>
>-
>-    <itemizedlist>
>-      <listitem>
>-	<para>The various components of the X Window System, and how
>-	  they interoperate.</para>
>-      </listitem>
>-
>-      <listitem>
>-	<para>How to install and configure
>-	  <application>&xorg;</application>.</para>
>-      </listitem>
>-
>-      <listitem>
>-	<para>How to install and configure several window managers
>-	  and desktop environments.</para>
>-      </listitem>
>-
>-      <listitem>
>-	<para>How to use &truetype; fonts in
>-	  <application>&xorg;</application>.</para>
>-      </listitem>
>-
>-      <listitem>
>-	<para>How to set up your system for graphical logins
>-	  (<application>XDM</application>).</para>
>-      </listitem>
>-    </itemizedlist>
>-
>-    <para>Before reading this chapter, you should:</para>
>-
>-    <itemizedlist>
>-      <listitem>
>-	<para>Know how to install additional third-party
>-	  software as described in <xref linkend="ports"/>.</para>
>-      </listitem>
>-    </itemizedlist>
>-  </sect1>
>-
>-  <sect1 xml:id="x-understanding">
>-    <title>Terminology</title>
>-
>-    <para>While it is not necessary to understand all of the details
>-      of the various components in the X Window System and how they
>-      interact, some basic knowledge of these components can be
>-      useful.</para>
>-
>-    <variablelist>
>-      <varlistentry>
>-	<term>X server</term>
>-
>-	<listitem>
>-	  <para>X was designed from the beginning to be
>-	    network-centric, and adopts a <quote>client-server</quote>
>-	    model.  In this model, the <quote>X server</quote> runs on
>-	    the computer that has the keyboard, monitor, and mouse
>-	    attached.  The server's responsibility includes tasks such
>-	    as managing the display, handling input from the keyboard
>-	    and mouse, and handling input or output from other devices
>-	    such as a tablet or a video projector.  This confuses some
>-	    people, because the X terminology is exactly backward to
>-	    what they expect.  They expect the <quote>X server</quote>
>-	    to be the big powerful machine down the hall, and the
>-	    <quote>X client</quote> to be the machine on their
>-	    desk.</para>
>-	</listitem>
>-      </varlistentry>
>-
>-      <varlistentry>
>-	<term>X client</term>
>-
>-	<listitem>
>-	  <para>Each X application, such as
>-	    <application>XTerm</application> or
>-	    <application>Firefox</application>, is a
>-	    <quote>client</quote>.  A client sends messages to the
>-	    server such as <quote>Please draw a window at these
>-	      coordinates</quote>, and the server sends back messages
>-	    such as <quote>The user just clicked on the OK
>-	      button</quote>.</para>
>-
>-	  <para>In a home or small office environment, the X server
>-	    and the X clients commonly run on the same computer.  It
>-	    is also possible to run the X server on a less powerful
>-	    computer and to run the X applications on a more powerful
>-	    system.  In this scenario, the communication between the X
>-	    client and server takes place over the network.</para>
>-	</listitem>
>-      </varlistentry>
>-
>-      <varlistentry>
>-	<term>window manager</term>
>-
>-	<listitem>
>-	  <para>X does not dictate what windows should look like on
>-	    screen, how to move them around with the mouse, which
>-	    keystrokes should be used to move between windows, what
>-	    the title bars on each window should look like, whether or
>-	    not they have close buttons on them, and so on.  Instead,
>-	    X delegates this responsibility to a separate window
>-	    manager application.  There are <link
>-	      xlink:href="http://xwinman.org/">dozens of window
>-	      managers</link> available.  Each window manager provides
>-	    a different look and feel: some support virtual desktops,
>-	    some allow customized keystrokes to manage the desktop,
>-	    some have a <quote>Start</quote> button, and some are
>-	    themeable, allowing a complete change of the desktop's
>-	    look-and-feel.  Window managers are available in the
>-	    <filename>x11-wm</filename> category of the Ports
>-	    Collection.</para>
>-
>-	  <para>Each window manager uses a different configuration
>-	    mechanism.  Some expect configuration file written by hand
>-	    while others provide graphical tools for most
>-	    configuration tasks.</para>
>-	</listitem>
>-      </varlistentry>
>-
>-      <varlistentry>
>-	<term>desktop environment</term>
>-
>-	<listitem>
>-	  <para><application>KDE</application> and
>-	    <application>GNOME</application> are considered to be
>-	    desktop environments as they include an entire suite of
>-	    applications for performing common desktop tasks.  These
>-	    may include office suites, web browsers, and games.</para>
>-	</listitem>
>-      </varlistentry>
>-
>-      <varlistentry>
>-	<term>focus policy</term>
>-
>-	<listitem>
>-	  <para>The window manager is responsible for the mouse focus
>-	    policy.  This policy provides some means for choosing
>-	    which window is actively receiving keystrokes and it
>-	    should also visibly indicate which window is currently
>-	    active.</para>
>-
>-	  <para>One focus policy is called
>-	    <quote>click-to-focus</quote>.  In this model, a window
>-	    becomes active upon receiving a mouse click.  In the
>-	    <quote>focus-follows-mouse</quote> policy, the window that
>-	    is under the mouse pointer has focus and the focus is
>-	    changed by pointing at another window.  If the mouse is
>-	    over the root window, then this window is focused.  In the
>-	    <quote>sloppy-focus</quote> model, if the mouse is moved
>-	    over the root window, the most recently used window still
>-	    has the focus.  With sloppy-focus, focus is only changed
>-	    when the cursor enters a new window, and not when exiting
>-	    the current window.  In the <quote>click-to-focus</quote>
>-	    policy, the active window is selected by mouse click.  The
>-	    window may then be raised and appear in front of all other
>-	    windows.  All keystrokes will now be directed to this
>-	    window, even if the cursor is moved to another
>-	    window.</para>
>-
>-	  <para>Different window managers support different focus
>-	    models.  All of them support click-to-focus, and the
>-	    majority of them also support other policies.  Consult the
>-	    documentation for the window manager to determine which
>-	    focus models are available.</para>
>-	</listitem>
>-      </varlistentry>
>-
>-      <varlistentry>
>-	<term>widgets</term>
>-
>-	<listitem>
>-	  <para>Widget is a term for all of the items in the user
>-	    interface that can be clicked or manipulated in some way.
>-	    This includes buttons, check boxes, radio buttons, icons,
>-	    and lists.  A widget toolkit is a set of widgets used to
>-	    create graphical applications.  There are several popular
>-	    widget toolkits, including Qt, used by
>-	    <application>KDE</application>, and GTK+, used by
>-	    <application>GNOME</application>.  As a result,
>-	    applications will have a different look and feel,
>-	    depending upon which widget toolkit was used to create the
>-	    application.</para>
>-	</listitem>
>-      </varlistentry>
>-    </variablelist>
>-  </sect1>
>-
>-  <sect1 xml:id="x-install">
>-    <title>Installing <application>&xorg;</application></title>
>-
>-    <para>On &os;, <application>&xorg;</application> can be installed
>-      as a package or port.</para>
>-
>-    <para>To build and install from the Ports Collection:</para>
>-
>-    <screen>&prompt.root; <userinput>cd /usr/ports/x11/xorg</userinput>
>-&prompt.root; <userinput>make install clean</userinput></screen>
>-
>-    <para>The binary package can be installed more quickly but with
>-      fewer options for customization:</para>
>-
>-    <screen>&prompt.root; <userinput>pkg install xorg</userinput></screen>
>-
>-    <para>Either of these installations results in the complete
>-      <application>&xorg;</application> system being installed.  This
>-      is the best option for most users.</para>
>-
>-    <para>A smaller version of the X system suitable for experienced
>-      users is available in <package>x11/xorg-minimal</package>.  Most
>-      of the documents, libraries, and applications will not be
>-      installed.  Some applications require these additional
>-      components to function.</para>
>-  </sect1>
>-
>-  <sect1 xml:id="x-config">
>-    <title><application>&xorg;</application> Configuration</title>
>-
>-    <info>
>-      <author>
>-	<personname>
>-	  <firstname>Warren</firstname>
>-	  <surname>Block</surname>
>-	</personname>
>-	<contrib>Originally contributed by</contrib>
>-      </author>
>-    </info>
>-
>-    <indexterm><primary>&xorg;</primary></indexterm>
>-    <indexterm><primary><application>&xorg;</application></primary></indexterm>
>-
>-    <sect2 xml:id="x-config-quick-start">
>-      <title>Quick Start</title>
>-
>-      <para><application>&xorg;</application> supports most common
>-	video cards, keyboards, and pointing devices.  These devices
>-	are automatically detected and do not require any manual
>-	configuration.</para>
>-
>-      <procedure>
>-	<step>
>-	  <para>If <application>&xorg;</application> has been used on
>-	    this computer before, move or remove any existing
>-	    configuration files:</para>
>-
>-	  <screen>&prompt.root; <userinput>mv /etc/X11/xorg.conf ~/xorg.conf.etc</userinput>
>-&prompt.root; <userinput>mv /usr/local/etc/X11/xorg.conf ~/xorg.conf.localetc</userinput></screen>
>-	</step>
>-
>-	<step>
>-	  <para>Add the user who will run
>-	    <application>&xorg;</application> to the
>-	    <literal>video</literal> or
>-	    <literal>wheel</literal> group to enable 3D acceleration
>-	    when available.  To add user
>-	    <replaceable>jru</replaceable> to whichever group is
>-	    available:</para>
>-
>-	  <screen>&prompt.root; <userinput>pw groupmod video -m <replaceable>jru</replaceable> || pw groupmod wheel -m <replaceable>jru</replaceable></userinput></screen>
>-	</step>
>-
>-	<step>
>-	  <para>The <acronym>TWM</acronym> window manager is included
>-	    by default.  It is started when
>-	    <application>&xorg;</application> starts:</para>
>-
>-	  <screen>&prompt.user; <userinput>startx</userinput></screen>
>-	</step>
>-
>-	<step>
>-	  <para>On some older versions of &os;, the system console
>-	    must be set to &man.vt.4; before switching back to the
>-	    text console will work properly.  See
>-	    <xref linkend="x-config-kms"/>.</para>
>-	</step>
>-      </procedure>
>-    </sect2>
>-
>-    <sect2 xml:id="x-config-user-group">
>-      <title>User Group for Accelerated Video</title>
>-
>-      <para>Access to <filename>/dev/dri</filename> is needed to allow
>-	3D acceleration on video cards.  It is usually simplest to add
>-	the user who will be running X to either the
>-	<literal>video</literal> or <literal>wheel</literal> group.
>-	Here, &man.pw.8; is used to add user
>-	<replaceable>slurms</replaceable> to the
>-	<literal>video</literal> group, or to the
>-	<literal>wheel</literal> group if there is no
>-	<literal>video</literal> group:</para>
>-
>-      <screen>&prompt.root; <userinput>pw groupmod video -m <replaceable>slurms</replaceable> || pw groupmod wheel -m <replaceable>slurms</replaceable></userinput></screen>
>-    </sect2>
>-
>-    <sect2 xml:id="x-config-kms">
>-      <title>Kernel Mode Setting (<acronym>KMS</acronym>)</title>
>-
>-      <para>When the computer switches from displaying the console to
>-	a higher screen resolution for X, it must set the video
>-	output <emphasis>mode</emphasis>.  Recent versions of
>-	<acronym>&xorg;</acronym> use a system inside the kernel to do
>-	these mode changes more efficiently.  Older versions of &os;
>-	use &man.sc.4;, which is not aware of the
>-	<acronym>KMS</acronym> system.  The end result is that after
>-	closing X, the system console is blank, even though it is
>-	still working.  The newer &man.vt.4; console avoids this
>-	problem.</para>
>-
>-      <para>Add this line to <filename>/boot/loader.conf</filename>
>-	to enable &man.vt.4;:</para>
>-
>-      <programlisting>kern.vty=vt</programlisting>
>-    </sect2>
>-
>-    <sect2 xml:id="x-config-files">
>-      <title>Configuration Files</title>
>-
>-      <sect3 xml:id="x-config-files-directory">
>-	<title>Directory</title>
>-
>-	<para><application>&xorg;</application> looks in several
>-	  directories for configuration files.
>-	  <filename>/usr/local/etc/X11/</filename> is the recommended
>-	  directory for these files on &os;.  Using this directory
>-	  helps keep application files separate from operating system
>-	  files.</para>
>-
>-	<para>Storing configuration files in the legacy
>-	  <filename>/etc/X11/</filename> still works.  However, this
>-	  mixes application files with the base &os; files and is not
>-	  recommended.</para>
>-      </sect3>
>-
>-      <sect3 xml:id="x-config-files-single-or-multi">
>-	<title>Single or Multiple Files</title>
>-
>-	<para>It is easier to use multiple files that each configure a
>-	  specific setting than the traditional single
>-	  <filename>xorg.conf</filename>.  These files are stored in
>-	  the <filename>xorg.conf.d/</filename> subdirectory of the
>-	  main configuration file directory.  The full path is
>-	  typically
>-	  <filename>/usr/local/etc/X11/xorg.conf.d/</filename>.</para>
>-
>-	<para>Examples of these files are shown later in this
>-	  section.</para>
>-
>-	<para>The traditional single <filename>xorg.conf</filename>
>-	  still works, but is neither as clear nor as flexible as
>-	  multiple files in the <filename>xorg.conf.d/</filename>
>-	  subdirectory.</para>
>-      </sect3>
>-    </sect2>
>-
>-    <sect2 xml:id="x-config-video-cards">
>-      <title>Video Cards</title>
>-
>-      <variablelist>
>-	<varlistentry xml:id="x-config-video-cards-intel">
>-	  <term>&intel;</term>
>-
>-	  <listitem>
>-	    <para>3D acceleration is supported on most &intel;
>-	      graphics up to Ivy Bridge (HD Graphics 2500, 4000, and
>-	      P4000), including Iron Lake (HD Graphics) and
>-	      Sandy Bridge (HD Graphics 2000).</para>
>-
>-	    <para>Driver name: <literal>intel</literal></para>
>-
>-	    <para>For reference, see <link
>-	        xlink:href="https://en.wikipedia.org/wiki/List_of_Intel_graphics_processing_units"/>.</para>
>-	  </listitem>
>-	</varlistentry>
>-
>-	<varlistentry xml:id="x-config-video-cards-radeon">
>-	  <term>&amd; Radeon</term>
>-
>-	  <listitem>
>-	    <para>2D and 3D acceleration is supported on Radeon
>-	      cards up to and including the HD6000 series.</para>
>-
>-	    <para>Driver name: <literal>radeon</literal></para>
>-
>-	    <para>For reference, see <link
>-	        xlink:href="https://en.wikipedia.org/wiki/List_of_AMD_graphics_processing_units"/>.</para>
>-	  </listitem>
>-	</varlistentry>
>-
>-	<varlistentry xml:id="x-config-video-cards-nvidia">
>-	  <term>NVIDIA</term>
>-
>-	  <listitem>
>-	    <para>Several NVIDIA drivers are available in the
>-	      <filename>x11</filename> category of the Ports
>-	      Collection.  Install the driver that matches the video
>-	      card.</para>
>-
>-	    <para>For reference, see <link
>-	      xlink:href="https://en.wikipedia.org/wiki/List_of_Nvidia_graphics_processing_units"/>.</para>
>-	  </listitem>
>-	</varlistentry>
>-
>-	<varlistentry xml:id="x-config-video-cards-hybrid">
>-	  <term>Hybrid Combination Graphics</term>
>-
>-	  <listitem>
>-	    <para>Some notebook computers add additional graphics
>-	      processing units to those built into the chipset or
>-	      processor.  <emphasis>Optimus</emphasis> combines
>-	      &intel; and NVIDIA hardware.
>-	      <emphasis>Switchable Graphics</emphasis> or
>-	      <emphasis>Hybrid Graphics</emphasis> are a combination
>-	      of an &intel; or &amd; processor and an &amd; Radeon
>-	      <acronym>GPU</acronym>.</para>
>-
>-	    <para>Implementations of these hybrid graphics systems
>-	      vary, and <application>&xorg;</application> on &os; is
>-	      not able to drive all versions of them.</para>
>-
>-	    <para>Some computers provide a <acronym>BIOS</acronym>
>-	      option to disable one of the graphics adapters or select
>-	      a <emphasis>discrete</emphasis> mode which can be used
>-	      with one of the standard video card drivers.  For
>-	      example, it is sometimes possible to disable the NVIDIA
>-	      <acronym>GPU</acronym> in an Optimus system.  The
>-	      &intel; video can then be used with an &intel;
>-	      driver.</para>
>-
>-	    <para><acronym>BIOS</acronym> settings depend on the model
>-	      of computer.  In some situations, both
>-	      <acronym>GPU</acronym>s can be left enabled, but
>-	      creating a configuration file that only uses the main
>-	      <acronym>GPU</acronym> in the <literal>Device</literal>
>-	      section is enough to make such a system
>-	      functional.</para>
>-	  </listitem>
>-	</varlistentry>
>-
>-	<varlistentry xml:id="x-config-video-cards-other">
>-	  <term>Other Video Cards</term>
>-
>-	  <listitem>
>-	    <para>Drivers for some less-common video cards can be
>-	      found in the <filename>x11-drivers</filename> directory
>-	      of the Ports Collection.</para>
>-
>-	    <para>Cards that are not supported by a specific driver
>-	      might still be usable with the
>-	      <package>x11-drivers/xf86-video-vesa</package> driver.
>-	      This driver is installed by <package>x11/xorg</package>.
>-	      It can also be installed manually as
>-	      <package>x11-drivers/xf86-video-vesa</package>.
>-	      <application>&xorg;</application> attempts to use this
>-	      driver when a specific driver is not found for the video
>-	      card.</para>
>-
>-	    <para><package>x11-drivers/xf86-video-scfb</package> is a
>-	      similar nonspecialized video driver that works on many
>-	      <acronym>UEFI</acronym> and &arm; computers.</para>
>-	  </listitem>
>-	</varlistentry>
>-
>-	<varlistentry xml:id="x-config-video-cards-file">
>-	  <term>Setting the Video Driver in a File</term>
>-
>-	  <listitem>
>-	    <para>To set the &intel; driver in a configuration
>-	      file:</para>
>-
>-	    <example xml:id="x-config-video-cards-file-intel">
>-	      <title>Select &intel; Video Driver in a File</title>
>-
>-	      <para><filename>/usr/local/etc/X11/xorg.conf.d/driver-intel.conf</filename></para>
>-
>-	      <programlisting>Section "Device"
>-	Identifier "Card0"
>-	Driver     "intel"
>-	# BusID    "PCI:1:0:0"
>-EndSection</programlisting>
>-
>-	      <para>If more than one video card is present, the
>-		<literal>BusID</literal> identifier can be uncommented
>-		and set to select the desired card.  A list of video
>-		card bus <acronym>ID</acronym>s can be displayed with
>-		<command>pciconf -lv | grep -B3
>-		  display</command>.</para>
>-	    </example>
>-
>-	    <para>To set the Radeon driver in a configuration
>-	      file:</para>
>-
>-	    <example xml:id="x-config-video-cards-file-radeon">
>-	      <title>Select Radeon Video Driver in a File</title>
>-
>-	      <para><filename>/usr/local/etc/X11/xorg.conf.d/driver-radeon.conf</filename></para>
>-
>-	      <programlisting>Section "Device"
>-	Identifier "Card0"
>-	Driver     "radeon"
>-EndSection</programlisting>
>-	    </example>
>-
>-	    <para>To set the <acronym>VESA</acronym> driver in a
>-	      configuration file:</para>
>-
>-	    <example xml:id="x-config-video-cards-file-vesa">
>-	      <title>Select <acronym>VESA</acronym> Video Driver in a
>-		File</title>
>-
>-	      <para><filename>/usr/local/etc/X11/xorg.conf.d/driver-vesa.conf</filename></para>
>-
>-	      <programlisting>Section "Device"
>-	Identifier "Card0"
>-	Driver     "vesa"
>-EndSection</programlisting>
>-	    </example>
>-	  </listitem>
>-	</varlistentry>
>-      </variablelist>
>-    </sect2>
>-
>-    <sect2 xml:id="x-config-monitors">
>-      <title>Monitors</title>
>-
>-      <para>Almost all monitors support the Extended Display
>-	Identification Data standard (<acronym>EDID</acronym>).
>-	<application>&xorg;</application> uses <acronym>EDID</acronym>
>-	to communicate with the monitor and detect the supported
>-	resolutions and refresh rates.  Then it selects the most
>-	appropriate combination of settings to use with that
>-	monitor.</para>
>-
>-      <para>Other resolutions supported by the monitor can be
>-	chosen by setting the desired resolution in configuration
>-	files, or after the X server has been started with
>-	&man.xrandr.1;.</para>
>-
>-      <variablelist>
>-	<varlistentry xml:id="x-config-monitors-xrandr">
>-	  <term>Using &man.xrandr.1;</term>
>-
>-	  <listitem>
>-	    <para>Run &man.xrandr.1; without any parameters to see a
>-	      list of video outputs and detected monitor modes:</para>
>-
>-	    <screen>&prompt.user; <userinput>xrandr</userinput>
>-Screen 0: minimum 320 x 200, current 3000 x 1920, maximum 8192 x 8192
>-DVI-0 connected primary 1920x1200+1080+0 (normal left inverted right x axis y axis) 495mm x 310mm
>-   1920x1200     59.95*+
>-   1600x1200     60.00
>-   1280x1024     85.02    75.02    60.02
>-   1280x960      60.00
>-   1152x864      75.00
>-   1024x768      85.00    75.08    70.07    60.00
>-   832x624       74.55
>-   800x600       75.00    60.32
>-   640x480       75.00    60.00
>-   720x400       70.08
>-DisplayPort-0 disconnected (normal left inverted right x axis y axis)
>-HDMI-0 disconnected (normal left inverted right x axis y axis)</screen>
>-
>-	    <para>This shows that the <literal>DVI-0</literal> output
>-	      is being used to display a screen resolution of
>-	      1920x1200 pixels at a refresh rate of about 60 Hz.
>-	      Monitors are not attached to the
>-	      <literal>DisplayPort-0</literal> and
>-	      <literal>HDMI-0</literal> connectors.</para>
>-
>-	    <para>Any of the other display modes can be selected with
>-	      &man.xrandr.1;.  For example, to switch to 1280x1024 at
>-	      60 Hz:</para>
>-
>-	    <screen>&prompt.user; <userinput>xrandr --mode 1280x1024 --rate 60</userinput></screen>
>-
>-	    <para>A common task is using the external video output on
>-	      a notebook computer for a video projector.</para>
>-
>-	    <para>Names and types of video connectors vary, so
>-	      &man.xrandr.1; is run without options to list the
>-	      outputs:</para>
>-
>-	    <screen>&prompt.user; <userinput>xrandr</userinput>
>-Screen 0: minimum 320 x 200, current 1366 x 768, maximum 8192 x 8192
>-LVDS1 connected 1366x768+0+0 (normal left inverted right x axis y axis) 344mm x 193mm
>-   1366x768      60.04*+
>-   1024x768      60.00
>-   800x600       60.32    56.25
>-   640x480       59.94
>-VGA1 connected (normal left inverted right x axis y axis)
>-   1280x1024     60.02 +  75.02
>-   1280x960      60.00
>-   1152x864      75.00
>-   1024x768      75.08    70.07    60.00
>-   832x624       74.55
>-   800x600       72.19    75.00    60.32    56.25
>-   640x480       75.00    72.81    66.67    60.00
>-   720x400       70.08
>-HDMI1 disconnected (normal left inverted right x axis y axis)
>-DP1 disconnected (normal left inverted right x axis y axis)</screen>
>-
>-	    <para>Four outputs were found: the built-in panel
>-	      <literal>LVDS1</literal>, and external
>-	      <literal>VGA1</literal>, <literal>HDMI1</literal>, and
>-	      <literal>DP1</literal> connectors.</para>
>-
>-	    <para>The projector has been connected to the
>-	      <literal>VGA1</literal> output.  &man.xrandr.1; is now
>-	      used to set that output to the native resolution of the
>-	      projector and add the additional space to the right side
>-	      of the desktop:</para>
>-
>-	    <screen>&prompt.user; <userinput>xrandr --output VGA1 --auto --right-of LVDS1</userinput></screen>
>-
>-	    <para><literal>--auto</literal> chooses the resolution and
>-	      refresh rate detected by <acronym>EDID</acronym>.  If
>-	      the resolution is not correctly detected, a fixed value
>-	      can be given with <literal>--mode</literal> instead of
>-	      the <literal>--auto</literal> statement.  For example,
>-	      most projectors can be used with a 1024x768 resolution,
>-	      which is set with
>-	      <literal>--mode 1024x768</literal>.</para>
>-
>-	    <para>&man.xrandr.1; is often run from
>-	      <filename>.xinitrc</filename> to set the appropriate
>-	      mode when X starts.</para>
>-	  </listitem>
>-	</varlistentry>
>-
>-	<varlistentry xml:id="x-config-monitors-files">
>-	  <term>Setting Monitor Resolution in a File</term>
>-
>-	  <listitem>
>-	    <para>To set a screen resolution of 1024x768 in a
>-	      configuration file:</para>
>-
>-	    <example>
>-	      <title>Set Screen Resolution in a File</title>
>-
>-	      <para><filename>/usr/local/etc/X11/xorg.conf.d/screen-resolution.conf</filename></para>
>-
>-	      <programlisting>Section "Screen"
>-	Identifier "Screen0"
>-	Device     "Card0"
>-	SubSection "Display"
>-	Modes      "1024x768"
>-	EndSubSection
>-EndSection</programlisting>
>-	    </example>
>-
>-	    <para>The few monitors that do not have
>-	      <acronym>EDID</acronym> can be configured by setting
>-	      <literal>HorizSync</literal> and
>-	      <literal>VertRefresh</literal> to the range of
>-	      frequencies supported by the monitor.</para>
>-
>-	    <example>
>-	      <title>Manually Setting Monitor Frequencies</title>
>-
>-	      <para><filename>/usr/local/etc/X11/xorg.conf.d/monitor0-freq.conf</filename></para>
>-
>-	      <programlisting>Section "Monitor"
>-	Identifier   "Monitor0"
>-	HorizSync    30-83   # kHz
>-	VertRefresh  50-76   # Hz
>-EndSection</programlisting>
>-	    </example>
>-	  </listitem>
>-	</varlistentry>
>-      </variablelist>
>-    </sect2>
>-
>-    <sect2 xml:id="x-config-input">
>-      <title>Input Devices</title>
>-
>-      <sect3 xml:id="x-config-input-keyboard">
>-	<title>Keyboards</title>
>-
>-	<variablelist>
>-	  <varlistentry xml:id="x-config-input-keyboard-layout">
>-	    <term>Keyboard Layout</term>
>-
>-	    <listitem>
>-	      <para>The standardized location of keys on a keyboard
>-		is called a <emphasis>layout</emphasis>.  Layouts and
>-		other adjustable parameters are listed in
>-		&man.xkeyboard-config.7;.</para>
>-
>-	      <para>A United States layout is the default.  To select
>-		an alternate layout, set the
>-		<literal>XkbLayout</literal> and
>-		<literal>XkbVariant</literal> options in an
>-		<literal>InputClass</literal>.  This will be applied
>-		to all input devices that match the class.</para>
>-
>-	      <para>This example selects a French keyboard layout with
>-		the <literal>oss</literal> variant.</para>
>-
>-	      <example>
>-		<title>Setting a Keyboard Layout</title>
>-
>-		<para><filename>/usr/local/etc/X11/xorg.conf.d/keyboard-fr-oss.conf</filename></para>
>-
>-		<programlisting>Section	"InputClass"
>-	Identifier	"KeyboardDefaults"
>-	Driver		"keyboard"
>-	MatchIsKeyboard	"on"
>-	Option		"XkbLayout" "fr"
>-	Option		"XkbVariant" "oss"
>-EndSection</programlisting>
>-	      </example>
>-
>-	      <example>
>-		<title>Setting Multiple Keyboard Layouts</title>
>-
>-		<para>Set United States, Spanish, and Ukrainian
>-		  keyboard layouts.  Cycle through these layouts by
>-		  pressing
>-		  <keycombo action="simul">
>-		    <keycap>Alt</keycap>
>-		    <keycap>Shift</keycap>
>-		  </keycombo>.  <package>x11/xxkb</package> or
>-		  <package>x11/sbxkb</package> can be used for
>-		  improved layout switching control and
>-		  current layout indicators.</para>
>-
>-		<para><filename>/usr/local/etc/X11/xorg.conf.d/kbd-layout-multi.conf</filename></para>
>-
>-		<programlisting>Section	"InputClass"
>-	Identifier	"All Keyboards"
>-	MatchIsKeyboard	"yes"
>-	Option		"XkbLayout" "us, es, ua"
>-EndSection</programlisting>
>-	      </example>
>-	    </listitem>
>-	  </varlistentry>
>-
>-	  <varlistentry xml:id="x-config-input-keyboard-zap">
>-	    <term>Closing <application>&xorg;</application> From the
>-	    Keyboard</term>
>-
>-	    <listitem>
>-	      <para>X can be closed with a combination of keys.
>-		By default, that key combination is not set because it
>-		conflicts with keyboard commands for some
>-		applications.  Enabling this option requires changes
>-		to the keyboard <literal>InputDevice</literal>
>-		section:</para>
>-
>-	      <example>
>-		<title>Enabling Keyboard Exit from X</title>
>-
>-		<para><filename>/usr/local/etc/X11/xorg.conf.d/keyboard-zap.conf</filename></para>
>-
>-		<programlisting>Section	"InputClass"
>-	Identifier	"KeyboardDefaults"
>-	Driver		"keyboard"
>-	MatchIsKeyboard	"on"
>-	Option		"XkbOptions" "terminate:ctrl_alt_bksp"
>-EndSection</programlisting>
>-	      </example>
>-	    </listitem>
>-	  </varlistentry>
>-	</variablelist>
>-      </sect3>
>-
>-      <sect3 xml:id="x11-input-mice">
>-	<title>Mice and Pointing Devices</title>
>-
>-	<para>Many mouse parameters can be adjusted with configuration
>-	  options.  See &man.mousedrv.4x; for a full list.</para>
>-
>-	<variablelist>
>-	  <varlistentry xml:id="x11-input-mice-buttons">
>-	    <term>Mouse Buttons</term>
>-
>-	    <listitem>
>-	      <para>The number of buttons on a mouse can be set in the
>-		mouse <literal>InputDevice</literal> section of
>-		<filename>xorg.conf</filename>.  To set the number of
>-		buttons to 7:</para>
>-
>-	      <example>
>-		<title>Setting the Number of Mouse Buttons</title>
>-
>-		<para><filename>/usr/local/etc/X11/xorg.conf.d/mouse0-buttons.conf</filename></para>
>-
>-		<programlisting>Section "InputDevice"
>-	Identifier  "Mouse0"
>-	Option      "Buttons" "7"
>-EndSection</programlisting>
>-	      </example>
>-	    </listitem>
>-	  </varlistentry>
>-	</variablelist>
>-      </sect3>
>-    </sect2>
>-
>-    <sect2 xml:id="x-config-manual-configuration">
>-      <title>Manual Configuration</title>
>-
>-      <para>In some cases, <application>&xorg;</application>
>-	autoconfiguration does not work with particular hardware, or a
>-	different configuration is desired.  For these cases, a custom
>-	configuration file can be created.</para>
>-
>-      <para>A configuration file can be generated by
>-	<application>&xorg;</application> based on the detected
>-	hardware.  This file is often a useful starting point for
>-	custom configurations.</para>
>-
>-      <para>Generating an <filename>xorg.conf</filename>:</para>
>-
>-      <screen>&prompt.root; <userinput>Xorg -configure</userinput></screen>
>-
>-      <para>The configuration file is saved to
>-	<filename>/root/xorg.conf.new</filename>.  Make any changes
>-	desired, then test that file with:</para>
>-
>-      <screen>&prompt.root; <userinput>Xorg -config /root/xorg.conf.new</userinput></screen>
>-
>-      <para>After the new configuration has been adjusted and tested,
>-	it can be split into smaller files in the normal location,
>-	<filename>/usr/local/etc/X11/xorg.conf.d/</filename>.</para>
>-    </sect2>
>-  </sect1>
>-
>-  <sect1 xml:id="x-fonts">
>-    
>-    <title>Using Fonts in <application>&xorg;</application></title>
>-
>-    <sect2 xml:id="type1">
>-      <title>Type1 Fonts</title>
>-
>-      <para>The default fonts that ship with
>-	<application>&xorg;</application> are less than ideal for
>-	typical desktop publishing applications.  Large presentation
>-	fonts show up jagged and unprofessional looking, and small
>-	fonts are almost completely unintelligible.  However, there
>-	are several free, high quality Type1 (&postscript;) fonts
>-	available which can be readily used with
>-	<application>&xorg;</application>.  For instance, the URW font
>-	collection (<package>x11-fonts/urwfonts</package>) includes
>-	high quality versions of standard type1 fonts (<trademark
>-	  class="registered">Times Roman</trademark>, <trademark
>-	  class="registered">Helvetica</trademark>, <trademark
>-	  class="registered">Palatino</trademark> and others).  The
>-	Freefonts collection (<package>x11-fonts/freefonts</package>)
>-	includes many more fonts, but most of them are intended for
>-	use in graphics software such as the
>-	<application>Gimp</application>, and are not complete enough
>-	to serve as screen fonts.  In addition,
>-	<application>&xorg;</application> can be configured to use
>-	&truetype; fonts with a minimum of effort.  For more details
>-	on this, see the &man.X.7; manual page or <xref
>-	  linkend="truetype"/>.</para>
>-
>-      <para>To install the above Type1 font collections from the Ports
>-	Collection, run the following commands:</para>
>-
>-      <screen>&prompt.root; <userinput>cd /usr/ports/x11-fonts/urwfonts</userinput>
>-&prompt.root; <userinput>make install clean</userinput></screen>
>-
>-      <para>And likewise with the freefont or other collections.  To
>-	have the X server detect these fonts, add an appropriate line
>-	to the X server configuration file
>-	(<filename>/etc/X11/xorg.conf</filename>), which reads:</para>
>-
>-      <programlisting>FontPath "/usr/local/share/fonts/urwfonts/"</programlisting>
>-
>-      <para>Alternatively, at the command line in the X session
>-	run:</para>
>-
>-      <screen>&prompt.user; <userinput>xset fp+ /usr/local/share/fonts/urwfonts</userinput>
>-&prompt.user; <userinput>xset fp rehash</userinput></screen>
>-
>-      <para>This will work but will be lost when the X session is
>-	closed, unless it is added to the startup file
>-	(<filename>~/.xinitrc</filename> for a normal
>-	<command>startx</command> session, or
>-	<filename>~/.xsession</filename> when logging in through a
>-	graphical login manager like <application>XDM</application>).
>-	A third way is to use the new
>-	<filename>/usr/local/etc/fonts/local.conf</filename> as
>-	demonstrated in <xref linkend="antialias"/>.</para>
>-    </sect2>
>-
>-    <sect2 xml:id="truetype">
>-      <title>&truetype; Fonts</title>
>-
>-      <indexterm>
>-	<primary>TrueType Fonts</primary>
>-      </indexterm>
>-      <indexterm>
>-	<primary>fonts</primary>
>-	<secondary>TrueType</secondary>
>-      </indexterm>
>-
>-      <para><application>&xorg;</application> has built in support for
>-	rendering &truetype; fonts.  There are two different modules
>-	that can enable this functionality.  The freetype module is
>-	used in this example because it is more consistent with the
>-	other font rendering back-ends.  To enable the freetype module
>-	just add the following line to the <literal>"Module"</literal>
>-	section of <filename>/etc/X11/xorg.conf</filename>.</para>
>-
>-      <programlisting>Load  "freetype"</programlisting>
>-
>-      <para>Now make a directory for the &truetype; fonts (for
>-	example,
>-	<filename>/usr/local/share/fonts/TrueType</filename>) and
>-	copy all of the &truetype; fonts into this directory.  Keep in
>-	mind that &truetype; fonts cannot be directly taken from an
>-	&apple; &mac;; they must be in &unix;/&ms-dos;/&windows;
>-	format for use by <application>&xorg;</application>.  Once the
>-	files have been copied into this directory, use
>-	<application>mkfontdir</application> to create a
>-	<filename>fonts.dir</filename>, so that the X font renderer
>-	knows that these new files have been installed.
>-	<command>mkfontdir</command> can be installed as a package:</para>
>-
>-      <screen>&prompt.root; <userinput>pkg install mkfontdir</userinput></screen>
>-
>-      <para>Then create an index of X font files in a directory:</para>
>-
>-      <screen>&prompt.root; <userinput>cd /usr/local/share/fonts/TrueType</userinput>
>-&prompt.root; <userinput>mkfontdir</userinput></screen>
>-
>-      <para>Now add the &truetype; directory to the font path.  This
>-	is just the same as described in <xref
>-	  linkend="type1"/>:</para>
>-
>-      <screen>&prompt.user; <userinput>xset fp+ /usr/local/share/fonts/TrueType</userinput>
>-&prompt.user; <userinput>xset fp rehash</userinput></screen>
>-
>-      <para>or add a <literal>FontPath</literal> line to
>-	<filename>xorg.conf</filename>.</para>
>-
>-      <para>Now <application>Gimp</application>,
>-	<application>OpenOffice</application>, and all of the other X
>-	applications should now recognize the installed &truetype;
>-	fonts.  Extremely small fonts (as with text in a high
>-	resolution display on a web page) and extremely large fonts
>-	(within <application>&staroffice;</application>) will look
>-	much better now.</para>
>-    </sect2>
>-
>-    <sect2 xml:id="antialias">
>-      
>-      <title>Anti-Aliased Fonts</title>
>-
>-      <indexterm>
>-	<primary>anti-aliased fonts</primary>
>-      </indexterm>
>-      <indexterm>
>-	<primary>fonts</primary>
>-	<secondary>anti-aliased</secondary>
>-      </indexterm>
>-
>-      <para>All fonts in <application>&xorg;</application> that are
>-	found in <filename>/usr/local/share/fonts/</filename> and
>-	<filename>~/.fonts/</filename> are automatically made
>-	available for anti-aliasing to Xft-aware applications.  Most
>-	recent applications are Xft-aware, including
>-	<application>KDE</application>,
>-	<application>GNOME</application>, and
>-	<application>Firefox</application>.</para>
>-
>-      <para>In order to control which fonts are anti-aliased, or to
>-	configure anti-aliasing properties, create (or edit, if it
>-	already exists) the file
>-	<filename>/usr/local/etc/fonts/local.conf</filename>.  Several
>-	advanced features of the Xft font system can be tuned using
>-	this file; this section describes only some simple
>-	possibilities.  For more details, please see
>-	&man.fonts-conf.5;.</para>
>-
>-      <indexterm><primary>XML</primary></indexterm>
>-
>-      <para>This file must be in XML format.  Pay careful attention to
>-	case, and make sure all tags are properly closed.  The file
>-	begins with the usual XML header followed by a DOCTYPE
>-	definition, and then the <literal>&lt;fontconfig&gt;</literal>
>-	tag:</para>
>-
>-      <programlisting>&lt;?xml version="1.0"?&gt;
>-      &lt;!DOCTYPE fontconfig SYSTEM "fonts.dtd"&gt;
>-      &lt;fontconfig&gt;</programlisting>
>-
>-      <para>As previously stated, all fonts in
>-	<filename>/usr/local/share/fonts/</filename> as well as
>-	<filename>~/.fonts/</filename> are already made available to
>-	Xft-aware applications.  If you wish to add another directory
>-	outside of these two directory trees, add a line similar to
>-	the following to
>-	<filename>/usr/local/etc/fonts/local.conf</filename>:</para>
>-
>-      <programlisting>&lt;dir&gt;/path/to/my/fonts&lt;/dir&gt;</programlisting>
>-
>-      <para>After adding new fonts, and especially new font
>-	directories, you should run the following command to rebuild
>-	the font caches:</para>
>-
>-      <screen>&prompt.root; <userinput>fc-cache -f</userinput></screen>
>-
>-      <para>Anti-aliasing makes borders slightly fuzzy, which makes
>-	very small text more readable and removes
>-	<quote>staircases</quote> from large text, but can cause
>-	eyestrain if applied to normal text.  To exclude font sizes
>-	smaller than 14 point from anti-aliasing, include these
>-	lines:</para>
>-
>-      <programlisting>        &lt;match target="font"&gt;
>-	    &lt;test name="size" compare="less"&gt;
>-		&lt;double&gt;14&lt;/double&gt;
>-	    &lt;/test&gt;
>-	    &lt;edit name="antialias" mode="assign"&gt;
>-		&lt;bool&gt;false&lt;/bool&gt;
>-	    &lt;/edit&gt;
>-	&lt;/match&gt;
>-	&lt;match target="font"&gt;
>-	    &lt;test name="pixelsize" compare="less" qual="any"&gt;
>-		&lt;double&gt;14&lt;/double&gt;
>-	    &lt;/test&gt;
>-	    &lt;edit mode="assign" name="antialias"&gt;
>-		&lt;bool&gt;false&lt;/bool&gt;
>-	    &lt;/edit&gt;
>-	&lt;/match&gt;</programlisting>
>-
>-      <indexterm>
>-	<primary>fonts</primary>
>-	<secondary>spacing</secondary>
>-      </indexterm>
>-
>-      <para>Spacing for some monospaced fonts may also be
>-	inappropriate with anti-aliasing.  This seems to be an issue
>-	with <application>KDE</application>, in particular.  One
>-	possible fix for this is to force the spacing for such fonts
>-	to be 100. Add the following lines:</para>
>-
>-      <programlisting>       &lt;match target="pattern" name="family"&gt;
>-	   &lt;test qual="any" name="family"&gt;
>-	       &lt;string&gt;fixed&lt;/string&gt;
>-	   &lt;/test&gt;
>-	   &lt;edit name="family" mode="assign"&gt;
>-	       &lt;string&gt;mono&lt;/string&gt;
>-	   &lt;/edit&gt;
>-	&lt;/match&gt;
>-	&lt;match target="pattern" name="family"&gt;
>-	    &lt;test qual="any" name="family"&gt;
>-		&lt;string&gt;console&lt;/string&gt;
>-	    &lt;/test&gt;
>-	    &lt;edit name="family" mode="assign"&gt;
>-		&lt;string&gt;mono&lt;/string&gt;
>-	    &lt;/edit&gt;
>-	&lt;/match&gt;</programlisting>
>-
>-      <para>(this aliases the other common names for fixed fonts as
>-	<literal>"mono"</literal>), and then add:</para>
>-
>-      <programlisting>         &lt;match target="pattern" name="family"&gt;
>-	     &lt;test qual="any" name="family"&gt;
>-		 &lt;string&gt;mono&lt;/string&gt;
>-	     &lt;/test&gt;
>-	     &lt;edit name="spacing" mode="assign"&gt;
>-		 &lt;int&gt;100&lt;/int&gt;
>-	     &lt;/edit&gt;
>-	 &lt;/match&gt;      </programlisting>
>-
>-      <para>Certain fonts, such as Helvetica, may have a problem when
>-	anti-aliased.  Usually this manifests itself as a font that
>-	seems cut in half vertically.  At worst, it may cause
>-	applications to crash.  To avoid this, consider adding the
>-	following to <filename>local.conf</filename>:</para>
>-
>-      <programlisting>         &lt;match target="pattern" name="family"&gt;
>-	     &lt;test qual="any" name="family"&gt;
>-		 &lt;string&gt;Helvetica&lt;/string&gt;
>-	     &lt;/test&gt;
>-	     &lt;edit name="family" mode="assign"&gt;
>-		 &lt;string&gt;sans-serif&lt;/string&gt;
>-	     &lt;/edit&gt;
>-	 &lt;/match&gt;        </programlisting>
>-
>-      <para>Once you have finished editing
>-	<filename>local.conf</filename> make sure you end the file
>-	with the <literal>&lt;/fontconfig&gt;</literal> tag.  Not
>-	doing this will cause your changes to be ignored.</para>
>-
>-      <para>Finally, users can add their own settings via their
>-	personal <filename>.fonts.conf</filename> files.  To do this,
>-	each user should simply create a
>-	<filename>~/.fonts.conf</filename>.  This file must also be in
>-	XML format.</para>
>-
>-      <indexterm><primary>LCD screen</primary></indexterm>
>-      <indexterm><primary>Fonts</primary>
>-	<secondary>LCD screen</secondary></indexterm>
>-
>-      <para>One last point: with an LCD screen, sub-pixel sampling may
>-	be desired.  This basically treats the (horizontally
>-	separated) red, green and blue components separately to
>-	improve the horizontal resolution; the results can be
>-	dramatic.  To enable this, add the line somewhere in
>-	<filename>local.conf</filename>:</para>
>-
>-      <programlisting>&lt;match target="font"&gt;
>-	     &lt;test qual="all" name="rgba"&gt;
>-		 &lt;const&gt;unknown&lt;/const&gt;
>-	     &lt;/test&gt;
>-	     &lt;edit name="rgba" mode="assign"&gt;
>-		 &lt;const&gt;rgb&lt;/const&gt;
>-	     &lt;/edit&gt;
>-	 &lt;/match&gt;</programlisting>
>-
>-      <note>
>-	<para>Depending on the sort of display,
>-	  <literal>rgb</literal> may need to be changed to
>-	  <literal>bgr</literal>, <literal>vrgb</literal> or
>-	  <literal>vbgr</literal>: experiment and see which works
>-	  best.</para>
>-      </note>
>-    </sect2>
>-  </sect1>
>-
>-  <sect1 xml:id="x-xdm">
>-    <info>
>-      <title>The X Display Manager</title>
>-
>-      <authorgroup>
>-	<author>
>-	  <personname>
>-	    <firstname>Seth</firstname>
>-	    <surname>Kingsley</surname>
>-	  </personname>
>-	  <contrib>Contributed by </contrib>
>-	</author>
>-      </authorgroup>
>-    </info>
>-
>-    <indexterm><primary>X Display Manager</primary></indexterm>
>-    <para><application>&xorg;</application> provides an X Display
>-      Manager, <application>XDM</application>, which can be used for
>-      login session management.  <application>XDM</application>
>-      provides a graphical interface for choosing which display server
>-      to connect to and for entering authorization information such as
>-      a login and password combination.</para>
>-
>-    <para>This section demonstrates how to configure the X Display
>-      Manager on &os;.  Some desktop environments provide their own
>-      graphical login manager.  Refer to <xref
>-	linkend="x11-wm-gnome"/> for instructions on how to configure
>-      the GNOME Display Manager and <xref linkend="x11-wm-kde"/> for
>-      instructions on how to configure the KDE Display Manager.</para>
>-
>-    <sect2>
>-      <title>Configuring <application>XDM</application></title>
>-
>-      <para>To install <application>XDM</application>, use the
>-	<package>x11/xdm</package> package or port.  Once installed,
>-	<application>XDM</application> can be configured to run when
>-	the  machine boots up by editing this entry in
>-	<filename>/etc/ttys</filename>:</para>
>-
>-      <screen>ttyv8   "/usr/local/bin/xdm -nodaemon"  xterm   off secure</screen>
>-
>-      <para>Change the <literal>off</literal> to <literal>on</literal>
>-	and save the edit.  The <literal>ttyv8</literal> in this entry
>-	indicates that <application>XDM</application> will run on the
>-	ninth virtual terminal.</para>
>-
>-      <para>The <application>XDM</application> configuration directory
>-	is located in <filename>/usr/local/lib/X11/xdm</filename>.
>-	This directory contains several files used to change the
>-	behavior and appearance of <application>XDM</application>, as
>-	well as a few scripts and programs used to set up the desktop
>-	when <application>XDM</application> is running.  <xref
>-	  linkend="xdm-config-files"/> summarizes the function of each
>-	of these files.  The exact syntax and usage of these files is
>-	described in &man.xdm.1;.</para>
>-
>-      <table frame="none" pgwide="1" xml:id="xdm-config-files">
>-	<title>XDM Configuration Files</title>
>-
>-	<tgroup cols="2">
>-	  <thead>
>-	    <row>
>-	      <entry>File</entry>
>-	      <entry>Description</entry>
>-	    </row>
>-	  </thead>
>-
>-	  <tbody>
>-	    <row>
>-	      <entry><filename>Xaccess</filename></entry>
>-	      <entry>The protocol for connecting to
>-		<application>XDM</application> is called the X Display
>-		Manager Connection Protocol (<acronym>XDMCP</acronym>)
>-		This file is a client authorization ruleset for
>-		controlling <acronym>XDMCP</acronym> connections from
>-		remote machines.  By default, this file does not allow
>-		any remote clients to connect.</entry>
>-	    </row>
>-
>-	    <row>
>-	      <entry><filename>Xresources</filename></entry>
>-	      <entry>This file controls the look and feel of the
>-		<application>XDM</application> display chooser and
>-		login screens.  The default configuration is a simple
>-		rectangular login window with the hostname of the
>-		machine displayed at the top in a large font and
>-		<quote>Login:</quote> and <quote>Password:</quote>
>-		prompts below.  The format of this file is identical
>-		to the app-defaults file described in the
>-		<application>&xorg;</application>
>-		documentation.</entry>
>-	    </row>
>-
>-	    <row>
>-	      <entry><filename>Xservers</filename></entry>
>-	      <entry>The list of local and remote displays the chooser
>-		should provide as login choices.</entry>
>-	    </row>
>-
>-	    <row>
>-	      <entry><filename>Xsession</filename></entry>
>-	      <entry>Default session script for logins which is run by
>-		<application>XDM</application> after a user has logged
>-		in.  Normally each user will have a customized session
>-		script in <filename>~/.xsession</filename> that
>-		overrides this script</entry>
>-	    </row>
>-
>-	    <row>
>-	      <entry><filename>Xsetup_</filename>*</entry>
>-	      <entry>Script to automatically launch applications
>-		before displaying the chooser or login interfaces.
>-		There is a script for each display being used, named
>-		<filename>Xsetup_*</filename>, where
>-		<literal>*</literal> is the local display number.
>-		Typically these scripts run one or two programs in the
>-		background such as
>-		<command>xconsole</command>.</entry>
>-	    </row>
>-
>-	    <row>
>-	      <entry><filename>xdm-config</filename></entry>
>-	      <entry>Global configuration for all displays running
>-		on this machine.</entry>
>-	    </row>
>-
>-	    <row>
>-	      <entry><filename>xdm-errors</filename></entry>
>-	      <entry>Contains errors generated by the server program.
>-		If a display that <application>XDM</application> is
>-		trying to start hangs, look at this file for error
>-		messages.  These messages are also written to the
>-		user's <filename>~/.xsession-errors</filename> on a
>-		per-session basis.</entry>
>-	    </row>
>-
>-	    <row>
>-	      <entry><filename>xdm-pid</filename></entry>
>-	      <entry>The running process <acronym>ID</acronym> of
>-		<application>XDM</application>.</entry>
>-	    </row>
>-	  </tbody>
>-	</tgroup>
>-      </table>
>-    </sect2>
>-
>-    <sect2>
>-      <title>Configuring Remote Access</title>
>-
>-      <para>By default, only users on the same system can login using
>-	<application>XDM</application>.  To enable users on other
>-	systems to connect to the display server, edit the access
>-	control rules and enable the connection listener.</para>
>-
>-      <para>To configure <application>XDM</application> to listen for
>-	any remote connection, comment out the
>-	<literal>DisplayManager.requestPort</literal> line in
>-	<filename>/usr/local/lib/X11/xdm/xdm-config</filename> by
>-	putting a <literal>!</literal> in front of it:</para>
>-
>-      <screen>! SECURITY: do not listen for XDMCP or Chooser requests
>-! Comment out this line if you want to manage X terminals with xdm
>-DisplayManager.requestPort:     0</screen>
>-
>-      <para>Save the edits and restart <application>XDM</application>.
>-	To restrict remote access, look at the example entries in
>-	<filename>/usr/local/lib/X11/xdm/Xaccess</filename> and refer
>-	to &man.xdm.1; for further information.</para>
>-    </sect2>
>-  </sect1>
>-
>-  <sect1 xml:id="x11-wm">
>-    <info>
>-      <title>Desktop Environments</title>
>-
>-      <authorgroup>
>-	<author>
>-	  <personname>
>-	    <firstname>Valentino</firstname>
>-	    <surname>Vaschetto</surname>
>-	  </personname>
>-	  <contrib>Contributed by </contrib>
>-	   
>-	</author>
>-      </authorgroup>
>-    </info>
>-
>-    <para>This section describes how to install three popular desktop
>-      environments on a &os; system.  A desktop environment can range
>-      from a simple window manager to a complete suite of desktop
>-      applications.  Over a hundred desktop environments are available
>-      in the <filename>x11-wm</filename> category of the Ports
>-      Collection.</para>
>-
>-    <sect2 xml:id="x11-wm-gnome">
>-      <title>GNOME</title>
>-
>-      <indexterm><primary>GNOME</primary></indexterm>
>-      <para><application>GNOME</application> is a user-friendly
>-	desktop environment.  It includes a panel for starting
>-	applications and displaying status, a desktop, a set of tools
>-	and applications, and a set of conventions that make it easy
>-	for applications to cooperate and be consistent with each
>-	other.  More information regarding
>-	<application>GNOME</application> on &os; can be found at <link
>-	  xlink:href="http://www.FreeBSD.org/gnome">http://www.FreeBSD.org/gnome</link>.
>-	That web site contains additional documentation about
>-	installing, configuring, and managing
>-	<application>GNOME</application> on &os;.</para>
>-
>-      <para>This desktop environment can be installed from a
>-	package:</para>
>-
>-      <screen>&prompt.root; <userinput>pkg install gnome2</userinput></screen>
>-
>-      <para>To instead build <application>GNOME</application> from
>-	ports, use the following command.
>-	<application>GNOME</application> is a large application and
>-	will take some time to compile, even on a fast
>-	computer.</para>
>-
>-      <screen>&prompt.root; <userinput>cd /usr/ports/x11/gnome2</userinput>
>-&prompt.root; <userinput>make install clean</userinput></screen>
>-
>-      <para><application>GNOME</application>
>-	requires <filename>/proc</filename> to be mounted.  Add this
>-	line to <filename>/etc/fstab</filename> to mount this file
>-	system automatically during system startup:</para>
>-
>-      <programlisting>proc           /proc       procfs  rw  0   0</programlisting>
>-
>-      <para><application>GNOME</application> uses
>-	<application>D-Bus</application> and
>-	<application>HAL</application> for a
>-	message bus and hardware abstraction.  These applications are automatically
>-	installed as dependencies of <application>GNOME</application>.
>-	Enable them in <filename>/etc/rc.conf</filename> so
>-	they will be started when the system boots:</para>
>-
>-      <programlisting>dbus_enable="YES"
>-hald_enable="YES"</programlisting>
>-
>-      <para>After installation,
>-	configure <application>&xorg;</application> to start
>-	<application>GNOME</application>.  The easiest way to do this
>-	is to enable the GNOME Display Manager,
>-	<application>GDM</application>, which is installed as part of
>-	the <application>GNOME</application> package or port.  It can
>-	be enabled by adding this line to
>-	<filename>/etc/rc.conf</filename>:</para>
>-
>-      <programlisting>gdm_enable="YES"</programlisting>
>-
>-      <para>It is often desirable to also start all
>-	<application>GNOME</application> services.  To achieve this,
>-	add a second line to <filename>/etc/rc.conf</filename>:</para>
>-
>-      <programlisting>gnome_enable="YES"</programlisting>
>-
>-      <para><application>GDM</application> will start
>-	automatically when the system boots.</para>
>-
>-      <para>A second method for starting
>-	<application>GNOME</application> is to type
>-	<command>startx</command> from the command-line after
>-	configuring <filename>~/.xinitrc</filename>.  If this file
>-	already exists, replace the line that starts the current
>-	window manager with one that starts
>-	<filename>/usr/local/bin/gnome-session</filename>.  If this
>-	file does not exist, create it with this command:</para>
>-
>-      <screen>&prompt.user; <userinput>echo "exec /usr/local/bin/gnome-session" &gt; ~/.xinitrc</userinput></screen>
>-
>-      <para>A third method is to use <application>XDM</application> as
>-	the display manager.  In this case, create an executable
>-	<filename>~/.xsession</filename>:</para>
>-
>-      <screen>&prompt.user; <userinput>echo "#!/bin/sh" &gt; ~/.xsession</userinput>
>-&prompt.user; <userinput>echo "exec /usr/local/bin/gnome-session" &gt;&gt; ~/.xsession</userinput>
>-&prompt.user; <userinput>chmod +x ~/.xsession</userinput></screen>
>-    </sect2>
>-
>-    <sect2 xml:id="x11-wm-kde">
>-      <title>KDE</title>
>-
>-      <indexterm><primary>KDE</primary></indexterm>
>-
>-      <para><application>KDE</application> is another easy-to-use
>-	desktop environment.  This desktop provides a suite of
>-	applications with a consistent look and feel, a standardized
>-	menu and toolbars, keybindings, color-schemes,
>-	internationalization, and a centralized, dialog-driven desktop
>-	configuration.  More information on
>-	<application>KDE</application> can be found at <link
>-	  xlink:href="http://www.kde.org/">http://www.kde.org/</link>.
>-	For &os;-specific information, consult <link
>-	  xlink:href="http://freebsd.kde.org/">http://freebsd.kde.org</link>.</para>
>-
>-      <para>To install the <application>KDE</application> package,
>-	type:</para>
>-
>-      <screen>&prompt.root; <userinput>pkg install x11/kde4</userinput></screen>
>-
>-      <para>To instead build the <application>KDE</application> port,
>-	use the following command.  Installing the port will provide a
>-	menu for selecting which components to install.
>-	<application>KDE</application> is a large application and will
>-	take some time to compile, even on a fast computer.</para>
>-
>-      <screen>&prompt.root; <userinput>cd /usr/ports/x11/kde4</userinput>
>-&prompt.root; <userinput>make install clean</userinput></screen>
>-
>-      <indexterm>
>-	<primary>KDE</primary>
>-	<secondary>display manager</secondary>
>-      </indexterm>
>-
>-      <para><application>KDE</application> requires
>-	<filename>/proc</filename> to be mounted.  Add this line to
>-	<filename>/etc/fstab</filename> to mount this file system
>-	automatically during system startup:</para>
>-
>-      <programlisting>proc           /proc       procfs  rw  0   0</programlisting>
>-
>-      <para>The installation of <application>KDE</application>
>-	includes the KDE Display Manager,
>-	<application>KDM</application>.  To enable this display
>-	manager, add this line to
>-	<filename>/etc/rc.conf</filename>:</para>
>-
>-      <programlisting>kdm4_enable="YES"</programlisting>
>-
>-      <para>A second method for launching
>-	<application>KDE</application> is to type
>-	<command>startx</command> from the command line.  For this to
>-	work, the following line is needed in
>-	<filename>~/.xinitrc</filename>:</para>
>-
>-      <programlisting>exec /usr/local/bin/startkde</programlisting>
>-
>-      <para>A third method for starting <application>KDE</application>
>-	is through <application>XDM</application>.  To do so, create
>-	an executable <filename>~/.xsession</filename> as
>-	follows:</para>
>-
>-      <screen>&prompt.user; <userinput>echo "#!/bin/sh" &gt; ~/.xsession</userinput>
>-&prompt.user; <userinput>echo "exec /usr/local/bin/startkde" &gt;&gt; ~/.xsession</userinput>
>-&prompt.user; <userinput>chmod +x ~/.xsession</userinput></screen>
>-
>-      <para>Once <application>KDE</application> is started, refer to
>-	its built-in help system for more information on how to use
>-	its various menus and applications.</para>
>-    </sect2>
>-
>-    <sect2 xml:id="x11-wm-xfce">
>-      <title>Xfce</title>
>-
>-      <para><application>Xfce</application> is a desktop environment
>-	based on the GTK+ toolkit used by
>-	<application>GNOME</application>.  However, it is more
>-	lightweight and provides a simple, efficient, easy-to-use
>-	desktop.  It is fully configurable, has a main panel with
>-	menus, applets, and application launchers, provides a file
>-	manager and sound manager, and is themeable.  Since it is
>-	fast, light, and efficient, it is ideal for older or slower
>-	machines with memory limitations.  More information on
>-	<application>Xfce</application> can be found at <link
>-	  xlink:href="http://www.xfce.org/">http://www.xfce.org</link>.</para>
>-
>-      <para>To install the <application>Xfce</application>
>-	package:</para>
>-
>-      <screen>&prompt.root; <userinput>pkg install xfce</userinput></screen>
>-
>-      <para>Alternatively, to build the port:</para>
>-
>-      <screen>&prompt.root; <userinput>cd /usr/ports/x11-wm/xfce4</userinput>
>-&prompt.root; <userinput>make install clean</userinput></screen>
>-
>-      <para>Unlike <application>GNOME</application> or
>-	<application>KDE</application>,
>-	<application>Xfce</application> does not provide its own login
>-	manager.  In order to start <application>Xfce</application>
>-	from the command line by typing <command>startx</command>,
>-	first add its entry to <filename>~/.xinitrc</filename>:</para>
>-
>-      <screen>&prompt.user; <userinput>echo "exec /usr/local/bin/startxfce4 --with-ck-launch" &gt; ~/.xinitrc</userinput></screen>
>-
>-      <para>An alternate method is to use
>-	<application>XDM</application>.  To configure this method,
>-	create an executable <filename>~/.xsession</filename>:</para>
>-
>-      <screen>&prompt.user; <userinput>echo "#!/bin/sh" &gt; ~/.xsession</userinput>
>-&prompt.user; <userinput>echo "exec /usr/local/bin/startxfce4 --with-ck-launch" &gt;&gt; ~/.xsession</userinput>
>-&prompt.user; <userinput>chmod +x ~/.xsession</userinput></screen>
>-    </sect2>
>-  </sect1>
>-
>-  <sect1 xml:id="x-compiz-fusion">
>-    <title>Installing Compiz Fusion</title>
>-
>-    <para>One way to make using a desktop
>-      computer more pleasant is with nice 3D effects.</para>
>-
>-    <para>Installing the <application>Compiz&nbsp;Fusion</application>
>-      package is easy, but configuring it requires a few steps that
>-      are not described in the port's documentation.</para>
>-
>-    <sect2 xml:id="x-compiz-video-card">
>-      <title>Setting up the &os; nVidia Driver</title>
>-
>-      <para>Desktop effects can cause quite a load on the graphics
>-	card.  For an nVidia-based graphics card, the proprietary
>-	driver is required for good performance.  Users of other
>-	graphics cards can skip this section and continue with the
>-	<filename>xorg.conf</filename> configuration.</para>
>-
>-      <para>To determine which nVidia driver is needed see the <link
>-	  xlink:href="&url.books.faq;/x.html#idp59950544">FAQ question
>-	  on the subject</link>.</para>
>-
>-      <para>Having determined the correct driver to use for your card,
>-	installation is as simple as installing any other
>-	package.</para>
>-
>-      <para>For example, to install the latest driver:</para>
>-
>-      <screen>&prompt.root; <userinput>pkg install x11/nvidia-driver</userinput></screen>
>-
>-      <para>The driver will create a kernel module, which needs to be
>-	loaded at system startup.  Add the following line to
>-	<filename>/boot/loader.conf</filename>:</para>
>-
>-      <programlisting>nvidia_load="YES"</programlisting>
>-
>-      <note>
>-	<para>To immediately load the kernel module into the running
>-	  kernel by issuing a command like <command>kldload
>-	    nvidia</command>, however it has been noted that the some
>-	  versions of <application>&xorg;</application> will not
>-	  function properly if the driver is not loaded at boot time.
>-	  After editing <filename>/boot/loader.conf</filename>, a
>-	  reboot is recommended.</para>
>-      </note>
>-
>-      <para>With the kernel module loaded, you normally only need to
>-	change a single line in <filename>xorg.conf</filename>
>-	to enable the proprietary driver:</para>
>-
>-      <para>Find the following line in
>-	<filename>/etc/X11/xorg.conf</filename>:</para>
>-
>-      <programlisting>Driver      "nv"</programlisting>
>-
>-      <para>and change it to:</para>
>-
>-      <programlisting>Driver      "nvidia"</programlisting>
>-
>-      <para>Start the GUI as usual, and you should be greeted by the
>-	nVidia splash.  Everything should work as usual.</para>
>-    </sect2>
>-
>-    <sect2 xml:id="xorg-configuration">
>-      <title>Configuring xorg.conf for Desktop Effects</title>
>-
>-      <para>To enable <application>Compiz&nbsp;Fusion</application>,
>-	<filename>/etc/X11/xorg.conf</filename> needs to be
>-	modified:</para>
>-
>-      <para>Add the following section to enable composite
>-	effects:</para>
>-
>-      <programlisting>Section "Extensions"
>-    Option         "Composite" "Enable"
>-EndSection</programlisting>
>-
>-      <para>Locate the <quote>Screen</quote> section which should look
>-	similar to the one below:</para>
>-
>-      <programlisting>Section "Screen"
>-    Identifier     "Screen0"
>-    Device         "Card0"
>-    Monitor        "Monitor0"
>-    ...</programlisting>
>-
>-      <para>and add the following two lines (after
>-	<quote>Monitor</quote> will do):</para>
>-
>-      <programlisting>DefaultDepth    24
>-Option         "AddARGBGLXVisuals" "True"</programlisting>
>-
>-      <para>Locate the <quote>Subsection</quote> that refers to the
>-	screen resolution that you wish to use.  For example, if you
>-	wish to use 1280x1024, locate the section that follows.  If
>-	the desired resolution does not appear in any subsection, you
>-	may add the relevant entry by hand:</para>
>-
>-      <programlisting>SubSection     "Display"
>-    Viewport    0 0
>-    Modes      "1280x1024"
>-EndSubSection</programlisting>
>-
>-      <para>A color depth of 24&nbsp;bits is needed for desktop
>-	composition, change the above subsection to:</para>
>-
>-      <programlisting>SubSection     "Display"
>-    Viewport    0 0
>-    Depth       24
>-    Modes      "1280x1024"
>-EndSubSection</programlisting>
>-
>-      <para>Finally, confirm that the <quote>glx</quote> and
>-	<quote>extmod</quote> modules are loaded in the
>-	<quote>Module</quote> section:</para>
>-
>-      <programlisting>Section "Module"
>-    Load           "extmod"
>-    Load           "glx"
>-    ...</programlisting>
>-
>-      <para>The preceding can be done automatically with
>-	<package>x11/nvidia-xconfig</package> by running (as
>-	root):</para>
>-
>-      <screen>&prompt.root; <userinput>nvidia-xconfig --add-argb-glx-visuals</userinput>
>-&prompt.root; <userinput>nvidia-xconfig --composite</userinput>
>-&prompt.root; <userinput>nvidia-xconfig --depth=24</userinput></screen>
>-    </sect2>
>-
>-    <sect2 xml:id="compiz-fusion">
>-      <title>Installing and Configuring Compiz&nbsp;Fusion</title>
>-
>-      <para>Installing <application>Compiz&nbsp;Fusion</application>
>-	is as simple as any other package:</para>
>-
>-      <screen>&prompt.root; <userinput>pkg install x11-wm/compiz-fusion</userinput></screen>
>-
>-      <para>When the installation is finished, start your graphic
>-	desktop and at a terminal, enter the following commands (as a
>-	normal user):</para>
>-
>-      <screen>&prompt.user; <userinput>compiz --replace --sm-disable --ignore-desktop-hints ccp &amp;</userinput>
>-&prompt.user; <userinput>emerald --replace &amp;</userinput></screen>
>-
>-      <para>Your screen will flicker for a few seconds, as your window
>-	manager (e.g. <application>Metacity</application> if you are
>-	using <application>GNOME</application>) is replaced by
>-	<application>Compiz&nbsp;Fusion</application>.
>-	<application>Emerald</application> takes care of the window
>-	decorations (i.e. close, minimize, maximize buttons, title
>-	bars and so on).</para>
>-
>-      <para>You may convert this to a trivial script and have it run
>-	at startup automatically (e.g. by adding to
>-	<quote>Sessions</quote> in a <application>GNOME</application>
>-	desktop):</para>
>-
>-      <programlisting>#! /bin/sh
>-compiz --replace --sm-disable --ignore-desktop-hints ccp &amp;
>-emerald --replace &amp;</programlisting>
>-
>-      <para>Save this in your home directory as, for example,
>-	<filename>start-compiz</filename> and make it
>-	executable:</para>
>-
>-      <screen>&prompt.user; <userinput>chmod +x ~/start-compiz</userinput></screen>
>-
>-      <para>Then use the GUI to add it to <guimenuitem>Startup
>-	  Programs</guimenuitem> (located in
>-	<guimenuitem>System</guimenuitem>,
>-	<guimenuitem>Preferences</guimenuitem>,
>-	<guimenuitem>Sessions</guimenuitem> on a
>-	<application>GNOME</application> desktop).</para>
>-
>-      <para>To actually select all the desired effects and their
>-	settings, execute (again as a normal user) the
>-	<application>Compiz&nbsp;Config&nbsp;Settings&nbsp;Manager</application>:</para>
>-
>-      <screen>&prompt.user; <userinput>ccsm</userinput></screen>
>-
>-      <note>
>-	<para>In <application>GNOME</application>, this can also be
>-	  found in the <guimenuitem>System</guimenuitem>,
>-	  <guimenuitem>Preferences</guimenuitem> menu.</para>
>-      </note>
>-
>-      <para>If you have selected <quote>gconf support</quote> during
>-	the build, you will also be able to view these settings using
>-	<command>gconf-editor</command> under
>-	<literal>apps/compiz</literal>.</para>
>-    </sect2>
>-  </sect1>
>-
>-  <sect1 xml:id="x11-understanding">
>-
>-    <title>Troubleshooting</title>
>-
>-    <para>If the mouse does not work, you will need to first configure
>-      it before proceeding.
>-      In recent <application>Xorg</application>
>-      versions, the <literal>InputDevice</literal> sections in
>-      <filename>xorg.conf</filename> are ignored in favor of the
>-      autodetected devices.  To restore the old behavior, add the
>-      following line to the <literal>ServerLayout</literal> or
>-      <literal>ServerFlags</literal> section of this file:</para>
>-
>-      <programlisting>Option "AutoAddDevices" "false"</programlisting>
>-
>-      <para>Input devices may then be configured as in previous
>-	versions, along with any other options needed (e.g., keyboard
>-	layout switching).</para>
>-
>-      <note>
>-	<para>As previously explained the
>-	  <application>hald</application> daemon will, by default,
>-	  automatically detect your keyboard.  There are chances that
>-	  your keyboard layout or model will not be correct, desktop
>-	  environments like <application>GNOME</application>,
>-	  <application>KDE</application> or
>-	  <application>Xfce</application> provide tools to configure
>-	  the keyboard.  However, it is possible to set the keyboard
>-	  properties directly either with the help of the
>-	  &man.setxkbmap.1; utility or with a
>-	  <application>hald</application>'s configuration rule.</para>
>-
>-	<para>For example if, one wants to use a PC 102 keys keyboard
>-	  coming with a french layout, we have to create a keyboard
>-	  configuration file for <application>hald</application>
>-	  called <filename>x11-input.fdi</filename> and saved in the
>-	  <filename>/usr/local/etc/hal/fdi/policy</filename>
>-	  directory.  This file should contain the following
>-	  lines:</para>
>-
>-	<programlisting>&lt;?xml version="1.0" encoding="iso-8859-1"?&gt;
>-&lt;deviceinfo version="0.2"&gt;
>-  &lt;device&gt;
>-    &lt;match key="info.capabilities" contains="input.keyboard"&gt;
>-	  &lt;merge key="input.x11_options.XkbModel" type="string"&gt;pc102&lt;/merge&gt;
>-	  &lt;merge key="input.x11_options.XkbLayout" type="string"&gt;fr&lt;/merge&gt;
>-    &lt;/match&gt;
>-  &lt;/device&gt;
>-&lt;/deviceinfo&gt;</programlisting>
>-
>-	<para>If this file already exists, just copy and add to your
>-	  file the lines regarding the keyboard configuration.</para>
>-
>-	<para>You will have to reboot your machine to force
>-	  <application>hald</application> to read this file.</para>
>-
>-	<para>It is possible to do the same configuration from an X
>-	  terminal or a script with this command line:</para>
>-
>-	<screen>&prompt.user; <userinput>setxkbmap -model pc102 -layout fr</userinput></screen>
>-
>-	<para><filename>/usr/local/share/X11/xkb/rules/base.lst</filename>
>-	  lists the various keyboard, layouts and options
>-	  available.</para>
>-      </note>
>-
>-      <indexterm><primary><application>&xorg;</application>
>-	  tuning</primary></indexterm>
>-
>-      <para>The <filename>xorg.conf.new</filename> configuration file
>-	may now be tuned to taste.  Open the file in a text editor
>-	such as &man.emacs.1; or &man.ee.1;.  If the monitor is an
>-	older or unusual model that does not support autodetection of
>-	sync frequencies, those settings can be added to
>-	<filename>xorg.conf.new</filename> under the
>-	<literal>"Monitor"</literal> section:</para>
>-
>-      <programlisting>Section "Monitor"
>-	Identifier   "Monitor0"
>-	VendorName   "Monitor Vendor"
>-	ModelName    "Monitor Model"
>-	HorizSync    30-107
>-	VertRefresh  48-120
>-EndSection</programlisting>
>-
>-      <para>Most monitors support sync frequency autodetection, making
>-	manual entry of these values unnecessary.  For the few
>-	monitors that do not support autodetection, avoid potential
>-	damage by only entering values provided by the
>-	manufacturer.</para>
>-
>-      <para>X allows DPMS (Energy Star) features to be used with
>-	capable monitors.  The &man.xset.1; program controls the
>-	time-outs and can force standby, suspend, or off modes.  If
>-	you wish to enable DPMS features for your monitor, you must
>-	add the following line to the monitor section:</para>
>-
>-      <programlisting>Option       "DPMS"</programlisting>
>-
>-      <indexterm>
>-	<primary><filename>xorg.conf</filename></primary>
>-      </indexterm>
>-
>-      <para>While the <filename>xorg.conf.new</filename> configuration
>-	file is still open in an editor, select the default resolution
>-	and color depth desired.  This is defined in the
>-	<literal>"Screen"</literal> section:</para>
>-
>-      <programlisting>Section "Screen"
>-	Identifier "Screen0"
>-	Device     "Card0"
>-	Monitor    "Monitor0"
>-	DefaultDepth 24
>-	SubSection "Display"
>-		Viewport  0 0
>-		Depth     24
>-		Modes     "1024x768"
>-	EndSubSection
>-EndSection</programlisting>
>-
>-      <para>The <literal>DefaultDepth</literal> keyword describes the
>-	color depth to run at by default.  This can be overridden with
>-	the <option>-depth</option> command line switch to
>-	&man.Xorg.1;.  The <literal>Modes</literal> keyword describes
>-	the resolution to run at for the given color depth.  Note that
>-	only VESA standard modes are supported as defined by the
>-	target system's graphics hardware.  In the example above, the
>-	default color depth is twenty-four bits per pixel.  At this
>-	color depth, the accepted resolution is 1024 by 768
>-	pixels.</para>
>-
>-      <para>Finally, write the configuration file and test it using
>-	the test mode given above.</para>
>-
>-      <note>
>-	<para>One of the tools available to assist you during
>-	  troubleshooting process are the
>-	  <application>&xorg;</application> log files, which contain
>-	  information on each device that the
>-	  <application>&xorg;</application> server attaches to.
>-	  <application>&xorg;</application> log file names are in the
>-	  format of <filename>/var/log/Xorg.0.log</filename>.  The
>-	  exact name of the log can vary from
>-	  <filename>Xorg.0.log</filename> to
>-	  <filename>Xorg.8.log</filename> and so forth.</para>
>-      </note>
>-
>-      <para>If all is well, the configuration file needs to be
>-	installed in a common location where &man.Xorg.1; can find it.
>-	This is typically <filename>/etc/X11/xorg.conf</filename> or
>-	<filename>/usr/local/etc/X11/xorg.conf</filename>.</para>
>-
>-      <screen>&prompt.root; <userinput>cp xorg.conf.new /etc/X11/xorg.conf</userinput></screen>
>-
>-      <para>The <application>&xorg;</application> configuration
>-	process is now complete.  <application>&xorg;</application>
>-	may be now started with the &man.startx.1; utility.  The
>-	<application>&xorg;</application> server may also be started
>-	with the use of &man.xdm.1;.</para>
>-
>-      <sect2>
>-	<title>Configuration with &intel; <literal>i810</literal>
>-	  Graphics Chipsets</title>
>-
>-	<indexterm>
>-	  <primary>Intel i810 graphic chipset</primary>
>-	</indexterm>
>-
>-	<para>Configuration with &intel; i810 integrated chipsets
>-	  requires the <filename>agpgart</filename> AGP programming
>-	  interface for <application>&xorg;</application> to drive the
>-	  card.  See the &man.agp.4; driver manual page for more
>-	  information.</para>
>-
>-	<para>This will allow configuration of the hardware as any
>-	  other graphics board.  Note on systems without the
>-	  &man.agp.4; driver compiled in the kernel, trying to load
>-	  the module with &man.kldload.8; will not work.  This driver
>-	  has to be in the kernel at boot time through being compiled
>-	  in or using <filename>/boot/loader.conf</filename>.</para>
>-      </sect2>
>-
>-      <sect2>
>-	<title>Adding a Widescreen Flatpanel to the Mix</title>
>-
>-	<indexterm>
>-	  <primary>widescreen flatpanel configuration</primary>
>-	</indexterm>
>-
>-	<para>This section assumes a bit of advanced configuration
>-	  knowledge.  If attempts to use the standard configuration
>-	  tools above have not resulted in a working configuration,
>-	  there is information enough in the log files to be of use in
>-	  getting the setup working.  Use of a text editor will be
>-	  necessary.</para>
>-
>-	<para>Current widescreen (WSXGA, WSXGA+, WUXGA, WXGA, WXGA+,
>-	  et.al.) formats support 16:10 and 10:9 formats or aspect
>-	  ratios that can be problematic.  Examples of some common
>-	  screen resolutions for 16:10 aspect ratios are:</para>
>-
>-	<itemizedlist>
>-	  <listitem>
>-	    <para>2560x1600</para>
>-	  </listitem>
>-
>-	  <listitem>
>-	    <para>1920x1200</para>
>-	  </listitem>
>-
>-	  <listitem>
>-	    <para>1680x1050</para>
>-	  </listitem>
>-
>-	  <listitem>
>-	    <para>1440x900</para>
>-	  </listitem>
>-
>-	  <listitem>
>-	    <para>1280x800</para>
>-	  </listitem>
>-	</itemizedlist>
>-
>-	<para>At some point, it will be as easy as adding one of these
>-	  resolutions as a possible <literal>Mode</literal> in the
>-	  <literal>Section "Screen"</literal> as such:</para>
>-
>-	<programlisting>Section "Screen"
>-Identifier "Screen0"
>-Device     "Card0"
>-Monitor    "Monitor0"
>-DefaultDepth 24
>-SubSection "Display"
>-	Viewport  0 0
>-	Depth     24
>-	Modes     "1680x1050"
>-EndSubSection
>-EndSection</programlisting>
>-
>-	<para><application>&xorg;</application> is smart enough to
>-	  pull the resolution information from the widescreen via
>-	  I2C/DDC information so it knows what the monitor can handle
>-	  as far as frequencies and resolutions.</para>
>-
>-	<para>If those <literal>ModeLines</literal> do not exist in
>-	  the drivers, one might need to give
>-	  <application>&xorg;</application> a little hint.  Using
>-	  <filename>/var/log/Xorg.0.log</filename> one can extract
>-	  enough information to manually create a
>-	  <literal>ModeLine</literal> that will work.  Simply look for
>-	  information resembling this:</para>
>-
>-	<programlisting>(II) MGA(0): Supported additional Video Mode:
>-(II) MGA(0): clock: 146.2 MHz   Image Size:  433 x 271 mm
>-(II) MGA(0): h_active: 1680  h_sync: 1784  h_sync_end 1960 h_blank_end 2240 h_border: 0
>-(II) MGA(0): v_active: 1050  v_sync: 1053  v_sync_end 1059 v_blanking: 1089 v_border: 0
>-(II) MGA(0): Ranges: V min: 48  V max: 85 Hz, H min: 30  H max: 94 kHz, PixClock max 170 MHz</programlisting>
>-
>-	<para>This information is called EDID information.  Creating a
>-	  <literal>ModeLine</literal> from this is just a matter of
>-	  putting the numbers in the correct order:</para>
>-
>-	<programlisting>ModeLine &lt;name&gt; &lt;clock&gt; &lt;4 horiz. timings&gt; &lt;4 vert. timings&gt;</programlisting>
>-
>-	<para>So that the <literal>ModeLine</literal> in
>-	  <literal>Section "Monitor"</literal> for this example would
>-	  look like this:</para>
>-
>-	<programlisting>Section "Monitor"
>-Identifier      "Monitor1"
>-VendorName      "Bigname"
>-ModelName       "BestModel"
>-ModeLine        "1680x1050" 146.2 1680 1784 1960 2240 1050 1053 1059 1089
>-Option          "DPMS"
>-EndSection</programlisting>
>-
>-	<para>Now having completed these simple editing steps, X
>-	  should start on your new widescreen monitor.</para>
>-      </sect2>
>-
>-      <sect2 xml:id="compiz-troubleshooting">
>-	<title>Troubleshooting Compiz&nbsp;Fusion</title>
>-
>-	<qandaset>
>-	  <qandaentry>
>-	    <question xml:id="no-decorations">
>-	      <para>I have installed
>-		<application>Compiz&nbsp;Fusion</application>, and
>-		after running the commands you mention, my windows are
>-		left without title bars and buttons.  What is
>-		wrong?</para>
>-	    </question>
>-
>-	    <answer>
>-	      <para>You are probably missing a setting in
>-		<filename>/etc/X11/xorg.conf</filename>.  Review this
>-		file carefully and check especially the
>-		<literal>DefaultDepth</literal> and
>-		<literal>AddARGBGLXVisuals</literal>
>-		directives.</para>
>-	    </answer>
>-	  </qandaentry>
>-
>-	  <qandaentry>
>-	    <question xml:id="xorg-crash">
>-	      <para>When I run the command to start
>-		<application>Compiz&nbsp;Fusion</application>, the X
>-		server crashes and I am back at the console.  What is
>-		wrong?</para>
>-	    </question>
>-
>-	    <answer>
>-	      <para>If you check
>-		<filename>/var/log/Xorg.0.log</filename>, you
>-		will probably find error messages during the X
>-		startup.  The most common would be:</para>
>-
>-	      <screen>(EE) NVIDIA(0):     Failed to initialize the GLX module; please check in your X
>-(EE) NVIDIA(0):     log file that the GLX module has been loaded in your X
>-(EE) NVIDIA(0):     server, and that the module is the NVIDIA GLX module.  If
>-(EE) NVIDIA(0):     you continue to encounter problems, Please try
>-(EE) NVIDIA(0):     reinstalling the NVIDIA driver.</screen>
>-
>-	    <para>This is usually the case when you upgrade
>-	      <application>&xorg;</application>.  You will need to
>-	      reinstall the <package>x11/nvidia-driver</package>
>-	      package so glx is built again.</para>
>-	  </answer>
>-	</qandaentry>
>-      </qandaset>
>-    </sect2>
>-  </sect1>
>-</chapter>
>+<?xml version="1.0" encoding="iso-8859-1"?>
>+
>+<chapter xmlns="http://docbook.org/ns/docbook"
>+  xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
>+  xml:id="x11">
>+  
>+
>+  <title>The X Window System</title>
>+
>+  <sect1 xml:id="x11-synopsis">
>+    <title>Synopsis</title>
>+
>+    <para>An installation of &os; using
>+      <application>bsdinstall</application> does not automatically
>+      install a graphical user interface.  This chapter describes how
>+      to install and configure <application>&xorg;</application>,
>+      which provides the open source X Window System used to provide a
>+      graphical environment.  It then describes how to find and
>+      install a desktop environment or window manager.</para>
>+
>+    <note>
>+      <para>Users who prefer an installation method that automatically
>+	configures the <application>&xorg;</application> and offers a
>+	choice of window managers during installation should refer to
>+	the <link xlink:href="http://www.pcbsd.org/">pcbsd.org</link>
>+	website.</para>
>+    </note>
>+
>+    <para>For more information on the video hardware that
>+      <application>&xorg;</application> supports, refer to the <link
>+	xlink:href="http://www.x.org/">x.org</link> website.</para>
>+
>+    <para>After reading this chapter, you will know:</para>
>+
>+    <itemizedlist>
>+      <listitem>
>+	<para>The various components of the X Window System, and how
>+	  they interoperate.</para>
>+      </listitem>
>+
>+      <listitem>
>+	<para>How to install and configure
>+	  <application>&xorg;</application>.</para>
>+      </listitem>
>+
>+      <listitem>
>+	<para>How to install and configure several window managers
>+	  and desktop environments.</para>
>+      </listitem>
>+
>+      <listitem>
>+	<para>How to use &truetype; fonts in
>+	  <application>&xorg;</application>.</para>
>+      </listitem>
>+
>+      <listitem>
>+	<para>How to set up your system for graphical logins
>+	  (<application>XDM</application>).</para>
>+      </listitem>
>+    </itemizedlist>
>+
>+    <para>Before reading this chapter, you should:</para>
>+
>+    <itemizedlist>
>+      <listitem>
>+	<para>Know how to install additional third-party
>+	  software as described in <xref linkend="ports"/>.</para>
>+      </listitem>
>+    </itemizedlist>
>+  </sect1>
>+
>+  <sect1 xml:id="x-understanding">
>+    <title>Terminology</title>
>+
>+    <para>While it is not necessary to understand all of the details
>+      of the various components in the X Window System and how they
>+      interact, some basic knowledge of these components can be
>+      useful.</para>
>+
>+    <variablelist>
>+      <varlistentry>
>+	<term>X server</term>
>+
>+	<listitem>
>+	  <para>X was designed from the beginning to be
>+	    network-centric, and adopts a <quote>client-server</quote>
>+	    model.  In this model, the <quote>X server</quote> runs on
>+	    the computer that has the keyboard, monitor, and mouse
>+	    attached.  The server's responsibility includes tasks such
>+	    as managing the display, handling input from the keyboard
>+	    and mouse, and handling input or output from other devices
>+	    such as a tablet or a video projector.  This confuses some
>+	    people, because the X terminology is exactly backward to
>+	    what they expect.  They expect the <quote>X server</quote>
>+	    to be the big powerful machine down the hall, and the
>+	    <quote>X client</quote> to be the machine on their
>+	    desk.</para>
>+	</listitem>
>+      </varlistentry>
>+
>+      <varlistentry>
>+	<term>X client</term>
>+
>+	<listitem>
>+	  <para>Each X application, such as
>+	    <application>XTerm</application> or
>+	    <application>Firefox</application>, is a
>+	    <quote>client</quote>.  A client sends messages to the
>+	    server such as <quote>Please draw a window at these
>+	      coordinates</quote>, and the server sends back messages
>+	    such as <quote>The user just clicked on the OK
>+	      button</quote>.</para>
>+
>+	  <para>In a home or small office environment, the X server
>+	    and the X clients commonly run on the same computer.  It
>+	    is also possible to run the X server on a less powerful
>+	    computer and to run the X applications on a more powerful
>+	    system.  In this scenario, the communication between the X
>+	    client and server takes place over the network.</para>
>+	</listitem>
>+      </varlistentry>
>+
>+      <varlistentry>
>+	<term>window manager</term>
>+
>+	<listitem>
>+	  <para>X does not dictate what windows should look like on-screen, how to move them around with the mouse, which
>+	    keystrokes should be used to move between windows, what
>+	    the title bars on each window should look like, whether or
>+	    not they have close buttons on them, and so on.  Instead,
>+	    X delegates this responsibility to a separate window
>+	    manager application.  There are <link
>+	      xlink:href="http://xwinman.org/">dozens of window
>+	      managers</link> available.  Each window manager provides
>+	    a different look and feel: some support virtual desktops,
>+	    some allow customized keystrokes to manage the desktop,
>+	    some have a <quote>Start</quote> button, and some are
>+	    themeable, allowing a complete change of the desktop's
>+	    look-and-feel.  Window managers are available in the
>+	    <filename>x11-wm</filename> category of the Ports
>+	    Collection.</para>
>+
>+	  <para>Each window manager uses a different configuration
>+	    mechanism.  Some expect configuration file written by hand
>+	    while others provide graphical tools for most
>+	    configuration tasks.</para>
>+	</listitem>
>+      </varlistentry>
>+
>+      <varlistentry>
>+	<term>desktop environment</term>
>+
>+	<listitem>
>+	  <para><application>KDE</application> and
>+	    <application>GNOME</application> are considered to be
>+	    desktop environments as they include an entire suite of
>+	    applications for performing common desktop tasks.  These
>+	    may include office suites, web browsers, and games.</para>
>+	</listitem>
>+      </varlistentry>
>+
>+      <varlistentry>
>+	<term>focus policy</term>
>+
>+	<listitem>
>+	  <para>The window manager is responsible for the mouse focus
>+	    policy.  This policy provides some means for choosing
>+	    which window is actively receiving keystrokes and it
>+	    should also visibly indicate which window is currently
>+	    active.</para>
>+
>+	  <para>One focus policy is called
>+	    <quote>click-to-focus</quote>.  In this model, a window
>+	    becomes active upon receiving a mouse click.  In the
>+	    <quote>focus-follows-mouse</quote> policy, the window that
>+	    is under the mouse pointer has focus and the focus is
>+	    changed by pointing at another window.  If the mouse is
>+	    over the root window, then this window is focused.  In the
>+	    <quote>sloppy-focus</quote> model, if the mouse is moved
>+	    over the root window, the most recently used window still
>+	    has the focus.  With sloppy-focus, focus is only changed
>+	    when the cursor enters a new window, and not when exiting
>+	    the current window.  In the <quote>click-to-focus</quote>
>+	    policy, the active window is selected by mouse click.  The
>+	    window may then be raised and appear in front of all other
>+	    windows.  All keystrokes will now be directed to this
>+	    window, even if the cursor is moved to another
>+	    window.</para>
>+
>+	  <para>Different window managers support different focus
>+	    models.  All of them support click-to-focus, and the
>+	    majority of them also support other policies.  Consult the
>+	    documentation for the window manager to determine which
>+	    focus models are available.</para>
>+	</listitem>
>+      </varlistentry>
>+
>+      <varlistentry>
>+	<term>widgets</term>
>+
>+	<listitem>
>+	  <para>Widget is a term for all of the items in the user
>+	    interface that can be clicked or manipulated in some way.
>+	    This includes buttons, check boxes, radio buttons, icons,
>+	    and lists.  A widget toolkit is a set of widgets used to
>+	    create graphical applications.  There are several popular
>+	    widget toolkits, including Qt, used by
>+	    <application>KDE</application>, and GTK+, used by
>+	    <application>GNOME</application>.  As a result,
>+	    applications will have a different look and feel,
>+	    depending upon which widget toolkit was used to create the
>+	    application.</para>
>+	</listitem>
>+      </varlistentry>
>+    </variablelist>
>+  </sect1>
>+
>+  <sect1 xml:id="x-install">
>+    <title>Installing <application>&xorg;</application></title>
>+
>+    <para>On &os;, <application>&xorg;</application> can be installed
>+      as a package or port.</para>
>+
>+    <para>To build and install from the Ports Collection:</para>
>+
>+    <screen>&prompt.root; <userinput>cd /usr/ports/x11/xorg</userinput>
>+&prompt.root; <userinput>make install clean</userinput></screen>
>+
>+    <para>The binary package can be installed more quickly but with
>+      fewer options for customization:</para>
>+
>+    <screen>&prompt.root; <userinput>pkg install xorg</userinput></screen>
>+
>+    <para>Either of these installations results in the complete
>+      <application>&xorg;</application> system being installed.  This
>+      is the best option for most users.</para>
>+
>+    <para>A smaller version of the X system suitable for experienced
>+      users is available in <package>x11/xorg-minimal</package>.  Most
>+      of the documents, libraries, and applications will not be
>+      installed.  Some applications require these additional
>+      components to function.</para>
>+  </sect1>
>+
>+  <sect1 xml:id="x-config">
>+    <title><application>&xorg;</application> Configuration</title>
>+
>+    <info>
>+      <author>
>+	<personname>
>+	  <firstname>Warren</firstname>
>+	  <surname>Block</surname>
>+	</personname>
>+	<contrib>Originally contributed by</contrib>
>+      </author>
>+    </info>
>+
>+    <indexterm><primary>&xorg;</primary></indexterm>
>+    <indexterm><primary><application>&xorg;</application></primary></indexterm>
>+
>+    <sect2 xml:id="x-config-quick-start">
>+      <title>Quick Start</title>
>+
>+      <para><application>&xorg;</application> supports most common
>+	video cards, keyboards, and pointing devices.  These devices
>+	are automatically detected and do not require any manual
>+	configuration.</para>
>+
>+      <procedure>
>+	<step>
>+	  <para>If <application>&xorg;</application> has been used on
>+	    this computer before, move or remove any existing
>+	    configuration files:</para>
>+
>+	  <screen>&prompt.root; <userinput>mv /etc/X11/xorg.conf ~/xorg.conf.etc</userinput>
>+&prompt.root; <userinput>mv /usr/local/etc/X11/xorg.conf ~/xorg.conf.localetc</userinput></screen>
>+	</step>
>+
>+	<step>
>+	  <para>Add the user who will run
>+	    <application>&xorg;</application> to the
>+	    <literal>video</literal> or
>+	    <literal>wheel</literal> group to enable 3D acceleration
>+	    when available.  To add user
>+	    <replaceable>jru</replaceable> to whichever group is
>+	    available:</para>
>+
>+	  <screen>&prompt.root; <userinput>pw groupmod video -m <replaceable>jru</replaceable> || pw groupmod wheel -m <replaceable>jru</replaceable></userinput></screen>
>+	</step>
>+
>+	<step>
>+	  <para>The <acronym>TWM</acronym> window manager is included
>+	    by default.  It is started when
>+	    <application>&xorg;</application> starts:</para>
>+
>+	  <screen>&prompt.user; <userinput>startx</userinput></screen>
>+	</step>
>+
>+	<step>
>+	  <para>On some older versions of &os;, the system console
>+	    must be set to &man.vt.4; before switching back to the
>+	    text console will work properly.  See
>+	    <xref linkend="x-config-kms"/>.</para>
>+	</step>
>+      </procedure>
>+    </sect2>
>+
>+    <sect2 xml:id="x-config-user-group">
>+      <title>User Group for Accelerated Video</title>
>+
>+      <para>Access to <filename>/dev/dri</filename> is needed to allow
>+	3D acceleration on video cards.  It is usually simplest to add
>+	the user who will be running X to either the
>+	<literal>video</literal> or <literal>wheel</literal> group.
>+	Here, &man.pw.8; is used to add user
>+	<replaceable>slurms</replaceable> to the
>+	<literal>video</literal> group, or to the
>+	<literal>wheel</literal> group if there is no
>+	<literal>video</literal> group:</para>
>+
>+      <screen>&prompt.root; <userinput>pw groupmod video -m <replaceable>slurms</replaceable> || pw groupmod wheel -m <replaceable>slurms</replaceable></userinput></screen>
>+    </sect2>
>+
>+    <sect2 xml:id="x-config-kms">
>+      <title>Kernel Mode Setting (<acronym>KMS</acronym>)</title>
>+
>+      <para>When the computer switches from displaying the console to
>+	a higher screen resolution for X, it must set the video
>+	output <emphasis>mode</emphasis>.  Recent versions of
>+	<acronym>&xorg;</acronym> use a system inside the kernel to do
>+	these mode changes more efficiently.  Older versions of &os;
>+	use &man.sc.4;, which is not aware of the
>+	<acronym>KMS</acronym> system.  The end result is that after
>+	closing X, the system console is blank, even though it is
>+	still working.  The newer &man.vt.4; console avoids this
>+	problem.</para>
>+
>+      <para>Add this line to <filename>/boot/loader.conf</filename>
>+	to enable &man.vt.4;:</para>
>+
>+      <programlisting>kern.vty=vt</programlisting>
>+    </sect2>
>+
>+    <sect2 xml:id="x-config-files">
>+      <title>Configuration Files</title>
>+
>+      <sect3 xml:id="x-config-files-directory">
>+	<title>Directory</title>
>+
>+	<para><application>&xorg;</application> looks in several
>+	  directories for configuration files.
>+	  <filename>/usr/local/etc/X11/</filename> is the recommended
>+	  directory for these files on &os;.  Using this directory
>+	  helps keep application files separate from operating system
>+	  files.</para>
>+
>+	<para>Storing configuration files in the legacy
>+	  <filename>/etc/X11/</filename> still works.  However, this
>+	  mixes application files with the base &os; files and is not
>+	  recommended.</para>
>+      </sect3>
>+
>+      <sect3 xml:id="x-config-files-single-or-multi">
>+	<title>Single or Multiple Files</title>
>+
>+	<para>It is easier to use multiple files that each configure a
>+	  specific setting than the traditional single
>+	  <filename>xorg.conf</filename>.  These files are stored in
>+	  the <filename>xorg.conf.d/</filename> subdirectory of the
>+	  main configuration file directory.  The full path is
>+	  typically
>+	  <filename>/usr/local/etc/X11/xorg.conf.d/</filename>.</para>
>+
>+	<para>Examples of these files are shown later in this
>+	  section.</para>
>+
>+	<para>The traditional single <filename>xorg.conf</filename>
>+	  still works, but is neither as clear nor as flexible as
>+	  multiple files in the <filename>xorg.conf.d/</filename>
>+	  subdirectory.</para>
>+      </sect3>
>+    </sect2>
>+
>+    <sect2 xml:id="x-config-video-cards">
>+      <title>Video Cards</title>
>+
>+      <variablelist>
>+	<varlistentry xml:id="x-config-video-cards-intel">
>+	  <term>&intel;</term>
>+
>+	  <listitem>
>+	    <para>3D acceleration is supported on most &intel;
>+	      graphics up to Ivy Bridge (HD Graphics 2500, 4000, and
>+	      P4000), including Iron Lake (HD Graphics) and
>+	      Sandy Bridge (HD Graphics 2000).</para>
>+
>+	    <para>Driver name: <literal>intel</literal></para>
>+
>+	    <para>For reference, see <link
>+	        xlink:href="https://en.wikipedia.org/wiki/List_of_Intel_graphics_processing_units"/>.</para>
>+	  </listitem>
>+	</varlistentry>
>+
>+	<varlistentry xml:id="x-config-video-cards-radeon">
>+	  <term>&amd; Radeon</term>
>+
>+	  <listitem>
>+	    <para>2D and 3D acceleration is supported on Radeon
>+	      cards up to and including the HD6000 series.</para>
>+
>+	    <para>Driver name: <literal>radeon</literal></para>
>+
>+	    <para>For reference, see <link
>+	        xlink:href="https://en.wikipedia.org/wiki/List_of_AMD_graphics_processing_units"/>.</para>
>+	  </listitem>
>+	</varlistentry>
>+
>+	<varlistentry xml:id="x-config-video-cards-nvidia">
>+	  <term>NVIDIA</term>
>+
>+	  <listitem>
>+	    <para>Several NVIDIA drivers are available in the
>+	      <filename>x11</filename> category of the Ports
>+	      Collection.  Install the driver that matches the video
>+	      card.</para>
>+
>+	    <para>For reference, see <link
>+	      xlink:href="https://en.wikipedia.org/wiki/List_of_Nvidia_graphics_processing_units"/>.</para>
>+	  </listitem>
>+	</varlistentry>
>+
>+	<varlistentry xml:id="x-config-video-cards-hybrid">
>+	  <term>Hybrid Combination Graphics</term>
>+
>+	  <listitem>
>+	    <para>Some notebook computers add additional graphics
>+	      processing units to those built into the chipset or
>+	      processor.  <emphasis>Optimus</emphasis> combines
>+	      &intel; and NVIDIA hardware.
>+	      <emphasis>Switchable Graphics</emphasis> or
>+	      <emphasis>Hybrid Graphics</emphasis> are a combination
>+	      of an &intel; or &amd; processor and an &amd; Radeon
>+	      <acronym>GPU</acronym>.</para>
>+
>+	    <para>Implementations of these hybrid graphics systems
>+	      vary, and <application>&xorg;</application> on &os; is
>+	      not able to drive all versions of them.</para>
>+
>+	    <para>Some computers provide a <acronym>BIOS</acronym>
>+	      option to disable one of the graphics adapters or select
>+	      a <emphasis>discrete</emphasis> mode which can be used
>+	      with one of the standard video card drivers.  For
>+	      example, it is sometimes possible to disable the NVIDIA
>+	      <acronym>GPU</acronym> in an Optimus system.  The
>+	      &intel; video can then be used with an &intel;
>+	      driver.</para>
>+
>+	    <para><acronym>BIOS</acronym> settings depend on the model
>+	      of computer.  In some situations, both
>+	      <acronym>GPU</acronym>s can be left enabled, but
>+	      creating a configuration file that only uses the main
>+	      <acronym>GPU</acronym> in the <literal>Device</literal>
>+	      section is enough to make such a system
>+	      functional.</para>
>+	  </listitem>
>+	</varlistentry>
>+
>+	<varlistentry xml:id="x-config-video-cards-other">
>+	  <term>Other Video Cards</term>
>+
>+	  <listitem>
>+	    <para>Drivers for some less-common video cards can be
>+	      found in the <filename>x11-drivers</filename> directory
>+	      of the Ports Collection.</para>
>+
>+	    <para>Cards that are not supported by a specific driver
>+	      might still be usable with the
>+	      <package>x11-drivers/xf86-video-vesa</package> driver.
>+	      This driver is installed by <package>x11/xorg</package>.
>+	      It can also be installed manually as
>+	      <package>x11-drivers/xf86-video-vesa</package>.
>+	      <application>&xorg;</application> attempts to use this
>+	      driver when a specific driver is not found for the video
>+	      card.</para>
>+
>+	    <para><package>x11-drivers/xf86-video-scfb</package> is a
>+	      similar nonspecialized video driver that works on many
>+	      <acronym>UEFI</acronym> and &arm; computers.</para>
>+	  </listitem>
>+	</varlistentry>
>+
>+	<varlistentry xml:id="x-config-video-cards-file">
>+	  <term>Setting the Video Driver in a File</term>
>+
>+	  <listitem>
>+	    <para>To set the &intel; driver in a configuration
>+	      file:</para>
>+
>+	    <example xml:id="x-config-video-cards-file-intel">
>+	      <title>Select &intel; Video Driver in a File</title>
>+
>+	      <para><filename>/usr/local/etc/X11/xorg.conf.d/driver-intel.conf</filename></para>
>+
>+	      <programlisting>Section "Device"
>+	Identifier "Card0"
>+	Driver     "intel"
>+	# BusID    "PCI:1:0:0"
>+EndSection</programlisting>
>+
>+	      <para>If more than one video card is present, the
>+		<literal>BusID</literal> identifier can be uncommented
>+		and set to select the desired card.  A list of video
>+		card bus <acronym>ID</acronym>s can be displayed with
>+		<command>pciconf -lv | grep -B3
>+		  display</command>.</para>
>+	    </example>
>+
>+	    <para>To set the Radeon driver in a configuration
>+	      file:</para>
>+
>+	    <example xml:id="x-config-video-cards-file-radeon">
>+	      <title>Select Radeon Video Driver in a File</title>
>+
>+	      <para><filename>/usr/local/etc/X11/xorg.conf.d/driver-radeon.conf</filename></para>
>+
>+	      <programlisting>Section "Device"
>+	Identifier "Card0"
>+	Driver     "radeon"
>+EndSection</programlisting>
>+	    </example>
>+
>+	    <para>To set the <acronym>VESA</acronym> driver in a
>+	      configuration file:</para>
>+
>+	    <example xml:id="x-config-video-cards-file-vesa">
>+	      <title>Select <acronym>VESA</acronym> Video Driver in a
>+		File</title>
>+
>+	      <para><filename>/usr/local/etc/X11/xorg.conf.d/driver-vesa.conf</filename></para>
>+
>+	      <programlisting>Section "Device"
>+	Identifier "Card0"
>+	Driver     "vesa"
>+EndSection</programlisting>
>+	    </example>
>+	  </listitem>
>+	</varlistentry>
>+      </variablelist>
>+    </sect2>
>+
>+    <sect2 xml:id="x-config-monitors">
>+      <title>Monitors</title>
>+
>+      <para>Almost all monitors support the Extended Display
>+	Identification Data standard (<acronym>EDID</acronym>).
>+	<application>&xorg;</application> uses <acronym>EDID</acronym>
>+	to communicate with the monitor and detect the supported
>+	resolutions and refresh rates.  Then it selects the most
>+	appropriate combination of settings to use with that
>+	monitor.</para>
>+
>+      <para>Other resolutions supported by the monitor can be
>+	chosen by setting the desired resolution in configuration
>+	files, or after the X server has been started with
>+	&man.xrandr.1;.</para>
>+
>+      <variablelist>
>+	<varlistentry xml:id="x-config-monitors-xrandr">
>+	  <term>Using &man.xrandr.1;</term>
>+
>+	  <listitem>
>+	    <para>Run &man.xrandr.1; without any parameters to see a
>+	      list of video outputs and detected monitor modes:</para>
>+
>+	    <screen>&prompt.user; <userinput>xrandr</userinput>
>+Screen 0: minimum 320 x 200, current 3000 x 1920, maximum 8192 x 8192
>+DVI-0 connected primary 1920x1200+1080+0 (normal left inverted right x axis y axis) 495mm x 310mm
>+   1920x1200     59.95*+
>+   1600x1200     60.00
>+   1280x1024     85.02    75.02    60.02
>+   1280x960      60.00
>+   1152x864      75.00
>+   1024x768      85.00    75.08    70.07    60.00
>+   832x624       74.55
>+   800x600       75.00    60.32
>+   640x480       75.00    60.00
>+   720x400       70.08
>+DisplayPort-0 disconnected (normal left inverted right x axis y axis)
>+HDMI-0 disconnected (normal left inverted right x axis y axis)</screen>
>+
>+	    <para>This shows that the <literal>DVI-0</literal> output
>+	      is being used to display a screen resolution of
>+	      1920x1200 pixels at a refresh rate of about 60 Hz.
>+	      Monitors are not attached to the
>+	      <literal>DisplayPort-0</literal> and
>+	      <literal>HDMI-0</literal> connectors.</para>
>+
>+	    <para>Any of the other display modes can be selected with
>+	      &man.xrandr.1;.  For example, to switch to 1280x1024 at
>+	      60 Hz:</para>
>+
>+	    <screen>&prompt.user; <userinput>xrandr --mode 1280x1024 --rate 60</userinput></screen>
>+
>+	    <para>A common task is using the external video output on
>+	      a notebook computer for a video projector.</para>
>+
>+	    <para>Names and types of video connectors vary, so
>+	      &man.xrandr.1; is run without options to list the
>+	      outputs:</para>
>+
>+	    <screen>&prompt.user; <userinput>xrandr</userinput>
>+Screen 0: minimum 320 x 200, current 1366 x 768, maximum 8192 x 8192
>+LVDS1 connected 1366x768+0+0 (normal left inverted right x axis y axis) 344mm x 193mm
>+   1366x768      60.04*+
>+   1024x768      60.00
>+   800x600       60.32    56.25
>+   640x480       59.94
>+VGA1 connected (normal left inverted right x axis y axis)
>+   1280x1024     60.02 +  75.02
>+   1280x960      60.00
>+   1152x864      75.00
>+   1024x768      75.08    70.07    60.00
>+   832x624       74.55
>+   800x600       72.19    75.00    60.32    56.25
>+   640x480       75.00    72.81    66.67    60.00
>+   720x400       70.08
>+HDMI1 disconnected (normal left inverted right x axis y axis)
>+DP1 disconnected (normal left inverted right x axis y axis)</screen>
>+
>+	    <para>Four outputs were found: the built-in panel
>+	      <literal>LVDS1</literal>, and external
>+	      <literal>VGA1</literal>, <literal>HDMI1</literal>, and
>+	      <literal>DP1</literal> connectors.</para>
>+
>+	    <para>The projector has been connected to the
>+	      <literal>VGA1</literal> output.  &man.xrandr.1; is now
>+	      used to set that output to the native resolution of the
>+	      projector and add the additional space to the right side
>+	      of the desktop:</para>
>+
>+	    <screen>&prompt.user; <userinput>xrandr --output VGA1 --auto --right-of LVDS1</userinput></screen>
>+
>+	    <para><literal>--auto</literal> chooses the resolution and
>+	      refresh rate detected by <acronym>EDID</acronym>.  If
>+	      the resolution is not correctly detected, a fixed value
>+	      can be given with <literal>--mode</literal> instead of
>+	      the <literal>--auto</literal> statement.  For example,
>+	      most projectors can be used with a 1024x768 resolution,
>+	      which is set with
>+	      <literal>--mode 1024x768</literal>.</para>
>+
>+	    <para>&man.xrandr.1; is often run from
>+	      <filename>.xinitrc</filename> to set the appropriate
>+	      mode when X starts.</para>
>+	  </listitem>
>+	</varlistentry>
>+
>+	<varlistentry xml:id="x-config-monitors-files">
>+	  <term>Setting Monitor Resolution in a File</term>
>+
>+	  <listitem>
>+	    <para>To set a screen resolution of 1024x768 in a
>+	      configuration file:</para>
>+
>+	    <example>
>+	      <title>Set Screen Resolution in a File</title>
>+
>+	      <para><filename>/usr/local/etc/X11/xorg.conf.d/screen-resolution.conf</filename></para>
>+
>+	      <programlisting>Section "Screen"
>+	Identifier "Screen0"
>+	Device     "Card0"
>+	SubSection "Display"
>+	Modes      "1024x768"
>+	EndSubSection
>+EndSection</programlisting>
>+	    </example>
>+
>+	    <para>The few monitors that do not have
>+	      <acronym>EDID</acronym> can be configured by setting
>+	      <literal>HorizSync</literal> and
>+	      <literal>VertRefresh</literal> to the range of
>+	      frequencies supported by the monitor.</para>
>+
>+	    <example>
>+	      <title>Manually Setting Monitor Frequencies</title>
>+
>+	      <para><filename>/usr/local/etc/X11/xorg.conf.d/monitor0-freq.conf</filename></para>
>+
>+	      <programlisting>Section "Monitor"
>+	Identifier   "Monitor0"
>+	HorizSync    30-83   # kHz
>+	VertRefresh  50-76   # Hz
>+EndSection</programlisting>
>+	    </example>
>+	  </listitem>
>+	</varlistentry>
>+      </variablelist>
>+    </sect2>
>+
>+    <sect2 xml:id="x-config-input">
>+      <title>Input Devices</title>
>+
>+      <sect3 xml:id="x-config-input-keyboard">
>+	<title>Keyboards</title>
>+
>+	<variablelist>
>+	  <varlistentry xml:id="x-config-input-keyboard-layout">
>+	    <term>Keyboard Layout</term>
>+
>+	    <listitem>
>+	      <para>The standardized location of keys on a keyboard
>+		is called a <emphasis>layout</emphasis>.  Layouts and
>+		other adjustable parameters are listed in
>+		&man.xkeyboard-config.7;.</para>
>+
>+	      <para>A United States layout is the default.  To select
>+		an alternate layout, set the
>+		<literal>XkbLayout</literal> and
>+		<literal>XkbVariant</literal> options in an
>+		<literal>InputClass</literal>.  This will be applied
>+		to all input devices that match the class.</para>
>+
>+	      <para>This example selects a French keyboard layout with
>+		the <literal>oss</literal> variant.</para>
>+
>+	      <example>
>+		<title>Setting a Keyboard Layout</title>
>+
>+		<para><filename>/usr/local/etc/X11/xorg.conf.d/keyboard-fr-oss.conf</filename></para>
>+
>+		<programlisting>Section	"InputClass"
>+	Identifier	"KeyboardDefaults"
>+	Driver		"keyboard"
>+	MatchIsKeyboard	"on"
>+	Option		"XkbLayout" "fr"
>+	Option		"XkbVariant" "oss"
>+EndSection</programlisting>
>+	      </example>
>+
>+	      <example>
>+		<title>Setting Multiple Keyboard Layouts</title>
>+
>+		<para>Set United States, Spanish, and Ukrainian
>+		  keyboard layouts.  Cycle through these layouts by
>+		  pressing
>+		  <keycombo action="simul">
>+		    <keycap>Alt</keycap>
>+		    <keycap>Shift</keycap>
>+		  </keycombo>.  <package>x11/xxkb</package> or
>+		  <package>x11/sbxkb</package> can be used for
>+		  improved layout switching control and
>+		  current layout indicators.</para>
>+
>+		<para><filename>/usr/local/etc/X11/xorg.conf.d/kbd-layout-multi.conf</filename></para>
>+
>+		<programlisting>Section	"InputClass"
>+	Identifier	"All Keyboards"
>+	MatchIsKeyboard	"yes"
>+	Option		"XkbLayout" "us, es, ua"
>+EndSection</programlisting>
>+	      </example>
>+	    </listitem>
>+	  </varlistentry>
>+
>+	  <varlistentry xml:id="x-config-input-keyboard-zap">
>+	    <term>Closing <application>&xorg;</application> From the
>+	    Keyboard</term>
>+
>+	    <listitem>
>+	      <para>X can be closed with a combination of keys.
>+		By default, that key combination is not set because it
>+		conflicts with keyboard commands for some
>+		applications.  Enabling this option requires changes
>+		to the keyboard <literal>InputDevice</literal>
>+		section:</para>
>+
>+	      <example>
>+		<title>Enabling Keyboard Exit from X</title>
>+
>+		<para><filename>/usr/local/etc/X11/xorg.conf.d/keyboard-zap.conf</filename></para>
>+
>+		<programlisting>Section	"InputClass"
>+	Identifier	"KeyboardDefaults"
>+	Driver		"keyboard"
>+	MatchIsKeyboard	"on"
>+	Option		"XkbOptions" "terminate:ctrl_alt_bksp"
>+EndSection</programlisting>
>+	      </example>
>+	    </listitem>
>+	  </varlistentry>
>+	</variablelist>
>+      </sect3>
>+
>+      <sect3 xml:id="x11-input-mice">
>+	<title>Mice and Pointing Devices</title>
>+
>+	<para>Many mouse parameters can be adjusted with configuration
>+	  options.  See &man.mousedrv.4x; for a full list.</para>
>+
>+	<variablelist>
>+	  <varlistentry xml:id="x11-input-mice-buttons">
>+	    <term>Mouse Buttons</term>
>+
>+	    <listitem>
>+	      <para>The number of buttons on a mouse can be set in the
>+		mouse <literal>InputDevice</literal> section of
>+		<filename>xorg.conf</filename>.  To set the number of
>+		buttons to 7:</para>
>+
>+	      <example>
>+		<title>Setting the Number of Mouse Buttons</title>
>+
>+		<para><filename>/usr/local/etc/X11/xorg.conf.d/mouse0-buttons.conf</filename></para>
>+
>+		<programlisting>Section "InputDevice"
>+	Identifier  "Mouse0"
>+	Option      "Buttons" "7"
>+EndSection</programlisting>
>+	      </example>
>+	    </listitem>
>+	  </varlistentry>
>+	</variablelist>
>+      </sect3>
>+    </sect2>
>+
>+    <sect2 xml:id="x-config-manual-configuration">
>+      <title>Manual Configuration</title>
>+
>+      <para>In some cases, <application>&xorg;</application>
>+	autoconfiguration does not work with particular hardware, or a
>+	different configuration is desired.  For these cases, a custom
>+	configuration file can be created.</para>
>+
>+      <para>A configuration file can be generated by
>+	<application>&xorg;</application> based on the detected
>+	hardware.  This file is often a useful starting point for
>+	custom configurations.</para>
>+
>+      <para>Generating an <filename>xorg.conf</filename>:</para>
>+
>+      <screen>&prompt.root; <userinput>Xorg -configure</userinput></screen>
>+
>+      <para>The configuration file is saved to
>+	<filename>/root/xorg.conf.new</filename>.  Make any changes
>+	desired, then test that file with:</para>
>+
>+      <screen>&prompt.root; <userinput>Xorg -config /root/xorg.conf.new</userinput></screen>
>+
>+      <para>After the new configuration has been adjusted and tested,
>+	it can be split into smaller files in the normal location,
>+	<filename>/usr/local/etc/X11/xorg.conf.d/</filename>.</para>
>+    </sect2>
>+  </sect1>
>+
>+  <sect1 xml:id="x-fonts">
>+    
>+    <title>Using Fonts in <application>&xorg;</application></title>
>+
>+    <sect2 xml:id="type1">
>+      <title>Type1 Fonts</title>
>+
>+      <para>The default fonts that ship with
>+	<application>&xorg;</application> are less than ideal for
>+	typical desktop publishing applications.  Large presentation
>+	fonts show up jagged and unprofessional looking, and small
>+	fonts are almost completely unintelligible.  However, there
>+	are several free, high quality Type1 (&postscript;) fonts
>+	available which can be readily used with
>+	<application>&xorg;</application>.  For instance, the URW font
>+	collection (<package>x11-fonts/urwfonts</package>) includes
>+	high quality versions of standard type1 fonts (<trademark
>+	  class="registered">Times Roman</trademark>, <trademark
>+	  class="registered">Helvetica</trademark>, <trademark
>+	  class="registered">Palatino</trademark> and others).  The
>+	Freefonts collection (<package>x11-fonts/freefonts</package>)
>+	includes many more fonts, but most of them are intended for
>+	use in graphics software such as the
>+	<application>Gimp</application>, and are not complete enough
>+	to serve as screen fonts.  In addition,
>+	<application>&xorg;</application> can be configured to use
>+	&truetype; fonts with a minimum of effort.  For more details
>+	on this, see the &man.X.7; manual page or <xref
>+	  linkend="truetype"/>.</para>
>+
>+      <para>To install the above Type1 font collections from the Ports
>+	Collection, run the following commands:</para>
>+
>+      <screen>&prompt.root; <userinput>cd /usr/ports/x11-fonts/urwfonts</userinput>
>+&prompt.root; <userinput>make install clean</userinput></screen>
>+
>+      <para>And likewise with the freefont or other collections.  To
>+	have the X server detect these fonts, add an appropriate line
>+	to the X server configuration file
>+	(<filename>/etc/X11/xorg.conf</filename>), which reads:</para>
>+
>+      <programlisting>FontPath "/usr/local/share/fonts/urwfonts/"</programlisting>
>+
>+      <para>Alternatively, at the command line in the X session
>+	run:</para>
>+
>+      <screen>&prompt.user; <userinput>xset fp+ /usr/local/share/fonts/urwfonts</userinput>
>+&prompt.user; <userinput>xset fp rehash</userinput></screen>
>+
>+      <para>This will work but will be lost when the X session is
>+	closed, unless it is added to the startup file
>+	(<filename>~/.xinitrc</filename> for a normal
>+	<command>startx</command> session, or
>+	<filename>~/.xsession</filename> when logging in through a
>+	graphical login manager like <application>XDM</application>).
>+	A third way is to use the new
>+	<filename>/usr/local/etc/fonts/local.conf</filename> as
>+	demonstrated in <xref linkend="antialias"/>.</para>
>+    </sect2>
>+
>+    <sect2 xml:id="truetype">
>+      <title>&truetype; Fonts</title>
>+
>+      <indexterm>
>+	<primary>TrueType Fonts</primary>
>+      </indexterm>
>+      <indexterm>
>+	<primary>fonts</primary>
>+	<secondary>TrueType</secondary>
>+      </indexterm>
>+
>+      <para><application>&xorg;</application> has built in support for
>+	rendering &truetype; fonts.  There are two different modules
>+	that can enable this functionality.  The freetype module is
>+	used in this example because it is more consistent with the
>+	other font rendering back-ends.  To enable the freetype module
>+	just add the following line to the <literal>"Module"</literal>
>+	section of <filename>/etc/X11/xorg.conf</filename>.</para>
>+
>+      <programlisting>Load  "freetype"</programlisting>
>+
>+      <para>Now make a directory for the &truetype; fonts (for
>+	example,
>+	<filename>/usr/local/share/fonts/TrueType</filename>) and
>+	copy all of the &truetype; fonts into this directory.  Keep in
>+	mind that &truetype; fonts cannot be directly taken from an
>+	&apple; &mac;; they must be in &unix;/&ms-dos;/&windows;
>+	format for use by <application>&xorg;</application>.  Once the
>+	files have been copied into this directory, use
>+	<application>mkfontdir</application> to create a
>+	<filename>fonts.dir</filename>, so that the X font renderer
>+	knows that these new files have been installed.
>+	<command>mkfontdir</command> can be installed as a package:</para>
>+
>+      <screen>&prompt.root; <userinput>pkg install mkfontdir</userinput></screen>
>+
>+      <para>Then create an index of X font files in a directory:</para>
>+
>+      <screen>&prompt.root; <userinput>cd /usr/local/share/fonts/TrueType</userinput>
>+&prompt.root; <userinput>mkfontdir</userinput></screen>
>+
>+      <para>Now add the &truetype; directory to the font path.  This
>+	is just the same as described in <xref
>+	  linkend="type1"/>:</para>
>+
>+      <screen>&prompt.user; <userinput>xset fp+ /usr/local/share/fonts/TrueType</userinput>
>+&prompt.user; <userinput>xset fp rehash</userinput></screen>
>+
>+      <para>or add a <literal>FontPath</literal> line to
>+	<filename>xorg.conf</filename>.</para>
>+
>+      <para>Now <application>Gimp</application>,
>+	<application>OpenOffice</application>, and all of the other X
>+	applications should now recognize the installed &truetype;
>+	fonts.  Extremely small fonts (as with text in a high
>+	resolution display on a web page) and extremely large fonts
>+	(within <application>&staroffice;</application>) will look
>+	much better now.</para>
>+    </sect2>
>+
>+    <sect2 xml:id="antialias">
>+      
>+      <title>Anti-Aliased Fonts</title>
>+
>+      <indexterm>
>+	<primary>anti-aliased fonts</primary>
>+      </indexterm>
>+      <indexterm>
>+	<primary>fonts</primary>
>+	<secondary>anti-aliased</secondary>
>+      </indexterm>
>+
>+      <para>All fonts in <application>&xorg;</application> that are
>+	found in <filename>/usr/local/share/fonts/</filename> and
>+	<filename>~/.fonts/</filename> are automatically made
>+	available for anti-aliasing to Xft-aware applications.  Most
>+	recent applications are Xft-aware, including
>+	<application>KDE</application>,
>+	<application>GNOME</application>, and
>+	<application>Firefox</application>.</para>
>+
>+      <para>In order to control which fonts are anti-aliased, or to
>+	configure anti-aliasing properties, create (or edit, if it
>+	already exists) the file
>+	<filename>/usr/local/etc/fonts/local.conf</filename>.  Several
>+	advanced features of the Xft font system can be tuned using
>+	this file; this section describes only some simple
>+	possibilities.  For more details, please see
>+	&man.fonts-conf.5;.</para>
>+
>+      <indexterm><primary>XML</primary></indexterm>
>+
>+      <para>This file must be in XML format.  Pay careful attention to
>+	case, and make sure all tags are properly closed.  The file
>+	begins with the usual XML header followed by a DOCTYPE
>+	definition, and then the <literal>&lt;fontconfig&gt;</literal>
>+	tag:</para>
>+
>+      <programlisting>&lt;?xml version="1.0"?&gt;
>+      &lt;!DOCTYPE fontconfig SYSTEM "fonts.dtd"&gt;
>+      &lt;fontconfig&gt;</programlisting>
>+
>+      <para>As previously stated, all fonts in
>+	<filename>/usr/local/share/fonts/</filename> as well as
>+	<filename>~/.fonts/</filename> are already made available to
>+	Xft-aware applications.  If you wish to add another directory
>+	outside of these two directory trees, add a line similar to
>+	the following to
>+	<filename>/usr/local/etc/fonts/local.conf</filename>:</para>
>+
>+      <programlisting>&lt;dir&gt;/path/to/my/fonts&lt;/dir&gt;</programlisting>
>+
>+      <para>After adding new fonts, and especially new font
>+	directories, you should run the following command to rebuild
>+	the font caches:</para>
>+
>+      <screen>&prompt.root; <userinput>fc-cache -f</userinput></screen>
>+
>+      <para>Anti-aliasing makes borders slightly fuzzy, which makes
>+	very small text more readable and removes
>+	<quote>staircases</quote> from large text, but can cause
>+	eyestrain if applied to normal text.  To exclude font sizes
>+	smaller than 14 point from anti-aliasing, include these
>+	lines:</para>
>+
>+      <programlisting>        &lt;match target="font"&gt;
>+	    &lt;test name="size" compare="less"&gt;
>+		&lt;double&gt;14&lt;/double&gt;
>+	    &lt;/test&gt;
>+	    &lt;edit name="antialias" mode="assign"&gt;
>+		&lt;bool&gt;false&lt;/bool&gt;
>+	    &lt;/edit&gt;
>+	&lt;/match&gt;
>+	&lt;match target="font"&gt;
>+	    &lt;test name="pixelsize" compare="less" qual="any"&gt;
>+		&lt;double&gt;14&lt;/double&gt;
>+	    &lt;/test&gt;
>+	    &lt;edit mode="assign" name="antialias"&gt;
>+		&lt;bool&gt;false&lt;/bool&gt;
>+	    &lt;/edit&gt;
>+	&lt;/match&gt;</programlisting>
>+
>+      <indexterm>
>+	<primary>fonts</primary>
>+	<secondary>spacing</secondary>
>+      </indexterm>
>+
>+      <para>Spacing for some monospaced fonts may also be
>+	inappropriate with anti-aliasing.  This seems to be an issue
>+	with <application>KDE</application>, in particular.  One
>+	possible fix for this is to force the spacing for such fonts
>+	to be 100. Add the following lines:</para>
>+
>+      <programlisting>       &lt;match target="pattern" name="family"&gt;
>+	   &lt;test qual="any" name="family"&gt;
>+	       &lt;string&gt;fixed&lt;/string&gt;
>+	   &lt;/test&gt;
>+	   &lt;edit name="family" mode="assign"&gt;
>+	       &lt;string&gt;mono&lt;/string&gt;
>+	   &lt;/edit&gt;
>+	&lt;/match&gt;
>+	&lt;match target="pattern" name="family"&gt;
>+	    &lt;test qual="any" name="family"&gt;
>+		&lt;string&gt;console&lt;/string&gt;
>+	    &lt;/test&gt;
>+	    &lt;edit name="family" mode="assign"&gt;
>+		&lt;string&gt;mono&lt;/string&gt;
>+	    &lt;/edit&gt;
>+	&lt;/match&gt;</programlisting>
>+
>+      <para>(this aliases the other common names for fixed fonts as
>+	<literal>"mono"</literal>), and then add:</para>
>+
>+      <programlisting>         &lt;match target="pattern" name="family"&gt;
>+	     &lt;test qual="any" name="family"&gt;
>+		 &lt;string&gt;mono&lt;/string&gt;
>+	     &lt;/test&gt;
>+	     &lt;edit name="spacing" mode="assign"&gt;
>+		 &lt;int&gt;100&lt;/int&gt;
>+	     &lt;/edit&gt;
>+	 &lt;/match&gt;      </programlisting>
>+
>+      <para>Certain fonts, such as Helvetica, may have a problem when
>+	anti-aliased.  Usually this manifests itself as a font that
>+	seems cut in half vertically.  At worst, it may cause
>+	applications to crash.  To avoid this, consider adding the
>+	following to <filename>local.conf</filename>:</para>
>+
>+      <programlisting>         &lt;match target="pattern" name="family"&gt;
>+	     &lt;test qual="any" name="family"&gt;
>+		 &lt;string&gt;Helvetica&lt;/string&gt;
>+	     &lt;/test&gt;
>+	     &lt;edit name="family" mode="assign"&gt;
>+		 &lt;string&gt;sans-serif&lt;/string&gt;
>+	     &lt;/edit&gt;
>+	 &lt;/match&gt;        </programlisting>
>+
>+      <para>Once you have finished editing
>+	<filename>local.conf</filename> make sure you end the file
>+	with the <literal>&lt;/fontconfig&gt;</literal> tag.  Not
>+	doing this will cause your changes to be ignored.</para>
>+
>+      <para>Finally, users can add their own settings via their
>+	personal <filename>.fonts.conf</filename> files.  To do this,
>+	each user should simply create a
>+	<filename>~/.fonts.conf</filename>.  This file must also be in
>+	XML format.</para>
>+
>+      <indexterm><primary>LCD screen</primary></indexterm>
>+      <indexterm><primary>Fonts</primary>
>+	<secondary>LCD screen</secondary></indexterm>
>+
>+      <para>One last point: with an LCD screen, sub-pixel sampling may
>+	be desired.  This basically treats the (horizontally
>+	separated) red, green and blue components separately to
>+	improve the horizontal resolution; the results can be
>+	dramatic.  To enable this, add the line somewhere in
>+	<filename>local.conf</filename>:</para>
>+
>+      <programlisting>&lt;match target="font"&gt;
>+	     &lt;test qual="all" name="rgba"&gt;
>+		 &lt;const&gt;unknown&lt;/const&gt;
>+	     &lt;/test&gt;
>+	     &lt;edit name="rgba" mode="assign"&gt;
>+		 &lt;const&gt;rgb&lt;/const&gt;
>+	     &lt;/edit&gt;
>+	 &lt;/match&gt;</programlisting>
>+
>+      <note>
>+	<para>Depending on the sort of display,
>+	  <literal>rgb</literal> may need to be changed to
>+	  <literal>bgr</literal>, <literal>vrgb</literal> or
>+	  <literal>vbgr</literal>: experiment and see which works
>+	  best.</para>
>+      </note>
>+    </sect2>
>+  </sect1>
>+
>+  <sect1 xml:id="x-xdm">
>+    <info>
>+      <title>The X Display Manager</title>
>+
>+      <authorgroup>
>+	<author>
>+	  <personname>
>+	    <firstname>Seth</firstname>
>+	    <surname>Kingsley</surname>
>+	  </personname>
>+	  <contrib>Contributed by </contrib>
>+	</author>
>+      </authorgroup>
>+    </info>
>+
>+    <indexterm><primary>X Display Manager</primary></indexterm>
>+    <para><application>&xorg;</application> provides an X Display
>+      Manager, <application>XDM</application>, which can be used for
>+      login session management.  <application>XDM</application>
>+      provides a graphical interface for choosing which display server
>+      to connect to and for entering authorization information such as
>+      a login and password combination.</para>
>+
>+    <para>This section demonstrates how to configure the X Display
>+      Manager on &os;.  Some desktop environments provide their own
>+      graphical login manager.  Refer to <xref
>+	linkend="x11-wm-gnome"/> for instructions on how to configure
>+      the GNOME Display Manager and <xref linkend="x11-wm-kde"/> for
>+      instructions on how to configure the KDE Display Manager.</para>
>+
>+    <sect2>
>+      <title>Configuring <application>XDM</application></title>
>+
>+      <para>To install <application>XDM</application>, use the
>+	<package>x11/xdm</package> package or port.  Once installed,
>+	<application>XDM</application> can be configured to run when
>+	the  machine boots up by editing this entry in
>+	<filename>/etc/ttys</filename>:</para>
>+
>+      <screen>ttyv8   "/usr/local/bin/xdm -nodaemon"  xterm   off secure</screen>
>+
>+      <para>Change the <literal>off</literal> to <literal>on</literal>
>+	and save the edit.  The <literal>ttyv8</literal> in this entry
>+	indicates that <application>XDM</application> will run on the
>+	ninth virtual terminal.</para>
>+
>+      <para>The <application>XDM</application> configuration directory
>+	is located in <filename>/usr/local/lib/X11/xdm</filename>.
>+	This directory contains several files used to change the
>+	behavior and appearance of <application>XDM</application>, as
>+	well as a few scripts and programs used to set up the desktop
>+	when <application>XDM</application> is running.  <xref
>+	  linkend="xdm-config-files"/> summarizes the function of each
>+	of these files.  The exact syntax and usage of these files is
>+	described in &man.xdm.1;.</para>
>+
>+      <table frame="none" pgwide="1" xml:id="xdm-config-files">
>+	<title>XDM Configuration Files</title>
>+
>+	<tgroup cols="2">
>+	  <thead>
>+	    <row>
>+	      <entry>File</entry>
>+	      <entry>Description</entry>
>+	    </row>
>+	  </thead>
>+
>+	  <tbody>
>+	    <row>
>+	      <entry><filename>Xaccess</filename></entry>
>+	      <entry>The protocol for connecting to
>+		<application>XDM</application> is called the X Display
>+		Manager Connection Protocol (<acronym>XDMCP</acronym>)
>+		This file is a client authorization ruleset for
>+		controlling <acronym>XDMCP</acronym> connections from
>+		remote machines.  By default, this file does not allow
>+		any remote clients to connect.</entry>
>+	    </row>
>+
>+	    <row>
>+	      <entry><filename>Xresources</filename></entry>
>+	      <entry>This file controls the look and feel of the
>+		<application>XDM</application> display chooser and
>+		login screens.  The default configuration is a simple
>+		rectangular login window with the hostname of the
>+		machine displayed at the top in a large font and
>+		<quote>Login:</quote> and <quote>Password:</quote>
>+		prompts below.  The format of this file is identical
>+		to the app-defaults file described in the
>+		<application>&xorg;</application>
>+		documentation.</entry>
>+	    </row>
>+
>+	    <row>
>+	      <entry><filename>Xservers</filename></entry>
>+	      <entry>The list of local and remote displays the chooser
>+		should provide as login choices.</entry>
>+	    </row>
>+
>+	    <row>
>+	      <entry><filename>Xsession</filename></entry>
>+	      <entry>Default session script for logins which is run by
>+		<application>XDM</application> after a user has logged
>+		in.  Normally each user will have a customized session
>+		script in <filename>~/.xsession</filename> that
>+		overrides this script</entry>
>+	    </row>
>+
>+	    <row>
>+	      <entry><filename>Xsetup_</filename>*</entry>
>+	      <entry>Script to automatically launch applications
>+		before displaying the chooser or login interfaces.
>+		There is a script for each display being used, named
>+		<filename>Xsetup_*</filename>, where
>+		<literal>*</literal> is the local display number.
>+		Typically these scripts run one or two programs in the
>+		background such as
>+		<command>xconsole</command>.</entry>
>+	    </row>
>+
>+	    <row>
>+	      <entry><filename>xdm-config</filename></entry>
>+	      <entry>Global configuration for all displays running
>+		on this machine.</entry>
>+	    </row>
>+
>+	    <row>
>+	      <entry><filename>xdm-errors</filename></entry>
>+	      <entry>Contains errors generated by the server program.
>+		If a display that <application>XDM</application> is
>+		trying to start hangs, look at this file for error
>+		messages.  These messages are also written to the
>+		user's <filename>~/.xsession-errors</filename> on a
>+		per-session basis.</entry>
>+	    </row>
>+
>+	    <row>
>+	      <entry><filename>xdm-pid</filename></entry>
>+	      <entry>The running process <acronym>ID</acronym> of
>+		<application>XDM</application>.</entry>
>+	    </row>
>+	  </tbody>
>+	</tgroup>
>+      </table>
>+    </sect2>
>+
>+    <sect2>
>+      <title>Configuring Remote Access</title>
>+
>+      <para>By default, only users on the same system can login using
>+	<application>XDM</application>.  To enable users on other
>+	systems to connect to the display server, edit the access
>+	control rules and enable the connection listener.</para>
>+
>+      <para>To configure <application>XDM</application> to listen for
>+	any remote connection, comment out the
>+	<literal>DisplayManager.requestPort</literal> line in
>+	<filename>/usr/local/lib/X11/xdm/xdm-config</filename> by
>+	putting a <literal>!</literal> in front of it:</para>
>+
>+      <screen>! SECURITY: do not listen for XDMCP or Chooser requests
>+! Comment out this line if you want to manage X terminals with xdm
>+DisplayManager.requestPort:     0</screen>
>+
>+      <para>Save the edits and restart <application>XDM</application>.
>+	To restrict remote access, look at the example entries in
>+	<filename>/usr/local/lib/X11/xdm/Xaccess</filename> and refer
>+	to &man.xdm.1; for further information.</para>
>+    </sect2>
>+  </sect1>
>+
>+  <sect1 xml:id="x11-wm">
>+    <info>
>+      <title>Desktop Environments</title>
>+
>+      <authorgroup>
>+	<author>
>+	  <personname>
>+	    <firstname>Valentino</firstname>
>+	    <surname>Vaschetto</surname>
>+	  </personname>
>+	  <contrib>Contributed by </contrib>
>+	   
>+	</author>
>+      </authorgroup>
>+    </info>
>+
>+    <para>This section describes how to install three popular desktop
>+      environments on a &os; system.  A desktop environment can range
>+      from a simple window manager to a complete suite of desktop
>+      applications.  Over a hundred desktop environments are available
>+      in the <filename>x11-wm</filename> category of the Ports
>+      Collection.</para>
>+
>+    <sect2 xml:id="x11-wm-gnome">
>+      <title>GNOME</title>
>+
>+      <indexterm><primary>GNOME</primary></indexterm>
>+      <para><application>GNOME</application> is a user-friendly
>+	desktop environment.  It includes a panel for starting
>+	applications and displaying status, a desktop, a set of tools
>+	and applications, and a set of conventions that make it easy
>+	for applications to cooperate and be consistent with each
>+	other.  More information regarding
>+	<application>GNOME</application> on &os; can be found at <link
>+	  xlink:href="http://www.FreeBSD.org/gnome">http://www.FreeBSD.org/gnome</link>.
>+	That web site contains additional documentation about
>+	installing, configuring, and managing
>+	<application>GNOME</application> on &os;.</para>
>+
>+      <para>This desktop environment can be installed from a
>+	package:</para>
>+
>+      <screen>&prompt.root; <userinput>pkg install gnome2</userinput></screen>
>+
>+      <para>To instead build <application>GNOME</application> from
>+	ports, use the following command.
>+	<application>GNOME</application> is a large application and
>+	will take some time to compile, even on a fast
>+	computer.</para>
>+
>+      <screen>&prompt.root; <userinput>cd /usr/ports/x11/gnome2</userinput>
>+&prompt.root; <userinput>make install clean</userinput></screen>
>+
>+      <para><application>GNOME</application>
>+	requires <filename>/proc</filename> to be mounted.  Add this
>+	line to <filename>/etc/fstab</filename> to mount this file
>+	system automatically during system startup:</para>
>+
>+      <programlisting>proc           /proc       procfs  rw  0   0</programlisting>
>+
>+      <para><application>GNOME</application> uses
>+	<application>D-Bus</application> and
>+	<application>HAL</application> for a
>+	message bus and hardware abstraction.  These applications are automatically
>+	installed as dependencies of <application>GNOME</application>.
>+	Enable them in <filename>/etc/rc.conf</filename> so
>+	they will be started when the system boots:</para>
>+
>+      <programlisting>dbus_enable="YES"
>+hald_enable="YES"</programlisting>
>+
>+      <para>After installation,
>+	configure <application>&xorg;</application> to start
>+	<application>GNOME</application>.  The easiest way to do this
>+	is to enable the GNOME Display Manager,
>+	<application>GDM</application>, which is installed as part of
>+	the <application>GNOME</application> package or port.  It can
>+	be enabled by adding this line to
>+	<filename>/etc/rc.conf</filename>:</para>
>+
>+      <programlisting>gdm_enable="YES"</programlisting>
>+
>+      <para>It is often desirable to also start all
>+	<application>GNOME</application> services.  To achieve this,
>+	add a second line to <filename>/etc/rc.conf</filename>:</para>
>+
>+      <programlisting>gnome_enable="YES"</programlisting>
>+
>+      <para><application>GDM</application> will start
>+	automatically when the system boots.</para>
>+
>+      <para>A second method for starting
>+	<application>GNOME</application> is to type
>+	<command>startx</command> from the command-line after
>+	configuring <filename>~/.xinitrc</filename>.  If this file
>+	already exists, replace the line that starts the current
>+	window manager with one that starts
>+	<filename>/usr/local/bin/gnome-session</filename>.  If this
>+	file does not exist, create it with this command:</para>
>+
>+      <screen>&prompt.user; <userinput>echo "exec /usr/local/bin/gnome-session" &gt; ~/.xinitrc</userinput></screen>
>+
>+      <para>A third method is to use <application>XDM</application> as
>+	the display manager.  In this case, create an executable
>+	<filename>~/.xsession</filename>:</para>
>+
>+      <screen>&prompt.user; <userinput>echo "#!/bin/sh" &gt; ~/.xsession</userinput>
>+&prompt.user; <userinput>echo "exec /usr/local/bin/gnome-session" &gt;&gt; ~/.xsession</userinput>
>+&prompt.user; <userinput>chmod +x ~/.xsession</userinput></screen>
>+    </sect2>
>+
>+    <sect2 xml:id="x11-wm-kde">
>+      <title>KDE</title>
>+
>+      <indexterm><primary>KDE</primary></indexterm>
>+
>+      <para><application>KDE</application> is another easy-to-use
>+	desktop environment.  This desktop provides a suite of
>+	applications with a consistent look and feel, a standardized
>+	menu and toolbars, keybindings, color-schemes,
>+	internationalization, and a centralized, dialog-driven desktop
>+	configuration.  More information on
>+	<application>KDE</application> can be found at <link
>+	  xlink:href="http://www.kde.org/">http://www.kde.org/</link>.
>+	For &os;-specific information, consult <link
>+	  xlink:href="http://freebsd.kde.org/">http://freebsd.kde.org</link>.</para>
>+
>+      <para>To install the <application>KDE</application> package,
>+	type:</para>
>+
>+      <screen>&prompt.root; <userinput>pkg install x11/kde4</userinput></screen>
>+
>+      <para>To instead build the <application>KDE</application> port,
>+	use the following command.  Installing the port will provide a
>+	menu for selecting which components to install.
>+	<application>KDE</application> is a large application and will
>+	take some time to compile, even on a fast computer.</para>
>+
>+      <screen>&prompt.root; <userinput>cd /usr/ports/x11/kde4</userinput>
>+&prompt.root; <userinput>make install clean</userinput></screen>
>+
>+      <indexterm>
>+	<primary>KDE</primary>
>+	<secondary>display manager</secondary>
>+      </indexterm>
>+
>+      <para><application>KDE</application> requires
>+	<filename>/proc</filename> to be mounted.  Add this line to
>+	<filename>/etc/fstab</filename> to mount this file system
>+	automatically during system startup:</para>
>+
>+      <programlisting>proc           /proc       procfs  rw  0   0</programlisting>
>+
>+      <para>The installation of <application>KDE</application>
>+	includes the KDE Display Manager,
>+	<application>KDM</application>.  To enable this display
>+	manager, add this line to
>+	<filename>/etc/rc.conf</filename>:</para>
>+
>+      <programlisting>kdm4_enable="YES"</programlisting>
>+
>+      <para>A second method for launching
>+	<application>KDE</application> is to type
>+	<command>startx</command> from the command line.  For this to
>+	work, the following line is needed in
>+	<filename>~/.xinitrc</filename>:</para>
>+
>+      <programlisting>exec /usr/local/bin/startkde</programlisting>
>+
>+      <para>A third method for starting <application>KDE</application>
>+	is through <application>XDM</application>.  To do so, create
>+	an executable <filename>~/.xsession</filename> as
>+	follows:</para>
>+
>+      <screen>&prompt.user; <userinput>echo "#!/bin/sh" &gt; ~/.xsession</userinput>
>+&prompt.user; <userinput>echo "exec /usr/local/bin/startkde" &gt;&gt; ~/.xsession</userinput>
>+&prompt.user; <userinput>chmod +x ~/.xsession</userinput></screen>
>+
>+      <para>Once <application>KDE</application> is started, refer to
>+	its built-in help system for more information on how to use
>+	its various menus and applications.</para>
>+    </sect2>
>+
>+    <sect2 xml:id="x11-wm-xfce">
>+      <title>Xfce</title>
>+
>+      <para><application>Xfce</application> is a desktop environment
>+	based on the GTK+ toolkit used by
>+	<application>GNOME</application>.  However, it is more
>+	lightweight and provides a simple, efficient, easy-to-use
>+	desktop.  It is fully configurable, has a main panel with
>+	menus, applets, and application launchers, provides a file
>+	manager and sound manager, and is themeable.  Since it is
>+	fast, light, and efficient, it is ideal for older or slower
>+	machines with memory limitations.  More information on
>+	<application>Xfce</application> can be found at <link
>+	  xlink:href="http://www.xfce.org/">http://www.xfce.org</link>.</para>
>+
>+      <para>To install the <application>Xfce</application>
>+	package:</para>
>+
>+      <screen>&prompt.root; <userinput>pkg install xfce</userinput></screen>
>+
>+      <para>Alternatively, to build the port:</para>
>+
>+      <screen>&prompt.root; <userinput>cd /usr/ports/x11-wm/xfce4</userinput>
>+&prompt.root; <userinput>make install clean</userinput></screen>
>+
>+      <para>Unlike <application>GNOME</application> or
>+	<application>KDE</application>,
>+	<application>Xfce</application> does not provide its own login
>+	manager.  In order to start <application>Xfce</application>
>+	from the command line by typing <command>startx</command>,
>+	first add its entry to <filename>~/.xinitrc</filename>:</para>
>+
>+      <screen>&prompt.user; <userinput>echo "exec /usr/local/bin/startxfce4 --with-ck-launch" &gt; ~/.xinitrc</userinput></screen>
>+
>+      <para>An alternate method is to use
>+	<application>XDM</application>.  To configure this method,
>+	create an executable <filename>~/.xsession</filename>:</para>
>+
>+      <screen>&prompt.user; <userinput>echo "#!/bin/sh" &gt; ~/.xsession</userinput>
>+&prompt.user; <userinput>echo "exec /usr/local/bin/startxfce4 --with-ck-launch" &gt;&gt; ~/.xsession</userinput>
>+&prompt.user; <userinput>chmod +x ~/.xsession</userinput></screen>
>+    </sect2>
>+  </sect1>
>+
>+  <sect1 xml:id="x-compiz-fusion">
>+    <title>Installing Compiz Fusion</title>
>+
>+    <para>One way to make using a desktop
>+      computer more pleasant is with nice 3D effects.</para>
>+
>+    <para>Installing the <application>Compiz&nbsp;Fusion</application>
>+      package is easy, but configuring it requires a few steps that
>+      are not described in the port's documentation.</para>
>+
>+    <sect2 xml:id="x-compiz-video-card">
>+      <title>Setting up the &os; nVidia Driver</title>
>+
>+      <para>Desktop effects can cause quite a load on the graphics
>+	card.  For an nVidia-based graphics card, the proprietary
>+	driver is required for good performance.  Users of other
>+	graphics cards can skip this section and continue with the
>+	<filename>xorg.conf</filename> configuration.</para>
>+
>+      <para>To determine which nVidia driver is needed see the <link
>+	  xlink:href="&url.books.faq;/x.html#idp59950544">FAQ question
>+	  on the subject</link>.</para>
>+
>+      <para>Having determined the correct driver to use for your card,
>+	installation is as simple as installing any other
>+	package.</para>
>+
>+      <para>For example, to install the latest driver:</para>
>+
>+      <screen>&prompt.root; <userinput>pkg install x11/nvidia-driver</userinput></screen>
>+
>+      <para>The driver will create a kernel module, which needs to be
>+	loaded at system startup.  Add the following line to
>+	<filename>/boot/loader.conf</filename>:</para>
>+
>+      <programlisting>nvidia_load="YES"</programlisting>
>+
>+      <note>
>+	<para>To immediately load the kernel module into the running
>+	  kernel by issuing a command like <command>kldload
>+	    nvidia</command>, however it has been noted that the some
>+	  versions of <application>&xorg;</application> will not
>+	  function properly if the driver is not loaded at boot time.
>+	  After editing <filename>/boot/loader.conf</filename>, a
>+	  reboot is recommended.</para>
>+      </note>
>+
>+      <para>With the kernel module loaded, you normally only need to
>+	change a single line in <filename>xorg.conf</filename>
>+	to enable the proprietary driver:</para>
>+
>+      <para>Find the following line in
>+	<filename>/etc/X11/xorg.conf</filename>:</para>
>+
>+      <programlisting>Driver      "nv"</programlisting>
>+
>+      <para>and change it to:</para>
>+
>+      <programlisting>Driver      "nvidia"</programlisting>
>+
>+      <para>Start the GUI as usual, and you should be greeted by the
>+	nVidia splash.  Everything should work as usual.</para>
>+    </sect2>
>+
>+    <sect2 xml:id="xorg-configuration">
>+      <title>Configuring xorg.conf for Desktop Effects</title>
>+
>+      <para>To enable <application>Compiz&nbsp;Fusion</application>,
>+	<filename>/etc/X11/xorg.conf</filename> needs to be
>+	modified:</para>
>+
>+      <para>Add the following section to enable composite
>+	effects:</para>
>+
>+      <programlisting>Section "Extensions"
>+    Option         "Composite" "Enable"
>+EndSection</programlisting>
>+
>+      <para>Locate the <quote>Screen</quote> section which should look
>+	similar to the one below:</para>
>+
>+      <programlisting>Section "Screen"
>+    Identifier     "Screen0"
>+    Device         "Card0"
>+    Monitor        "Monitor0"
>+    ...</programlisting>
>+
>+      <para>and add the following two lines (after
>+	<quote>Monitor</quote> will do):</para>
>+
>+      <programlisting>DefaultDepth    24
>+Option         "AddARGBGLXVisuals" "True"</programlisting>
>+
>+      <para>Locate the <quote>Subsection</quote> that refers to the
>+	screen resolution that you wish to use.  For example, if you
>+	wish to use 1280x1024, locate the section that follows.  If
>+	the desired resolution does not appear in any subsection, you
>+	may add the relevant entry by hand:</para>
>+
>+      <programlisting>SubSection     "Display"
>+    Viewport    0 0
>+    Modes      "1280x1024"
>+EndSubSection</programlisting>
>+
>+      <para>A color depth of 24&nbsp;bits is needed for desktop
>+	composition, change the above subsection to:</para>
>+
>+      <programlisting>SubSection     "Display"
>+    Viewport    0 0
>+    Depth       24
>+    Modes      "1280x1024"
>+EndSubSection</programlisting>
>+
>+      <para>Finally, confirm that the <quote>glx</quote> and
>+	<quote>extmod</quote> modules are loaded in the
>+	<quote>Module</quote> section:</para>
>+
>+      <programlisting>Section "Module"
>+    Load           "extmod"
>+    Load           "glx"
>+    ...</programlisting>
>+
>+      <para>The preceding can be done automatically with
>+	<package>x11/nvidia-xconfig</package> by running (as
>+	root):</para>
>+
>+      <screen>&prompt.root; <userinput>nvidia-xconfig --add-argb-glx-visuals</userinput>
>+&prompt.root; <userinput>nvidia-xconfig --composite</userinput>
>+&prompt.root; <userinput>nvidia-xconfig --depth=24</userinput></screen>
>+    </sect2>
>+
>+    <sect2 xml:id="compiz-fusion">
>+      <title>Installing and Configuring Compiz&nbsp;Fusion</title>
>+
>+      <para>Installing <application>Compiz&nbsp;Fusion</application>
>+	is as simple as any other package:</para>
>+
>+      <screen>&prompt.root; <userinput>pkg install x11-wm/compiz-fusion</userinput></screen>
>+
>+      <para>When the installation is finished, start your graphic
>+	desktop and at a terminal, enter the following commands (as a
>+	normal user):</para>
>+
>+      <screen>&prompt.user; <userinput>compiz --replace --sm-disable --ignore-desktop-hints ccp &amp;</userinput>
>+&prompt.user; <userinput>emerald --replace &amp;</userinput></screen>
>+
>+      <para>Your screen will flicker for a few seconds, as your window
>+	manager (e.g. <application>Metacity</application> if you are
>+	using <application>GNOME</application>) is replaced by
>+	<application>Compiz&nbsp;Fusion</application>.
>+	<application>Emerald</application> takes care of the window
>+	decorations (i.e. close, minimize, maximize buttons, title
>+	bars and so on).</para>
>+
>+      <para>You may convert this to a trivial script and have it run
>+	at startup automatically (e.g. by adding to
>+	<quote>Sessions</quote> in a <application>GNOME</application>
>+	desktop):</para>
>+
>+      <programlisting>#! /bin/sh
>+compiz --replace --sm-disable --ignore-desktop-hints ccp &amp;
>+emerald --replace &amp;</programlisting>
>+
>+      <para>Save this in your home directory as, for example,
>+	<filename>start-compiz</filename> and make it
>+	executable:</para>
>+
>+      <screen>&prompt.user; <userinput>chmod +x ~/start-compiz</userinput></screen>
>+
>+      <para>Then use the GUI to add it to <guimenuitem>Startup
>+	  Programs</guimenuitem> (located in
>+	<guimenuitem>System</guimenuitem>,
>+	<guimenuitem>Preferences</guimenuitem>,
>+	<guimenuitem>Sessions</guimenuitem> on a
>+	<application>GNOME</application> desktop).</para>
>+
>+      <para>To actually select all the desired effects and their
>+	settings, execute (again as a normal user) the
>+	<application>Compiz&nbsp;Config&nbsp;Settings&nbsp;Manager</application>:</para>
>+
>+      <screen>&prompt.user; <userinput>ccsm</userinput></screen>
>+
>+      <note>
>+	<para>In <application>GNOME</application>, this can also be
>+	  found in the <guimenuitem>System</guimenuitem>,
>+	  <guimenuitem>Preferences</guimenuitem> menu.</para>
>+      </note>
>+
>+      <para>If you have selected <quote>gconf support</quote> during
>+	the build, you will also be able to view these settings using
>+	<command>gconf-editor</command> under
>+	<literal>apps/compiz</literal>.</para>
>+    </sect2>
>+  </sect1>
>+
>+  <sect1 xml:id="x11-understanding">
>+
>+    <title>Troubleshooting</title>
>+
>+    <para>If the mouse does not work, you will need to first configure
>+      it before proceeding.
>+      In recent <application>Xorg</application>
>+      versions, the <literal>InputDevice</literal> sections in
>+      <filename>xorg.conf</filename> are ignored in favor of the
>+      autodetected devices.  To restore the old behavior, add the
>+      following line to the <literal>ServerLayout</literal> or
>+      <literal>ServerFlags</literal> section of this file:</para>
>+
>+      <programlisting>Option "AutoAddDevices" "false"</programlisting>
>+
>+      <para>Input devices may then be configured as in previous
>+	versions, along with any other options needed (e.g., keyboard
>+	layout switching).</para>
>+
>+      <note>
>+	<para>As previously explained the
>+	  <application>hald</application> daemon will, by default,
>+	  automatically detect your keyboard.  There are chances that
>+	  your keyboard layout or model will not be correct, desktop
>+	  environments like <application>GNOME</application>,
>+	  <application>KDE</application> or
>+	  <application>Xfce</application> provide tools to configure
>+	  the keyboard.  However, it is possible to set the keyboard
>+	  properties directly either with the help of the
>+	  &man.setxkbmap.1; utility or with a
>+	  <application>hald</application>'s configuration rule.</para>
>+
>+	<para>For example if, one wants to use a PC 102 keys keyboard
>+	  coming with a french layout, we have to create a keyboard
>+	  configuration file for <application>hald</application>
>+	  called <filename>x11-input.fdi</filename> and saved in the
>+	  <filename>/usr/local/etc/hal/fdi/policy</filename>
>+	  directory.  This file should contain the following
>+	  lines:</para>
>+
>+	<programlisting>&lt;?xml version="1.0" encoding="iso-8859-1"?&gt;
>+&lt;deviceinfo version="0.2"&gt;
>+  &lt;device&gt;
>+    &lt;match key="info.capabilities" contains="input.keyboard"&gt;
>+	  &lt;merge key="input.x11_options.XkbModel" type="string"&gt;pc102&lt;/merge&gt;
>+	  &lt;merge key="input.x11_options.XkbLayout" type="string"&gt;fr&lt;/merge&gt;
>+    &lt;/match&gt;
>+  &lt;/device&gt;
>+&lt;/deviceinfo&gt;</programlisting>
>+
>+	<para>If this file already exists, just copy and add to your
>+	  file the lines regarding the keyboard configuration.</para>
>+
>+	<para>You will have to reboot your machine to force
>+	  <application>hald</application> to read this file.</para>
>+
>+	<para>It is possible to do the same configuration from an X
>+	  terminal or a script with this command line:</para>
>+
>+	<screen>&prompt.user; <userinput>setxkbmap -model pc102 -layout fr</userinput></screen>
>+
>+	<para><filename>/usr/local/share/X11/xkb/rules/base.lst</filename>
>+	  lists the various keyboard, layouts and options
>+	  available.</para>
>+      </note>
>+
>+      <indexterm><primary><application>&xorg;</application>
>+	  tuning</primary></indexterm>
>+
>+      <para>The <filename>xorg.conf.new</filename> configuration file
>+	may now be tuned to taste.  Open the file in a text editor
>+	such as &man.emacs.1; or &man.ee.1;.  If the monitor is an
>+	older or unusual model that does not support autodetection of
>+	sync frequencies, those settings can be added to
>+	<filename>xorg.conf.new</filename> under the
>+	<literal>"Monitor"</literal> section:</para>
>+
>+      <programlisting>Section "Monitor"
>+	Identifier   "Monitor0"
>+	VendorName   "Monitor Vendor"
>+	ModelName    "Monitor Model"
>+	HorizSync    30-107
>+	VertRefresh  48-120
>+EndSection</programlisting>
>+
>+      <para>Most monitors support sync frequency autodetection, making
>+	manual entry of these values unnecessary.  For the few
>+	monitors that do not support autodetection, avoid potential
>+	damage by only entering values provided by the
>+	manufacturer.</para>
>+
>+      <para>X allows DPMS (Energy Star) features to be used with
>+	capable monitors.  The &man.xset.1; program controls the
>+	time-outs and can force standby, suspend, or off modes.  If
>+	you wish to enable DPMS features for your monitor, you must
>+	add the following line to the monitor section:</para>
>+
>+      <programlisting>Option       "DPMS"</programlisting>
>+
>+      <indexterm>
>+	<primary><filename>xorg.conf</filename></primary>
>+      </indexterm>
>+
>+      <para>While the <filename>xorg.conf.new</filename> configuration
>+	file is still open in an editor, select the default resolution
>+	and color depth desired.  This is defined in the
>+	<literal>"Screen"</literal> section:</para>
>+
>+      <programlisting>Section "Screen"
>+	Identifier "Screen0"
>+	Device     "Card0"
>+	Monitor    "Monitor0"
>+	DefaultDepth 24
>+	SubSection "Display"
>+		Viewport  0 0
>+		Depth     24
>+		Modes     "1024x768"
>+	EndSubSection
>+EndSection</programlisting>
>+
>+      <para>The <literal>DefaultDepth</literal> keyword describes the
>+	color depth to run at by default.  This can be overridden with
>+	the <option>-depth</option> command line switch to
>+	&man.Xorg.1;.  The <literal>Modes</literal> keyword describes
>+	the resolution to run at for the given color depth.  Note that
>+	only VESA standard modes are supported as defined by the
>+	target system's graphics hardware.  In the example above, the
>+	default color depth is twenty-four bits per pixel.  At this
>+	color depth, the accepted resolution is 1024 by 768
>+	pixels.</para>
>+
>+      <para>Finally, write the configuration file and test it using
>+	the test mode given above.</para>
>+
>+      <note>
>+	<para>One of the tools available to assist you during
>+	  troubleshooting process are the
>+	  <application>&xorg;</application> log files, which contain
>+	  information on each device that the
>+	  <application>&xorg;</application> server attaches to.
>+	  <application>&xorg;</application> log file names are in the
>+	  format of <filename>/var/log/Xorg.0.log</filename>.  The
>+	  exact name of the log can vary from
>+	  <filename>Xorg.0.log</filename> to
>+	  <filename>Xorg.8.log</filename> and so forth.</para>
>+      </note>
>+
>+      <para>If all is well, the configuration file needs to be
>+	installed in a common location where &man.Xorg.1; can find it.
>+	This is typically <filename>/etc/X11/xorg.conf</filename> or
>+	<filename>/usr/local/etc/X11/xorg.conf</filename>.</para>
>+
>+      <screen>&prompt.root; <userinput>cp xorg.conf.new /etc/X11/xorg.conf</userinput></screen>
>+
>+      <para>The <application>&xorg;</application> configuration
>+	process is now complete.  <application>&xorg;</application>
>+	may be now started with the &man.startx.1; utility.  The
>+	<application>&xorg;</application> server may also be started
>+	with the use of &man.xdm.1;.</para>
>+
>+      <sect2>
>+	<title>Configuration with &intel; <literal>i810</literal>
>+	  Graphics Chipsets</title>
>+
>+	<indexterm>
>+	  <primary>Intel i810 graphic chipset</primary>
>+	</indexterm>
>+
>+	<para>Configuration with &intel; i810 integrated chipsets
>+	  requires the <filename>agpgart</filename> AGP programming
>+	  interface for <application>&xorg;</application> to drive the
>+	  card.  See the &man.agp.4; driver manual page for more
>+	  information.</para>
>+
>+	<para>This will allow configuration of the hardware as any
>+	  other graphics board.  Note on systems without the
>+	  &man.agp.4; driver compiled in the kernel, trying to load
>+	  the module with &man.kldload.8; will not work.  This driver
>+	  has to be in the kernel at boot time through being compiled
>+	  in or using <filename>/boot/loader.conf</filename>.</para>
>+      </sect2>
>+
>+      <sect2>
>+	<title>Adding a Widescreen Flatpanel to the Mix</title>
>+
>+	<indexterm>
>+	  <primary>widescreen flatpanel configuration</primary>
>+	</indexterm>
>+
>+	<para>This section assumes a bit of advanced configuration
>+	  knowledge.  If attempts to use the standard configuration
>+	  tools above have not resulted in a working configuration,
>+	  there is information enough in the log files to be of use in
>+	  getting the setup working.  Use of a text editor will be
>+	  necessary.</para>
>+
>+	<para>Current widescreen (WSXGA, WSXGA+, WUXGA, WXGA, WXGA+,
>+	  et.al.) formats support 16:10 and 10:9 formats or aspect
>+	  ratios that can be problematic.  Examples of some common
>+	  screen resolutions for 16:10 aspect ratios are:</para>
>+
>+	<itemizedlist>
>+	  <listitem>
>+	    <para>2560x1600</para>
>+	  </listitem>
>+
>+	  <listitem>
>+	    <para>1920x1200</para>
>+	  </listitem>
>+
>+	  <listitem>
>+	    <para>1680x1050</para>
>+	  </listitem>
>+
>+	  <listitem>
>+	    <para>1440x900</para>
>+	  </listitem>
>+
>+	  <listitem>
>+	    <para>1280x800</para>
>+	  </listitem>
>+	</itemizedlist>
>+
>+	<para>At some point, it will be as easy as adding one of these
>+	  resolutions as a possible <literal>Mode</literal> in the
>+	  <literal>Section "Screen"</literal> as such:</para>
>+
>+	<programlisting>Section "Screen"
>+Identifier "Screen0"
>+Device     "Card0"
>+Monitor    "Monitor0"
>+DefaultDepth 24
>+SubSection "Display"
>+	Viewport  0 0
>+	Depth     24
>+	Modes     "1680x1050"
>+EndSubSection
>+EndSection</programlisting>
>+
>+	<para><application>&xorg;</application> is smart enough to
>+	  pull the resolution information from the widescreen via
>+	  I2C/DDC information so it knows what the monitor can handle
>+	  as far as frequencies and resolutions.</para>
>+
>+	<para>If those <literal>ModeLines</literal> do not exist in
>+	  the drivers, one might need to give
>+	  <application>&xorg;</application> a little hint.  Using
>+	  <filename>/var/log/Xorg.0.log</filename> one can extract
>+	  enough information to manually create a
>+	  <literal>ModeLine</literal> that will work.  Simply look for
>+	  information resembling this:</para>
>+
>+	<programlisting>(II) MGA(0): Supported additional Video Mode:
>+(II) MGA(0): clock: 146.2 MHz   Image Size:  433 x 271 mm
>+(II) MGA(0): h_active: 1680  h_sync: 1784  h_sync_end 1960 h_blank_end 2240 h_border: 0
>+(II) MGA(0): v_active: 1050  v_sync: 1053  v_sync_end 1059 v_blanking: 1089 v_border: 0
>+(II) MGA(0): Ranges: V min: 48  V max: 85 Hz, H min: 30  H max: 94 kHz, PixClock max 170 MHz</programlisting>
>+
>+	<para>This information is called EDID information.  Creating a
>+	  <literal>ModeLine</literal> from this is just a matter of
>+	  putting the numbers in the correct order:</para>
>+
>+	<programlisting>ModeLine &lt;name&gt; &lt;clock&gt; &lt;4 horiz. timings&gt; &lt;4 vert. timings&gt;</programlisting>
>+
>+	<para>So that the <literal>ModeLine</literal> in
>+	  <literal>Section "Monitor"</literal> for this example would
>+	  look like this:</para>
>+
>+	<programlisting>Section "Monitor"
>+Identifier      "Monitor1"
>+VendorName      "Bigname"
>+ModelName       "BestModel"
>+ModeLine        "1680x1050" 146.2 1680 1784 1960 2240 1050 1053 1059 1089
>+Option          "DPMS"
>+EndSection</programlisting>
>+
>+	<para>Now having completed these simple editing steps, X
>+	  should start on your new widescreen monitor.</para>
>+      </sect2>
>+
>+      <sect2 xml:id="compiz-troubleshooting">
>+	<title>Troubleshooting Compiz&nbsp;Fusion</title>
>+
>+	<qandaset>
>+	  <qandaentry>
>+	    <question xml:id="no-decorations">
>+	      <para>I have installed
>+		<application>Compiz&nbsp;Fusion</application>, and
>+		after running the commands you mention, my windows are
>+		left without title bars and buttons.  What is
>+		wrong?</para>
>+	    </question>
>+
>+	    <answer>
>+	      <para>You are probably missing a setting in
>+		<filename>/etc/X11/xorg.conf</filename>.  Review this
>+		file carefully and check especially the
>+		<literal>DefaultDepth</literal> and
>+		<literal>AddARGBGLXVisuals</literal>
>+		directives.</para>
>+	    </answer>
>+	  </qandaentry>
>+
>+	  <qandaentry>
>+	    <question xml:id="xorg-crash">
>+	      <para>When I run the command to start
>+		<application>Compiz&nbsp;Fusion</application>, the X
>+		server crashes and I am back at the console.  What is
>+		wrong?</para>
>+	    </question>
>+
>+	    <answer>
>+	      <para>If you check
>+		<filename>/var/log/Xorg.0.log</filename>, you
>+		will probably find error messages during the X
>+		startup.  The most common would be:</para>
>+
>+	      <screen>(EE) NVIDIA(0):     Failed to initialize the GLX module; please check in your X
>+(EE) NVIDIA(0):     log file that the GLX module has been loaded in your X
>+(EE) NVIDIA(0):     server, and that the module is the NVIDIA GLX module.  If
>+(EE) NVIDIA(0):     you continue to encounter problems, Please try
>+(EE) NVIDIA(0):     reinstalling the NVIDIA driver.</screen>
>+
>+	    <para>This is usually the case when you upgrade
>+	      <application>&xorg;</application>.  You will need to
>+	      reinstall the <package>x11/nvidia-driver</package>
>+	      package so glx is built again.</para>
>+	  </answer>
>+	</qandaentry>
>+      </qandaset>
>+    </sect2>
>+  </sect1>
>+</chapter>

Actions: View | Diff

Attachments on bug 207347: 167191