From 1abade00b8ebf52f51353da7297537b3f4b34996 Mon Sep 17 00:00:00 2001
From: "Richard M. Stallman" <rms@gnu.org>
Date: Mon, 3 Jul 2006 15:50:37 +0000
Subject: [PATCH] Lots of cleanups.

---
 man/help.texi | 528 +++++++++++++++++++++++++-------------------------
 man/m-x.texi  |  66 +++----
 2 files changed, 289 insertions(+), 305 deletions(-)

diff --git a/man/help.texi b/man/help.texi
index 4d69e18cc39..47600b711fa 100644
--- a/man/help.texi
+++ b/man/help.texi
@@ -11,65 +11,62 @@
 @kindex C-h
 @kindex F1
 
-  Emacs provides extensive help features accessible through a single
-character, @kbd{C-h} (or @key{F1}).  @kbd{C-h} is a prefix key that is
-used for commands that display documentation.  The characters that you
-can type after @kbd{C-h} are called @dfn{help options}.  One help
-option is @kbd{C-h}; that is how you ask for help about using
-@kbd{C-h}.  To cancel, type @kbd{C-g}.  The function key @key{F1} is
-equivalent to @kbd{C-h}.
+  Emacs provides extensive help features, all accessible through the
+@dfn{help character}, @kbd{C-h}.  This is a prefix key that is used
+for commands that display documentation; the next character you type
+should be a @dfn{help options}, to ask for a particular kind of help.
+You can cancel the @kbd{C-h} command with @kbd{C-g}.  The function key
+@key{F1} is equivalent to @kbd{C-h}.
 
 @kindex C-h C-h
 @findex help-for-help
-  @kbd{C-h C-h} (@code{help-for-help}) displays a list of the possible
-help options, each with a brief description.  You can look at the
-list, using @key{SPC} and @key{DEL} to scroll through it, then type
-the help option you want.  To cancel, type @kbd{C-g}.
+  @kbd{C-h} itself is one of the help options; @kbd{C-h C-h} displays
+a list of help options, with a brief description of each one
+(@code{help-for-help}).  You can scroll the list with @key{SPC} and
+@key{DEL}, then type the help option you want.  To cancel, type
+@kbd{C-g}.
 
   @kbd{C-h} or @key{F1} means ``help'' in various other contexts as
-well.  After a prefix key, it displays a list of the alternatives that
-can follow the prefix key.  (A few prefix keys don't support
-@kbd{C-h}, because they define other meanings for it, but they all
-support @key{F1}.)
+well.  For instance, you can type them after a prefix key to display
+list of the keys that can follow the prefix key.  (A few prefix keys
+don't support @kbd{C-h} in this way, because they define other
+meanings for it, but they all support @key{F1} for help.)
 
-  Most help buffers use a special major mode, Help mode, which lets you
-scroll conveniently with @key{SPC} and @key{DEL}.  It also offers
-hyperlinks to URLs and further help regarding cross-referenced names, Info
-nodes, customization buffers and the like.  @xref{Help Mode}.
+  Most help buffers use a special major mode, Help mode, which lets
+you scroll conveniently with @key{SPC} and @key{DEL}.  You can also
+follow hyperlinks to URLs, and to other facilities including Info
+nodes and customization buffers.  @xref{Help Mode}.
 
 @cindex searching documentation efficiently
 @cindex looking for a subject in documentation
-  If you are looking for a certain feature, but don't know where
-exactly it is documented, and aren't sure of the name of a
-related command or variable, we recommend trying these methods.  Usually
-it is best to start with an apropos command, then try searching the
-manual index, then finally look in the FAQ and the package keywords.
+  If you are looking for a certain feature, but don't know what it is
+called or where to look, we recommend three methods.  First, try an
+apropos command, then try searching the manual index, then look in the
+FAQ and the package keywords.
 
 @table @kbd
 @item C-h a @var{topics} @key{RET}
-This searches for commands whose names match @var{topics}, which
-should be a keyword, a list of keywords, or a regular expression
-(@pxref{Regexps}).  This command displays all the matches in a new
-buffer.  @xref{Apropos}.
+This searches for commands whose names match the argument
+@var{topics}.  The argument can be a keyword, a list of keywords, or a
+regular expression (@pxref{Regexps}).  This command displays all the
+matches in a new buffer.  @xref{Apropos}.
 
 @item C-h i d m emacs @key{RET} i @var{topic} @key{RET}
-This looks up @var{topic} in the indices of the Emacs on-line manual.
-If there are several matches, Emacs displays the first one.  You can then
-press @kbd{,} to move to other matches, until you find what you are
-looking for.
+This searches for @var{topic} in the indices of the on-line Emacs
+manual, and displays the first match found.  Press @kbd{,} to see
+subsequent matches.  You can use a regular expression as @var{topic}.
 
 @item C-h i d m emacs @key{RET} s @var{topic} @key{RET}
-Similar, but searches for @var{topic} (which can be a regular
-expression) in the @emph{text} of the manual rather than in its
+Similar, but searches the @emph{text} of the manual rather than the
 indices.
 
 @item C-h C-f
-This brings up the Emacs FAQ.  You can use the Info commands
+This displays the Emacs FAQ.  You can use the Info commands
 to browse it.
 
 @item C-h p
-Finally, you can try looking up a suitable package using keywords
-pertinent to the feature you need.  @xref{Library Keywords}.
+This displays the available Emacs packages based on keywords.
+@xref{Library Keywords}.
 @end table
 
 @menu
