History

Unix is old. Early in its life, memory, both RAM and disk space, was very expensive and scarce. Documentation was printed, and the Unix Programmer's Manual sat on the desk. The manual was divided into volumes, and Volume One contained pages on commands, functions, file formats, etc, for developing programs and using the system. Each 'page' (yes, originally, one page each) documented one thing (command, etc). Each type of thing documented was organized in its own numbered section.

When space permitted, Volume one was put on the system as pages and a program provided to process them, called man. (More on that processing later.) This was the time in Unix' history when the operating system was branching. The two surviving branches, the System 5 branch and the BSD branch, each had their own version (and organization) of the manual, although they agreed on the most frequently referenced first sections, and on the general structure of a manual page.

The first three sections of the man system, whose section numbers are in agreement between the branches, contain information on User Commands (section 1), System Calls (section 2) and Library Functions (section 3). From that point the section numbers diverge:

Distribution of Pages

The obvious way to organize manual pages would be to have a central repository for all of them, and have it organized in sections. However, this is suboptimal due to several issues

• optional software packages may have their own pages, whose names may conflict with the names of standard man pages.
• different users may want to use different software packages, or even different versions of the same utilities. Thus, the set of man pages accessed should be user-configurable.
• due to the volume of pages that exist, intermixing standard and non-standard man pages can create a maintenance problem.

For these reasons, a technique of finding pages was adopted that uses a MANPATH to find man pages, similarly to PATH. On linux, this facility has been finely honed, as we will see.

The basic structure of an area of man pages is a man tree. This consists of a base directory, usually named man. Beneath this base directory there is

• one subdirectory per section needed for the contents. The subdirectories must be named manN, where N is the section number. (If the tree contains man pages on commands, those pages will be in the man1 subdirectory. If there are no man pages on system calls, the tree will not have a man2 subdirectory.)

• one subdirectory for each language-specific set of pages. The subdirectory must be named the same of the standard language abbreviation. The language subdirectory forms the base directory of a new man tree, which has subdirectories man1, man2,... as needed to house the pages. (We will discuss further the language-specific areas later.)

• possibly, one subdirectory for catman-format pages for each section of the manual needed. catman format pages are preprocessed man pages and are rarely kept these days since the increased processor power on modern systems makes on-demand page processing feasible. (catman pages are also called cached man pages) catman subdirectories are named cat1, cat2,...

• beneath each manN (or catN) subdirectory are the pages for that section. They are named for the command (or topic), with the suffix .N, where N is the section. The page may be compressed by gzip, as shown by its extension. (I believe in a future release the pages may be compressed by xz instead.)
  

Following this scheme, the compressed man page for vim(1), which is housed in the main man page tree /usr/share/man would be found in /usr/share/man/man1/vim.1.gz. The corresponding French-language page would be found in /usr/share/man/fr/man1/vim.1.gz (fr is the abbreviation for French).

Example: Here is a listing of the root of the main man tree on linux and of the first level of the French (fr) subdirectory:

[gboyd@nelson ~]$ ls -F /usr/share/man
ca/  es/  it/      man1p/  man3p/  man5x/  man8/   overrides/  ro/  uk/
cs/  fr/  ja/      man1x/  man3x/  man6/   man8x/  pl/          ru/  zh/
da/  hr/  ko/      man2/   man4/   man6x/  man9/   pt/          sk/  zh_CN/
de/  hu/  man0p/  man2x/  man4x/  man7/   man9x/  pt_BR/      sv/  zh_TW/
en/  id/  man1/   man3/   man5/   man7x/  mann/   pt_PT/      tr/

[gboyd@nelson ~]$ ls -F /usr/share/man/fr
man1/  man3/  man5/  man8/
$

You can see from the tree above that at least some of the man pages have been installed for many languages, including Spanish (es), German (de), French (fr), Italian (it), Japanese (ja), Russian (ru), and several Chinese dialects (zh_CN, zh_TW). Here is the newgrp man page's first few lines using zh_CN.

NAME
       newgrp - 登录到新的用户组中

Language order and Section search

Let's assume for a moment that our system has a single man tree, located in the standard place, /usr/share/man, with all of the system's man pages in it. In this tree there might be several pages named X - one in section 1, one in section 3 (of the non-language-specific tree) and one in each of two language-specific trees. How does man decide which page it should display? It uses two parameters:

your language - If your language is set, man searches that language's subtree before it searches the generic part of the tree. Thus, the language-specific page is found first, then, if not, the generic (English) page is displayed.(We will see how to set the language at the command-line in the next section.)

your section order - man's configuration, which we will cover briefly later, contains a default section order, which is a colon-separated list of section numbers. You can override this by defining an environment variable named MANSECT or by adding the -S sectionlist option to the man command, where sectionlist is your section list. If sectionlist or MANSECT is "3:2:1", then section 3 is searched first, then 2, then 1. The normal default section list starts with "1:8:2:3".

