woman: Interface Options
5.1 Interface Options
=====================
These options control the process of locating the appropriate file to
browse, and the appearance of the browsing interface.
‘woman-man.conf-path’
A list of strings representing directories to search and/or files
to try for a man configuration file. The default is
("/etc" "/usr/local/lib")
[for GNU/Linux and Cygwin respectively.] A trailing separator (‘/’
for UNIX etc.) on directories is optional and the filename matched
if a directory is specified is the first to match the regexp
‘man.*\.conf’. If the environment variable ‘MANPATH’ is not set
but a configuration file is found then it is parsed instead (or as
well) to provide a default value for ‘woman-manpath’.
‘woman-manpath’
A list of strings representing _directory trees_ to search for Unix
manual files. Each element should be the name of a directory that
contains subdirectories of the form ‘man?’, or more precisely
subdirectories selected by the value of ‘woman-manpath-man-regexp’.
Non-directory and unreadable files are ignored. This can also
contain conses, with the car indicating a ‘PATH’ variable component
mapped to the directory tree given in the cdr.
If not set then the environment variable ‘MANPATH’ is used. If no
such environment variable is found, the default list is determined
by consulting the man configuration file if found. By default this
is expected to be either ‘/etc/man.config’ or
‘/usr/local/lib/man.conf’, which is controlled by the user option
‘woman-man.conf-path’. An empty substring of ‘MANPATH’ denotes the
default list. Otherwise, the default value of this variable is
("/usr/man" "/usr/local/man")
Any environment variables (names of which must have the Unix-style
form ‘$NAME’, e.g., ‘$HOME’, ‘$EMACSDATA’, ‘$EMACS_DIR’, regardless
of platform) are evaluated first but each element must evaluate to
a _single_ directory name. Trailing ‘/’s are ignored. (Specific
directories in ‘woman-path’ are also searched.)
On Microsoft platforms I recommend including drive letters
explicitly, e.g.:
("C:/Cygwin/usr/man" "C:/usr/man" "C:/usr/local/man")
The ‘MANPATH’ environment variable may be set using DOS
semi-colon-separated or Unix-style colon-separated syntax (but not
mixed).
‘woman-manpath-man-regexp’
A regular expression to match man directories _under_ the
‘woman-manpath’ directories. These normally have names of the form
‘man?’. Its default value is ‘"[Mm][Aa][Nn]"’, which is
case-insensitive mainly for the benefit of Microsoft platforms.
Its purpose is to avoid directories such as ‘cat?’, ‘.’, ‘..’, etc.
‘woman-path’
A list of strings representing _specific directories_ to search for
Unix manual files. For example
("/emacs/etc")
These directories are searched in addition to the directory trees
specified in ‘woman-manpath’. Each element should be a directory
string or ‘nil’, which represents the current directory when the
path is expanded and cached. However, the last component (only) of
each directory string is treated as a regexp (Emacs, not shell) and
the string is expanded into a list of matching directories.
Non-directory and unreadable files are ignored. The default value
on MS-DOS is
("$DJDIR/info" "$DJDIR/man/cat[1-9onlp]")
and on other platforms is ‘nil’.
Any environment variables (names of which must have the Unix-style
form ‘$NAME’, e.g., ‘$HOME’, ‘$EMACSDATA’, ‘$EMACS_DIR’, regardless
of platform) are evaluated first but each element must evaluate to
a _single_ directory name (regexp, see above). For example
("$EMACSDATA")
or equivalently
("$EMACS_DIR/etc")
Trailing ‘/’s are discarded. (The directory trees in
‘woman-manpath’ are also searched.) On Microsoft platforms I
recommend including drive letters explicitly.
‘woman-cache-level’
A positive integer representing the level of topic caching:
1. cache only the topic and directory lists (uses minimal memory,
but not recommended);
2. cache also the directories for each topic (faster, without
using much more memory);
3. cache also the actual filenames for each topic (fastest, but
uses twice as much memory).
The default value is currently 2, a good general compromise. If
the ‘woman’ command is slow to find files then try 3, which may be
particularly beneficial with large remote-mounted man directories.
Run the ‘woman’ command with a prefix argument or delete the cache
file ‘woman-cache-filename’ for a change to take effect. (Values <
1 behave like 1; values > 3 behave like 3.)
‘woman-cache-filename’
Either a string representing the full pathname of the WoMan
directory and topic cache file, or ‘nil’. It is used to save and
restore the cache between Emacs sessions. This is especially
useful with remote-mounted man page files! The default value of
‘nil’ suppresses this action. The “standard” non-‘nil’ filename is
‘~/.wmncach.el’. Remember that a prefix argument forces the
‘woman’ command to update and re-write the cache.
‘woman-dired-keys’
A list of ‘dired’ mode keys to be defined to run WoMan on the
current file, e.g., ‘("w" "W")’ or any non-‘nil’ atom to
automatically define ‘w’ and ‘W’ if they are unbound, or ‘nil’ to
do nothing. Default is ‘t’.
‘woman-imenu-generic-expression’
Imenu support for Sections and Subsections: an alist with elements
of the form ‘(MENU-TITLE REGEXP INDEX)’—see the documentation for
‘imenu-generic-expression’. Default value is
((nil "\n\\([A-Z].*\\)" 1) ; SECTION, but not TITLE
("*Subsections*" "^ \\([A-Z].*\\)" 1))
‘woman-imenu’
A boolean value that defaults to ‘nil’. If non-‘nil’ then WoMan
adds a Contents menu to the menubar by calling
‘imenu-add-to-menubar’.
‘woman-imenu-title’
A string representing the title to use if WoMan adds a Contents
menu to the menubar. Default is ‘"CONTENTS"’.
‘woman-use-topic-at-point’
A boolean value that defaults to ‘nil’. If non-‘nil’ then the
‘woman’ command uses the word at point as the topic, _without
interactive confirmation_, if it exists as a topic.
‘woman-use-topic-at-point-default’
A boolean value representing the default value for
‘woman-use-topic-at-point’. The default value is ‘nil’. [The
variable ‘woman-use-topic-at-point’ may be ‘let’-bound when ‘woman’
is loaded, in which case its global value does not get defined.
The function ‘woman-file-name’ sets it to this value if it is
unbound.]
‘woman-uncompressed-file-regexp’
A regular match expression used to select man source files
(ignoring any compression extension). The default value is
‘"\\.\\([0-9lmnt]\\w*\\)"’ [which means a filename extension is
required].
_Do not change this unless you are sure you know what you are
doing!_
The SysV standard man pages use two character suffixes, and this is
becoming more common in the GNU world. For example, the man pages
in the ‘ncurses’ package include ‘toe.1m’, ‘form.3x’, etc.
*Please note:* an optional compression regexp will be appended, so
this regexp _must not_ end with any kind of string terminator such
as ‘$’ or ‘\\'’.
‘woman-file-compression-regexp’
A regular match expression used to match compressed man file
extensions for which decompressors are available and handled by
auto-compression mode. It should begin with ‘\\.’ and end with
‘\\'’ and _must not_ be optional. The default value is
‘"\\.\\(g?z\\|bz2\\|xz\\)\\'"’, which matches the ‘gzip’, ‘bzip2’,
and ‘xz’ compression extensions.
_Do not change this unless you are sure you know what you are
doing!_
[It should be compatible with the ‘car’ of
‘jka-compr-file-name-handler-entry’, but that is unduly
complicated, includes an inappropriate extension (‘.tgz’) and is
not loaded by default!]
‘woman-use-own-frame’
If non-‘nil’ then use a dedicated frame for displaying WoMan
windows. This is useful only when WoMan is run under a window
system such as X or Microsoft Windows that supports real multiple
frames, in which case the default value is non-‘nil’.
Info Catalog
woman: Customization
woman: Formatting Options