bug#37078: 27.0.50; Proposal: new introductory section to the Gnus manual

[Eric Abrahamsen]

On 07/23/20 16:03 PM, Eli Zaretskii wrote:
>> From: Eric Abrahamsen <eric@ericabrahamsen.net>
>> 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.

My pleasure! I like manuals.

> 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?

I did that in the menu listing ("Don't Panic::   Your first 20 minutes
with Gnus"), because you're right it's a meaningless title otherwise. I
can add that subtitle in to the text itself. If I knew texinfo better, I
suspect there's a way to have the heading display differently in
different places.

> 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

Got it, will do.

>> +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.

Hmm, maybe "genes" then...

>> +@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.

Got it.

>> +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.

Yes, obviously I wasn't looking at the output. I'll try Robert's dwim
command, too.

>> +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.

I guess I was expecting that things like NNTP, IMAP and maildir would be
already familiar, while "server", "group" and "article" were the things
we'd need to explain. I'll see if I can add in more cross references.

>> +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}.

See below...

>> +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?

The thing is it's really data, lots of it, stored in many different
directories and files. "Configuration" sounds to me like an elisp file
with some setqs in it. I'm not married to "installation", but can't
think of anything more appropriate.

>> +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.

We had a bit of discussion on gnus.general about this. My feeling is
that Gnus has a "how do I exit vim" problem: people start it up, can't
figure out why they can't see their email, bang on the keyboard a bit,
then rage quit. I figured it would only take a tiny bit of information
to fix that: the fact that Gnus hides read groups/articles by default,
and the ~eight commands necessary to do basic maneuvering. Other people
felt it was weird to combine conceptual overviews with a handful of
keybindings, and I can understand that. But I really meant this section
to be "get to usability in 20 minutes".

But you're right that the three fetching/reading/sending sections
shouldn't be there (the fact that I was getting chapter name collisions
should have been a clue). I'll check the existing sections and see if
they can be made to provide an easier on-ramp, then just link to those.

Thanks for the review,
Eric