lfs-book/chapter06/man-db.xml

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

<sect1 id="ch-system-man-db" role="wrap">
  <?dbhtml filename="man-db.html"?>

  <sect1info condition="script">
    <productname>man-db</productname>
    <productnumber>&man-db-version;</productnumber>
    <address>&man-db-url;</address>
  </sect1info>

  <title>Man-DB-&man-db-version;</title>

  <indexterm zone="ch-system-man-db">
    <primary sortas="a-Man-DB">Man-DB</primary>
  </indexterm>

  <sect2 role="package">
    <title/>

    <para>The Man-DB package contains programs for finding and viewing man
    pages.</para>

    <segmentedlist>
      <segtitle>&buildtime;</segtitle>
      <segtitle>&diskspace;</segtitle>

      <seglistitem>
        <seg>&man-db-ch6-sbu;</seg>
        <seg>&man-db-ch6-du;</seg>
      </seglistitem>
    </segmentedlist>

  </sect2>

  <sect2 role="installation">
    <title>Installation of Man-DB</title>

    <!-- <para>Two adjustments need to be made to the sources of Man-DB.</para> 

    <para>The first change is a <command>sed</command> substitution to delete
    the <quote>/usr/man</quote> and <quote>/usr/local/man</quote> lines in
    the <filename>man_db.conf</filename> file to prevent redundant results
    when using programs such as <command>whatis</command>:</para> -->

    <para>LFS creates <filename>/usr/man</filename> and
    <filename>/usr/local/man</filename> as symlinks.   Remove them from the
    <filename>man_db.conf</filename> file to prevent redundant
    results when using programs such as <command>whatis</command>:</para>

<screen><userinput remap="pre">sed -i -e '\%\t/usr/man%d' -e '\%\t/usr/local/man%d' src/man_db.conf.in</userinput></screen>

    <para>Prepare Man-DB for compilation:</para>

<screen><userinput remap="configure">./configure --prefix=/usr --libexecdir=/usr/lib \
    --sysconfdir=/etc --disable-setuid \
    --enable-mb-groff --with-browser=/usr/bin/lynx \
    --with-col=/usr/bin/col --with-vgrind=/usr/bin/vgrind \
    --with-grap=/usr/bin/grap</userinput></screen>

    <variablelist>
      <title>The meaning of the configure options:</title>

      <varlistentry>
        <term><parameter>--disable-setuid</parameter></term>
        <listitem>
          <para>This disables making the <command>man</command> program setuid
          to user <systemitem class="username">man</systemitem>.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><parameter>--enable-mb-groff</parameter></term>
        <listitem>
          <para>This switch tells <application>man-db</application> to expect
          the Debian multibyte patched version of
          <application>groff</application>.</para>  
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><parameter>--with-...</parameter></term>
        <listitem>
          <para>These four parameters are used to set some default programs.
          The <command>col</command> program is a part of the Util-linux-ng
          package, <command>lynx</command> is a text-based web browser (see
          BLFS for installation instructions), <command>vgrind</command>
          converts program sources to Groff input, and <command>grap</command>
          is useful for typesetting graphs in Groff documents. The
          <command>vgrind</command> and <command>grap</command> programs are
          not normally needed for viewing manual pages. They are not part of
          LFS or BLFS, but you should be able to install them yourself after
          finishing LFS if you wish to do so.</para>
        </listitem>
      </varlistentry>

    </variablelist>

    <para>Compile the package:</para>

<screen><userinput remap="make">make</userinput></screen>

    <para>This package does not come with a test suite.</para>

    <para>Install the package:</para>

<screen><userinput remap="install">make install</userinput></screen>

  </sect2>

  <sect2>
    <title>Non-English Manual Pages in LFS</title>
