The topic interface is accessed principally via the command
woman. The same command can be accessed via the menu item
‘Help->Manuals->Read Man Page (WoMan)...’ once WoMan has been
loaded. The command reads a manual topic in the minibuffer, which can
be the basename of a man file anywhere in the man file
structure. The “basename” in this context means the filename
without any directory component and without any extension or suffix
components that relate to the file type. So, for example, if there is
a compressed source file in Chapter 5 of the UNIX Programmer’s Manual
with the full pathname /usr/local/man/man5/man.conf.5.gz then
the topic is man.conf. Provided WoMan is configured correctly,
this topic will appear among the completions offered by woman.
If more than one file has the same topic name then WoMan will prompt
for which file to format. Completion of topics is case insensitive.
Clearly, woman has to know where to look for man files and there
are two customizable user options that store this information:
woman-manpath and woman-path. See Interface Options. If woman-manpath is not set explicitly then
WoMan tries to pick up the information that would be used by the
man command, as follows. If the environment variable
MANPATH is set, which seems to be the standard mechanism under
UNIX, then WoMan parses that. Otherwise, if WoMan can find a
configuration file named (by default) man.conf (or something very
similar), which seems to be the standard mechanism under GNU/Linux, then
it parses that. To be precise, “something very similar” means
starting with ‘man’ and ending with ‘.conf’ and possibly more
lowercase letters, e.g., manual.configuration.
The search path and/or precise full path name for this file are set by
the value of the customizable user option woman-man.conf-path.
If all else fails, WoMan uses a plausible default man search path.
If the above default configuration does not work correctly for any
reason then simply customize the value of woman-manpath. To
access man files that are not in a conventional man file hierarchy,
customize the value of woman-path to include the directories
containing the files. In this way, woman can access manual files
anywhere in the entire file system.
There are two differences between woman-manpath and
woman-path. Firstly, the elements of woman-manpath must
be directories that contain directories of man files, whereas the
elements of woman-path must be directories that contain man files
directly. Secondly, the last directory component of each element
of woman-path is treated as a regular (Emacs) match expression
rather than a fixed name, which allows collections of related
directories to be specified succinctly. Also, elements of
woman-manpath can be conses, indicating a mapping from
‘PATH’ environment variable components to man directory
hierarchies.
For topic completion to work, WoMan must build a list of all the manual
files that it can access, which can be very slow, especially if a
network is involved. For this reason, it caches various amounts of
information, after which retrieving it from the cache is very fast. If
the cache ever gets out of synchronism with reality, running the
woman command with a prefix argument (e.g., C-u M-x woman)
will force it to rebuild its cache. This is necessary only if the names
or locations of any man files change; it is not necessary if only their
contents change. It would always be necessary if such a change occurred
whilst Emacs were running and after WoMan has been loaded. It may be
necessary if such a change occurs between Emacs sessions and persistent
caching is used, although WoMan can detect some changes that invalidate
its cache and rebuild it automatically.
Customize the variable woman-cache-filename to save the cache
between Emacs sessions. This is recommended only if the woman
command is too slow the first time it is run in an Emacs session, while
it builds its cache in main memory, which may be very
slow. See The WoMan Topic Cache, for further details.