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

[Eli Zaretskii]

> From: Stefan Kangas <stefan@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 ;-)