6.45. Man-DB-2.4.3

The Man-DB package contains programs for finding and viewing man pages.

Approximate build time: 0.2 SBU
Required disk space: 9 MB

6.45.1. Installation of Man-DB

Three adjustments need to be made to the sources of Man-DB.

The first one changes the location of translated manual pages that come with Man-DB, in order for them to be accessible in both traditional and UTF-8 locales:

mv man/de{_DE.88591,} &&
mv man/es{_ES.88591,} &&
mv man/it{_IT.88591,} &&
mv man/ja{_JP.eucJP,} &&
sed -i 's,\*_\*,??,' man/Makefile.in

The second change is a sed substitution to delete the “/usr/man” lines in the man_db.conf file to prevent redundant results when using programs such as whatis:

sed -i '/\t\/usr\/man/d' src/man_db.conf.in

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

cat >> include/manconfig.h.in << "EOF"
#define WEB_BROWSER "exec /usr/bin/lynx"
#define COL "/usr/bin/col"
#define VGRIND "/usr/bin/vgrind"
#define GRAP "/usr/bin/grap"
EOF

The col program is a part of the Util-linux package, lynx is a text-based web browser (see BLFS for installation instructions), vgrind converts program sources to Groff input, and grap is useful for typesetting graphs in Groff documents. The vgrind and grap 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.

Prepare Man-DB for compilation:

./configure --prefix=/usr --enable-mb-groff --disable-setuid

The meaning of the configure options:

--enable-mb-groff

This tells the man program to use the “ascii8” and “nippon” Groff devices for formatting non-ISO-8859-1 manual pages.

--disable-setuid

This disables making the man program setuid to user man.

Compile the package:

make

This package does not come with a test suite.

Install the package:

make install

Some packages provide UTF-8 man pages which this version of man 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.

cat >> convert-mans << "EOF"
#!/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
EOF
install -m755 convert-mans  /usr/bin

Additional information regarding the compression of man and info pages can be found in the BLFS book at http://www.linuxfromscratch.org/blfs/view/cvs/postlfs/compressdoc.html.

6.45.2. Non-English Manual Pages in LFS

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.

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 groff is known to misformat text.

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.

Table 6.1. Expected character encoding of manual pages

Language (code)Encoding
Danish (da)ISO-8859-1
German (de)ISO-8859-1
English (en)ISO-8859-1
Spanish (es)ISO-8859-1
Finnish (fi)ISO-8859-1
French (fr)ISO-8859-1
Irish (ga)ISO-8859-1
Galician (gl)ISO-8859-1
Indonesian (id)ISO-8859-1
Icelandic (is)ISO-8859-1
Italian (it)ISO-8859-1
Dutch (nl)ISO-8859-1
Norwegian (no)ISO-8859-1
Portuguese (pt)ISO-8859-1
Swedish (sv)ISO-8859-1
Czech (cs)ISO-8859-2
Croatian (hr)ISO-8859-2
Hungarian (hu)ISO-8859-2
Japanese (ja)EUC-JP
Korean (ko)EUC-KR
Polish (pl)ISO-8859-2
Russian (ru)KOI8-R
Slovak (sk)ISO-8859-2
Turkish (tr)ISO-8859-9
[Note]

Note

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.

If upstream distributes the manual pages in the same encoding as Man-DB expects, the manual pages can be copied to /usr/share/man/<language code>. E.g., French manual pages (http://ccb.club.fr/man/man-fr-1.58.0.tar.bz2) can be installed with the following command:

mkdir -p /usr/share/man/fr &&
cp -rv man? /usr/share/man/fr

If upstream distributes manual pages in UTF-8 (i.e., “for RedHat”) 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 convert-mans, e.g., Spanish manual pages (http://ditec.um.es/~piernas/manpages-es/man-pages-es-1.55.tar.bz2) can be installed with the following commands:

mv man7/iso_8859-7.7{,X}
convert-mans UTF-8 ISO-8859-1 man?/*.?
mv man7/iso_8859-7.7{X,}
make install
[Note]

Note

The need to exclude the man7/iso_8859-7.7 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.

6.45.3. Contents of Man-DB

Installed programs: accessdb, apropos, catman, convert-mans,lexgrog, man, mandb, manpath, whatis, and zsoelim

Short Descriptions

accessdb

Dumps the whatis database contents in human-readable form

apropos

Searches the whatis database and displays the short descriptions of system commands that contain a given string

catman

Creates or updates the pre-formatted manual pages

convert-mans

Reformat man pages so that Man-DB can display them

lexgrog

Displays one-line summary information about a given manual page

man

Formats and displays the requested manual page

mandb

Creates or updates the whatis database

manpath

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

whatis

Searches the whatis database and displays the short descriptions of system commands that contain the given keyword as a separate word

zsoelim

Reads files and replaces lines of the form .so file by the contents of the mentioned file