source: chapter06/man.xml@ b32e803

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../general.ent">
  %general-entities;
]>
<sect1 id="ch-system-man" xreflabel="Man">
<title>Man-&man-version;</title>
<?dbhtml filename="man.html"?>

<indexterm zone="ch-system-man"><primary sortas="a-Man">Man</primary></indexterm>

<para>The Man package contains programs for finding and viewing manual pages.</para>

<screen>&buildtime; 0.1 SBU
&diskspace; 1.9MB</screen>

<para>Man installation depends on: Bash, Binutils, Coreutils, Gawk, GCC,
Glibc, Grep, Make, Sed.</para>



<sect2>
<title>Installation of Man</title>

<para>We'll make three adjustments to the sources of Man.</para>

<para>The first is a patch which allows Man to work better with recent releases
of Groff. In particular, man pages will now display using the full terminal
width instead of being limited to 80 characters:</para>

<screen><userinput>patch -Np1 -i ../man-&man-version;-80cols-1.patch</userinput></screen>

<para>The second is a sed substitution to add the <emphasis>-R</emphasis>
switch to the <emphasis>PAGER</emphasis> variable so that escape sequences are
properly handled by Less:</para>

<screen><userinput>sed -i 's/-is/&amp;R/' configure</userinput></screen>

<para>The third is also a sed substitution to comment out the <quote>MANPATH
/usr/man</quote> line in the <filename>man.conf</filename> file to prevent
redundant results when using programs such as <command>whatis</command>:</para>

<screen><userinput>sed -i 's%MANPATH./usr/man%#&amp;%' src/man.conf.in</userinput></screen>
 
<para>Now prepare Man for compilation:</para>

<screen><userinput>./configure -default -confdir=/etc</userinput></screen>

<para>The meaning of the configure options:</para>

<itemizedlist>
<listitem><para><userinput>-default</userinput>: This tells the configure script
to select a sensible set of default options. For example: only English man
pages, no message catalogs, man not suid, handle compressed man pages, compress
cat pages, create cat pages whenever the appropriate directory exists, follow
FHS by putting cat pages under /var/cache/man (provided that directory
exists).</para></listitem>

<listitem><para><userinput>-confdir=/etc</userinput>: This tells the
<command>man</command> program to look for the <filename>man.conf</filename>
configuration file in the <filename>/etc</filename> directory.</para></listitem>
</itemizedlist>

<para>Compile the package:</para>

<screen><userinput>make</userinput></screen>

<para>Lastly, install it:</para>

<screen><userinput>make install</userinput></screen>

<note><para>If you wish to disable SGR (Select Graphic Rendition) escape sequences, you should edit the
<filename>man.conf</filename> file and add the <emphasis>-c</emphasis> switch
to NROFF.</para></note>

<para>If your character set uses 8-bit characters, search for the line
beginning with "NROFF" in /etc/man.conf, and verify that it coincides
with the following:</para>

<screen>NROFF  /usr/bin/nroff -Tlatin1 -mandoc</screen>

<para>Note that you should use "latin1" even if it is not the character set
of your locale. The reason is that,
according to the specification, <application>groff</application> has
no means of typesetting characters outside ISO-8859-1
without some strange escape codes, and localized manual
pages are therefore really a hack. When formatting manual pages,
<application>groff</application> thinks that they are in the ISO-8859-1
encoding and this <emphasis>-Tlatin1</emphasis> switch tells
<application>groff</application> to use the same encoding for output.
Since <application>groff</application> does no recoding of input characters,
the formatted result is really in the same encoding as input (although
<application>groff</application> doesn't know that it is not ISO-8859-1)
and therefore it is usable as the input for a pager.</para>

<para>Of course, this hack does not solve the problem of non-working
<command>man2dvi</command> program for localized manual
pages in non-ISO-8859-1 locales.
Also, it does not work at all with multibyte character sets.
The first problem does not have a solution currently. The second
one is not of a concern because the LFS installation does not support
multibyte character sets properly anyway. You may want to look at
internationalization related hints, though.</para>

<para>You may want to also take a look at the BLFS page at
<ulink url="&blfs-root;view/cvs/postlfs/compressdoc.html"/> which deals with
formatting and compression issues for man pages.</para>

</sect2>


<sect2 id="contents-man"><title>Contents of Man</title>

<para><emphasis>Installed programs</emphasis>: apropos, makewhatis, man,
man2dvi, man2html and whatis</para>

</sect2>


<sect2><title>Short descriptions</title>

<indexterm zone="ch-system-man apropos"><primary sortas="b-apropos">apropos</primary></indexterm>
<para id="apropos"><command>apropos</command> searches the whatis database and displays
the short descriptions of system commands that contain a given string.</para>

<indexterm zone="ch-system-man makewhatis"><primary sortas="b-makewhatis">makewhatis</primary></indexterm>
<para id="makewhatis"><command>makewhatis</command> builds the whatis database. It reads
all the manual pages in the manpath and for each page writes the name and a
short description in the whatis database.</para>

<indexterm zone="ch-system-man man"><primary sortas="b-man">man</primary></indexterm>
<para id="man"><command>man</command> formats and displays the requested on-line
manual page.</para>

<indexterm zone="ch-system-man man2dvi"><primary sortas="b-man2dvi">man2dvi</primary></indexterm>
<para id="man2dvi"><command>man2dvi</command> converts a manual page into dvi format.</para>

<indexterm zone="ch-system-man man2html"><primary sortas="b-man2html">man2html</primary></indexterm>
<para id="man2html"><command>man2html</command> converts a manual page into html.</para>

<indexterm zone="ch-system-man whatis"><primary sortas="b-whatis">whatis</primary></indexterm>
<para id="whatis"><command>whatis</command> searches the whatis database and displays
the short descriptions of system commands that contain the given keyword as a
separate word.</para>

</sect2>



</sect1>