path: root/manual/files.me

.\" Copyright (C), 1995, Graeme W. Wilford. (Wilf.)
.\" Copyright (c) 2002, 2007 Colin Watson.
.\"
.\" You may distribute under the terms of the GNU General Public
.\" License as specified in the file COPYING that comes with the
.\" man-db distribution.
.\"
.\" Thu Sep 21 19:22:47 BST 1995  Wilf. (G.Wilford@ee.surrey.ac.uk) 
.\" 
.BS 1 "Filesystem structure"
.BS 2 "Manual page hierarchies"
.lp
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
.ip
.i
/usr/man
.br
/usr/local/man
.br
/usr/local/tex/man
.br
/usr/local/pbm/man
.br
/usr/X11R6/man
.br
/usr/openwin/man
.br
/usr/local/packages/pvm/man
.r
.lp
A full system
.EV MANPATH
would be a colon separated list of these directories.
The order is important, and is observed by \*M's search algorithms.
The order is very much related to the user's
.EV PATH
environment variable, and should be set on a per user basis, or not
set at all.
If a user's
.EV PATH
causes
.ip
.i /usr/local/packages/bin/foobar
.lp
to be executed in preference to
.ip
.i /usr/bin/foobar ,
.lp
it is essential that
.ip
.bx "man foobar"
.lp
displays the manual page located within
.ip
.i /usr/local/packages/man
.lp
rather than within
.ip
.i /usr/share/man
.lp
To ensure correct order, the program
.b manpath
may be used to set the
.EV MANPATH
environment variable.
See
.b manpath (1)
and
.b manpath (5)
for details.
.BS 2 "Setting the MANPATH"
.lp
If using a Bourne style login shell such as
.b bash ,
.b ksh ,
or
.b zsh ,
the commands
.ip
export MANPATH
.br
MANPATH=`manpath \-q`
.lp
can be added to
.b \s-1$HOME\s+1\c
.i /.profile
.lp
If using a C style login shell such as
.b csh
or
.b tcsh ,
the commands
.ip
setenv MANPATH `manpath \-q`
.lp
can be added to
.b \s-1$HOME\s+1\c
.i /.login
.lp
N.B.
.EV PATH
must be set prior to using
.b manpath .
The setting of
.EV MANPATH
is actually unnecessary as the \*M utilities will dynamically determine the
manpath if
.EV MANPATH
is unset.
.BS 2 "Determination of the internal manpath"
.lp
All \*M utilities,
.b manpath
included, will use the user's
.EV MANPATH
environment variable if set and not equal to "".
Otherwise the user's
.EV PATH
environment variable is queried.
If this is unset or is set to "", the
determined manpath will simply be any
.ip
.b MANDATORY_MANPATH
.lp
elements defined in the \*M config file.
.lp
Assuming that a
.EV PATH
exists, each path element it contains is scanned for in the config file.
If found, the corresponding 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
.i ../man ,
.i man ,
.i ../share/man ,
or
.i share/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
.b NLS
and \(oqOther OS\(cq routines.
These may add to or modify the separate path
elements giving priority to
.b NLS
manual pages or add OS-relative manpaths.
.BS 2 "Other OS's manual pages"
.lp
It is common to have collections of heterogeneous computer systems linked
together in a network.
In some circumstances\**
.(f
\** writing portable software instantly comes to mind
.)f
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:

.TS
center box tab(@);
l | l.
System@Manual page hierarchy
_
<local>@/usr/share/man
newOS@/usr/share/man/newOS
userix@/usr/share/man/userix
<local>@/usr/local/man
newOS@/usr/local/man/newOS
userix@/usr/local/man/userix
.TE

Rather than have multiple NFS mounts from a single machine, this may be
accomplished by NFS mounting
.ip
.i <other-sys>:/usr
.lp
somewhere on the local system and using symbolic links within the manual
hierarchies.
To access these
.i "alternate systems"
using
.b man
use the
.b \-m
or
.b \-\-systems
option, eg.
.ip
.bx "man \-\-all\ \-\-systems userix:newOS 5 passwd"
.lp
would provide manual pages showing the structure of
.i /etc/passwd
on systems
.b userix
and
.b newOS
in that order.
A manual page would
.i not
be displayed about the local systems conventions.
Please read the relevant \*M utility's manual
page for further and more specific information.
.BS 2 "NLS manual pages"
.lp
.\"With appropriate font support, it is possible to access and display
.\".q "Native Language Support"
.\"manual pages.
.\".lp
NLS manual pages should be installed in NLS subdirectories of a standard
manual page hierarchy.
The subdirectory names should be made up of language, territory, and
character set components as necessary to specify the locale of the manual
page.
.lp
The character set component describes the encoding of the manual page
itself, and not the encoding in use by the user; a manual page installed
under the
.b fr.UTF-8
subdirectory will be used in the
.b fr_FR.ISO-8859-1
locale as well as
.b fr_FR.UTF-8 ,
and converted between encodings as necessary.
If no character set is specified in the subdirectory name, \*M will attempt
to detect whether each page is encoded using UTF-8 or a legacy character set
appropriate for the language.
Accordingly, the recommended scheme for installing manual pages is to encode
them in UTF-8 (or, if that is not practical, in the legacy character set)
and install them in directories
.i without
a character set component in their names.
.lp
The territory should normally be omitted unless it is necessary to describe
the manual page text.
For example, Brazilian Portuguese is quite distinct from Portuguese and so
should be installed under the
.b pt_BR
subdirectory, but a single German manual page will typically suffice in
Austria as well as in Germany and so should be installed under the
.b de
subdirectory.
.lp
The following table gives some examples.

.TS
center box tab(@);
l | l | l | l.
Language@Territory@Character Set@Directory
_
French@any@T{
.ad l
UTF-8 or ISO-8859-1
T}@/usr/share/man/fr
French@Canada@ISO 8859-1@/usr/share/man/fr_CA
French@any@UTF-8@/usr/share/man/fr.UTF-8
German@Germany@UTF-8@/usr/share/man/de_DE.UTF-8
German@Switzerland@ISO 8859-1@/usr/share/man/de_CH.ISO-8859-1
Japanese@Japan@UTF-8 or EUC-JP@/usr/share/man/ja_JP
Japanese@Japan@EUC-JP@/usr/share/man/ja_JP.EUC-JP
Japanese@any@UTF-8@/usr/share/man/ja.UTF-8
.TE

On systems supporting UTF-8, it is recommended that all manual pages be
encoded using UTF-8 where possible, in order to simplify the task of editing
a variety of pages without reconfiguring editors and terminals and the like.
.lp
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
.b setlocale (3)
function which queries user environment variables to
determine the current locale.
Internally to the \*M 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.
.lp
If a user's
.EV MANPATH
consists of or is determined as
.ip
.i /usr/local/man:/usr/share/man:/usr/X11R6/man
.lp
and their locale is set to
.b de_DE ,
the command
.ip
.bx "man \-\-systems userix:man foobar"
.lp
would produce the following internal \*M manpath elements
.ip
.i
.nf
/usr/local/man/userix/de_DE
/usr/local/man/userix/de
/usr/local/man/userix
/usr/share/man/userix/de_DE
/usr/share/man/userix/de
/usr/share/man/userix
/usr/X11R6/man/userix/de_DE
/usr/X11R6/man/userix/de
/usr/X11R6/man/userix
/usr/local/man/de_DE
/usr/local/man/de
/usr/local/man
/usr/share/man/de_DE
/usr/share/man/de
/usr/share/man
/usr/X11R6/man/de_DE
/usr/X11R6/man/de
/usr/X11R6/man
.fi
.r
.lp
.b foobar
would be searched for in the order of manual page hierarchies listed.
Additional directories corresponding to manual pages encoded in different
character sets would be used if present.
.BS 3 "ISO 8859-1 (latin1) manual pages"
.lp
By default \*N will format manual pages into a form suitable
for a typewriter style device, e.g. a terminal screen. \*(GN \*N is
capable\**
.(f
\** see
.b nroff (5)
for the output device formats available with your \*N
.)f
of formatting \*R into a form suitable for 8-bit latin1 capable output
devices. To enable output for such a device, give the option
.ip \-\-with\-device=DEVICE
.lp
to
.b configure
where DEVICE
is the suitable and supported output format, in this case
.b latin1 .
.BS 3 "Displaying non-ASCII characters on a \*L virtual terminal"
.lp
To view non-ASCII characters at the \*L console, you must have one of the
kbd\** and console\-tools packages installed.
.(f
\** written and maintained by Andries Brouwer <aeb@cwi.nl>.
.)f
If your system does not come with suitable configuration already, then
please see the documentation in the kbd or console\-tools package for
details on how to configure the console for your locale.
On modern systems, the best choice is likely to be to use the UTF-8 encoding
with a font suitable for your language.
Make sure that your locale environment variables match the encoding
displayed by the console.
For display under the
.q "X Window System",
a suitable 8-bit-clean terminal emulator is required.
.BS 3 "Viewing ASCII pages formatted for latin1 output device"
.lp
When formatting an ASCII manual page for a latin1 output device,
\*(GN \*N
will take advantage of the extra characters available and will always
produce a text page containing some latin1 (8-bit) symbols.
The table\**
.(f
\** The ISO 8859-1 and ASCII columns of this table will be identical if this
manual was formatted for an ASCII based typewriter display, i.e. using \*N
in its native mode.
.)f
below, taken from
.b man (1),
illustrates the differences.

.TS
center box tab (@);
l | c | c | c.
Description@Octal@ISO 8859-1@ASCII
_
continuation hyphen@255@\[char173]@\-
bullet (middle dot)@267@\(bu@o
acute accent@264@\(aa@'
multiplication sign@327@\(mu@x
.TE

To display such symbols on a 7 bit terminal or terminal emulator, they
must be translated back into standard ASCII.
The
.b \-7
option with
.b man
will enable this simple reverse translation.
.lp
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.
.BS 2 "Cat pages"
.lp
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
.i cat
pages.
Although cat pages require additional disk storage requirements, they
provide a substantial speed increase and their use is recommended.
.lp
The automatic support for storing and using cat pages is brought about by
simply creating suitable directories for them.
.BS 2 "Cat page hierarchies"
.lp
Traditionally, cat pages were stored under the same manual hierarchy as
their source manual pages, in
.i cat<sec>
subdirectories rather than
.i man<sec> .
This situation is rather limiting in several situations:
.ip
.bu
When it is advantageous to mount
.i /usr
as a read-only filesystem.
Cat pages cannot be supported in this situation
without use of symbolic links to various other areas of the filesystem.
This situation is a greater problem if the media itself is read-only, such as
CD-ROM.
.bu
When NFS mounting alternate OS's manual page hierarchies.
The alternate system may be under someone else's control and they may not
want cat pages stored on their system.
In fact, it is usually a good idea to export the manual page filesystems
read-only, or import them that way.
It is possible to avoid the problems, this time with even more symbolic
links that may need periodic updating.
.\".bu
.\"When sharing 
.\".i /usr 
.\"with several other machines. There may be a situation where two machines are
.\"producing the same cat file at the same time. A corrupted cat file is the
.\"probable result.
.bu
If there is a mixture of normal cat files and stray cats\**,
.(f
\** cat files that have no source manual page, i.e. they cannot be recreated.
.)f
it is very difficult to periodically
.i trim
the cat space disk usage by removing seldom accessed cat files.
.lp
To avoid all of these problems simultaneously, it was decided to support
local cat page directory caches.
.BS 2 "Local cat page directory caches"
.lp
Any location for cat page hierarchy may be specified in the
\*M 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 \*F
proposes
.i /var/cache/man
as the location for such directories, although \*M allows any directory
hierarchy to be used.
The \*F path transformation rule is as follows:
.ip
.i /usr/<hierarchy>/share/man/<locale>/man<sec>/page.<sec><ext>
.lp
should be formatted into the cat file
.ip
.i /var/cache/man/<hierarchy>/<locale>/cat<sec>/page.<sec><ext>
.lp
where the
.i <locale>
directory component may be missing and
.i <ext>
may be an empty string.
.lp
The suggestion is that stray cats are located in the traditional hierarchy
under
.i /usr
whereas re-creatable cat pages are stored under the local writable hierarchy
.i /var/cache/man.
.b man
follows strict rules in determining which file is displayed.
.lp
As an example, the following route is
taken if all three files exist.
.np
Check relative modification time stamps of the manual file and the
traditional cat file.
If the cat file is up to date (has an equal time stamp), display it.
.np
The traditional cat file is out of date.
Check relative time stamps of the manual file and the alternate cat file.
If the cat file is up to date, display it.
.np
The alternate cat file is out of date.
Format the manual file and display the result in the foreground, while
updating the alternate cat file in the background.
.lp
When a cat file is created, its time stamp is set to that of the
corresponding manual file.
Manual files are often stored in
.b tar
archives, and time stamps may be preserved when these archives are unpacked.
Simply checking whether the cat file is newer would sometimes cause
.b man
to display an out-of-date cat file in this case, when it should have
reformatted the manual file instead.