From: Eric Abrahamsen <eric@ericabrahamsen.net>
To: Lars Ingebrigtsen <larsi@gnus.org>
Cc: 37078@debbugs.gnu.org
Subject: bug#37078: 27.0.50; Proposal: new introductory section to the Gnus manual
Date: Wed, 22 Jul 2020 13:16:45 -0700 [thread overview]
Message-ID: <87sgdjtidu.fsf@ericabrahamsen.net> (raw)
In-Reply-To: <87mu3u9i9g.fsf@ericabrahamsen.net> (Eric Abrahamsen's message of "Mon, 20 Jul 2020 11:02:51 -0700")
[-- Attachment #1: Type: text/plain, Size: 1000 bytes --]
Eric Abrahamsen <eric@ericabrahamsen.net> writes:
> On 07/20/20 11:48 AM, Lars Ingebrigtsen wrote:
>> Eric Abrahamsen <eric@ericabrahamsen.net> writes:
>>
>>> Yes! The text itself is done (I incorporated some comments from
>>> gnus.general folks), I just need to format it as texinfo and add the
>>> internal links, then can post a proper commit for inspection.
>>
>> Great!
>
> Here's the diff I've got now. I've tried to sneak it in there without
> running any of texinfo-mode's "update the whole world" commands, because
> that dumps a whole bunch of new text into the file, all over the place,
> and I don't know texinfo well enough to know why it's doing that. On the
> other hand, "make" barfs a huge number of warnings, so something needs
> to be updated, I just don't know what.
Okay, I tiptoed through the violets and managed to make a diff that
raises no warnings and produces the expected output. I also did some
tweaking and edits. If no one hates this, I'll push in a few days.
Eric
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: gnus-intro.diff --]
[-- Type: text/x-patch, Size: 7638 bytes --]
diff --git a/doc/misc/gnus.texi b/doc/misc/gnus.texi
index 2f4bc0cbf8..9ee7a8c1df 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.
@@ -432,6 +433,13 @@ Top
@detailmenu
--- The Detailed Node Listing ---
+Don't Panic
+
+* Servers Groups and Articles:: What Gnus is made of.
+* How to Get Mail:: Where does mail come from?
+* How to View Mail:: How do I see it?
+* How to Send Mail:: How do I send it?
+
Starting Gnus
* Finding the News:: Choosing a method for getting news.
@@ -947,6 +955,158 @@ Top
@end detailmenu
@end menu
+@node Don't Panic
+@chapter Don't Panic
+
+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 DNA is still newsreader DNA. 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.
+
+@menu
+* Servers Groups and Articles:: What Gnus is made of.
+* How to Get Mail:: Where does mail come from?
+* How to View Mail:: How do I see it?
+* How to Send Mail:: How do I send it?
+@end menu
+
+@node Servers Groups and Articles
+@section Servers, Groups, and Articles
+
+The fundamental building blocks of Gnus are servers, groups, and
+articles. Servers can be local or remote. They maintain 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 @pxref{FAQ - Glossary} 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.
+
+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{^}), press @kbd{@key{RET}} the server in
+question, and toggle subscription to individual groups using @kbd{u}.
+
+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.
+
+
+@node How to Get Mail
+@section How to Get 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 second 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).
+
+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}).
+
+@node How to View Mail
+@section How to View 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 (see
+@pxref{Listing Groups}). The @kbd{j} key will prompt for a group name
+and jump to it, displaying it if it was hidden.
+
+Press @kbd{@key{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
+@kbd{@key{RET}} before entering the group, or by pressing @kbd{/ o}
+once the group is open.
+
+Articles can be opened and scrolled using @kbd{@key{RET}} and/or
+@kbd{@key{SPC}}, and @kbd{n} will select the next article.
+
+@node How to Send Mail
+@section How to Send Mail
+
+When sending messages, too, Gnus makes a distinction between news-like
+and mail-like behavior. News servers handle delivery themselves, and
+no additional configuration is necessary. Begin composing a news
+article using the @kbd{a} key in the Group buffer, or @kbd{F} if
+you're in a group and replying to an article.
+
+Mail message composition starts with @kbd{m} in the Group buffer, or
+@kbd{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 @code{message-send-mail-function} @xref{Mail Variables, ,Mail
+Variables,message,Message manual}.
+
@node Starting Up
@chapter Starting Gnus
@cindex starting up
next prev parent reply other threads:[~2020-07-22 20:16 UTC|newest]
Thread overview: 20+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-08-18 23:22 bug#37078: 27.0.50; Proposal: new introductory section to the Gnus manual Eric Abrahamsen
2019-08-27 2:04 ` Stefan Kangas
2019-10-22 14:27 ` Lars Ingebrigtsen
2019-10-22 19:58 ` Eric Abrahamsen
2020-07-19 15:39 ` Lars Ingebrigtsen
2020-07-20 5:28 ` Eric Abrahamsen
2020-07-20 9:48 ` Lars Ingebrigtsen
2020-07-20 18:02 ` Eric Abrahamsen
2020-07-22 20:16 ` Eric Abrahamsen [this message]
2020-07-23 13:03 ` Eli Zaretskii
2020-07-23 15:13 ` Robert Pluim
2020-07-23 15:29 ` Eric Abrahamsen
2020-07-23 16:59 ` Eric Abrahamsen
2020-07-23 17:43 ` Eli Zaretskii
2020-07-24 18:49 ` Eric Abrahamsen
2020-07-24 19:08 ` Eli Zaretskii
2020-07-24 21:08 ` Eric Abrahamsen
2020-07-25 6:11 ` Eli Zaretskii
2020-07-27 22:32 ` Eric Abrahamsen
2020-07-27 21:48 ` Lars Ingebrigtsen
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87sgdjtidu.fsf@ericabrahamsen.net \
--to=eric@ericabrahamsen.net \
--cc=37078@debbugs.gnu.org \
--cc=larsi@gnus.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.