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

[Stefan Kangas]

Eli Zaretskii <eliz@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.