source: chapter06/man-db.xml@ f65c459

Last change on this file since f65c459 was f65c459, checked in by Jeremy Huntwork <jhuntwork@…>, 17 years ago

Merge r8333 to jh branch

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

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