source: chapter06/man.xml@ 39734a9

<?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" role="wrap">
<title>Man-&man-version;</title>
<?dbhtml filename="man.html"?>

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

<sect2 role="package"><title/>
<para>The Man package contains programs for finding and viewing manual pages.</para>

<segmentedlist>
<segtitle>&buildtime;</segtitle>
<segtitle>&diskspace;</segtitle>
<seglistitem><seg>0.1 SBU</seg><seg>1.9MB</seg></seglistitem>
</segmentedlist>

<segmentedlist>
<segtitle>Man installation depends on</segtitle>
<seglistitem><seg>Bash, Binutils, Coreutils, Gawk, GCC,
Glibc, Grep, Make, Sed</seg></seglistitem>
</segmentedlist>
</sect2>

<sect2 role="installation">
<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@g' configure
chmod 755 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;@g' src/man.conf.in</userinput></screen>
 
<para>Now prepare Man for compilation:</para>

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

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

<variablelist>
<varlistentry>
<term><userinput>-confdir=/etc</userinput></term>
<listitem><para>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>
</varlistentry>
</variablelist>

<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" role="content"><title>Contents of Man</title>

<segmentedlist>
<segtitle>Installed programs</segtitle>
<seglistitem><seg>apropos, makewhatis, man,
man2dvi, man2html and whatis</seg></seglistitem>
</segmentedlist>

<variablelist><title>Short descriptions</title>

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

<varlistentry id="makewhatis">
<term><command>makewhatis</command></term>
<listitem>
<indexterm zone="ch-system-man makewhatis"><primary sortas="b-makewhatis">makewhatis</primary></indexterm>
<para>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>
</listitem>
</varlistentry>

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

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

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

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

</sect2>

</sect1>