gronod/lfs
1
0
Fork 0
mirror of https://git.linuxfromscratch.org/lfs.git synced 2025-06-19 11:49:20 +01:00
Code Issues Packages Projects Releases Wiki Activity

Updated text and instructions on man-db page.

Browse Source 
git-svn-id: http://svn.linuxfromscratch.org/LFS/trunk/BOOK@8694 4aa44e1e-78dd-0310-a6d2-fbcd4c07a689
This commit is contained in:
DJ Lucas 2008-10-23 04:32:05 +00:00
parent 18627b5228
commit 862c5aedfd
3 changed files with 133 additions and 82 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
chapter01/changelog.xml
View File

@ -36,6 +36,16 @@
</listitem> </listitem>
--> -->
<listitem>
<para>2008-10-23</para>
<itemizedlist>
<listitem>
<para>[dj] - Updated Man-DB instructions and text covering manual
pages and related i18n issues.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem> <listitem>
<para>2008-10-22</para> <para>2008-10-22</para>
<itemizedlist> <itemizedlist>

201
chapter06/man-db.xml
View File

@ -48,41 +48,18 @@
the <filename>man_db.conf</filename> file to prevent redundant results the <filename>man_db.conf</filename> file to prevent redundant results
when using programs such as <command>whatis</command>:</para> --> when using programs such as <command>whatis</command>:</para> -->
<para>Use a <command>sed</command> substitution to delete <para>LFS creates <filename>/usr/man</filename> and
the <quote>/usr/man</quote> and <quote>/usr/local/man</quote> lines in <filename>/usr/local/man</filename> as symlinks. Remove them from the
the <filename>man_db.conf</filename> file to prevent redundant results <filename>man_db.conf</filename> file to prevent redundant
when using programs such as <command>whatis</command>:</para> 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> <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> <para>Prepare Man-DB for compilation:</para>
<screen><userinput remap="configure">./configure --prefix=/usr --libexecdir=/usr/lib --sysconfdir=/etc \ <screen><userinput remap="configure">./configure --prefix=/usr --libexecdir=/usr/lib \
--disable-setuid --with-browser=/usr/bin/lynx \ --sysconfdir=/etc --disable-setuid \
--enable-mb-groff --with-browser=/usr/bin/lynx \
--with-col=/usr/bin/col --with-vgrind=/usr/bin/vgrind \ --with-col=/usr/bin/col --with-vgrind=/usr/bin/vgrind \
--with-grap=/usr/bin/grap</userinput></screen> --with-grap=/usr/bin/grap</userinput></screen>
@ -97,18 +74,28 @@ EOF</userinput></screen>
</listitem> </listitem>
</varlistentry> </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> <varlistentry>
<term><parameter>--with-...</parameter></term> <term><parameter>--with-...</parameter></term>
<listitem> <listitem>
<para>These four parameters are used to set some default programs. <para>These four parameters are used to set some default programs.
The <command>col</command> program is a part of the Util-linux-ng 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 package, <command>lynx</command> is a text-based web browser (see
for installation instructions), <command>vgrind</command> converts BLFS for installation instructions), <command>vgrind</command>
program sources to Groff input, and <command>grap</command> is useful converts program sources to Groff input, and <command>grap</command>
for typesetting graphs in Groff documents. The <command>vgrind</command> is useful for typesetting graphs in Groff documents. The
and <command>grap</command> programs are not normally needed for viewing <command>vgrind</command> and <command>grap</command> programs are
manual pages. They are not part of LFS or BLFS, but you should be able not normally needed for viewing manual pages. They are not part of
to install them yourself after finishing LFS if you wish to do so.</para> LFS or BLFS, but you should be able to install them yourself after
finishing LFS if you wish to do so.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -124,15 +111,15 @@ EOF</userinput></screen>
<screen><userinput remap="install">make install</userinput></screen> <screen><userinput remap="install">make install</userinput></screen>
<para>Some packages provide UTF-8 man pages which this version of <para>Some packages provide UTF-8 manual pages, which previous versions of
<command>man</command> is unable to display. The following script will <application>Man-DB</application> were unable to display. This limitation
allow some of these to be converted into the expected encodings shown in has been fixed in recent versions, and <application>Man-DB</application>
the table below. Man-DB expects the manual pages to be in the encodings can now convert manual pages from legacy encodings to UTF-8
in the table, and will convert them as necessary to the actual locale (and vice-versa) on the fly. This used to be a rather annoying
encoding when it displays them, so that they will display in both UTF-8 problem across different distributions, as packages written for one
and traditional locales. Because this script is intended for limited use distribution would require changes to work on another. The following
during the system build, for public data, we will not bother with error script will allow you to convert manual pages to and from legacy and UTF-8
checking, nor use a non-predictable temporary file name:</para> encodings.</para>
<screen><userinput remap="install">cat &gt;&gt; convert-mans &lt;&lt; "EOF" <screen><userinput remap="install">cat &gt;&gt; convert-mans &lt;&lt; "EOF"
<literal>#!/bin/sh -e <literal>#!/bin/sh -e
@ -160,24 +147,39 @@ install -m755 convert-mans /usr/bin</userinput></screen>
<para>Linux distributions have different policies concerning the character <para>Linux distributions have different policies concerning the character
encoding in which manual pages are stored in the filesystem. E.g., RedHat 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 stores all manual pages in UTF-8, while Debian previously used
(mostly 8-bit) encodings. This leads to incompatibility of packages with language-specific (mostly 8-bit) encodings. As mentioned above, this leads
manual pages designed for different distributions.</para> to incompatibility of packages with manual pages designed for different
distributions.</para>
<para>LFS uses the same conventions as Debian. This was chosen because <para>LFS previously used the same convention as Debian. This was chosen
Man-DB does not understand man pages stored in UTF-8. And, for our because <application>Man-DB</application> did not understand manual pages
purposes, Man-DB is preferable to Man as it works without extra stored in UTF-8 at the time of its introduction into LFS. For our purposes
configuration in any locale. Lastly, as of now, there is no fully-working at that time, <application>Man-DB</application> was preferable to
implementation of the RedHat convention. RedHat's <command>groff</command> <application>Man</application> as it worked without any additional
is known to misformat text.</para> configuration in any locale. This is still true today as
<application>Man-DB</application> with Debian patched
<application>Groff</application> will now dynamically convert UTF-8 encoded
manual pages to the user's locale. Additionally, this combination provides
support for Chinese and Japanese locales, and limited support for Korean,
whereas <application>Man</application> does not. The current offering of
<application>Man</application> as used in RedHat requires major
modifications to both the <application>Man</application> and
<application>Groff</application> packages, and still falls short on
Chinese, Japanese, and Korean encodings.</para>
<para>Finally, most distributions, including Debian, are rapidly migrating
to all UTF-8 encoded manual pages. Upstream packagers will very likely drop
legacy encodings in favor of UTF-8, though adoption has been slow due to
the hacks required to make the current <application>Man</application> and
<application>Groff</application> packages work correctly together.</para>
<para>The relationship between language codes and the expected encoding <para>The relationship between language codes and the expected encoding
of manual pages is listed below. Man-DB automatically converts them to of legacy manual pages is listed below.</para>
the locale encoding while viewing.</para>
<!-- Origin: man-db-2.4.3/src/encodings.c --> <!-- Origin: man-db-2.5.2/src/encodings.c -->
<table> <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" ?> <?dbfo table-width="2.5in" ?>
<tgroup cols="2"> <tgroup cols="2">
@ -257,6 +259,10 @@ install -m755 convert-mans /usr/bin</userinput></screen>
<entry>ISO-8859-1</entry> <entry>ISO-8859-1</entry>
</row> </row>
<!-- Languages below require patched groff --> <!-- Languages below require patched groff -->
<row>
<entry>Bulgarian (bg)</entry>
<entry>CP1251</entry>
</row>
<row> <row>
<entry>Czech (cs)</entry> <entry>Czech (cs)</entry>
<entry>ISO-8859-2</entry> <entry>ISO-8859-2</entry>
@ -289,10 +295,30 @@ install -m755 convert-mans /usr/bin</userinput></screen>
<entry>Slovak (sk)</entry> <entry>Slovak (sk)</entry>
<entry>ISO-8859-2</entry> <entry>ISO-8859-2</entry>
</row> </row>
<row>
<entry>Serbian (sr)</entry>
<entry>ISO-8859-5</entry>
</row>
<row> <row>
<entry>Turkish (tr)</entry> <entry>Turkish (tr)</entry>
<entry>ISO-8859-9</entry> <entry>ISO-8859-9</entry>
</row> </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> </tbody>
</tgroup> </tgroup>
@ -301,28 +327,35 @@ install -m755 convert-mans /usr/bin</userinput></screen>
<note> <note>
<para>Manual pages in languages not in the list are not supported. <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 Norwegian does not work because of the transition from no_NO to
nb_NO locale, and Korean is non-functional because of the incomplete nb_NO locale, and will be fixed in the next release of
Groff patch.</para> <application>Man-DB</application>. Korean is currently non functional
because of incomplete fixes in the Groff patch.</para>
</note> </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 <para>If upstream distributes the manual pages in a legacy encoding,
cp -rv man? /usr/share/man/fr</userinput></screen> 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 <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 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 can either be converted from UTF-8 to the encoding listed in the table
installation. This can be achieved with <command>convert-mans</command>, above, or they can be installed directly into
e.g., Spanish manual pages (<ulink <filename class="directory">/usr/share/man/<replaceable>&lt;language
url="http://ditec.um.es/~piernas/manpages-es/man-pages-es-1.55.tar.bz2"/>) code&gt;</replaceable>.UTF-8</filename>.</para>
can be installed with the following commands:</para>
<para>For example, to install <ulink
url="http://ditec.um.es/~piernas/manpages-es/man-pages-es-1.55.tar.bz2">
Spanish manual pages</ulink> in the legacy encoding, use the following
commands:</para>
<screen role="nodump"><userinput>mv man7/iso_8859-7.7{,X} <screen role="nodump"><userinput>mv man7/iso_8859-7.7{,X}
convert-mans UTF-8 ISO-8859-1 man?/*.? convert-mans UTF-8 ISO-8859-1 man?/*.?
@ -330,12 +363,20 @@ mv man7/iso_8859-7.7{X,}
make install</userinput></screen> make install</userinput></screen>
<note> <note>
<para>The need to exclude the <filename>man7/iso_8859-7.7</filename> file <para>The <filename>man7/iso_8859-7.7</filename> file needs to be
from the conversion process because it is already in ISO-8859-1 is a exclueded from the conversion process because it is already in
packaging bug in man-pages-es-1.55. Future versions should not require ISO-8859-1 format. This is a packaging bug in man-pages-es-1.55.
this workaround.</para> Future versions should not require this workaround.</para>
</note> </note>
<para>Finally, as an example installation of UTF-8 manual pages, the <ulink
url="http://manpagesfr.free.fr/download/man-pages-fr-2.40.0.tar.bz2">
French manual pages</ulink> can 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>
<sect2 id="contents-man-db" role="content"> <sect2 id="contents-man-db" role="content">
@ -391,7 +432,7 @@ make install</userinput></screen>
<varlistentry id="convert-mans"> <varlistentry id="convert-mans">
<term><command>convert-mans</command></term> <term><command>convert-mans</command></term>
<listitem> <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"> <indexterm zone="ch-system-man-db convert-mans">
<primary sortas="b-convert-mans">convert-mans</primary> <primary sortas="b-convert-mans">convert-mans</primary>
</indexterm> </indexterm>

4
general.ent
View File

@ -1,6 +1,6 @@
<?xml version="1.0" encoding="ISO-8859-1"?> <?xml version="1.0" encoding="ISO-8859-1"?>
<!ENTITY version "SVN-20081022"> <!ENTITY version "SVN-20081023">
<!ENTITY releasedate "October 22, 2008"> <!ENTITY releasedate "October 23, 2008">
<!ENTITY copyrightdate "1999&ndash;2008"> <!ENTITY copyrightdate "1999&ndash;2008">
<!ENTITY milestone "7.0"> <!ENTITY milestone "7.0">
<!ENTITY generic-version "development"> <!-- Use "development", "testing", or "x.y[-pre{x}]" --> <!ENTITY generic-version "development"> <!-- Use "development", "testing", or "x.y[-pre{x}]" -->