[Emacs-diffs] emacs-26 b46be29: More improvements for the Emacs manual

[Eli Zaretskii]

branch: emacs-26
commit b46be29424cc84982cf8b0cad8f3fdbc98e1c8e0
Author: Eli Zaretskii <address@hidden>
Commit: Eli Zaretskii <address@hidden>

    More improvements for the Emacs manual
    
    * doc/emacs/programs.texi (Basic Indent, Comment Commands): Fix
    typos.
    * doc/emacs/text.texi (TeX Print, HTML Mode, Enriched Faces): Fix
    typos.
    * doc/emacs/help.texi (Help Files): Improve @uref usage.  Reported
    by Stefan Kamphausen <address@hidden> in
    address@hidden
    
    * doc/emacs/fortran-xtra.texi (ForIndent Commands): Fix a typo.
    (ForIndent Commands, Fortran Columns): Add empty lines between
    @items in a @table.
    (ForIndent Cont, ForIndent Num, Fortran Columns): Mention
    'column-number-indicator-zero-based'.
    (ForIndent Vars): Fix a typo.
    (Fortran Comments): Fix punctuation.
    (ForIndent Cont, Fortran Autofill): Fix markup of keyboard input.
    * doc/emacs/programs.texi (Comments): Fix a typo.
    (Comment Commands): More accurate description of the commands.
    (Options for Comments): Don't mention "hook".
    (Man Page): Prefer "M-x man" if available.
    (Hideshow): Fix the command key sequence.
    (Semantic): Update supported languages.
    (Semantic, Hungry Delete, Other C Commands): Fix markup of
    commands.
    (Misc for Programs): Fix a typo.
    (Electric C, Hungry Delete): More accurate description of
    mode-line lighters of CC submodes.
    (Asm Mode): Add empty lines between @items in a @table.
    * doc/emacs/programs.texi (Program Modes): Add a few more modes.
    Reported by Michael Albinus <address@hidden> in
    address@hidden
    
    * doc/emacs/msdos.texi (Windows Misc): A minor rewording.
    Suggested by Isaac Carter <address@hidden> in
    address@hidden
---
 doc/emacs/fortran-xtra.texi | 42 ++++++++++++++--------
 doc/emacs/help.texi         |  2 +-
 doc/emacs/msdos.texi        |  3 +-
 doc/emacs/programs.texi     | 86 +++++++++++++++++++++++++--------------------
 doc/emacs/text.texi         |  8 ++---
 5 files changed, 82 insertions(+), 59 deletions(-)

diff --git a/doc/emacs/fortran-xtra.texi b/doc/emacs/fortran-xtra.texi
index 98ff825..859c613 100644
--- a/doc/emacs/fortran-xtra.texi
+++ b/doc/emacs/fortran-xtra.texi
@@ -158,11 +158,14 @@ the required columns.
 @item C-M-j
 Break the current line at point and set up a continuation line
 (@code{fortran-split-line}).
+
 @item M-^
 Join this line to the previous line (@code{fortran-join-line}).
+
 @item C-M-q
 Indent all the lines of the subprogram that point is in
 (@code{fortran-indent-subprogram}).
+
 @item M-q
 Fill a comment block or statement (using @code{fortran-fill-paragraph}
 or @code{fortran-fill-statement}).
@@ -185,7 +188,7 @@ lines.
 @kindex M-^ @r{(Fortran mode)}
 @kindex C-c C-d @r{(Fortran mode)}
 @findex fortran-join-line
-  @kbd{M-^} or @kbd{C-c C-d} runs the command @code{fortran-join-line},
+  @kbd{M-^} or @kbd{C-c C-d} run the command @code{fortran-join-line},
 which joins a continuation line back to the previous line, roughly as
 the inverse of @code{fortran-split-line}.  The point must be on a
 continuation line when this command is invoked.
