source: x/installing/x-setup.xml@ d9c80e1

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
   "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;
]>

<sect1 id="x-setup">
  <?dbhtml filename="xfree86-setup.html"?>

  <sect1info>
  <othername>$LastChangedBy$</othername>
  <date>$Date$</date>
  </sect1info>

  <title>X Window System Components</title>

  <sect2 id='dri'>
    <title>Checking Direct Rendering Infrastructure (DRI) Installation</title>

    <indexterm zone="x-setup dri">
      <primary sortas="g-DRI">DRI</primary>
    </indexterm>

    <para>DRI is a framework for allowing software to access graphics hardware
    in a safe and efficient manner. It is installed in
    <application>X</application> by default if you have a supported video card.
    To check if DRI is installed properly, check the log file
    <filename>/var/log/XFree86.0.log</filename> or
    <filename>/var/log/Xorg.0.log</filename> for statements like:</para>

<screen><literal>(II) R128(0): Direct rendering enabled</literal></screen>

    <para>From an <command>xterm</command>, run <command>glxinfo</command>
    and look for the phrase:</para>

<screen><computeroutput>direct rendering: Yes</computeroutput></screen>

    <para>You can also run the test program <command>glxgears</command>.
    This program brings up a window with three gears turning.  The
    <command>xterm</command> will display how many frames were drawn every
    five seconds, so this is a reasonable benchmark.  The window is scalable,
    and the frames drawn per second is highly dependent on the size of
    the window.</para>

    <indexterm zone="x-setup dri">
      <primary sortas="b-glxgears">glxgears</primary>
    </indexterm>

    <indexterm zone="x-setup dri">
      <primary sortas="b-glxinfo">glxinfo</primary>
    </indexterm>

    <para>For troubleshooting problems, check the DRI Users Guide at
    <ulink url="http://dri.sourceforge.net/doc/DRIuserguide.html"/>.</para>

  </sect2>

<!-- ================================================== -->

  <sect2 id='fonts'>
    <title>Adding TrueType Fonts to X</title>

    <para><application>TrueType</application> font support is built into
    <application>X</application>. The following items need to be
    completed to make the fonts available. Each item is described in
    detail after the list.</para>

    <indexterm zone="x-setup fonts">
      <primary sortas="g-truetype">TrueType</primary>
    </indexterm>

    <itemizedlist>
      <listitem>
        <para>Establish a directory for the fonts and move any
        <application>TrueType</application> fonts you want into that
        directory. Ensure that any fonts you install are world readable.
        Incorrect permissions on fonts have been known to cause problems
        with some <application>X</application> applications.</para>
      </listitem>
      <listitem>
        <para>Download the fonts.</para>
      </listitem>
      <listitem>
        <para>Create the <filename>fonts.scale</filename> and
        <filename>fonts.dir</filename> files in the
        <application>TrueType</application> font directory.</para>
      </listitem>
      <listitem>
        <para>Ensure the <application>TrueType</application> module is
        loaded in the <filename>XF86Config</filename> or
        <filename>xorg.conf</filename>.</para>
      </listitem>
      <listitem>
        <para>Update the font cache files</para>
      </listitem>
    </itemizedlist>

    <indexterm zone="x-setup fonts">
      <primary sortas="e-etc-X11-xorg-conf">/etc/X11/xorg.conf</primary>
    </indexterm>

    <indexterm zone="x-setup fonts">
      <primary sortas="e-etc-X11-XF86Config">/etc/X11/XF86Config</primary>
    </indexterm>

    <sect3>
      <title>Establish a TrueType Font Directory</title>

      <para>The build of <application>X</application> as given above
      automatically creates a <application>TrueType</application> font
      directory: <filename
      class="directory">/usr/share/fonts/TTF</filename>. This
      directory already has some <application>TrueType</application>
      fonts and is set up correctly. If this directory is satisfactory,
      copy any other <application>TrueType</application> fonts you want
      into that directory. If not, create a new directory, preferably
      in the <filename
      class="directory">/usr/share/fonts/</filename> directory
      and put your <application>TrueType</application> fonts there.</para>

    </sect3>

    <sect3>
      <title>Download the Fonts</title>

      <para>There are two known high quality free font resources:
      <ulink url="ftp://ftp.gnu.org/savannah/files/freefont/"/> and
      <ulink url="http://corefonts.sourceforge.net/"/>. Copy the fonts
      (files with the <filename>.ttf</filename> suffix) to the directory
      you've just created.</para>

    </sect3>

    <sect3 id="fonts-scale-dir">
      <title>Create 'fonts.scale' and 'fonts.dir'</title>

      <indexterm zone="x-setup fonts-scale-dir">
        <primary sortas="g-fonts.scale">fonts.scale</primary>
      </indexterm>

      <indexterm zone="x-setup fonts-scale-dir">
        <primary sortas="g-fonts.dir">fonts.dir</primary>
      </indexterm>

      <para>Now change to the directory where you have your
      <application>TrueType</application> fonts and run:</para>

