source: chapter06/man-db.xml@ 6a902c0

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.4 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 6a902c0 was 0445a3d, checked in by Manuel Canales Esparcia <manuel@…>, 17 years ago

Added remap attributes to userinput tags in packages pages.

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

  • Property mode set to 100644
File size: 15.8 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>Four adjustments need to be made to the sources of Man-DB.</para>
45
46 <para>The first one changes the location of translated manual pages that come
47 with Man-DB, in order for them to be accessible in both traditional and
48 UTF-8 locales:</para>
49
50<screen><userinput remap="pre">mv man/de{_DE.88591,}
51mv man/es{_ES.88591,}
52mv man/it{_IT.88591,}
53mv man/ja{_JP.eucJP,}
54sed -i 's,\*_\*,??,' man/Makefile.in</userinput></screen>
55
56 <para>The second change is a <command>sed</command> substitution to delete
57 the <quote>/usr/man</quote> and <quote>/usr/local/man</quote> lines in
58 the <filename>man_db.conf</filename> file to prevent redundant results
59 when using programs such as <command>whatis</command>:</para>
60
61<screen><userinput remap="pre">sed -i -e '\%\t/usr/man%d' -e '\%\t/usr/local/man%d' src/man_db.conf.in</userinput></screen>
62
63 <para>The third change accounts for programs that Man-DB should be able
64 to find at runtime, but that haven't been installed yet:</para>
65
66<screen><userinput remap="pre">cat &gt;&gt; include/manconfig.h.in &lt;&lt; "EOF"
67<literal>#define WEB_BROWSER "exec /usr/bin/lynx"
68#define COL "/usr/bin/col"
69#define VGRIND "/usr/bin/vgrind"
70#define GRAP "/usr/bin/grap"</literal>
71EOF</userinput></screen>
72
73 <para>The <command>col</command> program is a part of the Util-linux
74 package, <command>lynx</command> is a text-based web browser (see BLFS
75 for installation instructions), <command>vgrind</command> converts
76 program sources to Groff input, and <command>grap</command> is useful
77 for typesetting graphs in Groff documents. The <command>vgrind</command>
78 and <command>grap</command> programs are not normally needed for viewing
79 manual pages. They are not part of LFS or BLFS, but you should be able
80 to install them yourself after finishing LFS if you wish to do so.</para>
81
82 <para>Finally, patch the sources to fix output errors if the man page is
83 prematurely aborted by pressing the 'q' key:</para>
84
85<screen><userinput remap="pre">patch -Np1 -i ../&man-db-fixes-patch;</userinput></screen>
86
87 <para>Prepare Man-DB for compilation:</para>
88
89<screen><userinput remap="configure">./configure --prefix=/usr --enable-mb-groff --disable-setuid</userinput></screen>
90
91 <variablelist>
92 <title>The meaning of the configure options:</title>
93
94 <varlistentry>
95 <term><parameter>--enable-mb-groff</parameter></term>
96 <listitem>
97 <para>This tells the <command>man</command> program to use the
98 <quote>ascii8</quote> and <quote>nippon</quote> Groff devices for
99 formatting non-ISO-8859-1 manual pages.</para>
100 </listitem>
101 </varlistentry>
102
103 <varlistentry>
104 <term><parameter>--disable-setuid</parameter></term>
105 <listitem>
106 <para>This disables making the <command>man</command> program setuid
107 to user <systemitem class="username">man</systemitem>.</para>
108 </listitem>
109 </varlistentry>
110
111 </variablelist>
112
113 <para>Compile the package:</para>
114
115<screen><userinput remap="make">make</userinput></screen>
116
117 <para>This package does not come with a test suite.</para>
118
119 <para>Install the package:</para>
120
121<screen><userinput remap="install">make install</userinput></screen>
122
123 <para>Some packages provide UTF-8 man pages which this version of
124 <command>man</command> is unable to display. The following script will
125 allow some of these to be converted into the expected encodings shown in
126 the table below. Man-DB expects the manual pages to be in the encodings
127 in the table, and will convert them as necessary to the actual locale
128 encoding when it displays them, so that they will display in both UTF-8
129 and traditional locales. Because this script is intended for limited use
130 during the system build, for public data, we will not bother with error
131 checking, nor use a non-predictable temporary file name:</para>
132
133<screen><userinput remap="install">cat &gt;&gt; convert-mans &lt;&lt; "EOF"
134<literal>#!/bin/sh -e
135FROM="$1"
136TO="$2"
137shift ; shift
138while [ $# -gt 0 ]
139do
140 FILE="$1"
141 shift
142 iconv -f "$FROM" -t "$TO" "$FILE" >.tmp.iconv
143 mv .tmp.iconv "$FILE"
144done</literal>
145EOF
146install -m755 convert-mans /usr/bin</userinput></screen>
147
148 <para>Additional information regarding the compression of
149 man and info pages can be found in the BLFS book at
150 <ulink url="&blfs-root;view/cvs/postlfs/compressdoc.html"/>.</para>
151
152 </sect2>
153
154 <sect2>
155 <title>Non-English Manual Pages in LFS</title>
156
157 <para>Linux distributions have different policies concerning the character
158 encoding in which manual pages are stored in the filesystem. E.g., RedHat
159 stores all manual pages in UTF-8, while Debian uses language-specific
160 (mostly 8-bit) encodings. This leads to incompatibility of packages with
161 manual pages designed for different distributions.</para>
162
163 <para>LFS uses the same conventions as Debian. This was chosen because
164 Man-DB does not understand man pages stored in UTF-8. And, for our
165 purposes, Man-DB is preferable to Man as it works without extra
166 configuration in any locale. Lastly, as of now, there is no fully-working
167 implementation of the RedHat convention. RedHat's <command>groff</command>
168 is known to misformat text.</para>
169
170 <para>The relationship between language codes and the expected encoding
171 of manual pages is listed below. Man-DB automatically converts them to
172 the locale encoding while viewing.</para>
173
174 <!-- Origin: man-db-2.4.3/src/encodings.c -->
175 <table>
176 <title>Expected character encoding of manual pages</title>
177 <?dbfo table-width="2.5in" ?>
178
179 <tgroup cols="2">
180
181 <colspec colnum="1" colwidth="1.5in"/>
182 <colspec colnum="2" colwidth="1in"/>
183
184 <thead>
185 <row>
186 <entry>Language (code)</entry>
187 <entry>Encoding</entry>
188 </row>
189 </thead>
190
191 <tbody>
192 <row>
193 <entry>Danish (da)</entry>
194 <entry>ISO-8859-1</entry>
195 </row>
196 <row>
197 <entry>German (de)</entry>
198 <entry>ISO-8859-1</entry>
199 </row>
200 <row>
201 <entry>English (en)</entry>
202 <entry>ISO-8859-1</entry>
203 </row>
204 <row>
205 <entry>Spanish (es)</entry>
206 <entry>ISO-8859-1</entry>
207 </row>
208 <row>
209 <entry>Finnish (fi)</entry>
210 <entry>ISO-8859-1</entry>
211 </row>
212 <row>
213 <entry>French (fr)</entry>
214 <entry>ISO-8859-1</entry>
215 </row>
216 <row>
217 <entry>Irish (ga)</entry>
218 <entry>ISO-8859-1</entry>
219 </row>
220 <row>
221 <entry>Galician (gl)</entry>
222 <entry>ISO-8859-1</entry>
223 </row>
224 <row>
225 <entry>Indonesian (id)</entry>
226 <entry>ISO-8859-1</entry>
227 </row>
228 <row>
229 <entry>Icelandic (is)</entry>
230 <entry>ISO-8859-1</entry>
231 </row>
232 <row>
233 <entry>Italian (it)</entry>
234 <entry>ISO-8859-1</entry>
235 </row>
236 <row>
237 <entry>Dutch (nl)</entry>
238 <entry>ISO-8859-1</entry>
239 </row>
240 <!-- FIXME: BUG: "no" is deprecated, should use "nb" or "nn" and
241 symlinks -->
242 <row>
243 <entry>Norwegian (no)</entry>
244 <entry>ISO-8859-1</entry>
245 </row>
246 <!-- END BUG -->
247 <row>
248 <entry>Portuguese (pt)</entry>
249 <entry>ISO-8859-1</entry>
250 </row>
251 <row>
252 <entry>Swedish (sv)</entry>
253 <entry>ISO-8859-1</entry>
254 </row>
255 <!-- Languages below require patched groff -->
256 <row>
257 <entry>Czech (cs)</entry>
258 <entry>ISO-8859-2</entry>
259 </row>
260 <row>
261 <entry>Croatian (hr)</entry>
262 <entry>ISO-8859-2</entry>
263 </row>
264 <row>
265 <entry>Hungarian (hu)</entry>
266 <entry>ISO-8859-2</entry>
267 </row>
268 <row>
269 <entry>Japanese (ja)</entry>
270 <entry>EUC-JP</entry>
271 </row>
272 <row>
273 <entry>Korean (ko)</entry>
274 <entry>EUC-KR</entry>
275 </row>
276 <row>
277 <entry>Polish (pl)</entry>
278 <entry>ISO-8859-2</entry>
279 </row>
280 <row>
281 <entry>Russian (ru)</entry>
282 <entry>KOI8-R</entry>
283 </row>
284 <row>
285 <entry>Slovak (sk)</entry>
286 <entry>ISO-8859-2</entry>
287 </row>
288 <row>
289 <entry>Turkish (tr)</entry>
290 <entry>ISO-8859-9</entry>
291 </row>
292 </tbody>
293
294 </tgroup>
295
296 </table>
297
298 <note>
299 <para>Manual pages in languages not in the list are not supported.
300 Norwegian doesn't work now because of the transition from no_NO to
301 nb_NO locale, and Korean is non-functional because of the incomplete
302 Groff patch.</para>
303 </note>
304
305 <para>If upstream distributes the manual pages in the same encoding
306 as Man-DB expects, the manual pages can be copied to
307 <filename class="directory">/usr/share/man/<replaceable>&lt;language
308 code&gt;</replaceable></filename>. E.g., French manual pages
309 (<ulink url="http://ccb.club.fr/man/man-fr-1.58.0.tar.bz2"/>) can be
310 installed with the following command:</para>
311
312<screen role="nodump"><userinput>mkdir -p /usr/share/man/fr
313cp -rv man? /usr/share/man/fr</userinput></screen>
314
315 <para>If upstream distributes manual pages in UTF-8 (i.e., <quote>for
316 RedHat</quote>) instead of the encoding listed in the table above, they
317 have to be converted from UTF-8 to the encoding listed in the table before
318 installation. This can be achieved with <command>convert-mans</command>,
319 e.g., Spanish manual pages (<ulink
320 url="http://ditec.um.es/~piernas/manpages-es/man-pages-es-1.55.tar.bz2"/>)
321 can be installed with the following commands:</para>
322
323<screen role="nodump"><userinput>mv man7/iso_8859-7.7{,X}
324convert-mans UTF-8 ISO-8859-1 man?/*.?
325mv man7/iso_8859-7.7{X,}
326make install</userinput></screen>
327
328 <note>
329 <para>The need to exclude the <filename>man7/iso_8859-7.7</filename> file
330 from the conversion process because it is already in ISO-8859-1 is a
331 packaging bug in man-pages-es-1.55. Future versions should not require
332 this workaround.</para>
333 </note>
334
335 </sect2>
336
337 <sect2 id="contents-man-db" role="content">
338 <title>Contents of Man-DB</title>
339
340 <segmentedlist>
341 <segtitle>Installed programs</segtitle>
342
343 <seglistitem>
344 <seg>accessdb, apropos, catman, convert-mans, lexgrog, man, mandb,
345 manpath, whatis, and zsoelim</seg>
346 </seglistitem>
347 </segmentedlist>
348
349 <variablelist>
350 <bridgehead renderas="sect3">Short Descriptions</bridgehead>
351 <?dbfo list-presentation="list"?>
352 <?dbhtml list-presentation="table"?>
353
354 <varlistentry id="accessdb">
355 <term><command>accessdb</command></term>
356 <listitem>
357 <para>Dumps the <command>whatis</command> database contents in
358 human-readable form</para>
359 <indexterm zone="ch-system-man-db accessdb">
360 <primary sortas="b-accessdb">accessdb</primary>
361 </indexterm>
362 </listitem>
363 </varlistentry>
364
365 <varlistentry id="apropos">
366 <term><command>apropos</command></term>
367 <listitem>
368 <para>Searches the <command>whatis</command> database and displays
369 the short descriptions of system commands that contain a given
370 string</para>
371 <indexterm zone="ch-system-man-db apropos">
372 <primary sortas="b-apropos">apropos</primary>
373 </indexterm>
374 </listitem>
375 </varlistentry>
376
377 <varlistentry id="catman">
378 <term><command>catman</command></term>
379 <listitem>
380 <para>Creates or updates the pre-formatted manual pages</para>
381 <indexterm zone="ch-system-man-db catman">
382 <primary sortas="b-catman">catman</primary>
383 </indexterm>
384 </listitem>
385 </varlistentry>
386
387 <varlistentry id="convert-mans">
388 <term><command>convert-mans</command></term>
389 <listitem>
390 <para>Reformat man pages so that Man-DB can display them</para>
391 <indexterm zone="ch-system-man-db convert-mans">
392 <primary sortas="b-convert-mans">convert-mans</primary>
393 </indexterm>
394 </listitem>
395 </varlistentry>
396
397 <varlistentry id="lexgrog">
398 <term><command>lexgrog</command></term>
399 <listitem>
400 <para>Displays one-line summary information about a given manual
401 page</para>
402 <indexterm zone="ch-system-man-db lexgrog">
403 <primary sortas="b-lexgrog">lexgrog</primary>
404 </indexterm>
405 </listitem>
406 </varlistentry>
407
408 <varlistentry id="man">
409 <term><command>man</command></term>
410 <listitem>
411 <para>Formats and displays the requested manual page</para>
412 <indexterm zone="ch-system-man-db man">
413 <primary sortas="b-man">man</primary>
414 </indexterm>
415 </listitem>
416 </varlistentry>
417
418 <varlistentry id="mandb">
419 <term><command>mandb</command></term>
420 <listitem>
421 <para>Creates or updates the <command>whatis</command> database</para>
422 <indexterm zone="ch-system-man-db mandb">
423 <primary sortas="b-mandb">mandb</primary>
424 </indexterm>
425 </listitem>
426 </varlistentry>
427
428 <varlistentry id="manpath">
429 <term><command>manpath</command></term>
430 <listitem>
431 <para>Displays the contents of $MANPATH or (if $MANPATH is not set)
432 a suitable search path based on the settings in man.conf and the
433 user's environment</para>
434 <indexterm zone="ch-system-man-db manpath">
435 <primary sortas="b-manpath">manpath</primary>
436 </indexterm>
437 </listitem>
438 </varlistentry>
439
440 <varlistentry id="whatis">
441 <term><command>whatis</command></term>
442 <listitem>
443 <para>Searches the <command>whatis</command> database and displays
444 the short descriptions of system commands that contain the given
445 keyword as a separate word</para>
446 <indexterm zone="ch-system-man-db whatis">
447 <primary sortas="b-whatis">whatis</primary>
448 </indexterm>
449 </listitem>
450 </varlistentry>
451
452 <varlistentry id="zsoelim">
453 <term><command>zsoelim</command></term>
454 <listitem>
455 <para>Reads files and replaces lines of the form <emphasis>.so
456 file</emphasis> by the contents of the mentioned
457 <emphasis>file</emphasis></para>
458 <indexterm zone="ch-system-man-db zsoelim">
459 <primary sortas="b-zsoelim">zsoelim</primary>
460 </indexterm>
461 </listitem>
462 </varlistentry>
463
464 </variablelist>
465
466 </sect2>
467
468</sect1>
Note: See TracBrowser for help on using the repository browser.