From b46be29424cc84982cf8b0cad8f3fdbc98e1c8e0 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Thu, 15 Feb 2018 20:38:13 +0200 Subject: [PATCH] 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 in emacs-manual-bugs@gnu.org. * 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 in emacs-manual-bugs@gnu.org. * doc/emacs/msdos.texi (Windows Misc): A minor rewording. Suggested by Isaac Carter in emacs-manual-bugs@gnu.org. --- 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 98ff8258dbe..859c6132436 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 +@code{column-number-indicator-zero-based} 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 -@kbd{C-M-j}, the continuation marker on the newline is created according -to the continuation style. +continuation line with @kbd{@key{TAB}}, it converts the line to the +current continuation style. When you split a Fortran statement with +@kbd{C-M-j}, 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 +@code{column-number-indicator-zero-based} 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 non-@code{nil} 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 -@key{SPC}, @key{RET}, or @key{TAB}, and also in the Fortran -indentation commands. You activate Auto Fill in Fortran mode in the -normal way. +@kbd{@key{SPC}}, @kbd{@key{RET}}, or @kbd{@key{TAB}}, 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 2ed264258eb..6c093f13d05 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 dd368adb54a..27f9667e38b 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 3944ce46071..2bd6101782d 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 VHDL@. 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. +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 VHDL@. 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 @kbd{@key{TAB}} 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}). -@item C-c @@ C-l +@item 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: @kbd{@key{RET}} +accepts the current completion, @kbd{M-n} and @kbd{M-p} cycle through +possible completions, @kbd{@key{TAB}} 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 @kbd{@{}, @kbd{@}}, @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 -@kbd{C-c C-l}; when it is enabled, @samp{/l} appears in the mode line -after the mode name: +@kbd{C-c 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 +@kbd{@key{DEL}} deletes all preceding whitespace, not just one space, +and a single @kbd{C-d} (but @emph{not} plain @kbd{@key{Delete}}) +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 -@key{RET} (@code{newline}), in a C preprocessor line it additionally +@kbd{@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 -@key{RET}. We use @code{c-initialization-hook} here to make sure -the keymap is loaded before we try to change it. +@kbd{@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 45407b21098..e753ab55196 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 @kbd{M-@key{TAB}}, 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 -- 2.39.2