GNU bug report logs - #50926
Light edits to the Emacs Manual (screen.texi)

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 50926 in the body.
You can then email your comments to 50926 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: bug-gnu-emacs <at> gnu.org
Subject: Light edits to the Emacs Manual (screen.texi)
Date: Fri, 1 Oct 2021 01:51:04 +0200

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

Message #8 received at 50926 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Stefan Kangas <stefan <at> marxist.se>, "50926 <at> debbugs.gnu.org"
 <50926 <at> debbugs.gnu.org>
Subject: RE: [External] : bug#50926: Light edits to the Emacs Manual
 (screen.texi)
Date: Fri, 1 Oct 2021 01:50:07 +0000

Some quick, minor copy-edit suggestions -

> -  Some commands display informative messages in the echo area to tell
> -you what the command has done,
> +  Some commands display messages in the echo area to tell
> +you what it has done,

Some commands...what they have done.

> , 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}.

Drop the ", and so *".  It's redundant with "such as".

> +@xref{Optional Mode Line}.  Finally, you can click
> +on different parts of the mode line

Drop "on".

> Hovering
> +the mouse pointer above...shows...by clicking

"Place the mouse pointer on...to show...
by clicking there"

or

"Move the mouse pointer to...to show...
by clicking there"

It's not a hummingbird.  And "above" can
mislead as in toward the top of the screen.

(Informally I use "mouseover" as a verb,
but I'm not suggesting that for Emacs.)

-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{...}

That's wrong, IMO.  The menu-bar has menus, which can
have submenus.  The menu-bar doesn't have submenus.

+  If a command in the menu bar have an ordinary key binding

"has", not "have"

-  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}).

"menu-bar", not "menu bar" if used as an
adjective before the noun.

But what is meant by "the first menu bar item"?
The menu bar doesn't have items.  It has menus.
And what's meant by "first" here?  Must have
something to do with invoking (first command
invoked?), but it's not clear to me what this
is trying to say.

And you can drop "with your keyboard" here:

  with your keyboard by pressing @key{F10}

HTH.  Feel free to ignore, of course.

Message #11 received at 50926 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 50926 <at> debbugs.gnu.org
Subject: Re: bug#50926: Light edits to the Emacs Manual (screen.texi)
Date: Fri, 01 Oct 2021 10:20:10 +0300

> From: Stefan Kangas <stefan <at> marxist.se>
> Date: Fri, 1 Oct 2021 01:51:04 +0200
> 
> 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.

Thanks.  The most important job of reviewing the manuals before a
major release is to find mistakes and important omissions.  These
happen because, even when we do accompany code changes with
documentation changes, we only do that in the immediate places where
the respective features are mentioned, not where those changes are
referenced indirectly, let alone implicitly.  For example, some new
feature could affect our recommendations how to do some job, because
it enables yet another, perhaps much more efficient, way of doing that
job.  Such places are hard to find without reading the manual in its
entirety, and thus many times become outdated.

> 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).

That is good to know, but I find it hard to believe, based on my
experience.  How much of the Emacs manual did you proof-read? which
chapters?  The patch is for just a single Texinfo file.

As for the specific changes you propose: I find many of them to be of
personal stylistic preference nature.  In some cases, your proposals
actually lose useful contents; in others, I agree with a rewording;
still others strike me as being less clear after the change.  See the
specific comments below.

>  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.)

This is a distraction here, IMO.  If we want to say this, it belongs
to the Glossary.

>  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.

Is this really better?  You omitted "implicitly", which IMO is
important (the current buffer is not explicitly mentioned in those
cases).  You omitted "text displayed", but that's the important part
of the window display.  I don't see any net improvements here.

>    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

This is for the worse, IMO.  If we want to avoid passive tense here,
we should say

  The cursor in the selected window shows the location, called
  @dfn{point}@footnote{...}, where most editing commands take effect ...

> -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.

Here you lost the reference to confident users, which is important.

> -  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

