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

[Eric Abrahamsen]

Gnus has a great big manual, but it's a little difficult to dive into.
The manual itself states that it isn't a tutorial, and that's true! The
text I'm proposing to add isn't a tutorial either, but it's sort of a
"start here" section, which I've titled Don't Panic. It's meant to be a
brief orientation, and a crash course in the style of the vim tutorials
that start with how to quit vim. If this goes in, we might want to
change or remove the existing "Mail in a Newsreader" section of the
manual, which covers some of the same ground, but which I find more
panic-inducing than not :)

I'll post this to gnus.general in a second, as well.


                             ━━━━━━━━━━━━━
                              DON’T PANIC
                             ━━━━━━━━━━━━━


Welcome, gentle user, to the Gnus newsreader and email client! Gnus is
unlike most clients, in part because of its gross configurability, and
in part because of its historical origins. While Gnus is now a
fully-featured email client, it began life as a newsreader, and its DNA
is still newsreader DNA. Thus it behaves a little differently than most
mail clients.

The typical assumptions of a newsreader are:

1. The news server offers a potentially enormous number of newsgroups to
   read. The user may only be interested in some of those groups, and
   more interested in some than others.
2. Groups probably see a high volume of articles, and the user won’t
   want to read all of them. Mechanisms are needed for foregrounding
   interesting articles, and backgrounding uninteresting articles.
3. Once a group has been scanned and dealt with by the user, it’s
   unlikely to be of further interest until new articles come in.

These assumptions lead to certain default Gnus behaviors:

1. Not all interesting groups are equally interesting, thus there are
   varying degrees of “subscribedness”, with different behavior
   depending on “how subscribed” a group is.
2. There are a large number of commands and tools for scoring and
   sorting articles, or otherwise sweeping them under the rug.
3. Gnus will only show you groups with unread or ticked articles; groups
   with no new articles are hidden.
4. When entering a group, only unread or ticked articles are shown, all
   other articles are hidden.

If this seems draconian, think of it as Enforced Inbox Zero. This is the
way Gnus works by default. It is possible to make it work more like an
email client (always showing read groups and read messages), but that
will take some effort on the part of the user, and Gnus won’t ever
really like it.

The brief introduction below should be enough to get you off the ground.


Servers, Groups, and Articles
═════════════════════════════

  The fundamental building blocks of Gnus are servers, groups, and
  articles. Servers represent stores of articles, either local or
  remote. A server maintains a list of groups, and those groups contain
  articles. Because Gnus presents a unified interface to wide variety of
  servers, the vocabulary doesn’t always quite line up (see XXX for a
  more complete 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. Gnus employs
  unified terms for all these things.

  A Gnus installation is basically just a list of one or more servers,
  plus the user’s subscribed groups from those servers.

  Servers can be added and configured in two places: in the user’s
  gnus.el startup file, using the `gnus-select-method’ and
  `gnus-secondary-select-methods’ options, or within Gnus itself using
  commands in the *Server* buffer. See XXX for details.

  Some servers (including the more mail-like servers) will automatically
  subscribe the user to all their groups. Other servers (more news-like)
  will not. In the latter case, it’s necessary to enter the *Server*
  buffer (with “^”), press return on the server in question, and then
  subscribe to individual groups using “u”.


Getting Mail
════════════

  New mail has to come from somewhere. Some servers, such as NNTP or
  IMAP, are themselves responsible for adding 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 “mail sources”: places where new
  mail is fetched from. A mail source might be a local spool, or a
  remote POP server, or some other source of incoming messages. Mail
  sources are usually configured globally, but can be specified
  per-group (see XXX for more information).

  The “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 XXX).


Viewing Mail
════════════

  By default, Gnus’s *Group* buffer only displays groups with unread
  messages. It is always possible to display all the groups temporarily
  with “L”, and to configure Gnus to always display some groups (see
  XXX). The “j” key will prompt for a group name and jump to it,
  displaying it if necessary.

  Press “RET” on a group to enter it: by default Gnus will only show
  unread and ticked articles. It’s possible to see already-read mail,
  either by giving a prefix argument to “RET” before entering the group,
  or by pressing “/ o” once the group is open.

  Articles can be opened and scrolled using “RET” and/or “SPC”, and “n”
  will select the next message.


Sending Mail
════════════

  When sending messages, too, Gnus makes a distinction between news-like
  and mail-like behavior. News servers handle mail delivery themselves,
  and no additional configuration is necessary. Begin composing a news
  article using the “a” key in the *Group* buffer, or “f” if you’re in a
  group and replying to an article.

  Mail message composition starts with “m” in the *Group* buffer, or “r”
  if you’re replying to an existing message. Because mail is sent with
  SMTP, which is an entirely separate process from the mail-reading
  servers, it must also be configured separately, with the option
  `message-send-mail-function’ (see XXX).