The general conventions used throughout this manual include file names and paths in italic, eg. /usr/man. variable strings (usually path components) enclosed within <> and in italic, eg. <sec>, program names in bold, eg. man. commands that can be typed at a shell prompt in a eg. environment variables denoted as follows: $ENV_VAR
Copyright © 1995 Graeme W. Wilford
Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.
Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a notice identical to this one.
Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by the copyright holder.
.
man_db-2.3.x is a package that is designed to provide users with online information in a fast and friendly manner while at the same time offering flexibility to the system administrator.
It is made up of several user programs: man - an interface to the on-line reference manuals whatis - search the manual page names apropos - search the manual page names and descriptions manpath - determine search path for manual pages several maintenance programs: mandb - create or update the manual page index caches catman - create or update the pre-formatted manual pages and a special pre-formatter that knows about compressed manual pages zsoelim - satisfy .so requests in roff inputIn addition to these compiled programs, there are two shell scripts, mkcatdirs and checkman in the tools subdirectory. These scripts aid the creation of cat directories and check for duplicated manual pages, respectively.
The following manual pages are provided with this package to explain correct format and usage. man(1), whatis(1), apropos(1), manpath(1), manpath(5), mandb(8), catman(8) and zsoelim(1). .
man_db-2.3.x originally started out life as program suite man-1.1B, written by John W. Eaton <jwe@che.utexas.edu> and maintained by Rik Faith <faith@cs.unc.edu> to which support proposed by the newly formed FSSTND committee regarding cat directories was added.
Since then, man_db-2.3.x's most innovative feature: the database cache scheme[1] has been significantly developed. The basic idea was to reduce manual page search times to a minimum. The following piece of text is included from the man_db-2.2 distribution:
The theory: If you go to a library to take a book out, what do you do?a) Go and look where it might be on a micro-fiche/terminal, take a look where it is supposed to be on the shelf, and then go look at the new arrivals if it's not where it's supposed to be?
OR
b) Start at one end of the ground floor, look along every bookshelf until you've completed that floor, then go up a level and start again until you've found what you're looking for?
Since then the database index scheme has evolved greatly. Every manual page and stray cat page on the system is registered in an index database cache which stores various details about the file including the timestamp, the location and the whatis[2] information. This information is kept up to date by man which looks for filesystem changes each time it is invoked. .
The simplest manual page system will have a single manual page hierarchy. This will typically be
beneath which will be several subdirectories of the form man<sec> where <sec> is 1, 2, 3, 4, 5, 6, 7 or 8. These are referred to as sections of the manual. Others may exist and they are not restricted to single character names. eg.
is a valid section subdirectory. Other common sections include 9, n, l, p and o.
Within these section subdirectories reside the manual pages themselves. Their filenames follow the pattern
where in most cases <ext> is an empty string. An example is manual page cp
which resides in section 1 and has no special extension.
.
The manual is split up into sections to ease access and to cater for manual pages that share the same name. It is common for a program and function to share the same name. kill is a good example. This is both a program which can be used to send a process a signal and an operating system call with similar functionality. Their manual pages are stored under sections 1 and 2 respectively. Thus, sections are used to separate out the program manual pages from the function manual pages and so on. The table below shows the section numbers of the manual followed by the types of pages they contain.
+---------+------------------------------------------------------+ | Section | Section contents | +---------+------------------------------------------------------+ | 1 | user executable programs or shell commands | | 2 | system calls (functions provided by the kernel) | | 3 | library calls (functions within system libraries) | | 4 | special files (usually found in /dev) | | 5 | file formats and conventions eg. /etc/passwd | | 6 | games | | 7 | macro packages and conventions eg. man(7), groff(7). | | 8 | system administration commands | | 9 | kernel routines [Non standard] | | n | new [obsolete] | | l | local [obsolete] | | p | public [obsolete] | | o | old [obsolete] | +---------+------------------------------------------------------+.
The format in which manual pages are stored is NROFF/TROFF or more generally ROFF. This is a typesetter style language[3] which requires formatting before being viewed. In fact some manual pages require pre-format processing to correctly format tables or equations.
If the page is to be viewed on screen in a text environment, NROFF is used as the primary formatter. If the page is to be printed or displayed in a graphical environment, TROFF is used. Traditionally, TROFF formatted files for a C/A/T (Computer aided Typesetter) which is now obsolete. The GNU ROFF (GROFF[4]) suite of programs offer a choice of output types including X, dvi and postscript. When configuring man_db-2.3.x, the preference is to use GROFF rather than TROFF. .
To allow the configuration program, configure, to be non-interactive, it can be passed various options to alter the default settings. Generic configure options are discussed in docs/INSTALL. Options that are specific to the man_db-2.3.x package are described below.
The use of package specific manual page sections is discouraged as packages large enough to warrant their own section probably contain manual pages that span other sections. An example might be package foo that has it's own section
which contains manual pages describing it's programs, the library routines it offers and the format of several of its configuration files. These pages would normally be allocated to sections 1, 3 and 5 respectively and thus combining them all under section foo is misleading. Subtle problems will arise if there are any base name-space clashes with standard manual pages, eg. exit(3), exit(foo) and the order in which they should be shown.
There are two standard solutions to this problem.
Only (2) offers a complete solution to manual page ordering problems and allows users to access the desired page directly. .
This is done via use of the section argument to man
will look for exit.1* in section 1 of the manual. If exit.1 exists, it will be displayed in preference to exit.1foo
will look for exit.1foo* in section 1 of the manual. The asterisk (*) represents a wild-card of any type or length, including length zero.
For an argument to be interpreted as a section name rather than a page name, it must either begin with a digit, or be included in the standard section list. The default section list is defined in include/manconfig.h to be 1, n, l, 8, 3, 2, 5, 4, 9, 6 and 7. This should be modified in order and content to meet the local conventions.
Every subdirectory section name in the entire system must be in the list, including sections found in imported manual page hierarchies. The order is important because in normal operation, man will only display the first manual page it finds that meets the search criteria. Using the --all argument will cause man to attempt to display all manual pages that meet the criteria. See man(1) for further information.
Having an excess of sections listed will not slow man down. .
If the section is unknown, but the package extension is, it is possible to use the extension argument
to search in all sections for manual pages named
exit
from package
foo.
.
It is often common for manual page systems to have more than one manual page hierarchy. Indeed one of the systems I use has the following globally accessible hierarchies
A full system $MANPATH would be a colon separated list of these directories The order is important, and is observed by man_db's search algorithms. The order is very much related to the users $PATH environment variable, and should be set on a per user basis, or not set at all. If a user's $PATH causes
to be executed in preference to
it is essential that
displays the manual page located within
rather than within
To ensure correct order, the program manpath may be used to set the $MANPATH environment variable. See manpath(1) and manpath(5) for details. .
If using a Bourne style login shell such as bash, ksh, or zsh, the commands
can be added to $HOME/.profile
If using a C style login shell such as csh or tcsh, the commands
can be added to $HOME/.login
N.B. $PATH must be set prior to using manpath. The setting of $MANPATH is actually unnecessary as the man_db-2.3.x utilities will dynamically determine the manpath if $MANPATH is unset. .
All man_db utilities, manpath included, will use the user's $MANPATH environment variable if set and not equal to "". Otherwise the user's $PATH environment variable is queried. If this is unset or is set to "", the determined manpath will simply be any
elements defined in the man_db config file.
Assuming that a $PATH exists, each path element it contains is scanned for in the config file. If found, the relative manpath element is appended to the internal manpath. However, if the element is not mentioned in the config file, a man directory relative to it will be sought. The subdirectories ../man or man relative to the path component are appended to the internal manpath if they exist. Finally, the internal manpath is stripped of duplicate paths before being processed by the NLS and `Other OS' routines. These may add to or modify the separate path elements giving priority to NLS manual pages or add OS-relative manpaths. .
It is common to have collections of heterogeneous computer systems linked together in a network. In some circumstances[5] it is advantageous to be able to access the manual pages of these other systems directly from your system. This feature is known as alternate system support. The accepted way to setup this support is to NFS mount the respective systems' manual page hierarchies under the native manual page hierarchies. An example:
+--------+-----------------------+ | System | Manual page hierarchy | +--------+-----------------------+ |<local> | /usr/man | | newOS | /usr/man/newOS | | userix | /usr/man/userix | |<local> | /usr/local/man | | newOS | /usr/local/man/newOS | | userix | /usr/local/man/userix | +--------+-----------------------+Rather than have multiple NFS mounts from a single machine, this may be accomplished by NFS mounting
somewhere on the local system and using symbolic links within the manual hierarchies. To access these alternate systems using man use the -m option, eg.
would provide manual pages showing the structure of /etc/passwd on systems userix and newOS in that order. A manual page would not be displayed about the local systems conventions. Please read the relevant man_db utility's manual page for further and more specific information. .
NLS manual pages should be put in NLS subdirectories of a standard manual page hierarchy. A table illustrating the concept is reproduced from the ``Linux Filesystem Structure''[6] (FSSTND) manual from which further information may be obtained.
+----------+----------------+-----------------+----------------------+ | Language | Territory | Character Set | Directory | +----------+----------------+-----------------+----------------------+ | English | -- | ASCII | /usr/man/en | | English | United Kingdom | ASCII | /usr/man/en_GB | | English | United States | ASCII | /usr/man/en_US | | French | Canada | ISO 8859-1 | /usr/man/fr_CA | | French | France | ISO 8859-1 | /usr/man/fr_FR | | German | Germany | ISO 646 | /usr/man/de_DE.646 | | German | Germany | ISO 6937 | /usr/man/de_DE.6937 | | German | Germany | ISO 8859-1 | /usr/man/de_DE.88591 | | German | Switzerland | ISO 646 | /usr/man/de_CH.646 | | Japanese | Japan | JIS | /usr/man/ja_JP.jis | | Japanese | Japan | SJIS | /usr/man/ja_JP.sjis | | Japanese | Japan | UJIS (or EUC-J) | /usr/man/ja_JP.ujis | +----------+----------------+-----------------+----------------------+Each of these directories are then interpreted as manual page hierarchies themselves and may contain the usual section subdirectories. Access to NLS manual pages is achieved via use of the setlocale(3) function which queries user environment variables to determine the current locale. Internally to the man_db utilities, this locale string is appended to each manpath element and the resultant NLS manpath element is searched before the standard manpath element. In this way, an NLS manual page that matches the search criteria will be shown before or in place of the standard American English page.
If a user's $MANPATH consists of or is determined as
and their locale is set to de_DE, the command
would produce the following internal man_db manpath elements
foobar would be searched for in the order of manual page hierarchies listed. .
By default NROFF will format manual pages into a form suitable for a typewriter style device, e.g. a terminal screen. GNU NROFF is capable[7] of formatting ROFF into a form suitable for 8-bit latin1 capable output devices. To enable output for such a device, give the option
to configure where DEVICE is the suitable and supported output format, in this case latin1. .
To enable console based viewing of latin1 characters on a Linux system, you
must have the kbd[8] package installed.
The following commands included within an initialisation file such as
/etc/rc.d/rc.local
will enable the display of latin1 fonts on the first 5 virtual terminals.
---< part of /etc/rc.d/rc.local >---
# sort out the vt font
if [ -x /bin/setfont ]; then
/bin/setfont /etc/kbd/consolefonts/lat1-16.psf
fi
# load the keymap transformation to do when activating new font
if [ -x /bin/mapscrn ]; then
/bin/mapscrn /etc/kbd/consoletrans/trivial
fi
# enable new font
for t in 1 2 3 4 5; do
echo -n -e "\033(K" > /dev/tty$t
done
---< part of /etc/rc.d/rc.local >---
For display under the
``X Window System'',
a suitable 8 bit clean terminal emulator is required.
.
When formatting an ASCII manual page for a latin1 output device, GNU NROFF will take advantage of the extra characters available and will always produce a text page containing some latin1 (8-bit) symbols. The table[9] below, taken from man(1) illustrates the differences.
+---------------------+-------+------------+-------+
| Description | Octal | ISO 8859-1 | ASCII |
+---------------------+-------+------------+-------+
| continuation hyphen | 255 | | - |
| bullet (middle dot) | 267 | · | o |
| acute accent | 264 | ´ | ' |
| multiplication sign | 327 | × | x |
+---------------------+-------+------------+-------+
To display such symbols on a 7 bit terminal or terminal emulator, they
must be translated back into standard ASCII. The
-7
option with
man
will enable this simple reverse translation.
This option may be useful if your site has both 7 and 8-bit capable output devices and nroff is using the latin1 output device to format manual pages. .
It has become standard practice to store the formatted manual pages on disk so that subsequent requests for the manual page do not have to involve the formatting process. These pre-formatted manual pages are known as cat pages. Although cat pages require additional disk storage requirements, they provide a substantial speed increase and their use is recommended.
The automatic support of storing and using cat pages is brought about by simply creating suitable directories for them. .
Traditionally, cat pages were stored under the same manual hierarchy as their source manual pages, in cat<sec> subdirectories rather than man<sec>. This situation is rather limiting in several situations
To avoid all of these problems simultaneously, it was decided to support local cat page directory caches. .
Any location for cat page hierarchy may be specified in the man_db configuration file. The location of the database cache associated with each manual page hierarchy will always be at the root of the cat page hierarchy. By default, the cat page hierarchy shadows the manual page hierarchy. The FSSTND proposes /var/catman as the location for such directories although man_db-2.3.x allows any directory hierarchy to be used. The FSSTND path transformation rule is as follows
should be formatted into the cat file
where the <locale> directory component may be missing and <ext> may be an empty string.
The suggestion is that stray cats are located in the traditional hierarchy under /usr whereas re-creatable cat pages are stored under the local writable hierarchy /var/catman. man follows strict rules in determining which file is displayed.
As an example, the following route is taken if all three files exist.
Having an excess of sections listed will not slow man down. .
If the section is unknown, but the package extension is, it is possible to use the extension argument
to search in all sections for manual pages named
exit
from package
foo.
.
It is often common for manual page systems to have more than one manual page hierarchy. Indeed one of the systems I use has the following globally accessible hierarchies
A full system $MANPATH would be a colon separated list of these directories The order is important, and is observed by man_db's search algorithms. The order is very much related to the users $PATH environment variable, and should be set on a per user basis, or not set at all. If a user's $PATH causes
to be executed in preference to
it is essential that
displays the manual page located within
rather than within
To ensure correct order, the program manpath may be used to set the $MANPATH environment variable. See manpath(1) and manpath(5) for details. .
If using a Bourne style login shell such as bash, ksh, or zsh, the commands
can be added to $HOME/.profile
If using a C style login shell such as csh or tcsh, the commands
can be added to $HOME/.login
N.B. $PATH must be set prior to using manpath. The setting of $MANPATH is actually unnecessary as the man_db-2.3.x utilities will dynamically determine the manpath if $MANPATH is unset. .
All man_db utilities, manpath included, will use the user's $MANPATH environment variable if set and not equal to "". Otherwise the user's $PATH environment variable is queried. If this is unset or is set to "", the determined manpath will simply be any
elements defined in the man_db config file.
Assuming that a $PATH exists, each path element it contains is scanned for in the config file. If found, the relative manpath element is appended to the internal manpath. However, if the element is not mentioned in the config file, a man directory relative to it will be sought. The subdirectories ../man or man relative to the path component are appended to the internal manpath if they exist. Finally, the internal manpath is stripped of duplicate paths before being processed by the NLS and `Other OS' routines. These may add to or modify the separate path elements giving priority to NLS manual pages or add OS-relative manpaths. .
It is common to have collections of heterogeneous computer systems linked together in a network. In some circumstances[5] it is advantageous to be able to access the manual pages of these other systems directly from your system. This feature is known as alternate system support. The accepted way to setup this support is to NFS mount the respective systems' manual page hierarchies under the native manual page hierarchies. An example:
+--------+-----------------------+ | System | Manual page hierarchy | +--------+-----------------------+ |<local> | /usr/man | | newOS | /usr/man/newOS | | userix | /usr/man/userix | |<local> | /usr/local/man | | newOS | /usr/local/man/newOS | | userix | /usr/local/man/userix | +--------+-----------------------+Rather than have multiple NFS mounts from a single machine, this may be accomplished by NFS mounting
somewhere on the local system and using symbolic links within the manual hierarchies. To access these alternate systems using man use the -m option, eg.
would provide manual pages showing the structure of /etc/passwd on systems userix and newOS in that order. A manual page would not be displayed about the local systems conventions. Please read the relevant man_db utility's manual page for further and more specific information. .
NLS manual pages should be put in NLS subdirectories of a standard manual page hierarchy. A table illustrating the concept is reproduced from the ``Linux Filesystem Structure''[6] (FSSTND) manual from which further information may be obtained.
+----------+----------------+-----------------+----------------------+ | Language | Territory | Character Set | Directory | +----------+----------------+-----------------+----------------------+ | English | -- | ASCII | /usr/man/en | | English | United Kingdom | ASCII | /usr/man/en_GB | | English | United States | ASCII | /usr/man/en_US | | French | Canada | ISO 8859-1 | /usr/man/fr_CA | | French | France | ISO 8859-1 | /usr/man/fr_FR | | German | Germany | ISO 646 | /usr/man/de_DE.646 | | German | Germany | ISO 6937 | /usr/man/de_DE.6937 | | German | Germany | ISO 8859-1 | /usr/man/de_DE.88591 | | German | Switzerland | ISO 646 | /usr/man/de_CH.646 | | Japanese | Japan | JIS | /usr/man/ja_JP.jis | | Japanese | Japan | SJIS | /usr/man/ja_JP.sjis | | Japanese | Japan | UJIS (or EUC-J) | /usr/man/ja_JP.ujis | +----------+----------------+-----------------+----------------------+Each of these directories are then interpreted as manual page hierarchies themselves and may contain the usual section subdirectories. Access to NLS manual pages is achieved via use of the setlocale(3) function which queries user environment variables to determine the current locale. Internally to the man_db utilities, this locale string is appended to each manpath element and the resultant NLS manpath element is searched before the standard manpath element. In this way, an NLS manual page that matches the search criteria will be shown before or in place of the standard American English page.
If a user's $MANPATH consists of or is determined as
and their locale is set to de_DE, the command
would produce the following internal man_db manpath elements
foobar would be searched for in the order of manual page hierarchies listed. .
By default NROFF will format manual pages into a form suitable for a typewriter style device, e.g. a terminal screen. GNU NROFF is capable[7] of formatting ROFF into a form suitable for 8-bit latin1 capable output devices. To enable output for such a device, give the option
to configure where DEVICE is the suitable and supported output format, in this case latin1. .
To enable console based viewing of latin1 characters on a Linux system, you
must have the kbd[8] package installed.
The following commands included within an initialisation file such as
/etc/rc.d/rc.local
will enable the display of latin1 fonts on the first 5 virtual terminals.
---< part of /etc/rc.d/rc.local >---
# sort out the vt font
if [ -x /bin/setfont ]; then
/bin/setfont /etc/kbd/consolefonts/lat1-16.psf
fi
# load the keymap transformation to do when activating new font
if [ -x /bin/mapscrn ]; then
/bin/mapscrn /etc/kbd/consoletrans/trivial
fi
# enable new font
for t in 1 2 3 4 5; do
echo -n -e "\033(K" > /dev/tty$t
done
---< part of /etc/rc.d/rc.local >---
For display under the
``X Window System'',
a suitable 8 bit clean terminal emulator is required.
.
When formatting an ASCII manual page for a latin1 output device, GNU NROFF will take advantage of the extra characters available and will always produce a text page containing some latin1 (8-bit) symbols. The table[9] below, taken from man(1) illustrates the differences.
+---------------------+-------+------------+-------+
| Description | Octal | ISO 8859-1 | ASCII |
+---------------------+-------+------------+-------+
| continuation hyphen | 255 | | - |
| bullet (middle dot) | 267 | · | o |
| acute accent | 264 | ´ | ' |
| multiplication sign | 327 | × | x |
+---------------------+-------+------------+-------+
To display such symbols on a 7 bit terminal or terminal emulator, they
must be translated back into standard ASCII. The
-7
option with
man
will enable this simple reverse translation.
This option may be useful if your site has both 7 and 8-bit capable output devices and nroff is using the latin1 output device to format manual pages. .
It has become standard practice to store the formatted manual pages on disk so that subsequent requests for the manual page do not have to involve the formatting process. These pre-formatted manual pages are known as cat pages. Although cat pages require additional disk storage requirements, they provide a substantial speed increase and their use is recommended.
The automatic support of storing and using cat pages is brought about by simply creating suitable directories for them. .
Traditionally, cat pages were stored under the same manual hierarchy as their source manual pages, in cat<sec> subdirectories rather than man<sec>. This situation is rather limiting in several situations
To avoid all of these problems simultaneously, it was decided to support local cat page directory caches. .
Any location for cat page hierarchy may be specified in the man_db configuration file. The location of the database cache associated with each manual page hierarchy will always be at the root of the cat page hierarchy. By default, the cat page hierarchy shadows the manual page hierarchy. The FSSTND proposes /var/catman as the location for such directories although man_db-2.3.x allows any directory hierarchy to be used. The FSSTND path transformation rule is as follows
should be formatted into the cat file
where the <locale> directory component may be missing and <ext> may be an empty string.
The suggestion is that stray cats are located in the traditional hierarchy under /usr whereas re-creatable cat pages are stored under the local writable hierarchy /var/catman. man follows strict rules in determining which file is displayed.
As an example, the following route is taken if all three files exist.
Having an excess of sections listed will not slow man down. .
If the section is unknown, but the package extension is, it is possible to use the extension argument
to search in all sections for manual pages named
exit
from package
foo.
.
It is often common for manual page systems to have more than one manual page hierarchy. Indeed one of the systems I use has the following globally accessible hierarchies
A full system $MANPATH would be a colon separated list of these directories The order is important, and is observed by man_db's search algorithms. The order is very much related to the users $PATH environment variable, and should be set on a per user basis, or not set at all. If a user's $PATH causes
to be executed in preference to
it is essential that
displays the manual page located within
rather than within
To ensure correct order, the program manpath may be used to set the $MANPATH environment variable. See manpath(1) and manpath(5) for details. .
If using a Bourne style login shell such as bash, ksh, or zsh, the commands
can be added to $HOME/.profile
If using a C style login shell such as csh or tcsh, the commands
can be added to $HOME/.login
N.B. $PATH must be set prior to using manpath. The setting of $MANPATH is actually unnecessary as the man_db-2.3.x utilities will dynamically determine the manpath if $MANPATH is unset. .
All man_db utilities, manpath included, will use the user's $MANPATH environment variable if set and not equal to "". Otherwise the user's $PATH environment variable is queried. If this is unset or is set to "", the determined manpath will simply be any
elements defined in the man_db config file.
Assuming that a $PATH exists, each path element it contains is scanned for in the config file. If found, the relative manpath element is appended to the internal manpath. However, if the element is not mentioned in the config file, a man directory relative to it will be sought. The subdirectories ../man or man relative to the path component are appended to the internal manpath if they exist. Finally, the internal manpath is stripped of duplicate paths before being processed by the NLS and `Other OS' routines. These may add to or modify the separate path elements giving priority to NLS manual pages or add OS-relative manpaths. .
It is common to have collections of heterogeneous computer systems linked together in a network. In some circumstances[5] it is advantageous to be able to access the manual pages of these other systems directly from your system. This feature is known as alternate system support. The accepted way to setup this support is to NFS mount the respective systems' manual page hierarchies under the native manual page hierarchies. An example:
+--------+-----------------------+ | System | Manual page hierarchy | +--------+-----------------------+ |<local> | /usr/man | | newOS | /usr/man/newOS | | userix | /usr/man/userix | |<local> | /usr/local/man | | newOS | /usr/local/man/newOS | | userix | /usr/local/man/userix | +--------+-----------------------+Rather than have multiple NFS mounts from a single machine, this may be accomplished by NFS mounting
somewhere on the local system and using symbolic links within the manual hierarchies. To access these alternate systems using man use the -m option, eg.
would provide manual pages showing the structure of /etc/passwd on systems userix and newOS in that order. A manual page would not be displayed about the local systems conventions. Please read the relevant man_db utility's manual page for further and more specific information. .
NLS manual pages should be put in NLS subdirectories of a standard manual page hierarchy. A table illustrating the concept is reproduced from the ``Linux Filesystem Structure''[6] (FSSTND) manual from which further information may be obtained.
+----------+----------------+-----------------+----------------------+ | Language | Territory | Character Set | Directory | +----------+----------------+-----------------+----------------------+ | English | -- | ASCII | /usr/man/en | | English | United Kingdom | ASCII | /usr/man/en_GB | | English | United States | ASCII | /usr/man/en_US | | French | Canada | ISO 8859-1 | /usr/man/fr_CA | | French | France | ISO 8859-1 | /usr/man/fr_FR | | German | Germany | ISO 646 | /usr/man/de_DE.646 | | German | Germany | ISO 6937 | /usr/man/de_DE.6937 | | German | Germany | ISO 8859-1 | /usr/man/de_DE.88591 | | German | Switzerland | ISO 646 | /usr/man/de_CH.646 | | Japanese | Japan | JIS | /usr/man/ja_JP.jis | | Japanese | Japan | SJIS | /usr/man/ja_JP.sjis | | Japanese | Japan | UJIS (or EUC-J) | /usr/man/ja_JP.ujis | +----------+----------------+-----------------+----------------------+Each of these directories are then interpreted as manual page hierarchies themselves and may contain the usual section subdirectories. Access to NLS manual pages is achieved via use of the setlocale(3) function which queries user environment variables to determine the current locale. Internally to the man_db utilities, this locale string is appended to each manpath element and the resultant NLS manpath element is searched before the standard manpath element. In this way, an NLS manual page that matches the search criteria will be shown before or in place of the standard American English page.
If a user's $MANPATH consists of or is determined as
and their locale is set to de_DE, the command
would produce the following internal man_db manpath elements
foobar would be searched for in the order of manual page hierarchies listed. .
By default NROFF will format manual pages into a form suitable for a typewriter style device, e.g. a terminal screen. GNU NROFF is capable[7] of formatting ROFF into a form suitable for 8-bit latin1 capable output devices. To enable output for such a device, give the option
to configure where DEVICE is the suitable and supported output format, in this case latin1. .
To enable console based viewing of latin1 characters on a Linux system, you
must have the kbd[8] package installed.
The following commands included within an initialisation file such as
/etc/rc.d/rc.local
will enable the display of latin1 fonts on the first 5 virtual terminals.
---< part of /etc/rc.d/rc.local >---
# sort out the vt font
if [ -x /bin/setfont ]; then
/bin/setfont /etc/kbd/consolefonts/lat1-16.psf
fi
# load the keymap transformation to do when activating new font
if [ -x /bin/mapscrn ]; then
/bin/mapscrn /etc/kbd/consoletrans/trivial
fi
# enable new font
for t in 1 2 3 4 5; do
echo -n -e "\033(K" > /dev/tty$t
done
---< part of /etc/rc.d/rc.local >---
For display under the
``X Window System'',
a suitable 8 bit clean terminal emulator is required.
.
When formatting an ASCII manual page for a latin1 output device, GNU NROFF will take advantage of the extra characters available and will always produce a text page containing some latin1 (8-bit) symbols. The table[9] below, taken from man(1) illustrates the differences.
+---------------------+-------+------------+-------+
| Description | Octal | ISO 8859-1 | ASCII |
+---------------------+-------+------------+-------+
| continuation hyphen | 255 | | - |
| bullet (middle dot) | 267 | · | o |
| acute accent | 264 | ´ | ' |
| multiplication sign | 327 | × | x |
+---------------------+-------+------------+-------+
To display such symbols on a 7 bit terminal or terminal emulator, they
must be translated back into standard ASCII. The
-7
option with
man
will enable this simple reverse translation.
This option may be useful if your site has both 7 and 8-bit capable output devices and nroff is using the latin1 output device to format manual pages. .
It has become standard practice to store the formatted manual pages on disk so that subsequent requests for the manual page do not have to involve the formatting process. These pre-formatted manual pages are known as cat pages. Although cat pages require additional disk storage requirements, they provide a substantial speed increase and their use is recommended.
The automatic support of storing and using cat pages is brought about by simply creating suitable directories for them. .
Traditionally, cat pages were stored under the same manual hierarchy as their source manual pages, in cat<sec> subdirectories rather than man<sec>. This situation is rather limiting in several situations
To avoid all of these problems simultaneously, it was decided to support local cat page directory caches. .
Any location for cat page hierarchy may be specified in the man_db configuration file. The location of the database cache associated with each manual page hierarchy will always be at the root of the cat page hierarchy. By default, the cat page hierarchy shadows the manual page hierarchy. The FSSTND proposes /var/catman as the location for such directories although man_db-2.3.x allows any directory hierarchy to be used. The FSSTND path transformation rule is as follows
should be formatted into the cat file
where the <locale> directory component may be missing and <ext> may be an empty string.
The suggestion is that stray cats are located in the traditional hierarchy under /usr whereas re-creatable cat pages are stored under the local writable hierarchy /var/catman. man follows strict rules in determining which file is displayed.
As an example, the following route is taken if all three files exist.
Having an excess of sections listed will not slow man down. .
If the section is unknown, but the package extension is, it is possible to use the extension argument
to search in all sections for manual pages named
exit
from package
foo.
.
It is often common for manual page systems to have more than one manual page hierarchy. Indeed one of the systems I use has the following globally accessible hierarchies
A full system $MANPATH would be a colon separated list of these directories The order is important, and is observed by man_db's search algorithms. The order is very much related to the users $PATH environment variable, and should be set on a per user basis, or not set at all. If a user's $PATH causes
to be executed in preference to
it is essential that
displays the manual page located within
rather than within
To ensure correct order, the program manpath may be used to