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

[Eric Abrahamsen <eric@ericabrahamsen.net>]

[-- Attachment #1: Type: text/plain, Size: 1995 bytes --]


On 07/23/20 20:43 PM, Eli Zaretskii wrote:
>> From: Eric Abrahamsen <eric@ericabrahamsen.net>
>> Cc: larsi@gnus.org,  37078@debbugs.gnu.org
>> Date: Thu, 23 Jul 2020 09:59:14 -0700
>> 
>> > 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.
>
> The introduction you wrote can mention the main points briefly, and
> then have a cross-reference to where the commands are described in
> full.  That way, both those who don't know "how to exit vim" will find
> what they need (and can follow the cross-reference to read the rest),
> and those who read the relevant chapter will have this information
> spelled out.

Okay, here's another stab at it. Since the sections have been slimmed
down I've just turned them into headings, which I think aids digestion
and removes the heading collision problem.

I feel like adding cross references to the first paragraph of "The
Basics of Servers, Groups, and Articles" has made it even harder to
parse, and am inclined to turn that into an unordered list of three
terms.

Otherwise, WDYT?

Eric


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: gnus-intro.diff --]
[-- Type: text/x-patch, Size: 6317 bytes --]

diff --git a/doc/misc/gnus.texi b/doc/misc/gnus.texi
index 2f4bc0cbf8..18db52eccd 100644
--- a/doc/misc/gnus.texi
+++ b/doc/misc/gnus.texi
@@ -402,6 +402,7 @@ Top
 @end iftex
 
 @menu
+* Don't Panic::              Your first 20 minutes with Gnus.
 * Starting Up::              Finding news can be a pain.
 * Group Buffer::             Selecting, subscribing and killing groups.
 * Summary Buffer::           Reading, saving and posting articles.
@@ -947,6 +948,140 @@ Top
 @end detailmenu
 @end menu
 
+@node Don't Panic
+@chapter Don't Panic
+@cindex don't panic
+@cindex introduction to Gnus
+
+Welcome, gentle user, to the Gnus newsreader and email client!  Gnus
+is unlike most clients, in part because of its endless
+configurability, in part because of its historical origins.  Gnus is
+now a fully-featured email client, but it began life as a Usenet-style
+newsreader, and its genes are still newsreader genes.  Thus it behaves
+a little differently than most mail clients.
+
+The typical assumptions of a newsreader are:
+
+@enumerate
+@item
+The server offers a potentially enormous number of newsgroups on a
+variety of subjects.  The user may only be interested in some of those
+groups, and more interested in some than others.
+@item
+Many groups 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.
+@item
+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.
+@end enumerate
+
+These assumptions lead to certain default Gnus behaviors:
+
+@enumerate
+@item
+Not all interesting groups are equally interesting, thus groups have
+varying degrees of ``subscribedness'', with different behavior
+depending on ``how subscribed'' a group is.
+@item
+There are many commands and tools for scoring and sorting articles,
+or otherwise sweeping them under the rug.
+@item
+Gnus will only show you groups with unread or ticked articles;
+groups with no new articles are hidden.
+@item
+When entering a group, only unread or ticked articles are shown,
+all other articles are hidden.
+@end enumerate
+
+If this seems draconian, think of it as Automatic 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 articles),
+but that takes some effort on the part of the user.
+
+The brief introduction below should be enough to get you off the
+ground.
+
+@heading The Basics of Servers, Groups, and Articles
+@cindex servers
+@cindex groups
+@cindex articles
+
+The fundamental building blocks of Gnus are @dfn{servers},
+@dfn{groups}, and @dfn{articles}.  Servers can be local or remote.
+Each server maintains a list of groups, and those groups contain
+articles.  Because Gnus presents a unified interface to a wide variety
+of servers, the vocabulary doesn't always quite line up (see @ref{FAQ
+- Glossary}, for a more complete glossary).  Thus a local maildir is
+referred to as a ``server'' (@pxref{Finding the News}) the same as a
+Usenet or IMAP server is; ``groups'' (@pxref{Group Buffer}) might mean
+an NNTP group, IMAP folder, or local mail directory; and an
+``article'' (@pxref{Summary Buffer}) might elsewhere be known as a
+message or an email.  Gnus employs unified terms for all these things.
+
+Servers fall into two general categories: ``news-like'', meaning that
+the articles are part of a public archive and can't be manipulated by
+the user; and ``mail-like'', meaning that the articles are owned by
+the user, who can freely edit them, move them around, and delete
+them.
+
+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{^}) and press @kbd{@key{RET}} on the server
+in question.  From here, Gnus provides commands to change or toggle
+your group subscriptions (@pxref{Browse Foreign Server}).
+
+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.
+
+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.
+
+
+@heading Fetching Mail
+
+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 latter case, Gnus provides for @code{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 articles.
+Mail sources are usually configured globally, but can be specified
+per-group (see @pxref{Mail Sources} for more information).
+
+@xref{Scanning New Messages} for details on fetching new mail.
+
+@heading Viewing Mail
+
+By default, Gnus's Group buffer only displays groups with unread
+articles.  It is always possible to display all the groups temporarily
+with @kbd{L}, and to configure Gnus to always display some groups
+(@pxref{Listing Groups}).
+
+@xref{Selecting a Group} for how to enter a group, and @pxref{Summary
+Buffer} for what to do once you're there.
+
+@heading Sending Mail
+
+New message composition can be initiated from the Group buffer
+(@pxref{Misc Group Stuff}).  If you're in a Summary buffer, you can
+compose replies and forward emails in addition to starting new
+messages, @xref{Summary Mail Commands} for details.
+
+For information about what happens once you've started composing a
+message, @xref{Composing Messages}.  For information on setting up
+@dfn{SMTP} servers in particular, @xref{Mail Variables, ,Mail
+Variables,message,Message manual}.
+
 @node Starting Up
 @chapter Starting Gnus
 @cindex starting up