diff man/misc.texi @ 36168:df827c1def99

Clean up close-quote punctuation.

--- a/man/misc.texi	Sat Feb 17 17:47:20 2001 +0000
+++ b/man/misc.texi	Sat Feb 17 17:50:28 2001 +0000
@@ -307,7 +307,7 @@
 
   Emacs has commands for passing single command lines to inferior shell
 processes; it can also run a shell interactively with input and output
-to an Emacs buffer named @samp{*shell*} or run s shell inside a terminal
+to an Emacs buffer named @samp{*shell*} or run a shell inside a terminal
 emulator window.
 
 There is a shell implemented entirely in Emacs, documented in a separate
@@ -338,6 +338,7 @@
 * Interactive Shell::      Permanent shell taking input via Emacs.
 * Shell Mode::             Special Emacs commands used with permanent shell.
 * History: Shell History.  Repeating previous commands in a shell buffer.
+* Directory Tracking::     Keeping track when the subshell changes directory.
 * Options: Shell Options.  Options for customizing Shell mode.
 * Terminal emulator::      An Emacs window as a terminal emulator.
 * Term Mode::              Special Emacs commands used in Term mode.
@@ -419,6 +420,13 @@
 process it; this happens whenever Emacs is waiting for keyboard input or
 for time to elapse.
 
+@cindex @code{comint-highlight-input} face
+@cindex @code{comint-highlight-prompt} face
+  Input lines, once you submit them, are displayed using the face
+@code{comint-highlight-input}, and prompts are displayed using the
+face @code{comint-highlight-prompt}.  This makes it easier to see
+previous input lines in the buffer.  @xref{Faces}.
+
   To make multiple subshells, rename the buffer @samp{*shell*} to
 something different using @kbd{M-x rename-uniquely}.  Then type @kbd{M-x
 shell} again to create a new buffer @samp{*shell*} with its own
@@ -437,49 +445,17 @@
 @env{PATH} when Emacs is started.  Your @file{.emacs} file can override
 either or both of these default initializations.
 
+  Emacs sends the new shell the contents of the file
+@file{~/.emacs_@var{shellname}} as input, if it exists, where
+@var{shellname} is the name of the file that the shell was loaded
+from.  For example, if you use bash, the file sent to it is
+@file{~/.emacs_bash}.
+
   To specify a coding system for the shell, you can use the command
 @kbd{C-x @key{RET} c} immediately before @kbd{M-x shell}.  You can also
 specify a coding system after starting the shell by using @kbd{C-x
 @key{RET} p} in the shell buffer.  @xref{Specify Coding}.
 
-  As soon as the subshell is started, it is sent as input the contents
-of the file @file{~/.emacs_@var{shellname}}, if that file exists, where
-@var{shellname} is the name of the file that the shell was loaded from.
-For example, if you use bash, the file sent to it is
-@file{~/.emacs_bash}.
-
-@vindex shell-pushd-regexp
-@vindex shell-popd-regexp
-@vindex shell-cd-regexp
-  @code{cd}, @code{pushd} and @code{popd} commands given to the inferior
-shell are watched by Emacs so it can keep the @samp{*shell*} buffer's
-default directory the same as the shell's working directory.  These
-commands are recognized syntactically by examining lines of input that are
-sent.  If you use aliases for these commands, you can tell Emacs to
-recognize them also.  For example, if the value of the variable
-@code{shell-pushd-regexp} matches the beginning of a shell command line,
-that line is regarded as a @code{pushd} command.  Change this variable when
-you add aliases for @samp{pushd}.  Likewise, @code{shell-popd-regexp} and
-@code{shell-cd-regexp} are used to recognize commands with the meaning of
-@samp{popd} and @samp{cd}.  These commands are recognized only at the
-beginning of a shell command line.@refill
-
-@vindex shell-set-directory-error-hook
-  If Emacs gets an error while trying to handle what it believes is a
-@samp{cd}, @samp{pushd} or @samp{popd} command, it runs the hook
-@code{shell-set-directory-error-hook} (@pxref{Hooks}).
-
-@findex dirs
-  If Emacs does not properly track changes in the current directory of
-the subshell, use the command @kbd{M-x dirs} to ask the shell what its
-current directory is.  This command works for shells that support the
-most common command syntax; it may not work for unusual shells.
-
-@findex dirtrack-mode
-  You can also use @kbd{M-x dirtrack-mode} to enable (or disable) an
-alternative and more aggressive method of tracking changes in the
-current directory.
-
   Emacs defines the environment variable @env{EMACS} in the subshell,
 with value @code{t}.  A shell script can check this variable to
 determine whether it has been run from an Emacs subshell.
@@ -499,12 +475,11 @@
 @item @key{RET}
 @kindex RET @r{(Shell mode)}
 @findex comint-send-input
-@vindex comint-use-prompt-regexp-instead-of-fields
 @cindex prompt, shell
-At end of buffer send line as input; otherwise, copy current line to end
-of buffer and send it (@code{comint-send-input}).  When a line is
-copied, any prompt is left out (where the prompt is the part of the line
-that was not input by the user; see also
+At end of buffer send line as input; otherwise, copy current line to
+end of buffer and send it (@code{comint-send-input}).  When a line is
+copied, any prompt at the beginning if the line (text output by
+programs preceding your input) is omitted.  See also
 @code{comint-use-prompt-regexp-instead-of-fields}).
 
 @item @key{TAB}
