From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#50926: Light edits to the Emacs Manual (screen.texi) Date: Fri, 01 Oct 2021 10:20:10 +0300 Message-ID: <834ka1fbyt.fsf@gnu.org> References: Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="12496"; mail-complaints-to="usenet@ciao.gmane.io" Cc: 50926@debbugs.gnu.org To: Stefan Kangas Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Fri Oct 01 09:29:50 2021 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1mWCzN-0002zy-4V for geb-bug-gnu-emacs@m.gmane-mx.org; Fri, 01 Oct 2021 09:29:49 +0200 Original-Received: from localhost ([::1]:39156 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mWCzM-0004NR-1E for geb-bug-gnu-emacs@m.gmane-mx.org; Fri, 01 Oct 2021 03:29:48 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:37990) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mWCqs-0003Rr-Fw for bug-gnu-emacs@gnu.org; Fri, 01 Oct 2021 03:21:02 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:43026) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1mWCqs-0003rW-4k for bug-gnu-emacs@gnu.org; Fri, 01 Oct 2021 03:21:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1mWCqs-0004au-0P for bug-gnu-emacs@gnu.org; Fri, 01 Oct 2021 03:21:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 01 Oct 2021 07:21:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 50926 X-GNU-PR-Package: emacs Original-Received: via spool by 50926-submit@debbugs.gnu.org id=B50926.163307285517622 (code B ref 50926); Fri, 01 Oct 2021 07:21:01 +0000 Original-Received: (at 50926) by debbugs.gnu.org; 1 Oct 2021 07:20:55 +0000 Original-Received: from localhost ([127.0.0.1]:54571 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mWCql-0004a9-73 for submit@debbugs.gnu.org; Fri, 01 Oct 2021 03:20:55 -0400 Original-Received: from eggs.gnu.org ([209.51.188.92]:32768) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mWCqi-0004Zy-4J for 50926@debbugs.gnu.org; Fri, 01 Oct 2021 03:20:53 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:44144) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mWCqY-0003US-6r; Fri, 01 Oct 2021 03:20:46 -0400 Original-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 ) id 1mWCqL-0006X4-Vm; Fri, 01 Oct 2021 03:20:40 -0400 In-Reply-To: (message from Stefan Kangas on Fri, 1 Oct 2021 01:51:04 +0200) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.io gmane.emacs.bugs:216008 Archived-At: > From: Stefan Kangas > 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 ;-)