Next: Lisp Doc, Previous: Info Lookup, Up: Documentation [Contents][Index]

#### 26.6.2 Man Page Lookup

On Unix, the main form of on-line documentation was the manual page or man page. In the GNU operating system, we aim to replace man pages with better-organized manuals that you can browse with Info (see Misc Help). This process is not finished, so it is still useful to read manual pages.

You can read the man page for an operating system command, library function, or system call, with the `M-x man` command. This prompts for a topic, with completion (see Completion), and runs the `man` program to format the corresponding man page. If the system permits, it runs `man` asynchronously, so that you can keep on editing while the page is being formatted. The result goes in a buffer named `*Man topic*`. These buffers use a special major mode, Man mode, that facilitates scrolling and jumping to other manual pages. For details, type `C-h m` while in a Man mode buffer.

Each man page belongs to one of ten or more sections, each named by a digit or by a digit and a letter. Sometimes there are man pages with the same name in different sections. To read a man page from a specific section, type ‘`topic(section)`’ or ‘`section topic`’ when `M-x manual-entry` prompts for the topic. For example, the man page for the C library function `chmod` is in section 2, but there is a shell command of the same name, whose man page is in section 1; to view the former, type `M-x manual-entry RET chmod(2) RET`.

If you do not specify a section, `M-x man` normally displays only the first man page found. On some systems, the `man` program accepts a ‘`-a`’ command-line option, which tells it to display all the man pages for the specified topic. To make use of this, change the value of the variable `Man-switches` to ‘`"-a"`’. Then, in the Man mode buffer, you can type `M-n` and `M-p` to switch between man pages in different sections. The mode line shows how many manual pages are available.

An alternative way of reading manual pages is the `M-x woman` command. Unlike `M-x man`, it does not run any external programs to format and display the man pages; the formatting is done by Emacs, so it works on systems such as MS-Windows where the `man` program may be unavailable. It prompts for a man page, and displays it in a buffer named `*WoMan section topic`.

`M-x woman` computes the completion list for manpages the first time you invoke the command. With a numeric argument, it recomputes this list; this is useful if you add or delete manual pages.

If you type a name of a manual page and `M-x woman` finds that several manual pages by the same name exist in different sections, it pops up a window with possible candidates asking you to choose one of them.

For more information about setting up and using `M-x woman`, see the WoMan Info manual, which is distributed with Emacs.

Next: Lisp Doc, Previous: Info Lookup, Up: Documentation [Contents][Index]