you replaced "the command" with "it", which made the text ambiguous:
"it" could refer to the echo area.

> -@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.

Here you removed a useful reference to progress reports.

> -@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}.)

here you replaced an active tense with passive tense, something we
generally avoid.

> -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

The text delete here is important, IMO.

> -considered the selected window.  You can always get out of the
> +considered the selected window.  You can always leave the

That's a minor stylistic change.  Both are okay, but what's wrong with
the original one, in your opinion?

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

Same comment here.

>  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.

This loses important information, IMO, because (assuming GUI frames
are more popular) the user will wonder why there are no dashes on
display.

> -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.

This loses an important remark, IMO.

> -end-of-line conventions, described in the next paragraph).  @samp{=}
> +end-of-line conventions, described below).  @samp{=}

This is OK, since "in the next paragraph" is inaccurate.

>    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

"Furthermore" facilitates readability, IMO.

> @@ -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.

Here you removed some words, which makes the text less clear, in that
it isn't clear when description of one EOL convention ends and that of
another begins.

> -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.

Personal stylistic preference?

> -  @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,

Here you remove words that you consider redundant, but the result is
potentially less clear to the readers, as it relies more on deduction
and reasoning instead of spelling things out.

>    @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}.)

The "too" part made a point of saying that the column is displayed in
addition to the line number; now this is open to speculation.

> -  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.

This is IMO for the worse: it loses important information about format
of stuff displayed on the mode line, uses "Finally" in what is not the
final aspect (there's the "hovering mouse" thing described
afterwards), and generally removes words that could make the text
harder to understand by non-native English speakers.

> -  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.

"That" instead of "which"?  And a sentence about why we don't list the
menu items dropped -- why?

>    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{...}

This loses the explanation of what is a submenu, which is not a good
idea where we use @dfn.

All in all, I don't think we need to squeeze every possible character
out of the text, that's not a hard requirement for a manual.  We
should strive to make the text clear and correct, even if that clarity
comes at a price of some extra text.  IOW, the text should be as short
as possible, but no shorter ;-)

Message #14 received at 50926 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: "50926 <at> debbugs.gnu.org" <50926 <at> debbugs.gnu.org>
Subject: Re: [External] : bug#50926: Light edits to the Emacs Manual
 (screen.texi)
Date: Fri, 1 Oct 2021 15:29:01 +0200

Drew Adams <drew.adams <at> oracle.com> writes:
>
> Some quick, minor copy-edit suggestions -
>
> > -  Some commands display informative messages in the echo area to tell
> > -you what the command has done,
> > +  Some commands display messages in the echo area to tell
> > +you what it has done,
>
> Some commands...what they have done.

Done.

> > , 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}.
>
> Drop the ", and so *".  It's redundant with "such as".

Done.

> > +@xref{Optional Mode Line}.  Finally, you can click
> > +on different parts of the mode line
>
> Drop "on".

Done.

> > Hovering
> > +the mouse pointer above...shows...by clicking
>
> "Place the mouse pointer on...to show...
> by clicking there"
>
> or
>
> "Move the mouse pointer to...to show...
> by clicking there"

Skipped this one, as it goes further than I'd like at this point.
Thanks, though.

> -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{...}
>
> That's wrong, IMO.  The menu-bar has menus, which can
> have submenus.  The menu-bar doesn't have submenus.

So the original text is wrong as well?

> +  If a command in the menu bar have an ordinary key binding
>
> "has", not "have"

Oops, a very obvious one.  Fixed.

> -  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}).
>
> "menu-bar", not "menu bar" if used as an
> adjective before the noun.

Hmm, I'll take your word for it.

> But what is meant by "the first menu bar item"?
> The menu bar doesn't have items.  It has menus.
> And what's meant by "first" here?  Must have
> something to do with invoking (first command
> invoked?), but it's not clear to me what this
> is trying to say.

This is a pre-existing confusion, right?

> And you can drop "with your keyboard" here:
>
>   with your keyboard by pressing @key{F10}

