diff options
Diffstat (limited to 'src-qt5')
| -rw-r--r-- | src-qt5/desktop-utils/lumina-textedit/tests/test.xml | 2170 |
1 files changed, 2170 insertions, 0 deletions
diff --git a/src-qt5/desktop-utils/lumina-textedit/tests/test.xml b/src-qt5/desktop-utils/lumina-textedit/tests/test.xml new file mode 100644 index 00000000..629d82db --- /dev/null +++ b/src-qt5/desktop-utils/lumina-textedit/tests/test.xml @@ -0,0 +1,2170 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!-- + The FreeBSD Documentation Project + + $FreeBSD$ +--> +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" + xml:id="x11"> + <!-- + <chapterinfo> + <authorgroup> + <author> + <firstname>Ken</firstname> + <surname>Tom</surname> + <contrib>Updated for X.Org's X11 server by </contrib> + </author> + <author> + <firstname>Marc</firstname> + <surname>Fonvieille</surname> + </author> + </authorgroup> + </chapterinfo> + --> + + <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.trueos.org/" /> + 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://www.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>The binary package can be installed quickly but with + fewer options for customization:</para> + + <screen>&prompt.root; <userinput>pkg install xorg</userinput></screen> + + <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>Either of these installations results in the complete + <application>&xorg;</application> system being installed. Binary packages + are 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.</para> + + <tip> + <para>Video cards, monitors, and input devices are + automatically detected and do not require any manual + configuration. Do not create <filename>xorg.conf</filename> + or run a <option>-configure</option> step unless automatic + configuration fails.</para> + </tip> + + <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> + + <para>Manual configuration is usually not necessary. Please do + not manually create configuration files unless + autoconfiguration does not work.</para> + + <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> + + <para>To set the <literal>scfb</literal> driver for use + with a <acronym>UEFI</acronym> or &arm; computer:</para> + + <example xml:id="x-config-video-cards-file-scfb"> + <title>Select <literal>scfb</literal> Video Driver in a + File</title> + + <para><filename>/usr/local/etc/X11/xorg.conf.d/driver-scfb.conf</filename></para> + + <programlisting>Section "Device" + Identifier "Card0" + Driver "scfb" +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>The type and quantity of output connectors varies + between devices, and the name given to each output + varies from driver to driver. What one driver calls + <literal>HDMI-1</literal>, another might call + <literal>HDMI1</literal>. So the first step is to run + &man.xrandr.1; to list all the available + 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> + + <warning> + <para>Do not create manual configuration files unless + required. Unnecessary manual configuration can prevent + proper operation.</para> + </warning> + + <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"> + <!-- + <sect1info> + <authorgroup> + <author> + <firstname>Murray</firstname> + <surname>Stokely</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + </sect1info> + --> + <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 binary packages, + run the following commands:</para> + + <screen>&prompt.root; <userinput>pkg install urwfonts</userinput></screen> + + <para>Alternatively, to build 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>Apache 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"> + <!-- + <sect2info> + <authorgroup> + <author> + <firstname>Joe Marcus</firstname> + <surname>Clarke</surname> + <contrib>Updated in May 2003 by</contrib> + </author> + </authorgroup> + </sect2info> + --> + <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>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><fontconfig></literal> + tag:</para> + + <programlisting><?xml version="1.0"?> + <!DOCTYPE fontconfig SYSTEM "fonts.dtd"> + <fontconfig></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. To add another directory + outside of these two directory trees, add a line like + this to + <filename>/usr/local/etc/fonts/local.conf</filename>:</para> + + <programlisting><dir>/path/to/my/fonts</dir></programlisting> + + <para>After adding new fonts, and especially new font + directories, 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> <match target="font"> + <test name="size" compare="less"> + <double>14</double> + </test> + <edit name="antialias" mode="assign"> + <bool>false</bool> + </edit> + </match> + <match target="font"> + <test name="pixelsize" compare="less" qual="any"> + <double>14</double> + </test> + <edit mode="assign" name="antialias"> + <bool>false</bool> + </edit> + </match></programlisting> + + <indexterm> + <primary>fonts</primary> + <secondary>spacing</secondary> + </indexterm> + + <para>Spacing for some monospaced fonts might also be + inappropriate with anti-aliasing. This seems to be an issue + with <application>KDE</application>, in particular. One + possible fix is to force the spacing for such fonts + to be 100. Add these lines:</para> + + <programlisting> <match target="pattern" name="family"> + <test qual="any" name="family"> + <string>fixed</string> + </test> + <edit name="family" mode="assign"> + <string>mono</string> + </edit> + </match> + <match target="pattern" name="family"> + <test qual="any" name="family"> + <string>console</string> + </test> + <edit name="family" mode="assign"> + <string>mono</string> + </edit> + </match></programlisting> + + <para>(this aliases the other common names for fixed fonts as + <literal>"mono"</literal>), and then add:</para> + + <programlisting> <match target="pattern" name="family"> + <test qual="any" name="family"> + <string>mono</string> + </test> + <edit name="spacing" mode="assign"> + <int>100</int> + </edit> + </match> </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> <match target="pattern" name="family"> + <test qual="any" name="family"> + <string>Helvetica</string> + </test> + <edit name="family" mode="assign"> + <string>sans-serif</string> + </edit> + </match> </programlisting> + + <para>After editing + <filename>local.conf</filename>, make certain to end the file + with the <literal></fontconfig></literal> tag. Not + doing this will cause changes to be ignored.</para> + + <para>Users can add personalized settings by creating their own + <filename>~/.config/fontconfig/fonts.conf</filename>. This + file uses the same <acronym>XML</acronym> format described + above.</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> <match target="font"> + <test qual="all" name="rgba"> + <const>unknown</const> + </test> + <edit name="rgba" mode="assign"> + <const>rgb</const> + </edit> + </match></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> + <!-- in June 2001 --> + </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 gnome3</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/gnome3</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" > ~/.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" > ~/.xsession</userinput> +&prompt.user; <userinput>echo "exec /usr/local/bin/gnome-session" >> ~/.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><application>KDE</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>KDE</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>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" > ~/.xsession</userinput> +&prompt.user; <userinput>echo "exec /usr/local/bin/startkde" >> ~/.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" > ~/.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" > ~/.xsession</userinput> +&prompt.user; <userinput>echo "exec /usr/local/bin/startxfce4 --with-ck-launch" >> ~/.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 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 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 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 Fusion</title> + + <para>Installing <application>Compiz 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 &</userinput> +&prompt.user; <userinput>emerald --replace &</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 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 & +emerald --replace &</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 Config Settings 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><?xml version="1.0" encoding="iso-8859-1"?> +<deviceinfo version="0.2"> + <device> + <match key="info.capabilities" contains="input.keyboard"> + <merge key="input.x11_options.XkbModel" type="string">pc102</merge> + <merge key="input.x11_options.XkbLayout" type="string">fr</merge> + </match> + </device> +</deviceinfo></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 <name> <clock> <4 horiz. timings> <4 vert. timings></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 Fusion</title> + + <qandaset> + <qandaentry> + <question xml:id="no-decorations"> + <para>I have installed + <application>Compiz 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 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> |