Re: MH-E manual update

[Eli Zaretskii <eliz@gnu.org>]

> From: Bill Wohler <wohler@newt.com>
> Date: Mon, 06 Mar 2006 17:29:49 -0800
> Cc: mh-e-devel@lists.sourceforge.net
> 
> I'd appreciate it if someone could take a quick look and ensure it
> (man/mh-e.texi) meets Emacs' standards.

Well, it's over 9000 lines, so it's beyond my resources to read it in
its entirety and give you feedback on every sentence.  Some comments
based on casual reading are below:

In general, the manual seems to be well designed and well written.

The GNU documentation standards call for 2 spaces after a period that
ends a sentence; this manual leaves only one space.

This paragraph has an extraneous quote character at its end:

    The second extra option is @code{mh-xemacs-tool-bar-position} which
    controls the placement of the tool bar along the four edges of the
    frame. You can choose from one of @samp{Same As Default Tool Bar},
    @samp{Top}, @samp{Bottom}, @samp{Left}, or @samp{Right}. If this
    variable is set to anything other than @samp{Same As Default Tool Bar}
    and the default tool bar is in a different location, then two tool
    bars will be displayed: the MH-E tool bar and the default tool bar."

This paragraph uses ".." in plain text; you should use ``..'' instead,
as the latter produces a nicer output in PDF and DVI.

    First, run @samp{spamassassin -t} on every mail message in your
    archive and use @command{gnumeric} to verify that the average plus the
    standard deviation of good mail is under 5, the SpamAssassin default
    for "spam".

The text uses @samp{"foo"} when it describes values that are strings.
Here's one of many examples, with the offending @samp marked by <<<<:

    @item mh-scan-body-regexp
    This regular expression matches the message body fragment. Note that
    the default setting of @code{mh-folder-font-lock-keywords} expects
    this expression to contain at least one parenthesized expression which
    matches the body text as in the default of
    @samp{"\\(<<\\([^\n]+\\)?\\)"}. If this regular expression is not <<<<<<<
    correct, the body fragment will not be highlighted with the face
    @code{mh-folder-body}.

I think this usage is not a very good idea: @samp{foo} is typeset as
`foo', so you will have here quotes inside quotes.  I suggest to lose
the inner quotes, since they are redundant IMO.

Some indexing commands need work, IMHO.  Here's one example:

    @cindex Emacs, mark
    @cindex Emacs, point
    @cindex Emacs, region

It is not useful to have several index entries all starting with the
same string and pointing to the same page.  I'd change this to

    @cindex Emacs mark, point and region

Actually, it might be better yet to reverse the parts of the index
entries for the individual terms:

    @cindex mark, in Emacs
    @cindex point, in Emacs
    @cindex region, in Emacs

and then you can discard the entries without ", in Emacs" altogether.

Here's another similar example:

    @cindex @samp{Draft-Folder:} MH profile component
    @cindex @samp{Path:} MH profile component
    @cindex @samp{Previous-Sequence:} MH profile component
    @cindex @samp{Unseen-Sequence:} MH profile component
    @cindex MH profile component, @samp{Draft-Folder:}
    @cindex MH profile component, @samp{Path:}
    @cindex MH profile component, @samp{Previous-Sequence:}
    @cindex MH profile component, @samp{Unseen-Sequence:}

Again, I'd modify the first 4 slightly, like this:

    @cindex @samp{Draft-Folder:}, MH profile component
    @cindex @samp{Path:}, MH profile component
    @cindex @samp{Previous-Sequence:}, MH profile component
    @cindex @samp{Unseen-Sequence:}, MH profile component

and drop the other 4.

OTOH, I didn't see an index entry that explains what is the ``MH
profile'' and how to set it up.

So I suggest to review all your index entries to remove the unhelpful
ones.

Here's incorrect use of @ref:

    The text usually says to turn on an option by setting it to a
    @emph{non-@code{nil}} value, because sometimes values other than
    @samp{on} are meaningful (for example, see @code{mh-mhl-format-file},
    described in @ref{Viewing}).

There should be a period after the right brace that ends the @ref.

Here's another:

    appears in an Emacs buffer whose mode is MH-Letter (see the Figure in
    @ref{Sending Mail Tour} to see what the buffer looks like).

Here, the right brace should be followed by a comma.

Please check all your @ref's, there are some more that lack
punctuation after the right brace.

That's all for now, I hope it helps.