Good point, but on the other hand it is to contrast with usage with
the mouse so I think it's also fine to leave it.

> HTH.  Feel free to ignore, of course.

Much appreciated, thank you.

Message #17 received at 50926 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: "50926 <at> debbugs.gnu.org" <50926 <at> debbugs.gnu.org>
Subject: RE: [External] : bug#50926: Light edits to the Emacs Manual
 (screen.texi)
Date: Fri, 1 Oct 2021 17:13:46 +0000

> > -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{...}
> >
> > That's wrong, IMO.  The menu-bar has menus, which can
> > have submenus.  The menu-bar doesn't have submenus.
> 
> So the original text is wrong as well?

IMO, yes.

> > But what is meant by "the first menu bar item"?
> > The menu bar doesn't have items.  It has menus.
> > And what's meant by "first" here?  Must have
> > something to do with invoking (first command
> > invoked?), but it's not clear to me what this
> > is trying to say.
> 
> This is a pre-existing confusion, right?

If you mean that the existing text already presents
such confusion, then yes, IMO.

Message #20 received at 50926 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 50926 <at> debbugs.gnu.org
Subject: Re: bug#50926: Light edits to the Emacs Manual (screen.texi)
Date: Fri, 8 Oct 2021 20:40:42 -0400

Eli Zaretskii <eliz <at> gnu.org> writes:

> > 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).
>
> That is good to know, but I find it hard to believe, based on my
> experience.  How much of the Emacs manual did you proof-read? which
> chapters?  The patch is for just a single Texinfo file.

That referred to only this one texinfo files, I have found mistakes
elsewhere.

> As for the specific changes you propose: I find many of them to be of
> personal stylistic preference nature.  In some cases, your proposals
> actually lose useful contents; in others, I agree with a rewording;
> still others strike me as being less clear after the change.  See the
> specific comments below.

Thanks, specific comments is what is needed; it is often too hard to
explain what is meant in general.

> >  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.)
>
> This is a distraction here, IMO.  If we want to say this, it belongs
> to the Glossary.

OK, if it's fine with you then let's add it to the glossary instead.

> >  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.
>
> Is this really better?  You omitted "implicitly", which IMO is
> important (the current buffer is not explicitly mentioned in those
> cases).  You omitted "text displayed", but that's the important part
> of the window display.  I don't see any net improvements here.

I don't fully agree, but let's skip this change.

> >    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
>
> This is for the worse, IMO.  If we want to avoid passive tense here,
> we should say
>
>   The cursor in the selected window shows the location, called
>   @dfn{point}@footnote{...}, where most editing commands take effect ...

This change aims to highlight the fact that "point" is an Emacs specific
term.  I don't think the change you propose makes the text better, as
the key part of the sentence "where most editing commands take effect",
is moved too far from the beginning of the sentence.  This is sometimes
acceptable with such parenthetical remark in commas, but here I think it
doesn't help.

> > -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.
>
> Here you lost the reference to confident users, which is important.

Actually, this entire last sentence could just as well be removed, as it
doesn't add anything useful.

But if you insist, I think one way to say it is: "This behavior gives
fast response, but provides feedback when its needed."

> > -  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
>
> you replaced "the command" with "it", which made the text ambiguous:
> "it" could refer to the echo area.

I believe this is fixed by Drew's correction to use the plural "they":

  Some commands display messages in the echo area to tell
  you what they have done

> > -@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.
>
> Here you removed a useful reference to progress reports.

I removed it precisely because it is not useful and mostly dead weight.

Since you disagree, let's leave this change out.

> > -@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}.)
>
> here you replaced an active tense with passive tense, something we
> generally avoid.

Good catch.  Changed to:

    (We explain buffers in the later section @ref{Buffers}.)

> > -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
>
> The text delete here is important, IMO.

I disagree, it could for example be the name of a file to delete or a
myriad of other things that Emacs is prompting for.

