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

[Eli Zaretskii <eliz@gnu.org>]

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

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.