Adding upstream version 2.12.0.upstream/2.12.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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.