<!--
    <para>Some packages provide UTF-8 manual pages, which previous versions of
    <application>Man-DB</application> were unable to display correctly because
    the expected (8-bit) encoding for each language was hard-coded in the
    source of <application>Man-DB</application>.
    <application>Man-DB</application> now uses the extension of the directory
    name in order to determine the encoding of the manual pages stored within.
    If no extension exists, <application>Man-DB</application> uses a built-in
    table (see below) to determine the encoding.  E.g., because of "UTF-8" in
    the directory name, it knows that all manual pages residing in 
    <filename class="directory">/usr/share/man/fr.UTF-8</filename> are UTF-8
    encoded and, according to the built-in table, expects all manual pages
    residing in <filename class="directory">/usr/share/man/ru</filename> to
    be encoded using KOI8-R.</para>

    <para>Linux distributions have different policies concerning the character
    encoding in which manual pages are stored in the filesystem. E.g., RedHat
    stores all manual pages in UTF-8, while Debian previously used
    language-specific (mostly 8-bit) encodings. Many other distributions simply
    ignore the problem all together.  LFS also used the legacy encodings in
    previuos versions of the book. This was chosen because of the ease of
    configuration associated with <application>Man-DB</application>.
    Additionally, <application>Man-DB</application> provided support for
    Chinese and Japanese locales, and limited support for Korean, whereas
    <application>Man</application> did not at that time.</para>

    <para>In contrast, the setup in Fedora Core expects all manual pages
    to be UTF-8 encoded, and stored in directories without suffixes.
    Disagreement about the expected encoding of manual pages amongst
    distribution vendors, has led to confusion for upstream package maintainers.
    Some packages contain, UTF-8 manual pages, while others ship with manual
    pages in legacy encodings.  Unlike the
    <application>Man</application>/<application>Groff</application> setup in
    Fedora Core, <application>Man-DB</application> can make very good decisions
    about the on disk encoding and present the information to the user in their
    prefered format, without complex configurations.</para>

    <para><application>Man-DB</application> has, for the most part, made this
    problem completely transparent to end users, as long as the manual pages
    are installed into the correct directory.  There may be times, however,
    where one encoding is preferred over the other.  For this purpose, the
    <command>convert-mans</command> script was written. It will convert manual
    pages to another encoding before (or after) installation.  Install the
    <command>convert-mans</command> script with the following
    instructions:</para>
