From 7f89db8a15fbc62c9ca23d042ef69089e748d3f6 Mon Sep 17 00:00:00 2001 From: DJ Lucas Date: Sat, 25 Oct 2008 21:31:14 +0000 Subject: [PATCH] Updated Man-DB text to account for recent Man-DB development. Many thanks to Alexander Patrakov for patientely guiding me through this. git-svn-id: http://svn.linuxfromscratch.org/LFS/trunk/BOOK@8698 4aa44e1e-78dd-0310-a6d2-fbcd4c07a689 --- chapter01/changelog.xml | 11 +++ chapter06/man-db.xml | 194 ++++++++++++++++++++++++---------------- 2 files changed, 129 insertions(+), 76 deletions(-) diff --git a/chapter01/changelog.xml b/chapter01/changelog.xml index d49e66e4e..36071d7e2 100644 --- a/chapter01/changelog.xml +++ b/chapter01/changelog.xml @@ -36,6 +36,17 @@ --> + + 2008-10-25 + + + [dj] - Updated the text on the Man-DB page to accout for recent + changes in Man-DB. Thanks to Alexander Patrakov for providing most + of the included text, explanations, and examples. + + + + 2008-10-23 diff --git a/chapter06/man-db.xml b/chapter06/man-db.xml index 5be9fa4e1..729abbaf7 100644 --- a/chapter06/man-db.xml +++ b/chapter06/man-db.xml @@ -111,71 +111,95 @@ make install - 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 -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 - . - Non-English Manual Pages in LFS + + 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 man program, + its configuration and patches applied to it) concerning the character + encoding in which manual pages are stored in the filesystem. - The relationship between language codes and the expected encoding - of legacy manual pages is listed below. + E.g., Debian previously required Russian manual pages to be encoded + in KOI8-R and to be placed in + /usr/share/man/ru. Now, in addition, + their man program (Man-DB) + searches for UTF-8 encoded Russian manual pages in + /usr/share/man/ru.UTF-8. On the + other hand, Fedora uses UTF-8 encoded manual pages exclusively. Russian + manual pages are found in + /usr/share/man/ru and their + man program doesn't acknowledge + /usr/share/man/ru.UTF-8. 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 man 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. + + 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. man + searches for manual pages based on the user's locale settings. + Man-DB 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, + Man-DB knows that all manual pages residing in + /usr/share/man/fr.UTF-8 are UTF-8 + encoded and, according to the built-in table, expects all manual pages + residing in /usr/share/man/ru to + be encoded using KOI8-R. @@ -308,7 +332,7 @@ install -m755 convert-mans /usr/binGBK - Simplified Chinese,Singapore} (zh_SG) + Simplified Chinese, Singapore (zh_SG) GBK @@ -330,12 +354,36 @@ install -m755 convert-mans /usr/bin 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. + because of incomplete fixes in the Debian + Groff patch applied in LFS. + 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 convert-mans + script was written. It will convert manual pages to another encoding before + (or after) installation. Install the convert-mans + script with the following instructions: - If upstream distributes the manual pages in a legacy encoding, - the manual pages can simply be copied to +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 + + + If upstream distributes the manual pages in a legacy encoding, the + manual pages can simply be copied to /usr/share/man/<language code>. For example, @@ -353,27 +401,21 @@ cp -rv man? /usr/share/man/de 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?/*.? -mv man7/iso_8859-7.7{X,} -make install - - - 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 + French manual pages in the legacy encoding, use the following commands: +convert-mans UTF-8 ISO-8859-1 man?/*.? +mkdir -p /usr/share/man/fr +cp -rv man? /usr/share/man/fr + + 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 convert-mans script. + + Finally, as an example installation of UTF-8 manual pages, again, the + French manual pages could be installed with the following commands: + mkdir -p /usr/share/man/fr.UTF-8 cp -rv man? /usr/share/man/fr.UTF-8