@@ -203,7 +206,9 @@ point is in.  This removes any excess statement 
continuations.
 If the first non-space character on a line is in column 5, then that
 line is a continuation of the previous line.  We call this @dfn{fixed
 form}.  (In GNU Emacs we always count columns from 0; but note that
-the Fortran standard counts from 1.)  The variable
+the Fortran standard counts from 1.  You can customize the variable
address@hidden to make the column display
+Fortran-like; @pxref{Optional Mode Line}.)  The variable
 @code{fortran-continuation-string} specifies what character to put in
 column 5.  A line that starts with a tab character followed by any digit
 except @samp{0} is also a continuation line.  We call this style of
@@ -229,10 +234,10 @@ accordingly.
   If the text on a line starts with the Fortran continuation marker
 @samp{$}, or if it begins with any non-whitespace character in column
 5, Fortran mode treats it as a continuation line.  When you indent a
-continuation line with @key{TAB}, it converts the line to the current
-continuation style.  When you split a Fortran statement with
address@hidden, the continuation marker on the newline is created according
-to the continuation style.
+continuation line with @address@hidden, it converts the line to the
+current continuation style.  When you split a Fortran statement with
address@hidden, the continuation marker on the newline is created
+according to the continuation style.
 
   The setting of continuation style affects several other aspects of
 editing in Fortran mode.  In fixed form mode, the minimum column
@@ -247,7 +252,9 @@ column 8 must consist of one tab character.
 
   If a number is the first non-whitespace in the line, Fortran
 indentation assumes it is a line number and moves it to columns 0
-through 4.  (Columns always count from 0 in Emacs.)
+through 4.  (Columns always count from 0 in Emacs, but setting
address@hidden to @code{nil} can change
+that, @pxref{Optional Mode Line}.)
 
 @vindex fortran-line-number-indent
   Line numbers of four digits or less are normally indented one space.
@@ -320,7 +327,7 @@ Extra indentation within each level of @samp{structure}, 
@samp{union},
 Extra indentation for bodies of continuation lines (default 5).
 
 @item fortran-check-all-num-for-matching-do
-In Fortran 77, a numbered @samp{do} statement is ended by any statement
+In Fortran 77, a numbered @samp{do} statement is terminated by any statement
 with a matching line number.  It is common (but not compulsory) to use a
 @samp{continue} statement for this purpose.  If this variable has a
 address@hidden value, indenting any numbered statement must check for a
@@ -330,7 +337,7 @@ then you can speed up indentation by setting this variable 
to
 @code{nil} (the default).
 
 @item fortran-blink-matching-if
-If this is @code{t}, indenting an @samp{endif} (or @samp{enddo}
+If this is @code{t}, indenting an @samp{endif} (or @samp{enddo})
 statement moves the cursor momentarily to the matching @samp{if} (or
 @samp{do}) statement to show where it is.  The default is @code{nil}.
 
@@ -386,7 +393,7 @@ Fortran mode as in other modes.
 
   When a new comment must be inserted, if the current line is blank, a
 full-line comment is inserted.  On a non-blank line, a nonstandard @samp{!}
-comment is inserted if you have said you want to use them.  Otherwise a
+comment is inserted if you have said you want to use them.  Otherwise, a
 full-line comment is inserted on a new line before the current line.
 
   Nonstandard @samp{!} comments are aligned like comments in other
@@ -434,7 +441,7 @@ distinctive font-locking.
 
   The normal Emacs comment command @kbd{C-x ;} (@code{comment-set-column})
 has not been redefined.  If you use @samp{!} comments, this command
-can be used with them.  Otherwise it is useless in Fortran mode.
+can be used with them.  Otherwise, it is useless in Fortran mode.
 
 @kindex C-c ; @r{(Fortran mode)}
 @findex fortran-comment-region
@@ -457,9 +464,9 @@ minor mode that automatically splits statements as you 
insert them
 when they become too wide.  Splitting a statement involves making
 continuation lines using @code{fortran-continuation-string}
 (@pxref{ForIndent Cont}).  This splitting happens when you type
address@hidden, @key{RET}, or @key{TAB}, and also in the Fortran
-indentation commands.  You activate Auto Fill in Fortran mode in the
-normal way.
address@hidden@key{SPC}}, @address@hidden, or @address@hidden, and also in the
+Fortran indentation commands.  You activate Auto Fill in Fortran mode
+in the normal way.
 @iftex
 @xref{Auto Fill,,, emacs, the Emacs Manual}.
 @end iftex
