Gnus docs questions/notes

[David Abrahams <dave@boost-consulting.com>]

Hi,

I am going through the Gnus documentation from beginning to end, to try
to get a grip on this beast that I've never been able to quite
understand.  Many questions and a few problems are popping up, which I'm
posting here.  I hope that my postings will be used to clarify the
documentation.  If not, please let me know, as posting them is a
significant effort.

I realize that _some_ of what I'm asking for may be outside the charter
of this document as described in 15.4, "On Writing Manuals," but it's
the only comprehensive document we have AFAIK, so it may make sense to
improve it rather than wait for someone to write something that's more
like a "user's guide."

Section 1.1 Finding the news

- Page numbering is restarted somewhere in gnus-manual-standard.pdf, so
that the reference on page 2 to the Terminology section points to page
113, but there's no indication of the restart.  That's confusing.

- p.2 mentions "the local spool."  What's a spool?  It's not covered in
the terminology section

- p.2 mentions "Leafnode."  It would be nice to have at least a short
footnote that says what that is.

- p.3 mentions "active files." I realize this is defined in the
terminology section, but it would be nice if newly-introduced terms
could be cross-referenced to their definitions.  It isn't clear whether
the active file is typically stored on the machine where Gnus is running
or on the server; the answer could greatly affect how I decide to make
many Gnus settings, since active files can grow so large.

Section 1.2 The First Time

- By "startup files" do you mean .gnus et. al?

- "If gnus-default-subscribed-newsgroups is t, Gnus will just use the
normal functions for handling new groups, and not do anything special."
This is too vague.  It's unclear what these normal functions might be,
nor what special things might have happened otherwise.

1.5 Fetching a Group

- why might this be more useful for someone who writes code than for users?

- does it start Gnus?  If not, and you can read a group without starting
Gnus, what does it mean to start Gnus?

1.6.1 Checking New Groups

The news servers I use have so many groups on them, and I have so much
incoming traffic, that it's hard to imagine anyone wanting to have Gnus
automatically subscribe them to new groups.  Is this really a common
usage pattern?  From reading the docs, it seems like there's a lot of
expensive computation and storage devoted to being able to do that in
Gnus, and it's all turned on by default.

1.8 Startup Files

- Begins, "Now, you all know about the `.newsrc' file."  Well, not
really.  I don't know much about it at all yet.  The statement makes me
wonder what I *should* know about it at this point, and where I ought to
go to find that information.

- "You can turn off writing the ‘.newsrc’ file by setting
gnus-save-newsrc-file to nil, which means you can delete the file and
save some space, as well as exiting from Gnus faster. However, this will
make it impossible to use other newsreaders than Gnus."

This baffles me.  How could telling Gnus not to touch .newsrc prevent me
from using other newsreaders?

- "Similarly, setting gnus-read-newsrc-file to nil makes Gnus ignore the
‘.newsrc’ file and any ‘.newsrc-SERVER’ files, which is convenient if
you have a tendency to use Netscape once in a while."

Why is that convenient for people who use Netscape once in a while?

- "You should always set gnus-check-new-newsgroups to nil or ask-server
if you set this variable to nil (see “New Groups” on page 5). This
variable can also be a regular expression. If that’s the case, remove
all groups that do not match this regexp before saving."

Is this an instruction to me, the user, or is it really telling me what
Gnus will do if gnus-check-new-newsgroups is a regexp?  Before saving
what?  Remove the groups from where?

- The gnus-startup-file variable says where the startup files are. The
default value is ‘˜/.newsrc’, with the Gnus (El Dingo) startup file
being whatever that one is, with a “.eld” appended.

What is El Dingo?

1.10 The Active File

I'm trying to figure out how to set gnus-read-active-file for my primary
select method, which will be an IMAP server.  I assume that's neither
Leafnode nor INN, so none of the information here applies to me.

Thanks in advance for your attention,

-- 
Dave Abrahams
Boost Consulting
http://www.boost-consulting.com