bug#50926: Light edits to the Emacs Manual (screen.texi)

[Stefan Kangas]

Severity: wishlist

I'm proof-reading some sections of the Emacs manual in preparation of
Emacs 28, and I noticed some parts that are too wordy, explains things
in a convoluted way, or explains things that do not need explaining.
I will not attempt to enumerate all types of edits as I think it is
better to look at each edit concretely.

Please find below the resulting patch.  It mostly amounts to taking
out unnecessary words, or shortening and simplifying an overly
complicated explanation.  (To make reviewing easier, I have refrained
from re-filling any paragraphs.)

I would like to see how welcome this type of work is before attempting
similar editing in other sections of the manual, which I hope to do as
time and energy allows.

Finally, I'm also happy to report that I have found almost no
mistakes, besides one obvious one where the text incorrectly says "in
the next paragraph" (fixed in the patch).

diff --git a/doc/emacs/screen.texi b/doc/emacs/screen.texi
index 2ff808e040..1545dec9a2 100644
--- a/doc/emacs/screen.texi
+++ b/doc/emacs/screen.texi
@@ -28,7 +28,8 @@ Screen
 manual, we will use the word ``window'' in this sense.  Graphical
 display systems commonly use the word ``window'' with a different
 meaning; but, as stated above, we refer to those graphical windows
-as ``frames''.
+as ``frames''.  (The reasons for this are historical and beyond the
+scope of this chapter.)

   An Emacs window is where the @dfn{buffer}---the text or other
 graphics you are editing or viewing---is displayed.  On a graphical
@@ -49,10 +50,10 @@ Screen
 cursor (usually a hollow box).  On a text terminal, there is only one
 cursor, which is shown in the selected window.  The buffer displayed
 in the selected window is called the @dfn{current buffer}, and it is
-where editing happens.  Most Emacs commands implicitly apply to the
-current buffer; the text displayed in unselected windows is mostly
-visible for reference.  If you use multiple frames on a graphical
-display, selecting a particular frame selects a window in that frame.
+where editing happens.  Most Emacs commands apply to the current
+buffer; unselected windows are mostly visible for reference.  If you
+use multiple frames on a graphical display, selecting a particular
+frame selects a window in that frame.

 @menu
 * Point::             The place in the text where editing commands operate.
@@ -67,7 +68,7 @@ Point
 @cindex cursor

   The cursor in the selected window shows the location where most
