[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] Changes to emacs/man/woman.texi,v
From: |
Richard M. Stallman |
Subject: |
[Emacs-diffs] Changes to emacs/man/woman.texi,v |
Date: |
Fri, 27 Oct 2006 11:58:11 +0000 |
CVSROOT: /cvsroot/emacs
Module name: emacs
Changes by: Richard M. Stallman <rms> 06/10/27 11:58:11
Index: woman.texi
===================================================================
RCS file: /cvsroot/emacs/emacs/man/woman.texi,v
retrieving revision 1.22
retrieving revision 1.23
diff -u -b -r1.22 -r1.23
--- woman.texi 25 Mar 2006 23:13:20 -0000 1.22
+++ woman.texi 27 Oct 2006 11:58:10 -0000 1.23
@@ -91,7 +91,6 @@
@menu
* Introduction:: Introduction
* Background:: Background
-* Installation:: Installation and Setup
* Finding:: Finding and Formatting Man Pages
* Browsing:: Browsing Man Pages
* Customization:: Customization
@@ -127,7 +126,7 @@
@code{man} (or @code{manual-entry}) command to format a Unix-style
@dfn{manual page} (usually abbreviated to @dfn{man page}) for display,
but without calling any external programs. It is intended to emulate
-the whole of the @code{ROFF -man} macro package, plus those @code{ROFF}
+the whole of the @code{roff -man} macro package, plus those @code{roff}
requests (@pxref{Background, , Background}) that are most commonly used
in man pages. However, the emulation is modified to include the
reformatting done by the Emacs @code{man} command. No hyphenation is
@@ -145,7 +144,7 @@
This browser works quite well on simple well-written man files. It
works less well on idiosyncratic files that ``break the rules'' or use
-the more obscure @code{ROFF} requests directly. Current test results
+the more obscure @code{roff} requests directly. Current test results
are available in the file
@uref{http://centaur.maths.qmw.ac.uk/Emacs/WoMan/files/woman.status,
@file{woman.status}}.
@@ -169,7 +168,7 @@
@c ===================================================================
address@hidden Background, Installation, Introduction, Top
address@hidden Background, Finding, Introduction, Top
@comment node-name, next, previous, up
@chapter Background
@cindex background
@@ -178,31 +177,31 @@
Each such document is conventionally referred to as a @dfn{manual page},
or @dfn{man page} for short, even though some are very much longer than
one page. A man page is a document written using the Unix ``man''
-macros, which are themselves written in the NROFF/TROFF text processing
-markup language. @code{NROFF} and @code{TROFF} are text processors
+macros, which are themselves written in the nroff/troff text processing
+markup language. @code{nroff} and @code{troff} are text processors
originally written for the UNIX operating system by Joseph F. Ossanna at
Bell Laboratories, Murray Hill, New Jersey, address@hidden They are closely
related, and except in the few cases where the distinction between them
-is important I will refer to them both ambiguously as @dfn{ROFF}.
+is important I will refer to them both ambiguously as @code{roff}.
address@hidden markup consists of @dfn{requests} and @dfn{escape
address@hidden markup consists of @dfn{requests} and @dfn{escape
sequences}. A request occupies a complete line and begins with either a
period or a single forward quote. An escape sequences is embedded
within the input text and begins (by default) with a backslash. The
-original man macro package defines 20 new @code{ROFF} requests
+original man macro package defines 20 new @code{roff} requests
implemented as macros, which were considered to be sufficient for
writing man pages. But whilst in principle man pages use only the man
-macros, in practice a significant number use many other @code{ROFF}
+macros, in practice a significant number use many other @code{roff}
requests.
-The distinction between @code{TROFF} and @code{NROFF} is that
address@hidden was designed to drive a phototypesetter whereas
address@hidden was designed to produce essentially @acronym{ASCII} output for a
+The distinction between @code{troff} and @code{nroff} is that
address@hidden was designed to drive a phototypesetter whereas
address@hidden was designed to produce essentially @acronym{ASCII} output for a
character-based device similar to a teletypewriter (usually abbreviated
-to ``teletype'' or ``tty''). Hence, @code{TROFF} supports much finer
-control over output positioning than does @code{NROFF} and can be seen
+to ``teletype'' or ``tty''). Hence, @code{troff} supports much finer
+control over output positioning than does @code{nroff} and can be seen
as a forerunner of @TeX{}. Traditionally, man pages are either
-formatted by @code{TROFF} for typesetting or by @code{NROFF} for
+formatted by @code{troff} for typesetting or by @code{nroff} for
printing on a character printer or displaying on a screen. Of course,
over the last 25 years or so, the distinction between typeset output on
paper and characters on a screen has become blurred by the fact that
@@ -214,8 +213,8 @@
browsed on screen by running a program called @code{man}. This program
looks in a predefined set of directories for the man page matching a
specified topic, then either formats the source file by running
address@hidden or recovers a pre-formatted file, and displays it via a
-pager such as @code{more}. @code{NROFF} normally formats for a printer,
address@hidden or recovers a pre-formatted file, and displays it via a
+pager such as @code{more}. @code{nroff} normally formats for a printer,
so it paginates the output, numbers the pages, etc., most of which is
irrelevant when the document is browsed as a continuous scrollable
document on screen. The only concession to on-screen browsing normally
@@ -228,7 +227,7 @@
Emacs Manual}.
This command runs @code{man} as described above, perhaps in
the background, and then post-processes the output to remove much of the
address@hidden pagination such as page headers and footers, and places the
address@hidden pagination such as page headers and footers, and places the
result into an Emacs buffer. It puts this buffer into a special major
mode, which is tailored for man page browsing, and provides a number of
useful navigation commands, support for following references, etc. It
@@ -236,7 +235,7 @@
menu or mouse support. The Emacs man package appears to have been
developed over about 10 years, from the late 1980s to the late 1990s.
-There is considerable inefficiency in having @code{NROFF} paginate a
+There is considerable inefficiency in having @code{nroff} paginate a
document and then removing most of the pagination!
WoMan is an Emacs Lisp library that provides an emulation of the
@@ -253,22 +252,22 @@
read because ports of the Unix-style @code{man} program can be a little
awkward to set up. I decided that it should not be too hard to emulate
the 20 @code{man} macros directly, without treating them as macros and
-largely ignoring the underlying @code{ROFF} requests, given the text
+largely ignoring the underlying @code{roff} requests, given the text
processing capabilities of Emacs. This proved to be essentially true,
and it did not take a great deal of work to be able to format simple man
pages acceptably.
One problem arose with the significant number of man pages that use
address@hidden requests in addition to the @code{man} macros, and since
address@hidden requests in addition to the @code{man} macros, and since
releasing the first version of WoMan I have been continually extending
-it to support more @code{ROFF} requests. WoMan can now format a
+it to support more @code{roff} requests. WoMan can now format a
significant proportion of the man pages that I have tested, either well
or at least readably. However, I have added capabilities partly by
making additional passes through the document, a design that is
fundamentally flawed. This can only be solved by a major re-design of
WoMan to handle the major formatting within a single recursive pass,
rather than the present multiple passes without any significant
-recursion. There are some @code{ROFF} requests that cannot be handled
+recursion. There are some @code{roff} requests that cannot be handled
satisfactorily within the present design. Some of these are currently
handled by kludges that ``usually more or less work.''
@@ -288,227 +287,18 @@
WoMan @emph{does not} replace @code{man}, although it does use a number
of the facilities implemented in the Emacs @code{man} library. WoMan
and man can happily co-exist, which is very useful for comparison and
-debugging purposes. The only way in which WoMan affects @code{man} is
-that it adds a timer to indicate how long @code{man} has taken to format
-a man page. The timing is as compatible as possible with the timing
-built into WoMan, for as fair a comparison as possible. The time
-comparison seems to depend on the details of the platform, the version
-of @code{man} in use, etc, but times are similar and WoMan is never
-significantly slower than @code{man}. This is despite the fact that
-WoMan is running byte code whereas most of the formatting done by
address@hidden uses machine code, and is a testimony to the quality of the
-Emacs Lisp system.
+debugging purposes.
address@hidden simulates address@hidden characters by using one or more
address@hidden simulates address@hidden characters by using one or more
@acronym{ASCII} characters. WoMan should be able to do much better than
this. I have recently begun to add support for WoMan to use more of the
characters in its default font and to use a symbol font, and it is an
aspect that I intend to develop further in the near future. It should
-be possible to move WoMan from an emulation of @code{NROFF} to an
-emulation of @code{TROFF} as GNU Emacs moves to providing bit-mapped
+be possible to move WoMan from an emulation of @code{nroff} to an
+emulation of @code{troff} as GNU Emacs moves to providing bit-mapped
display facilities.
address@hidden
===================================================================
-
address@hidden Installation, Finding, Background, Top
address@hidden node-name, next, previous, up
address@hidden Installation and Setup
address@hidden installation
address@hidden setup
-
-No installation is necessary if you just want to run the version of
-WoMan distributed with GNU Emacs 21 or later, although some additional
-setup may still be desirable.
-
-If you are installing @file{woman.el}, either to update the version
-distributed with GNU Emacs or because WoMan was not distributed with
-your version of Emacs, then you need to put the file in a directory in
-your Emacs load path and byte compile it. A good directory to use is
-the @file{site-lisp} directory in your Emacs file tree, e.g.@:
address@hidden/usr/local/share/emacs/@var{version}/site-lisp/} (where
address@hidden is your Emacs version), provided you have write access to
-it. If you use a directory that is not included by default in your
-Emacs load path then you need to add something like this to your
address@hidden initialization file:
-
address@hidden
-(add-to-list 'load-path "my-lisp")
address@hidden lisp
-
address@hidden
-where @file{my-lisp} is the pathname of the directory. @xref{Init File, ,
-The Init File ~/.emacs, emacs, The Emacs Editor}, for further details on
-customizing Emacs in general.
-
-You can byte-compile the file by using the Emacs command
address@hidden or by opening the directory containing the
-file, putting point on it and pressing the key @kbd{B}. (In fact, if
-the file is compiled then it is only the compiled file that needs to be
-in the Emacs load path, but leaving the source file there will do no
-harm.)
-
address@hidden Setup
-
-Setup that is either necessary or desirable consists of adding a small
-amount of Emacs Lisp code to your @file{.emacs} initialization file. It
-may be necessary (or at least convenient) to make WoMan autoload (if you
-are not running GNU Emacs 21 or later) and to set the search path used
-by the @code{woman} interface. You may also find it convenient to make
-various WoMan menu and key bindings available and to make WoMan
-customizable even before WoMan has been loaded.
-
-It is possible to run WoMan from a command line (from outside or even
-from inside Emacs) by suitably configuring your command interpreter.
-
address@hidden
-* Autoloading:: Autoloading
-* Search Path:: Search Path
-* Auto Bindings:: Preloading Menu and Key Bindings
-* Auto Customization:: Preloading Customization
-* Command Line:: Command Line Access
address@hidden menu
-
-
address@hidden Autoloading, Search Path, Installation, Installation
address@hidden node-name, next, previous, up
address@hidden Autoloading
address@hidden autoloading
-
-If you are not running GNU Emacs 21 or later then you are recommended to
-add these autoloads to your @file{.emacs} file:
-
address@hidden
-(autoload 'woman "woman"
- "Decode and browse a Unix man page." t)
-(autoload 'woman-find-file "woman"
- "Find, decode and browse a specific Unix man-page file." t)
-(autoload 'woman-dired-find-file "woman"
- "In dired, run the WoMan man-page browser on this file." t)
address@hidden lisp
-
address@hidden
-(In GNU Emacs 21 and later these autoloads are predefined.)
-
-
address@hidden Search Path, Auto Bindings, Autoloading, Installation
address@hidden node-name, next, previous, up
address@hidden Search Path
address@hidden search path
-
-The next step is necessary if you want to use the friendliest WoMan
-interface, which is recommended in general. If the @code{MANPATH}
-environment variable is set then WoMan will use it; alternatively (or
-additionally), if your platform uses a man configuration file (as do
-many versions of Linux) then WoMan will use it, provided it can find it.
-(This may need configuration. @xref{Interface Options, , Interface
-Options}.) If these mechanisms correctly define the search path for man
-pages then no further action is required.
-
-Otherwise you may need to customize the user option
address@hidden, and you may also want to customize the user option
address@hidden @xref{Customization, , Customization}. Now you can
-execute the extended command @code{woman} and enter or select a manual
-topic using completion, and if necessary select a filename, again using
-completion. By default, WoMan suggests the word nearest to point in the
-current buffer as the topic.
-
-
address@hidden Auto Bindings, Auto Customization, Search Path, Installation
address@hidden node-name, next, previous, up
address@hidden Preloading Menu and Key Bindings
address@hidden preloading menu and key bindings
address@hidden menu bindings, preloading
address@hidden key bindings, preloading
address@hidden bindings, preloading
-
-Once WoMan is loaded it adds an item to the @samp{Help} menu and defines
-one or more keys in dired mode to run WoMan on the current file. If you
-would like these facilities always to be available, even before WoMan is
-loaded, then add the following to your @file{.emacs} file:
-
address@hidden
-(define-key-after menu-bar-manuals-menu [woman]
- '(menu-item "Read Man Page (WoMan)..." woman
- :help "Man-page documentation Without Man") t)
-
-(add-hook 'dired-mode-hook
- (lambda ()
- (define-key dired-mode-map "W" 'woman-dired-find-file)))
address@hidden lisp
-
-(By default, WoMan will automatically define the dired keys @kbd{W} and
address@hidden when it loads, but only if they are not already defined. This
-behavior is controlled by the user option @code{woman-dired-keys}.
-Note that the @code{dired-x} (dired extra) package binds
address@hidden to the key @kbd{w}, although @kbd{W}
-appears to be unused. The @code{dired-x} package will over-write the
-WoMan binding for @kbd{w}, whereas (by default) WoMan will not overwrite
-the @code{dired-x} binding.)
-
-
address@hidden Auto Customization, Command Line, Auto Bindings, Installation
address@hidden node-name, next, previous, up
address@hidden Preloading Customization
address@hidden preloading customization
address@hidden customization, preloading
-
-WoMan supports the GNU Emacs 20+ customization facility, and puts a
-customization group called @code{WoMan} in the @code{Help} group under
-the top-level @code{Emacs} group. In order to be able to customize
-WoMan without first loading it, add the following to your @file{.emacs}
-file:
-
address@hidden
-(defgroup woman nil
- "Browse UNIX manual pages `wo (without) man'."
- :tag "WoMan" :group 'help :load "woman")
address@hidden lisp
-
-
address@hidden Command Line, , Auto Customization, Installation
address@hidden node-name, next, previous, up
address@hidden Command Line Access
address@hidden command line access
-
-If you really want to square the man-woman circle then you can! If you
-run the GNU command interpreter @code{bash} then you might care to
-define the following @code{bash} function in your @code{bash}
-initialization file @file{.bashrc}:
-
address@hidden
-man() @{ gnudoit -q '(raise-frame (selected-frame)) (woman' \"$1\" ')' ; @}
address@hidden example
-
-If you use a Microsoft command interpreter (@file{command.com} or
address@hidden) then you can create a file called @file{man.bat}
-somewhere in your path containing the two lines:
-
address@hidden
-@@echo off
-gnudoit -q (raise-frame (selected-frame)) (woman \"%1\")
address@hidden example
-
-and then (e.g.@: from a command prompt or the @samp{Run...} option in the
-Windows @samp{Start} menu) just execute
-
address@hidden
-man man_page_name
address@hidden example
-
-(Of course, if you already have a @code{man} command installed then you
-could call these commands @code{woman} instead of @code{man}.)
-
-The above examples assume that you have the @code{gnuserv} Emacs
-client-server package installed (which I recommend). It would be
-possible to do something similar by calling Emacs directly, but that is
-less satisfactory, because you are likely to end up with multiple copies
-of Emacs running, which is generally inelegant, inefficient and
-inconvenient. If you run a different command interpreter then something
-similar to the above suggestions should be possible.
-
address@hidden
===================================================================
-
address@hidden Finding, Browsing, Installation, Top
address@hidden Finding, Browsing, Background, Top
@comment node-name, next, previous, up
@chapter Finding and Formatting Man Pages
@cindex using, finding man pages
@@ -572,19 +362,18 @@
The topic interface is accessed principally via the command
@code{woman}. The same command can be accessed via the menu item
address@hidden>Manuals->Read Man Page (WoMan)...} either once WoMan has been
-loaded or if it is set up specially. @xref{Installation, , Installation
-and Setup}. The command reads a manual topic in the minibuffer, which
-can be the @dfn{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 @file{/usr/local/man/man5/man.conf.5.gz} then the topic is
address@hidden Provided WoMan is configured correctly, this topic
-will appear among the completions offered by @code{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.
address@hidden>Manuals->Read Man Page (WoMan)...} once WoMan has been
+loaded. The command reads a manual topic in the minibuffer, which can
+be the @dfn{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 @file{/usr/local/man/man5/man.conf.5.gz} then
+the topic is @code{man.conf}. Provided WoMan is configured correctly,
+this topic will appear among the completions offered by @code{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, @code{woman} has to know where to look for man files and there
are two customizable user options that store this information:
@@ -834,7 +623,7 @@
@cindex fonts
@cindex faces
-Fonts used by @code{ROFF} are handled by WoMan as faces, the details of
+Fonts used by @code{roff} are handled by WoMan as faces, the details of
which are customizable. @xref{Faces, , Faces}. WoMan supports both the
italic and bold fonts normally used in man pages, together with a single
face to represent all unknown fonts (which are occasionally used in
@@ -1070,15 +859,12 @@
@chapter Customization
@cindex customization
-All WoMan user options are customizable, and it is recommended to change
-them only via the standard Emacs customization facilities. WoMan
-defines a top-level customization group called @code{WoMan} under the
-parent group @code{Help}. The WoMan customization group is available
-only once WoMan has been loaded unless it is specially set up to be
-automatically available. @xref{Auto Customization, , Preloading
-Customization}. It can be accessed either via the standard Emacs
-facilities, e.g.@: via the @samp{Help->Customize} submenu, or via the
-WoMan major mode menu.
+All WoMan user options are customizable, and it is recommended to
+change them only via the standard Emacs customization facilities.
+WoMan defines a top-level customization group called @code{WoMan}
+under the parent group @code{Help}. It can be accessed either via the
+standard Emacs facilities, e.g.@: via the @samp{Help->Customize}
+submenu, or via the WoMan major mode menu.
The top-level WoMan group contains only a few general options and three
subgroups. The hooks are provided only for special purposes that, for
@@ -1385,7 +1171,7 @@
@item woman-ignore
A boolean value. If address@hidden then unrecognised requests etc. are
-ignored. Default is @code{t}. This gives the standard @code{ROFF} behavior.
+ignored. Default is @code{t}. This gives the standard @code{roff} behavior.
If @code{nil} then they are left in the buffer, which may aid debugging.
@item woman-preserve-ascii
@@ -1395,8 +1181,8 @@
saved to a file. Default is @code{nil}.
@item woman-emulation
-WoMan emulation, currently either @code{NROFF} or @code{TROFF}. Default
-is @code{NROFF}. @code{TROFF} emulation is experimental and largely
+WoMan emulation, currently either @code{nroff} or @code{troff}. Default
+is @code{nroff}. @code{troff} emulation is experimental and largely
untested.
@end vtable
@@ -1417,8 +1203,8 @@
@item woman-italic-face
Face for italic font in man pages. Default: italic, underlined,
-foreground red. This is overkill! @code{TROFF} uses just italic;
address@hidden uses just underline. You should probably select either
+foreground red. This is overkill! @code{troff} uses just italic;
address@hidden uses just underline. You should probably select either
italic or underline as you prefer, but not both, although italic and
underline work together perfectly well!
@@ -1494,7 +1280,7 @@
Uninterpreted escape sequences are also logged (in some cases).
By resetting the variable @code{woman-ignore} to @code{nil} (by default
-it is @code{t}), uninterpreted @code{ROFF} requests can optionally be
+it is @code{t}), uninterpreted @code{roff} requests can optionally be
left in the formatted buffer to indicate precisely where they occurred.
@xref{Interface Options, , Interface Options}.
@@ -1514,7 +1300,7 @@
WoMan currently assumes 10 characters per inch horizontally, hence a
horizontal resolution of 24 basic units, and 5 lines per inch
vertically, hence a vertical resolution of 48 basic units.
-(@code{NROFF} uses 240 per inch.)
+(@code{nroff} uses 240 per inch.)
@heading Vertical spacing and blank lines
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Emacs-diffs] Changes to emacs/man/woman.texi,v,
Richard M. Stallman <=