GNU Info

(woman)Topic

---

Next: Filename Prev: Finding Up: Finding

---

Enter node , (file) or (file)node

Topic Interface
===============

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)...' either once WoMan has been loaded or if it is set
up specially.  Note: Installation and Setup.  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'.  Note: 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 having two name components separated by
a dot and respectively containing `man' and beginning with `conf', 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.

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.  Note: The WoMan
Topic Cache, for further details.

Cache

The WoMan Topic Cache

Word at point

Using the ``Word at Point'' as a Topic Suggestion