source: chapter06/man-db.xml@ dd03426

Last change on this file since dd03426 was 28b40e2, checked in by Manuel Canales Esparcia <manuel@…>, 18 years ago

Finished the PDF fixes.

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

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