Info: (woman) Topic

woman: Topic

 
 3.1 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)...’ 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’.  Interface Options 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.  The WoMan Topic
 Cache Cache, for further details.
woman: Topic

Menu
