source: chapter06/man-db.xml@ 89c14a9a

10.0 10.0-rc1 10.1 10.1-rc1 11.0 11.0-rc1 11.0-rc2 11.0-rc3 11.1 11.1-rc1 11.2 11.2-rc1 11.3 11.3-rc1 12.0 12.0-rc1 12.1 12.1-rc1 6.5 6.6 6.7 6.8 7.0 7.1 7.2 7.3 7.4 7.5 7.5-systemd 7.6 7.6-systemd 7.7 7.7-systemd 7.8 7.8-systemd 7.9 7.9-systemd 8.0 8.1 8.2 8.3 8.4 9.0 9.1 arm bdubbs/gcc13 ml-11.0 multilib renodr/libudev-from-systemd s6-init trunk xry111/arm64 xry111/arm64-12.0 xry111/clfs-ng xry111/lfs-next xry111/loongarch xry111/loongarch-12.0 xry111/loongarch-12.1 xry111/mips64el xry111/pip3 xry111/rust-wip-20221008 xry111/update-glibc
Last change on this file since 89c14a9a was 89c14a9a, checked in by Matthew Burgess <matthew@…>, 15 years ago

Upgrade to Man-DB-2.5.4. Fixes #2356 and #2338.

git-svn-id: http://svn.linuxfromscratch.org/LFS/trunk/BOOK@8826 4aa44e1e-78dd-0310-a6d2-fbcd4c07a689

  • Property mode set to 100644