@@ -827,38 +802,79 @@
 @subsubsection Shell History References
 @cindex history reference
 
-  Various shells including csh and bash support @dfn{history references}
-that begin with @samp{!} and @samp{^}.  Shell mode can understand these
-constructs and perform the history substitution for you.  If you insert
-a history reference and type @key{TAB}, this searches the input history
-for a matching command, performs substitution if necessary, and places
-the result in the buffer in place of the history reference.  For
-example, you can fetch the most recent command beginning with @samp{mv}
-with @kbd{! m v @key{TAB}}.  You can edit the command if you wish, and
-then resubmit the command to the shell by typing @key{RET}.
+  Various shells including csh and bash support @dfn{history
+references} that begin with @samp{!} and @samp{^}.  Shell mode
+recognizes these constructs, and can perform the history substitution
+for you.
+
+  If you insert a history reference and type @key{TAB}, this searches
+the input history for a matching command, performs substitution if
+necessary, and places the result in the buffer in place of the history
+reference.  For example, you can fetch the most recent command
+beginning with @samp{mv} with @kbd{! m v @key{TAB}}.  You can edit the
+command if you wish, and then resubmit the command to the shell by
+typing @key{RET}.
+
+@vindex comint-input-autoexpand
+@findex comint-magic-space
+  Shell mode can optionally expand history references in the buffer
+when you send them to the shell.  To request this, set the variable
+@code{comint-input-autoexpand} to @code{input}.  You can make
+@key{SPC} perform history expansion by binding @key{SPC} to the
+command @code{comint-magic-space}.
 
 @vindex shell-prompt-pattern
 @vindex comint-prompt-regexp
 @vindex comint-use-prompt-regexp-instead-of-fields
 @cindex prompt, shell
-  History references take effect only following a shell prompt.  The
-prompt is defined to be any text not input by the user, unless the
-variable @code{comint-use-prompt-regexp-instead-of-fields} is
-non-@code{nil} (the default value is @code{nil}).  When
-@code{comint-use-prompt-regexp-instead-of-fields} is non-@code{nil}, the
-variable @code{shell-prompt-pattern} specifies how to recognize a shell
-prompt, and comint modes in general use the variable
-@code{comint-prompt-regexp} (shell mode uses @code{shell-prompt-pattern}
-to set up the local value of @code{comint-prompt-regexp}).
+  Shell mode recognizes history references when they follow a prompt.
+Normally, any text output by a program at the beginning of an input
+line is considered a prompt.  However, if the variable
+@code{comint-use-prompt-regexp-instead-of-fields} is non-@code{nil},
+then Comint mode uses a regular expression to recognize prompts.  In
+general, the variable @code{comint-prompt-regexp} specifies the
+regular expression; Shell mode uses the variable
+@code{shell-prompt-pattern} to set up @code{comint-prompt-regexp} in
+the shell buffer.
+
+@node Directory Tracking
+@subsection Directory Tracking
+@cindex directory tracking
+
+@vindex shell-pushd-regexp
+@vindex shell-popd-regexp
+@vindex shell-cd-regexp
+  Shell mode keeps track of @samp{cd}, @samp{pushd} and @samp{popd}
+commands given to the inferior shell, so it can keep the
+@samp{*shell*} buffer's default directory the same as the shell's
+working directory.  It recognizes these commands syntactically, by
+examining lines of input that are sent.
 
-@vindex comint-input-autoexpand
-  Shell mode can optionally expand history references in the buffer when
-you send them to the shell.  To request this, set the variable
-@code{comint-input-autoexpand} to @code{input}.
+  If you use aliases for these commands, you can tell Emacs to
+recognize them also.  For example, if the value of the variable
+@code{shell-pushd-regexp} matches the beginning of a shell command
+line, that line is regarded as a @code{pushd} command.  Change this
+variable when you add aliases for @samp{pushd}.  Likewise,
+@code{shell-popd-regexp} and @code{shell-cd-regexp} are used to
+recognize commands with the meaning of @samp{popd} and @samp{cd}.
+These commands are recognized only at the beginning of a shell command
+line.
 
-@findex comint-magic-space
-  You can make @key{SPC} perform history expansion by binding @key{SPC} to
-the command @code{comint-magic-space}.
+@vindex shell-set-directory-error-hook
+  If Emacs gets an error while trying to handle what it believes is a
+@samp{cd}, @samp{pushd} or @samp{popd} command, it runs the hook
+@code{shell-set-directory-error-hook} (@pxref{Hooks}).
+
+@findex dirs
+  If Emacs gets confused about changes in the current directory of the
+subshell, use the command @kbd{M-x dirs} to ask the shell what its
+current directory is.  This command works for shells that support the
+most common command syntax; it may not work for unusual shells.
+
+@findex dirtrack-mode
+  You can also use @kbd{M-x dirtrack-mode} to enable (or disable) an
+alternative and more aggressive method of tracking changes in the
+current directory.
 
 @node Shell Options
 @subsection Shell Mode Options
@@ -929,63 +945,56 @@
 underlying shell, of course.
 
 @node Terminal emulator
-@subsection Interactive Inferior Shell with Terminal Emulator
+@subsection Emacs Terminal Emulator
 @findex term
 
