---

   groffer    ( 1 )

---

Man Page Searching

The default behavior of groffer is to first test whether a file parameter represents a local file; if it is not an existing file name, it is assumed to represent the name of a man page. The following options can be used to determine whether the arguments should be handled as file name or man page arguments.

--man forces to interpret all file parameters as filespecs for searching man pages.

--no-man --local-file disable the man searching; so only local files are displayed.

If neither a local file nor a man page was retrieved for some file parameter a warning is issued on standard error, but processing is continued.

Search algorithm Let us now assume that a man page should be searched. The groffer program provides a search facility for man pages. All long options, all environment variables, and most of the functionality of the GNU man(1) program were implemented. The search algorithm shall determine which file is displayed for a given man page. The process can be modified by options and environment variables.

The only man action that is omitted in groffer are the preformatted man pages, also called cat pages. With the excellent performance of the actual computers, the preformatted man pages aren't necessary any longer. Additionally, groffer is a roff program; it wants to read roff source files and format them itself.

The algorithm for retrieving the file for a man page needs first a set of directories. This set starts with the so-called man path that is modified later on by adding names of operating system and language. This arising set is used for adding the section directories which contain the man page files.

The man path is a list of directories that are separated by colon. It is generated by the following methods.

* The environment variable MANPATH can be set.

* It can be read from the arguments of the environment variable MANOPT.

* The man path can be manually specified by using the option --manpath. An empty argument disables the man page searching.

* When no man path was set the manpath(1) program is tried to determine one.

* If this does not work a reasonable default path from $PATH is determined.

We now have a starting set of directories. The first way to change this set is by adding names of operating systems. This assumes that man pages for several operating systems are installed. This is not always true. The names of such operating systems can be provided by 3 methods.

* The environment variable SYSTEM has the lowest precedence.

* This can be overridden by an option in MANOPT.

* This again is overridden by the command-line option --systems.

Several names of operating systems can be given by appending their names, separated by a comma.

The man path is changed by appending each system name as subdirectory at the end of each directory of the set. No directory of the man path set is kept. But if no system name is specified the man path is left unchanged.

After this, the actual set of directories can be changed by language information. This assumes that there exist man pages in different languages. The wanted language can be chosen by several methods.

* Environment variable LANG.

* This is overridden by LC_MESSAGES.

* This is overridden by LC_ALL.

* This can be overridden by providing an option in MANOPT.

* All these environment variables are overridden by the command- line option --locale.

The default language can be specified by specifying one of the pseudo-language parameters C or POSIX. This is like deleting a formerly given language information. The man pages in the default language are usually in English.

Of course, the language name is determined by man. In GNU man, it is specified in the POSIX 1003.1 based format:

<language>[_<territory>[.<character-set>[,<version>]]],

but the two-letter code in <language> is sufficient for most purposes. If for a complicated language formulation no man pages are found groffer searches the country part consisting of these first two characters as well.

The actual directory set is copied thrice. The language name is appended as subdirectory to each directory in the first copy of the actual directory set (this is only done when a language information is given). Then the 2-letter abbreviation of the language name is appended as subdirectories to the second copy of the directory set (this is only done when the given language name has more than 2 letters). The third copy of the directory set is kept unchanged (if no language information is given this is the kept directory set). These maximally 3 copies are appended to get the new directory set.

We now have a complete set of directories to work with. In each of these directories, the man files are separated in sections. The name of a section is represented by a single character, a digit between 1 and 9, or the character o or n, in this order.

For each available section, a subdirectory man<section> exists containing all man files for this section, where <section> is a single character as described before. Each man file in a section directory has the form man<section>/<name>.<section>[<extension>][.<compression>], where <extension> and <compression> are optional. <name> is the name of the man page that is also specified as filespec argument on the command line.

The extension is an addition to the section. This postfix acts like a subsection. An extension occurs only in the file name, not in name of the section subdirectory. It can be specified on the command line.

On the other hand, the compression is just an information on how the file is compressed. This is not important for the user, such that it cannot be specified on the command line.

There are 4 methods to specify a section on the command line:

* Environment variable MANSECT

* Command-line option --sections

* Appendix to the name argument in the form <name>.<section>

* Preargument before the name argument in the form <section> <name>

It is also possible to specify several sections by appending the single characters separated by colons. One can imagine that this means to restrict the man page search to only some sections. The multiple sections are only possible for MANSECT and --sections.

If no section is specified all sections are searched one after the other in the given order, starting with section 1, until a suitable file is found.

There are 4 methods to specify an extension on the command line. But it is not necessary to provide the whole extension name, some abbreviation is good enough in most cases.

* Environment variable EXTENSION

* Command-line option --extension

* Appendix to the <name>.<section> argument in the form <name>.<section><extension>

* Preargument before the name argument in the form <section><extension> <name>

For further details on man page searching, see man(1).

Examples of man files /usr/share/man/man1/groff.1 This is an uncompressed file for the man page groff in section 1. It can be called by sh# groffer groff No section is specified here, so all sections should be searched, but as section 1 is searched first this file will be found first. The file name is composed of the following components. /usr/share/man/ must be part of the man path; the subdirectory man1/ and the part .1 stand for the section; groff is the name of the man page.

/usr/local/share/man/man7/groff.7.gz The file name is composed of the following components. /usr/local/share/man must be part of the man path; the subdirectory man7/ and the part .7 stand for the section; groff is the name of the man page; the final part .gz stands for a compression with gzip(1). As the section is not the first one it must be specified as well. This can be done by one of the following commands. sh# groffer groff.7 sh# groffer 7 groff sh# groffer --sections=7 groff

/usr/local/man/man1/ctags.1emacs21.bz2 Here /usr/local/man must be in man path; the subdirectory man1/ and the file name part .1 stand for section 1; the name of the man page is ctags; the section has an extension emacs21; and the file is compressed as .bz2 with bzip2(1). The file can be viewed with one of the following commands sh# groffer ctags.1e sh# groffer 1e ctags sh# groffer --extension=e --sections=1 ctags where e works as an abbreviation for the extension emacs21.

/usr/man/linux/de/man7/man.7.Z The directory /usr/man is now part of the man path; then there is a subdirectory for an operating system name linux/; next comes a subdirectory de/ for the German language; the section names man7 and .7 are known so far; man is the name of the man page; and .Z signifies the compression that can be handled by gzip(1). We want now show how to provide several values for some options. That is possible for sections and operating system names. So we use as sections 5 and 7 and as system names linux and aix. The command is then

sh# groffer --locale=de --sections=5:7 --systems=linux,aix man sh# LANG=de MANSECT=5:7 SYSTEM=linux,aix groffer man