GNU bug report logs - #37078
27.0.50; Proposal: new introductory section to the Gnus manual

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 37078 in the body.
You can then email your comments to 37078 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Eric Abrahamsen <eric <at> ericabrahamsen.net>
To: bug-gnu-emacs <at> gnu.org
Subject: 27.0.50; Proposal: new introductory section to the Gnus manual
Date: Mon, 19 Aug 2019 07:22:34 +0800

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.


			     ━━━━━━━━━━━━━
			      DON’T PANIC
			     ━━━━━━━━━━━━━


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’t
   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’s
   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 “subscribedness”, with different behavior
   depending on “how subscribed” 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’t ever
really like it.

The brief introduction below should be enough to get you off the ground.


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 wide variety of
  servers, the vocabulary doesn’t always quite line up (see XXX 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.

  A Gnus installation is basically just a list of one or more servers,
  plus the user’s subscribed groups from those servers.

  Servers can be added and configured in two places: in the user’s
  gnus.el startup file, using the `gnus-select-method’ and
  `gnus-secondary-select-methods’ options, or within Gnus itself using
  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’s necessary to enter the *Server*
  buffer (with “^”), press return on the server in question, and then
  subscribe to individual groups using “u”.


Getting Mail
════════════

  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’t
  fetch them from anywhere.

  In the second case, Gnus provides for “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 messages. Mail
  sources are usually configured globally, but can be specified
  per-group (see XXX for more information).

  The “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 XXX).


Viewing Mail
════════════

  By default, Gnus’s *Group* buffer only displays groups with unread
  messages. It is always possible to display all the groups temporarily
  with “L”, and to configure Gnus to always display some groups (see
  XXX). The “j” key will prompt for a group name and jump to it,
  displaying it if necessary.

  Press “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 “RET” before entering the group,
  or by pressing “/ o” once the group is open.

  Articles can be opened and scrolled using “RET” and/or “SPC”, and “n”
  will select the next message.


