path: root/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>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>

    <!-- Note that the enable-mb-groff switch is a temporary workaround for the
    fact that the configure test doesn't automatically detect that Groff-1.20.1
    is multibyte capable -->

<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 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="6in" ?>

      <tgroup cols="4">

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

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

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