aboutsummaryrefslogtreecommitdiff
path: root/en_US.ISO8859-1/books/handbook/x11
diff options
context:
space:
mode:
authorWarren Block <wblock@FreeBSD.org>2015-10-15 19:02:39 +0000
committerWarren Block <wblock@FreeBSD.org>2015-10-15 19:02:39 +0000
commitcd6e9ff5025236f6641d36a0cb3a7ba30fe6f03d (patch)
treeec98d70a836f494e29ae94b2c1e1d6970c194558 /en_US.ISO8859-1/books/handbook/x11
parent493099edb4cf9263cfc748ff03b474e25374c04c (diff)
downloaddoc-cd6e9ff5025236f6641d36a0cb3a7ba30fe6f03d.tar.gz
doc-cd6e9ff5025236f6641d36a0cb3a7ba30fe6f03d.zip
Rewrite the X configuration section to better suit current conditions.
Reviewed by: #freebsd-xorg on IRC (some slightly earlier versions)
Notes
Notes: svn path=/head/; revision=47566
Diffstat (limited to 'en_US.ISO8859-1/books/handbook/x11')
-rw-r--r--en_US.ISO8859-1/books/handbook/x11/chapter.xml633
1 files changed, 506 insertions, 127 deletions
diff --git a/en_US.ISO8859-1/books/handbook/x11/chapter.xml b/en_US.ISO8859-1/books/handbook/x11/chapter.xml
index a3fbcd74b4..ef5640de91 100644
--- a/en_US.ISO8859-1/books/handbook/x11/chapter.xml
+++ b/en_US.ISO8859-1/books/handbook/x11/chapter.xml
@@ -93,7 +93,7 @@
<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>
+ useful.</para>
<variablelist>
<varlistentry>
@@ -237,161 +237,540 @@
<sect1 xml:id="x-install">
<title>Installing <application>&xorg;</application></title>
- <para><application>&xorg;</application> is the implementation of
- the open source X Window System released by the X.Org
- Foundation. In &os;, it can be installed as a package or port.
- The meta-port for the complete distribution which includes X
- servers, clients, libraries, and fonts is located in
- <package>x11/xorg</package>. A minimal distribution is located
- in <package>x11/xorg-minimal</package>, with separate ports
- available for docs, libraries, and apps. The examples in this
- section install the complete <application>&xorg;</application>
- distribution.</para>
+ <para>On &os;, <application>&xorg;</application> can be installed
+ as a package or port.</para>
- <para>To build and install <application>&xorg;</application> from
- the Ports Collection:</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>
- <note>
- <para>To build <application>&xorg;</application> in its
- entirety, be sure to have at least 4&nbsp;GB of free disk
- space available.</para>
- </note>
-
- <para>Alternatively, <application>&xorg;</application> can be
- installed directly from packages with this command:</para>
+ <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">
- <!--
- <sect1info>
- <authorgroup>
- <author>
- <firstname>Christopher</firstname>
- <surname>Shumway</surname>
- <contrib>Contributed in July 2001 by</contrib>
- </author>
- </authorgroup>
- </sect1info>
- -->
<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>
- <para>In most cases, <application>&xorg;</application> is
- self-configuring. Autoconfiguration is the preferred method,
- and should be tried first. When X is started without a
- configuration file, the video card and input devices are
- automatically detected and used. If the system already has a
- configuration file and you wish to create a new configuration,
- save a copy of the old one first:</para>
+ <sect2 xml:id="x-config-quick-start">
+ <title>Quick Start</title>
- <screen>&prompt.root; <userinput>mv /etc/X11/xorg.conf ~/xorg.conf.etc</userinput>
+ <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>
- <para>To generate the configuration file and start the X system,
- issue this command:</para>
+ <sect2 xml:id="x-config-user-group">
+ <title>User Group for Accelerated Video</title>
- <screen>&prompt.user; <userinput>startx</userinput></screen>
+ <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>
- <para>If a black and grey grid and an X mouse cursor appear, the
- configuration was successful. Test the system by moving the
- mouse and typing text into the windows. To exit the test,
- switch to the virtual console used to start it by pressing
- <keycombo action="simul"> <keycap>Ctrl</keycap>
- <keycap>Alt</keycap>
- <keycap>F<replaceable>n</replaceable></keycap> </keycombo>
- (<keycap>F1</keycap> for the first virtual console) and press
- <keycombo action="simul"> <keycap>Ctrl</keycap>
- <keycap>C</keycap> </keycombo>.</para>
+ <screen>&prompt.root; <userinput>pw groupmod video -m <replaceable>slurms</replaceable> || pw groupmod wheel -m <replaceable>slurms</replaceable></userinput></screen>
+ </sect2>
- <para>If the mouse or keyboard do not work, continue with <xref
- linkend="x11-understanding"/>.</para>
+ <sect2 xml:id="x-config-kms">
+ <title>Kernel Mode Setting (<acronym>KMS</acronym>)</title>
- <para>Desktop environments like <application>GNOME</application>,
- <application>KDE</application> or
- <application>Xfce</application> provide graphical tools to set
- parameters such as video resolution. If the default
- configuration works, skip to <xref linkend="x11-wm"/> for
- examples on how to install a desktop environment.</para>
+ <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>
- <note>
- <para>The <keycombo action="simul">
- <keycap>Ctrl</keycap>
- <keycap>Alt</keycap>
- <keycap>Backspace</keycap>
- </keycombo> key combination may also be used to break out of
- <application>&xorg;</application>. To enable it, you can
- either type the following command from any X terminal
- emulator:</para>
-
- <screen>&prompt.user; <userinput>setxkbmap -option terminate:ctrl_alt_bksp</userinput></screen>
-
- <para>or 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.XkbOptions" type="string"&gt;terminate:ctrl_alt_bksp&lt;/merge&gt;
- &lt;/match&gt;
- &lt;/device&gt;
-&lt;/deviceinfo&gt;</programlisting>
+ <para>Add this line to <filename>/boot/loader.conf</filename>
+ to enable &man.vt.4;:</para>
- <para>The following line will also have to be added to
- <filename>xorg.conf.new</filename>, in the
- <literal>ServerLayout</literal> or
- <literal>ServerFlags</literal> section:</para>
+ <programlisting>kern.vty=vt</programlisting>
+ </sect2>
- <programlisting>Option "DontZap" "off"</programlisting>
- </note>
+ <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>
- <title>Caveats</title>
+ <sect2 xml:id="x-config-video-cards">
+ <title>Video Cards</title>
- <para>The ability to configure optimal resolution is dependent
- upon the video hardware and the support provided by its
- driver. At this time, driver support includes:</para>
+ <variablelist>
+ <varlistentry xml:id="x-config-video-cards-intel">
+ <term>&intel;</term>
- <itemizedlist>
- <listitem>
- <para>Intel: as of &os;&nbsp;9.3 and &os;&nbsp;10.1, 3D
- acceleration on most Intel graphics, including IronLake,
- SandyBridge, and IvyBridge, is supported. Support for
- switching between X and virtual consoles is provided by
- &man.vt.4;.</para>
- </listitem>
+ <listitem>
+ <para>3D acceleration is supported on most &intel;
+ graphics, including IronLake, SandyBridge, and
+ IvyBridge.</para>
+ </listitem>
+ </varlistentry>
- <listitem>
- <para>ATI/Radeon: 2D and 3D acceleration is supported on
- most Radeon cards up to the HD6000 series.</para>
- </listitem>
+ <varlistentry xml:id="x-config-video-cards-radeon">
+ <term>&amd; Radeon</term>
- <listitem>
- <para>NVIDIA: several NVIDIA drivers are available in the
- <filename>x11</filename> category of the Ports Collection.
- Install the driver that matches the video card.</para>
- </listitem>
+ <listitem>
+ <para>2D and 3D acceleration is supported on Radeon
+ cards up to and including the HD6000 series.</para>
+ </listitem>
+ </varlistentry>
- <listitem>
- <para>Optimus: currently there is no switching support
- between the two graphics adapters provided by Optimus.
- Optimus implementations vary, and &os; will not be able to
- drive all versions of the hardware. Some computers
- provide a <acronym>BIOS</acronym> option to disable one of
- the graphics adapters or select a
- <emphasis>discrete</emphasis> mode.</para>
- </listitem>
- </itemizedlist>
+ <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>
+ </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 &intel; 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.</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>
+ </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>
+
+ <programlisting>Section "Screen"
+ Identifier "Screen0"
+ Device "Card0"
+ SubSection "Display"
+ Modes "1024x768"
+ EndSubSection
+EndSection</programlisting>
+
+ <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 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>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry xml:id="x-config-input-keyboard-zap">
+ <term>Closing <application>&xorg;</application> From the
+ Keyboard</term>
+
+ <listitem>
+ <para>A combination of keys is available to close the X
+ system. This option is disabled by default because it
+ conflicts with keyboard commands for some
+ applications. Enabling this option requires changes
+ to both <literal>ServerLayout</literal> and keyboard
+ <literal>InputDevice</literal> sections:</para>
+
+ <example>
+ <title>Enabling Keyboard Exit from X</title>
+
+ <para><filename>/usr/local/etc/X11/xorg.conf.d/serverlayout-enablezap.conf</filename></para>
+
+ <programlisting>Section "ServerLayout"
+ Identifier "EnableZap"
+ Option "DontZap" "Off"
+EndSection</programlisting>
+
+ <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>
@@ -924,7 +1303,7 @@ DisplayManager.requestPort: 0</screen>
<para>This desktop environment can be installed from a
package:</para>
- <screen>&prompt.root; <userinput>pkg install gnome3</userinput></screen>
+ <screen>&prompt.root; <userinput>pkg install gnome2</userinput></screen>
<para>To instead build <application>GNOME</application> from
ports, use the following command.
@@ -932,7 +1311,7 @@ DisplayManager.requestPort: 0</screen>
will take some time to compile, even on a fast
computer.</para>
- <screen>&prompt.root; <userinput>cd /usr/ports/x11/gnome3</userinput>
+ <screen>&prompt.root; <userinput>cd /usr/ports/x11/gnome2</userinput>
&prompt.root; <userinput>make install clean</userinput></screen>
<para>For proper operation, <application>GNOME</application>