From debbugs-submit-bounces@debbugs.gnu.org Sun Aug 18 19:22:53 2019 Received: (at submit) by debbugs.gnu.org; 18 Aug 2019 23:22:53 +0000 Received: from localhost ([127.0.0.1]:58928 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hzUVh-00055V-0y for submit@debbugs.gnu.org; Sun, 18 Aug 2019 19:22:53 -0400 Received: from lists.gnu.org ([209.51.188.17]:60868) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hzUVe-00055M-Id for submit@debbugs.gnu.org; Sun, 18 Aug 2019 19:22:51 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:51277) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1hzUVc-00008z-P8 for bug-gnu-emacs@gnu.org; Sun, 18 Aug 2019 19:22:50 -0400 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=-1.5 required=5.0 tests=BAYES_50,RCVD_IN_DNSWL_MED autolearn=disabled version=3.3.2 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1hzUVb-0002Fu-2n for bug-gnu-emacs@gnu.org; Sun, 18 Aug 2019 19:22:48 -0400 Received: from ericabrahamsen.net ([52.70.2.18]:53278 helo=mail.ericabrahamsen.net) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1hzUVa-0002Dk-VA for bug-gnu-emacs@gnu.org; Sun, 18 Aug 2019 19:22:47 -0400 Received: from localhost (unknown [36.110.118.85]) (Authenticated sender: eric@ericabrahamsen.net) by mail.ericabrahamsen.net (Postfix) with ESMTPSA id D4931FA026 for ; Sun, 18 Aug 2019 23:22:38 +0000 (UTC) From: Eric Abrahamsen To: bug-gnu-emacs@gnu.org Subject: 27.0.50; Proposal: new introductory section to the Gnus manual Date: Mon, 19 Aug 2019 07:22:34 +0800 Message-ID: <87sgpym539.fsf@ericabrahamsen.net> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 52.70.2.18 X-Spam-Score: -1.4 (-) X-Debbugs-Envelope-To: submit X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -2.4 (--) 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. =E2=94=81=E2=94=81=E2=94=81=E2=94=81=E2=94=81=E2=94=81=E2=94=81=E2= =94=81=E2=94=81=E2=94=81=E2=94=81=E2=94=81=E2=94=81 DON=E2=80=99T PANIC =E2=94=81=E2=94=81=E2=94=81=E2=94=81=E2=94=81=E2=94=81=E2=94=81=E2= =94=81=E2=94=81=E2=94=81=E2=94=81=E2=94=81=E2=94=81 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=E2=80=99t 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=E2=80=99s 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 =E2=80=9Csubscribedness=E2=80=9D, with different beha= vior depending on =E2=80=9Chow subscribed=E2=80=9D 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=E2=80=99t ever really like it. The brief introduction below should be enough to get you off the ground. Servers, Groups, and Articles =E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2= =95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95= =90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90= =E2=95=90=E2=95=90=E2=95=90=E2=95=90 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=E2=80=99t always quite line up (see XXX for= a more complete glossary). Thus a local maildir is referred to as a =E2=80=9Cserver=E2=80=9D the same as a Usenet or IMAP server is; =E2=80= =9Cgroup=E2=80=9D might mean an NNTP group, IMAP folder, or local mail directory; and an =E2=80=9Carticle= =E2=80=9D 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=E2=80=99s subscribed groups from those servers. Servers can be added and configured in two places: in the user=E2=80=99s gnus.el startup file, using the `gnus-select-method=E2=80=99 and `gnus-secondary-select-methods=E2=80=99 options, or within Gnus itself us= ing 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=E2=80=99s necessary to enter the *Server* buffer (with =E2=80=9C^=E2=80=9D), press return on the server in question= , and then subscribe to individual groups using =E2=80=9Cu=E2=80=9D. Getting Mail =E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2= =95=90=E2=95=90=E2=95=90=E2=95=90 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=E2= =80=99t fetch them from anywhere. In the second case, Gnus provides for =E2=80=9Cmail sources=E2=80=9D: pla= ces 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 =E2=80=9Cg=E2=80=9D key is used to update Gnus and fetch new mail. Se= rvers 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 =E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2= =95=90=E2=95=90=E2=95=90=E2=95=90 By default, Gnus=E2=80=99s *Group* buffer only displays groups with unread messages. It is always possible to display all the groups temporarily with =E2=80=9CL=E2=80=9D, and to configure Gnus to always display some gr= oups (see XXX). The =E2=80=9Cj=E2=80=9D key will prompt for a group name and jump t= o it, displaying it if necessary. Press =E2=80=9CRET=E2=80=9D on a group to enter it: by default Gnus will = only show unread and ticked articles. It=E2=80=99s possible to see already-read mai= l, either by giving a prefix argument to =E2=80=9CRET=E2=80=9D before enteri= ng the group, or by pressing =E2=80=9C/ o=E2=80=9D once the group is open. Articles can be opened and scrolled using =E2=80=9CRET=E2=80=9D and/or = =E2=80=9CSPC=E2=80=9D, and =E2=80=9Cn=E2=80=9D will select the next message. Sending Mail =E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2=95=90=E2= =95=90=E2=95=90=E2=95=90=E2=95=90 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 =E2=80=9Ca=E2=80=9D key in the *Group* buffer, or =E2= =80=9Cf=E2=80=9D if you=E2=80=99re in a group and replying to an article. Mail message composition starts with =E2=80=9Cm=E2=80=9D in the *Group* b= uffer, or =E2=80=9Cr=E2=80=9D if you=E2=80=99re replying to an existing message. Because mail is sent w= ith 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=E2=80=99 (see XXX). From debbugs-submit-bounces@debbugs.gnu.org Mon Aug 26 22:05:07 2019 Received: (at 37078) by debbugs.gnu.org; 27 Aug 2019 02:05:07 +0000 Received: from localhost ([127.0.0.1]:47418 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1i2Qr5-0000CW-4o for submit@debbugs.gnu.org; Mon, 26 Aug 2019 22:05:07 -0400 Received: from mail-pg1-f170.google.com ([209.85.215.170]:34295) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1i2Qr3-0000Bx-Tb for 37078@debbugs.gnu.org; Mon, 26 Aug 2019 22:05:06 -0400 Received: by mail-pg1-f170.google.com with SMTP id n9so11714857pgc.1 for <37078@debbugs.gnu.org>; Mon, 26 Aug 2019 19:05:05 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc:content-transfer-encoding; bh=cQbdJyy0pOIldtbWYuEJKc8yn6UsmPvWj4hv7RkxOu8=; b=U1+wd0TRgwuuKwYRSyHg7Yu+lE6v2XMNatIY+eiPBgd4K0WM0Ge8i2Wuji/sxSzxN7 7rgoYOz+2wSYm9KGVFFwE2deBYIJLXgyhjB0UX85qfAjHAsnUq6KFznCiuKD+hmZXf8Q MjlB+vofSqnQhHCaut8n5HdxZ/Ccz52dUdh7ezWmlzjJT5Z+Z+U74516U9QpYrowEjSx TCv2ExL6BUHF/JvAuvRy/UnrAi8/GYrgiL6AGy+QhuHRXkhBcEklx3XQe+rZGI0pyEBL Jht3+2KDlNduzGXKaIXzS0teyV1/1vi1Gy+SHWE+5KZWh7+KS+tup0aK1vKcVfb0hCm2 j4dQ== X-Gm-Message-State: APjAAAU5nLuDcwrbgPaSXtNXBEeVusvhMJPDfzeSfLQ5HOapxph0JUow NA3+dTmGCaSo+FkYIp78A/1RmuyqqbHEyWLoY3RUBg== X-Google-Smtp-Source: APXvYqzZbFZwtOXAr59Jl5toAjf+6k+7Ial4ax2SzrbNgN/ZvdjuTsqAaBwiObUexRuSEnJYrznFgcE0dqi9ULcYV2U= X-Received: by 2002:a17:90a:c086:: with SMTP id o6mr6954310pjs.2.1566871500062; Mon, 26 Aug 2019 19:05:00 -0700 (PDT) MIME-Version: 1.0 References: <87sgpym539.fsf@ericabrahamsen.net> In-Reply-To: <87sgpym539.fsf@ericabrahamsen.net> From: Stefan Kangas Date: Tue, 27 Aug 2019 04:04:49 +0200 Message-ID: Subject: Re: bug#37078: 27.0.50; Proposal: new introductory section to the Gnus manual To: Eric Abrahamsen Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable X-Spam-Score: 0.5 (/) X-Debbugs-Envelope-To: 37078 Cc: 37078@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -0.5 (/) Eric Abrahamsen writes: > Gnus has a great big manual, but it's a little difficult to dive into. I remember diving into Gnus 10 years ago and using it for a good 4-5 years. I can testify the initial setup was a bit daunting, and having read your proposal, I think it's a good introduction for beginners. > 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. Should we perhaps mention what "newsreader" means in this context? I suspect that a lot of people would read that as "RSS reader". Usenet is of course still around, but it's not commonly known that it even exists, in my experience. > 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. This makes sense if one knows basically what Usenet is already. > A Gnus installation is basically just a list of one or more servers, > plus the user=E2=80=99s subscribed groups from those servers. I would imagine that the groups contain articles. Perhaps that's worth mentioning. With those minor comments, I think it's a good addition to the Gnus manual. Thanks, Stefan Kangas From debbugs-submit-bounces@debbugs.gnu.org Tue Oct 22 10:27:39 2019 Received: (at 37078) by debbugs.gnu.org; 22 Oct 2019 14:27:39 +0000 Received: from localhost ([127.0.0.1]:60264 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1iMv8M-0000lw-OR for submit@debbugs.gnu.org; Tue, 22 Oct 2019 10:27:38 -0400 Received: from quimby.gnus.org ([80.91.231.51]:42586) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1iMv8L-0000lo-BN for 37078@debbugs.gnu.org; Tue, 22 Oct 2019 10:27:37 -0400 Received: from cm-84.212.202.86.getinternet.no ([84.212.202.86] helo=marnie) by quimby.gnus.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.89) (envelope-from ) id 1iMv8H-0005xz-Of; Tue, 22 Oct 2019 16:27:36 +0200 From: Lars Ingebrigtsen To: Eric Abrahamsen Subject: Re: bug#37078: 27.0.50; Proposal: new introductory section to the Gnus manual References: <87sgpym539.fsf@ericabrahamsen.net> Date: Tue, 22 Oct 2019 16:27:33 +0200 In-Reply-To: <87sgpym539.fsf@ericabrahamsen.net> (Eric Abrahamsen's message of "Mon, 19 Aug 2019 07:22:34 +0800") Message-ID: <878spcn9d6.fsf@gnus.org> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.0.50 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Spam-Report: Spam detection software, running on the system "quimby.gnus.org", has NOT identified this incoming email as spam. The original message has been attached to this so you can view it or label similar future email. If you have any questions, see @@CONTACT_ADDRESS@@ for details. Content preview: Eric Abrahamsen writes: > I'll post this to gnus.general in a second, as well. Looks good to me, but: Content analysis details: (-2.9 points, 5.0 required) pts rule name description ---- ---------------------- -------------------------------------------------- -1.0 ALL_TRUSTED Passed through trusted hosts only via SMTP -1.9 BAYES_00 BODY: Bayes spam probability is 0 to 1% [score: 0.0000] X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: 37078 Cc: 37078@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) Eric Abrahamsen writes: > I'll post this to gnus.general in a second, as well. Looks good to me, but: > Mail message composition starts with =E2=80=9Cm=E2=80=9D in the *Group*= buffer, or =E2=80=9Cr=E2=80=9D > if you=E2=80=99re 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=E2=80=99 (see XXX). There's no configuration necessary for sending email -- Emacs will prompt you for what you want to do. And sending Emacs isn't part of Gnus, anyway... --=20 (domestic pets only, the antidote for overdose, milk.) bloggy blog: http://lars.ingebrigtsen.no From debbugs-submit-bounces@debbugs.gnu.org Tue Oct 22 15:58:10 2019 Received: (at 37078) by debbugs.gnu.org; 22 Oct 2019 19:58:11 +0000 Received: from localhost ([127.0.0.1]:60512 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1iN0IE-0004Vu-Mh for submit@debbugs.gnu.org; Tue, 22 Oct 2019 15:58:10 -0400 Received: from ericabrahamsen.net ([52.70.2.18]:33612 helo=mail.ericabrahamsen.net) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1iN0ID-0004Vh-7G for 37078@debbugs.gnu.org; Tue, 22 Oct 2019 15:58:09 -0400 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 73F11FA028; Tue, 22 Oct 2019 19:58:01 +0000 (UTC) From: Eric Abrahamsen To: Lars Ingebrigtsen Subject: Re: bug#37078: 27.0.50; Proposal: new introductory section to the Gnus manual References: <87sgpym539.fsf@ericabrahamsen.net> <878spcn9d6.fsf@gnus.org> Date: Tue, 22 Oct 2019 12:58:00 -0700 In-Reply-To: <878spcn9d6.fsf@gnus.org> (Lars Ingebrigtsen's message of "Tue, 22 Oct 2019 16:27:33 +0200") Message-ID: <878spck0xj.fsf@ericabrahamsen.net> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.0.50 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 37078 Cc: 37078@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) Lars Ingebrigtsen writes: > Eric Abrahamsen writes: > >> I'll post this to gnus.general in a second, as well. > > Looks good to me, but: > >> Mail message composition starts with =E2=80=9Cm=E2=80=9D in the *Group= * buffer, or =E2=80=9Cr=E2=80=9D >> if you=E2=80=99re replying to an existing message. Because mail is sen= t 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=E2=80=99 (see XXX). > > There's no configuration necessary for sending email -- Emacs will > prompt you for what you want to do. And sending Emacs isn't part of > Gnus, anyway... Okay, that makes sense. I've been gathering together comments from various sources, and will polish up another version this weekend. Not very pressing... From debbugs-submit-bounces@debbugs.gnu.org Sun Jul 19 11:39:34 2020 Received: (at 37078) by debbugs.gnu.org; 19 Jul 2020 15:39:34 +0000 Received: from localhost ([127.0.0.1]:32820 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jxBPa-0003bb-Aw for submit@debbugs.gnu.org; Sun, 19 Jul 2020 11:39:34 -0400 Received: from quimby.gnus.org ([95.216.78.240]:35018) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jxBPY-0003bM-Qn for 37078@debbugs.gnu.org; Sun, 19 Jul 2020 11:39:33 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnus.org; s=20200322; h=Content-Type:MIME-Version:Message-ID:In-Reply-To:Date: References:Subject:Cc:To:From:Sender:Reply-To:Content-Transfer-Encoding: Content-ID:Content-Description:Resent-Date:Resent-From:Resent-Sender: Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help:List-Unsubscribe: List-Subscribe:List-Post:List-Owner:List-Archive; bh=b4djNnoSPGIIm2hnr5dfCEWXBS85KbVsyxskWDby+7w=; b=My6DPa+NOKjy6/ledUQKt76vME aIL/ihA0sO5GdpFX01MyxII9WtqscHbRhXOK8v24EvC2aK/I5FYsEGFBQFr6EJfnIw1Med1TSAwq5 PEvN+/BrgqmGwEv11UET+7EisJugi93lPMsAPPq5wyBa9kUYmVDcRopUHVen/b3e2CiI=; Received: from cm-84.212.202.86.getinternet.no ([84.212.202.86] helo=xo) by quimby with esmtpsa (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1jxBPQ-0007QS-Hz; Sun, 19 Jul 2020 17:39:27 +0200 From: Lars Ingebrigtsen To: Eric Abrahamsen Subject: Re: bug#37078: 27.0.50; Proposal: new introductory section to the Gnus manual References: <87sgpym539.fsf@ericabrahamsen.net> <878spcn9d6.fsf@gnus.org> <878spck0xj.fsf@ericabrahamsen.net> Date: Sun, 19 Jul 2020 17:39:23 +0200 In-Reply-To: <878spck0xj.fsf@ericabrahamsen.net> (Eric Abrahamsen's message of "Tue, 22 Oct 2019 12:58:00 -0700") Message-ID: <87h7u3o6ok.fsf@gnus.org> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/28.0.50 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Report: Spam detection software, running on the system "quimby.gnus.org", has NOT identified this incoming email as spam. The original message has been attached to this so you can view it or label similar future email. If you have any questions, see @@CONTACT_ADDRESS@@ for details. Content preview: Eric Abrahamsen writes: > Okay, that makes sense. I've been gathering together comments from > various sources, and will polish up another version this weekend. Not > very pressing... Content analysis details: (-2.9 points, 5.0 required) pts rule name description ---- ---------------------- -------------------------------------------------- -1.0 ALL_TRUSTED Passed through trusted hosts only via SMTP -1.9 BAYES_00 BODY: Bayes spam probability is 0 to 1% [score: 0.0000] X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: 37078 Cc: 37078@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) Eric Abrahamsen writes: > Okay, that makes sense. I've been gathering together comments from > various sources, and will polish up another version this weekend. Not > very pressing... Any progress here? :-) -- (domestic pets only, the antidote for overdose, milk.) bloggy blog: http://lars.ingebrigtsen.no From debbugs-submit-bounces@debbugs.gnu.org Mon Jul 20 01:28:25 2020 Received: (at 37078) by debbugs.gnu.org; 20 Jul 2020 05:28:25 +0000 Received: from localhost ([127.0.0.1]:33478 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jxOLh-0005AB-1c for submit@debbugs.gnu.org; Mon, 20 Jul 2020 01:28:25 -0400 Received: from ericabrahamsen.net ([52.70.2.18]:42116 helo=mail.ericabrahamsen.net) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jxOLf-00059x-TU for 37078@debbugs.gnu.org; Mon, 20 Jul 2020 01:28:24 -0400 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 1C19BFA0AC; Mon, 20 Jul 2020 05:28:18 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=ericabrahamsen.net; s=mail; t=1595222898; bh=JA82lu0j/Oexdkt9eiIsnBetuDj0c5cdIJM26+XNzdc=; h=From:To:Cc:Subject:References:Date:In-Reply-To:From; b=mzxXd4beb4YVUpc669hRuj/m/vr6UrrW+pv3ETCrh/C0Y9K2PM/hOa8+hturGC9jE XIbykt7vJjd0kOWdpujwRTmF4kbAo4IkGzKt25XAKoaCLlCqU8H3CxY5c5OQKWVuXJ uoy/oARzD18V9DkxMcu34xHQ27B57tU/jOITJrJw= From: Eric Abrahamsen To: Lars Ingebrigtsen Subject: Re: bug#37078: 27.0.50; Proposal: new introductory section to the Gnus manual References: <87sgpym539.fsf@ericabrahamsen.net> <878spcn9d6.fsf@gnus.org> <878spck0xj.fsf@ericabrahamsen.net> <87h7u3o6ok.fsf@gnus.org> Date: Sun, 19 Jul 2020 22:28:16 -0700 In-Reply-To: <87h7u3o6ok.fsf@gnus.org> (Lars Ingebrigtsen's message of "Sun, 19 Jul 2020 17:39:23 +0200") Message-ID: <87zh7uah73.fsf@ericabrahamsen.net> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/28.0.50 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 37078 Cc: 37078@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) Lars Ingebrigtsen writes: > Eric Abrahamsen writes: > >> Okay, that makes sense. I've been gathering together comments from >> various sources, and will polish up another version this weekend. Not >> very pressing... > > Any progress here? :-) 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. From debbugs-submit-bounces@debbugs.gnu.org Mon Jul 20 05:48:19 2020 Received: (at 37078) by debbugs.gnu.org; 20 Jul 2020 09:48:19 +0000 Received: from localhost ([127.0.0.1]:33845 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jxSPD-0003Tt-5n for submit@debbugs.gnu.org; Mon, 20 Jul 2020 05:48:19 -0400 Received: from quimby.gnus.org ([95.216.78.240]:43458) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jxSPA-0003TT-LH for 37078@debbugs.gnu.org; Mon, 20 Jul 2020 05:48:17 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnus.org; s=20200322; h=Content-Type:MIME-Version:Message-ID:In-Reply-To:Date: References:Subject:Cc:To:From:Sender:Reply-To:Content-Transfer-Encoding: Content-ID:Content-Description:Resent-Date:Resent-From:Resent-Sender: Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help:List-Unsubscribe: List-Subscribe:List-Post:List-Owner:List-Archive; bh=P4Q6pBNcTel4ld7Z20ytlxdxlvqh6AwOPzGA/E7RzXI=; b=NAXbCvQ3Ld1aDwFEkObV/Wc/q7 PHqZm3d5ruVUY3jBHCTPQ8/iUWmcNYI1HOJ7Ijvjb1kuAcTTTMti9tQJF+Pswhuuega6+TEn9eVYl HM/oQcAs5DGtYaZpwahOgs+mCY4kFQkvcR2YG5D3lguawgtoda83hqR6bR/hzzh0V4zg=; Received: from cm-84.212.202.86.getinternet.no ([84.212.202.86] helo=xo) by quimby with esmtpsa (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1jxSP1-00077a-Qo; Mon, 20 Jul 2020 11:48:10 +0200 From: Lars Ingebrigtsen To: Eric Abrahamsen Subject: Re: bug#37078: 27.0.50; Proposal: new introductory section to the Gnus manual References: <87sgpym539.fsf@ericabrahamsen.net> <878spcn9d6.fsf@gnus.org> <878spck0xj.fsf@ericabrahamsen.net> <87h7u3o6ok.fsf@gnus.org> <87zh7uah73.fsf@ericabrahamsen.net> Date: Mon, 20 Jul 2020 11:48:06 +0200 In-Reply-To: <87zh7uah73.fsf@ericabrahamsen.net> (Eric Abrahamsen's message of "Sun, 19 Jul 2020 22:28:16 -0700") Message-ID: <87pn8qikkp.fsf@gnus.org> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/28.0.50 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Report: Spam detection software, running on the system "quimby.gnus.org", has NOT identified this incoming email as spam. The original message has been attached to this so you can view it or label similar future email. If you have any questions, see @@CONTACT_ADDRESS@@ for details. Content preview: 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. Content analysis details: (-2.9 points, 5.0 required) pts rule name description ---- ---------------------- -------------------------------------------------- -1.0 ALL_TRUSTED Passed through trusted hosts only via SMTP -1.9 BAYES_00 BODY: Bayes spam probability is 0 to 1% [score: 0.0000] X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: 37078 Cc: 37078@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) 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! -- (domestic pets only, the antidote for overdose, milk.) bloggy blog: http://lars.ingebrigtsen.no From debbugs-submit-bounces@debbugs.gnu.org Mon Jul 20 14:03:02 2020 Received: (at 37078) by debbugs.gnu.org; 20 Jul 2020 18:03:02 +0000 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 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 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= From: Eric Abrahamsen To: Lars Ingebrigtsen Subject: Re: bug#37078: 27.0.50; Proposal: new introductory section to the Gnus manual 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> Date: Mon, 20 Jul 2020 11:02:51 -0700 In-Reply-To: <87pn8qikkp.fsf@gnus.org> (Lars Ingebrigtsen's message of "Mon, 20 Jul 2020 11:48:06 +0200") Message-ID: <87mu3u9i9g.fsf@ericabrahamsen.net> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/28.0.50 (gnu/linux) MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 37078 Cc: 37078@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) --=-=-= 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 --=-=-=-- From debbugs-submit-bounces@debbugs.gnu.org Wed Jul 22 16:16:58 2020 Received: (at 37078) by debbugs.gnu.org; 22 Jul 2020 20:16:58 +0000 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 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 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= From: Eric Abrahamsen To: Lars Ingebrigtsen Subject: Re: bug#37078: 27.0.50; Proposal: new introductory section to the Gnus manual 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> Date: Wed, 22 Jul 2020 13:16:45 -0700 In-Reply-To: <87mu3u9i9g.fsf@ericabrahamsen.net> (Eric Abrahamsen's message of "Mon, 20 Jul 2020 11:02:51 -0700") Message-ID: <87sgdjtidu.fsf@ericabrahamsen.net> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/28.0.50 (gnu/linux) MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 37078 Cc: 37078@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) --=-=-= 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 --=-=-=-- From debbugs-submit-bounces@debbugs.gnu.org Thu Jul 23 09:04:05 2020 Received: (at 37078) by debbugs.gnu.org; 23 Jul 2020 13:04:05 +0000 Received: from localhost ([127.0.0.1]:44360 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jyatI-0006d1-VK for submit@debbugs.gnu.org; Thu, 23 Jul 2020 09:04:05 -0400 Received: from eggs.gnu.org ([209.51.188.92]:52172) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jyatG-0006cX-84 for 37078@debbugs.gnu.org; Thu, 23 Jul 2020 09:04:03 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:41156) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jyatA-0000ws-Ms; Thu, 23 Jul 2020 09:03:56 -0400 Received: from [176.228.60.248] (port=3270 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1jyat9-0003LC-MG; Thu, 23 Jul 2020 09:03:56 -0400 Date: Thu, 23 Jul 2020 16:03:39 +0300 Message-Id: <838sfafkno.fsf@gnu.org> From: Eli Zaretskii To: Eric Abrahamsen In-Reply-To: <87sgdjtidu.fsf@ericabrahamsen.net> (message from Eric Abrahamsen on Wed, 22 Jul 2020 13:16:45 -0700) Subject: Re: bug#37078: 27.0.50; Proposal: new introductory section to the Gnus manual 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> <87sgdjtidu.fsf@ericabrahamsen.net> X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 37078 Cc: larsi@gnus.org, 37078@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > From: Eric Abrahamsen > Date: Wed, 22 Jul 2020 13:16:45 -0700 > Cc: 37078@debbugs.gnu.org First and foremost, thank you for working on improvements of the Gnus manual! This is a very important job, IMO. When reading my comments below, please keep in mind that I don't use Gnus. > +@node Don't Panic > +@chapter Don't Panic A node name such as this is okay, but I wonder whether the chapter should be named "Don't Panic: An Introduction to Gnus Concepts", as that is what it is, right? Also, it is generally a good idea to have a @cindex entry or entries at the beginning of each node which summarize(s) the topic(s) of the node. Think about a reader who wants to find this node quickly using the Info-index command. In this case, I suggest @cindex introduction to Gnus @cindex don't panic > +newsreader, and its DNA is still newsreader DNA. Thus it behaves a Texinfo markup note: it is best to use @acronym, as in @acronym{DNA}, when you use acronyms. Also, consider explaining in parentheses the meaning of an acronym when you first use it, as not every reader might know what "DNA" stands for. > +@node Servers Groups and Articles > +@section Servers, Groups, and Articles This section describes the basic terminology used by Gnus, so perhaps this should be reflected in the node/chapter name? It definitely should be reflected in a @cindex entry here. > +The fundamental building blocks of Gnus are servers, groups, and > +articles. Our documentation conventions call for using @dfn the first time you mention a certain term, as in The fundamental building blocks of Gnus are @dfn{servers}, @dfn{groups}, and @dfn{articles}. In addition, each time you use @dfn, it is a good idea to have a @cindex entry for that term -- this is useful when the reader wants later to re-read the explanations of what each term means. > +always quite line up (see @pxref{FAQ - Glossary} for a more complete ^^^^^^^^^^ "see @ref" (@pxref produces "see" on its own), and make a point of having some punctuation after the closing brace, in this case a comma will do. > +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. You dump many terms and acronyms on the reader here, but never explain them. That is okay in itself, but please keep in mind that some people have limited attention span, and a lot of abstract descriptions with little or nothing to connect that to real-life experiences will turn them off and lose them. One method of keeping them reading is to have cross-references to where each term is discussed in detail. This is also good for those readers who only want to read part of your introduction: they can get as far as they want to go, and then jump directly to the detailed descriptions of what they are after. So terms like "server", "group", "article", "maildir", IMAP, etc. beg for a cross-reference to where the details of handling those are described. > +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}. Does the command to change group subscription really belong here? Wouldn't it be better to say something like the below instead: Gnus has commands to change or toggle your group subscriptions, see @ref{Wherever the ^ command is described}. > +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. Is "installation" really the right term here? Would "configuration" be better, perhaps? > +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. ^^^^^^^^^^ Just @xref (without the "See" part, which @xref produces by itself) will do. > +@node How to Get Mail > +@section How to Get Mail I would suggest @node Reading Mail with Gnus @section Reading Mail with Gnus @cindex reading mail with Gnus > +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 ^^^^^^ "latter", not "second". > +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}). It is strange to have descriptions of user commands in an introductory section. Shouldn't this be elsewhere, like in the "Fetching Mail" section (which strangely says nothing about how to trigger mail fetching)? Also, it is our convention to name the command invoked by a key sequence in parentheses; this is useful if there's ever a need to invoke the command by name, or if it is rebound to another key. Sadly, the Gnus manual doesn't seem to follow this convention, but it's never late to start! And finally, the same "see @pxref" mistake again. > +@node How to View Mail > +@section How to View Mail Most of this section should be somewhere under "Getting Mail" chapter, IMO, with only a short mention of that in the introductory chapter. > +@node How to Send Mail > +@section How to Send Mail Most of this section should be under the "Composing Messages" chapter, IMO. Thanks again for working on this. From debbugs-submit-bounces@debbugs.gnu.org Thu Jul 23 11:14:03 2020 Received: (at 37078) by debbugs.gnu.org; 23 Jul 2020 15:14:03 +0000 Received: from localhost ([127.0.0.1]:45828 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jycv4-0003t5-TJ for submit@debbugs.gnu.org; Thu, 23 Jul 2020 11:14:03 -0400 Received: from mail-wr1-f50.google.com ([209.85.221.50]:37879) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jycv2-0003sR-Gr for 37078@debbugs.gnu.org; Thu, 23 Jul 2020 11:14:01 -0400 Received: by mail-wr1-f50.google.com with SMTP id y3so5531098wrl.4 for <37078@debbugs.gnu.org>; Thu, 23 Jul 2020 08:14:00 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:references:date:in-reply-to:message-id :mime-version; bh=O3kVcNlq33npbjjBnbMAhMW4xaugYimAyz90r4RNu+k=; b=poR5fmPKkXo5gmEU3K4lHkzOkk9ufejmhdBdzZWsfZFzdByQlmUFqo7P8v2OP1RyI+ miDD6y9t8HaFX5jEeMMOjHMmUC2A4n4MrKouzhyjvptHdkEPDVJLYwT2+Ay2Hk/yjBtb Pr2bdUYc6Sf7Yn3zqTvkmMX+dgtgBjaq0I+0I6qwzdvUWx3w8WwdqpGoQuFHTy3pBDsB HqD5GCnD3Cv+I9mVy8W2m6AQfgM7ALDJsw9gi+jSC+dZv05KR+w/DoZOhAkgSWhF48xP xatXq64AeyVoRUwpXIOdpnZqpM6Wtu5lBt+iLBmOaqTkbXMZOQYQeeGWrqlWTMErezPh q+/g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:references:date:in-reply-to :message-id:mime-version; bh=O3kVcNlq33npbjjBnbMAhMW4xaugYimAyz90r4RNu+k=; b=GhPk22UL1yIzD8vbyZwLtcvYi/ryTzU9loLHuNxVd60frWkCD3nfe7KQfIylkGxZHZ kwNgMpAQv1KGRz7hobLv3WHAAmK347EPaFtd5it8J42n7SqtiCAWrnjsa6SQkRMVsTFr 8nctIKtbKdar74zs0TXyzv1y8YaG7TMAOAKTOxOaWcCMqBYZwmcS6h7Ft4JYw7L9Q6Hu OOV69DrMn05jEMiHbHBxx3FNjj9lxIUn3pk5nTKMjJONPX0EEHbKjbT9dQaSBgXtpY5q yFyMCybmF8o6v268d4K5bP3fWDvqXUtXmivj/fv2BEDl7VdR1/vouR4MIp/yp07+40E9 9ipg== X-Gm-Message-State: AOAM530yMFCkjJFudlBZnam27b10nYYMf6wX544TLLJHtErjet5SGJQf 5hkQk8+J96TmpCTbJQQGku3YLW+J X-Google-Smtp-Source: ABdhPJx8tV53pQuHyH/+6RTzwxiFVoQbxT8P3BiRJPPqOXa1fVxTveXUB/BoTebTE+cXTboTu/1Yug== X-Received: by 2002:a5d:6cce:: with SMTP id c14mr4228393wrc.377.1595517234016; Thu, 23 Jul 2020 08:13:54 -0700 (PDT) Received: from rpluim-mac (vav06-1-78-207-202-134.fbx.proxad.net. [78.207.202.134]) by smtp.gmail.com with ESMTPSA id y20sm3601476wmi.8.2020.07.23.08.13.53 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 23 Jul 2020 08:13:53 -0700 (PDT) From: Robert Pluim To: Eli Zaretskii Subject: Re: bug#37078: 27.0.50; Proposal: new introductory section to the Gnus manual 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> <87sgdjtidu.fsf@ericabrahamsen.net> <838sfafkno.fsf@gnu.org> Date: Thu, 23 Jul 2020 17:13:50 +0200 In-Reply-To: <838sfafkno.fsf@gnu.org> (Eli Zaretskii's message of "Thu, 23 Jul 2020 16:03:39 +0300") Message-ID: MIME-Version: 1.0 Content-Type: text/plain X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: 37078 Cc: Eric Abrahamsen , larsi@gnus.org, 37078@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) >>>>> On Thu, 23 Jul 2020 16:03:39 +0300, Eli Zaretskii said: >> +always quite line up (see @pxref{FAQ - Glossary} for a more complete Eli> ^^^^^^^^^^ Eli> "see @ref" (@pxref produces "see" on its own), and make a point of Eli> having some punctuation after the closing brace, in this case a comma Eli> will do. Shameless plug: `texinfo-insert-dwim-@ref' (bound to C-c C-c r in texinfo mode) attempts to do the right thing with @ref and similar based on the surrounding text. Robert From debbugs-submit-bounces@debbugs.gnu.org Thu Jul 23 11:29:57 2020 Received: (at 37078) by debbugs.gnu.org; 23 Jul 2020 15:29:57 +0000 Received: from localhost ([127.0.0.1]:45855 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jydAS-0004HN-Qx for submit@debbugs.gnu.org; Thu, 23 Jul 2020 11:29:57 -0400 Received: from ericabrahamsen.net ([52.70.2.18]:44968 helo=mail.ericabrahamsen.net) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jydAP-0004H9-Dv for 37078@debbugs.gnu.org; Thu, 23 Jul 2020 11:29:56 -0400 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 D0AC5FA03D; Thu, 23 Jul 2020 15:29:46 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=ericabrahamsen.net; s=mail; t=1595518187; bh=O4PY+QVZooe6AZlJmu/8B9Nlb5iTOpZgjKFviSqwVog=; h=From:To:Cc:Subject:References:Date:In-Reply-To:From; b=owjMB/J3hM8SOlbp4LvMeJG3ZutB3NXXpn4gIuU3IUZITHbsja3W9/6Y/RXLKN3yB yuIBkZ77l6JndBg9Z6U+fsuUStNEciNL8GstbWs0zaBvdo380h2moRibC1+vusZKm2 Eyb2pjaeTnU682mRUVr0sm+uU2gviHAJ0Qlyx0p4= From: Eric Abrahamsen To: Robert Pluim Subject: Re: bug#37078: 27.0.50; Proposal: new introductory section to the Gnus manual 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> <87sgdjtidu.fsf@ericabrahamsen.net> <838sfafkno.fsf@gnu.org> Date: Thu, 23 Jul 2020 08:29:45 -0700 In-Reply-To: (Robert Pluim's message of "Thu, 23 Jul 2020 17:13:50 +0200") Message-ID: <871rl2tfkm.fsf@ericabrahamsen.net> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/28.0.50 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 37078 Cc: Eli Zaretskii , 37078@debbugs.gnu.org, larsi@gnus.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) On 07/23/20 17:13 PM, Robert Pluim wrote: >>>>>> On Thu, 23 Jul 2020 16:03:39 +0300, Eli Zaretskii said: > > >> +always quite line up (see @pxref{FAQ - Glossary} for a more complete > Eli> ^^^^^^^^^^ > Eli> "see @ref" (@pxref produces "see" on its own), and make a point of > Eli> having some punctuation after the closing brace, in this case a comma > Eli> will do. > > Shameless plug: `texinfo-insert-dwim-@ref' (bound to C-c C-c r in > texinfo mode) attempts to do the right thing with @ref and similar > based on the surrounding text. Obviously that's exactly what I need, as I never get this right! Thanks a lot. From debbugs-submit-bounces@debbugs.gnu.org Thu Jul 23 12:59:26 2020 Received: (at 37078) by debbugs.gnu.org; 23 Jul 2020 16:59:26 +0000 Received: from localhost ([127.0.0.1]:45901 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jyeZ3-0006Oc-G4 for submit@debbugs.gnu.org; Thu, 23 Jul 2020 12:59:25 -0400 Received: from ericabrahamsen.net ([52.70.2.18]:47272 helo=mail.ericabrahamsen.net) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jyeZ0-0006OM-AW for 37078@debbugs.gnu.org; Thu, 23 Jul 2020 12:59:24 -0400 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 42199FA0AC; Thu, 23 Jul 2020 16:59:16 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=ericabrahamsen.net; s=mail; t=1595523556; bh=biPwl59U63S6ecvwfAPuAnIzTPk4OQ44bMecdrDgrjg=; h=From:To:Cc:Subject:References:Date:In-Reply-To:From; b=MVadBdzIShTPzNk0aqaZAq64HP0xNXPlFnkDGbfxHFGf5ekIycXIiy5il6TA1h02j SJx648VwFZ0wR7t2fSRAzCow+Rx/mDgZQ6y6y3WCyKMb077OwV+zqvEv55q1uVKC0L 6t+v3VaNBe6f7jgheRX7HHK4uItX8jU+zJiv6bUY= From: Eric Abrahamsen To: Eli Zaretskii Subject: Re: bug#37078: 27.0.50; Proposal: new introductory section to the Gnus manual 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> <87sgdjtidu.fsf@ericabrahamsen.net> <838sfafkno.fsf@gnu.org> Date: Thu, 23 Jul 2020 09:59:14 -0700 In-Reply-To: <838sfafkno.fsf@gnu.org> (Eli Zaretskii's message of "Thu, 23 Jul 2020 16:03:39 +0300") Message-ID: <87zh7qrwv1.fsf@ericabrahamsen.net> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/28.0.50 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 37078 Cc: larsi@gnus.org, 37078@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) On 07/23/20 16:03 PM, Eli Zaretskii wrote: >> From: Eric Abrahamsen >> Date: Wed, 22 Jul 2020 13:16:45 -0700 >> Cc: 37078@debbugs.gnu.org > > First and foremost, thank you for working on improvements of the Gnus > manual! This is a very important job, IMO. My pleasure! I like manuals. > When reading my comments below, please keep in mind that I don't use > Gnus. > >> +@node Don't Panic >> +@chapter Don't Panic > > A node name such as this is okay, but I wonder whether the chapter > should be named "Don't Panic: An Introduction to Gnus Concepts", as > that is what it is, right? I did that in the menu listing ("Don't Panic:: Your first 20 minutes with Gnus"), because you're right it's a meaningless title otherwise. I can add that subtitle in to the text itself. If I knew texinfo better, I suspect there's a way to have the heading display differently in different places. > Also, it is generally a good idea to have a @cindex entry or entries > at the beginning of each node which summarize(s) the topic(s) of the > node. Think about a reader who wants to find this node quickly using > the Info-index command. In this case, I suggest > > @cindex introduction to Gnus > @cindex don't panic Got it, will do. >> +newsreader, and its DNA is still newsreader DNA. Thus it behaves a > > Texinfo markup note: it is best to use @acronym, as in @acronym{DNA}, > when you use acronyms. Also, consider explaining in parentheses the > meaning of an acronym when you first use it, as not every reader might > know what "DNA" stands for. Hmm, maybe "genes" then... >> +@node Servers Groups and Articles >> +@section Servers, Groups, and Articles > > This section describes the basic terminology used by Gnus, so perhaps > this should be reflected in the node/chapter name? It definitely > should be reflected in a @cindex entry here. > >> +The fundamental building blocks of Gnus are servers, groups, and >> +articles. > > Our documentation conventions call for using @dfn the first time you > mention a certain term, as in > > The fundamental building blocks of Gnus are @dfn{servers}, > @dfn{groups}, and @dfn{articles}. > > In addition, each time you use @dfn, it is a good idea to have a > @cindex entry for that term -- this is useful when the reader wants > later to re-read the explanations of what each term means. Got it. >> +always quite line up (see @pxref{FAQ - Glossary} for a more complete > ^^^^^^^^^^ > "see @ref" (@pxref produces "see" on its own), and make a point of > having some punctuation after the closing brace, in this case a comma > will do. Yes, obviously I wasn't looking at the output. I'll try Robert's dwim command, too. >> +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. > > You dump many terms and acronyms on the reader here, but never explain > them. That is okay in itself, but please keep in mind that some > people have limited attention span, and a lot of abstract descriptions > with little or nothing to connect that to real-life experiences will > turn them off and lose them. One method of keeping them reading is to > have cross-references to where each term is discussed in detail. This > is also good for those readers who only want to read part of your > introduction: they can get as far as they want to go, and then jump > directly to the detailed descriptions of what they are after. > > So terms like "server", "group", "article", "maildir", IMAP, etc. beg > for a cross-reference to where the details of handling those are > described. I guess I was expecting that things like NNTP, IMAP and maildir would be already familiar, while "server", "group" and "article" were the things we'd need to explain. I'll see if I can add in more cross references. >> +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}. > > Does the command to change group subscription really belong here? > Wouldn't it be better to say something like the below instead: > > Gnus has commands to change or toggle your group subscriptions, see > @ref{Wherever the ^ command is described}. See below... >> +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. > > Is "installation" really the right term here? Would "configuration" > be better, perhaps? The thing is it's really data, lots of it, stored in many different directories and files. "Configuration" sounds to me like an elisp file with some setqs in it. I'm not married to "installation", but can't think of anything more appropriate. >> +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. ^^^^^^^^^^ > > Just @xref (without the "See" part, which @xref produces by itself) > will do. > >> +@node How to Get Mail >> +@section How to Get Mail > > I would suggest > > @node Reading Mail with Gnus > @section Reading Mail with Gnus > @cindex reading mail with Gnus > >> +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 > ^^^^^^ > "latter", not "second". > >> +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}). > > It is strange to have descriptions of user commands in an introductory > section. Shouldn't this be elsewhere, like in the "Fetching Mail" > section (which strangely says nothing about how to trigger mail > fetching)? > > Also, it is our convention to name the command invoked by a key > sequence in parentheses; this is useful if there's ever a need to > invoke the command by name, or if it is rebound to another key. > Sadly, the Gnus manual doesn't seem to follow this convention, but > it's never late to start! > > And finally, the same "see @pxref" mistake again. > >> +@node How to View Mail >> +@section How to View Mail > > Most of this section should be somewhere under "Getting Mail" chapter, > IMO, with only a short mention of that in the introductory chapter. > >> +@node How to Send Mail >> +@section How to Send Mail > > 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. Thanks for the review, Eric From debbugs-submit-bounces@debbugs.gnu.org Thu Jul 23 13:43:50 2020 Received: (at 37078) by debbugs.gnu.org; 23 Jul 2020 17:43:50 +0000 Received: from localhost ([127.0.0.1]:45941 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jyfG2-0007Se-2M for submit@debbugs.gnu.org; Thu, 23 Jul 2020 13:43:50 -0400 Received: from eggs.gnu.org ([209.51.188.92]:48842) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jyfFz-0007SR-Ta for 37078@debbugs.gnu.org; Thu, 23 Jul 2020 13:43:49 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:45275) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jyfFu-0003a3-3s; Thu, 23 Jul 2020 13:43:42 -0400 Received: from [176.228.60.248] (port=4566 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1jyfFt-0007l1-G6; Thu, 23 Jul 2020 13:43:41 -0400 Date: Thu, 23 Jul 2020 20:43:23 +0300 Message-Id: <834kpyf7pg.fsf@gnu.org> From: Eli Zaretskii To: Eric Abrahamsen In-Reply-To: <87zh7qrwv1.fsf@ericabrahamsen.net> (message from Eric Abrahamsen on Thu, 23 Jul 2020 09:59:14 -0700) Subject: Re: bug#37078: 27.0.50; Proposal: new introductory section to the Gnus manual 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> <87sgdjtidu.fsf@ericabrahamsen.net> <838sfafkno.fsf@gnu.org> <87zh7qrwv1.fsf@ericabrahamsen.net> X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 37078 Cc: larsi@gnus.org, 37078@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > From: Eric Abrahamsen > 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. From debbugs-submit-bounces@debbugs.gnu.org Fri Jul 24 14:49:33 2020 Received: (at 37078) by debbugs.gnu.org; 24 Jul 2020 18:49:33 +0000 Received: from localhost ([127.0.0.1]:48724 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jz2lA-0003lH-NW for submit@debbugs.gnu.org; Fri, 24 Jul 2020 14:49:33 -0400 Received: from ericabrahamsen.net ([52.70.2.18]:52792 helo=mail.ericabrahamsen.net) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jz2l6-0003kz-09 for 37078@debbugs.gnu.org; Fri, 24 Jul 2020 14:49:31 -0400 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 521C5FA0EE; Fri, 24 Jul 2020 18:49:21 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=ericabrahamsen.net; s=mail; t=1595616561; bh=f7daXJvSLq3ERkLylXE1Tw2EAhxqwVo15CSTSu01MGo=; h=From:To:Cc:Subject:References:Date:In-Reply-To:From; b=lNJW2BDQbgzLVtYn2lwrIYV8WFoVpyjeZzzwuaefBfH9/1IjTi4HF7Ym+v9mkkOPk lAZyiyk18zsEffUEkdHAVYAIIH1AfsSfJN7Nb/1iYi5o/bL1LQp700k5hVH5YrYJH/ mW1+XCCzXJH2L4yyH6wR/emaimEfYJ8jsYI3JWuE= From: Eric Abrahamsen To: Eli Zaretskii Subject: Re: bug#37078: 27.0.50; Proposal: new introductory section to the Gnus manual 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> <87sgdjtidu.fsf@ericabrahamsen.net> <838sfafkno.fsf@gnu.org> <87zh7qrwv1.fsf@ericabrahamsen.net> <834kpyf7pg.fsf@gnu.org> Date: Fri, 24 Jul 2020 11:49:19 -0700 In-Reply-To: <834kpyf7pg.fsf@gnu.org> (Eli Zaretskii's message of "Thu, 23 Jul 2020 20:43:23 +0300") Message-ID: <87y2n8rbo0.fsf@ericabrahamsen.net> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/28.0.50 (gnu/linux) MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 37078 Cc: larsi@gnus.org, 37078@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) --=-=-= Content-Type: text/plain On 07/23/20 20:43 PM, Eli Zaretskii wrote: >> From: Eric Abrahamsen >> 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 --=-=-= 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..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 --=-=-=-- From debbugs-submit-bounces@debbugs.gnu.org Fri Jul 24 15:08:25 2020 Received: (at 37078) by debbugs.gnu.org; 24 Jul 2020 19:08:25 +0000 Received: from localhost ([127.0.0.1]:48728 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jz33R-0004CD-Km for submit@debbugs.gnu.org; Fri, 24 Jul 2020 15:08:25 -0400 Received: from eggs.gnu.org ([209.51.188.92]:39792) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jz33O-0004Bz-Cs for 37078@debbugs.gnu.org; Fri, 24 Jul 2020 15:08:24 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:58978) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jz33I-0007PM-JP; Fri, 24 Jul 2020 15:08:16 -0400 Received: from [176.228.60.248] (port=1852 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1jz33H-0007cs-7e; Fri, 24 Jul 2020 15:08:15 -0400 Date: Fri, 24 Jul 2020 22:08:00 +0300 Message-Id: <83d04kenov.fsf@gnu.org> From: Eli Zaretskii To: Eric Abrahamsen In-Reply-To: <87y2n8rbo0.fsf@ericabrahamsen.net> (message from Eric Abrahamsen on Fri, 24 Jul 2020 11:49:19 -0700) Subject: Re: bug#37078: 27.0.50; Proposal: new introductory section to the Gnus manual 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> <87sgdjtidu.fsf@ericabrahamsen.net> <838sfafkno.fsf@gnu.org> <87zh7qrwv1.fsf@ericabrahamsen.net> <834kpyf7pg.fsf@gnu.org> <87y2n8rbo0.fsf@ericabrahamsen.net> X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 37078 Cc: larsi@gnus.org, 37078@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > From: Eric Abrahamsen > Cc: larsi@gnus.org, 37078@debbugs.gnu.org > Date: Fri, 24 Jul 2020 11:49:19 -0700 > > 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. That's okay. > 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. I like the result. Maybe I'm biased, so it would be good to hear other opinions. A few minor Texinfo comments below. > +using interactive commands in the Server buffer. See @pxref{Finding "See @pxref" again. > +per-group (see @pxref{Mail Sources} for more information). Same here. > +@xref{Scanning New Messages} for details on fetching new mail. ^ Please add a comma after the closing brace: old versions of Texinfo require it. > +@xref{Selecting a Group} for how to enter a group, and @pxref{Summary Same here. > +messages, @xref{Summary Mail Commands} for details. And here, you want "@pxref" or "see @ref". @xref produces a capitalized "See", which is inappropriate in the middle of a sentence. > +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}. Same here (twice). Also, did you mean @dfn{SMTP} or @acronym{SMTP}? Thanks. From debbugs-submit-bounces@debbugs.gnu.org Fri Jul 24 17:08:32 2020 Received: (at 37078) by debbugs.gnu.org; 24 Jul 2020 21:08:33 +0000 Received: from localhost ([127.0.0.1]:48802 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jz4vg-00075k-CM for submit@debbugs.gnu.org; Fri, 24 Jul 2020 17:08:32 -0400 Received: from ericabrahamsen.net ([52.70.2.18]:55658 helo=mail.ericabrahamsen.net) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jz4ve-00075T-Pv for 37078@debbugs.gnu.org; Fri, 24 Jul 2020 17:08:31 -0400 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 2B62EFA0EE; Fri, 24 Jul 2020 21:08:24 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=ericabrahamsen.net; s=mail; t=1595624904; bh=CNGgXALNRn2fl/qrGvOJDPliTfb9x/yTL98iTh0Bplg=; h=From:To:Cc:Subject:References:Date:From; b=TX+FYYajs7jnaNx98P52Lf+/WlHafvtteoxAtsoDvh1CCqfJB0kCm6r78RC8k6L2A o5gX2qXUKcZJDd93GzBjIPoNblcZrV4EoS4jybiJcvMhNJV7muQ/06pdpbD/FKN8Y3 vvrWE1rg0k+xSWftQ2B865lWrfVItE1uruMhluik= From: Eric Abrahamsen To: Eli Zaretskii Subject: Re: bug#37078: 27.0.50; Proposal: new introductory section to the Gnus manual 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> <87sgdjtidu.fsf@ericabrahamsen.net> <838sfafkno.fsf@gnu.org> <87zh7qrwv1.fsf@ericabrahamsen.net> <834kpyf7pg.fsf@gnu.org> <87y2n8rbo0.fsf@ericabrahamsen.net> <83d04kenov.fsf@gnu.org> Date: Fri, 24 Jul 2020 14:08:20 -0700 Message-ID: <87h7twaaez.fsf@ericabrahamsen.net> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/28.0.50 (gnu/linux) MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 37078 Cc: larsi@gnus.org, 37078@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) --=-=-= Content-Type: text/plain Eli Zaretskii writes: >> From: Eric Abrahamsen >> Cc: larsi@gnus.org, 37078@debbugs.gnu.org >> Date: Fri, 24 Jul 2020 11:49:19 -0700 >> >> 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. > > That's okay. > >> 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. > > I like the result. Maybe I'm biased, so it would be good to hear > other opinions. I don't mind either way, really. > A few minor Texinfo comments below. > >> +using interactive commands in the Server buffer. See @pxref{Finding > > "See @pxref" again. > >> +per-group (see @pxref{Mail Sources} for more information). > > Same here. Okay there's something funny going on here. When I run "make" with this exact diff, the output looks exactly right: "See _Finding the News_ for details." Same with your other, later notes. If I "C-x C-f" from the info manual (now I'm in "/info/") and open gnus.info, I see there is no "See" in the text, just "*note Finding the News:: for details." Playing with this further, the info display seems to be inserting a "see" if there isn't one, and not if there is. In the info manual for the texinfo package on my system, it says all three reference commands (@xref, @ref, and @pxref) will insert a see. I'm not seeing any doubled "see"s in the output, though. The texinfo package version on Arch linux is 6.7-3. Could behavior be different between versions? Anyway, I've edited my diff according to your notes, please take a look. 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..f3cc46087f 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. @ref{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 (@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, see @ref{Summary Mail Commands} for details. + +For information about what happens once you've started composing a +message, see @ref{Composing Messages}. For information on setting up +@acronym{SMTP} servers in particular, see @ref{Mail Variables, ,Mail +Variables,message,Message manual}. + @node Starting Up @chapter Starting Gnus @cindex starting up --=-=-=-- From debbugs-submit-bounces@debbugs.gnu.org Sat Jul 25 02:11:45 2020 Received: (at 37078) by debbugs.gnu.org; 25 Jul 2020 06:11:45 +0000 Received: from localhost ([127.0.0.1]:49185 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jzDPN-0004Fz-AR for submit@debbugs.gnu.org; Sat, 25 Jul 2020 02:11:45 -0400 Received: from eggs.gnu.org ([209.51.188.92]:57772) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jzDPL-0004Fm-Ce for 37078@debbugs.gnu.org; Sat, 25 Jul 2020 02:11:43 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:40835) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jzDPF-0008RS-Og; Sat, 25 Jul 2020 02:11:37 -0400 Received: from [176.228.60.248] (port=2500 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1jzDPF-0004gD-4X; Sat, 25 Jul 2020 02:11:37 -0400 Date: Sat, 25 Jul 2020 09:11:24 +0300 Message-Id: <838sf8dsz7.fsf@gnu.org> From: Eli Zaretskii To: Eric Abrahamsen In-Reply-To: <87h7twaaez.fsf@ericabrahamsen.net> (message from Eric Abrahamsen on Fri, 24 Jul 2020 14:08:20 -0700) Subject: Re: bug#37078: 27.0.50; Proposal: new introductory section to the Gnus manual 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> <87sgdjtidu.fsf@ericabrahamsen.net> <838sfafkno.fsf@gnu.org> <87zh7qrwv1.fsf@ericabrahamsen.net> <834kpyf7pg.fsf@gnu.org> <87y2n8rbo0.fsf@ericabrahamsen.net> <83d04kenov.fsf@gnu.org> <87h7twaaez.fsf@ericabrahamsen.net> X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 37078 Cc: larsi@gnus.org, 37078@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > From: Eric Abrahamsen > Cc: larsi@gnus.org, 37078@debbugs.gnu.org > Date: Fri, 24 Jul 2020 14:08:20 -0700 > > > "See @pxref" again. > > > >> +per-group (see @pxref{Mail Sources} for more information). > > > > Same here. > > Okay there's something funny going on here. When I run "make" with this > exact diff, the output looks exactly right: "See _Finding the News_ for > details." Same with your other, later notes. If I "C-x C-f" from the > info manual (now I'm in "/info/") and open gnus.info, I > see there is no "See" in the text, just "*note Finding the News:: for > details." > > Playing with this further, the info display seems to be inserting a > "see" if there isn't one, and not if there is. That's right, you need to look at the file itself, or reset Info-hide-note-references to nil inside Info. > In the info manual for the texinfo package on my system, it says all > three reference commands (@xref, @ref, and @pxref) will insert a see. I think you are misinterpreting the Texinfo manual, or maybe judging by the Info mode display, not the real Info file. In the Info format, the cross-reference marker is "*note ", not "See". The latter appears in the printed manual. And @ref doesn't generate "see" in the printed manual, it leaves that to you, so that you could, for example, say something like "this-and-that, as described in @ref{foo}". > I'm not seeing any doubled "see"s in the output, though. You should see "see *note " in the output, which is already a sign of trouble. And in printed output, you will see a duplicate "see". > The texinfo package version on Arch linux is 6.7-3. Could behavior be > different between versions? Not this one, no. > Anyway, I've edited my diff according to your notes, please take a look. Mostly okay, see below. > +using interactive commands in the Server buffer. @ref{Finding > +the News} for details. ^^^^ You want @xref here, and please remember the comma after the closing brace. > +messages, see @ref{Summary Mail Commands} for details. ^ A comma there is missing. From debbugs-submit-bounces@debbugs.gnu.org Mon Jul 27 17:48:36 2020 Received: (at 37078) by debbugs.gnu.org; 27 Jul 2020 21:48:36 +0000 Received: from localhost ([127.0.0.1]:55893 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1k0Az6-00062R-0P for submit@debbugs.gnu.org; Mon, 27 Jul 2020 17:48:36 -0400 Received: from quimby.gnus.org ([95.216.78.240]:55162) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1k0Az4-00062E-Mg for 37078@debbugs.gnu.org; Mon, 27 Jul 2020 17:48:35 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnus.org; s=20200322; h=Content-Type:MIME-Version:Message-ID:In-Reply-To:Date: References:Subject:Cc:To:From:Sender:Reply-To:Content-Transfer-Encoding: Content-ID:Content-Description:Resent-Date:Resent-From:Resent-Sender: Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help:List-Unsubscribe: List-Subscribe:List-Post:List-Owner:List-Archive; bh=Z8rPYxqdBV4z37+bIZPJBEqq7E4EFGDIR+4oyO2tBj4=; b=ha6iBjGAdMMOFmbk8gb+zbSJ9k 2aCtWOL963R6bpd0PKXgXy/agaafw2QodEDqczU/SyYr6A1YZmlTg8oHtKLBnKJaSCSA7DGYATTYE /tFRHG59YbRWGrh2BSgXanexgXNCKBoWUKwG9ZCRnCNfX+ucqYYXM8ZhOwEoPkvq1JNg=; Received: from cm-84.212.202.86.getinternet.no ([84.212.202.86] helo=xo) by quimby with esmtpsa (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1k0Ayo-0004tm-MB; Mon, 27 Jul 2020 23:48:28 +0200 From: Lars Ingebrigtsen To: Eric Abrahamsen Subject: Re: bug#37078: 27.0.50; Proposal: new introductory section to the Gnus manual 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> <87sgdjtidu.fsf@ericabrahamsen.net> <838sfafkno.fsf@gnu.org> <87zh7qrwv1.fsf@ericabrahamsen.net> <834kpyf7pg.fsf@gnu.org> <87y2n8rbo0.fsf@ericabrahamsen.net> Date: Mon, 27 Jul 2020 23:48:17 +0200 In-Reply-To: <87y2n8rbo0.fsf@ericabrahamsen.net> (Eric Abrahamsen's message of "Fri, 24 Jul 2020 11:49:19 -0700") Message-ID: <87a6zk634u.fsf@gnus.org> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/28.0.50 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Report: Spam detection software, running on the system "quimby.gnus.org", has NOT identified this incoming email as spam. The original message has been attached to this so you can view it or label similar future email. If you have any questions, see @@CONTACT_ADDRESS@@ for details. Content preview: Eric Abrahamsen writes: > Otherwise, WDYT? Looks good to me. Content analysis details: (-2.9 points, 5.0 required) pts rule name description ---- ---------------------- -------------------------------------------------- -1.0 ALL_TRUSTED Passed through trusted hosts only via SMTP -1.9 BAYES_00 BODY: Bayes spam probability is 0 to 1% [score: 0.0000] X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: 37078 Cc: Eli Zaretskii , 37078@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) Eric Abrahamsen writes: > Otherwise, WDYT? Looks good to me. -- (domestic pets only, the antidote for overdose, milk.) bloggy blog: http://lars.ingebrigtsen.no From debbugs-submit-bounces@debbugs.gnu.org Mon Jul 27 18:32:36 2020 Received: (at 37078) by debbugs.gnu.org; 27 Jul 2020 22:32:36 +0000 Received: from localhost ([127.0.0.1]:55975 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1k0Bfg-00035v-DY for submit@debbugs.gnu.org; Mon, 27 Jul 2020 18:32:36 -0400 Received: from ericabrahamsen.net ([52.70.2.18]:33304 helo=mail.ericabrahamsen.net) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1k0Bfd-00035c-Mg; Mon, 27 Jul 2020 18:32:34 -0400 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 A7C36FA097; Mon, 27 Jul 2020 22:32:26 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=ericabrahamsen.net; s=mail; t=1595889147; bh=DxUfHi+mtDr2uu6kj7rwiL4xf687vrVSc4MG1eghphA=; h=From:To:Cc:Subject:References:Date:In-Reply-To:From; b=L7ZWXj7w52wOFma8LJUsmHx6vX7XP+FvqzyyK650mhvlTdeQqqCT6HUvHnXbj0tBA 115zUf4QS7iOCDMX9QWOPrLIa3lpNHe28hRITildqyKKC4vJuLCpqjhPEDrw8XNPzA dOBRR3Is9ptk8CJj1IlWSVSws1AaYbhblxdwIiD0= From: Eric Abrahamsen To: Eli Zaretskii Subject: Re: bug#37078: 27.0.50; Proposal: new introductory section to the Gnus manual 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> <87sgdjtidu.fsf@ericabrahamsen.net> <838sfafkno.fsf@gnu.org> <87zh7qrwv1.fsf@ericabrahamsen.net> <834kpyf7pg.fsf@gnu.org> <87y2n8rbo0.fsf@ericabrahamsen.net> <83d04kenov.fsf@gnu.org> <87h7twaaez.fsf@ericabrahamsen.net> <838sf8dsz7.fsf@gnu.org> Date: Mon, 27 Jul 2020 15:32:25 -0700 In-Reply-To: <838sf8dsz7.fsf@gnu.org> (Eli Zaretskii's message of "Sat, 25 Jul 2020 09:11:24 +0300") Message-ID: <87h7tssi6e.fsf@ericabrahamsen.net> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/28.0.50 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 37078 Cc: 37078-done@debbugs.gnu.org, larsi@gnus.org, 37078@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) Eli Zaretskii writes: >> From: Eric Abrahamsen >> Cc: larsi@gnus.org, 37078@debbugs.gnu.org >> Date: Fri, 24 Jul 2020 14:08:20 -0700 >> >> > "See @pxref" again. >> > >> >> +per-group (see @pxref{Mail Sources} for more information). >> > >> > Same here. >> >> Okay there's something funny going on here. When I run "make" with this >> exact diff, the output looks exactly right: "See _Finding the News_ for >> details." Same with your other, later notes. If I "C-x C-f" from the >> info manual (now I'm in "/info/") and open gnus.info, I >> see there is no "See" in the text, just "*note Finding the News:: for >> details." >> >> Playing with this further, the info display seems to be inserting a >> "see" if there isn't one, and not if there is. > > That's right, you need to look at the file itself, or reset > Info-hide-note-references to nil inside Info. > >> In the info manual for the texinfo package on my system, it says all >> three reference commands (@xref, @ref, and @pxref) will insert a see. > > I think you are misinterpreting the Texinfo manual, or maybe judging > by the Info mode display, not the real Info file. In the Info format, > the cross-reference marker is "*note ", not "See". The latter appears > in the printed manual. And @ref doesn't generate "see" in the printed > manual, it leaves that to you, so that you could, for example, say > something like "this-and-that, as described in @ref{foo}". Yeesh, I had no idea all this happened (nor did I know about Info-hide-note-references), I was indeed just going by the display. Sorry if I've come across as obtuse, here. >> I'm not seeing any doubled "see"s in the output, though. > > You should see "see *note " in the output, which is already a sign of > trouble. And in printed output, you will see a duplicate "see". > >> The texinfo package version on Arch linux is 6.7-3. Could behavior be >> different between versions? > > Not this one, no. > >> Anyway, I've edited my diff according to your notes, please take a look. > > Mostly okay, see below. > >> +using interactive commands in the Server buffer. @ref{Finding >> +the News} for details. ^^^^ > > You want @xref here, and please remember the comma after the closing > brace. > >> +messages, see @ref{Summary Mail Commands} for details. > ^ > A comma there is missing. Okay, those final changes are in, and I'm pushing to master this before I mess anything else up. Thanks for your help, Eric From unknown Thu Jun 19 14:02:04 2025 Received: (at fakecontrol) by fakecontrolmessage; To: internal_control@debbugs.gnu.org From: Debbugs Internal Request Subject: Internal Control Message-Id: bug archived. Date: Tue, 25 Aug 2020 11:24:07 +0000 User-Agent: Fakemail v42.6.9 # This is a fake control message. # # The action: # bug archived. thanks # This fakemail brought to you by your local debbugs # administrator