Sending Mail
════════════

  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 “a” key in the *Group* buffer, or “f” if you’re in a
  group and replying to an article.

  Mail message composition starts with “m” in the *Group* buffer, or “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
  `message-send-mail-function’ (see XXX).

Message #8 received at 37078 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Eric Abrahamsen <eric <at> ericabrahamsen.net>
Cc: 37078 <at> debbugs.gnu.org
Subject: Re: bug#37078: 27.0.50; Proposal: new introductory section to the
 Gnus manual
Date: Tue, 27 Aug 2019 04:04:49 +0200

Eric Abrahamsen <eric <at> ericabrahamsen.net> 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’s 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

Message #11 received at 37078 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Eric Abrahamsen <eric <at> ericabrahamsen.net>
Cc: 37078 <at> debbugs.gnu.org
Subject: Re: bug#37078: 27.0.50; Proposal: new introductory section to the
 Gnus manual
Date: Tue, 22 Oct 2019 16:27:33 +0200

Eric Abrahamsen <eric <at> ericabrahamsen.net> writes:

> I'll post this to gnus.general in a second, as well.

Looks good to me, but:

>   Mail message composition starts with “m” in the *Group* buffer, or “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
>   `message-send-mail-function’ (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...

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Message #14 received at 37078 <at> debbugs.gnu.org (full text, mbox):

From: Eric Abrahamsen <eric <at> ericabrahamsen.net>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 37078 <at> debbugs.gnu.org
Subject: Re: bug#37078: 27.0.50; Proposal: new introductory section to the
 Gnus manual
Date: Tue, 22 Oct 2019 12:58:00 -0700

Lars Ingebrigtsen <larsi <at> gnus.org> writes:

> Eric Abrahamsen <eric <at> ericabrahamsen.net> writes:
>
>> I'll post this to gnus.general in a second, as well.
>
> Looks good to me, but:
>
>>   Mail message composition starts with “m” in the *Group* buffer, or “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
>>   `message-send-mail-function’ (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...

Message #17 received at 37078 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Eric Abrahamsen <eric <at> ericabrahamsen.net>
Cc: 37078 <at> debbugs.gnu.org
Subject: Re: bug#37078: 27.0.50; Proposal: new introductory section to the
 Gnus manual
Date: Sun, 19 Jul 2020 17:39:23 +0200

Eric Abrahamsen <eric <at> ericabrahamsen.net> 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

Message #20 received at 37078 <at> debbugs.gnu.org (full text, mbox):

From: Eric Abrahamsen <eric <at> ericabrahamsen.net>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 37078 <at> debbugs.gnu.org
Subject: Re: bug#37078: 27.0.50; Proposal: new introductory section to the
 Gnus manual
Date: Sun, 19 Jul 2020 22:28:16 -0700

Lars Ingebrigtsen <larsi <at> gnus.org> writes:

> Eric Abrahamsen <eric <at> ericabrahamsen.net> 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.

Message #23 received at 37078 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Eric Abrahamsen <eric <at> ericabrahamsen.net>
Cc: 37078 <at> debbugs.gnu.org
Subject: Re: bug#37078: 27.0.50; Proposal: new introductory section to the
 Gnus manual
Date: Mon, 20 Jul 2020 11:48:06 +0200

Eric Abrahamsen <eric <at> ericabrahamsen.net> writes:

> Yes! The text itself is done (I incorporated some comments from
> gnus.general folks), I just need to format it as texinfo and add the
> internal links, then can post a proper commit for inspection.

Great!

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Message #26 received at 37078 <at> debbugs.gnu.org (full text, mbox):

From: Eric Abrahamsen <eric <at> ericabrahamsen.net>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 37078 <at> debbugs.gnu.org
Subject: Re: bug#37078: 27.0.50; Proposal: new introductory section to the
 Gnus manual
Date: Mon, 20 Jul 2020 11:02:51 -0700

[Message part 1 (text/plain, inline)]

On 07/20/20 11:48 AM, Lars Ingebrigtsen wrote:
> Eric Abrahamsen <eric <at> ericabrahamsen.net> writes:
>
>> Yes! The text itself is done (I incorporated some comments from
>> gnus.general folks), I just need to format it as texinfo and add the
>> internal links, then can post a proper commit for inspection.
>
> Great!

Here's the diff I've got now. I've tried to sneak it in there without
running any of texinfo-mode's "update the whole world" commands, because
that dumps a whole bunch of new text into the file, all over the place,
and I don't know texinfo well enough to know why it's doing that. On the
other hand, "make" barfs a huge number of warnings, so something needs
to be updated, I just don't know what.

[gnus-intro.diff (text/x-patch, attachment)]

Message #29 received at 37078 <at> debbugs.gnu.org (full text, mbox):

From: Eric Abrahamsen <eric <at> ericabrahamsen.net>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 37078 <at> debbugs.gnu.org
Subject: Re: bug#37078: 27.0.50; Proposal: new introductory section to the
 Gnus manual
Date: Wed, 22 Jul 2020 13:16:45 -0700

[Message part 1 (text/plain, inline)]

Eric Abrahamsen <eric <at> ericabrahamsen.net> writes:

> On 07/20/20 11:48 AM, Lars Ingebrigtsen wrote:
>> Eric Abrahamsen <eric <at> ericabrahamsen.net> writes:
>>
>>> Yes! The text itself is done (I incorporated some comments from
>>> gnus.general folks), I just need to format it as texinfo and add the
>>> internal links, then can post a proper commit for inspection.
>>
>> Great!
>
> Here's the diff I've got now. I've tried to sneak it in there without
> running any of texinfo-mode's "update the whole world" commands, because
> that dumps a whole bunch of new text into the file, all over the place,
> and I don't know texinfo well enough to know why it's doing that. On the
> other hand, "make" barfs a huge number of warnings, so something needs
> to be updated, I just don't know what.

Okay, I tiptoed through the violets and managed to make a diff that
raises no warnings and produces the expected output. I also did some
tweaking and edits. If no one hates this, I'll push in a few days.

Eric

[gnus-intro.diff (text/x-patch, attachment)]

Message #32 received at 37078 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Eric Abrahamsen <eric <at> ericabrahamsen.net>
Cc: larsi <at> gnus.org, 37078 <at> debbugs.gnu.org
Subject: Re: bug#37078: 27.0.50;
 Proposal: new introductory section to the Gnus manual
Date: Thu, 23 Jul 2020 16:03:39 +0300

> From: Eric Abrahamsen <eric <at> ericabrahamsen.net>
> Date: Wed, 22 Jul 2020 13:16:45 -0700
> Cc: 37078 <at> 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.

Message #35 received at 37078 <at> debbugs.gnu.org (full text, mbox):

From: Robert Pluim <rpluim <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: Eric Abrahamsen <eric <at> ericabrahamsen.net>, larsi <at> gnus.org,
 37078 <at> debbugs.gnu.org
Subject: Re: bug#37078: 27.0.50; Proposal: new introductory section to the
 Gnus manual
Date: Thu, 23 Jul 2020 17:13:50 +0200

>>>>> On Thu, 23 Jul 2020 16:03:39 +0300, Eli Zaretskii <eliz <at> gnu.org> 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

Message #38 received at 37078 <at> debbugs.gnu.org (full text, mbox):

From: Eric Abrahamsen <eric <at> ericabrahamsen.net>
To: Robert Pluim <rpluim <at> gmail.com>
Cc: Eli Zaretskii <eliz <at> gnu.org>, 37078 <at> debbugs.gnu.org, larsi <at> gnus.org
Subject: Re: bug#37078: 27.0.50; Proposal: new introductory section to the
 Gnus manual
Date: Thu, 23 Jul 2020 08:29:45 -0700

On 07/23/20 17:13 PM, Robert Pluim wrote:
>>>>>> On Thu, 23 Jul 2020 16:03:39 +0300, Eli Zaretskii <eliz <at> gnu.org> 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.

Message #41 received at 37078 <at> debbugs.gnu.org (full text, mbox):

From: Eric Abrahamsen <eric <at> ericabrahamsen.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: larsi <at> gnus.org, 37078 <at> debbugs.gnu.org
Subject: Re: bug#37078: 27.0.50; Proposal: new introductory section to the
 Gnus manual
Date: Thu, 23 Jul 2020 09:59:14 -0700

On 07/23/20 16:03 PM, Eli Zaretskii wrote:
>> From: Eric Abrahamsen <eric <at> ericabrahamsen.net>
>> Date: Wed, 22 Jul 2020 13:16:45 -0700
>> Cc: 37078 <at> 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

Message #44 received at 37078 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Eric Abrahamsen <eric <at> ericabrahamsen.net>
Cc: larsi <at> gnus.org, 37078 <at> debbugs.gnu.org
Subject: Re: bug#37078: 27.0.50; Proposal: new introductory section to the
 Gnus manual
Date: Thu, 23 Jul 2020 20:43:23 +0300

> From: Eric Abrahamsen <eric <at> ericabrahamsen.net>
> Cc: larsi <at> gnus.org,  37078 <at> 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.

Message #47 received at 37078 <at> debbugs.gnu.org (full text, mbox):

From: Eric Abrahamsen <eric <at> ericabrahamsen.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: larsi <at> gnus.org, 37078 <at> debbugs.gnu.org
Subject: Re: bug#37078: 27.0.50; Proposal: new introductory section to the
 Gnus manual
Date: Fri, 24 Jul 2020 11:49:19 -0700

[Message part 1 (text/plain, inline)]

On 07/23/20 20:43 PM, Eli Zaretskii wrote:
>> From: Eric Abrahamsen <eric <at> ericabrahamsen.net>
>> Cc: larsi <at> gnus.org,  37078 <at> 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

[gnus-intro.diff (text/x-patch, attachment)]

Message #50 received at 37078 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Eric Abrahamsen <eric <at> ericabrahamsen.net>
Cc: larsi <at> gnus.org, 37078 <at> debbugs.gnu.org
Subject: Re: bug#37078: 27.0.50; Proposal: new introductory section to the
 Gnus manual
Date: Fri, 24 Jul 2020 22:08:00 +0300

> From: Eric Abrahamsen <eric <at> ericabrahamsen.net>
> Cc: larsi <at> gnus.org,  37078 <at> 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.

Message #53 received at 37078 <at> debbugs.gnu.org (full text, mbox):

From: Eric Abrahamsen <eric <at> ericabrahamsen.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: larsi <at> gnus.org, 37078 <at> debbugs.gnu.org
Subject: Re: bug#37078: 27.0.50; Proposal: new introductory section to the
 Gnus manual
Date: Fri, 24 Jul 2020 14:08:20 -0700

[Message part 1 (text/plain, inline)]

Eli Zaretskii <eliz <at> gnu.org> writes:

>> From: Eric Abrahamsen <eric <at> ericabrahamsen.net>
>> Cc: larsi <at> gnus.org,  37078 <at> 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 "<emacsbuilddir>/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

[gnus-intro.diff (text/x-patch, attachment)]

Message #56 received at 37078 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Eric Abrahamsen <eric <at> ericabrahamsen.net>
Cc: larsi <at> gnus.org, 37078 <at> debbugs.gnu.org
Subject: Re: bug#37078: 27.0.50; Proposal: new introductory section to the
 Gnus manual
Date: Sat, 25 Jul 2020 09:11:24 +0300

> From: Eric Abrahamsen <eric <at> ericabrahamsen.net>
> Cc: larsi <at> gnus.org,  37078 <at> 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 "<emacsbuilddir>/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.

Message #59 received at 37078 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Eric Abrahamsen <eric <at> ericabrahamsen.net>
Cc: Eli Zaretskii <eliz <at> gnu.org>, 37078 <at> debbugs.gnu.org
Subject: Re: bug#37078: 27.0.50; Proposal: new introductory section to the
 Gnus manual
Date: Mon, 27 Jul 2020 23:48:17 +0200

Eric Abrahamsen <eric <at> ericabrahamsen.net> writes:

> Otherwise, WDYT?

Looks good to me.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Message #62 received at 37078 <at> debbugs.gnu.org (full text, mbox):

From: Eric Abrahamsen <eric <at> ericabrahamsen.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 37078-done <at> debbugs.gnu.org, larsi <at> gnus.org, 37078 <at> debbugs.gnu.org
Subject: Re: bug#37078: 27.0.50; Proposal: new introductory section to the
 Gnus manual
Date: Mon, 27 Jul 2020 15:32:25 -0700

Eli Zaretskii <eliz <at> gnu.org> writes:

>> From: Eric Abrahamsen <eric <at> ericabrahamsen.net>
>> Cc: larsi <at> gnus.org,  37078 <at> 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 "<emacsbuilddir>/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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.