MAN.CONF(5)

NAME
man.conf - configuration file for man(1)

DESCRIPTION
The man(1), apropos(1), and whatis(1) commands search for manual pages or their database files as specified by the man.conf file. Manual pages are normally expected to be preformatted (see nroff(1) ).

The man.conf file contains two types of lines.

The first type of line is a ``section'' line, which contains a section name followed by one or more directory paths. The directory paths may contain the normal shell globbing characters; to escape a shell globbing character, precede it with a backslash (``\''). Lines in this format specify that manual pages for the section may be found in the following directories.

Section names are unrestricted except for the reserved words specified below; in general, you should avoid anything with a leading underscore (``_'') to avoid future incompatibilities.

The section named ``_order'' is the list of sections that will be searched if no section is specified by the user.

The second type of line is preceded with a ``keyword''. The possible keywords and their meanings are as follows:

_manpath
    This is the list of directories that contain manual sections. Each directory in this list is expected to contain ``cat'' and ``man'' subdirectories for whatever man sections you might have. The ``cat'' directories (cat1, cat2, ... , catn) contain preformatted manual pages, while the ``man'' directories contain unformatted manual pages.

_cat
    A _cat line is used to describe how to print out a manpage. For preformatted pages, this is the only command needed to display a page; unformatted pages are also passed through the “_ascii” or “_ps” filters before they are displayed.

_order
    The list (in search order) of sections that will be searched in any manual directory.

_save
    man attempts to save formatted copies of manpages in ``cat'' directories when it displays unformatted manpages. _save takes two arguments; the first is the command that's used to prepare the manpage for saving in the cat directory, and the second is the extension that will be added to that directory after saving.

_suffix
    Man file names, regardless of their format are expected to end in a ``.*'' pattern, i.e. a ``.'' followed by some suffix. Each field of a _suffix line is a suffix which indicates preformatted files which do not need to be reformatted or manipulated in any way, but which may be directly displayed to the user. Each suffix may contain the normal shell globbing characters. _suffix is only applied to files in cat-directories.

_version
    The version of the configuration file.

_whatdb
    The full pathname (not just a directory path) for a database to be used by the apropos(1) and whatis(1) commands.

_text
    The nroff command to format manpages for printing on a terminal. This must be defined for man to actually work.

_ps The troff command to format pages in postscript. If this is not defined, man -t will not work.

Multiple specifications for all types of lines are cumulative and the entries are used in the order listed in the file; multiple entries may be listed per line, as well.

Empty lines or lines whose first non-whitespace character is a hash mark (``#'') are ignored.

EXAMPLES
Given the following man.conf file:

    _version	Mastodon
    _order		1 2 3
    _cat		*.Z /bin/zcat
    _save		compress .Z
    _manpages	/usr/man
    sect3		/usr/man/Attic/man3 /usr/man/cat3 /usr/man/man3
    _ps		troff -Tps -mandoc
    _text		troff -Tascii -mandoc

By default, the command “man mktemp” will search for ``mktemp.*.Z'' and ``mktemp.*'' in the directories “/usr/man/cat1”, “/usr/man/man1”, “/usr/man/cat2”, “/usr/man/man2”, “/usr/man/cat3”, and “/usr/man/man3”.

If ``/usr/man/man*/mktemp.*.Z'' was found first, the command “/bin/zcat <manual page> |groff -Tascii -mandoc” would be run to build a man page for display to the user. If ``/usr/man/cat*/mktemp.*.Z'' was found first, the command “/bin/zcat <manual page>” would be run to display the manual page.

The command “man sect3 mktemp” would search the directories “/usr/man/Attic/man3”, “/usr/man/cat3”, and “/usr/man/man3”, in that order, for the mktemp manual page.

ERRORS

-t option not supported
    You used the “-t” flag, but config file does not have a “_ps” setting.

there is no way to format manpages
    The config file does not have a “_text” setting. This usually happens when you're using the “-C” option and the config file you're giving to man is incomplete.

FILES
/etc/man.conf
    Standard manual directory search path.

SEE ALSO
apropos(1), machine(1), man(1), whatis(1), whereis(1), fnmatch(3), glob(3)

HISTORY
This man.conf format is derived from the OpenBSD 2.3 man.conf format. Most of the OpenBSD directives were summarily dropped on the floor when the man program was ported to Mastodon Linux.