From 862c5aedfdbfb0dfccd43d28bbb0ffe8cdb3928d Mon Sep 17 00:00:00 2001 From: DJ Lucas Date: Thu, 23 Oct 2008 04:32:05 +0000 Subject: Updated text and instructions on man-db page. git-svn-id: http://svn.linuxfromscratch.org/LFS/trunk/BOOK@8694 4aa44e1e-78dd-0310-a6d2-fbcd4c07a689 --- chapter01/changelog.xml | 10 +++ chapter06/man-db.xml | 201 +++++++++++++++++++++++++++++------------------- general.ent | 4 +- 3 files changed, 133 insertions(+), 82 deletions(-) diff --git a/chapter01/changelog.xml b/chapter01/changelog.xml index 822ea4fce..81bd28169 100644 --- a/chapter01/changelog.xml +++ b/chapter01/changelog.xml @@ -36,6 +36,16 @@ --> + + 2008-10-23 + + + [dj] - Updated Man-DB instructions and text covering manual + pages and related i18n issues. + + + + 2008-10-22 diff --git a/chapter06/man-db.xml b/chapter06/man-db.xml index bb1fefced..5be9fa4e1 100644 --- a/chapter06/man-db.xml +++ b/chapter06/man-db.xml @@ -48,41 +48,18 @@ the man_db.conf file to prevent redundant results when using programs such as whatis: --> - Use a sed substitution to delete - the /usr/man and /usr/local/man lines in - the man_db.conf file to prevent redundant results - when using programs such as whatis: + LFS creates /usr/man and + /usr/local/man as symlinks. Remove them from the + man_db.conf file to prevent redundant + results when using programs such as whatis: sed -i -e '\%\t/usr/man%d' -e '\%\t/usr/local/man%d' src/man_db.conf.in - - Prepare Man-DB for compilation: -./configure --prefix=/usr --libexecdir=/usr/lib --sysconfdir=/etc \ - --disable-setuid --with-browser=/usr/bin/lynx \ +./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 @@ -97,18 +74,28 @@ EOF + + --enable-mb-groff + + This switch tells man-db to expect + the Debian multibyte patched version of + groff. + + + --with-... These four parameters are used to set some default programs. The col program is a part of the Util-linux-ng - 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. + 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. @@ -124,15 +111,15 @@ EOF 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: + Some packages provide UTF-8 manual pages, which previous versions of + Man-DB were unable to display. This limitation + has been fixed in recent versions, and Man-DB + can now convert manual pages from legacy encodings to UTF-8 + (and vice-versa) on the fly. This used to be a rather annoying + problem across different distributions, as packages written for one + distribution would require changes to work on another. The following + script will allow you to convert manual pages to and from legacy and UTF-8 + encodings. cat >> convert-mans << "EOF" #!/bin/sh -e @@ -160,24 +147,39 @@ install -m755 convert-mans /usr/bin 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. + stores all manual pages in UTF-8, while Debian previously used + language-specific (mostly 8-bit) encodings. As mentioned above, this leads + to incompatibility of packages with manual pages designed for different + distributions. + + LFS previously used the same convention as Debian. This was chosen + because Man-DB did not understand manual pages + stored in UTF-8 at the time of its introduction into LFS. For our purposes + at that time, Man-DB was preferable to + Man as it worked without any additional + configuration in any locale. This is still true today as + Man-DB with Debian patched + Groff 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 Man does not. The current offering of + Man as used in RedHat requires major + modifications to both the Man and + Groff packages, and still falls short on + Chinese, Japanese, and Korean encodings. + + 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 Man and + Groff packages work correctly together. 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. + of legacy manual pages is listed below. - + - Expected character encoding of manual pages + Expected character encoding of legacy 8-bit manual pages @@ -257,6 +259,10 @@ install -m755 convert-mans /usr/bin ISO-8859-1 + + Bulgarian (bg) + CP1251 + Czech (cs) ISO-8859-2 @@ -289,10 +295,30 @@ install -m755 convert-mans /usr/bin Slovak (sk) ISO-8859-2 + + Serbian (sr) + ISO-8859-5 + Turkish (tr) ISO-8859-9 + + Simplified Chinese (zh_CN) + GBK + + + Simplified Chinese,Singapore} (zh_SG) + GBK + + + Traditional Chinese (zh_TW) + BIG5 + + + Traditional Chinese, Hong Kong (zh_HK) + BIG5HKSCS + @@ -301,28 +327,35 @@ install -m755 convert-mans /usr/bin 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. + Norwegian does not work because of the transition from no_NO to + nb_NO locale, and will be fixed in the next release of + Man-DB. Korean is currently non functional + because of incomplete fixes in the Groff patch. - If upstream distributes the manual pages in the same encoding - as Man-DB expects, the manual pages can be copied to + + If upstream distributes the manual pages in a legacy encoding, + the manual pages can simply be copied to /usr/share/man/<language - code>. E.g., French manual pages - () can be - installed with the following command: + code>. For example, + German manual pages can be installed with the following + commands: -mkdir -p /usr/share/man/fr -cp -rv man? /usr/share/man/fr +mkdir -p /usr/share/man/de +cp -rv man? /usr/share/man/deIf 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 () - can be installed with the following commands: + can either be converted from UTF-8 to the encoding listed in the table + above, or they can be installed directly into + /usr/share/man/<language + code>.UTF-8. + + For example, to install + Spanish manual pages in the legacy encoding, use the following + commands:mv man7/iso_8859-7.7{,X} convert-mans UTF-8 ISO-8859-1 man?/*.? @@ -330,12 +363,20 @@ mv man7/iso_8859-7.7{X,} make install - 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. + The man7/iso_8859-7.7 file needs to be + exclueded from the conversion process because it is already in + ISO-8859-1 format. This is a packaging bug in man-pages-es-1.55. + Future versions should not require this workaround. + Finally, as an example installation of UTF-8 manual pages, the + French manual pages can be installed with the following + commands: + +mkdir -p /usr/share/man/fr.UTF-8 +cp -rv man? /usr/share/man/fr.UTF-8 + @@ -391,7 +432,7 @@ make install convert-mans - Reformat man pages so that Man-DB can display them + Reformats manual pages into the chosen encoding. convert-mans diff --git a/general.ent b/general.ent index ee1c48e36..f6c77b4e3 100644 --- a/general.ent +++ b/general.ent @@ -1,6 +1,6 @@ - - + + -- cgit v1.2.3-54-g00ecf