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#37078: 27.0.50; Proposal: new introductory section to the Gnus manual Date: Thu, 23 Jul 2020 16:03:39 +0300 Message-ID: <838sfafkno.fsf@gnu.org> References: <87sgpym539.fsf@ericabrahamsen.net> <878spcn9d6.fsf@gnus.org> <878spck0xj.fsf@ericabrahamsen.net> <87h7u3o6ok.fsf@gnus.org> <87zh7uah73.fsf@ericabrahamsen.net> <87pn8qikkp.fsf@gnus.org> <87mu3u9i9g.fsf@ericabrahamsen.net> <87sgdjtidu.fsf@ericabrahamsen.net> Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="6472"; mail-complaints-to="usenet@ciao.gmane.io" Cc: larsi@gnus.org, 37078@debbugs.gnu.org To: Eric Abrahamsen Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Thu Jul 23 15:05:12 2020 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 1jyauN-0001Zt-CC for geb-bug-gnu-emacs@m.gmane-mx.org; Thu, 23 Jul 2020 15:05:11 +0200 Original-Received: from localhost ([::1]:60560 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jyauM-0002ql-Dy for geb-bug-gnu-emacs@m.gmane-mx.org; Thu, 23 Jul 2020 09:05:10 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:46118) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jyauE-0002ov-2Y for bug-gnu-emacs@gnu.org; Thu, 23 Jul 2020 09:05:02 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:32814) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1jyauD-0001CU-OF for bug-gnu-emacs@gnu.org; Thu, 23 Jul 2020 09:05:01 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1jyauD-0006eI-JY for bug-gnu-emacs@gnu.org; Thu, 23 Jul 2020 09:05:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 23 Jul 2020 13:05:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 37078 X-GNU-PR-Package: emacs Original-Received: via spool by 37078-submit@debbugs.gnu.org id=B37078.159550944525489 (code B ref 37078); Thu, 23 Jul 2020 13:05:01 +0000 Original-Received: (at 37078) by debbugs.gnu.org; 23 Jul 2020 13:04:05 +0000 Original-Received: from localhost ([127.0.0.1]:44360 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jyatI-0006d1-VK for submit@debbugs.gnu.org; Thu, 23 Jul 2020 09:04:05 -0400 Original-Received: from eggs.gnu.org ([209.51.188.92]:52172) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jyatG-0006cX-84 for 37078@debbugs.gnu.org; Thu, 23 Jul 2020 09:04:03 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:41156) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jyatA-0000ws-Ms; Thu, 23 Jul 2020 09:03:56 -0400 Original-Received: from [176.228.60.248] (port=3270 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1jyat9-0003LC-MG; Thu, 23 Jul 2020 09:03:56 -0400 In-Reply-To: <87sgdjtidu.fsf@ericabrahamsen.net> (message from Eric Abrahamsen on Wed, 22 Jul 2020 13:16:45 -0700) 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:183421 Archived-At: > From: Eric Abrahamsen > Date: Wed, 22 Jul 2020 13:16:45 -0700 > Cc: 37078@debbugs.gnu.org First and foremost, thank you for working on improvements of the Gnus manual! This is a very important job, IMO. When reading my comments below, please keep in mind that I don't use Gnus. > +@node Don't Panic > +@chapter Don't Panic A node name such as this is okay, but I wonder whether the chapter should be named "Don't Panic: An Introduction to Gnus Concepts", as that is what it is, right? Also, it is generally a good idea to have a @cindex entry or entries at the beginning of each node which summarize(s) the topic(s) of the node. Think about a reader who wants to find this node quickly using the Info-index command. In this case, I suggest @cindex introduction to Gnus @cindex don't panic > +newsreader, and its DNA is still newsreader DNA. Thus it behaves a Texinfo markup note: it is best to use @acronym, as in @acronym{DNA}, when you use acronyms. Also, consider explaining in parentheses the meaning of an acronym when you first use it, as not every reader might know what "DNA" stands for. > +@node Servers Groups and Articles > +@section Servers, Groups, and Articles This section describes the basic terminology used by Gnus, so perhaps this should be reflected in the node/chapter name? It definitely should be reflected in a @cindex entry here. > +The fundamental building blocks of Gnus are servers, groups, and > +articles. Our documentation conventions call for using @dfn the first time you mention a certain term, as in The fundamental building blocks of Gnus are @dfn{servers}, @dfn{groups}, and @dfn{articles}. In addition, each time you use @dfn, it is a good idea to have a @cindex entry for that term -- this is useful when the reader wants later to re-read the explanations of what each term means. > +always quite line up (see @pxref{FAQ - Glossary} for a more complete ^^^^^^^^^^ "see @ref" (@pxref produces "see" on its own), and make a point of having some punctuation after the closing brace, in this case a comma will do. > +glossary). Thus a local maildir is referred to as a ``server'' the > +same as a Usenet or IMAP server is; ``group'' might mean an NNTP > +group, IMAP folder, or local mail directory; and an ``article'' might > +elsewhere be known as a message or an email. You dump many terms and acronyms on the reader here, but never explain them. That is okay in itself, but please keep in mind that some people have limited attention span, and a lot of abstract descriptions with little or nothing to connect that to real-life experiences will turn them off and lose them. One method of keeping them reading is to have cross-references to where each term is discussed in detail. This is also good for those readers who only want to read part of your introduction: they can get as far as they want to go, and then jump directly to the detailed descriptions of what they are after. So terms like "server", "group", "article", "maildir", IMAP, etc. beg for a cross-reference to where the details of handling those are described. > +For news-like servers, which typically offer hundreds or thousands of > +groups, it's important to be able to subscribe to a subset of those > +groups. For mail-like servers, the user is generally automatically > +subscribed to all groups (though IMAP, for example, also allows > +selective subscription). To change group subscription, enter the > +Server buffer (with @kbd{^}), press @kbd{@key{RET}} the server in > +question, and toggle subscription to individual groups using @kbd{u}. Does the command to change group subscription really belong here? Wouldn't it be better to say something like the below instead: Gnus has commands to change or toggle your group subscriptions, see @ref{Wherever the ^ command is described}. > +A Gnus installation is basically just a list of one or more servers, > +plus the user's subscribed groups from those servers, plus articles in > +those groups. Is "installation" really the right term here? Would "configuration" be better, perhaps? > +Servers can be added and configured in two places: in the user's > +gnus.el startup file, using the @code{gnus-select-method} and > +@code{gnus-secondary-select-methods} options, or within Gnus itself > +using interactive commands in the Server buffer. See @pxref{Finding > +the News} for details. ^^^^^^^^^^ Just @xref (without the "See" part, which @xref produces by itself) will do. > +@node How to Get Mail > +@section How to Get Mail I would suggest @node Reading Mail with Gnus @section Reading Mail with Gnus @cindex reading mail with Gnus > +New mail has to come from somewhere. Some servers, such as NNTP or > +IMAP, are themselves responsible for fetching newly-arrived articles. > +Others, such as maildir or mbox servers, only store articles and don't > +fetch them from anywhere. > + > +In the second case, Gnus provides for @code{mail sources}: places ^^^^^^ "latter", not "second". > +The @kbd{g} key is used to update Gnus and fetch new mail. Servers > +that fetch their own mail will do so; additionally, all the mail > +sources will be scanned for new mail. That incoming mail will then be > +split into local servers according to the users splitting rules (see > +@pxref{Splitting Mail}). It is strange to have descriptions of user commands in an introductory section. Shouldn't this be elsewhere, like in the "Fetching Mail" section (which strangely says nothing about how to trigger mail fetching)? Also, it is our convention to name the command invoked by a key sequence in parentheses; this is useful if there's ever a need to invoke the command by name, or if it is rebound to another key. Sadly, the Gnus manual doesn't seem to follow this convention, but it's never late to start! And finally, the same "see @pxref" mistake again. > +@node How to View Mail > +@section How to View Mail Most of this section should be somewhere under "Getting Mail" chapter, IMO, with only a short mention of that in the introductory chapter. > +@node How to Send Mail > +@section How to Send Mail Most of this section should be under the "Composing Messages" chapter, IMO. Thanks again for working on this.