[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: MH-E manual update
From: |
Eli Zaretskii |
Subject: |
Re: MH-E manual update |
Date: |
Sat, 11 Mar 2006 16:30:14 +0200 |
> From: Bill Wohler <address@hidden>
> Date: Mon, 06 Mar 2006 17:29:49 -0800
> Cc: address@hidden
>
> 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
@address@hidden 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.
- Re: MH-E manual update, Bill Wohler, 2006/03/06
- Re: MH-E manual update,
Eli Zaretskii <=
- Re: MH-E manual update, Bill Wohler, 2006/03/11
- Re: MH-E manual update, Luc Teirlinck, 2006/03/11
- Re: MH-E manual update, Bill Wohler, 2006/03/11
- Re: MH-E manual update, Luc Teirlinck, 2006/03/11
- Re: MH-E manual update, Bill Wohler, 2006/03/11
- Re: MH-E manual update, Luc Teirlinck, 2006/03/11