By default, only the first page that is found is displayed.If you want to output each page man finds on your name one after the other, use the -a option to man.

Language-specific Pages

We indicated in the previous section that language-specific pages will be displayed preferentially. The preferred language is determined by your locale setting. The easiest way to set your locale is to set your language when you log in at the console under X. (The menu to change your language only displays between the entry of your username and your password, so it is often missed.) This propagates the locale setting to all processes (and all shells) that run on your behalf. 

You can change your locale for the current shell by setting (and exporting) the LANG environment variable appropriately. The LANG setting is a string in the format

lang_country.charset

where lang is the two character standard language code (in lowercase), country is the two character standard country code (in uppercase) and charset is the character set (usually utf8). A list of the available locales can be displayed using locale -a

[ The locale has many individual settings, each of which controls one type of information display. These can be set individually or all inherited from LANG. You can display these settings using the locale command. ]

The two character lang setting of the locale (or of LANG) corresponds to the subdirectory of each man tree that houses the language-specific pages.

Example: First, let's look at the standard locale and the display of a system message and part of a man page:

$ locale
LANG=en_US.utf8
LC_CTYPE="en_US.utf8"
...

$ rm xxx
rm: cannot remove `xxx': No such file or directory

Now, we will change the locale to Belgian French (fr_BE) and show the output of the same commands. (Note that the French language subsystems were installed on this system)

Note that the pages provided with each alternate language are sparse. If no language-specific page is found, the correponding English page is displayed instead.

Let's recap. Assuming we have a single man tree, and you have two environment variables set like this:

LANG=fr_BE.utf8

MANSECT=8:1:2:3

A seach for man XXX will search the following directories of our man tree in order:

fr/man8, man8, fr/man1, man1, fr/man2, man2, fr/man3, man3

The first page found named XXX.N (or XXX.N.gz), where N is the current section number, is displayed.

Multiple man trees

Let's expand our search using two man trees instead of one. We will name them tree1 and tree2. Assuming we search tree1 first, the above search for man XXX given our section order and language is as follows:

tree1/fr/man8, tree1/man8, tree2/fr/man8, tree2/man8, tree1/fr/man1, tree1/man1, tree2/fr/man1, tree2/man1...

As you can see, the section has precedence, and, within a section, the language has precedence.

The only problem remaining is where are the man trees and how do we tell man how the order to search them in? Well, the simple answer is use the MANPATH variable. Yes, there is a MANPATH, just like there is a PATH. Each directory in MANPATH is the base directory of a man tree. However, you rarely want to specify the MANPATH on linux. Instead, you'd like the system to figure it out for you! In the best of worlds, you'd like the search for man pages (using MANPATH) to mimic the search for executables (using PATH), and this is what happens.

For brevity, we won't go into how the MANPATH is created on-the-fly. Basically, however, a configuration file /etc/man.config (/etc/man_db.conf on RH7) specifies where standard pages are (the default MANPATH), and where man pages are that correspond to programs in system directories (like /bin). To supplement these areas, man will look for 'standard places' corresponding to each non-standard directory in the user's PATH variable, so that man pages can be part of a large release without merging the pages into the system man areas (and making a mess). In addition, the standard man page area can have an overrides directory to supersede a page in that area.

To illustrate this process, let's start with a simple PATH, and without a LANG variable:

We can look at the MANPATH generated by man using the command man --path. (For convenience an alternate command manpath has been created.) The MANPATH that is generated is

Here, both /bin and /usr/bin were mapped to /usr/share/man (via /etc/man_db.conf directives), there was no /home/gboyd/man directory (which would have been the 'standard' place corresponding to /home/gboyd/bin), but there was a /pub/cs/gboyd/cs260a/man directory (corresponding to /pub/cs/gboyd/cs260a/bin). The final default man directory /usr/local/share/man was added at the end. Finally, since there was an overrides subdirectory in /usr/share/man, it was inserted before the first use of that directory.

Let's keep everything the same, but change the order of the PATH:

$ PATH=/pub/cs/gboyd/cs260a/bin:/bin:/usr/bin

The MANPATH is generated appropriately

$ manpath
/pub/cs/gboyd/cs260a/man:/usr/share/man/overrides:/usr/share/man:/usr/local/share/man

Superseding MANPATH

You can set your own MANPATH as an environment variable if you like. In this case, the only modification that will be made to it by man will be to insert language-specific directories on-the-fly.

Adding local pages

Local updates to man pages or additional man pages are most often stored in a separate tree that is configured as the first tree searched in MANPATH. This is the use of the /usr/local/share/man man tree in the MANPATH above, but on this system it is searched last (to find missing pages) rather than first (to supersede pages). As we have seen, the standard man tree /usr/share/man can have an overrides area to supersede pages in /usr/share/man. If the overrides area is found, it is searched first.