-editing commands take effect, which is called @dfn{point}@footnote{The
+editing commands take effect, which Emacs calls @dfn{point}@footnote{The
 term ``point'' comes from the character @samp{.}, which was the
 command in TECO (the language in which the original Emacs was written)
 for accessing the editing position.}.  Many Emacs commands move point
@@ -109,9 +110,8 @@ Echo Area
 pause for more than a second in the middle of a command.  Emacs then
 echoes all the characters of the command so far, to prompt you for the
 rest.  Once echoing has started, the rest of the command echoes
-immediately as you type it.  This behavior is designed to give
-confident users fast response, while giving hesitant users maximum
-feedback.
+immediately as you type it.  This behavior gives hesitant users
+maximum feedback.

 @cindex error message
 @cindex echo area message
@@ -119,16 +119,15 @@ Echo Area
 command cannot do its job.  Error messages may be accompanied by
 beeping or by flashing the screen.

-  Some commands display informative messages in the echo area to tell
-you what the command has done, or to provide you with some specific
+  Some commands display messages in the echo area to tell
+you what it has done, or some other specific
 information.  These @dfn{informative} messages, unlike error messages,
 are not accompanied with a beep or flash.  For example, @kbd{C-x =}
 (hold down @key{Ctrl} and type @kbd{x}, then let go of @key{Ctrl} and
 type @kbd{=}) displays a message describing the character at point,
 its position in the buffer, and its current column in the window.
 Commands that take a long time often display messages ending in
-@samp{...} while they are working (sometimes also indicating how much
-progress has been made, as a percentage), and add @samp{done} when
+@samp{...}, and add @samp{done} when
 they are finished.

 @cindex @file{*Messages*} buffer
@@ -136,25 +135,23 @@ Echo Area
 @cindex messages saved from echo area
 @vindex message-log-max
   Informative echo area messages are saved in a special buffer named
-@file{*Messages*}.  (We have not explained buffers yet; see
-@ref{Buffers}, for more information about them.)  If you miss a
-message that appeared briefly on the screen, you can switch to the
+@file{*Messages*}.  (Buffers are explained in the later section
+@ref{Buffers}.)  If you miss a
+message, you can switch to the
 @file{*Messages*} buffer to see it again.  The @file{*Messages*}
 buffer is limited to a certain number of lines, specified by the
-variable @code{message-log-max}.  (We have not explained variables
-either; see @ref{Variables}, for more information about them.)  Beyond
-this limit, one line is deleted from the beginning whenever a new
-message line is added at the end.
+variable @code{message-log-max}.  (See the section @ref{Variables}
+for more information on variables.)

   @xref{Display Custom}, for options that control how Emacs uses the
 echo area.

   The echo area is also used to display the @dfn{minibuffer}, a
 special window where you can input arguments to commands, such as the
-name of a file to be edited.  When the minibuffer is in use, the text
+name of a file.  When the minibuffer is in use, the text
 displayed in the echo area begins with a @dfn{prompt string}, and the
 active cursor appears within the minibuffer, which is temporarily
-considered the selected window.  You can always get out of the
+considered the selected window.  You can always leave the
 minibuffer by typing @kbd{C-g}.  @xref{Minibuffer}.

 @node Mode Line
@@ -165,12 +162,11 @@ Mode Line
   At the bottom of each window is a @dfn{mode line}, which describes
 what is going on in the current buffer.  When there is only one
 window, the mode line appears right above the echo area; it is the
-next-to-last line in the frame.  On a graphical display, the mode line
-is drawn with a 3D box appearance.  Emacs also usually draws the mode
+next-to-last line in the frame.  Emacs usually draws the mode
 line of the selected window with a different color from that of
-unselected windows, in order to make it stand out.
+unselected windows, to make it stand out.

-  The text displayed in the mode line has the following format:
+  The text displayed in the mode line has this format:

 @example
  @var{cs}:@var{ch}-@var{fr}  @var{buf}      @var{pos} @var{line}
(@var{major} @var{minor})
@@ -178,26 +174,24 @@ Mode Line

 @noindent
 On a text terminal, this text is followed by a series of dashes
-extending to the right edge of the window.  These dashes are omitted
-on a graphical display.
+extending to the right edge of the window.

 The @var{cs} string and the colon character after it describe the
 character set and newline convention used for the current buffer.
-Normally, Emacs automatically handles these settings for you, but it
-is sometimes useful to have this information.
+These settings are normally handled automatically for you.

   @var{cs} describes the character set of the text in the buffer
 (@pxref{Coding Systems}).  If it is a dash (@samp{-}), that indicates
 no special character set handling (with the possible exception of
-end-of-line conventions, described in the next paragraph).  @samp{=}
+end-of-line conventions, described below).  @samp{=}
 means no conversion whatsoever, and is usually used for files
 containing non-textual data.  Other characters represent various
 @dfn{coding systems}---for example, @samp{1} represents ISO Latin-1.

   On a text terminal, @var{cs} is preceded by two additional
 characters that describe the coding systems for keyboard input and
-terminal output.  Furthermore, if you are using an input method,
-@var{cs} is preceded by a string that identifies the input method
+terminal output.  If you are using an input method,
+@var{cs} is also preceded by a string that identifies it
 (@pxref{Input Methods}).

 @cindex end-of-line convention, mode-line indication
@@ -208,10 +202,10 @@ Mode Line
 sometimes used.  The MS-DOS convention uses a carriage return
 character followed by a linefeed character; when editing such
 files, the colon changes to either a backslash (@samp{\}) or
-@samp{(DOS)}, depending on the operating system.  Another convention,
-employed by older Macintosh systems, uses a carriage return
-character instead of a newline; when editing such files, the colon
-changes to either a forward slash (@samp{/}) or @samp{(Mac)}.  On some
+@samp{(DOS)}, depending on the operating system.
+Old Macintosh systems use a carriage return
+character instead of a newline; when editing such files,
+this is indicated by (@samp{/}) or @samp{(Mac)}.  On some
 systems, Emacs displays @samp{(Unix)} instead of the colon for files
 that use newline as the line separator.

@@ -235,25 +229,25 @@ Mode Line
 only on text terminals.  The initial frame's name is @samp{F1}.

   @var{buf} is the name of the buffer displayed in the window.
-Usually, this is the same as the name of a file you are editing.
+This is usually the same as the name of a file you are editing.
 @xref{Buffers}.