> > -considered the selected window.  You can always get out of the
> > +considered the selected window.  You can always leave the
>
> That's a minor stylistic change.  Both are okay, but what's wrong with
> the original one, in your opinion?
>
> > -  The text displayed in the mode line has the following format:
> > +  The text displayed in the mode line has this format:
>
> Same comment here.

There is a rule of thumb that you will find in pretty much all writing
guides: Where you have a choice between a long word and a short one,
generally prefer the short one.

I'm fine either way in both of these cases, but I feel that my
suggestion is very slightly better.

> >  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.
>
> This loses important information, IMO, because (assuming GUI frames
> are more popular) the user will wonder why there are no dashes on
> display.

The sentence before it already says that this happens "on a text
terminals", so is there really any risk for confusion?

> > -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.
>
> This loses an important remark, IMO.

What is the important remark?  If you mean "it is sometimes useful to
have this information", it is IMO not very important as this could be
said about almost any information that Emacs shows on the screen.
If the information is not useful, at least sometimes, we wouldn't show
it, right?

> >    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
>
> "Furthermore" facilitates readability, IMO.

This is done more directly and better by my added "also", but given that
you disagree, let's just keep the original.

> > @@ -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.
>
> Here you removed some words, which makes the text less clear, in that
> it isn't clear when description of one EOL convention ends and that of
> another begins.

I think my edit is fine in this regard, and it would be unfortunate for
this section if we left it out.  Removing all those words and extra
markers make the text more direct and easier to understand.

Perhaps we could change the sentence to: "On old Macintosh systems the
convention is to use a carriage return character instead of a newline
..."

> > -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.
>
> Personal stylistic preference?

Not sure what you mean by "personal preference" here.  This is indeed a
stylistic change, and a very minor one at that, that I believe makes the
text more direct.

But let's leave it out, as it is too minor to be worth discussing.

> > -  @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,
>
> Here you remove words that you consider redundant, but the result is
> potentially less clear to the readers, as it relies more on deduction
> and reasoning instead of spelling things out.

I don't see that this is less clear, IMO it more clear precisely because
it is shorter.

The original is not very well written.  For example, it excruciatingly
explains things like "if the buffer is small", as if the reader doesn't
already know that you can only fit a limited amount of text on the
screen.

I think at the very least here, we should remove the words "your buffer
is small and".

> >    @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}.)
>
> The "too" part made a point of saying that the column is displayed in
> addition to the line number; now this is open to speculation.

Good point, let's leave this change out.

> > -  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.
>
> This is IMO for the worse: it loses important information about format
> of stuff displayed on the mode line, uses "Finally" in what is not the
> final aspect (there's the "hovering mouse" thing described
> afterwards), and generally removes words that could make the text
> harder to understand by non-native English speakers.

You make a good point regarding "Finally", I suggest changing it to "In
addition".

Other than that, I don't think I see that this change is for the worse.

What important information is lost?  Which words do you think should be
kept?

> > -  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.
>
> "That" instead of "which"?

I think it should be "which" here, upon closer consideration.  "That"
introduces a confusion.  Sorry for the noise.

> And a sentence about why we don't list the
> menu items dropped -- why?

Because why would the reader expect us to list the options in a menu in
the manual?  No one does that these days.  So there is no need to
specifically mention it, as if it is some unusual thing we are doing.

We also don't list the contents of `C-h b', and many other things
besides.

> >    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{...}
>
> This loses the explanation of what is a submenu, which is not a good
> idea where we use @dfn.

A "submenu" is scarcely something that needs explaining, nor the
convention to have a right arrow to indicate them (that happens in all
software these days).

I would propose removing @dfn:

       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 submenu.  A @samp{...}

[Perhaps we want to change "menu bar" to "menu" here, as the former is
somewhat ambiguous (the commands are in the drop-down menu, not in the
menu "bar").]

