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

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Fri, 8 Oct 2021 20:40:42 -0400
> Cc: 50926@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.