Re: MH-E manual update

[Bill Wohler]

Eli Zaretskii <address@hidden> wrote:

> This paragraph has an extraneous quote character at its end:

I thought you weren't reading carefully ;-).

Fixed.

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

Fixed.

> 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.

They aren't redundant since the user actually has to enter the quotes in
his value. I agree that having quotes inside quotes doesn't look good,
but it's probably a necessary evil to be technically correct.

Taking a closer look, let's say we had the convention that you use
quotes for string-valued variables. If you look at this example in
(emacs)Mail Aliases, wrapping the value in double quotes would look
really bad.

  @samp{"George W. Bush" <bush@@whitehouse.gov>}.

While the user has to enter the quotes in a setq, they don't in the
customization buffer, so that would be a good argument for removing the
quotes.

OK, I might have talked myself into removing the quotes but I'd like to
first measure the consensus. Looking at the existing strings in the
manual, there doesn't seem to be a clear precedent or convention, but
rather a mix of usage.

What do others think about the addition of literal quotes in a @samp{}
for a string value?

> 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.

I disagree. You can't look at this example in isolation. If you're in
the index with a lot of other "Emacs" entries, you might not find the
"region" entry using your suggested entry since it would sorted under
"m".

> 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.

I disagree, but for a different reason. The user might know that he's
looking for an "MH profile component" but can't quite remember the name.
This indexing technique provides a nice quick-reference table.

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

Fixed.

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

In the old days, when makeinfo dutifully indexed every entry, a good
convention was to take care to have one index entry per node per item.
The problem with that is that when you move paragraphs around, you might
either "steal" an index entry from a node, or "forget" to add a new
entry in the new node.

Now makeinfo ensures there is only entry per node so I thought it would
be a good idea to add appropriate index entries to each paragraph,
independent of the context. That way, if you move the paragraph, the
index entries go with it. Thoughts?

> 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.

Thanks. I fixed a handful of them.

Question: Cross-references with five arguments are preceded by
"section" in printed output (texi2pdf), but not in info output. Where
there is a URL to the same document, I insert a @uref in @ifhtml. I've
been inserting the word "section" before the @uref to be consistent with
the printed manual, but now I'm thinking I should just drop the word
"section" to be consistent with Info and let @uref do what it wants to
do. Thoughts?

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

Great feedback, Eli, thanks!

-- 
Bill Wohler <address@hidden>  http://www.newt.com/wohler/  GnuPG ID:610BD9AD
Maintainer of comp.mail.mh FAQ and MH-E. Vote Libertarian!
If you're passed on the right, you're in the wrong lane.