<screen role="root"><userinput>mkfontscale &amp;&amp;
mkfontdir</userinput></screen>

      <indexterm zone="x-setup fonts-scale-dir">
        <primary sortas="b-mkfontscale">mkfontscale</primary>
      </indexterm>

      <indexterm zone="x-setup fonts-scale-dir">
        <primary sortas="b-mkfontdir">mkfontdir</primary>
      </indexterm>

    </sect3>

    <sect3>
      <title>Ensure TrueType is Loaded in 'XF86Config' or 'xorg.conf'</title>

      <para>The "Module" section should look like:</para>

<screen><literal>Section "Module"
    ...
    Load  "freetype"
    ...
EndSection</literal></screen>

    </sect3>

    <sect3>
      <title>Update the Font Cache Files</title>

      <para>If you decided not to install X windows fonts into
      <filename class='directory'>/usr/share/fonts</filename>, then
      ensure you have the following directory entries in
      <filename>/etc/fonts/local.conf</filename>, inside the &lt;fontconfig&gt;
      tags. Create <filename>/etc/fonts/local.conf</filename> using the
      following commands:</para>

      <indexterm zone="x-setup fonts">
        <primary sortas="e-etc-fonts-local.conf">/etc/fonts/local.conf</primary>
      </indexterm>

<screen role="root"><userinput>cat &gt; /etc/fonts/local.conf &lt;&lt; "EOF"
<literal>&lt;?xml version="1.0"?&gt;
&lt;!DOCTYPE fontconfig SYSTEM "fonts.dtd"&gt;
&lt;!-- /etc/fonts/local.conf file for local customizations --&gt;

&lt;fontconfig&gt;
&lt;dir&gt;/usr/X11R6/lib/X11/fonts/TTF&lt;/dir&gt;
&lt;dir&gt;/usr/X11R6/lib/X11/fonts/Type1&lt;/dir&gt;
&lt;/fontconfig&gt;</literal>

EOF</userinput></screen>


<!--
<screen><userinput><command>sed -i -e '/^&lt;\/fontconfig&gt;/i\
&lt;dir&gt;/usr/X11R6/lib/X11/fonts/TTF&lt;/dir&gt;\
&lt;dir&gt;/usr/X11R6/lib/X11/fonts/Type1&lt;/dir&gt;' /etc/fonts/local.conf</command></userinput></screen>
 -->

      <para>The <command>fc-cache</command> program will automatically
      search the above directories and all subdirectories for needed
      fonts.</para>

      <para>Finally, to update all the font cache files, run</para>

<screen role="root"><userinput>fc-cache</userinput></screen>

      <indexterm zone="x-setup fonts">
        <primary sortas="b-fc-cache">fc-cache</primary>
      </indexterm>

      <para><application>X</application> will now be able to use
      <application>TrueType</application> fonts when it is restarted.
      You can check to see if the new fonts are available with the
      <command>xlsfonts</command>  or <command>xfontsel</command>
      program.</para>

      <note>
        <para>You should rerun <command>mkfontscale</command> and
        <command>mkfontdir</command> any time you add or delete
        <application>TrueType</application> fonts.
        You should also rerun <command>fc-cache</command> each time
        you add or remove any fonts.</para>
      </note>

    </sect3>

  </sect2>

<!-- ================================================== -->

  <sect2>
    <title>Setting up Keyboards</title>

    <para>In this version of <application>X</application>, non-Latin
    keyboard layouts do not include Latin configurations as was previous
    practice. To set up a keyboard for Latin and non-Latin input, change
    the XkbLayout keyboard driver option in the InputDevice section
    of the <filename>XF86Config</filename> or <filename>xorg.conf</filename>
    file. For example:</para>

<screen><literal>Section "InputDevice"
    Identifier          "Keyboard0"
    Driver              "Keyboard"
    Option "XkbModel"   "pc105"
    Option "XkbLayout"  "en_US,ru"
    Option "XkbOptions" "grp:switch,grp:alt_shift_toggle,grp_led:scroll"
EndSection</literal></screen>

    <para>In this example, you can use the <keycap>Alt+Shift</keycap>
    combination to switch between keyboard layouts and use the Scroll Lock
    LED to indicate when the second layout is active.</para>

  </sect2>

