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

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

    <!-- This is removed and the same thing is done using the configure
         command, which seems to be the more proper method

    <para>The second change accounts for programs that Man-DB should be able
    to find at runtime, but that haven't been installed yet:</para>

<screen><userinput remap="pre">cat &gt;&gt; include/manconfig.h.in &lt;&lt; "EOF"
<literal>#define WEB_BROWSER "exec /usr/bin/lynx"
#define COL "/usr/bin/col"
#define VGRIND "/usr/bin/vgrind"
#define GRAP "/usr/bin/grap"</literal>
EOF</userinput></screen>

    <para>The <command>col</command> program is a part of the Util-linux
    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>

    -->

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

<screen><userinput remap="configure">./configure --prefix=/usr --libexecdir=/usr/lib --sysconfdir=/etc \
    --disable-setuid --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>--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>

    <para>Some packages provide UTF-8 man pages which this version of
    <command>man</command> is unable to display.  The following script will
    allow some of these to be converted into the expected encodings shown in
    the table below. Man-DB expects the manual pages to be in the encodings
    in the table, and will convert them as necessary to the actual locale
    encoding when it displays them, so that they will display in both UTF-8
    and traditional locales.  Because this script is intended for limited use
    during the system build, for public data, we will not bother with error
    checking, nor use a non-predictable temporary file name:</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>Additional information regarding the compression of
    man and info pages can be found in the BLFS book at
    <ulink url="&blfs-root;view/cvs/postlfs/compressdoc.html"/>.</para>

  </sect2>

  <sect2>
    <title>Non-English Manual Pages in LFS</title>

    <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 uses language-specific
    (mostly 8-bit) encodings. This leads to incompatibility of packages with
    manual pages designed for different distributions.</para>

    <para>LFS uses the same conventions as Debian. This was chosen because
    Man-DB does not understand man pages stored in UTF-8. And, for our
    purposes, Man-DB is preferable to Man as it works without extra
    configuration in any locale. Lastly, as of now, there is no fully-working
    implementation of the RedHat convention. RedHat's <command>groff</command>
    is known to misformat text.</para>

    <para>The relationship between language codes and the expected encoding
    of manual pages is listed below. Man-DB automatically converts them to
    the locale encoding while viewing.</para>

    <!-- Origin: man-db-2.4.3/src/encodings.c -->
    <table>
      <title>Expected character encoding of 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>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>Turkish (tr)</entry>
            <entry>ISO-8859-9</entry>
          </row>
        </tbody>

      </tgroup>

    </table>

    <note>
      <para>Manual pages in languages not in the list are not supported.
      Norwegian doesn't work now because of the transition from no_NO to
      nb_NO locale, and Korean is non-functional because of the incomplete
      Groff patch.</para>
    </note>

    <para>If upstream distributes the manual pages in the same encoding
    as Man-DB expects, the manual pages can be copied to
    <filename class="directory">/usr/share/man/<replaceable>&lt;language
    code&gt;</replaceable></filename>. E.g., French manual pages
    (<ulink url="http://ccb.club.fr/man/man-fr-1.58.0.tar.bz2"/>) can be
    installed with the following command:</para>

<screen role="nodump"><userinput>mkdir -p /usr/share/man/fr
cp -rv man? /usr/share/man/fr</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
    have to be converted from UTF-8 to the encoding listed in the table before
    installation. This can be achieved with <command>convert-mans</command>,
    e.g., Spanish manual pages (<ulink
    url="http://ditec.um.es/~piernas/manpages-es/man-pages-es-1.55.tar.bz2"/>)
    can be installed with the following commands:</para>

<screen role="nodump"><userinput>mv man7/iso_8859-7.7{,X}
convert-mans UTF-8 ISO-8859-1 man?/*.?
mv man7/iso_8859-7.7{X,}
make install</userinput></screen>

    <note>
      <para>The need to exclude the <filename>man7/iso_8859-7.7</filename> file
      from the conversion process because it is already in ISO-8859-1 is a
      packaging bug in man-pages-es-1.55. Future versions should not require
      this workaround.</para>
    </note>

  </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>Reformat man pages so that Man-DB can display them</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>