-  To run a subshell in a terminal emulator, putting its typescript in an Emacs
-buffer, use @kbd{M-x term}.  This creates (or reuses) a buffer named
-@samp{*term*} and runs a subshell with input coming from your keyboard and
-output going to that buffer.
+  To run a subshell in a terminal emulator, putting its typescript in
+an Emacs buffer, use @kbd{M-x term}.  This creates (or reuses) a
+buffer named @samp{*term*}, and runs a subshell with input coming from
+your keyboard, and output going to that buffer.
 
-All the normal keys that you type are sent without any interpretation
-by Emacs directly to the subshell, as ``terminal input''.
-Any ``echo'' of your input is the responsibility of the subshell.
-(The exception is the terminal escape character,
-which by default is @kbd{C-c}.  @xref{Term Mode}.)
+  The terminal emulator uses Term mode, which has two input modes.  In
+line mode, Term basically acts like Shell mode; see @ref{Shell Mode}.
+
+  In char mode, each character is sent directly to the inferior
+subshell, as ``terminal input.''  Any ``echoing'' of your input is the
+responsibility of the subshell.  The sole exception is the terminal
+escape character, which by default is @kbd{C-c} (@pxref{Term Mode}).
 Any ``terminal output'' from the subshell goes into the buffer,
 advancing point.
 
-  Some programs (such as Emacs itself) need to control the
-appearance on the terminal screen in detail.  They do this by
-sending special control codes.  The exact control
-codes needed vary from terminal to terminal, but nowadays
-most terminals and terminal emulators (including @code{xterm})
-understand the ANSI-standard (VT100-style) escape sequences.
-Term mode also understands these escape sequences,
-and for each control code does the appropriate thing
-to change the buffer so that the appearance of the window
-matches what it would be on a real terminal.
-Thus you can actually run Emacs inside an Emacs Term window!
+  Some programs (such as Emacs itself) need to control the appearance
+on the terminal screen in detail.  They do this by sending special
+control codes.  The exact control codes needed vary from terminal to
+terminal, but nowadays most terminals and terminal emulators
+(including @code{xterm}) understand the ANSI-standard (VT100-style)
+escape sequences.  Term mode recognizes these escape sequences, and
+handles each one appropriately, changing the buffer so that the
+appearance of the window matches what it would be on a real terminal.
+You can actually run Emacs inside an Emacs Term window.
 
-   Emacs does not wait for the subshell to do anything.  You can switch
-windows or buffers and edit them while the shell is waiting, or while
-it is running a command.  Output from the subshell waits until Emacs
-has time to process it; this happens whenever Emacs is waiting for
-keyboard input or for time to elapse.
+   The file name used to load the subshell is determined the same way
+as for Shell mode.  To make multiple terminal emulators, rename the
+buffer @samp{*term*} to something different using @kbd{M-x
+rename-uniquely}, just as with Shell mode.
 
-   To make multiple terminal emulators, rename the buffer @samp{*term*}
-to something different using @kbd{M-x rename-uniquely},
-just as with Shell mode.
-
-   The file name used to load the subshell is determined
-the same way as for Shell mode.
-
-Unlike Shell mode, Term mode does not track the current directory
-by examining your input.  Instead, if you use a programmable
-shell, you can have it tell Term what the current directory is.
-This is done automatically by @code{bash} version 1.15 and later.
+  Unlike Shell mode, Term mode does not track the current directory by
+examining your input.  But some shells can tell Term what the current
+directory is.  This is done automatically by @code{bash} version 1.15
+and later.
 
 @node Term Mode
 @subsection Term Mode
 @cindex Term mode
 @cindex mode, Term
 
-  Term uses Term mode, which has two input modes:
-In line mode, Term basically acts like Shell mode.  @xref{Shell Mode}.
-In Char mode, each character is sent directly to the inferior subshell,
-except for the Term escape character, normally @kbd{C-c}.
+  The terminal emulator uses Term mode, which has two input modes.  In
+line mode, Term basically acts like Shell mode; see @ref{Shell Mode}.
+In char mode, each character is sent directly to the inferior
+subshell, except for the Term escape character, normally @kbd{C-c}.
 
-To switch between line and char mode, use these commands:
+  To switch between line and char mode, use these commands:
+
 @table @kbd
 @kindex C-c C-k @r{(Term mode)}
 @findex term-char-mode
@@ -998,7 +1007,8 @@
 Switch to char mode.  Do nothing if already in char mode.
 @end table
 
-The following commands are only available in Char mode:
+  The following commands are only available in char mode:
+
 @table @kbd
 @item C-c C-c
 Send a literal @key{C-c} to the sub-shell.
@@ -1010,26 +1020,26 @@
 @end table
 
 @node Paging in Term
-@subsection Paging in the terminal emulator
+@subsection Page-At-A-Time Output
+@cindex page-at-a-time
 
-Term mode has a pager feature.  When the pager is enabled,
-term mode will pause at the end of each screenful.
+  Term mode has a page-at-a-time feature.  When enabled it makes
+output pause at the end of each screenful.
 
 @table @kbd
 @kindex C-c C-q @r{(Term mode)}
 @findex term-pager-toggle
 @item C-c C-q
-Toggles the pager feature:  Disables the pager if it is enabled,
-and vice versa.  This works in both line and char modes.
-If the pager enabled, the mode-line contains the word @samp{page}.
+Toggle the page-at-a-time feature.  This command works in both line
+and char modes.  When page-at-a-time is enabled, the mode-line
+displays the word @samp{page}.
 @end table
 