@@ -93,25 +90,25 @@ pertinent to the feature you need.  @xref{Library Keywords}.
 @section Help Summary
 @end ifnottex
 
-  Here is a summary of the Emacs interactive help commands.
-@xref{Help Files}, for other help commands that just display a
-pre-written file of information.  The character that follows
-@kbd{C-h} is a ``help option.''
+  Here is a summary of the Emacs interactive help commands.  (The
+character that follows @kbd{C-h} is the ``help option.'')  @xref{Help
+Files}, for other help commands that display fixed files of
+information.
 
 @table @kbd
 @item C-h a @var{topics} @key{RET}
 Display a list of commands whose names match @var{topics}
 (@code{apropos-command}; @pxref{Apropos}).
 @item C-h b
-Display a table of all key bindings in effect now, in this order: minor
-mode bindings, major mode bindings, and global bindings
-(@code{describe-bindings}).
+Display all active key bindings; minor mode bindings first, then those
+of the major mode, then global bindings (@code{describe-bindings}).
 @item C-h c @var{key}
-Show the name of the command that @var{key} runs
-(@code{describe-key-briefly}).  Here @kbd{c} stands for ``character.''
-For more extensive information on @var{key}, use @kbd{C-h k}.
+Given a key sequence @var{key}, show the name of the command that it
+runs (@code{describe-key-briefly}).  Here @kbd{c} stands for
+``character.''  For more extensive information on @var{key}, use
+@kbd{C-h k}.
 @item C-h d @var{topics} @key{RET}
-Display a list of commands and variables whose documentation matches
+Display the commands and variables whose documentation matches
 @var{topics} (@code{apropos-documentation}).
 @item C-h e
 Display the @code{*Messages*} buffer
@@ -119,12 +116,12 @@ Display the @code{*Messages*} buffer
 @item C-h f @var{function} @key{RET}
 Display documentation on the Lisp function named @var{function}
 (@code{describe-function}).  Since commands are Lisp functions,
-a command name may be used.
+this works for commands too.
 @item C-h h
 Display the @file{HELLO} file, which shows examples of various character
 sets.
 @item C-h i
-Run Info, the program for browsing documentation files (@code{info}).
+Run Info, the GNU documentation browser (@code{info}).
 The complete Emacs manual is available on-line in Info.
 @item C-h k @var{key}
 Display the name and documentation of the command that @var{key} runs
@@ -137,7 +134,7 @@ Display documentation of the current major mode (@code{describe-mode}).
 @item C-h p
 Find packages by topic keyword (@code{finder-by-keyword}).
 @item C-h s
-Display the current contents of the syntax table, plus an explanation of
+Display the current contents of the syntax table, with an explanation of
 what they mean (@code{describe-syntax}).  @xref{Syntax}.
 @item C-h t
 Enter the Emacs interactive tutorial (@code{help-with-tutorial}).
@@ -147,28 +144,29 @@ Display the documentation of the Lisp variable @var{var}
 @item C-h w @var{command} @key{RET}
 Show which keys run the command named @var{command} (@code{where-is}).
 @item C-h C @var{coding} @key{RET}
-Describe coding system @var{coding}
+Describe the coding system @var{coding}
 (@code{describe-coding-system}).
 @item C-h C @key{RET}
 Describe the coding systems currently in use.
 @item C-h I @var{method} @key{RET}
-Describe an input method (@code{describe-input-method}).
+Describe the input method @var{method} (@code{describe-input-method}).
 @item C-h L @var{language-env} @key{RET}
 Display information on the character sets, coding systems, and input
-methods used for language environment @var{language-env}
+methods used in language environment @var{language-env}
 (@code{describe-language-environment}).
 @item C-h F @var{function} @key{RET}
-Enter Info and go to the node documenting the Emacs function @var{function}
-(@code{Info-goto-emacs-command-node}).
+Enter Info and goes to the node that documents the Emacs function
+@var{function} (@code{Info-goto-emacs-command-node}).
 @item C-h K @var{key}
-Enter Info and go to the node where the key sequence @var{key} is
-documented (@code{Info-goto-emacs-key-command-node}).
+Enter Info and goes to the node that documents the key sequence
+@var{key} (@code{Info-goto-emacs-key-command-node}).
 @item C-h S @var{symbol} @key{RET}
 Display the Info documentation on symbol @var{symbol} according to the
 programming language you are editing (@code{info-lookup-symbol}).
 @item C-h .
-Display a help message associated with special text areas, such as
-links in @samp{*Help*} buffers (@code{display-local-help}).
+Display the help message for a special text area, if point is in one
+(@code{display-local-help}).  (These include, for example, links in
+@samp{*Help*} buffers.)
 @end table
 
 @node Key Help
@@ -176,50 +174,48 @@ links in @samp{*Help*} buffers (@code{display-local-help}).
 
 @kindex C-h c
 @findex describe-key-briefly
-  The most basic @kbd{C-h} commands are @kbd{C-h c}
-(@code{describe-key-briefly}) and @w{@kbd{C-h k}} (@code{describe-key}).
-@kbd{C-h c @var{key}} displays in the echo area the name of the command
-that @var{key} is bound to.  For example, @kbd{C-h c C-f} displays
-@samp{forward-char}.  Since command names are chosen to describe what
-the commands do, this is a good way to get a very brief description of
-what @var{key} does.
+  The help commands to get information about a key sequence are
+@kbd{C-h c} and @w{@kbd{C-h k}}.  @kbd{C-h c @var{key}} displays in
+the echo area the name of the command that @var{key} is bound to.  For
+example, @kbd{C-h c C-f} displays @samp{forward-char}.  Since command
+names are chosen to describe what the commands do, this gives you a
+very brief description of what @var{key} does.
 
 @kindex C-h k
 @findex describe-key
   @kbd{C-h k @var{key}} is similar but gives more information: it
 displays the documentation string of the command as well as its name.