> All in all, I don't think we need to squeeze every possible character
> out of the text, that's not a hard requirement for a manual.  We
> should strive to make the text clear and correct, even if that clarity
> comes at a price of some extra text.  IOW, the text should be as short
> as possible, but no shorter ;-)

I agree with this final sentiment.

IME, the problem is that the devil is in the details; even when you
accept the exact same set of principles you still end up with different
opinions.  :-)

Thanks for the review.  I have a reworked version of the patch on my
laptop that I will send separately as soon as I can.

Message #23 received at 50926 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 50926 <at> debbugs.gnu.org
Subject: Re: bug#50926: Light edits to the Emacs Manual (screen.texi)
Date: Sat, 09 Oct 2021 10:21:10 +0300

> From: Stefan Kangas <stefan <at> marxist.se>
> Date: Fri, 8 Oct 2021 20:40:42 -0400
> Cc: 50926 <at> debbugs.gnu.org
> 
> > >    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
> >
> > This is for the worse, IMO.  If we want to avoid passive tense here,
> > we should say
> >
> >   The cursor in the selected window shows the location, called
> >   @dfn{point}@footnote{...}, where most editing commands take effect ...
> 
> This change aims to highlight the fact that "point" is an Emacs specific
> term.  I don't think the change you propose makes the text better, as
> the key part of the sentence "where most editing commands take effect",
> is moved too far from the beginning of the sentence.  This is sometimes
> acceptable with such parenthetical remark in commas, but here I think it
> doesn't help.

I'm okay with leaving the original text unaltered, it's not bad at
all.

> > > -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.
> >
> > Here you lost the reference to confident users, which is important.
> 
> Actually, this entire last sentence could just as well be removed, as it
> doesn't add anything useful.
> 
> But if you insist, I think one way to say it is: "This behavior gives
> fast response, but provides feedback when its needed."

Fine with me, but I'm curious what did you see wrong with the original
text.

> > > -  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
> >
> > you replaced "the command" with "it", which made the text ambiguous:
> > "it" could refer to the echo area.
> 
> I believe this is fixed by Drew's correction to use the plural "they":

No, it isn't, because "they" could refer to the "informative
messages".

What's wrong with the original text?

> > > -@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}.)
> >
> > here you replaced an active tense with passive tense, something we
> > generally avoid.
> 
> Good catch.  Changed to:
> 
>     (We explain buffers in the later section @ref{Buffers}.)

OK.

> > > -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
> >
> > The text delete here is important, IMO.
> 
> I disagree, it could for example be the name of a file to delete or a
> myriad of other things that Emacs is prompting for.

The text before the hunk says "such as", so this is just an example.
Why is the text you want to delete a problem?

> > > -considered the selected window.  You can always get out of the
> > > +considered the selected window.  You can always leave the
> >
> > That's a minor stylistic change.  Both are okay, but what's wrong with
> > the original one, in your opinion?
> >
> > > -  The text displayed in the mode line has the following format:
> > > +  The text displayed in the mode line has this format:
> >
> > Same comment here.
> 
> There is a rule of thumb that you will find in pretty much all writing
> guides: Where you have a choice between a long word and a short one,
> generally prefer the short one.

I don't think that rule should be applied to each and every situation
where we could find a slightly shorter wording.  This is a book for
humans to read, so it doesn't need to be as short as possible.

> > >  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.
> >
> > This loses important information, IMO, because (assuming GUI frames
> > are more popular) the user will wonder why there are no dashes on
> > display.
> 
> The sentence before it already says that this happens "on a text
> terminals", so is there really any risk for confusion?

Yes, because you actually force the reader to solve a riddle: since
the text said "text terminals", it means it never happens on other
types of terminals.  Riddles in documentation are not a good idea,
because they leave the reader wondering whether he or she understood
correctly.

> > > -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.
> >
> > This loses an important remark, IMO.
> 
> What is the important remark?  If you mean "it is sometimes useful to
> have this information", it is IMO not very important as this could be
> said about almost any information that Emacs shows on the screen.
> If the information is not useful, at least sometimes, we wouldn't show
> it, right?

