GNU Info

(emacs)Man Page

---

Next: Lisp Doc Prev: Info Lookup Up: Documentation

---

Enter node , (file) or (file)node

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 hope to replace
man pages with better-organized manuals that you can browse with Info
(Note: 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 manual-entry' command.  It runs
the `man' program to format the man page; if the system permits, it
runs `man' asynchronously, so that you can keep on editing while the
page is being formatted.  (On MS-DOS and MS-Windows 3, you cannot edit
while Emacs waits for `man' to finish.)  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 page 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 multiple
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, to read the man
page for the C library function `chmod' (as opposed to a command of the
same name), type `M-x manual-entry <RET> chmod(2) <RET>' (`chmod' is a
system call, so it is in section `2').

   If you do not specify a section, the results depend on how the `man'
program works on your system.  Some of them display only the first man
page they find.  Others display all man pages that have the specified
name, so you can move between them with the `M-n' and `M-p' keys(1).
The mode line shows how many manual pages are present in the Man buffer.

   By default, Emacs highlights the text in man pages.  For a long man
page, highlighting can take substantial time.  You can turn off
highlighting of man pages by setting the variable
`Man-fontify-manpage-flag' to `nil'.

   If you insert the text of a man page into an Emacs buffer in some
other fashion, you can use the command `M-x Man-fontify-manpage' to
perform the same conversions that `M-x manual-entry' does.

   An alternative way of reading manual pages is the `M-x woman'
command(2).  Unlike `M-x man', it does not run any external programs to
format and display the man pages; instead it does the job in Emacs
Lisp, so it works on systems such as MS-Windows, where the `man'
program (and the other programs it uses) are not generally available.

   `M-x woman' prompts for a name of a manual page, and provides
completion based on the list of manual pages that are installed on your
machine; the list of available manual pages is computed automatically
the first time you invoke `woman'.  The word at point in the current
buffer is used to suggest the default for the name the manual page.

   With a numeric argument, `M-x woman' recomputes the list of the
manual pages used for completion.  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.

   By default, `M-x woman' looks for manual pages in the directories
specified in the `MANPATH' environment variable.  (If `MANPATH' is not
set, `woman' uses a suitable default value, which can be customized.)
More precisely, `woman' looks for subdirectories that match the shell
wildcard pattern `man*' in each one of these directories, and tries to
find the manual pages in those subdirectories.  When first invoked,
`M-x woman' converts the value of `MANPATH' to a list of directory
names and stores that list in the `woman-manpath' variable.  Changing
the value of this variable is another way to control the list of
directories used.

   You can also augment the list of directories searched by `woman' by
setting the value of the `woman-path' variable.  This variable should
hold a list of specific directories which `woman' should search, in
addition to those in `woman-manpath'.  Unlike `woman-manpath', the
directories in `woman-path' are searched for the manual pages, not for
`man*' subdirectories.

   Occasionally, you might need to display manual pages that are not in
any of the directories listed by `woman-manpath' and `woman-path'.  The
`M-x woman-find-file' command prompts for a name of a manual page file,
with completion, and then formats and displays that file like `M-x
woman' does.

   The first time you invoke `M-x woman', it defines the Dired `W' key
to run the `woman-find-file' command on the current line's file.  You
can disable this by setting the variable `woman-dired-keys' to `nil'.
Note: Dired.  In addition, the Tar-mode `w' key is define to invoke
`woman-find-file' on the current line's archive member.

   For more information about setting up and using `M-x woman', see
Note: WoMan.

   ---------- Footnotes ----------

   (1) 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.  If you want this behavior, you can add this option to the value
of the variable `Man-switches'.

   (2) The name of the command, `woman', is an acronym for "w/o
(without) man," since it doesn't use the `man' program.