<!-- ================================================== -->

  <sect2>
    <title>Setting up Fonts</title>

    <para>Users using character sets other than ISO-8859-1 have to make
    a few adjustments to their font settings in order to make sure that
    fonts with the correct encoding are used for "fixed", "variable",
    "10x20" and similar aliases. For ISO-8859-<replaceable>[X]</replaceable>
    based locales, use the following command:</para>

<screen role="root"><userinput>sed -i 's,iso8859-1\( \|$\),iso8859-<replaceable>[X]</replaceable>\1,g' \
    /usr/share/fonts/{75dpi,100dpi,misc}/fonts.alias</userinput></screen>

    <para>To use cyrillic fonts with <application>GTK1</application>,
    <application>Tk</application>, <application>Xaw</application> and
    <application>Motif</application>, put the following line into the top of the
    "Files" section in <filename>XF86Config</filename> or
    <filename>xorg.conf</filename>. This directory already contains the needed bitmap
    fonts and their aliases:</para>

<screen><literal>FontPath   "/usr/share/fonts/cyrillic/"</literal></screen>

  </sect2>

<!-- ================================================== -->

  <sect2 id='xdm'>
    <title>Setting up XDM</title>

    <para><command>xdm</command> provides a graphical logon capability and
    is normally set up in <filename>/etc/inittab</filename>. Most of the
    information you need to customize <command>xdm</command> is found in
    its man page. To execute <command>xdm</command> during bootup, change
    the initdefault level to 5 and add the following lines to
    <filename>/etc/inittab</filename>:</para>

    <indexterm zone="x-setup xdm">
      <primary sortas="b-xdm">xdm</primary>
    </indexterm>

<screen><literal># Run xdm as a separate service
x:5:respawn:/usr/X11R6/bin/xdm -nodaemon</literal></screen>

    <para>If <application>Linux-PAM</application> is installed on your
    system, you should create a PAM entry for <command>xdm</command> by
    duplicating the <command>login</command> entry using the following
    command:</para>

    <indexterm zone="x-setup xdm">
      <primary sortas="e-etc-pam.d/xdm">/etc/pam.d/xdm</primary>
    </indexterm>

<screen role="root"><userinput>cp /etc/pam.d/login /etc/pam.d/xdm</userinput></screen>

  </sect2>

<!-- ================================================== -->

  <sect2 id='x-resources'>
    <title>Using X Resources</title>

    <para>There are many options that can be set in
    <application>X</application> and <application>X</application>
    clients via resources. Typically resources are set in the
    <filename>~/.Xresources</filename> file.</para>

    <para>The layout of the <filename>~/.Xresources</filename> file
    consists of a list of specifications in the form of</para>

    <indexterm zone="x-setup x-resources">
      <primary sortas="e-AA.xresources">~/.Xresources</primary>
    </indexterm>

<screen><literal>object.subobject[.subobject...].attribute: value</literal></screen>

    <para>Components of a resource specification are linked together by
    either <emphasis>tight</emphasis>, represented by a dot (.), or
    <emphasis>loose</emphasis>, represented by an asterisk (*), bindings.
    A tight binding indicates that the components on either side of the
    dot must be directly next to each other as defined in a specific
    implementation. An asterisk is a wildcard character that means that
    any number of levels in a defined hierarchy can be between the components.
    For example, X offers two special cursors: redglass and whiteglass. To
    use one of these resources, you need to add the following line:</para>

<screen><literal>Xcursor.theme: whiteglass</literal></screen>

    <para>However, you can specify the background for all clients with:</para>

<screen><literal>*background: blue</literal></screen>

    <para>More specific resource variables will override less specific
    names.</para>

    <para>Resource definitions can be found in the man pages for each
    respective client.</para>

    <para>In order to load your resources, the <command>xrdb</command>
    program must be called with the appropriate parameters. Typically,
    the first time resources are loaded, you use:</para>

<screen><userinput>xrdb -load &lt;filename&gt;</userinput></screen>

    <para>To add resources to <application>X</application>'s database
    in memory, use:</para>

<screen><userinput>xrdb -merge &lt;filename&gt;</userinput></screen>

    <para>The <command>xrdb</command> instruction is usually placed in
    <filename>~/.xinitrc</filename> or <filename>~/.xsession</filename>.
    To get more information, see the <command>xrdb</command> man page.</para>

    <indexterm zone="x-setup x-resources">
      <primary sortas="b-xrdb">xrdb</primary>
    </indexterm>

  </sect2>

</sect1>