I think you misunderstand what "handles automatically" refers to.  It
refers to the automatic detection of file's encoding and EOL format.
These _can_ decide incorrectly in some rare cases, and in those cases
it _is_ important to see what Emacs decided.  So maybe we should _add_
some text there to make this intent more clear, because the fact you
misunderstood it might mean it is too terse.

> > > @@ -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.
> >
> > Here you removed some words, which makes the text less clear, in that
> > it isn't clear when description of one EOL convention ends and that of
> > another begins.
> 
> I think my edit is fine in this regard, and it would be unfortunate for
> this section if we left it out.  Removing all those words and extra
> markers make the text more direct and easier to understand.
> 
> Perhaps we could change the sentence to: "On old Macintosh systems the
> convention is to use a carriage return character instead of a newline
> ..."

Please tell what's wrong with the original text, and let's take it
from there.  It basically says something like "one conventions is
... another conventions is ...", and I see nothing wrong with this
style.

> > > -  @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,
> >
> > Here you remove words that you consider redundant, but the result is
> > potentially less clear to the readers, as it relies more on deduction
> > and reasoning instead of spelling things out.
> 
> I don't see that this is less clear, IMO it more clear precisely because
> it is shorter.
> 
> The original is not very well written.  For example, it excruciatingly
> explains things like "if the buffer is small", as if the reader doesn't
> already know that you can only fit a limited amount of text on the
> screen.
> 
> I think at the very least here, we should remove the words "your buffer
> is small and".

The details in such detailed descriptions are important, IME.  They
prevent misunderstandings and confusion, especially when the reader is
not a native English speaker.  For example, the "buffer is small" part
prevents the reader from having to think about a case where it could
happen that all of the buffer's contents is entirely visible in a
single window-full.  I see nothing wrong with the original text.

> > > -  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.
> >
> > This is IMO for the worse: it loses important information about format
> > of stuff displayed on the mode line, uses "Finally" in what is not the
> > final aspect (there's the "hovering mouse" thing described
> > afterwards), and generally removes words that could make the text
> > harder to understand by non-native English speakers.
> 
> You make a good point regarding "Finally", I suggest changing it to "In
> addition".
> 
> Other than that, I don't think I see that this change is for the worse.
> 
> What important information is lost?  Which words do you think should be
> kept?

I simply see no problem with the original text.

We shouldn't make changes where nothing is wrong, just because the
same content could be expressed in different words.  People labored on
this text, and when the results are fine, we should leave their
contributions intact, out of respect to their labor if nothing else.
Making changes that perform unnecessary rewording just because we can
is not TRT, IMO.

> > > -  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.
> >
> > "That" instead of "which"?
> 
> I think it should be "which" here, upon closer consideration.  "That"
> introduces a confusion.  Sorry for the noise.
> 
> > And a sentence about why we don't list the
> > menu items dropped -- why?
> 
> Because why would the reader expect us to list the options in a menu in
> the manual?

They might.  They might ask themselves why everything else is
displayed in detail, whereas this one isn't.  It's a short sentence,
and it isn't wrong.  Someone who wrote this stuff decided it could be
useful; why should we overrule their decision?

> We also don't list the contents of `C-h b', and many other things
> besides.

You cannot usefully describe what "C-h b" displays, because it depends
on the major mode.

> > >    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{...}
> >
> > This loses the explanation of what is a submenu, which is not a good
> > idea where we use @dfn.
> 
> A "submenu" is scarcely something that needs explaining, nor the
> convention to have a right arrow to indicate them (that happens in all
> software these days).
> 
> I would propose removing @dfn:
> 
>        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 submenu.  A @samp{...}
> 
> [Perhaps we want to change "menu bar" to "menu" here, as the former is
> somewhat ambiguous (the commands are in the drop-down menu, not in the
> menu "bar").]

