Received: (at 50926) by debbugs.gnu.org; 9 Oct 2021 00:40:53 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Fri Oct 08 20:40:53 2021
Received: from localhost ([127.0.0.1]:52128 helo=debbugs.gnu.org)
by debbugs.gnu.org with esmtp (Exim 4.84_2)
(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
id 1mZ0Q0-0002Zx-Hs
for submit <at> debbugs.gnu.org; Fri, 08 Oct 2021 20:40:53 -0400
Received: from mail-pj1-f53.google.com ([209.85.216.53]:36354)
by debbugs.gnu.org with esmtp (Exim 4.84_2)
(envelope-from <stefankangas@HIDDEN>) id 1mZ0Px-0002Zk-O9
for 50926 <at> debbugs.gnu.org; Fri, 08 Oct 2021 20:40:50 -0400
Received: by mail-pj1-f53.google.com with SMTP id
qe4-20020a17090b4f8400b0019f663cfcd1so10495765pjb.1
for <50926 <at> debbugs.gnu.org>; Fri, 08 Oct 2021 17:40:49 -0700 (PDT)
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
d=1e100.net; s=20210112;
h=x-gm-message-state:from:in-reply-to:references:mime-version:date
:message-id:subject:to:cc;
bh=yPv7Dv11bng/VP5J3mOWFxfxARaV7+gnYiRh8AHEAas=;
b=mwJAp7TBLLBwW+Ul2UCVEFB1NATe7vywU3JtPzXPUruqt592gS+CQGeOHoHOOqu7D3
Q1gZPRuBHsIlBrh0GVAlxpuoQpsJk0DSQ8CuwQTLUhTa3IYurVcED8xcamKDs2weCjB9
7g3Trkq5eO0zRjzvLpkRnTzR8pf/RN91d3KBCHaH2E8Q7bpTJl8VezD3RFd694474gdy
vs3IuIjUzLO4+tAFL+NvamaMY4JPjBRykJ5m5w4QWXSWLlQUM8nN/mtRgUA9HzrqV/6o
TIrtx7OGdV1vKdp4QJRxXaG/dJaVrgnG3WS85B+SKI91J2UKVvlp46pIMuXEW750QT+v
IC4A==
X-Gm-Message-State: AOAM533UFDKtn0TfPfgzlOdy8G3eQSDss0Uo9iMtiUKhJxdR1QYM76AA
gFWoMfY0yfYctPAkkiJ283/lhbMLBUEqol8f3XQ=
X-Google-Smtp-Source: ABdhPJxmt4HrLeIRzYJvjHzo+0Iz/PgjxXMvgS685i/SRweTKhcQkhQ9a/lAt0N0EirvftbPJhj/jHu362Sb/v2pIfU=
X-Received: by 2002:a17:902:6b07:b0:13e:d5ba:3d8f with SMTP id
o7-20020a1709026b0700b0013ed5ba3d8fmr12247749plk.32.1633740043454; Fri, 08
Oct 2021 17:40:43 -0700 (PDT)
Received: from 753933720722 named unknown by gmailapi.google.com with
HTTPREST; Fri, 8 Oct 2021 20:40:42 -0400
From: Stefan Kangas <stefan@HIDDEN>
In-Reply-To: <834ka1fbyt.fsf@HIDDEN>
References: <CADwFkm=9P0jHSFbyUV1vh=URyais5cRcuZYwJx9NQZqXM4hX_g@HIDDEN>
<834ka1fbyt.fsf@HIDDEN>
MIME-Version: 1.0
Date: Fri, 8 Oct 2021 20:40:42 -0400
Message-ID: <CADwFkmkR6rhJDatTW7kBS8bG1BeeCF46Z80O_kYCUY_6W23KLw@HIDDEN>
Subject: Re: bug#50926: Light edits to the Emacs Manual (screen.texi)
To: Eli Zaretskii <eliz@HIDDEN>
Content-Type: text/plain; charset="UTF-8"
X-Spam-Score: 0.5 (/)
X-Debbugs-Envelope-To: 50926
Cc: 50926 <at> debbugs.gnu.org
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -0.5 (/)
Eli Zaretskii <eliz@HIDDEN> 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.
bug-gnu-emacs@HIDDEN:bug#50926; Package emacs.
Full text available.Received: (at 50926) by debbugs.gnu.org; 1 Oct 2021 17:13:55 +0000 From debbugs-submit-bounces <at> debbugs.gnu.org Fri Oct 01 13:13:55 2021 Received: from localhost ([127.0.0.1]:57280 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>) id 1mWM6d-00040c-4i for submit <at> debbugs.gnu.org; Fri, 01 Oct 2021 13:13:55 -0400 Received: from mx0a-00069f02.pphosted.com ([205.220.165.32]:35268) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from <drew.adams@HIDDEN>) id 1mWM6Y-00040Q-V4 for 50926 <at> debbugs.gnu.org; Fri, 01 Oct 2021 13:13:53 -0400 Received: from pps.filterd (m0246629.ppops.net [127.0.0.1]) by mx0b-00069f02.pphosted.com (8.16.1.2/8.16.1.2) with SMTP id 191FvFNE012502; Fri, 1 Oct 2021 17:13:50 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com; h=from : to : cc : subject : date : message-id : references : in-reply-to : content-type : content-transfer-encoding : mime-version; s=corp-2021-07-09; bh=KEA3a7J2CXU0QOWye0lMZLPgqW6S+YaG0hILcxOn6iI=; b=ICtyedaZrTDVVwalkM0S9SNx6svlmmGvO/7nNeDstonJDvj1RTX1PTAz3ugbDdF05mDk Lin2th5Pvd5wQNf2MASChtYuVkor5vZhRed92IiEVMeNs6kgwA9lCGBBIt2nltjGmePS 38vZge6jhki9JRrXaGmocZB61sWd0kpCNXy3IOXJHfMfRJmUBVTxMCVQ/MNTXzFuWuZy NQOKSNjAkPiyJuEZVouStEm9f6Shhtw9T/LNvwKgV3O2I6MfHJalnrJSkHtqFRuYmw+f 7NqDWWbxh/qJUoa45T+1mub6mZTtakRa0UlWBqbkKGXKfu62f/mFlis+jkt85DAsmvEO 5g== Received: from aserp3020.oracle.com (aserp3020.oracle.com [141.146.126.70]) by mx0b-00069f02.pphosted.com with ESMTP id 3bdevvfytn-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Fri, 01 Oct 2021 17:13:49 +0000 Received: from pps.filterd (aserp3020.oracle.com [127.0.0.1]) by aserp3020.oracle.com (8.16.0.42/8.16.0.42) with SMTP id 191H9vMJ060608; Fri, 1 Oct 2021 17:13:48 GMT Received: from nam11-co1-obe.outbound.protection.outlook.com (mail-co1nam11lp2169.outbound.protection.outlook.com [104.47.56.169]) by aserp3020.oracle.com with ESMTP id 3bceu8wy79-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Fri, 01 Oct 2021 17:13:48 +0000 ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=oNj956/ex3+lGnNfMZoBN6vzKZgtNMACw8zLgYnPjdHeT72hQpAFDKrOSzotBtBN5pEbYD/vUsOr5Kf+Wh5H7BqONk3uZLzC1oE+eIBI9N/GTuSTqWd6Ylbfd8juLdyfDOMOZULZF07sMEU/w05ds6Q0uWYfmp2FT4LVT3+J4M8UD6A4G9dLSF7CAlmKepSeEOXSLMc3rFBXxGLGSpiLQjwCargBw7xdkwrrQr+q0dy3aeDUIlPPr9WJ67FioY1pA8wSi4av9hTqjbdOZSLZZaOyea2oq7gDcIDdSIFsJaEZDHwx9olKWdNi52G4h4EAF0fVQ7bpdTv1wmGwpFWcSA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-AntiSpam-MessageData-ChunkCount:X-MS-Exchange-AntiSpam-MessageData-0:X-MS-Exchange-AntiSpam-MessageData-1; bh=KEA3a7J2CXU0QOWye0lMZLPgqW6S+YaG0hILcxOn6iI=; b=oBYY/oe3RTd7PT2PpSuBzgBP0pR0U+Itmt2Sq/+9D8/k3oN0+blf0H8DCsO4HJ2dFuXwEvI/NcB0oa/zj1m8npRNPle2+Z1NEJ1bmZmetAU7AqUXlwGxipspcMZEFX3vSAjqWWvRwIuiul41SxhQsC+SxHzelTn5XUQmi+W+aCWpyEAqPGg5HCbwPIbhDfIAxTb7BP0bIbwRgu5D2hfD5wSH4u782rdmuKJ+7pbn+x5yyYP1zAuW9Cc80T3Pbcerp0v9cnNWJsqVhb7hm7UwMAq9Rq73KcHPrL+dLVSBURzb5vWn7ntRb1PJyqqqq/zUQAc1FvM4zrYQ2QHRx2Hz0g== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass smtp.mailfrom=oracle.com; dmarc=pass action=none header.from=oracle.com; dkim=pass header.d=oracle.com; arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.onmicrosoft.com; s=selector2-oracle-onmicrosoft-com; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=KEA3a7J2CXU0QOWye0lMZLPgqW6S+YaG0hILcxOn6iI=; b=G4pUz3/T0at7la7ix7ut3WhixFdJq1kZDfehIN6+8oinYmnnD+XbOouEkiU72YePTzFzWjf0+aoHFivETUOepNDavzNxaNkfjfVCvC6BH9fgKMNmt1vRe+S4Vnhn7QvP8UMToG0b4Vj31SLe7bKbS2AZM/+i9Yy5619W+OB/YJ8= Received: from CO6PR10MB5473.namprd10.prod.outlook.com (2603:10b6:5:355::21) by MWHPR10MB1758.namprd10.prod.outlook.com (2603:10b6:301:9::7) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.4566.15; Fri, 1 Oct 2021 17:13:46 +0000 Received: from CO6PR10MB5473.namprd10.prod.outlook.com ([fe80::2539:8e21:118e:865d]) by CO6PR10MB5473.namprd10.prod.outlook.com ([fe80::2539:8e21:118e:865d%6]) with mapi id 15.20.4566.019; Fri, 1 Oct 2021 17:13:46 +0000 From: Drew Adams <drew.adams@HIDDEN> To: Stefan Kangas <stefan@HIDDEN> Subject: RE: [External] : bug#50926: Light edits to the Emacs Manual (screen.texi) Thread-Topic: [External] : bug#50926: Light edits to the Emacs Manual (screen.texi) Thread-Index: AQHXtshVhhv+uYA7+Uee03v75VX/vqu+YTkw Date: Fri, 1 Oct 2021 17:13:46 +0000 Message-ID: <CO6PR10MB547370A0B45B799C62141131F3AB9@HIDDEN> References: <CADwFkm=9P0jHSFbyUV1vh=URyais5cRcuZYwJx9NQZqXM4hX_g@HIDDEN> <SJ0PR10MB5488DFFA1676E70B7917390DF3AB9@HIDDEN> <CADwFkmk7-WPQXpZjjWes11A47BR2jk6i7-_cRwVfpsZNFx_b-w@HIDDEN> In-Reply-To: <CADwFkmk7-WPQXpZjjWes11A47BR2jk6i7-_cRwVfpsZNFx_b-w@HIDDEN> Accept-Language: en-US Content-Language: en-US X-MS-Has-Attach: X-MS-TNEF-Correlator: authentication-results: marxist.se; dkim=none (message not signed) header.d=none;marxist.se; dmarc=none action=none header.from=oracle.com; x-ms-publictraffictype: Email x-ms-office365-filtering-correlation-id: dd313f06-d387-4101-7813-08d984fed45a x-ms-traffictypediagnostic: MWHPR10MB1758: x-microsoft-antispam-prvs: <MWHPR10MB17588EBFC7D2C9F331222F72F3AB9@HIDDEN> x-ms-oob-tlc-oobclassifiers: OLM:7691; x-ms-exchange-senderadcheck: 1 x-ms-exchange-antispam-relay: 0 x-microsoft-antispam: BCL:0; x-microsoft-antispam-message-info: 3nknBZbP0JY42n0A2xEJKgO2QhfdSx1kx0XJ8Btmdg7ERaBigGSPR9KoMLoutzgPT3m8aKqm0lX38KMApGfd/wk9QV3DbugEEoUg6xww2nMO6wGOgJ1wbgpEWQqWvnf2n/WZvFiIgh+D0jjFHlSqHPAYMlbtyd/+Cli4kq+G2/cPZ4RSWHAE4CbZlb5LO/L04NyBRQTvE+LlBpG5Jm+70SDAAuDJMrmAoAzeKuYt7IVTMwpzdY3OAal5lrumsm6R3Arjsd6an+5Sbyfg6F6fxxqIiMZwbe8Up+NnotHo/+7jHWkZ7xIPjvIkbbjWn8Y+JvnL8rh2Ihshyziae5vYtRYfRPwf8is//GSv+th7L9+qH6CQ8SHc1STE3QX1Fvl0QzsG7MBXxnlsCSZHUbzAio57tr9TujZ2gFSD3S3ZodkYbsXlKzfv5WizjIYsqe+nK6e2Lp7kEEVJVSoCAwUvBtjHS/M6RjMHqkcuRX6xLcTrQtPzncGUmcfRrP/+m3QYOJOiJk/BAfp5ajNrEXzm+GOsiON5UIxrGn81Oj8DJ3hqVAgu1HfjFaMDo+iOegqMka/z6BsQmg0zjwmgMhzTB7aAGr63clHrw8V6Ac4AgsaHj/YoNw+gm7Mu6UlDburc/0VAe7Q+tJ9BNCtqCjXp4w08NrFMi2TeMdH3DuEtJk4rB4yK6Rc2pnS0Rqbf4e2FR0s3IDD+bbmy0RqdkwWb9A== x-forefront-antispam-report: CIP:255.255.255.255; CTRY:; LANG:en; SCL:1; SRV:; IPV:NLI; SFV:NSPM; H:CO6PR10MB5473.namprd10.prod.outlook.com; PTR:; CAT:NONE; SFS:(366004)(38100700002)(26005)(316002)(6506007)(33656002)(2906002)(6916009)(38070700005)(186003)(8676002)(8936002)(7696005)(86362001)(4744005)(55016002)(76116006)(9686003)(71200400001)(4326008)(66446008)(64756008)(66556008)(66476007)(52536014)(66946007)(5660300002)(44832011)(508600001)(122000001); DIR:OUT; SFP:1101; x-ms-exchange-antispam-messagedata-chunkcount: 1 x-ms-exchange-antispam-messagedata-0: =?utf-8?B?ZjRtcktlK0p2alRvdGxyZ0lrTnRtZnJjZi8zQlRaT3ppc2FvNElDTEhDeGlY?= =?utf-8?B?SndybThtalVtSnh2bkN3N3FjY3E0M3ZRaGF5clhlNlhBYnpNVkxiN0tTM1Bw?= =?utf-8?B?Mnk0MXIxTml6ZDJWOUZ5Ulp3ejA2dE5mQktSYlljd1hJbFNWRG9sLzVQSEdO?= =?utf-8?B?WVVSKzZSRzd6ZlNHOWxSR1haUVJoRWc2ZjNabUY4L3p1VWNPc2J6TXE2WHhC?= =?utf-8?B?TjNZaTZRRlVuVVYyZnBNL1R2NUpxVXFyWGFKVmlqcWs4ekRCMnhIV3RGSHk1?= =?utf-8?B?N00yenk5Vm9ubUwwN3hNV2JoMG5MU0l2bXV1RythSkoydWs3STN3SVc2bXVk?= =?utf-8?B?aWVGYXAxdVk2dnZnV3piUEJhVS9BUjU3SXU2SGtadUtQSmpycHBTbFV3cTE3?= =?utf-8?B?bmNMV3VLeDdML2NtR2NXTUhNdVgyWHdJUUVnZmdSb3hlSkpEcEtET0hOV2lt?= =?utf-8?B?QVljcEFuZEllM1hvQXQrNUQ5bHF6SUVaOGJ4bGR6WnBJUlB2amhCNGdGcmN4?= =?utf-8?B?TTlmQWZFQUl2UFJjNVJwSjlVZ0hPRkE0SUZzTHJuR3NPdTNxbHNIWHpld2o0?= =?utf-8?B?QzQxY1F5MXR4clVvV0hyYWIzc2FiSmZvKzNBdlA2bERKU1VTa3VUbFZnLzhR?= =?utf-8?B?a2ZBa0lDSllRUDNsK3o0ZWI4RFhGaitFVXBDdTl2WEIyU213UEV3UGViUk5N?= =?utf-8?B?N0VQbGNsalZJQ0pXWFlZelh6RVRheU4xTWVMMURVZ0lUeWZwUFMyUkl2d3ZJ?= =?utf-8?B?YkxuazlpNEIxdGp5R3RYVk9WeFM3dmxkL2NLeU4zZXVyY1pnSllBOTNESTBG?= =?utf-8?B?T2hyaHE2bDVWV3BPNy84R1ZhU1pvb0R6TWRDWCtBMndWM2NSRWJWY0EvNWh6?= =?utf-8?B?R0lxNXFncnBYK0kzWGZRb0EvbHlTOWp3VHVDZklCN1plYmRMc0FUYStwbEZC?= =?utf-8?B?VUYyYTRXbTVnTmhQVXprMzJ5M05DT1R0dmdtT0RJWW8wT2xvU3hoSFR3MkF4?= =?utf-8?B?aHdSTnVhNmQxMFVZVzgyR1hkVVdrOUJMSWIrUXRBdjJpSEs0VmVZaFZ1c3dR?= =?utf-8?B?OTh3bE0rSUNWUEdUbzlXQUNCTUZQbFprRFRZMXM1bW42Z0lSdWI5VnpvMVpS?= =?utf-8?B?cE4rbFJneGt6K3ljQU5xTmVidlhDVnNPUXp2OGhQWkNncEo3WExYUHdIeFJp?= =?utf-8?B?MnZsaG56V3F4cXBrUXljZ01JdklianVXVERFUjhZcmtyNTh6UHpwbk44USs3?= =?utf-8?B?NzBiRmRFK3BoNmV4RERXL0ljTHNmengzMnNtWkNFZjJJSU1Yby8xU0pWRHhS?= =?utf-8?B?Rm0zUXU0WFA5MXZROXZEUjljY040cXR4MkxEZUFmWllBTklYZjNIRTAzSTVH?= =?utf-8?B?Wnc2QUVYRFZkQS9Ca3ZSb0RuRlNjcEFYajhEaW5SL0VxeG5ZZlRVaWZVOGdn?= =?utf-8?B?NGVUWllJOVllazZ5Z1BTTStoaEI1OW5mZGpoOEhoZ3BlMDUvWTFHQWVzMFZB?= =?utf-8?B?TnVQR3FQZlJZOGdUU1RMeVBuODdkSjNXWU1ES1NheDNMMnkyL3psQTRtaGNu?= =?utf-8?B?QXV4ekZYQ1Q3bmhjTXkyakl6cTk5T2pRSkpreS9UZThteHIyRzB1L3g5a1lU?= =?utf-8?B?NjBIam9uazlqemg5bWM3aThqY3ZRUTh6am9rbE5xc05tMFd1OTd4VGRabjJT?= =?utf-8?B?cEY2NzJrT1N3Sm02U1pMdjdGSnNJUE5FL0FSb0F3ajFGejVkdTdmR3ZncTBq?= =?utf-8?Q?EjiQljDCXKVv05WEUy0CP3k1b3LePu0pcKrmqC9?= x-ms-exchange-transport-forked: True Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: base64 MIME-Version: 1.0 X-OriginatorOrg: oracle.com X-MS-Exchange-CrossTenant-AuthAs: Internal X-MS-Exchange-CrossTenant-AuthSource: CO6PR10MB5473.namprd10.prod.outlook.com X-MS-Exchange-CrossTenant-Network-Message-Id: dd313f06-d387-4101-7813-08d984fed45a X-MS-Exchange-CrossTenant-originalarrivaltime: 01 Oct 2021 17:13:46.7968 (UTC) X-MS-Exchange-CrossTenant-fromentityheader: Hosted X-MS-Exchange-CrossTenant-id: 4e2c6054-71cb-48f1-bd6c-3a9705aca71b X-MS-Exchange-CrossTenant-mailboxtype: HOSTED X-MS-Exchange-CrossTenant-userprincipalname: L9D4yNCeZePsWNXgaGcU9xX+5lonrYEVQH+8U9xoKRoPYXPvTIxKWivmxMlobr10MrrHgGLdGYBHPA4s0P/tsA== X-MS-Exchange-Transport-CrossTenantHeadersStamped: MWHPR10MB1758 X-Proofpoint-Virus-Version: vendor=nai engine=6300 definitions=10124 signatures=668683 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 phishscore=0 suspectscore=0 spamscore=0 adultscore=0 bulkscore=0 mlxscore=0 malwarescore=0 mlxlogscore=818 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2109230001 definitions=main-2110010122 X-Proofpoint-ORIG-GUID: 3vPs9gw_sYLvS_NofTAtaS8ZSPUzAiya X-Proofpoint-GUID: 3vPs9gw_sYLvS_NofTAtaS8ZSPUzAiya X-Spam-Score: -0.7 (/) X-Debbugs-Envelope-To: 50926 Cc: "50926 <at> debbugs.gnu.org" <50926 <at> debbugs.gnu.org> X-BeenThere: debbugs-submit <at> debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: <debbugs-submit.debbugs.gnu.org> List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe> List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/> List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org> List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help> List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe> Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org> X-Spam-Score: -1.7 (-) PiA+IC1jb21tYW5kIGZyb20gdGhlIG1lbnUgYmFyLiAgQW4gYXJyb3cgb24gdGhlIHJpZ2h0IGVk Z2Ugb2YgYSBtZW51DQo+IGl0ZW0NCj4gPiAtbWVhbnMgaXQgbGVhZHMgdG8gYSBzdWJzaWRpYXJ5 IG1lbnUsIG9yIEBkZm57c3VibWVudX0uICBBIEBzYW1wey4uLn0NCj4gPiArY29tbWFuZCBmcm9t IHRoZSBtZW51IGJhciBvciBhIEBkZm57c3VibWVudX0uICBBIEBzYW1wey4uLn0NCj4gPg0KPiA+ IFRoYXQncyB3cm9uZywgSU1PLiAgVGhlIG1lbnUtYmFyIGhhcyBtZW51cywgd2hpY2ggY2FuDQo+ ID4gaGF2ZSBzdWJtZW51cy4gIFRoZSBtZW51LWJhciBkb2Vzbid0IGhhdmUgc3VibWVudXMuDQo+ IA0KPiBTbyB0aGUgb3JpZ2luYWwgdGV4dCBpcyB3cm9uZyBhcyB3ZWxsPw0KDQpJTU8sIHllcy4N Cg0KPiA+IEJ1dCB3aGF0IGlzIG1lYW50IGJ5ICJ0aGUgZmlyc3QgbWVudSBiYXIgaXRlbSI/DQo+ ID4gVGhlIG1lbnUgYmFyIGRvZXNuJ3QgaGF2ZSBpdGVtcy4gIEl0IGhhcyBtZW51cy4NCj4gPiBB bmQgd2hhdCdzIG1lYW50IGJ5ICJmaXJzdCIgaGVyZT8gIE11c3QgaGF2ZQ0KPiA+IHNvbWV0aGlu ZyB0byBkbyB3aXRoIGludm9raW5nIChmaXJzdCBjb21tYW5kDQo+ID4gaW52b2tlZD8pLCBidXQg aXQncyBub3QgY2xlYXIgdG8gbWUgd2hhdCB0aGlzDQo+ID4gaXMgdHJ5aW5nIHRvIHNheS4NCj4g DQo+IFRoaXMgaXMgYSBwcmUtZXhpc3RpbmcgY29uZnVzaW9uLCByaWdodD8NCg0KSWYgeW91IG1l YW4gdGhhdCB0aGUgZXhpc3RpbmcgdGV4dCBhbHJlYWR5IHByZXNlbnRzDQpzdWNoIGNvbmZ1c2lv biwgdGhlbiB5ZXMsIElNTy4NCg==
bug-gnu-emacs@HIDDEN:bug#50926; Package emacs.
Full text available.
Received: (at 50926) by debbugs.gnu.org; 1 Oct 2021 13:29:21 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Fri Oct 01 09:29:21 2021
Received: from localhost ([127.0.0.1]:54992 helo=debbugs.gnu.org)
by debbugs.gnu.org with esmtp (Exim 4.84_2)
(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
id 1mWIbI-0003fL-KB
for submit <at> debbugs.gnu.org; Fri, 01 Oct 2021 09:29:21 -0400
Received: from mail-pl1-f172.google.com ([209.85.214.172]:42976)
by debbugs.gnu.org with esmtp (Exim 4.84_2)
(envelope-from <stefankangas@HIDDEN>) id 1mWIbG-0003eu-9K
for 50926 <at> debbugs.gnu.org; Fri, 01 Oct 2021 09:29:18 -0400
Received: by mail-pl1-f172.google.com with SMTP id l6so6293725plh.9
for <50926 <at> debbugs.gnu.org>; Fri, 01 Oct 2021 06:29:18 -0700 (PDT)
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
d=1e100.net; s=20210112;
h=x-gm-message-state:mime-version:references:in-reply-to:from:date
:message-id:subject:to:cc;
bh=sMa+zJtFgh9481mk2nkbRIPqoM9ZkNKhXdtr6mkRtNo=;
b=qaDpAB7Wyw/ki6a5Ce3bjm/ecg5gO7eoCuyvw+vWoewW9M+bWwOYSBRjZPkAeQDX0D
loZHtO6YCrvWdZkgWf3v6+XTfKlL1CM/6p8xSSfsDf86xB0A378rDu30bYAK/JZI3nNq
d/fkF3IR6ar5faDJQsOjRiVvyLI66NL/5hr2yikQq6L85h2ShAzPeS8A7voMG7Khx6o8
PoWbaucngyFMm4HBd/2jZ1ImhI2CaNwCl5S00S8wsBP5lsR4AsQaVY8cPS7HKAuWUwWh
bznJJzUxLg2iEhk+e4ZjF7rqkPg7Jzy06S552brUjvKA9ty/qKOn4tzkwrtIjMsBWyHz
c+3w==
X-Gm-Message-State: AOAM531NFQA8FpHPmrcvIN7k71lCDycGkzStobAiNbk0RRTg+rA22svK
btFysifkCMtkEAwy3pucvAOms21ThpZASXHfZbo=
X-Google-Smtp-Source: ABdhPJzRvbwKZw2bn4fwLdZOf8ThYtHw30SSrbe5uRruCT3LSt6AK3zxSgimKloOI41dGc0c7OMKU2vH84HxFrE3uY0=
X-Received: by 2002:a17:90b:3805:: with SMTP id
mq5mr19772869pjb.143.1633094952264;
Fri, 01 Oct 2021 06:29:12 -0700 (PDT)
MIME-Version: 1.0
References: <CADwFkm=9P0jHSFbyUV1vh=URyais5cRcuZYwJx9NQZqXM4hX_g@HIDDEN>
<SJ0PR10MB5488DFFA1676E70B7917390DF3AB9@HIDDEN>
In-Reply-To: <SJ0PR10MB5488DFFA1676E70B7917390DF3AB9@HIDDEN>
From: Stefan Kangas <stefan@HIDDEN>
Date: Fri, 1 Oct 2021 15:29:01 +0200
Message-ID: <CADwFkmk7-WPQXpZjjWes11A47BR2jk6i7-_cRwVfpsZNFx_b-w@HIDDEN>
Subject: Re: [External] : bug#50926: Light edits to the Emacs Manual
(screen.texi)
To: Drew Adams <drew.adams@HIDDEN>
Content-Type: text/plain; charset="UTF-8"
X-Spam-Score: 0.5 (/)
X-Debbugs-Envelope-To: 50926
Cc: "50926 <at> debbugs.gnu.org" <50926 <at> debbugs.gnu.org>
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -0.5 (/)
Drew Adams <drew.adams@HIDDEN> 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.
bug-gnu-emacs@HIDDEN:bug#50926; Package emacs.
Full text available.
Received: (at 50926) by debbugs.gnu.org; 1 Oct 2021 07:20:55 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Fri Oct 01 03:20:55 2021
Received: from localhost ([127.0.0.1]:54571 helo=debbugs.gnu.org)
by debbugs.gnu.org with esmtp (Exim 4.84_2)
(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
id 1mWCql-0004a9-73
for submit <at> debbugs.gnu.org; Fri, 01 Oct 2021 03:20:55 -0400
Received: from eggs.gnu.org ([209.51.188.92]:32768)
by debbugs.gnu.org with esmtp (Exim 4.84_2)
(envelope-from <eliz@HIDDEN>) id 1mWCqi-0004Zy-4J
for 50926 <at> debbugs.gnu.org; Fri, 01 Oct 2021 03:20:53 -0400
Received: from fencepost.gnu.org ([2001:470:142:3::e]:44144)
by eggs.gnu.org with esmtp (Exim 4.90_1)
(envelope-from <eliz@HIDDEN>)
id 1mWCqY-0003US-6r; Fri, 01 Oct 2021 03:20:46 -0400
Received: from 84.94.185.95.cable.012.net.il ([84.94.185.95]:1902
helo=home-c4e4a596f7)
by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
(Exim 4.90_1) (envelope-from <eliz@HIDDEN>)
id 1mWCqL-0006X4-Vm; Fri, 01 Oct 2021 03:20:40 -0400
Date: Fri, 01 Oct 2021 10:20:10 +0300
Message-Id: <834ka1fbyt.fsf@HIDDEN>
From: Eli Zaretskii <eliz@HIDDEN>
To: Stefan Kangas <stefan@HIDDEN>
In-Reply-To: <CADwFkm=9P0jHSFbyUV1vh=URyais5cRcuZYwJx9NQZqXM4hX_g@HIDDEN>
(message from Stefan Kangas on Fri, 1 Oct 2021 01:51:04 +0200)
Subject: Re: bug#50926: Light edits to the Emacs Manual (screen.texi)
References: <CADwFkm=9P0jHSFbyUV1vh=URyais5cRcuZYwJx9NQZqXM4hX_g@HIDDEN>
X-Spam-Score: -2.3 (--)
X-Debbugs-Envelope-To: 50926
Cc: 50926 <at> debbugs.gnu.org
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -3.3 (---)
> From: Stefan Kangas <stefan@HIDDEN>
> 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 ;-)
bug-gnu-emacs@HIDDEN:bug#50926; Package emacs.
Full text available.Received: (at 50926) by debbugs.gnu.org; 1 Oct 2021 01:50:16 +0000 From debbugs-submit-bounces <at> debbugs.gnu.org Thu Sep 30 21:50:16 2021 Received: from localhost ([127.0.0.1]:54358 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>) id 1mW7gm-0004jZ-3l for submit <at> debbugs.gnu.org; Thu, 30 Sep 2021 21:50:16 -0400 Received: from mx0b-00069f02.pphosted.com ([205.220.177.32]:37644) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from <drew.adams@HIDDEN>) id 1mW7gi-0004jO-Gs for 50926 <at> debbugs.gnu.org; Thu, 30 Sep 2021 21:50:14 -0400 Received: from pps.filterd (m0246631.ppops.net [127.0.0.1]) by mx0b-00069f02.pphosted.com (8.16.1.2/8.16.1.2) with SMTP id 1910TdRr014668; Fri, 1 Oct 2021 01:50:11 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com; h=from : to : subject : date : message-id : references : in-reply-to : content-type : content-transfer-encoding : mime-version; s=corp-2021-07-09; bh=dIahUbMTZJnd/45igOF5dp0goRfL8KKELqc5ZTXfHsY=; b=GuI5dBE7FwysmIrcz7aX24YaKtO+GHMtbzX+G8YMA1Gjhg0+SnfKFpr+WDB/X5xAhuVd D0S8uTcYme7Q5baSlg03BJ3UHJ+ITwUC483zTo6gtUx4SYT97pPdWZ6mVMvQLGquLxjJ oi3lmi+LNKhtchf8f8uWex1wyoeXKomigYOILCKEWIoor7xU/zlurmntZMHt8rJsNdN9 O4K6izOju15yCe1Al7ZcMn+1fKZMmn3AxFuGy4U3qXugIKF66YsqCYN469/T3d+mJo9c Zm7jiBj3CLgztgUS7U305B3DqE2TAH7v+TB69apgOYuinHNx7KjfGpBqhOfG+OiybYmd dg== Received: from userp3020.oracle.com (userp3020.oracle.com [156.151.31.79]) by mx0b-00069f02.pphosted.com with ESMTP id 3bddu8vr6h-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Fri, 01 Oct 2021 01:50:11 +0000 Received: from pps.filterd (userp3020.oracle.com [127.0.0.1]) by userp3020.oracle.com (8.16.0.42/8.16.0.42) with SMTP id 1911eIdc100146; Fri, 1 Oct 2021 01:50:10 GMT Received: from nam11-co1-obe.outbound.protection.outlook.com (mail-co1nam11lp2176.outbound.protection.outlook.com [104.47.56.176]) by userp3020.oracle.com with ESMTP id 3bc3cgu2sp-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Fri, 01 Oct 2021 01:50:10 +0000 ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=BfWiCUn4CevE02lAfO+aVXzC1jxBHvCHtBLvtknpfyMGka9OXGIujEXIzXIJO9TZQiwQ+ggVCgc9QNJ0WQZzKkoGNeKClITQwYVTM5wvm9YVwjQa22GybO1Nkv5pJhnaA9/QRcKRQx7H/afCKMwlvpvyipJeNA89mJAUwDa1XKst5kiKESDf8loadOj7hT/3hRiVT00DSP7t9K+U3wyGG1aJgMbu6NdiZGCYjlQairf7m4oYkDrdPtoAuPX+MTUZZDbuCEpeZsmTn0K7C4gbdwr7yoHtn6YMQ/JWdZ/d0cP5P93Lu0YJCnc3YSn4jBrtX9NGCy/QD1atRQEqa7gqNQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-AntiSpam-MessageData-ChunkCount:X-MS-Exchange-AntiSpam-MessageData-0:X-MS-Exchange-AntiSpam-MessageData-1; bh=dIahUbMTZJnd/45igOF5dp0goRfL8KKELqc5ZTXfHsY=; b=GPPwcVsrY4AJ8VXgBbj73LgQXsmBDUjouLRf0Ppx00ZbgOHcv83G2vwbWui5CV9u8P3s1wHIEw3Yta/A8dEFgBw0m+JEy44L0zl5hLiICeE1AX6Q5vxNVnjXgtEFWTiq2WuiQdd+jZm8kTxCt/Ba5qbi45z8zdI/cYI/SiK0Cn0lDHoaLDusO+iJ4OCLcYvd7LmIthad6F19Ex8VmibZeHC17y5GkWqSQTH4a3TeooO/5ubtq6lqrolb4N/QTEUDQSYz3c7IDM+4IOn3lhit5hqZWeRthDgjKPUjuPEIIO9iK3NTs/5BfJGN9MapCiyuc8EE1rmf8zucdnpkwyKC/Q== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass smtp.mailfrom=oracle.com; dmarc=pass action=none header.from=oracle.com; dkim=pass header.d=oracle.com; arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.onmicrosoft.com; s=selector2-oracle-onmicrosoft-com; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=dIahUbMTZJnd/45igOF5dp0goRfL8KKELqc5ZTXfHsY=; b=Xza7o8oXG8XGjz1BE+Wd6EKl4e5setSkDKaZmBz0O+bdGBwEZmpgCr2s9t6JIE0kp6BEeV4eDg92hLHyJRW51kPkQEBnbvQr3oEvUTVwK21ybD90Tng1YpD0/LXqrbyvnvcY67t/uIEGGh8DAB813x5RWQ7wy038GxROerMRnAs= Received: from SJ0PR10MB5488.namprd10.prod.outlook.com (2603:10b6:a03:37e::19) by BYAPR10MB2871.namprd10.prod.outlook.com (2603:10b6:a03:83::31) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.4544.18; Fri, 1 Oct 2021 01:50:08 +0000 Received: from SJ0PR10MB5488.namprd10.prod.outlook.com ([fe80::c0bc:7c3a:292f:8a82]) by SJ0PR10MB5488.namprd10.prod.outlook.com ([fe80::c0bc:7c3a:292f:8a82%9]) with mapi id 15.20.4544.023; Fri, 1 Oct 2021 01:50:08 +0000 From: Drew Adams <drew.adams@HIDDEN> To: Stefan Kangas <stefan@HIDDEN>, "50926 <at> debbugs.gnu.org" <50926 <at> debbugs.gnu.org> Subject: RE: [External] : bug#50926: Light edits to the Emacs Manual (screen.texi) Thread-Topic: [External] : bug#50926: Light edits to the Emacs Manual (screen.texi) Thread-Index: AQHXtlYzTLGZxdT/30e7oW2FmOPvHau9Wfqw Date: Fri, 1 Oct 2021 01:50:07 +0000 Message-ID: <SJ0PR10MB5488DFFA1676E70B7917390DF3AB9@HIDDEN> References: <CADwFkm=9P0jHSFbyUV1vh=URyais5cRcuZYwJx9NQZqXM4hX_g@HIDDEN> In-Reply-To: <CADwFkm=9P0jHSFbyUV1vh=URyais5cRcuZYwJx9NQZqXM4hX_g@HIDDEN> Accept-Language: en-US Content-Language: en-US X-MS-Has-Attach: X-MS-TNEF-Correlator: authentication-results: marxist.se; dkim=none (message not signed) header.d=none;marxist.se; dmarc=none action=none header.from=oracle.com; x-ms-publictraffictype: Email x-ms-office365-filtering-correlation-id: d54e8f31-f1b3-46fd-b135-08d9847dcc28 x-ms-traffictypediagnostic: BYAPR10MB2871: x-microsoft-antispam-prvs: <BYAPR10MB287157E9EBC031DFC7FC0948F3AB9@HIDDEN> x-ms-oob-tlc-oobclassifiers: OLM:9508; x-ms-exchange-senderadcheck: 1 x-ms-exchange-antispam-relay: 0 x-microsoft-antispam: BCL:0; x-microsoft-antispam-message-info: M01Sypn1MtXrbRu8Xa7gpvZWNeXrErLlGXQeyZNxTzOF6rXKXWs/I+JiusX98dW5dtY5DjZiIc+QpfRk5aCnqMFWa/BvcibAaAf4TXKsz+8Qb18flnoUVzfqrmdgA/huDrm4YEWFo7NS4t6iQst5t3z934wkJmjmtcvCQ4KhFHJSNCpYIIYEaZFd1/YnkkfTPHLqo/7RvB6wodCFIgqTHw9/TXrgyMdiJouEeq6xgCmaf5OjfboWD/hCtWpJYkiZjNYjdALgU7BbQXkwkzfEVNPIoG9pDOOAkD8OtTrUeDPRZJnS9eIBQIyoPi9HHlpp/RQ/qiOT/NiwXEFYAeqAenQIcQcjjp65r4Sa0jOPm0uxCpb21x3aOFwup4qGg0EuqL5SmItAhY31dtb/tUB+Lf7yHU+te3LxyUKX10gKnwYJiAwd9pdwn/3J5SIZpgVfk9ra7NMaFOhn2/uYr9HJakYq2Qhn+h7EMxwRYnNTGHAVKrdmAo1BeppccXp2nAR2ijMsoFBGTeGm/JYKP8WpnIVwO370JpWaxdt9LSNnb7SBrixvzprMjRKWbUI+v8LUxMdM1ondvks+fKTPipwzfmv8h60sk9Bvefv3rHN12bUDphUMWmDvXAj1wIXNoFIwN1PWsM444Usax14dbJZr+FaIGSc7MPmyR9E5lD+vogqxOVaqbibgVaR/l199wmAJHrs7euj3by6EzbUZccl6aQ== x-forefront-antispam-report: CIP:255.255.255.255; CTRY:; LANG:en; SCL:1; SRV:; IPV:NLI; SFV:NSPM; H:SJ0PR10MB5488.namprd10.prod.outlook.com; PTR:; CAT:NONE; SFS:(366004)(38070700005)(8676002)(76116006)(2906002)(66946007)(26005)(66476007)(66556008)(64756008)(66446008)(8936002)(6506007)(5660300002)(316002)(508600001)(110136005)(44832011)(83380400001)(52536014)(86362001)(7696005)(71200400001)(122000001)(55016002)(38100700002)(9686003)(33656002)(186003); DIR:OUT; SFP:1101; x-ms-exchange-antispam-messagedata-chunkcount: 1 x-ms-exchange-antispam-messagedata-0: =?utf-8?B?WlcrczR1NVJTYWwxNUhDRnVkOTRGYnR5b2RzSDBDSVd6T1IvTGY5RTlDMU83?= =?utf-8?B?MTVBZkIyMlRlRGpJYzdUcExNUXBVT29wT2hwYk1rRnpZZVJqMlpKSUNTYUFm?= =?utf-8?B?dXNPWTAxYjFqOFM0NE5mSCtKQU5aMU8yMHViUzhOLyszRGNBa3I4bURlSFZo?= =?utf-8?B?cG5LUTBJVHNpeEZNUEtqenVnQlc3VUQweHlxWkJwQzNJWE5qVVNEWlFBbGEz?= =?utf-8?B?NWVkMmxaMG8ycUo1VSs4RURqTW1IWC9iWHpubEtuSjNTZVRsajhvVGh0cTdm?= =?utf-8?B?bWFtd1VSZG1XUGlWUlZxU2prL3ErM29FUFpkQ3hKSmI1WE45NGVEM2t4V0dp?= =?utf-8?B?SEpPK3cwMEdiV0NCcDNobEkwUkIramZhemFhc1RXdWFzblFLd0syZ05GMG9E?= =?utf-8?B?U05MT1JvZW80TnhEZG9ZNXRWT3RxY2xjc2lSMUUzL3lsUHNOY3pTUTZQSkxq?= =?utf-8?B?L01PZlNxcE5ZZ0F3RXQ0UEIvRTF4NXF2cmNGRExUd2dkaEYzcFp0TEdPenN0?= =?utf-8?B?SnQxOVk5M3Rjd2NHKzJPQ3JaMlV4UzlwTTljRUlMUEZwZEFGQ0pEcUV2Ritj?= =?utf-8?B?SVc3NGVvbHBjeXBKN2phTGtQbDc3bCtnTzRnVnVpVysrd3hRK3ZNeGNjT3dC?= =?utf-8?B?MWdyUm1mM01rNFUrKzlCUXA5YXZaS2ZrRU41UytmMEpIUllRMkJxM2MyUGR0?= =?utf-8?B?VnBSZjB0bWNCYnFTck1zUXF3b21uNFhvL3h5MWZ5dmNnVjkyQ0EzSW92Y3Uv?= =?utf-8?B?S2lNRkg4Y25VcUN1TndjQitua2NVUW1wSkVNVkh5NGQvemQ1SER6RUpsdGJ6?= =?utf-8?B?VzdINGkzTHY3d0p3M01mbll6dkphZXJ4LzJPOEhiTWlUK1dzb2hHZ0V6WjFx?= =?utf-8?B?RzZCdnlMQysvSUo0RjliUjVHTnYwRENpaHE5Szh2MVVwSjRmL0FDRVFJemEr?= =?utf-8?B?bjVrYU03Q3Z4bTRqTWc2MVNzeHlmOWNYRUVUeE0zTE83d3kzU0gwaFhLT1lM?= =?utf-8?B?eTRIaGw0ZHBwNTBYWklSbFYvODM4cVQ0bmMxL1ZsRm5kMjJabjAwQVZBVytN?= =?utf-8?B?WVJoSmFlQjFnRjZMVHBnY2xCdG5VNFBVSVo2aXNua0lsWWlHRnJLRlZzL3or?= =?utf-8?B?M3MvdXZ3QlZLS0gzbUJHdG1CZUlaZWZRSDVvd1l4TG1kVnc2ZUF6MWZTaUJk?= =?utf-8?B?WGErRnFhQWZaWk5ZeUdoWWlyeXgyRFFKMmc4OVRqNDJtQmFKSDB5b29CVTZj?= =?utf-8?B?R0FsRWNycjc4c0poVmNTc04ycGtsdUh1T1BQdmF6aWNGc2dBa2FTSW85R1ZC?= =?utf-8?B?WllOZTVGR2ZVSWZvRExOcmMwZHpyNE4xdjdzY3dmdTRPc3dPWVVEV3lPQWh2?= =?utf-8?B?OC84YjVENi9KWGZIeGVZRU5tYzkySmplZ1N0MWJUZ2xYZkZOZGpMU0ZhWnF4?= =?utf-8?B?VjBUS3JELzc2WDZUc3VHRS93S245U3Fsc2xaZUUvWVpCRWZETERxVkNHUHVq?= =?utf-8?B?V0tEdXE5MVF3TXZualB1ZHEzVkNpVXBwTnpZODBjakZ4dGp6eUh6Z0pmYUtx?= =?utf-8?B?aG1MY1VPV3F3QXBJYit0SWpoR2lrbmFrOTh6cm5nRThmLytWTWdYTzRLcWRt?= =?utf-8?B?MzB3NktUMlhEdDc2M3JOeUF4WjhCZG1DcGg4bW8wcUFXTVNlYW93ZXhGS0dm?= =?utf-8?B?VUJSMmJjT0hiTENOSml4cU5lblhLVUhsY28rQjdLQ1A5TFpqR09ZWmNjUy9K?= =?utf-8?Q?NHg95ibcB2JsL1e8MzPasufvhyvRj93XvqmpHP7?= x-ms-exchange-transport-forked: True Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: base64 MIME-Version: 1.0 X-OriginatorOrg: oracle.com X-MS-Exchange-CrossTenant-AuthAs: Internal X-MS-Exchange-CrossTenant-AuthSource: SJ0PR10MB5488.namprd10.prod.outlook.com X-MS-Exchange-CrossTenant-Network-Message-Id: d54e8f31-f1b3-46fd-b135-08d9847dcc28 X-MS-Exchange-CrossTenant-originalarrivaltime: 01 Oct 2021 01:50:07.9727 (UTC) X-MS-Exchange-CrossTenant-fromentityheader: Hosted X-MS-Exchange-CrossTenant-id: 4e2c6054-71cb-48f1-bd6c-3a9705aca71b X-MS-Exchange-CrossTenant-mailboxtype: HOSTED X-MS-Exchange-CrossTenant-userprincipalname: LwWujWeRY9QFsmfxYdqJHEF9jTNkM8PuRGiR80E3YGWR4PZoRcVSigMHz5uku9Y2zjAh+2kXl/hnQJprJk1FfA== X-MS-Exchange-Transport-CrossTenantHeadersStamped: BYAPR10MB2871 X-Proofpoint-Virus-Version: vendor=nai engine=6300 definitions=10123 signatures=668683 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 adultscore=0 mlxscore=0 mlxlogscore=999 phishscore=0 bulkscore=0 suspectscore=0 malwarescore=0 spamscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2109230001 definitions=main-2110010007 X-Proofpoint-GUID: 0l9pu7lWRNGjndEok-bQFUrgPrZz0zAX X-Proofpoint-ORIG-GUID: 0l9pu7lWRNGjndEok-bQFUrgPrZz0zAX X-Spam-Score: -0.7 (/) X-Debbugs-Envelope-To: 50926 X-BeenThere: debbugs-submit <at> debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: <debbugs-submit.debbugs.gnu.org> List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe> List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/> List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org> List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help> List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe> Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org> X-Spam-Score: -1.7 (-) U29tZSBxdWljaywgbWlub3IgY29weS1lZGl0IHN1Z2dlc3Rpb25zIC0NCg0KPiAtICBTb21lIGNv bW1hbmRzIGRpc3BsYXkgaW5mb3JtYXRpdmUgbWVzc2FnZXMgaW4gdGhlIGVjaG8gYXJlYSB0byB0 ZWxsDQo+IC15b3Ugd2hhdCB0aGUgY29tbWFuZCBoYXMgZG9uZSwNCj4gKyAgU29tZSBjb21tYW5k cyBkaXNwbGF5IG1lc3NhZ2VzIGluIHRoZSBlY2hvIGFyZWEgdG8gdGVsbA0KPiAreW91IHdoYXQg aXQgaGFzIGRvbmUsDQoNClNvbWUgY29tbWFuZHMuLi53aGF0IHRoZXkgaGF2ZSBkb25lLg0KDQo+ ICwgc3VjaCBhcyBUZXh0DQo+IC1tb2RlLCBMaXNwIG1vZGUsIEMgbW9kZSwgYW5kIHNvIGZvcnRo LiAgQHhyZWZ7TWFqb3IgTW9kZXN9LiAgU29tZQ0KPiArbW9kZSwgTGlzcCBtb2RlLCBDIG1vZGUs IGFuZCBzbyBvbi4gIEB4cmVme01ham9yIE1vZGVzfS4NCg0KRHJvcCB0aGUgIiwgYW5kIHNvICoi LiAgSXQncyByZWR1bmRhbnQgd2l0aCAic3VjaCBhcyIuDQoNCj4gK0B4cmVme09wdGlvbmFsIE1v ZGUgTGluZX0uICBGaW5hbGx5LCB5b3UgY2FuIGNsaWNrDQo+ICtvbiBkaWZmZXJlbnQgcGFydHMg b2YgdGhlIG1vZGUgbGluZQ0KDQpEcm9wICJvbiIuDQoNCj4gSG92ZXJpbmcNCj4gK3RoZSBtb3Vz ZSBwb2ludGVyIGFib3ZlLi4uc2hvd3MuLi5ieSBjbGlja2luZw0KDQoiUGxhY2UgdGhlIG1vdXNl IHBvaW50ZXIgb24uLi50byBzaG93Li4uDQpieSBjbGlja2luZyB0aGVyZSINCg0Kb3INCg0KIk1v dmUgdGhlIG1vdXNlIHBvaW50ZXIgdG8uLi50byBzaG93Li4uDQpieSBjbGlja2luZyB0aGVyZSIN Cg0KSXQncyBub3QgYSBodW1taW5nYmlyZC4gIEFuZCAiYWJvdmUiIGNhbg0KbWlzbGVhZCBhcyBp biB0b3dhcmQgdGhlIHRvcCBvZiB0aGUgc2NyZWVuLg0KDQooSW5mb3JtYWxseSBJIHVzZSAibW91 c2VvdmVyIiBhcyBhIHZlcmIsDQpidXQgSSdtIG5vdCBzdWdnZXN0aW5nIHRoYXQgZm9yIEVtYWNz LikNCg0KLWNvbW1hbmQgZnJvbSB0aGUgbWVudSBiYXIuICBBbiBhcnJvdyBvbiB0aGUgcmlnaHQg ZWRnZSBvZiBhIG1lbnUgaXRlbQ0KLW1lYW5zIGl0IGxlYWRzIHRvIGEgc3Vic2lkaWFyeSBtZW51 LCBvciBAZGZue3N1Ym1lbnV9LiAgQSBAc2FtcHsuLi59DQorY29tbWFuZCBmcm9tIHRoZSBtZW51 IGJhciBvciBhIEBkZm57c3VibWVudX0uICBBIEBzYW1wey4uLn0NCg0KVGhhdCdzIHdyb25nLCBJ TU8uICBUaGUgbWVudS1iYXIgaGFzIG1lbnVzLCB3aGljaCBjYW4NCmhhdmUgc3VibWVudXMuICBU aGUgbWVudS1iYXIgZG9lc24ndCBoYXZlIHN1Ym1lbnVzLg0KDQorICBJZiBhIGNvbW1hbmQgaW4g dGhlIG1lbnUgYmFyIGhhdmUgYW4gb3JkaW5hcnkga2V5IGJpbmRpbmcNCg0KImhhcyIsIG5vdCAi aGF2ZSINCg0KLSAgSW5zdGVhZCBvZiB1c2luZyB0aGUgbW91c2UsIHlvdSBjYW4gYWxzbyBpbnZv a2UgdGhlIGZpcnN0IG1lbnUgYmFyDQotaXRlbSBieSBwcmVzc2luZyBAa2V5e0YxMH0gKHRvIHJ1 biB0aGUgY29tbWFuZCBAY29kZXttZW51LWJhci1vcGVufSkuDQorICBZb3UgY2FuIGludm9rZSB0 aGUgZmlyc3QgbWVudSBiYXINCitpdGVtIHdpdGggeW91ciBrZXlib2FyZCBieSBwcmVzc2luZyBA a2V5e0YxMH0gKHRvIHJ1biB0aGUgY29tbWFuZA0KQGNvZGV7bWVudS1iYXItb3Blbn0pLg0KDQoi bWVudS1iYXIiLCBub3QgIm1lbnUgYmFyIiBpZiB1c2VkIGFzIGFuDQphZGplY3RpdmUgYmVmb3Jl IHRoZSBub3VuLg0KDQpCdXQgd2hhdCBpcyBtZWFudCBieSAidGhlIGZpcnN0IG1lbnUgYmFyIGl0 ZW0iPw0KVGhlIG1lbnUgYmFyIGRvZXNuJ3QgaGF2ZSBpdGVtcy4gIEl0IGhhcyBtZW51cy4NCkFu ZCB3aGF0J3MgbWVhbnQgYnkgImZpcnN0IiBoZXJlPyAgTXVzdCBoYXZlDQpzb21ldGhpbmcgdG8g ZG8gd2l0aCBpbnZva2luZyAoZmlyc3QgY29tbWFuZA0KaW52b2tlZD8pLCBidXQgaXQncyBub3Qg Y2xlYXIgdG8gbWUgd2hhdCB0aGlzDQppcyB0cnlpbmcgdG8gc2F5Lg0KDQpBbmQgeW91IGNhbiBk cm9wICJ3aXRoIHlvdXIga2V5Ym9hcmQiIGhlcmU6DQoNCiAgd2l0aCB5b3VyIGtleWJvYXJkIGJ5 IHByZXNzaW5nIEBrZXl7RjEwfQ0KDQpIVEguICBGZWVsIGZyZWUgdG8gaWdub3JlLCBvZiBjb3Vy c2UuDQoNCg0KDQoNCg0K
bug-gnu-emacs@HIDDEN:bug#50926; Package emacs.
Full text available.
Received: (at submit) by debbugs.gnu.org; 30 Sep 2021 23:51:25 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Thu Sep 30 19:51:25 2021
Received: from localhost ([127.0.0.1]:54324 helo=debbugs.gnu.org)
by debbugs.gnu.org with esmtp (Exim 4.84_2)
(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
id 1mW5pl-0001v2-19
for submit <at> debbugs.gnu.org; Thu, 30 Sep 2021 19:51:25 -0400
Received: from lists.gnu.org ([209.51.188.17]:58100)
by debbugs.gnu.org with esmtp (Exim 4.84_2)
(envelope-from <stefankangas@HIDDEN>) id 1mW5ph-0001ur-0U
for submit <at> debbugs.gnu.org; Thu, 30 Sep 2021 19:51:23 -0400
Received: from eggs.gnu.org ([2001:470:142:3::10]:34180)
by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
(Exim 4.90_1) (envelope-from <stefankangas@HIDDEN>)
id 1mW5pg-0007a4-PY
for bug-gnu-emacs@HIDDEN; Thu, 30 Sep 2021 19:51:20 -0400
Received: from mail-pf1-f180.google.com ([209.85.210.180]:41687)
by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128)
(Exim 4.90_1) (envelope-from <stefankangas@HIDDEN>)
id 1mW5pe-0002oF-DK
for bug-gnu-emacs@HIDDEN; Thu, 30 Sep 2021 19:51:20 -0400
Received: by mail-pf1-f180.google.com with SMTP id p1so330481pfh.8
for <bug-gnu-emacs@HIDDEN>; Thu, 30 Sep 2021 16:51:17 -0700 (PDT)
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
d=1e100.net; s=20210112;
h=x-gm-message-state:mime-version:from:date:message-id:subject:to;
bh=DZ2hUD8dqVfzfXYMySjSx5S7HYRIZ64nTZMNQ/BqiGs=;
b=f4DnDhicpkL3X9fG/fK3csqUFOy59L5xS0dpJk5qGF8Iuk+KScSx37gNYQpPH72OdI
WiqffVLtSez8RdiBM8LLHYFnGlCKLkW0rPF+9GrO1FOGpnG8IMJPOX+adiDXmSF4iALs
WfnYy0keTduHtTzHROIsnlfT4yBMKsn/c/jLFIPKu2Z3D6raXoWwBZBUm6gMLpZTyI5W
MQNahfvhj+dUUojVMetCK2l2Sm5NrNAR+7RlOySNDG5MR2P9na431VNtAwP3HGRfo3tC
6KG9OmVpr4fVP7kJS2WHg7wcyv4WbBEMAsGCLRGG2+aVbIFazHE4u/MCLuPDHtlqs4ji
aflQ==
X-Gm-Message-State: AOAM533iADhReFuoz67LX2YDzAkxKGphiaMwXR6srNxdnUGinbJnmDs6
dmgrTHf+SBPI7w1iOJjxwLrdEgIDlqic3jEQhfWCXx7w040=
X-Google-Smtp-Source: ABdhPJx8CBKrqtdxmeEBNDBFjME/FV6l88AwU6dOzQjB1It3dFSEnoVX1HnJtrC4CkQQIS75UJXZqBJ4UTSX4vCKZug=
X-Received: by 2002:a63:6941:: with SMTP id e62mr7191351pgc.114.1633045876214;
Thu, 30 Sep 2021 16:51:16 -0700 (PDT)
MIME-Version: 1.0
From: Stefan Kangas <stefan@HIDDEN>
Date: Fri, 1 Oct 2021 01:51:04 +0200
Message-ID: <CADwFkm=9P0jHSFbyUV1vh=URyais5cRcuZYwJx9NQZqXM4hX_g@HIDDEN>
Subject: Light edits to the Emacs Manual (screen.texi)
To: bug-gnu-emacs@HIDDEN
Content-Type: text/plain; charset="UTF-8"
Received-SPF: pass client-ip=209.85.210.180;
envelope-from=stefankangas@HIDDEN; helo=mail-pf1-f180.google.com
X-Spam_score_int: -13
X-Spam_score: -1.4
X-Spam_bar: -
X-Spam_report: (-1.4 / 5.0 requ) BAYES_00=-1.9,
FREEMAIL_FORGED_FROMDOMAIN=0.249, FREEMAIL_FROM=0.001,
HEADER_FROM_DIFFERENT_DOMAINS=0.249, RCVD_IN_DNSWL_NONE=-0.0001,
RCVD_IN_MSPIKE_H3=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001,
SPF_PASS=-0.001 autolearn=no autolearn_force=no
X-Spam_action: no action
X-Spam-Score: -0.8 (/)
X-Debbugs-Envelope-To: submit
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -1.8 (-)
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
Stefan Kangas <stefan@HIDDEN>:bug-gnu-emacs@HIDDEN.
Full text available.bug-gnu-emacs@HIDDEN:bug#50926; Package emacs.
Full text available.
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997 nCipher Corporation Ltd,
1994-97 Ian Jackson.