-This is too big for the echo area, so a window is used for the display.
+It displays this information in a window, since it may not fit in the
+echo area.
 
 @kindex C-h K
 @findex Info-goto-emacs-key-command-node
-  To find the documentation of a key sequence, type @kbd{C-h K} and
-then enter that key sequence.  This looks up the description of the
-command invoked by the key in whichever manual describes it (this need
-not be the Emacs manual).  @kbd{C-h K} runs the command
-@code{Info-goto-emacs-key-command-node}.
+  To find the documentation of a key sequence @var{key}, type @kbd{C-h
+K @var{key}}.  This displays the appropriate manual section which
+contains the documentation of @var{key}.
 
   @kbd{C-h c}, @kbd{C-h k} and @kbd{C-h K} work for any sort of key
 sequences, including function keys, menus, and mouse events.  For
-instance, you can type @kbd{C-h k} and then select a menu item from
-the menu bar, to show the documentation string of the command that
-menu item runs.
+instance, after @kbd{C-h k} you can select a menu item from the menu
+bar, to view the documentation string of the command it runs.
 
 @kindex C-h w
 @findex where-is
-  @kbd{C-h w @var{command} @key{RET}} tells you what keys are bound to
-@var{command}.  It displays a list of the keys in the echo area.  If it
-says the command is not on any key, you must use @kbd{M-x} to run it.
-@kbd{C-h w} runs the command @code{where-is}.
+  @kbd{C-h w @var{command} @key{RET}} lists the keys that are bound to
+@var{command}.  It displays the list in the echo area.  If it says the
+command is not on any key, that means you must use @kbd{M-x} to run
+it.  @kbd{C-h w} runs the command @code{where-is}.
 
 @node Name Help
 @section Help by Command or Variable Name
 
 @kindex C-h f
 @findex describe-function
-  @kbd{C-h f} (@code{describe-function}) reads the name of a Lisp function
-using the minibuffer, then displays that function's documentation string
-in a window.  Since commands are Lisp functions, you can use this to get
-the documentation of a command that you know by name.  For example,
+  @kbd{C-h f @var{function} @key{RET}} (@code{describe-function})
+displays the documentation of Lisp function @var{function}, in a
+window.  Since commands are Lisp functions, you can use this method to
+view the documentation of any command whose name you know.  For
+example,
 
 @example
 C-h f auto-fill-mode @key{RET}
@@ -230,118 +226,119 @@ displays the documentation of @code{auto-fill-mode}.  This is the only
 way to get the documentation of a command that is not bound to any key
 (one which you would normally run using @kbd{M-x}).
 