I see no reason to change anything there.  The text is correct,
explains the important parts and conventions of a menu, and is concise
enough.  Maybe you are thinking about GUI menus, but this also
describes what TTY menus and menus on non-toolkit X builds look like,
where it could be less obvious.

> > All in all, I don't think we need to squeeze every possible character
> > out of the text, that's not a hard requirement for a manual.  We
> > should strive to make the text clear and correct, even if that clarity
> > comes at a price of some extra text.  IOW, the text should be as short
> > as possible, but no shorter ;-)
> 
> I agree with this final sentiment.
> 
> IME, the problem is that the devil is in the details; even when you
> accept the exact same set of principles you still end up with different
> opinions.  :-)

And that is fine.  We shouldn't impose a single set of opinions on the
manual.  The same ideas can be correctly and usefully conveyed using
different styles; we shouldn't override the stylistic decisions of
those who wrote the manual text just because we would pick up a
different style.

More importantly, I think our work on the manuals for the Emacs 28
release would benefit much more from looking for inaccuracies, missed
documentation of new features, and other factual issues caused by
Emacs development, then by trying to "fix" minor stylistic issues or
reword text that is fine as it is.

Thanks.

Message #26 received at 50926 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>, Stefan Kangas <stefan <at> marxist.se>
Cc: "50926 <at> debbugs.gnu.org" <50926 <at> debbugs.gnu.org>
Subject: RE: [External] : bug#50926: Light edits to the Emacs Manual
 (screen.texi)
Date: Sat, 9 Oct 2021 16:41:50 +0000

> > > > -  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
> > >
> > > you replaced "the command" with "it", which made the text
> > > ambiguous: "it" could refer to the echo area.
> >
> > I believe this is fixed by Drew's correction to use the plural
> > "they":
> 
> No, it isn't, because "they" could refer to the "informative
> messages".

Only if a reader doesn't understand that it
would make no sense to display a message to tell
you what that message itself has done.

(That might be amusing, however...)

And in that case I expect our docs will present
much more serious problems for that reader.)

But if you really want to be sure such a reader
doesn't get confused, then say "those commands"
instead of "they".

The point is that the messages tell you what the
commands _have_ done, not what "the command" has
done.

> >-  Each Emacs frame normally has a @dfn{menu bar} 

FWIW, I think "normally" is inappropriate here.
It's not about normality or abnormality.

I suggest something like "by default" (or
"usually" or "typically", if that's what you
really mean).

Message #29 received at 50926 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 50926 <at> debbugs.gnu.org, stefan <at> marxist.se
Subject: Re: [External] : bug#50926: Light edits to the Emacs Manual
 (screen.texi)
Date: Sat, 09 Oct 2021 19:54:01 +0300

> From: Drew Adams <drew.adams <at> oracle.com>
> CC: "50926 <at> debbugs.gnu.org" <50926 <at> debbugs.gnu.org>
> Date: Sat, 9 Oct 2021 16:41:50 +0000
> 
> > >-  Each Emacs frame normally has a @dfn{menu bar} 
> 
> FWIW, I think "normally" is inappropriate here.

That's our usual style, it means the same as "by default".  We use
both interchangeable, and I see no reason to change that.

Message #32 received at 50926 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: "50926 <at> debbugs.gnu.org" <50926 <at> debbugs.gnu.org>,
 "stefan <at> marxist.se" <stefan <at> marxist.se>
Subject: RE: [External] : bug#50926: Light edits to the Emacs Manual
 (screen.texi)
Date: Sat, 9 Oct 2021 17:18:49 +0000

> > > >-  Each Emacs frame normally has a @dfn{menu bar}
> >
> > FWIW, I think "normally" is inappropriate here.
> 
> That's our usual style, it means the same as "by default".  We use
> both interchangeable, and I see no reason to change that.

FWIW -

A reason to change it is that it misleads & confuses.

"Normal" doesn't mean "by default", and vice versa.

"Our usual style" (our normal style?) might stand
some minor improvements ... or not.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.