From 26f64410fd6845cde1a06373eea05e256b87513d Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Mon, 12 Feb 2018 19:52:48 +0200 Subject: [PATCH] Another set of improvements in the Emacs manual * doc/emacs/msdos-xtra.texi (MS-DOS Keyboard): * doc/emacs/msdos.texi (Windows Keyboard): * doc/emacs/mark.texi (Using Region): * doc/emacs/frames.texi (Menu Mouse Clicks): * doc/emacs/macos.texi (Mac / GNUstep Basics): Fix spelling of keys. Reported by Michael Albinus in emacs-manual-bugs@gnu.org. * doc/emacs/glossary.texi (Glossary): Document that "c.f." is a misspelling. Reported by Robert Pluim . Various minor wording improvements. Suggested by Toon Claes in emacs-manual-bugs@gnu.org. More minor changes. Suggested by Michael Albinus in emacs-manual-bugs@gnu.org. * doc/emacs/cmdargs.texi (Title X): Improve wording. * doc/emacs/building.texi (Grep Searching, Compilation): Avoid passive tense. * doc/emacs/basic.texi (Moving Point): Move the description of the bidi-related effects of the arrow keys from here ... * doc/emacs/mule.texi (Bidirectional Editing): ... to here. Explain the behavior of arrow keys between paragraphs. --- doc/emacs/basic.texi | 22 ++++------------------ doc/emacs/building.texi | 14 +++++++------- doc/emacs/cmdargs.texi | 17 ++++++++--------- doc/emacs/frames.texi | 2 +- doc/emacs/glossary.texi | 47 +++++++++++++++++++++++++++-------------------- doc/emacs/macos.texi | 6 +++--- doc/emacs/mark.texi | 2 +- doc/emacs/msdos-xtra.texi | 2 +- doc/emacs/msdos.texi | 2 +- doc/emacs/mule.texi | 34 ++++++++++++++++++++++++++++++---- 10 files changed, 83 insertions(+), 65 deletions(-) diff --git a/doc/emacs/basic.texi b/doc/emacs/basic.texi index 8a8298bc2c4..4db3855dd9c 100644 --- a/doc/emacs/basic.texi +++ b/doc/emacs/basic.texi @@ -184,18 +184,8 @@ Move forward one character (@code{forward-char}). @item @key{RIGHT} @kindex RIGHT @findex right-char -@vindex visual-order-cursor-movement -@cindex cursor, visual-order motion -This command (@code{right-char}) behaves like @kbd{C-f}, with one -exception: when editing right-to-left scripts such as Arabic, it -instead moves @emph{backward} if the current paragraph is a -right-to-left paragraph. @xref{Bidirectional Editing}. - -If @code{visual-order-cursor-movement} is non-@code{nil}, this command -moves to the character that is to the right of the current screen -position, moving to the next or previous screen line as appropriate. -Note that this might potentially move point many buffer positions -away, depending on the surrounding bidirectional context. +This command (@code{right-char}) behaves like @kbd{C-f}, except when +point is in a right-to-left paragraph (@pxref{Bidirectional Editing}). @item C-b @kindex C-b @@ -205,12 +195,8 @@ Move backward one character (@code{backward-char}). @item @key{LEFT} @kindex LEFT @findex left-char -This command (@code{left-char}) behaves like @kbd{C-b}, except it -moves @emph{forward} if the current paragraph is right-to-left. -@xref{Bidirectional Editing}. - -The variable @code{visual-order-cursor-movement} affects this like -@key{RIGHT}, but moving left instead of right on the screen. +This command (@code{left-char}) behaves like @kbd{C-b}, except if the +current paragraph is right-to-left (@pxref{Bidirectional Editing}). @item C-n @itemx @key{DOWN} diff --git a/doc/emacs/building.texi b/doc/emacs/building.texi index f61e3335770..f2819c67c5d 100644 --- a/doc/emacs/building.texi +++ b/doc/emacs/building.texi @@ -90,9 +90,9 @@ inserted above point, which remains at the end. Otherwise, point remains fixed while compilation output is added at the end of the buffer. - While compilation proceeds, the mode line is updated to show the -number of errors, warnings, and informational messages that have been -seen so far. + While compilation proceeds, the mode line shows the number of +errors, warnings, and informational messages emitted by the compiler +so far. @cindex compilation buffer, keeping point at end @vindex compilation-scroll-output @@ -384,16 +384,16 @@ grep -nH -e foo *.el | grep bar | grep toto can find the corresponding lines in the original files using @w{@kbd{C-x `}}, @key{RET}, and so forth, just like compilation errors. - As with compilation commands (@pxref{Compilation}), while the grep -command runs, the mode line is updated to show the number of matches -that have been seen so far. - Some grep programs accept a @samp{--color} option to output special markers around matches for the purpose of highlighting. You can make use of this feature by setting @code{grep-highlight-matches} to @code{t}. When displaying a match in the source buffer, the exact match will be highlighted, instead of the entire source line. + As with compilation commands (@pxref{Compilation}), while the grep +command runs, the mode line shows the running number of matches found +and highlighted so far. + The @command{grep} commands will offer to save buffers before running. This is controlled by the @code{grep-save-buffers} variable. The possible values are either @code{nil} (don't save), @code{ask} diff --git a/doc/emacs/cmdargs.texi b/doc/emacs/cmdargs.texi index e463e7c8194..d18de8e7a02 100644 --- a/doc/emacs/cmdargs.texi +++ b/doc/emacs/cmdargs.texi @@ -1104,15 +1104,14 @@ border is 2. @node Title X @appendixsec Frame Titles - An Emacs frame may or may not have a specified title. The frame -title, if specified, appears in window decorations and icons as the -name of the frame. If an Emacs frame has no specified title, the -default title has the form @samp{@var{invocation-name}@@@var{machine}} -(if there is only one frame) or the selected window's buffer name (if -there is more than one frame). - - You can specify a title for the initial Emacs frame with a command -line option: + Each Emacs frame always has a title, which appears in window +decorations and icons as the name of the frame. The default title is +of the form @samp{@var{invocation-name}@@@var{machine}} (if there is +only one frame) or shows the selected window's buffer name (if there +is more than one frame). + + You can specify a non-default title for the initial Emacs frame with +a command line option: @table @samp @item -T @var{title} diff --git a/doc/emacs/frames.texi b/doc/emacs/frames.texi index 2c1a55b7dc6..b2ec5746a0e 100644 --- a/doc/emacs/frames.texi +++ b/doc/emacs/frames.texi @@ -312,7 +312,7 @@ button. @node Menu Mouse Clicks @section Mouse Clicks for Menus - Several mouse clicks with the @key{CTRL} and @key{SHIFT} modifiers + Several mouse clicks with the @key{Ctrl} and @key{SHIFT} modifiers bring up menus. @table @kbd diff --git a/doc/emacs/glossary.texi b/doc/emacs/glossary.texi index 7a34692dc53..a9120194a49 100644 --- a/doc/emacs/glossary.texi +++ b/doc/emacs/glossary.texi @@ -24,7 +24,7 @@ Setting the mark (q.v.@:) at a position in the text also activates it. When the mark is active, we call the region an active region. @xref{Mark}. -@item Alt +@item @key{Alt} Alt is the name of a modifier bit that a keyboard input character may have. To make a character Alt, type it while holding down the @key{Alt} key. Such characters are given names that start with @kbd{@key{Alt}-} @@ -160,10 +160,11 @@ right away when you press down on a mouse button. @xref{Mouse Buttons}. @item Byte Compilation @xref{Glossary---Compilation}. -@item c.f. -@itemx cf. +@item cf. +@itemx c.f. Short for ``confer'' in Latin, which means ``compare with'' or -``compare to''. +``compare to''. The second variant, ``c.f.'', is a widespread +misspelling. @anchor{Glossary---C-} @item @kbd{C-} @@ -192,7 +193,7 @@ other input events as well). @xref{User Input}. @item Character Folding Character folding means ignoring differences between similarly looking -characters, such as between @code{a}, and @code{@:a} and @code{@'a}. +characters, such as between @code{a}, and @code{@"a} and @code{@'a}. Emacs performs character folding by default in text search. @xref{Lax Search}. @@ -225,14 +226,16 @@ text to or from a variety of coding systems when reading or writing it. @xref{Coding Systems}. @item Command -A command is a Lisp function specially defined to be able to serve as a -key binding in Emacs. When you type a key sequence (q.v.), its -binding (q.v.@:) is looked up in the relevant keymaps (q.v.@:) to find -the command to run. @xref{Commands}. +A command is a Lisp function specially defined to be able to serve as +a key binding in Emacs or to be invoked by its name +(@pxref{Glossary---Command Name}). When you type a key sequence +(q.v.), its binding (q.v.@:) is looked up in the relevant keymaps +(q.v.@:) to find the command to run. @xref{Commands}. @item Command History @xref{Glossary---Minibuffer History}. +@anchor{Glossary---Command Name} @item Command Name A command name is the name of a Lisp symbol that is a command (@pxref{Commands}). You can invoke any command by its name using @@ -255,7 +258,8 @@ Compilation is the process of creating an executable program from source code. Emacs has commands for compiling files of Emacs Lisp code (@pxref{Byte Compilation,,, elisp, the Emacs Lisp Reference Manual}) and programs in C and other languages -(@pxref{Compilation}). +(@pxref{Compilation}). Byte-compiled Emacs Lisp code loads and +executes faster. @item Complete Key A complete key is a key sequence that fully specifies one action to be @@ -875,7 +879,7 @@ A local value of a variable (q.v.@:) applies to only one buffer. @xref{Locals}. @item @kbd{M-} -@kbd{M-} in the name of a character is an abbreviation for @key{Meta}, +@kbd{M-} in the name of a character is an abbreviation for @key{META}, one of the modifier keys that can accompany any character. @xref{User Input,M-}. @@ -933,15 +937,15 @@ a keyboard interface to navigate it. @xref{Menu Bars}. @item Meta Meta is the name of a modifier bit which you can use in a command -character. To enter a meta character, you hold down the @key{Meta} +character. To enter a meta character, you hold down the @key{META} key while typing the character. We refer to such characters with names that start with @kbd{Meta-} (usually written @kbd{M-} for -short). For example, @kbd{M-<} is typed by holding down @key{Meta} +short). For example, @kbd{M-<} is typed by holding down @key{META} and at the same time typing @kbd{<} (which itself is done, on most terminals, by holding down @key{SHIFT} and typing @kbd{,}). @xref{User Input,Meta}. -On some terminals, the @key{Meta} key is actually labeled @key{Alt} +On some terminals, the @key{META} key is actually labeled @key{Alt} or @key{Edit}. @item Meta Character @@ -1139,8 +1143,8 @@ one corner and putting the mark at the diagonally opposite corner. A recursive editing level is a state in which part of the execution of a command involves asking you to edit some text. This text may or may not be the same as the text to which the command was applied. -The mode line indicates recursive editing levels with square brackets -(@samp{[} and @samp{]}). @xref{Recursive Edit}. +The mode line (q.v.@:) indicates recursive editing levels with square +brackets (@samp{[} and @samp{]}). @xref{Recursive Edit}. @item Redisplay Redisplay is the process of correcting the image on the screen to @@ -1168,7 +1172,7 @@ digits. @xref{Regexps}. @item Remote File A remote file is a file that is stored on a system other than your own. Emacs can access files on other computers provided that they are -connected to the same network as your machine, and (obviously) that +reachable from your machine over the network, and (obviously) that you have a supported method to gain access to those files. @xref{Remote Files}. @@ -1190,8 +1194,9 @@ newline into the text. It is also used to terminate most arguments read in the minibuffer (q.v.). @xref{User Input,Return}. @item Reverting -Reverting means returning to the original state. Emacs lets you -revert a buffer by re-reading its file from disk. @xref{Reverting}. +Reverting means returning to the original state. For example, Emacs +lets you revert a buffer by re-reading its file from disk. +@xref{Reverting}. @c Seems too obvious, also there is nothing special about the format @c these days. @@ -1363,6 +1368,7 @@ Emacs does not make a termscript file unless you tell it to. @xref{Bugs}. @item Text + ``Text'' has two meanings (@pxref{Text}): @itemize @bullet @@ -1371,6 +1377,7 @@ Data consisting of a sequence of characters, as opposed to binary numbers, executable programs, and the like. The basic contents of an Emacs buffer (aside from the text properties, q.v.@:) are always text in this sense. + @item Data consisting of written human language (as opposed to programs), or following the stylistic conventions of human language. @@ -1473,7 +1480,7 @@ where they can be edited. @xref{Visiting}. @item Whitespace Whitespace is any run of consecutive formatting characters (space, -tab, newline, and backspace). +tab, newline, backspace, etc.). @item Widening Widening is removing any restriction (q.v.@:) on the current buffer; diff --git a/doc/emacs/macos.texi b/doc/emacs/macos.texi index 28a5f9041ab..bf37d67b642 100644 --- a/doc/emacs/macos.texi +++ b/doc/emacs/macos.texi @@ -34,8 +34,8 @@ Support}), but we hope to improve it in the future. @node Mac / GNUstep Basics @section Basic Emacs usage under macOS and GNUstep - By default, the @key{alt} and @key{option} keys are the same as -@key{Meta}. The Mac @key{Cmd} key is the same as @key{Super}, and + By default, the @key{Alt} and @key{Option} keys are the same as +@key{META}. The Mac @key{Cmd} key is the same as @key{Super}, and Emacs provides a set of key bindings using this modifier key that mimic other Mac / GNUstep applications (@pxref{Mac / GNUstep Events}). You can change these bindings in the usual way (@pxref{Key Bindings}). @@ -43,7 +43,7 @@ can change these bindings in the usual way (@pxref{Key Bindings}). @vindex ns-alternate-modifier @vindex ns-right-alternate-modifier The variable @code{ns-right-alternate-modifier} controls the -behavior of the right @key{alt} and @key{option} keys. These keys +behavior of the right @key{Alt} and @key{Option} keys. These keys behave like the left-hand keys if the value is @code{left} (the default). A value of @code{control}, @code{meta}, @code{alt}, @code{super}, or @code{hyper} makes them behave like the corresponding diff --git a/doc/emacs/mark.texi b/doc/emacs/mark.texi index 7cb48a67e7c..0ffa9f74ac6 100644 --- a/doc/emacs/mark.texi +++ b/doc/emacs/mark.texi @@ -260,7 +260,7 @@ change the variable @code{use-empty-active-region} to @code{t}. @vindex delete-active-region As described in @ref{Erasing}, the @key{DEL} -(@code{backward-delete-char}) and @key{delete} +(@code{backward-delete-char}) and @key{Delete} (@code{delete-forward-char}) commands also act this way. If the mark is active, they delete the text in the region. (As an exception, if you supply a numeric argument @var{n}, where @var{n} is not one, these diff --git a/doc/emacs/msdos-xtra.texi b/doc/emacs/msdos-xtra.texi index 541e29aa25f..39d003c453c 100644 --- a/doc/emacs/msdos-xtra.texi +++ b/doc/emacs/msdos-xtra.texi @@ -84,7 +84,7 @@ a running command and for emergency escape @vindex dos-super-key @vindex dos-hyper-key The PC keyboard maps use the left @key{Alt} key as the @key{META} key. -You have two choices for emulating the @key{SUPER} and @key{HYPER} keys: +You have two choices for emulating the @key{SUPER} and @key{Hyper} keys: choose either the right @key{Ctrl} key or the right @key{Alt} key by setting the variables @code{dos-hyper-key} and @code{dos-super-key} to 1 or 2 respectively. If neither @code{dos-super-key} nor diff --git a/doc/emacs/msdos.texi b/doc/emacs/msdos.texi index 9c47f47a736..032e82eb621 100644 --- a/doc/emacs/msdos.texi +++ b/doc/emacs/msdos.texi @@ -575,7 +575,7 @@ keys (it converts lower-case characters to their upper-case variants). However, if you set the variable @code{w32-capslock-is-shiftlock} to a non-@code{nil} value, the @key{CapsLock} key will affect non-character keys as well, as if you -pressed the @key{Shift} key while typing the non-character key. +pressed the @key{SHIFT} key while typing the non-character key. @vindex w32-enable-caps-lock If the variable @code{w32-enable-caps-lock} is set to a @code{nil} diff --git a/doc/emacs/mule.texi b/doc/emacs/mule.texi index 4989982eca0..dc80bc92172 100644 --- a/doc/emacs/mule.texi +++ b/doc/emacs/mule.texi @@ -1841,7 +1841,33 @@ sometimes jump when point traverses reordered bidirectional text. Similarly, a highlighted region covering a contiguous range of character positions may look discontinuous if the region spans reordered text. This is normal and similar to the behavior of other -programs that support bidirectional text. If you set -@code{visual-order-cursor-movement} to a non-@code{nil} value, cursor -motion by the arrow keys follows the visual order on screen -(@pxref{Moving Point, visual-order movement}). +programs that support bidirectional text. + +@kindex RIGHT@r{, and bidirectional text} +@kindex LEFT@r{, and bidirectional text} +@findex right-char@r{, and bidirectional text} +@findex left-char@r{, and bidirectional text} + Cursor motion commands bound to arrow keys, such as @key{LEFT} and +@kbd{C-@key{RIGHT}}, are sensitive to the base direction of the +current paragraph. In a left-to-right paragraph, commands bound to +@key{RIGHT} with or without modifiers move @emph{forward} through +buffer text, but in a right-to-left paragraph they move +@emph{backward} instead. This reflects the fact that in a +right-to-left paragraph buffer positions predominantly increase when +moving to the left on display. + + When you move out of a paragraph, the meaning of the arrow keys +might change if the base direction of the preceding or the following +paragraph is different from the paragraph out of which you moved. +When that happens, you need to adjust the arrow key you press to the +new base direction. + +@vindex visual-order-cursor-movement +@cindex cursor, visual-order motion + By default, @key{LEFT} and @key{RIGHT} move in the logical order, +but if @code{visual-order-cursor-movement} is non-@code{nil}, these +commands move to the character that is, correspondingly, to the left +or right of the current screen position, moving to the next or +previous screen line as appropriate. Note that this might potentially +move point many buffer positions away, depending on the surrounding +bidirectional context. -- 2.11.4.GIT