.\" 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 docs/COPYING.GPLv2 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 _ @/usr/share/man newOS@/usr/share/man/newOS userix@/usr/share/man/userix @/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 :/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 . .)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 subdirectories rather than .i man . 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//share/man//man/page. .lp should be formatted into the cat file .ip .i /var/cache/man///cat/page. .lp where the .i directory component may be missing and .i 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.