source: x/installing/x-setup.xml@ 86af98a

<?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.3/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;
]>

<sect1 id="x-setup">
<sect1info>
<othername>$LastChangedBy$</othername>
<date>$Date$</date>
</sect1info>
<?dbhtml filename="xfree86-setup.html"?>
<title>X Window System Components</title>

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

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

<para><acronym>DRI</acronym> 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 <acronym>DRI</acronym> 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>(II) R128(0): Direct rendering enabled</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 <acronym>DRI</acronym> Users 
Guide at 
<ulink url="http://dri.sourceforge.net/doc/DRIuserguide.html"/>.</para>

</sect2>

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

<sect2 id='fonts'>
<title>Adding <application>TrueType</application> fonts to
<application>X</application></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>Ensure the <parameter>FontPath</parameter> in 
<filename>XF86Config</filename> or <filename>xorg.conf</filename> contains the
<application>TrueType</application> font directory.</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 <application>TrueType</application> 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/X11R6/lib/X11/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/X11R6/lib/X11/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 <filename>fonts.scale</filename> and 
<filename>fonts.dir</filename></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:
<screen><userinput><command>mkfontscale &amp;&amp;
mkfontdir</command></userinput></screen></para>
<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 <application>TrueType</application> is loaded in 
<filename>XF86Config</filename> or <filename>xorg.conf</filename></title> 
<para>The "Module" section should look like:
<screen>Section "Module"
        ...
        Load  "freetype"
        ...
EndSection</screen></para>
</sect3>

<sect3><title>Ensure the <parameter>FontPath</parameter> in
<filename>XF86Config</filename> or <filename>xorg.conf</filename> points to the
<application>TrueType</application> font directory</title>
<para>The "Files" section should look like:
<screen>Section "Files"
        ...
        FontPath "/usr/X11R6/lib/X11/fonts/<replaceable>[TrueTypeDir]</replaceable>/"
        ...
EndSection</screen></para>
</sect3>

<sect3><title>Update the font cache files</title> 

<para>Ensure you have the following directory entries in
<filename>/etc/fonts/local.conf</filename>, inside the fontconfig
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><userinput><command>cat &gt; /etc/fonts/local.conf &lt;&lt; "EOF"</command>
&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;

<command>EOF</command></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><userinput><command>fc-cache</command></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>   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</screen>

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

<!-- ================================================== -->
<sect2>
<title>Setting up fonts</title>

<para>Users using character sets other than <acronym>ISO</acronym>-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:</para>
    
<para>For Cyrillic alphabet, it is sufficient to put the following line
into the top of the "Files" section in <filename>XF86Config</filename>
or <filename>xorg.conf</filename> because this directory already contains 
the needed bitmap fonts and their aliases:</para>

<screen>FontPath     "/usr/X11R6/lib/X11/fonts/cyrillic/"</screen>

<para>For ISO-8859-<replaceable>[X]</replaceable> based locales, use the
following command instead:</para>

<screen><userinput><command>sed -i 's,iso8859-1\( \|$\),iso8859-<replaceable>[X]</replaceable>\1,g' \
    /usr/X11R6/lib/X11/fonts/{75dpi,100dpi,misc}/fonts.alias</command></userinput></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>

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

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

<para><screen><userinput>cp /etc/pam.d/login /etc/pam.d/xdm</userinput></screen></para>
<indexterm zone="x-setup xdm">
  <primary sortas="e-etc-pam.d/xdm">/etc/pam.d/xdm</primary>
</indexterm>

</sect2>

<!-- ================================================== -->
<sect2 id='x-resources'>
<title>Using <application>X</application> 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>object.subobject[.subobject...].attribute: value</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>Xcursor.theme: whiteglass</screen>

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

<screen>*background: blue</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><command>xrdb -load &lt;filename&gt;</command></userinput></screen>

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

<screen><userinput><command>xrdb -merge &lt;filename&gt;</command></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 xrdb man page.</para>

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

</sect2>

</sect1>