diff options
Diffstat (limited to 'chapter06/man-db.xml')
| -rw-r--r-- | chapter06/man-db.xml | 269 |
1 files changed, 150 insertions, 119 deletions
diff --git a/chapter06/man-db.xml b/chapter06/man-db.xml index bb1fefced..542ff47f9 100644 --- a/chapter06/man-db.xml +++ b/chapter06/man-db.xml @@ -41,48 +41,18 @@ <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> + <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> - <!-- 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 >> include/manconfig.h.in << "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 \ +<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> @@ -98,17 +68,27 @@ EOF</userinput></screen> </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> + 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> @@ -124,60 +104,54 @@ EOF</userinput></screen> <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 >> convert-mans << "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 --> + <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 manual pages</title> + <title>Expected character encoding of legacy 8-bit manual pages</title> <?dbfo table-width="2.5in" ?> <tgroup cols="2"> @@ -241,7 +215,7 @@ install -m755 convert-mans /usr/bin</userinput></screen> <entry>Dutch (nl)</entry> <entry>ISO-8859-1</entry> </row> - <!-- FIXME: BUG: "no" is deprecated, should use "nb" or "nn" and + <!-- FIXME: BUG: "no" is deprecated, should use "nb" or "nn" and symlinks --> <row> <entry>Norwegian (no)</entry> @@ -258,6 +232,10 @@ install -m755 convert-mans /usr/bin</userinput></screen> </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> @@ -290,9 +268,29 @@ install -m755 convert-mans /usr/bin</userinput></screen> <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> @@ -301,40 +299,73 @@ install -m755 convert-mans /usr/bin</userinput></screen> <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> + 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>If upstream distributes the manual pages in the same encoding - as Man-DB expects, the manual pages can be copied to + <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 >> convert-mans << "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><language - code></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> + code></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/fr -cp -rv man? /usr/share/man/fr</userinput></screen> +<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 - 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> + 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><language + code></replaceable>.UTF-8</filename>.</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> + <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> - <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> +<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> @@ -391,7 +422,7 @@ make install</userinput></screen> <varlistentry id="convert-mans"> <term><command>convert-mans</command></term> <listitem> - <para>Reformat man pages so that Man-DB can display them</para> + <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> |