diff options
Diffstat (limited to '')
| -rw-r--r-- | manual/files.me | 518 |
1 files changed, 518 insertions, 0 deletions
diff --git a/manual/files.me b/manual/files.me new file mode 100644 index 0000000..72c09ed --- /dev/null +++ b/manual/files.me @@ -0,0 +1,518 @@ +.\" 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 +_ +<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. |