From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Eric Abrahamsen Newsgroups: gmane.emacs.bugs Subject: bug#37078: 27.0.50; Proposal: new introductory section to the Gnus manual Date: Wed, 22 Jul 2020 13:16:45 -0700 Message-ID: <87sgdjtidu.fsf@ericabrahamsen.net> References: <87sgpym539.fsf@ericabrahamsen.net> <878spcn9d6.fsf@gnus.org> <878spck0xj.fsf@ericabrahamsen.net> <87h7u3o6ok.fsf@gnus.org> <87zh7uah73.fsf@ericabrahamsen.net> <87pn8qikkp.fsf@gnus.org> <87mu3u9i9g.fsf@ericabrahamsen.net> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="38849"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/28.0.50 (gnu/linux) Cc: 37078@debbugs.gnu.org To: Lars Ingebrigtsen Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Wed Jul 22 22:17:11 2020 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1jyLAs-0009xI-A4 for geb-bug-gnu-emacs@m.gmane-mx.org; Wed, 22 Jul 2020 22:17:10 +0200 Original-Received: from localhost ([::1]:37860 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jyLAr-00046z-Ah for geb-bug-gnu-emacs@m.gmane-mx.org; Wed, 22 Jul 2020 16:17:09 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:60452) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jyLAk-00046s-QD for bug-gnu-emacs@gnu.org; Wed, 22 Jul 2020 16:17:02 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:59793) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1jyLAk-0003oU-H9 for bug-gnu-emacs@gnu.org; Wed, 22 Jul 2020 16:17:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1jyLAk-0004ZL-9X for bug-gnu-emacs@gnu.org; Wed, 22 Jul 2020 16:17:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Eric Abrahamsen Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Wed, 22 Jul 2020 20:17:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 37078 X-GNU-PR-Package: emacs Original-Received: via spool by 37078-submit@debbugs.gnu.org id=B37078.159544901817550 (code B ref 37078); Wed, 22 Jul 2020 20:17:02 +0000 Original-Received: (at 37078) by debbugs.gnu.org; 22 Jul 2020 20:16:58 +0000 Original-Received: from localhost ([127.0.0.1]:43106 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jyLAg-0004Yz-3X for submit@debbugs.gnu.org; Wed, 22 Jul 2020 16:16:58 -0400 Original-Received: from ericabrahamsen.net ([52.70.2.18]:50458 helo=mail.ericabrahamsen.net) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jyLAb-0004Yh-IL for 37078@debbugs.gnu.org; Wed, 22 Jul 2020 16:16:57 -0400 Original-Received: from localhost (75-172-112-137.tukw.qwest.net [75.172.112.137]) (Authenticated sender: eric@ericabrahamsen.net) by mail.ericabrahamsen.net (Postfix) with ESMTPSA id 87895FA03D; Wed, 22 Jul 2020 20:16:47 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=ericabrahamsen.net; s=mail; t=1595449007; bh=0micjeT8wEe3VMhB66ydQ5zNkapALgDeK4k6Z8RK43c=; h=From:To:Cc:Subject:References:Date:In-Reply-To:From; b=qeVraSmJBJIsnzthggRCscq3fvv1W2/90fk0HLg2RaVHrTmEzCgJn+Pp0Wmslu9Jk COpeqougV2uSGArOwaGtDROeOpj1UNNwhyXo2KQ336GiifpWFazDbZ9d7CSumyieen ZF6l6FSTm2LCHljY2EAmkJlmC8T1rGAMGeUJDMu8= In-Reply-To: <87mu3u9i9g.fsf@ericabrahamsen.net> (Eric Abrahamsen's message of "Mon, 20 Jul 2020 11:02:51 -0700") X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.io gmane.emacs.bugs:183389 Archived-At: --=-=-= Content-Type: text/plain Eric Abrahamsen writes: > On 07/20/20 11:48 AM, Lars Ingebrigtsen wrote: >> Eric Abrahamsen 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 --=-=-= Content-Type: text/x-patch Content-Disposition: attachment; filename=gnus-intro.diff 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 --=-=-=--