-->
    <para>Some packages provide non-English manual pages. They are displayed 
    correctly only if their location and encoding matches the expectation of 
    the "man" program. However, different Linux distributions have different 
    policies (expressed in the choice of the <command>man</command> program,
    its configuration and patches applied to it) concerning the character 
    encoding in which manual pages are stored in the filesystem.</para>

    <para>E.g., Debian previously required Russian manual pages to be encoded
    in KOI8-R and to be placed in
    <filename class="directory">/usr/share/man/ru</filename>. Now, in addition,
    their <command>man</command> program (<application>Man-DB</application>)
    searches for UTF-8 encoded Russian manual pages in
    <filename class="directory">/usr/share/man/ru.UTF-8</filename>. On the
    other hand, Fedora uses UTF-8 encoded manual pages exclusively. Russian
    manual pages  are found in
    <filename class="directory">/usr/share/man/ru</filename> and their
    <command>man</command> program doesn't acknowledge
    <filename class="directory">/usr/share/man/ru.UTF-8</filename>.  Many
    other distributions ignore the on disk encodings completely, leaving the
    end user with a mix of improperly encoded manual pages for their
    configuration. When <command>man</command> processes the requtested page,
    it will display the contents as configured, resulting in completely
    unreadable text if the on disk encoding is not what is expected for that
    configuration.</para>

    <para>Disagreement about the expected encoding of manual pages amongst
    distribution vendors, has led to confusion for upstream package
    maintainers. One package may contain UTF-8 manual pages, while another
    ships with manual pages in legacy encodings. <command>man</command>
    searches for manual pages based on the user's locale settings.
    <application>Man-DB</application> uses a built-in table (see below) to
    determine the on disk encoding of manual pages found for a user's
    locale, only if the directories found do not have an extension that
    describes the encoding. E.g., because of ".UTF-8" in the directory name,
    <application>Man-DB</application> knows that all manual pages residing in 
    <filename class="directory">/usr/share/man/fr.UTF-8</filename> are UTF-8
    encoded and, according to the built-in table, expects all manual pages
    residing in <filename class="directory">/usr/share/man/ru</filename> to
    be encoded using KOI8-R.</para>

    <!-- Origin: man-db-2.5.2/src/encodings.c -->
    <table>
      <title>Expected character encoding of legacy 8-bit manual pages</title>
      <?dbfo table-width="2.5in" ?>

      <tgroup cols="2">

        <colspec colnum="1" colwidth="1.5in"/>
        <colspec colnum="2" colwidth="1in"/>

        <thead>
          <row>
            <entry>Language (code)</entry>
            <entry>Encoding</entry>
          </row>
        </thead>

        <tbody>
          <row>
            <entry>Danish (da)</entry>
            <entry>ISO-8859-1</entry>
          </row>
          <row>
            <entry>German (de)</entry>
            <entry>ISO-8859-1</entry>
          </row>
          <row>
            <entry>English (en)</entry>
            <entry>ISO-8859-1</entry>
          </row>
          <row>
            <entry>Spanish (es)</entry>
            <entry>ISO-8859-1</entry>
          </row>
          <row>
            <entry>Finnish (fi)</entry>
            <entry>ISO-8859-1</entry>
          </row>
          <row>
            <entry>French (fr)</entry>
            <entry>ISO-8859-1</entry>
          </row>
          <row>
            <entry>Irish (ga)</entry>
            <entry>ISO-8859-1</entry>
          </row>
          <row>
            <entry>Galician (gl)</entry>
            <entry>ISO-8859-1</entry>
          </row>
          <row>
            <entry>Indonesian (id)</entry>
            <entry>ISO-8859-1</entry>
          </row>
          <row>
            <entry>Icelandic (is)</entry>
            <entry>ISO-8859-1</entry>
          </row>
          <row>
            <entry>Italian (it)</entry>
            <entry>ISO-8859-1</entry>
          </row>
          <row>
            <entry>Dutch (nl)</entry>
            <entry>ISO-8859-1</entry>
          </row>
	  <!-- FIXME: BUG: "no" is deprecated, should use "nb" or "nn" and
          symlinks -->
          <row>
            <entry>Norwegian (no)</entry>
            <entry>ISO-8859-1</entry>
          </row>
          <!-- END BUG -->
          <row>
            <entry>Portuguese (pt)</entry>
            <entry>ISO-8859-1</entry>
          </row>
          <row>
            <entry>Swedish (sv)</entry>
            <entry>ISO-8859-1</entry>
          </row>
          <!-- Languages below require patched groff -->
          <row>
            <entry>Bulgarian (bg)</entry>
            <entry>CP1251</entry>
          </row>
          <row>
            <entry>Czech (cs)</entry>
            <entry>ISO-8859-2</entry>
          </row>
          <row>
            <entry>Croatian (hr)</entry>
            <entry>ISO-8859-2</entry>
          </row>
          <row>
            <entry>Hungarian (hu)</entry>
            <entry>ISO-8859-2</entry>
          </row>
          <row>
            <entry>Japanese (ja)</entry>
            <entry>EUC-JP</entry>
          </row>
          <row>
            <entry>Korean (ko)</entry>
            <entry>EUC-KR</entry>
          </row>
          <row>
            <entry>Polish (pl)</entry>
            <entry>ISO-8859-2</entry>
          </row>
          <row>
            <entry>Russian (ru)</entry>
            <entry>KOI8-R</entry>
          </row>
          <row>
            <entry>Slovak (sk)</entry>
            <entry>ISO-8859-2</entry>
          </row>
          <row>
            <entry>Serbian (sr)</entry>
            <entry>ISO-8859-5</entry>
          </row>
          <row>
            <entry>Turkish (tr)</entry>
            <entry>ISO-8859-9</entry>
          </row>
          <row>
            <entry>Simplified Chinese (zh_CN)</entry>
            <entry>GBK</entry>
          </row>
          <row>
            <entry>Simplified Chinese, Singapore (zh_SG)</entry>
            <entry>GBK</entry>
          </row>
          <row>
            <entry>Traditional Chinese (zh_TW)</entry>
            <entry>BIG5</entry>
          </row>
          <row>
            <entry>Traditional Chinese, Hong Kong (zh_HK)</entry>
            <entry>BIG5HKSCS</entry>
          </row>
        </tbody>

      </tgroup>

    </table>

    <note>
      <para>Manual pages in languages not in the list are not supported.
      Norwegian does not work because of the transition from no_NO to
      nb_NO locale, and will be fixed in the next release of 
      <application>Man-DB</application>.  Korean is currently non functional
      because of incomplete fixes in the Debian
      <application>Groff</application> patch applied in LFS.</para>
    </note>

    <para>Packages may install manual pages into an improperly named directory,
    depending on which distributions the author develops the package for. To
    assist in the conversion of the manual pages to the proper encoding for the
    directory in which they are installed, the <command>convert-mans</command>
    script was written. It will convert manual pages to another encoding before
    (or after) installation.  Install the <command>convert-mans</command>
    script with the following instructions:</para>