-  @var{pos} tells you whether there is additional text above the top
-of the window, or below the bottom.  If your buffer is small and all
-of it is visible in the window, @var{pos} is @samp{All}.  Otherwise,
-it is @samp{Top} if you are looking at the beginning of the buffer,
+  @var{pos} tells you whether there is additional text above or below the
+visible portion of the buffer.  If the entire buffer
+is visible in the window, @var{pos} is @samp{All}.
+It is @samp{Top} if you are looking at the beginning of the buffer,
 @samp{Bot} if you are looking at the end of the buffer, or
 @samp{@var{nn}%}, where @var{nn} is the percentage of the buffer above
 the top of the window.  With Size Indication mode, you can display the
 size of the buffer as well.  @xref{Optional Mode Line}.

   @var{line} is the character @samp{L} followed by the line number at
-point.  (You can display the current column number too, by turning on
+point.  (You can display the current column number by turning on
 Column Number mode.  @xref{Optional Mode Line}.)

   @var{major} is the name of the @dfn{major mode} used in the buffer.
 A major mode is a principal editing mode for the buffer, such as Text
-mode, Lisp mode, C mode, and so forth.  @xref{Major Modes}.  Some
+mode, Lisp mode, C mode, and so on.  @xref{Major Modes}.  Some
 major modes display additional information after the major mode name.
 For example, Compilation buffers and Shell buffers display the status
 of the subprocess.
@@ -276,30 +270,28 @@ Mode Line
 editing levels affect Emacs globally, such square brackets appear in
 the mode line of every window.  @xref{Recursive Edit}.

-  You can change the appearance of the mode line as well as the format
-of its contents.  @xref{Optional Mode Line}.  In addition, the mode
-line is mouse-sensitive; clicking on different parts of the mode line
-performs various commands.  @xref{Mode Line Mouse}.  Also, hovering
-the mouse pointer above mouse-sensitive portions of the mode line
+  You can change the appearance and format of the mode line.
+@xref{Optional Mode Line}.  Finally, you can click
+on different parts of the mode line to
+perform various commands.  @xref{Mode Line Mouse}.  Hovering
+the mouse pointer above some portions of the mode line
 shows tooltips (@pxref{Tooltips}) with information about commands you
-can invoke by clicking on the mode line.
+can invoke by clicking.

 @node Menu Bar
 @section The Menu Bar
 @cindex menu bar

-  Each Emacs frame normally has a @dfn{menu bar} at the top which you
-can use to perform common operations.  There's no need to list them
-here, as you can more easily see them yourself.
+  Each Emacs frame normally has a @dfn{menu bar} at the top that you
+can use to perform common operations.

   On a display that supports a mouse, you can use the mouse to choose a
-command from the menu bar.  An arrow on the right edge of a menu item
-means it leads to a subsidiary menu, or @dfn{submenu}.  A @samp{...}
+command from the menu bar or a @dfn{submenu}.  A @samp{...}
 at the end of a menu item means that the command will prompt you for
 further input before it actually does anything.

-  Some of the commands in the menu bar have ordinary key bindings as
-well; if so, a key binding is shown after the item itself.  To view
+  If a command in the menu bar have an ordinary key binding,
+it is shown after the item.  To view
 the full command name and documentation for a menu item, type
 @kbd{C-h k}, and then select the menu bar with the mouse in the usual
 way (@pxref{Key Help}).
@@ -307,21 +299,20 @@ Menu Bar
 @kindex F10
 @findex menu-bar-open
 @cindex menu bar access using keyboard
-  Instead of using the mouse, you can also invoke the first menu bar
-item by pressing @key{F10} (to run the command @code{menu-bar-open}).
+  You can invoke the first menu bar
+item with your keyboard by pressing @key{F10} (to run the command
@code{menu-bar-open}).
 You can then navigate the menus with the arrow keys or with @kbd{C-b},
 @kbd{C-f} (left/right), @kbd{C-p}, and @kbd{C-n} (up/down).  To
 activate a selected menu item, press @key{RET}; to cancel menu
 navigation, press @kbd{C-g} or @kbd{@key{ESC} @key{ESC} @key{ESC}}.
-(However, note that when Emacs was built with a GUI toolkit, the menus
-are drawn and controlled by the toolkit, and the key sequences to
-cancel menu navigation might be different from the above description.)
+(Note that Emacs is normally built with a GUI toolkit that has its
own commands to
+cancel menu navigation.)

 @kindex M-`
 @findex tmm-menubar
 @vindex tty-menu-open-use-tmm
   On a text terminal, you can optionally access the menu-bar menus in
-the echo area.  To this end, customize the variable
+the echo area.  To enable this, customize the variable
 @code{tty-menu-open-use-tmm} to a non-@code{nil} value.  Then typing
 @key{F10} will run the command @code{tmm-menubar} instead of dropping
 down the menu.  (You can also type @kbd{M-`}, which always invokes