-  @kbd{C-h f} is also useful for Lisp functions that you are planning
-to use in a Lisp program.  For example, if you have just written the
-expression @code{(make-vector len)} and want to check that you are
-using @code{make-vector} properly, type @kbd{C-h f make-vector
-@key{RET}}.  Because @kbd{C-h f} allows all function names, not just
-command names, you may find that some of your favorite completion
-abbreviations that work in @kbd{M-x} don't work in @kbd{C-h f}.  An
-abbreviation may be unique among command names, yet fail to be unique
-when other function names are allowed.
-
-  The default function name for @kbd{C-h f} to describe, if you type
-just @key{RET}, is the name of the function called by the innermost Lisp
-expression in the buffer around point, @emph{provided} that is a valid,
-defined Lisp function name.  For example, if point is located following
-the text @samp{(make-vector (car x)}, the innermost list containing
-point is the one that starts with @samp{(make-vector}, so the default is
-to describe the function @code{make-vector}.
-
-  @kbd{C-h f} is often useful just to verify that you have the right
-spelling for the function name.  If @kbd{C-h f} mentions a name from the
-buffer as the default, that name must be defined as a Lisp function.  If
-that is all you want to know, just type @kbd{C-g} to cancel the @kbd{C-h
-f} command, then go on editing.
-
-  @kbd{C-h v} (@code{describe-variable}) is like @kbd{C-h f} but describes
-Lisp variables instead of Lisp functions.  Its default is the Lisp symbol
-around or before point, but only if that is the name of a known Lisp
-variable.  @xref{Variables}.
-
-  Help buffers describing Emacs variables and functions normally have
-hyperlinks to the definition, if you have the source files installed.
-(@xref{Hyperlinking}.)  If you know Lisp (or C), this provides the
-ultimate documentation.  If you don't know Lisp, you should learn it.
-(The Introduction to Emacs Lisp Programming, available from the FSF
-through fsf.org, is a good way to get started.)  Emacs won't be happy
-if it feels you are just @emph{using} Emacs, treating it as an object
-program.  If you really love Emacs, show that you care by reading the
-source code.
+  @kbd{C-h f} is also useful for Lisp functions that you use in a Lisp
+program.  For example, if you have just written the expression
+@code{(make-vector len)} and want to check that you are using
+@code{make-vector} properly, type @kbd{C-h f make-vector @key{RET}}.
+Because @kbd{C-h f} allows all function names, not just command names,
+you may find that some of your favorite completion abbreviations that
+work in @kbd{M-x} don't work in @kbd{C-h f}.  An abbreviation that is
+unique among command names may not be unique among all function names.
+
+  If you type @kbd{C-h f @key{RET}}, it describes the function called
+by the innermost Lisp expression in the buffer around point,
+@emph{provided} that function name is a valid, defined Lisp function.
+(That name appears as the default while you enter the argument.)  For
+example, if point is located following the text @samp{(make-vector
+(car x)}, the innermost list containing point is the one that starts
+with @samp{(make-vector}, so @kbd{C-h f @key{RET}} will describe the
+function @code{make-vector}.
+
+  @kbd{C-h f} is also useful just to verify that you spelled a
+function name correctly.  If the minibuffer prompt for @kbd{C-h f}
+shows the function name from the buffer as the default, it means that
+name is defined as a Lisp function.  Type @kbd{C-g} to cancel the
+@kbd{C-h f} command if you don't really want to view the
+documentation.
+
+  @kbd{C-h v} (@code{describe-variable}) is like @kbd{C-h f} but
+describes Lisp variables instead of Lisp functions.  Its default is
+the Lisp symbol around or before point, if that is the name of a
+defined Lisp variable.  @xref{Variables}.
+
+  Help buffers that describe Emacs variables and functions normally
+have hyperlinks to the corresponding source definition, if you have
+the source files installed.  (@xref{Hyperlinking}.)  If you know Lisp
+(or C), this provides the ultimate documentation.  If you don't know
+Lisp, you should learn it.  (The Introduction to Emacs Lisp
+Programming, available from the FSF through fsf.org, is a good way to
+get started.)  If Emacs feels you are just @emph{using} it, treating
+it as an object program, its feelings may be hurt.  For real intimacy,
+read the Emacs source code.
 
 @kindex C-h F
 @findex Info-goto-emacs-command-node
-  To find a specific function's documentation in a manual, use
-@kbd{C-h F} (@code{Info-goto-emacs-command-node}).  This knows
-about various manuals, not just the Emacs manual, and finds the
-right one.
+  To find a function's documentation in a manual, use @kbd{C-h F}
+(@code{Info-goto-emacs-command-node}).  This knows about various
+manuals, not just the Emacs manual, and finds the right one.
 
 @node Apropos
 @section Apropos
 
-  A more sophisticated sort of question to ask is, ``What are the
-commands for working with files?''  The @dfn{apropos} commands ask
-such questions---they look for things whose names match an
+  The @dfn{apropos} commands answer questions like, ``What are the
+commands for working with files?''  More precisely, you specify an
 @dfn{apropos pattern}, which means either a word, a list of words, or
-a regular expression.  Each apropos command displays a list of
-matching items in a special buffer.
+a regular expression.  Each apropos command displays a list of items
+that match the pattern, in a separate buffer.
 
 @table @kbd
 @item C-h a @var{pattern} @key{RET}
 Search for commands whose names match @var{pattern}.
 
 @item M-x apropos @key{RET} @var{pattern} @key{RET}
-Similar, but it searches for noninteractive functions and for
-variables, as well as commands.
+Search for functions and variables whose names match @var{pattern}.
+Both interactive functions (commands) and noninteractive functions can
+be found by this command.
 
 @item M-x apropos-variable @key{RET} @var{pattern} @key{RET}
-Similar, but it searches for variables only.
+Search for user-option variables whose names match @var{pattern}.
 
 @item M-x apropos-value @key{RET} @var{pattern} @key{RET}
-Similar, but it searches for variables based on their values, or
-functions based on their definitions.
+Search for functions whose definitions @var{pattern}, and variables
+whose values match @var{pattern}.
 
 @item C-h d @var{pattern} @key{RET}
-Search the @emph{documentation strings} (the built-in short
-descriptions) of all variables and functions (not their names) for a
-match for @var{pattern}.
+Search for functions and variables whose @strong{documentation
+strings} match @var{pattern}.
 @end table
 
 @kindex C-h a
 @findex apropos-command
 @cindex apropos
-  To find the commands that work on files, type @kbd{C-h a file
-@key{RET}}.  This displays a list of all command names that contain
-@samp{file}, including @code{copy-file}, @code{find-file}, and so on.
-With each command name appears a brief description of how to use the
-command, and what keys you can currently invoke it with.  For example,
-it would say that you can invoke @code{find-file} by typing @kbd{C-x
-C-f}.  The @kbd{a} in @kbd{C-h a} stands for ``Apropos''; @kbd{C-h a}
+  The simplest kind of apropos pattern is one word.  Anything which
+contains that word matches the pattern.  Thus, to find the commands
+that work on files, type @kbd{C-h a file @key{RET}}.  This displays a
+list of all command names that contain @samp{file}, including
+@code{copy-file}, @code{find-file}, and so on.  Each command name
+comes with a brief description and a list of keys you can currently
+invoke it with.  In our example, it would say that you can invoke
+@code{find-file} by typing @kbd{C-x C-f}.
+
+  The @kbd{a} in @kbd{C-h a} stands for ``Apropos''; @kbd{C-h a}
 runs the command @code{apropos-command}.  This command normally checks
 only commands (interactive functions); if you specify a prefix
 argument, it checks noninteractive functions as well.
 
-  If you want more information about a function definition, variable or
-symbol property listed in the Apropos buffer, you can click on it with
+  For more information about a function definition, variable or symbol
+property listed in the apropos buffer, you can click on it with
 @kbd{Mouse-1} or @kbd{Mouse-2}, or move there and type @key{RET}.
 
-  @kbd{C-h a} with a single word can find too many matches.  Don't
-just give up; you can give Apropos a list of words to search for.
-When you specify more than one word in the apropos pattern, a name
+  When you specify more than one word in the apropos pattern, a name
 must contain at least two of the words in order to match.  Thus, if
 you are looking for commands to kill a chunk of text before point, you
-could try @kbd{C-h a kill back backward behind before @key{RET}}.
+could try @kbd{C-h a kill back backward behind before @key{RET}}.  The
+real command name @code{kill-backward} will match that; if there were
+a command @code{kill-text-before}, it would also match, since it
+contains two of the specified words.
 
   For even greater flexibility, you can specify a regular expression
 (@pxref{Regexps}).  An apropos pattern is interpreted as a regular
 expression if it contains any of the regular expression special
 characters, @samp{^$*+?.\[}.
 
-  Here is a set of arguments to give to @kbd{C-h a} that covers many
-classes of Emacs commands, since there are strong conventions for
-naming the standard Emacs commands.  By giving you a feel for the
-naming conventions, this set should also serve to aid you in
-developing a technique for picking Apropos keywords.
+  Following the conventions for naming Emacs commands, here are some
+words that you'll find useful in apropos patterns.  By using them in
+@kbd{C-h a}, you will also get a feel for the naming conventions.
 
 @quotation
 char, line, word, sentence, paragraph, region, page, sexp, list, defun,
@@ -352,45 +349,44 @@ view, describe, default.
 @end quotation
 
 @findex apropos
-  To list all Lisp symbols that contain a match for an Apropos pattern,
-not just the ones that are defined as commands, use the command
-@kbd{M-x apropos} instead of @kbd{C-h a}.  This command does not check
-key bindings by default; specify a numeric argument if you want it to
-check them.
+  Use @kbd{M-x apropos} instead of @kbd{C-h a} to list all the Lisp
+symbols that match an apropos pattern, not just the symbols that are
+commands.  This command does not list key bindings by default; specify
+a numeric argument if you want it to list them.
 
 @findex apropos-variable
-  To list user-customizable variables that match an apropos pattern,
-use the command @kbd{M-x apropos-variable}.  If you specify a prefix
-argument, it checks all variables.
+  Use @kbd{M-x apropos-variable} to list user-customizable variables
+that match an apropos pattern.  If you specify a prefix argument, it
+lists all matching variables.
 
 @kindex C-h d
 @findex apropos-documentation
   The @code{apropos-documentation} command is like @code{apropos}
 except that it searches documentation strings instead of symbol names
-for matches for the specified Apropos pattern.
+for matches.
 
 @findex apropos-value
   The @code{apropos-value} command is like @code{apropos} except that
-it searches variables' values for matches for the pattern.  With a
-prefix argument, it also checks symbols' function definitions and
-property lists.
+it searches variables' values for matches for the apropos pattern.
+With a prefix argument, it also checks symbols' function definitions
+and property lists.
 
 @vindex apropos-do-all
-  If the variable @code{apropos-do-all} is non-@code{nil}, the commands
-above all behave as if they had been given a prefix argument.
+  If the variable @code{apropos-do-all} is non-@code{nil}, the apropos
+commands always behave as if they had been given a prefix argument.
 
 @vindex apropos-sort-by-scores
 @cindex apropos search results, order by score
-  By default, Apropos lists the search results in alphabetical order.
-If the variable @code{apropos-sort-by-scores} is non-@code{nil},
-Apropos tries to guess the relevance of each result, and displays the
-most relevant ones first.
+  By default, apropos lists the search results in alphabetical order.
+If the variable @code{apropos-sort-by-scores} is non-@code{nil}, the
+apropos commands try to guess the relevance of each result, and
+display the most relevant ones first.
 
 @vindex apropos-documentation-sort-by-scores
-  By default, Apropos lists the search results for
+  By default, apropos lists the search results for
 @code{apropos-documentation} in order of relevance of the match.  If
 the variable @code{apropos-documentation-sort-by-scores} is
-@code{nil}, Apropos lists the symbols found in alphabetical order.
+@code{nil}, apropos lists the symbols found in alphabetical order.
 
 @node Library Keywords
 @section Keyword Search for Lisp Libraries
@@ -444,23 +440,23 @@ use:
 @section Help for International Language Support
 
   You can use the command @kbd{C-h L}
-(@code{describe-language-environment}) to find out information about
-the support for a specific language environment.  @xref{Language
-Environments}.  This tells you which languages this language
-environment is useful for, and lists the character sets, coding
-systems, and input methods that it operates on.  It also shows some
-sample text to illustrate scripts.
+(@code{describe-language-environment}) to get information about a
+specific language environment.  @xref{Language Environments}.  This
+tells you which languages this language environment supports.  It also
+lists the character sets, coding systems, and input methods that work
+with this language environment, and finally shows some sample text to
+illustrate scripts.
 
   The command @kbd{C-h h} (@code{view-hello-file}) displays the file
 @file{etc/HELLO}, which shows how to say ``hello'' in many languages.
 
-  The command @kbd{C-h I} (@code{describe-input-method}) describes
-information about input methods---either a specified input method, or by
-default the input method in use.  @xref{Input Methods}.
+  The command @kbd{C-h I} (@code{describe-input-method}) describes an
+input method---either a specified input method, or by default the
+input method currently in use.  @xref{Input Methods}.
 
   The command @kbd{C-h C} (@code{describe-coding-system}) describes
-information about coding systems---either a specified coding system, or
-the ones currently in use.  @xref{Coding Systems}.
+coding systems---either a specified coding system, or the ones
+currently in use.  @xref{Coding Systems}.
 
 @node Help Mode
 @section Help Mode Commands
@@ -487,36 +483,36 @@ Show all documentation about the symbol at point.
 @end table
 
   When a function name (@pxref{M-x,, Running Commands by Name}),
-variable name (@pxref{Variables}), or face name (@pxref{Faces}) appears
-in the documentation, it normally appears inside paired single-quotes.
-You can click on the name with @kbd{Mouse-1} or @kbd{Mouse-2}, or move
-point there and type @key{RET}, to view the documentation of that
-command, variable or face.  Use @kbd{C-c C-b} to retrace your steps.
+variable name (@pxref{Variables}), or face name (@pxref{Faces})
+appears in the documentation, it normally appears inside paired
+single-quotes.  To view the documentation of that command, variable or
+face, you can click on the name with @kbd{Mouse-1} or @kbd{Mouse-2},
+or move point there and type @key{RET}.  Use @kbd{C-c C-b} to retrace
+your steps.
 
 @cindex URL, viewing in help
 @cindex help, viewing web pages
 @cindex viewing web pages in help
 @cindex web pages, viewing in help
 @findex browse-url
-  You can follow cross references to URLs (web pages) as well.  When
-you follow a cross reference that is a URL, the @code{browse-url}
-command is used to view the web page in a browser of your choosing.
-@xref{Browse-URL}.
+  You can follow cross references to URLs (web pages) also.  This uses
+the @code{browse-url} command to view the page in the browser you
+choose.  @xref{Browse-URL}.
 
 @kindex @key{TAB} @r{(Help mode)}
 @findex help-next-ref
 @kindex S-@key{TAB} @r{(Help mode)}
 @findex help-previous-ref
-  There are convenient commands for moving point to cross references in
-the help text.  @key{TAB} (@code{help-next-ref}) moves point down to the
-next cross reference.  Use @kbd{S-@key{TAB}} to move point up to the
-previous cross reference (@code{help-previous-ref}).
+  There are convenient commands to move point to cross references in
+the help text.  @key{TAB} (@code{help-next-ref}) moves point down to
+the next cross reference.  @kbd{S-@key{TAB}} moves up to the previous
+cross reference (@code{help-previous-ref}).
 
-  You can view all documentation about any symbol name that appears in
-the text, by moving point to the symbol name and typing @kbd{C-c C-c}
+  To view all documentation about any symbol name that appears in the
+text, move point to the symbol name and type @kbd{C-c C-c}
 (@code{help-follow-symbol}).  This shows all available documentation
-about the symbol as a variable, function and/or face.  @kbd{C-c C-b}
-works in this case also, to retrace your steps.
+about the symbol as a variable, function and/or face.  As above, use
+@kbd{C-c C-b} to retrace your steps.
 
 @node Misc Help
 @section Other Help Commands
@@ -526,22 +522,18 @@ works in this case also, to retrace your steps.
 @cindex Info
 @cindex manuals, on-line
 @cindex on-line manuals
-  @kbd{C-h i} (@code{info}) runs the Info program, which is used for
-browsing through structured documentation files.  The entire Emacs manual
-is available within Info.  Eventually all the documentation of the GNU
-system will be available.  Type @kbd{h} after entering Info to run
-a tutorial on using Info.
+  @kbd{C-h i} (@code{info}) runs the Info program, which browses
+structured documentation files.  The entire Emacs manual is available
+within Info, along with many other manuals for the GNU system.  Type
+@kbd{h} after entering Info to run a tutorial on using Info.
 
 @cindex find Info manual by its file name
-  With a numeric argument, @kbd{C-h i} selects an Info buffer with the
-number appended to the default @samp{*info*} buffer name
-(e.g. @samp{*info*<2>}).  This is useful if you want to browse
-multiple Info manuals simultaneously.  If you specify just @kbd{C-u}
-as the prefix argument, @kbd{C-h i} prompts for the name of a
-documentation file.  This way, you can browse a file which doesn't
-have an entry in the top-level Info menu.  It is also handy when you
-need to get to the documentation quickly, and you know the exact name
-of the file.
+  With a numeric argument @var{n}, @kbd{C-h i} selects the Info buffer
+@samp{*info*<@var{n}>}.  This is useful if you want to browse multiple
+Info manuals simultaneously.  If you specify just @kbd{C-u} as the
+prefix argument, @kbd{C-h i} prompts for the name of a documentation
+file, so you can browse a file which doesn't have an entry in the
+top-level Info menu.
 
   The help commands @kbd{C-h F @var{function} @key{RET}} and @kbd{C-h
 K @var{key}}, described above, enter Info and go straight to the
@@ -550,56 +542,56 @@ documentation of @var{function} or @var{key}.
 @kindex C-h S
 @findex info-lookup-symbol
   When editing a program, if you have an Info version of the manual
-for the programming language, you can use the command @kbd{C-h S}
-(@code{info-lookup-symbol}) to refer to the manual documentation for a
-symbol (keyword, function or variable).  The details of how this
-command works depend on the major mode.
+for the programming language, you can use @kbd{C-h S}
+(@code{info-lookup-symbol}) to find symbol (keyword, function or
+variable) in the proper manual.  The details of how this command works
+depend on the major mode.
 
 @kindex C-h l
 @findex view-lossage
-  If something surprising happens, and you are not sure what commands you
-typed, use @kbd{C-h l} (@code{view-lossage}).  @kbd{C-h l} displays the last
-100 command characters you typed in.  If you see commands that you don't
-know, you can use @kbd{C-h c} to find out what they do.
+  If something surprising happens, and you are not sure what you
+typed, use @kbd{C-h l} (@code{view-lossage}).  @kbd{C-h l} displays
+the last 100 characters you typed in Emacs.  If you see commands that
+you don't know, you can use @kbd{C-h c} to find out what they do.
 
 @kindex C-h e
 @findex view-echo-area-messages
-  To review messages that recently appeared in the echo area, use
-@kbd{C-h e} (@code{view-echo-area-messages}).  This displays the
-buffer @code{*Messages*}, where those messages are kept.
+  To review recent echo area messages, use @kbd{C-h e}
+(@code{view-echo-area-messages}).  This displays the buffer
+@code{*Messages*}, where those messages are kept.
 
 @kindex C-h m
 @findex describe-mode
-  Emacs has numerous major modes, each of which redefines a few keys and
-makes a few other changes in how editing works.  @kbd{C-h m}
-(@code{describe-mode}) displays documentation on the current major mode,
-which normally describes all the commands that are changed in this
-mode.
+  Each Emacs major mode typically redefines a few keys and makes other
+changes in how editing works.  @kbd{C-h m} (@code{describe-mode})
+displays documentation on the current major mode, which normally
+describes the commands and features that are changed in this mode.
 
 @kindex C-h b
 @findex describe-bindings
   @kbd{C-h b} (@code{describe-bindings}) and @kbd{C-h s}
-(@code{describe-syntax}) present other information about the current
-Emacs mode.  @kbd{C-h b} displays a list of all the key bindings now in
-effect, showing the local bindings defined by the current minor modes first,
-then the local bindings defined by the current major mode, and finally
-the global bindings (@pxref{Key Bindings}).  @kbd{C-h s} displays the
-contents of the syntax table, with explanations of each character's
-syntax (@pxref{Syntax}).
-
-  You can get a similar list for a particular prefix key by typing
-@kbd{C-h} after the prefix key.  (There are a few prefix keys for which
-this does not work---those that provide their own bindings for
-@kbd{C-h}.  One of these is @key{ESC}, because @kbd{@key{ESC} C-h} is
-actually @kbd{C-M-h}, which marks a defun.)
+(@code{describe-syntax}) show other information about the current
+environment within Emacs.  @kbd{C-h b} displays a list of all the key
+bindings now in effect: first the local bindings of the current minor
+modes, then the local bindings defined by the current major mode, and
+finally the global bindings (@pxref{Key Bindings}).  @kbd{C-h s}
+displays the contents of the syntax table, with explanations of each
+character's syntax (@pxref{Syntax}).
+
+  You can get a list of subcommands for a particular prefix key by
+typing @kbd{C-h} after the prefix key.  (There are a few prefix keys
+for which this does not work---those that provide their own bindings
+for @kbd{C-h}.  One of these is @key{ESC}, because @kbd{@key{ESC} C-h}
+is actually @kbd{C-M-h}, which marks a defun.)
 
 @node Help Files
 @section Help Files
 
-  The Emacs help commands described above display the state of data
-bases within Emacs.  Emacs has a few other help commands that display
-pre-written help files.  These commands all have the form @kbd{C-h
-C-@var{char}}; that is, @kbd{C-h} followed by a control character.
+  The Emacs help commands described above display dynamic help based
+on the current state within Emacs, or refer to manuals.  Other help
+commands display pre-written, static help files.  These commands all
+have the form @kbd{C-h C-@var{char}}; that is, @kbd{C-h} followed by a
+control character.
 
 @kindex C-h C-c
 @findex describe-copying
@@ -617,31 +609,29 @@ C-@var{char}}; that is, @kbd{C-h} followed by a control character.
 @findex view-emacs-todo
 @kindex C-h C-w
 @findex describe-no-warranty
-  The other @kbd{C-h} options display various files containing useful
-information.
 
 @table @kbd
 @item C-h C-c
-Displays the Emacs copying conditions (@code{describe-copying}).
+Display the Emacs copying conditions (@code{describe-copying}).
 These are the rules under which you can copy and redistribute Emacs.
 @item C-h C-d
-Displays information on how to download or order the latest version of
+Display how to download or order the latest version of
 Emacs and other GNU software (@code{describe-distribution}).
 @item C-h C-e
-Displays the list of known Emacs problems, sometimes with suggested
+Display the list of known Emacs problems, sometimes with suggested
 workarounds (@code{view-emacs-problems}).
 @item C-h C-f
-Displays the Emacs frequently-answered-questions list (@code{view-emacs-FAQ}).
+Display the Emacs frequently-answered-questions list (@code{view-emacs-FAQ}).
 @item C-h C-n
-Displays the Emacs ``news'' file, which lists new Emacs features, most
-recent first (@code{view-emacs-news}).
+Display the Emacs ``news'' file, which lists new features in the most
+recent version of Emacs (@code{view-emacs-news}).
 @item C-h C-p
-Displays general information about the GNU Project
+Display general information about the GNU Project
 (@code{describe-project}).
 @item C-h C-t
-Displays the Emacs to-do list (@code{view-todo}).
+Display the Emacs to-do list (@code{view-todo}).
 @item C-h C-w
-Displays the full details on the complete absence of warranty for GNU
+Display the full details on the complete absence of warranty for GNU
 Emacs (@code{describe-no-warranty}).
 @end table
 
@@ -652,12 +642,12 @@ Emacs (@code{describe-no-warranty}).
 @cindex balloon help
   When a region of text is ``active,'' so that you can select it with
 the mouse or a key like @kbd{RET}, it often has associated help text.
-Areas of the mode line are examples.  On graphical displays, the help
-text is displayed as a ``tooltip'' (sometimes known as ``balloon
-help''), when you move the mouse over the active text.  @xref{Tooltips}.
-On some systems, it is shown in the echo area.  On text-only
-terminals, Emacs may not be able to follow the mouse and hence will
-not show the help text on mouse-over.
+For instance, most parts of the mode line have help text.  On
+graphical displays, the help text is displayed as a ``tooltip''
+(sometimes known as ``balloon help''), when you move the mouse over
+the active text.  @xref{Tooltips}.  On some systems, it is shown in
+the echo area.  On text-only terminals, if Emacs cannot follow the
+mouse, it cannot show the help text on mouse-over.
 
 @kindex C-h .
 @findex display-local-help
diff --git a/man/m-x.texi b/man/m-x.texi
index 9030f809cc3..c4974c5f7b4 100644
--- a/man/m-x.texi
+++ b/man/m-x.texi
@@ -5,31 +5,27 @@
 @node M-x, Help, Minibuffer, Top
 @chapter Running Commands by Name
 
-  Every Emacs command has a name that you can use to run it.  Commands
-that are used often, or that must be quick to type, are also bound to
-keys---short sequences of characters---for convenient use.  You can
-run them by typing the keys, or run them by name if you don't remember
-the keys.  Other Emacs commands that do not need to be quick are not
-bound to keys; the only way to run them is by name.  @xref{Key
-Bindings}, for the description of how to bind commands to keys.
+  Every Emacs command has a name that you can use to run it.  For
+convenience, many commands also have key bindings.  You can run those
+commands by typing the keys, or run them by name.  Most Emacs commands
+have no key bindings, so the only way to run them is by name.
+(@xref{Key Bindings}, for how to set up key bindings.)
 
   By convention, a command name consists of one or more words,
 separated by hyphens; for example, @code{auto-fill-mode} or
-@code{manual-entry}.  The use of English words makes the command name
-easier to remember than a key made up of obscure characters, even
-though it is more characters to type.
+@code{manual-entry}.  Command names mostly use complete English words
+to make them easier to remember.
 
 @kindex M-x
-  The way to run a command by name is to start with @kbd{M-x}, type the
-command name, and finish it with @key{RET}.  @kbd{M-x} uses the
-minibuffer to read the command name.  @key{RET} exits the minibuffer and
-runs the command.  The string @samp{M-x} appears at the beginning of the
-minibuffer as a @dfn{prompt} to remind you to enter the name of a
-command to be run.  @xref{Minibuffer}, for full information on the
-features of the minibuffer.
+  To run a command by name, start with @kbd{M-x}, type the command
+name, then terminate it with @key{RET}.  @kbd{M-x} uses the minibuffer
+to read the command name.  The string @samp{M-x} appears at the
+beginning of the minibuffer as a @dfn{prompt} to remind you to enter a
+command name to be run.  @key{RET} exits the minibuffer and runs the
+command.  @xref{Minibuffer}, for more information on the minibuffer.
 
   You can use completion to enter the command name.  For example, you
-can invoke the command @code{forward-char} by name by typing either
+to invoke the command @code{forward-char}, you can type
 
 @example
 M-x forward-char @key{RET}
@@ -44,32 +40,30 @@ M-x forw @key{TAB} c @key{RET}
 
 @noindent
 Note that @code{forward-char} is the same command that you invoke with
-the key @kbd{C-f}.  You can run any Emacs command by name using
-@kbd{M-x}, whether or not any keys are bound to it.
+the key @kbd{C-f}.  The existence of a key binding does not stop you
+from running the command by name.
 
-  If you type @kbd{C-g} while the command name is being read, that
-cancels the @kbd{M-x} command and exits the minibuffer, so you end up
-back at command level.
+  To cancel the @kbd{M-x} and not run a command, type @kbd{C-g} instead
+of entering the command name.  This takes you back to command level.
 
   To pass a numeric argument to the command you are invoking with
-@kbd{M-x}, specify the numeric argument before the @kbd{M-x}.  @kbd{M-x}
-passes the argument along to the command it runs.  The argument value
-appears in the prompt while the command name is being read.
+@kbd{M-x}, specify the numeric argument before @kbd{M-x}.  The
+argument value appears in the prompt while the command name is being
+read, and finally @kbd{M-x} passes the argument to that command.
 
 @vindex suggest-key-bindings
-  If the command you type has a key binding of its own, Emacs mentions
-this in the echo area after running the command.  For example, if you
-type @kbd{M-x forward-word}, the message says that you can run the
-same command more easily by typing @kbd{M-f}.  You can turn off these
+  When the command you run with @kbd{M-x} has a key binding, Emacs
+mentions this in the echo area after running the command.  For
+example, if you type @kbd{M-x forward-word}, the message says that you
+can run the same command by typing @kbd{M-f}.  You can turn off these
 messages by setting the variable @code{suggest-key-bindings} to
 @code{nil}.
 
-  Normally, when describing in this manual a command that is run by
-name, we omit the @key{RET} that is needed to terminate the name.  Thus
-we might speak of @kbd{M-x auto-fill-mode} rather than @kbd{M-x
-auto-fill-mode @key{RET}}.  We mention the @key{RET} only when there is
-a need to emphasize its presence, such as when we show the command
-together with following arguments.
+  In this manual, when we speak of running a command by name, we often
+omit the @key{RET} that terminates the name.  Thus we might say
+@kbd{M-x auto-fill-mode} rather than @kbd{M-x auto-fill-mode
+@key{RET}}.  We mention the @key{RET} only for emphasis, such as when
+the command is followed by arguments.
 
 @findex execute-extended-command
   @kbd{M-x} works by running the command
-- 
2.39.2