<screen><userinput remap="install">cat &gt;&gt; convert-mans &lt;&lt; "EOF"
<literal>#!/bin/sh -e
FROM="$1"
TO="$2"
shift ; shift
while [ $# -gt 0 ]
do
        FILE="$1"
        shift
        iconv -f "$FROM" -t "$TO" "$FILE" >.tmp.iconv
        mv .tmp.iconv "$FILE"
done</literal>
EOF
install -m755 convert-mans  /usr/bin</userinput></screen>


    <para>If upstream distributes the manual pages in a legacy encoding, the
    manual pages can simply be copied to
    <filename class="directory">/usr/share/man/<replaceable>&lt;language
    code&gt;</replaceable></filename>. For example, <ulink
    url="http://www.infodrom.org/projects/manpages-de/download/manpages-de-0.5.tar.gz">
    German manual pages</ulink> can be installed with the following
    commands:</para>

<screen role="nodump"><userinput>mkdir -p /usr/share/man/de
cp -rv man? /usr/share/man/de</userinput></screen>

    <para>If upstream distributes manual pages in UTF-8 (i.e., <quote>for
    RedHat</quote>) instead of the encoding listed in the table above, they
    can either be converted from UTF-8 to the encoding listed in the table
    above, or they can be installed directly into
    <filename class="directory">/usr/share/man/<replaceable>&lt;language
    code&gt;</replaceable>.UTF-8</filename>.</para>

    <para>For example, to install <ulink
    url="http://manpagesfr.free.fr/download/man-pages-fr-2.40.0.tar.bz2">
    French manual pages</ulink> in the legacy encoding, use the following
    commands:</para>

<screen role="nodump"><userinput>convert-mans UTF-8 ISO-8859-1 man?/*.?
mkdir -p /usr/share/man/fr
cp -rv man? /usr/share/man/fr</userinput></screen>

    <note><para>The French manual pages ship with ready made scripts to do the
    same conversion. The above instructions are used only as an example for
    use of the <command>convert-mans</command> script.</para></note>

    <para>Finally, as an example installation of UTF-8 manual pages, again, the
    French manual pages could be installed with the following commands:</para>

<screen role="nodump"><userinput>mkdir -p /usr/share/man/fr.UTF-8
cp -rv man? /usr/share/man/fr.UTF-8</userinput></screen>

  </sect2>

  <sect2 id="contents-man-db" role="content">
    <title>Contents of Man-DB</title>

    <segmentedlist>
      <segtitle>Installed programs</segtitle>

      <seglistitem>
        <seg>apropos, catman, convert-mans, lexgrog, man, mandb,
        manpath, whatis, and zsoelim</seg>
      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <!-- <varlistentry id="accessdb">
        <term><command>accessdb</command></term>
        <listitem>
          <para>Dumps the <command>whatis</command> database contents in
          human-readable form</para>
          <indexterm zone="ch-system-man-db accessdb">
            <primary sortas="b-accessdb">accessdb</primary>
          </indexterm>
        </listitem>
      </varlistentry> -->

      <varlistentry id="apropos">
        <term><command>apropos</command></term>
        <listitem>
          <para>Searches the <command>whatis</command> database and displays
          the short descriptions of system commands that contain a given
          string</para>
          <indexterm zone="ch-system-man-db apropos">
            <primary sortas="b-apropos">apropos</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="catman">
        <term><command>catman</command></term>
        <listitem>
          <para>Creates or updates the pre-formatted manual pages</para>
          <indexterm zone="ch-system-man-db catman">
            <primary sortas="b-catman">catman</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="convert-mans">
        <term><command>convert-mans</command></term>
        <listitem>
          <para>Reformats manual pages into the chosen encoding.</para>
          <indexterm zone="ch-system-man-db convert-mans">
            <primary sortas="b-convert-mans">convert-mans</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="lexgrog">
        <term><command>lexgrog</command></term>
        <listitem>
          <para>Displays one-line summary information about a given manual
          page</para>
          <indexterm zone="ch-system-man-db lexgrog">
            <primary sortas="b-lexgrog">lexgrog</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="man">
        <term><command>man</command></term>
        <listitem>
          <para>Formats and displays the requested manual page</para>
          <indexterm zone="ch-system-man-db man">
            <primary sortas="b-man">man</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="mandb">
        <term><command>mandb</command></term>
        <listitem>
          <para>Creates or updates the <command>whatis</command> database</para>
          <indexterm zone="ch-system-man-db mandb">
            <primary sortas="b-mandb">mandb</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="manpath">
        <term><command>manpath</command></term>
        <listitem>
          <para>Displays the contents of $MANPATH or (if $MANPATH is not set)
          a suitable search path based on the settings in man.conf and the
          user's environment</para>
          <indexterm zone="ch-system-man-db manpath">
            <primary sortas="b-manpath">manpath</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="whatis">
        <term><command>whatis</command></term>
        <listitem>
          <para>Searches the <command>whatis</command> database and displays
          the short descriptions of system commands that contain the given
          keyword as a separate word</para>
          <indexterm zone="ch-system-man-db whatis">
            <primary sortas="b-whatis">whatis</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="zsoelim">
        <term><command>zsoelim</command></term>
        <listitem>
          <para>Reads files and replaces lines of the form <emphasis>.so
          file</emphasis> by the contents of the mentioned
          <emphasis>file</emphasis></para>
          <indexterm zone="ch-system-man-db zsoelim">
            <primary sortas="b-zsoelim">zsoelim</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>