-If the pager is enabled, and Term receives more than a screenful
-of output since your last input, Term will enter More break mode.
-This is indicated by @samp{**MORE**} in the mode-line.
-Type a @kbd{Space} to display the next screenful of output.
-Type @kbd{?} to see your other options.  The interface is similar
-to the Unix @code{more} program.
+  With page-at-a-time enabled, whenever Term receives more than a
+screenful of output since your last input, it pauses, displaying
+@samp{**MORE**} in the mode-line.  Type @key{SPC} to display the next
+screenful of output.  Type @kbd{?} to see your other options.  The
+interface is similar to the Unix @code{more} program.
 
 @node Remote Host
 @subsection Remote Host Shell
@@ -1042,16 +1052,16 @@
 would from a regular terminal (e.g.@: using the @code{telnet} or
 @code{rlogin} commands), from a Term window.
 
-A program that asks you for a password will normally suppress
-echoing of the password, so the password will not show up in the buffer.
-This will happen just as if you were using a real terminal, if
-the buffer is in char mode.  If it is in line mode, the password
-will be temporarily visible, but will be erased when you hit return.
-(This happens automatically; there is no special password processing.)
+  A program that asks you for a password will normally suppress
+echoing of the password, so the password will not show up in the
+buffer.  This will happen just as if you were using a real terminal,
+if the buffer is in char mode.  If it is in line mode, the password is
+temporarily visible, but will be erased when you hit return.  (This
+happens automatically; there is no special password processing.)
 
-When you log in to a different machine, you need to specify the
-type of terminal your using.  Terminal types @samp{ansi}
-or @samp{vt100} will work on most systems.
+  When you log in to a different machine, you need to specify the type
+of terminal your using.  Terminal types @samp{ansi} or @samp{vt100}
+will work on most systems.
 
 @c   If you are talking to a Bourne-compatible
 @c shell, and your system understands the @env{TERMCAP} variable,
@@ -1066,10 +1076,11 @@
 @c whether or not gdb is running on a different computer than Emacs,
 @c as long as Emacs can access the source files specified by gdb.
 
-You cannot log into to a remove comuter using the Shell mode.
+@ignore
+  You cannot log into to a remote computer using the Shell mode.
 @c (This will change when Shell is re-written to use Term.)
 Instead, Emacs provides two commands for logging in to another computer
-and communicating with it through an Emacs buffer.
+and communicating with it through an Emacs buffer using Comint mode:
 
 @table @kbd
 @item M-x telnet @key{RET} @var{hostname} @key{RET}
@@ -1113,6 +1124,8 @@
 argument means use local names, and a negative argument means turn
 off directory tracking.
 
+@end ignore
+
 @node Emacs Server, Hardcopy, Shell, Top
 @section Using Emacs as a Server
 @pindex emacsclient