@@ -501,15 +508,18 @@ will confuse font-lock.)
 @item C-c C-r
 Display a column ruler momentarily above the current line
 (@code{fortran-column-ruler}).
+
 @item C-c C-w
 Split the current window horizontally temporarily so that it is
 @code{fortran-line-length} columns wide
 (@code{fortran-window-create-momentarily}).  This may help you avoid
 making lines longer than the limit imposed by your Fortran compiler.
+
 @item C-u C-c C-w
 Split the current window horizontally so that it is
 @code{fortran-line-length} columns wide (@code{fortran-window-create}).
 You can then continue editing.
+
 @item M-x fortran-strip-sequence-nos
 Delete all text in column @code{fortran-line-length} and beyond.
 @end table
@@ -523,7 +533,9 @@ Fortran programs.  Square brackets show the limits of the 
columns for line
 numbers, and curly brackets show the limits of the columns for the
 statement body.  Column numbers appear above them.
 
-  Note that the column numbers count from zero, as always in GNU Emacs.
+  Note that the column numbers count from zero, as always in GNU Emacs
+(but customizing @code{column-number-indicator-zero-based} can change
+column display to match that of Fortran; @pxref{Optional Mode Line}).
 As a result, the numbers may be one less than those you are familiar
 with; but the positions they indicate in the line are standard for
 Fortran.
diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi
index 2ed2642..6c093f1 100644
--- a/doc/emacs/help.texi
+++ b/doc/emacs/help.texi
@@ -642,7 +642,7 @@ Display information about where to get external packages
 @item C-h C-f
 Display the Emacs frequently-answered-questions list (@code{view-emacs-FAQ}).
 @item C-h g
