[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

bug#37078: closed (27.0.50; Proposal: new introductory section to the Gn

From: GNU bug Tracking System
Subject: bug#37078: closed (27.0.50; Proposal: new introductory section to the Gnus manual)
Date: Mon, 27 Jul 2020 22:33:02 +0000

Your message dated Mon, 27 Jul 2020 15:32:25 -0700
with message-id <87h7tssi6e.fsf@ericabrahamsen.net>
and subject line Re: bug#37078: 27.0.50; Proposal: new introductory section to 
the Gnus manual
has caused the debbugs.gnu.org bug report #37078,
regarding 27.0.50; Proposal: new introductory section to the Gnus manual
to be marked as done.

(If you believe you have received this mail in error, please contact

37078: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=37078
GNU Bug Tracking System
Contact help-debbugs@gnu.org with problems
--- Begin Message --- 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).

--- End Message ---
--- Begin Message --- Subject: Re: bug#37078: 27.0.50; Proposal: new introductory section to the Gnus manual Date: Mon, 27 Jul 2020 15:32:25 -0700 User-agent: Gnus/5.13 (Gnus v5.13) Emacs/28.0.50 (gnu/linux)
Eli Zaretskii <eliz@gnu.org> writes:

>> From: Eric Abrahamsen <eric@ericabrahamsen.net>
>> 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 "<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,

--- End Message ---

reply via email to

[Prev in Thread] Current Thread [Next in Thread]