@@ -1161,6 +1174,16 @@
 to arrive at it with @kbd{C-x #}.  But @kbd{C-x #} is the only way to
 say that you are ``finished'' with one.
 
+@vindex server-kill-new-buffers
+@vindex server-temp-file-regexp
+  Finishing with a server buffer also kills the buffer, unless it
+already existed in the Emacs session before the server asked to create
+it.  However, if you set @code{server-kill-new-buffers} to @code{nil},
+then a different criterion is used: finishing with a server buffer
+kills it if the file name matches the regular expression
+@code{server-temp-file-regexp}.  This is set up to distinguish certain
+``temporary'' files.
+
 @vindex server-window
   If you set the variable @code{server-window} to a window or a frame,
 @kbd{C-x #} displays the server buffer in that window or in that frame.
@@ -1170,7 +1193,7 @@
 input.  So the terminal that @code{mail} was using is effectively
 blocked for the duration.  In order to edit with your principal Emacs,
 you need to be able to use it without using that terminal.  There are
-two ways to do this:
+three ways to do this:
 
 @itemize @bullet
 @item
@@ -1180,55 +1203,19 @@
 switching windows.
 
 @item
-Use Shell mode in Emacs to run the other program such as @code{mail};
-then, @code{emacsclient} blocks only the subshell under Emacs, and you
-can still use Emacs to edit the file.
+Using virtual terminals, run @code{mail} in one virtual terminal
+and run Emacs in another.
+
+@item
+Use Shell mode or Term mode in Emacs to run the other program such as
+@code{mail}; then, @code{emacsclient} blocks only the subshell under
+Emacs, and you can still use Emacs to edit the file.
 @end itemize
 
-@vindex server-temp-file-regexp
-  Some programs write temporary files for you to edit.  After you edit
-the temporary file, the program reads it back and deletes it.  If the
-Emacs server is later asked to edit the same file name, it should assume
-this has nothing to do with the previous occasion for that file name.
-The server accomplishes this by killing the temporary file's buffer when
-you finish with the file.  Use the variable
-@code{server-temp-file-regexp} to specify which files are temporary in
-this sense; its value should be a regular expression that matches file
-names that are temporary.
-
-@vindex server-kill-new-buffers
-  If the variable @code{server-kill-new-buffers} is set to non-nil,
-buffers which still have a client are killed when you are done with
-them, unless they were already present before Emacs Server visited
-them.  This overrides the effect of the @code{server-temp-file-regexp}
-variable.  By default, @code{server-kill-new-buffers} has a non-nil
-value; set it to nil if you want the old behavior governed by
-@code{server-temp-file-regexp}.
-
   If you run @code{emacsclient} with the option @samp{--no-wait}, it
-returns immediately without waiting for you to ``finish'' the buffer in
-Emacs.  Note that it this case, buffers for temporary files will not be
-killed automatically with the default value of
-@code{server-kill-new-buffers}, since those buffers will not have a
-client.
-
-  If you have forgotten to start Emacs, then the option
-@samp{--alternate-editor=@var{command}} may be useful.  It specifies a
-command to run if @code{emacsclient} fails to contact Emacs.  For
-example, the following setting for the @var{EDITOR} environment variable
-will always give an editor, even if Emacs is not running.
-
-@example
-EDITOR="emacsclient --alternate-editor vi +%d %s"
-@end example
-
-The environment variable @var{ALTERNATE_EDITOR} has the same effect, but
-the value of the @samp{--alternate-editor} takes precedence.
-
-@pindex emacs.bash
-Alternatively, the file @file{etc/emacs.bash} defines a function for
-@command{bash} which will use a running Emacs server or start one if
-none exists.
+returns immediately without waiting for you to ``finish'' the buffer
+in Emacs.  Note that server buffers created in this way are not killed
+automatically when you finish with them.
 
 @menu
 * Invoking emacsclient::
@@ -1244,17 +1231,37 @@
 emacsclient @r{@{}@r{[}+@var{line}@r{]} @var{filename}@r{@}}@dots{}
 @end example
 
+@noindent
 This tells Emacs to visit each of the specified files; if you specify a
 line number for a certain file, Emacs moves to that line in the file.
 
-Ordinarily, @code{emacsclient} does not return until you use the
-@kbd{C-x #} command on each of these buffers.  When that happens, Emacs
-sends a message to the @code{emacsclient} program telling it to return.
+  Ordinarily, @code{emacsclient} does not return until you use the
+@kbd{C-x #} command on each of these buffers.  When that happens,
+Emacs sends a message to the @code{emacsclient} program telling it to
+return.
+
+  But if you use the option @samp{-n} or @samp{--no-wait} when running
+@code{emacsclient}, then it returns immediately.  (You can take as
+long as you like to edit the files in Emacs.)
 
-But if you use the option @samp{-n} or @samp{--no-wait} when running
-@code{emacsclient}, then it returns immediately.  (You can take as long
-as you like to edit the files in Emacs.)
+  The option @samp{--alternate-editor=@var{command}} is useful when
+running @code{emacsclient} in a script.  It specifies a command to run
+if @code{emacsclient} fails to contact Emacs.  For example, the
+following setting for the @var{EDITOR} environment variable will
+always give an editor, even if Emacs is not running:
 
+@example
+EDITOR="emacsclient --alternate-editor vi +%d %s"
+@end example
+
+@noindent
+The environment variable @var{ALTERNATE_EDITOR} has the same effect, but
+the value of the @samp{--alternate-editor} takes precedence.
+
+@pindex emacs.bash
+  Alternatively, the file @file{etc/emacs.bash} defines a bash
+function which will communicate with a running Emacs server, or start
+one if none exists.
 
 @node Hardcopy, PostScript, Emacs Server, Top
 @section Hardcopy Output
@@ -1403,10 +1410,10 @@
 screen colors only use shades of gray.
 
 @vindex ps-use-face-background
-  By default, PostScript printing ignored the background of the faces,
-unless the variable @code{ps-use-face-background} is set to a
-non-@code{nil} value.  This is to avoid unwanted interference with the
-zebra stripes and background image/text.
+  By default, PostScript printing ignores the background colors of the
+faces, unless the variable @code{ps-use-face-background} is
+non-@code{nil}.  This is to avoid unwanted interference with the zebra
+stripes and background image/text.
 
 @vindex ps-paper-type
 @vindex ps-page-dimensions-database
@@ -1836,12 +1843,12 @@
 @vindex save-place
 @cindex Saveplace
 @findex toggle-save-place
-There is a simpler mechanism provided by Saveplace library which records
-your position in each file when you kill its buffer (or kill Emacs), and
+  The Saveplace library provides a simpler feature that records your
+position in each file when you kill its buffer (or kill Emacs), and
 jumps to the same position when you visit the file again (even in
 another Emacs session).  Use @kbd{M-x toggle-save-place} to turn on
-place-saving in a given file.  Customize the option @code{save-place} to
-turn it on for all files in each session.
+place-saving in a given file.  Customize the option @code{save-place}
+to turn it on for all files in each session.
 
 @node Recursive Edit, Emulation, Saving Emacs Sessions, Top
 @section Recursive Editing Levels
@@ -1957,35 +1964,35 @@
 @item `PC' bindings
 @findex pc-bindings-mode
 @cindex `PC' key bindings
-The command @kbd{M-x pc-bindings-mode} sets up certain key bindings for
-`PC compatibility'---what people are often used to on PCs---as follows:
-@kbd{Delete} and its variants) delete forward instead of backward,
-@kbd{C-Backspace} kills backward a word (as @kbd{C-Delete} normally
-would), @kbd{M-Backspace} does undo, @kbd{Home} and @kbd{End} move to
-beginning and end of line, @kbd{C-Home} and @kbd{C-End} move to
-beginning and end of buffer and @kbd{C-Escape} does @code{list-buffers}.
+The command @kbd{M-x pc-bindings-mode} sets up certain key bindings
+for ``PC compatibility''---what people are often used to on PCs---as
+follows: @kbd{Delete} and its variants delete forward instead of
+backward, @kbd{C-Backspace} kills backward a word (as @kbd{C-Delete}
+normally would), @kbd{M-Backspace} does undo, @kbd{Home} and @kbd{End}
+move to beginning and end of line, @kbd{C-Home} and @kbd{C-End} move
+to beginning and end of buffer and @kbd{C-Escape} does
+@code{list-buffers}.
 
 @item PC Selection mode
 @findex pc-selection-mode
 @cindex PC Selection minor mode
 @cindex mode, PC selection
 @cindex selection, `PC'
-The command @kbd{M-x pc-selction-mode} turns on a global minor mode
-which emulates the mark, copy, cut and paste
-look-and-feel of Motif programs (which is the same as the Macintosh GUI
-and MS-Windows).  It makes the keybindings of PC mode and also modifies
-the bindings of the cursor keys and the @kbd{next}, @kbd{prior},
-@kbd{home} and @kbd{end} keys.  It does not provide the full set of CUA
-keybindings---the fundamental Emacs keys @kbd{C-c}, @kbd{C-v} and
-@kbd{C-x} are not rebound.
+The command @kbd{M-x pc-selection-mode} enables a global minor mode
+that emulates the mark, copy, cut and paste commands of various other
+systems---an interface known as CUA.  It establishes the keybindings
+of PC mode, and also modifies the bindings of the cursor keys and the
+@kbd{next}, @kbd{prior}, @kbd{home} and @kbd{end} keys.  It does not
+provide the full set of CUA keybindings---the fundamental Emacs keys
+@kbd{C-c}, @kbd{C-v} and @kbd{C-x} are not changed.
 
-The standard keys for moving around (@kbd{right}, @kbd{left}, @kbd{up},
-@kbd{down}, @kbd{home}, @kbd{end}, @kbd{prior}, @kbd{next}, called
-``move-keys'') will always de-activate the mark.  Using @kbd{Shift}
-together with the ``move keys'' activates the region over which they
-move.  The copy, cut and paste functions (as in many other programs)
-operate on the active region, bound to @kbd{C-insert}, @kbd{S-delete}
-and @kbd{S-insert} respectively.
+The standard keys for moving around (@kbd{right}, @kbd{left},
+@kbd{up}, @kbd{down}, @kbd{home}, @kbd{end}, @kbd{prior}, @kbd{next},
+called ``move-keys'') deactivate the mark in PC selection mode.
+However, using @kbd{Shift} together with the ``move keys'' activates
+the region over which they move.  The copy, cut and paste functions
+are available on @kbd{C-insert}, @kbd{S-delete} and @kbd{S-insert}
+respectively.
 
 @cindex s-region package
 The @code{s-region} package provides similar, but less complete,
@@ -2046,18 +2053,20 @@
 @cindex hyperlinking
 @cindex URLs
 @cindex navigation
-Various modes documented elsewhere have hypertext features whereby you
-can follow links, usually with @kbd{mouse-2} or @kbd{RET} on the text of
-the link.  Info mode, Help mode and the Dired-like modes are examples.
-The Tags facility links between uses and definitions in source files,
-see @ref{Tags}.  Imenu provides navigation amongst items indexed in the
-current buffer, see @ref{Imenu}.  Info-lookup provides mode-specific
-lookup of definitions in Info indexes, see @ref{Documentation}.
-Speedbar maintains a frame in which links to files, and locations in
-files are displayed, see @ref{Speedbar}.
+  Various modes documented elsewhere have hypertext features so that
+you can follow links, usually by clicking @kbd{Mouse-2} on the link or
+typing @key{RET} while point is on the link.  Info mode, Help mode and
+the Dired-like modes are examples.  The Tags facility links between
+uses and definitions in source files, see @ref{Tags}.  Imenu provides
+navigation amongst items indexed in the current buffer, see
+@ref{Imenu}.  Info-lookup provides mode-specific lookup of definitions
+in Info indexes, see @ref{Documentation}.  Speedbar maintains a frame
+in which links to files, and locations in files are displayed, see
+@ref{Speedbar}.
 
-Other non-mode-specific facilities described in this section enable
-following links from the current buffer in a context-sensitive fashion.
+  Other non-mode-specific facilities described in this section enable
+following links from the current buffer in a context-sensitive
+fashion.
 
 @menu
 * Browse-URL::                  Following URLs.
@@ -2083,23 +2092,24 @@
 
 The Browse-URL package provides facilities for following URLs specifying
 links on the World Wide Web.  Usually this works by invoking a web
-browser but you can, for instance, arrange to invoke @code{compose-mail}
-from @samp{mailto:} URLs.  Packages such as Gnus may make active links
-from URLs themselves.  Otherwise you can use @kbd{M-x browse-url} to
-follow a link, defaulting to the URL at point.  Other commands are
-available which you might like to bind to keys, such as
+browser, but you can, for instance, arrange to invoke @code{compose-mail}
+from @samp{mailto:} URLs.
+
+  The general way to use this feature is to type @kbd{M-x browse-url},
+which displays a specified URL.  If point is located near a plausible
+URL, that URL is used as the default.  Other commands are available
+which you might like to bind to keys, such as
 @code{browse-url-at-point} and @code{browse-url-at-mouse}.
 
 @vindex browse-url-browser-function
-You can customize Browse-URL's behaviour via various options in the
+  You can customize Browse-URL's behaviour via various options in the
 @code{browse-url} Customize group, particularly
-@code{browse-url-browser-function}.  You can invoke actions dependent on
-the type of URL by defining @code{browse-url-browser-function} as an
-association list.  The package's commentary available via @kbd{C-h p}
-provides more information.  Packages with facilities for following URLs
-should use Browse-URL, so customizing options in the @code{browse-url}
-group should be sufficient to determine how they all work in that
-respect.
+@code{browse-url-browser-function}.  You can invoke actions dependent
+on the type of URL by defining @code{browse-url-browser-function} as
+an association list.  The package's commentary available via @kbd{C-h
+p} provides more information.  Packages with facilities for following
+URLs should always go through Browse-URL, so that the customization
+options for Browse-URL will affect all browsing in Emacs.
 
 @node Goto-address
 @subsection Activating URLs
@@ -2112,11 +2122,20 @@
 Activate URLs and e-mail addresses in the current buffer.
 @end table
 
-You can arrange to activate URLs in any buffer with @kbd{M-x
-goto-address}.  It may be useful to add @code{goto-address} to hooks
-invoked when buffers are displayed in particular modes.
-@code{rmail-show-message-hook} is the appropriate hook if you use Rmail,
-or @code{mh-show-mode-hook} if you use MH.
+  You can make URLs in the current buffer active with @kbd{M-x
+goto-address}.  This finds all the URLs in the buffer, and establishes
+bindings for @kbd{Mouse-2} and @kbd{C-c @key{RET}} on them.  After
+activation, if you click on a URL with @kbd{Mouse-2}, or move to a URL
+and type @kbd{C-c @key{RET}}, that will display the web page that the URL
+specifies.  For a @samp{mailto} URL, it sends mail instead, using your
+selected mail-composition method (@pxref{Mail Methods}).
+
+  It can be useful to add @code{goto-address} to mode hooks and the
+hooks used to display an incoming message.
+@code{rmail-show-message-hook} is the appropriate hook for Rmail, and
+@code{mh-show-mode-hook} for MH-E.  This is not needed for Gnus,
+which has a similar feature of its own.
+
 
 @node FFAP
 @subsection Finding Files and URLs at Point
@@ -2127,105 +2146,88 @@
 @findex ffap-next
 @findex ffap-menu
 @cindex FFAP
-@cindex URLs
 @cindex finding file at point
 
-@table @kbd
-@item M-x ffap @key{RET} @var{filename} @key{RET}
-Find @var{filename}, guessing a default from text around point.
-@item M-x ffap-next
-Search buffer for next file or URL, and run `ffap'.  With single prefix
-arg, search backwards, with double arg wrap search forwards, with triple
-arg wrap search backwards.
-@item M-x ffap-menu
-Put up a menu of files and URLs mentioned in current buffer and try to
-fetch the selected one.
-@item M-x ffap-dired-at-point
-Start Dired, defaulting to file at point.
-@end table
+  FFAP mode replaces certain key bindings for finding files, including
+@kbd{C-x C-f}, with commands that provide more sensitive defaults.
+These commands behave like the ordinary ones when given a prefix
+argument.  Otherwise, they get the default file name or URL from the
+text around point.  If what is found in the buffer has the form of a
+URL rather than a file name, the commands use @code{browse-url} to
+view it.
 
-The command @kbd{M-x find-file-at-point} (or @kbd{M-x ffap}) can be used
-as a replacement for @kbd{M-x find-file}.  With a prefix argument it
-behaves as @kbd{M-x find-file}.  Otherwise it tries to guess a default
-file or URL from the text around point.  In the case of a URL, it will
-invoke @code{browse-url} rather than finding a file.  This is useful for
-following references in mail or news buffers, @file{README}s,
-@file{MANIFEST}s, and so on.  The @samp{ffap} package's
-commentary available via @kbd{C-h p} and the @code{ffap} Custom group
-provide details.
+  This feature is useful for following references in mail or news
+buffers, @file{README} files, @file{MANIFEST} files, and so on.  The
+@samp{ffap} package's commentary available via @kbd{C-h p} and the
+@code{ffap} Custom group provide details.
 
 @cindex FFAP minor mode
 @findex ffap-mode
-You can turn on FFAP minor mode to make the following key bindings and
-to install hooks for using @code{ffap} in Rmail, Gnus and VM article
-buffers.
+  You can turn on FFAP minor mode to make the following key bindings
+and to install hooks for using @code{ffap} in Rmail, Gnus and VM
+article buffers.
 
 @table @kbd
-@item C-x C-f
+@item C-x C-f @var{filename} @key{RET}
 @kindex C-x C-f @r{(FFAP)}
-@kbd{find-file-at-point};
+Find @var{filename}, guessing a default from text around point
+(@code{find-file-at-point}).
 @item C-x 4 f
 @kindex C-x 4 f @r{(FFAP)}
-@code{ffap-other-window}, analagous to @kbd{M-x find-file-other-window};
+@code{ffap-other-window}, analogous to @code{find-file-other-window}.
 @item C-x 5 f
 @kindex C-x 5 f @r{(FFAP)}
-@code{ffap-other-frame}, analagous to @kbd{M-x find-file-other-frame};
-@item C-x d
+@code{ffap-other-frame}, analogous to @code{find-file-other-frame}.
+@item M-x ffap-next
+Search buffer for next file name or URL, then find that file or URL.
+@item C-x d @var{directory} @key{RET}
 @kindex C-x d @r{(FFAP)}
-@code{ffap-dired-at-point}, analogous to @kbd{M-x dired};
-@item S-mouse-3
-@kindex S-mouse-3 @r{(FFAP)}
+Start Dired on @var{directory}, defaulting to the directory name at
+point (@code{ffap-dired-at-point}).
+@item S-Mouse-3
+@kindex S-Mouse-3 @r{(FFAP)}
 @code{ffap-at-mouse} finds the file guessed from text around the position
-of a mouse click;
-@item C-S-mouse-3
-@kindex C-S-mouse-3 @r{(FFAP)}
-@code{ffap-menu} puts up a selectable menu of files and URLs mentioned in
-the current buffer.
+of a mouse click.
+@item C-S-Mouse-3
+@kindex C-S-Mouse-3 @r{(FFAP)}
+Display a menu of files and URLs mentioned in current buffer, then
+find the one you select (@code{ffap-menu}).
 @end table
 
 @node Find-func
 @subsection Finding Function and Variable Definitions
-@findex find-function
-@findex find-function-on-key
-@findex find-variable
-@cindex examples of Lisp functions
-@cindex Lisp examples
-@cindex Find-func
-@cindex Lisp definitions
-@cindex definitions, locating in sources
-@cindex tags
+@cindex definitions, finding in Lisp sources
+@cindex Lisp definitions, finding in sources
 
 @table @kbd
 @item M-x find-function @key{RET} @var{function} @key{RET}
-Find the definition of the @var{function} at point.
+Find the definition @var{function} in its source file.
 @item M-x find-variable @key{RET} @var{variable} @key{RET}
-Find the definition of the @var{variable} at point.
-@item M-x find-function-on-key @var{key}
+Find the definition of @var{variable} in its source file.
+@item M-x find-function-on-key @key{RET} @var{key}
 Find the definition of the function that @var{key} invokes.
 @end table
 
-The Find-func package provides convenient facilities for finding the
-definitions of Emacs Lisp functions and variables.  It has a somewhat
-similar function to the Tags facility (@pxref{Tags}) but uses Emacs's
-introspective facilities which maintain information about loaded
-libraries.  In contrast to Tags, it only works for functions and
-variables with definitions which are already loaded but it relates to
-the code actually running and doesn't require maintaining tags files.
+  These commands provide an easy way to find the definitions of Emacs
+Lisp functions and variables.  They are similar in purpose to the Tags
+facility (@pxref{Tags}), but don't require a tags table; on the other
+hand, they only works for function and variable definitions that are
+already loaded in the Emacs session.
 
-You need to have the Lisp source (@samp{.el}) files available on your
-load path along with the compiled (@samp{.elc}) versions for this to
-work.  You can use compressed source files if you turn on
-@code{auto-compression-mode}.
+@findex find-function
+@findex find-function-on-key
+@findex find-variable
+  To find the definition of a function, use @kbd{M-x find-function}.
+@kbd{M-x find-variable} finds the definition of a specified variable.
+@kbd{M-x find-function-on-key} finds the definition of the function
+bound to a specified key.
 
-The commands available include @kbd{M-x find-function} to find the
-definition of a named function, @kbd{find-function-on-key} to find the
-definition of the function bound to a key and @kbd{find-variable} to
-find a variable's definition.  These only work for things defined in
-Lisp source files, not primitive functions or variables defined
-primitively in the Emacs layer implemented in C.
-
-Find-func is useful for finding examples of how to do things if you want
-to write an Emacs Lisp extension similar to some existing function.
+  To use these commands, you must have the Lisp source (@samp{.el})
+files available along with the compiled (@samp{.elc}) files, in
+directories in @code{load-path}.  You can use compressed source files
+if you enable Auto Compression mode.  These commands only handle
+definitions written in Lisp, not primitive functions or variables
+defined in the C code of Emacs.
 
 @node Dissociated Press, Amusements, Hyperlinking, Top
 @section Dissociated Press
@@ -2341,8 +2343,8 @@
 
 @findex pong
 @cindex Pong game
-@kbd{M-x pong} plays an implementation of the game Pong, bouncing the
-ball off opposing bats.
+@kbd{M-x pong} plays a Pong-like game, bouncing the ball off opposing
+bats.
 
 @findex solitaire
 @cindex solitaire
@@ -2351,7 +2353,8 @@
 
 @findex studlify-region
 @cindex StudlyCaps
-@kbd{M-x studlify-region} studlify-cases the region, that is
+@kbd{M-x studlify-region} studlify-cases the region, producing
+text like this:
 
 @example
 M-x stUdlIfY-RegioN stUdlIfY-CaSeS thE region.
@@ -2359,9 +2362,9 @@
 
 @findex tetris
 @cindex Tetris
-@kbd{M-x tetris} runs an implementation of the well-known Tetris game.
 @findex snake
 @cindex Snake
+@kbd{M-x tetris} runs an implementation of the well-known Tetris game.
 Likewise, @kbd{M-x snake} provides an implementation of Snake.
 
   When you are frustrated, try the famous Eliza program.  Just do