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

<?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>Setting up Fonts</title>

    <para>There are two font systems in the
    <application>X Window System</application>.  The first is the
    core X font protocol, and the second is Xft.  Toolkits that use the core
    X font protocol include Xt, Xaw, Motif clones and GTK+-1.2.  Toolkits that
    use Xft include GTK+-2 and Qt and use <application>Fontconfig</application>
    for control.  Both font systems should be configured for proper font
    coverage in the <application>X Window System</application>.</para>

    <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>Core X Font Protocol</title>

      <indexterm zone="x-setup fonts">
        <primary sortas="g-core-x-font">Core X Font Protocol</primary>
      </indexterm>

      <para>The core X font protocol finds fonts from the server configuration
      file (<filename>xorg.conf</filename> or <filename>XF86Config</filename>). 
      If no font paths exist in the configurations file, the server will fall
      back to an internal hard-coded path.  Assuming the prefix for your
      <application>X</application> installation is
      <filename class="directory">/usr/X11R6</filename>, the core fonts will
      reside in subdirectories of <filename
      class="directory">/usr/X11R6/lib/X11/fonts</filename>.  For each
      directory in the path, the server reads three files:</para>

      <itemizedlist>
        <listitem>
          <para><filename>fonts.dir</filename> - maps font files to font
          names&semi; updated with <command>mkfontdir</command></para>
        </listitem>
        <listitem>
          <para><filename>fonts.alias</filename> - defines aliases (such as
          "9x18") for existing fonts</para>
        </listitem>
        <listitem>
          <para><filename>fonts.scale</filename> - lists scalable fonts&semi;
          updated with <command>mkfontscale</command></para>
        </listitem>
      </itemizedlist>

      <para>The core X fonts protocol uses names such as
      <systemitem>-misc-fixed-medium-r-normal--13-120-75-75-c-80-iso8859-1</systemitem>. 
      These fonts are rendered by the <application>X</application> server
      without antialiasing.  The server itself uses the "cursor" font for
      painting the mouse cursor, and the protocol specification requires the
      font "fixed" to be available.</para>

      <para>Scalable fonts, such as Type1 and TrueType, are read from
      <filename>fonts.scale</filename> files by the server.  The core X font
      system uses the "freetype" module for non-antialiased rendering of these
      fonts.  Ensure that the "freetype" module is loaded in the
      <filename>XF86config</filename> or <filename>xorg.conf</filename>
      file by adding it to the "Module" section:</para>

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

      <para>The character set used is part of the font name, e.g. "-iso8859-1". 
      It is important that applications which support a non-English interface
      specify the character set correctly so that the proper glyphs are used. 
      This can be controlled through the <application>X</application>
      resources, which will be described later.</para>

      <para>In some cases, applications rely upon the fonts named "fixed" or
      something like "9x18".  In these cases, it is important that the
      <filename>fonts.alias</filename> file specifies the correct character
      set.  Users of ISO-8859-<replaceable>X</replaceable> encodings where
      <replaceable>X</replaceable> != 1 should modify the
      <filename>/usr/lib/X11/fonts/misc/fonts.alias</filename> file by
      replacing the "iso8859-1" string with the proper encoding name.  This is
      accomplished by running the following command as the <systemitem
      class="username">root</systemitem> user, substituting the proper value
      for <replaceable>[X]</replaceable>:</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>Users of Cyrillic fonts have properly defined aliases in
      <filename>/usr/lib/X11/fonts/cyrillic/fonts.alias</filename>.  However,
      this file will not be used unless the <filename
      class="directory">/usr/lib/X11/fonts/cyrillic</filename> directory is
      first in the font search path.  Otherwise, the
      <filename>/usr/lib/X11/fonts/misc/fonts.alias</filename> file will be
      used.</para>

    </sect3>

    <sect3>
      <title>Xft Font Protocol</title>

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

      <para>Xft provides antialiased font rendering through
      <application>Freetype</application>, and fonts are controlled from the
      client side using <application>Fontconfig</application>.  The default
      search path is <filename class="directory">/usr/share/fonts</filename>
      and <filename class="directory">~/.fonts</filename>. 
      When installing <application>X</application>, symlinks were created from
      the <filename class="directory">OTF</filename> and <filename
      class="directory">TTF</filename> <application>X</application> font
      directories to <filename
      class="directory">/usr/share/fonts/X11-{OTF,TTF}</filename>.  This
      prevents <application>Fontconfig</application> from using the poorly
      rendered Type1 fonts or the non-scalable bitmapped fonts.</para>

      <para><application>Fontconfig</application> searches directories in its
      path recursively and maintains a cache of the font characteristics in
      <filename>fonts.cache-1</filename> files in each directory.  If the cache
      appears to be out of date, it is ignored, and information is (slowly)
      fetched from the fonts themselves.  This cache
      can be regenerated using the <command>fc-cache</command> command at any
      time.</para>

      <para><application>Fontconfig</application> uses names such as
      "Monospace 12" to define fonts.  Applications generally use generic font
      names such as "Monospace", "Sans" and "Serif". 
      <application>Fontconfig</application> resolves these names to a font that
      has all characters that cover the orthography of the language indicated
      by the locale settings.  Knowledge of these font names is included in
      <filename>/etc/fonts/fonts.conf</filename>.</para>

      <para>Standard scalable fonts that come with <application>X</application>
      provide very poor Unicode coverage.  You may notice in applications that
      use <application>Xft</application> that some characters appear as a box
      with four binary digits inside.  In this case, a font set with the
      available glyphs has not been found.  Other times, applications that
      don't use other font families by default and don't accept substitutions
      from <application>Fontconfig</application> will display blank lines when
      the default font doesn't cover the orthography of the user's language. 
      This happens, e.g., with <application>Fluxbox</application> in the
      ru_RU.KOI8-R locale.</para>

      <para>In order to provide greater Unicode coverage, it is recommended
      that you install these fonts:</para>

      <itemizedlist>
        <listitem>
          <para><ulink url="http://dejavu.sourceforge.net/">DejaVu fonts</ulink>
          - These fonts are replacements for the Bitstream Vera fonts and
          provide Latin-based scripts with accents and Cyrillic glyphs.
          <application>Fontconfig</application> does not know about the DejaVu
          fonts by default, so <filename>/etc/fonts/fonts.conf</filename> will
          have to be edited for it to be recognized by the generic names such
          as "Sans".  This will be described below.</para>
        </listitem>
        <listitem>
          <para><ulink
          url="http://download.savannah.nongnu.org/releases/freefont/">FreeFont</ulink>
          - This set of fonts covers nearly every non-CJK character, but is not
          visually pleasing.  <application>Fontconfig</application> will use it
          as a last resort to substitute generic font family names.</para>
        </listitem>
        <listitem>
          <para><ulink
          url="http://corefonts.sourceforge.net/">Microsoft Core fonts</ulink>
          - These fonts provide slightly worse Unicode coverage than FreeFont,
          but are better hinted.  Be sure to read the license before using
          them.  <application>Fontconfig</application> knows about them by
          default.</para>
        </listitem>
        <listitem>
          <para><ulink
          url="http://cle.linux.org.tw/fonts/FireFly">Firefly New Sung font</ulink>
          - This font provides Chinese coverage.  However,
          <application>Fontconfig</application>does not know about this font
          by default.</para>
        </listitem>
        <listitem>
          <para><ulink
          url="http://cle.linux.org.tw/fonts/Arphic">Arphic fonts</ulink> -
          A similar set of Chinese fonts to the Firefly New Sung font.
          <application>Fontconfig</application> knows about these fonts by
          default and will substitute them for generic family names.</para>
        </listitem>
        <listitem>
          <para><ulink
          url="http://sourceforge.jp/projects/efont/">Kochi fonts</ulink> -
          These provide Japanese characters, and
          <application>Fontconfig</application> knows about these fonts by
          default.</para>
        </listitem>
        <listitem>
          <para><ulink
          url="http://kldp.net/projects/baekmuk/">Baekmuk fonts</ulink>
          - These fonts provide Korean coverage, and
          <application>Fontconfig</application> knows about these fonts by
          default.</para>
        </listitem>
      </itemizedlist>

      <para>The list above will not provide complete Unicode coverage.  For
      more information, please visit the <ulink
      url="http://unifont.org/fontguide/">Unicode Font Guide</ulink>.</para>

      <para>As an example, consider the installation of the DejaVu fonts.  From
      the unpacked source directory, run the following commands as the
      <systemitem class="username">root</systemitem> user:</para>

<screen role="root"><userinput>install -v -d -m755 /usr/share/fonts/dejavu &amp;&amp;
install -v -m644 *.ttf /usr/share/fonts/dejavu &amp;&amp;
fc-cache -v /usr/share/fonts/dejavu</userinput></screen>

      <para>Earlier it was mentioned that <filename>/etc/fonts/fonts.conf</filename>
      could be modified to use DejaVu using the default family names.  Since
      DejaVu is a replacement for Bitstream Vera fonts, we can substitute it
      for that family.  Visually inspect the <filename>fonts.conf</filename> to
      see how fonts are grouped together under the generic family names and a
      preference list is created.  To replace Bitstream Vera with DejaVu, as the
      <systemitem class="username">root</systemitem> user:</para>

<screen role="root"><userinput>sed -i 's/&lt;family&gt;Bitstream Vera/&lt;family&gt;DejaVu/' /etc/fonts/fonts.conf</userinput></screen>

    </sect3>

<!--
<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>
 -->
<!-- this doesn't validate
    <bridgehead renderas="sect3" condition="html" role="usernotes">User Notes:
    <ulink url='&blfs-wiki;/XWindowSystemComponents'/></bridgehead>
-->

  </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 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>