Editing the manual

Editing the manual

[Lars Magne Ingebrigtsen]

I got as far as to page 27 before I grew *extremely* bored with
proof-reading, so I decided to 1) document all undocumented variables,
2) add index entries for all variables and functions, and 3) move
everything around some.  There are now only 10 chapters -- I've moved
some stuff to the appendices, and have made chapters out of the
"Composing Messages" (formerly "Mail Reply and Followup") and "Select
Methods" (formerly "Foreign Groups") sections.   See what y'all think
about the new organization in 0.39.

-- 
  "Yes.  The journey through the human heart 
     would have to wait until some other time."

Editing the manual

[luis fernandes]

I still use vm to read mail. I have considered using gnus on many
previous occasions, but have found the portion of the manual that
describes how to read mail, rather overwhelming.

I would like to propose an approach that would alleviate this
apprehension (at least to me; mail is *VERY* important to me (I
refuse to answer my phone, or answer the door; so email is the only
method people can communicate with me)) so I cannot afford to lose
even 1 message.

With this in mind, I would like to propose that certain sections in
the manual accomodate both the novice and the expert user.

The section aimed at the novice would describe the minimum number of
steps required to get the bare-bones functionality of whatever is
being described. The expert section would describe, in appropriate
detail, the more esoteric functionality the user may be interested
in.

For example, with reading mail, I would like to know what variable to
define in my ~/.gnus file. and what commands to type in the
command-buffer, I envision it looking like:

		5.0 Reading Mail With Gnus

		A few words about the benefits of reading mail with gnus, &c.

		1. Add (setq this-n-that t) The doc-string for this-n-that
		   pasted here.
		2. Add (setq something-else nil) The doc-string for
		   something-else.
		3. Type M-x get-mail-with-gnus RET

[If I'm reading this on-line, I can cut-n-paste the lisp-code into my
~/.gnus and be up-and-running in under 30 sec.]

		For more experienced users, you can get gnus to split mail
		into various folders and sort it &c...

[These steps, would require more work on the reader's part because he
may have to ftp auxilliary software (procmail) and will take >30s]

This novice/expert proposal will not apply for all the sections but
only for those where there is both a simple way to do something and a
more involved way (e.g. mail, scoring, etc.)

Re: Editing the manual

[Lars Magne Ingebrigtsen]

elf@ee.ryerson.ca (luis fernandes) writes:

> With this in mind, I would like to propose that certain sections in
> the manual accomodate both the novice and the expert user.

I've now added a section called "Getting Started Reading Mail" that
just mentions `gnus-secondary-select-methods' and
`nnmail-split-methods'.  

A hyper-short version on reading mail with Gnus is:

(setq gnus-secondary-select-methods
      '((nnml "private")))

That's it, really.  nnml will snarf all new mail and you'll be
subscribed to a group called "nnml:misc.mail" that carries all your
mail.

(The manual elaborates a bit more on this, though.)

-- 
  "Yes.  The journey through the human heart 
     would have to wait until some other time."