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: Mon, 20 Jul 2020 11:02:51 -0700 Message-ID: <87mu3u9i9g.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> 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="22168"; 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 Mon Jul 20 20:04:29 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 1jxa9M-0005dT-UE for geb-bug-gnu-emacs@m.gmane-mx.org; Mon, 20 Jul 2020 20:04:29 +0200 Original-Received: from localhost ([::1]:60528 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jxa9M-00050g-0T for geb-bug-gnu-emacs@m.gmane-mx.org; Mon, 20 Jul 2020 14:04:28 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:57392) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jxa8w-0004ng-2f for bug-gnu-emacs@gnu.org; Mon, 20 Jul 2020 14:04:02 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:52712) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1jxa8v-0000tI-QK for bug-gnu-emacs@gnu.org; Mon, 20 Jul 2020 14:04:01 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1jxa8v-0005vV-Ku for bug-gnu-emacs@gnu.org; Mon, 20 Jul 2020 14:04:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Eric Abrahamsen Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 20 Jul 2020 18:04:01 +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.159526818222699 (code B ref 37078); Mon, 20 Jul 2020 18:04:01 +0000 Original-Received: (at 37078) by debbugs.gnu.org; 20 Jul 2020 18:03:02 +0000 Original-Received: from localhost ([127.0.0.1]:36025 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jxa7x-0005ty-L1 for submit@debbugs.gnu.org; Mon, 20 Jul 2020 14:03:02 -0400 Original-Received: from ericabrahamsen.net ([52.70.2.18]:43984 helo=mail.ericabrahamsen.net) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jxa7v-0005tj-80 for 37078@debbugs.gnu.org; Mon, 20 Jul 2020 14:03:00 -0400 Original-Received: from localhost (c-73-254-86-141.hsd1.wa.comcast.net [73.254.86.141]) (Authenticated sender: eric@ericabrahamsen.net) by mail.ericabrahamsen.net (Postfix) with ESMTPSA id CC7A9FA03D; Mon, 20 Jul 2020 18:02:52 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=ericabrahamsen.net; s=mail; t=1595268173; bh=n4HQJjPF7mLN/3J9IcMQGJcYFxTFT+LmUbBG04x9t4k=; h=From:To:Cc:Subject:References:Date:In-Reply-To:From; b=uRCokz7dDCXeW5ytB72XEFJve3559clT+TEwAdWjDmDY43zFLRtz6OAXGk4PRZ8P/ IGbzg6cHbT/mt473lGOUdDwlHOQlU0+6yZ24DUsWTgWlMviPpb2FCQfMF2eh0oF9hB Ac9M3ZP8klVkp4lUph6WqrDotIq9lWrageEzCnxQ= In-Reply-To: <87pn8qikkp.fsf@gnus.org> (Lars Ingebrigtsen's message of "Mon, 20 Jul 2020 11:48:06 +0200") 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:183319 Archived-At: --=-=-= Content-Type: text/plain 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. --=-=-= 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..572b3b8403 100644 --- a/doc/misc/gnus.texi +++ b/doc/misc/gnus.texi @@ -974,6 +974,7 @@ Starting Up terminology section (@pxref{Terminology}). @menu +* Don't Panic:: Your first 20 minutes with Gnus. * Finding the News:: Choosing a method for getting news. * The Server is Down:: How can I read my mail then? * Child Gnusae:: You can have more than one Gnus active at a time. @@ -985,8 +986,154 @@ Starting Up * Startup Variables:: Other variables you might change. @end menu +@node Don't Panic, , Starting Up, Starting Up +@section Don't Panic -@node Finding the News +Welcome, gentle user, to the Gnus newsreader and email client! Gnus +is unlike most clients, in part because of its endless +configurability, and 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 there are +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. + + +@node Servers Groups and Articles, Getting Mail, Starting Up, Top +@unnumbered 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 a wide variety +of servers, the vocabulary doesn't always quite line up (see +@pxref{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 then subscribe 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 Getting Mail, Viewing Mail, Servers Groups and Articles, Top +@unnumbered Getting 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 Viewing Mail, Sending Mail, Getting Mail, Top +@unnumbered 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 (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 Sending Mail, Group Buffer, Viewing Mail, Top +@unnumbered Sending 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 Finding the News, The Server is Down, Sending Mail, Sending Mail @section Finding the News @cindex finding news --=-=-=--