-Visit a @uref{https://www.gnu.org} page with information about the GNU
+Visit the @uref{https://www.gnu.org, page} with information about the GNU
 Project (@code{describe-gnu-project}).
 @item C-h C-m
 Display information about ordering printed copies of Emacs manuals
diff --git a/doc/emacs/msdos.texi b/doc/emacs/msdos.texi
index dd368ad..27f9667 100644
--- a/doc/emacs/msdos.texi
+++ b/doc/emacs/msdos.texi
@@ -1033,7 +1033,8 @@ the system default antialiasing.
 @node Windows Misc
 @section Miscellaneous Windows-specific features
 
-  This section describes miscellaneous Windows-specific features.
+  This section describes Windows-specific features that don't fit
+anywhere else.
 
 @vindex w32-use-visible-system-caret
 @cindex screen reader software, MS-Windows
diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi
index 3944ce4..2bd6101 100644
--- a/doc/emacs/programs.texi
+++ b/doc/emacs/programs.texi
@@ -86,14 +86,14 @@ mode for the C programming language is @code{c-mode}.
 @cindex Awk mode
   Emacs has programming language modes for Lisp, Scheme, the
 Scheme-based DSSSL expression language, Ada, ASM, AWK, C, C++,
-Fortran, Icon, IDL (CORBA), IDLWAVE, Java, Javascript, Metafont
-(@TeX{}'s companion for font creation), Modula2, Object Pascal,
-Objective-C, Octave, Pascal, Perl, Pike, PostScript, Prolog, Python,
-Ruby, Simula, SQL, Tcl, Verilog, and address@hidden  An alternative mode for
-Perl is called CPerl mode.  Modes are also available for the scripting
-languages of the common GNU and Unix shells, and MS-DOS/MS-Windows
address@hidden files, and for makefiles, DNS master files, and various
-sorts of configuration files.
+Fortran, Icon, IDL (CORBA), IDLWAVE, Java, Javascript, M4, Makefiles,
+Metafont (@TeX{}'s companion for font creation), Modula2, Object
+Pascal, Objective-C, Octave, Pascal, Perl, Pike, PostScript, Prolog,
+Python, Ruby, Simula, SQL, Tcl, Verilog, and address@hidden  An alternative
+mode for Perl is called CPerl mode.  Modes are also available for the
+scripting languages of the common GNU and Unix shells, and
+MS-DOS/MS-Windows @samp{BAT} files, and for makefiles, DNS master
+files, and various sorts of configuration files.
 
   Ideally, Emacs should have a major mode for each programming
 language that you might want to edit.  If it doesn't have a mode for
@@ -403,7 +403,7 @@ manually give one of these lines a nonstandard indentation 
(e.g., for
 aesthetic purposes), the lines below will follow it.
 
   The indentation commands for most programming language modes assume
-that a open-parenthesis, open-brace or other opening delimiter at the
+that an open-parenthesis, open-brace or other opening delimiter at the
 left margin is the start of a function.  If the code you are editing
 violates this assumption---even if the delimiters occur in strings or
 comments---you must set @code{open-paren-in-column-0-is-defun-start}
@@ -927,7 +927,7 @@ also do spell checking on comments with Flyspell Prog mode
 comments.  For example, in Lisp code, comments starting with two
 semicolons are indented as if they were lines of code, while those
 starting with three semicolons are supposed to be aligned to the left
-margin and are often used for sectioning purposes.  Emacs understand
+margin and are often used for sectioning purposes.  Emacs understands
 these conventions; for instance, typing @address@hidden on a comment
 line will indent the comment to the appropriate position.
 
@@ -958,7 +958,9 @@ line will indent the comment to the appropriate position.
 Insert or realign comment on current line; if the region is active,
 comment or uncomment the region instead (@code{comment-dwim}).
 @item @kbd{C-x C-;}
-Comment or uncomment the current line (@code{comment-line}).
+Comment or uncomment the current line (@code{comment-line}).  If the
+region is active, comment or uncomment the lines in the region
+instead.
 @item @kbd{C-u M-;}
 Kill comment on current line (@code{comment-kill}).
 @item @kbd{C-x ;}
@@ -1045,8 +1047,7 @@ region, even if the mark is inactive.  In C mode and 
related modes,
 this command is bound to @kbd{C-c C-c}.  The command @kbd{M-x
 uncomment-region} uncomments each line in the region; a numeric prefix
 argument specifies the number of comment delimiters to remove
-(negative arguments specify the number of comment to delimiters to
-add).
+(negative arguments specify the number of comment delimiters to add).
 
   For C-like modes, you can configure the exact effect of @kbd{M-;} by
 setting the variables @code{c-indent-comment-alist} and
@@ -1151,8 +1152,8 @@ comment or for aligning an existing comment.  It is set 
differently by
 various major modes.  The function is called with no arguments, but with
 point at the beginning of the comment, or at the end of a line if a new
 comment is to be inserted.  It should return the column in which the
-comment ought to start.  For example, the default hook function bases
-its decision on how many comment characters begin an existing comment.
+comment ought to start.  For example, the default function bases its
+decision on how many comment characters begin an existing comment.
 
 Emacs also tries to align comments on adjacent lines.  To override
 this, the function may return a cons of two (possibly equal) integers
@@ -1183,10 +1184,10 @@ buffer at point.  For example, in C mode this looks for 
the symbol in
 the C Library Manual.  The command only works if the appropriate
 manual's Info files are installed.
 
-  The major mode determines where to look for documentation for the
-symbol---which Info files to look in, and which indices to search.
-You can also use @kbd{M-x info-lookup-file} to look for documentation
-for a file name.
+  Emacs determines where to look for documentation for the
+symbol---which Info files to look in, and which indices to
+search---based on the major mode.  You can also use @kbd{M-x
+info-lookup-file} to look for documentation for a file name.
 
   If you use @kbd{C-h S} in a major mode that does not support it,
 it asks you to specify the symbol help mode.  You should enter
@@ -1256,6 +1257,10 @@ several manual pages by the same name exist in different 
sections, it
 pops up a window with possible candidates asking you to choose one of
 them.
 
+  Note that @kbd{M-x woman} doesn't yet support the latest features of
+modern man pages, so we recommend using @kbd{M-x man} if that is
+available on your system.
+
   For more information about setting up and using @kbd{M-x woman}, see
 @ifinfo
 @ref{Top, WoMan, Browse UN*X Manual Pages WithOut Man, woman, The
@@ -1336,7 +1341,7 @@ Hide all top-level blocks (@code{hs-hide-all}).
 @item C-c @@ C-M-s
 @itemx C-c @@ C-a
 Show all blocks in the buffer (@code{hs-show-all}).
address@hidden C-c @@ C-l
address@hidden C-u @var{n} C-c @@ C-l
 Hide all blocks @var{n} levels below this block
 (@code{hs-hide-level}).
 @end table
@@ -1458,8 +1463,8 @@ the menu item named @samp{Source Code Parsers (Semantic)} 
in the
 
    When Semantic mode is enabled, Emacs automatically attempts to
 parse each file you visit.  Currently, Semantic understands C, C++,
-Scheme, Javascript, Java, HTML, and Make.  Within each parsed buffer,
-the following commands are available:
+Javascript, Java, HTML, Make, Python, Scheme, SRecode, and Texinfo.
+Within each parsed buffer, the following commands are available:
 
 @table @kbd
 @item C-c , j
@@ -1476,10 +1481,10 @@ parsed, and move point there 
(@code{semantic-complete-jump}).
 @kindex C-c , SPC
 Display a list of possible completions for the symbol at point
 (@code{semantic-complete-analyze-inline}).  This also activates a set
-of special key bindings for choosing a completion: @key{RET} accepts
-the current completion, @kbd{M-n} and @kbd{M-p} cycle through possible
-completions, @key{TAB} completes as far as possible and then cycles,
-and @kbd{C-g} or any other key aborts completion.
+of special key bindings for choosing a completion: @address@hidden
+accepts the current completion, @kbd{M-n} and @kbd{M-p} cycle through
+possible completions, @address@hidden completes as far as possible and
+then cycles, and @kbd{C-g} or any other key aborts completion.
 
 @item C-c , l
 @kindex C-c , l
@@ -1503,7 +1508,7 @@ is idle.
 programs are useful for that nonetheless.
 
   The Emacs commands that operate on words, sentences and paragraphs
-are useful for editing code.  Most symbols names contain words
+are useful for editing code.  Most symbol names contain words
 (@pxref{Words}), while sentences can be found in strings and comments
 (@pxref{Sentences}).  As for paragraphs, they are defined in most
 programming language modes to begin and end at blank lines
@@ -1678,8 +1683,9 @@ electric characters are @address@hidden, @address@hidden, 
@kbd{:}, @kbd{#},
   You might find electric indentation inconvenient if you are editing
 chaotically indented code.  If you are new to CC Mode, you might find
 it disconcerting.  You can toggle electric action with the command
address@hidden C-l}; when it is enabled, @samp{/l} appears in the mode line
-after the mode name:
address@hidden C-l}; when it is enabled, @samp{/@var{c}l} appears in the
+mode line after the mode name (where @var{c}, if present, is @samp{*}
+or @samp{/}):
 
 @table @kbd
 @item C-c C-l
@@ -1692,8 +1698,8 @@ negative one it disables it.
 
   Electric characters insert newlines only when, in addition to the
 electric state, the @dfn{auto-newline} feature is enabled (indicated
-by @samp{/la} in the mode line after the mode name).  You can turn
-this feature on or off with the command @kbd{C-c C-a}:
+by @samp{/@var{c}la} in the mode line after the mode name).  You can
+turn this feature on or off with the command @kbd{C-c C-a}:
 
 @table @kbd
 @item C-c C-a
@@ -1737,10 +1743,11 @@ Delete the entire block of whitespace after point 
(@code{c-hungry-delete-forward
 @end table
 
   As an alternative to the above commands, you can enable @dfn{hungry
-delete mode}.  When this feature is enabled (indicated by @samp{/h} in
-the mode line after the mode name), a single @key{DEL} deletes all
-preceding whitespace, not just one space, and a single @kbd{C-d}
-(but @emph{not} plain @key{Delete}) deletes all following whitespace.
+delete mode}.  When this feature is enabled (indicated by @samp{h}
+after a @samp{/} in the mode line after the mode name), a single
address@hidden@key{DEL}} deletes all preceding whitespace, not just one space,
+and a single @kbd{C-d} (but @emph{not} plain @address@hidden)
+deletes all following whitespace.
 
 @table @kbd
 @item M-x c-toggle-hungry-state
@@ -1763,14 +1770,14 @@ hungry-delete feature is enabled.
 @findex c-context-line-break
 This command inserts a line break and indents the new line in a manner
 appropriate to the context.  In normal code, it does the work of
address@hidden (@code{newline}), in a C preprocessor line it additionally
address@hidden@key{RET}} (@code{newline}), in a C preprocessor line it 
additionally
 inserts a @samp{\} at the line break, and within comments it's like
 @kbd{M-j} (@code{c-indent-new-comment-line}).
 
 @code{c-context-line-break} isn't bound to a key by default, but it
 needs a binding to be useful.  The following code will bind it to
address@hidden  We use @code{c-initialization-hook} here to make sure
-the keymap is loaded before we try to change it.
address@hidden@key{RET}}.  We use @code{c-initialization-hook} here to make
+sure the keymap is loaded before we try to change it.
 
 @example
 (defun my-bind-clb ()
@@ -1895,11 +1902,14 @@ defines these commands:
 @item @key{TAB}
 @code{tab-to-tab-stop}.
 @c FIXME: Maybe this should be consistent with other programming modes.
+
 @item C-j
 Insert a newline and then indent using @code{tab-to-tab-stop}.
+
 @item :
 Insert a colon and then remove the indentation from before the label
 preceding colon.  Then do @code{tab-to-tab-stop}.
+
 @item ;
 Insert or align a comment.
 @end table
diff --git a/doc/emacs/text.texi b/doc/emacs/text.texi
index 45407b2..e753ab5 100644
--- a/doc/emacs/text.texi
+++ b/doc/emacs/text.texi
@@ -1684,7 +1684,7 @@ when you type the corresponding one.
 @node TeX Print
 @subsection @TeX{} Printing Commands
 
-  You can invoke @TeX{} as an subprocess of Emacs, supplying either
+  You can invoke @TeX{} as a subprocess of Emacs, supplying either
 the entire contents of the buffer or just part of it (e.g., one
 chapter of a larger document).
 
@@ -1736,7 +1736,7 @@ C-p} (@code{tex-print}) to print a hardcopy of the output 
file.
 output of @TeX{} also goes in this directory.  To run @TeX{} in a
 different directory, change the variable @code{tex-directory} to
 the desired directory.  If your environment variable @env{TEXINPUTS}
-contains relative names, or if your files contains
+contains relative names, or if your files contain
 @samp{\input} commands with relative file names, then
 @code{tex-directory} @emph{must} be @code{"."} or you will get the
 wrong results.  Otherwise, it is safe to specify some other directory,
@@ -2007,7 +2007,7 @@ used as a cheap preview (@code{sgml-tags-invisible}).
 @findex nxml-mode
 @cindex XML schema
   The major mode for editing XML documents is called nXML mode.  This
-is a powerful major mode that can recognize many existing XML schema
+is a powerful major mode that can recognize many existing XML schemas
 and use them to provide completion of XML elements via
 @address@hidden, as well as on-the-fly XML
 validation with error highlighting.  To enable nXML mode in an
@@ -2280,7 +2280,7 @@ Prompt for a color, and apply it as a background color.
 @end table
 
 @noindent
-These command are also available via the Text Properties menu.
+These commands are also available via the Text Properties menu.
 
   A self-inserting character normally inherits the face properties
 (and most other text properties) from the preceding character in the