File size: 18.7 KB
Line 
1<?xml version="1.0" encoding="ISO-8859-1"?>
2<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4 <!ENTITY % general-entities SYSTEM "../general.ent">
5 %general-entities;
6]>
7
8<sect1 id="ch-system-man-db" role="wrap">
9 <?dbhtml filename="man-db.html"?>
10
11 <sect1info condition="script">
12 <productname>man-db</productname>
13 <productnumber>&man-db-version;</productnumber>
14 <address>&man-db-url;</address>
15 </sect1info>
16
17 <title>Man-DB-&man-db-version;</title>
18
19 <indexterm zone="ch-system-man-db">
20 <primary sortas="a-Man-DB">Man-DB</primary>
21 </indexterm>
22
23 <sect2 role="package">
24 <title/>
25
26 <para>The Man-DB package contains programs for finding and viewing man
27 pages.</para>
28
29 <segmentedlist>
30 <segtitle>&buildtime;</segtitle>
31 <segtitle>&diskspace;</segtitle>
32
33 <seglistitem>
34 <seg>&man-db-ch6-sbu;</seg>
35 <seg>&man-db-ch6-du;</seg>
36 </seglistitem>
37 </segmentedlist>
38
39 </sect2>
40
41 <sect2 role="installation">
42 <title>Installation of Man-DB</title>
43
44 <para>LFS creates <filename>/usr/man</filename> and
45 <filename>/usr/local/man</filename> as symlinks. Remove them from the
46 <filename>man_db.conf</filename> file to prevent redundant
47 results when using programs such as <command>whatis</command>:</para>
48
49<screen><userinput remap="pre">sed -i -e '\%\t/usr/man%d' -e '\%\t/usr/local/man%d' src/man_db.conf.in</userinput></screen>
50
51 <para>Prepare Man-DB for compilation:</para>
52
53<screen><userinput remap="configure">./configure --prefix=/usr --libexecdir=/usr/lib \
54 --sysconfdir=/etc --disable-setuid \
55 --with-browser=/usr/bin/lynx --with-col=/usr/bin/col \
56 --with-vgrind=/usr/bin/vgrind --with-grap=/usr/bin/grap</userinput></screen>
57
58 <variablelist>
59 <title>The meaning of the configure options:</title>
60
61 <varlistentry>
62 <term><parameter>--disable-setuid</parameter></term>
63 <listitem>
64 <para>This disables making the <command>man</command> program setuid
65 to user <systemitem class="username">man</systemitem>.</para>
66 </listitem>
67 </varlistentry>
68
69 <varlistentry>
70 <term><parameter>--with-...</parameter></term>
71 <listitem>
72 <para>These four parameters are used to set some default programs.
73 The <command>col</command> program is a part of the Util-linux-ng
74 package, <command>lynx</command> is a text-based web browser (see
75 BLFS for installation instructions), <command>vgrind</command>
76 converts program sources to Groff input, and <command>grap</command>
77 is useful for typesetting graphs in Groff documents. The
78 <command>vgrind</command> and <command>grap</command> programs are
79 not normally needed for viewing manual pages. They are not part of
80 LFS or BLFS, but you should be able to install them yourself after
81 finishing LFS if you wish to do so.</para>
82 </listitem>
83 </varlistentry>
84
85 </variablelist>
86
87 <para>Compile the package:</para>
88
89<screen><userinput remap="make">make</userinput></screen>
90
91 <para>This package does not come with a test suite.</para>
92
93 <para>Install the package:</para>
94
95<screen><userinput remap="install">make install</userinput></screen>
96
97 </sect2>
98
99 <sect2>
100 <title>Non-English Manual Pages in LFS</title>
101
102 <para>Some packages provide non-English manual pages. They are displayed
103 correctly only if their location and encoding matches the expectation of
104 the "man" program. However, different Linux distributions have different
105 policies (expressed in the choice of the <command>man</command> program,
106 its configuration and patches applied to it) concerning the character
107 encoding in which manual pages are stored in the filesystem.</para>
108
109 <para>E.g., Debian previously required Russian manual pages to be encoded
110 in KOI8-R and to be placed in
111 <filename class="directory">/usr/share/man/ru</filename>. Now, in addition,
112 their <command>man</command> program (<application>Man-DB</application>)
113 searches for UTF-8 encoded Russian manual pages in
114 <filename class="directory">/usr/share/man/ru.UTF-8</filename>. On the
115 other hand, Fedora uses UTF-8 encoded manual pages exclusively. Russian
116 manual pages are found in
117 <filename class="directory">/usr/share/man/ru</filename> and their
118 <command>man</command> program doesn't acknowledge
119 <filename class="directory">/usr/share/man/ru.UTF-8</filename>. Many
120 other distributions ignore the on disk encodings completely, leaving the
121 end user with a mix of improperly encoded manual pages for their
122 configuration. When <command>man</command> processes the requtested page,
123 it will display the contents as configured, resulting in completely
124 unreadable text if the on disk encoding is not what is expected for that
125 configuration.</para>
126
127 <para>Disagreement about the expected encoding of manual pages amongst
128 distribution vendors, has led to confusion for upstream package
129 maintainers. One package may contain UTF-8 manual pages, while another
130 ships with manual pages in legacy encodings. <command>man</command>
131 searches for manual pages based on the user's locale settings.
132 <application>Man-DB</application> uses a built-in table (see below) to
133 determine the on disk encoding of manual pages found for a user's
134 locale, only if the directories found do not have an extension that
135 describes the encoding. E.g., because of ".UTF-8" in the directory name,
136 <application>Man-DB</application> knows that all manual pages residing in
137 <filename class="directory">/usr/share/man/fr.UTF-8</filename> are UTF-8
138 encoded and, according to the built-in table, expects all manual pages
139 residing in <filename class="directory">/usr/share/man/ru</filename> to
140 be encoded using KOI8-R.</para>
141
142 <!-- Origin: man-db-2.5.2/src/encodings.c -->
143 <table>
144<title>Expected character encoding of legacy 8-bit manual pages</title>
145 <?dbfo table-width="6in" ?>
146
147 <tgroup cols="4">
148
149 <colspec colnum="1" colwidth="1.5in"/>
150 <colspec colnum="2" colwidth="1in"/>
151 <colspec colnum="3" colwidth="2.5in"/>
152 <colspec colnum="4" colwidth="1in"/>
153
154 <thead>
155 <row>
156 <entry>Language (code)</entry>
157 <entry>Encoding</entry>
158 <entry>Language (code)</entry>
159 <entry>Encoding</entry>
160 </row>
161 </thead>
162
163 <tbody>
164 <row>
165 <entry>Danish (da)</entry>
166 <entry>ISO-8859-1</entry>
167 <entry>Bulgarian (bg)</entry>
168 <entry>CP1251</entry>
169 </row>
170 <row>
171 <entry>German (de)</entry>
172 <entry>ISO-8859-1</entry>
173 <entry>Czech (cs)</entry>
174 <entry>ISO-8859-2</entry>
175 </row>
176 <row>
177 <entry>English (en)</entry>
178 <entry>ISO-8859-1</entry>
179 <entry>Croatian (hr)</entry>
180 <entry>ISO-8859-2</entry>
181 </row>
182 <row>
183 <entry>Spanish (es)</entry>
184 <entry>ISO-8859-1</entry>
185 <entry>Hungarian (hu)</entry>
186 <entry>ISO-8859-2</entry>
187 </row>
188 <row>
189 <entry>Finnish (fi)</entry>
190 <entry>ISO-8859-1</entry>
191 <entry>Japanese (ja)</entry>
192 <entry>EUC-JP</entry>
193 </row>
194 <row>
195 <entry>French (fr)</entry>
196 <entry>ISO-8859-1</entry>
197 <entry>Korean (ko)</entry>
198 <entry>EUC-KR</entry>
199 </row>
200 <row>
201 <entry>Irish (ga)</entry>
202 <entry>ISO-8859-1</entry>
203 <entry>Polish (pl)</entry>
204 <entry>ISO-8859-2</entry>
205 </row>
206 <row>
207 <entry>Galician (gl)</entry>
208 <entry>ISO-8859-1</entry>
209 <entry>Russian (ru)</entry>
210 <entry>KOI8-R</entry>
211 </row>
212 <row>
213 <entry>Indonesian (id)</entry>
214 <entry>ISO-8859-1</entry>
215 <entry>Slovak (sk)</entry>
216 <entry>ISO-8859-2</entry>
217 </row>
218 <row>
219 <entry>Icelandic (is)</entry>
220 <entry>ISO-8859-1</entry>
221 <entry>Serbian (sr)</entry>
222 <entry>ISO-8859-5</entry>
223 </row>
224 <row>
225 <entry>Italian (it)</entry>
226 <entry>ISO-8859-1</entry>
227 <entry>Turkish (tr)</entry>
228 <entry>ISO-8859-9</entry>
229 </row>
230 <row>
231 <entry>Dutch (nl)</entry>
232 <entry>ISO-8859-1</entry>
233 <entry>Simplified Chinese (zh_CN)</entry>
234 <entry>GBK</entry>
235 </row>
236 <!-- FIXME: BUG: "no" is deprecated, should use "nb" or "nn" and
237 symlinks -->
238 <row>
239 <entry>Norwegian (no)</entry>
240 <entry>ISO-8859-1</entry>
241 <entry>Simplified Chinese, Singapore (zh_SG)</entry>
242 <entry>GBK</entry>
243 </row>
244 <!-- END BUG -->
245 <row>
246 <entry>Portuguese (pt)</entry>
247 <entry>ISO-8859-1</entry>
248 <entry>Traditional Chinese (zh_TW)</entry>
249 <entry>BIG5</entry>
250 </row>
251 <row>
252 <entry>Swedish (sv)</entry>
253 <entry>ISO-8859-1</entry>
254 <entry>Traditional Chinese, Hong Kong (zh_HK)</entry>
255 <entry>BIG5HKSCS</entry>
256 </row>
257
258 <!-- Languages below require patched groff -->
259 <!--
260 <row>
261 <entry>Bulgarian (bg)</entry>
262 <entry>CP1251</entry>
263 </row>
264 <row>
265 <entry>Czech (cs)</entry>
266 <entry>ISO-8859-2</entry>
267 </row>
268 <row>
269 <entry>Croatian (hr)</entry>
270 <entry>ISO-8859-2</entry>
271 </row>
272 <row>
273 <entry>Hungarian (hu)</entry>
274 <entry>ISO-8859-2</entry>
275 </row>
276 <row>
277 <entry>Japanese (ja)</entry>
278 <entry>EUC-JP</entry>
279 </row>
280 <row>
281 <entry>Korean (ko)</entry>
282 <entry>EUC-KR</entry>
283 </row>
284 <row>
285 <entry>Polish (pl)</entry>
286 <entry>ISO-8859-2</entry>
287 </row>
288 <row>
289 <entry>Russian (ru)</entry>
290 <entry>KOI8-R</entry>
291 </row>
292 <row>
293 <entry>Slovak (sk)</entry>
294 <entry>ISO-8859-2</entry>
295 </row>
296 <row>
297 <entry>Serbian (sr)</entry>
298 <entry>ISO-8859-5</entry>
299 </row>
300 <row>
301 <entry>Turkish (tr)</entry>
302 <entry>ISO-8859-9</entry>
303 </row>
304 <row>
305 <entry>Simplified Chinese (zh_CN)</entry>
306 <entry>GBK</entry>
307 </row>
308 <row>
309 <entry>Simplified Chinese, Singapore (zh_SG)</entry>
310 <entry>GBK</entry>
311 </row>
312 <row>
313 <entry>Traditional Chinese (zh_TW)</entry>
314 <entry>BIG5</entry>
315 </row>
316 <row>
317 <entry>Traditional Chinese, Hong Kong (zh_HK)</entry>
318 <entry>BIG5HKSCS</entry>
319 </row>-->
320 </tbody>
321
322 </tgroup>
323
324 </table>
325
326 <note>
327 <para>Manual pages in languages not in the list are not supported.
328 Norwegian does not work because of the transition from no_NO to
329 nb_NO locale, and will be fixed in the next release of
330 <application>Man-DB</application>. Korean is currently non functional
331 because of incomplete fixes in the Debian
332 <application>Groff</application> patch applied in LFS.</para>
333 </note>
334
335 <para>Packages may install manual pages into an improperly named directory,
336 depending on which distributions the author develops the package for. To
337 assist in the conversion of the manual pages to the proper encoding for the
338 directory in which they are installed, the <command>convert-mans</command>
339 script was written. It will convert manual pages to another encoding before
340 (or after) installation. Install the <command>convert-mans</command>
341 script with the following instructions:</para>
342
343<screen><userinput remap="install">cat &gt;&gt; convert-mans &lt;&lt; "EOF"
344<literal>#!/bin/sh -e
345FROM="$1"
346TO="$2"
347shift ; shift
348while [ $# -gt 0 ]
349do
350 FILE="$1"
351 shift
352 iconv -f "$FROM" -t "$TO" "$FILE" >.tmp.iconv
353 mv .tmp.iconv "$FILE"
354done</literal>
355EOF
356install -v -m755 convert-mans /usr/bin</userinput></screen>
357
358
359 <para>If upstream distributes the manual pages in a legacy encoding, the
360 manual pages can simply be copied to
361 <filename class="directory">/usr/share/man/<replaceable>&lt;language
362 code&gt;</replaceable></filename>. For example, <ulink
363 url="http://www.infodrom.org/projects/manpages-de/download/manpages-de-0.5.tar.gz">
364 German manual pages</ulink> can be installed with the following
365 commands:</para>
366
367<screen role="nodump"><userinput>mkdir -p /usr/share/man/de
368cp -rv man? /usr/share/man/de</userinput></screen>
369
370 <para>If upstream distributes manual pages in UTF-8 (i.e., <quote>for
371 RedHat</quote>) instead of the encoding listed in the table above, they
372 can either be converted from UTF-8 to the encoding listed in the table
373 above, or they can be installed directly into
374 <filename class="directory">/usr/share/man/<replaceable>&lt;language
375 code&gt;</replaceable>.UTF-8</filename>.</para>
376
377 <para>For example, to install <ulink
378 url="http://manpagesfr.free.fr/download/man-pages-fr-2.40.0.tar.bz2">
379 French manual pages</ulink> in the legacy encoding, use the following
380 commands:</para>
381
382<screen role="nodump"><userinput>convert-mans UTF-8 ISO-8859-1 man?/*.?
383mkdir -p /usr/share/man/fr
384cp -rv man? /usr/share/man/fr</userinput></screen>
385
386 <note><para>The French manual pages ship with ready made scripts to do the
387 same conversion. The above instructions are used only as an example for
388 use of the <command>convert-mans</command> script.</para></note>
389
390 <para>Finally, as an example installation of UTF-8 manual pages, again, the
391 French manual pages could be installed with the following commands:</para>
392
393<screen role="nodump"><userinput>mkdir -p /usr/share/man/fr.UTF-8
394cp -rv man? /usr/share/man/fr.UTF-8</userinput></screen>
395
396 </sect2>
397
398 <sect2 id="contents-man-db" role="content">
399 <title>Contents of Man-DB</title>
400
401 <segmentedlist>
402 <segtitle>Installed programs</segtitle>
403
404 <seglistitem>
405 <seg>apropos, catman, convert-mans, lexgrog, man, mandb,
406 manpath, whatis, and zsoelim</seg>
407 </seglistitem>
408 </segmentedlist>
409
410 <variablelist>
411 <bridgehead renderas="sect3">Short Descriptions</bridgehead>
412 <?dbfo list-presentation="list"?>
413 <?dbhtml list-presentation="table"?>
414
415 <!-- <varlistentry id="accessdb">
416 <term><command>accessdb</command></term>
417 <listitem>
418 <para>Dumps the <command>whatis</command> database contents in
419 human-readable form</para>
420 <indexterm zone="ch-system-man-db accessdb">
421 <primary sortas="b-accessdb">accessdb</primary>
422 </indexterm>
423 </listitem>
424 </varlistentry> -->
425
426 <varlistentry id="apropos">
427 <term><command>apropos</command></term>
428 <listitem>
429 <para>Searches the <command>whatis</command> database and displays
430 the short descriptions of system commands that contain a given
431 string</para>
432 <indexterm zone="ch-system-man-db apropos">
433 <primary sortas="b-apropos">apropos</primary>
434 </indexterm>
435 </listitem>
436 </varlistentry>
437
438 <varlistentry id="catman">
439 <term><command>catman</command></term>
440 <listitem>
441 <para>Creates or updates the pre-formatted manual pages</para>
442 <indexterm zone="ch-system-man-db catman">
443 <primary sortas="b-catman">catman</primary>
444 </indexterm>
445 </listitem>
446 </varlistentry>
447
448 <varlistentry id="convert-mans">
449 <term><command>convert-mans</command></term>
450 <listitem>
451 <para>Reformats manual pages into the chosen encoding.</para>
452 <indexterm zone="ch-system-man-db convert-mans">
453 <primary sortas="b-convert-mans">convert-mans</primary>
454 </indexterm>
455 </listitem>
456 </varlistentry>
457
458 <varlistentry id="lexgrog">
459 <term><command>lexgrog</command></term>
460 <listitem>
461 <para>Displays one-line summary information about a given manual
462 page</para>
463 <indexterm zone="ch-system-man-db lexgrog">
464 <primary sortas="b-lexgrog">lexgrog</primary>
465 </indexterm>
466 </listitem>
467 </varlistentry>
468
469 <varlistentry id="man">
470 <term><command>man</command></term>
471 <listitem>
472 <para>Formats and displays the requested manual page</para>
473 <indexterm zone="ch-system-man-db man">
474 <primary sortas="b-man">man</primary>
475 </indexterm>
476 </listitem>
477 </varlistentry>
478
479 <varlistentry id="mandb">
480 <term><command>mandb</command></term>
481 <listitem>
482 <para>Creates or updates the <command>whatis</command> database</para>
483 <indexterm zone="ch-system-man-db mandb">
484 <primary sortas="b-mandb">mandb</primary>
485 </indexterm>
486 </listitem>
487 </varlistentry>
488
489 <varlistentry id="manpath">
490 <term><command>manpath</command></term>
491 <listitem>
492 <para>Displays the contents of $MANPATH or (if $MANPATH is not set)
493 a suitable search path based on the settings in man.conf and the
494 user's environment</para>
495 <indexterm zone="ch-system-man-db manpath">
496 <primary sortas="b-manpath">manpath</primary>
497 </indexterm>
498 </listitem>
499 </varlistentry>
500
501 <varlistentry id="whatis">
502 <term><command>whatis</command></term>
503 <listitem>
504 <para>Searches the <command>whatis</command> database and displays
505 the short descriptions of system commands that contain the given
506 keyword as a separate word</para>
507 <indexterm zone="ch-system-man-db whatis">
508 <primary sortas="b-whatis">whatis</primary>
509 </indexterm>
510 </listitem>
511 </varlistentry>
512
513 <varlistentry id="zsoelim">
514 <term><command>zsoelim</command></term>
515 <listitem>
516 <para>Reads files and replaces lines of the form <emphasis>.so
517 file</emphasis> by the contents of the mentioned
518 <emphasis>file</emphasis></para>
519 <indexterm zone="ch-system-man-db zsoelim">
520 <primary sortas="b-zsoelim">zsoelim</primary>
521 </indexterm>
522 </listitem>
523 </varlistentry>
524
525 </variablelist>
526
527 </sect2>
528
529</sect1>
Note: See TracBrowser for help on using the repository browser.