From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Bill Wohler Newsgroups: gmane.mail.mh-e.devel,gmane.emacs.devel Subject: Re: MH-E manual update Date: Sat, 11 Mar 2006 12:08:10 -0800 Organization: Newt Software Message-ID: <9353.1142107690@olgas.newt.com> References: <27306.1134088031@olgas.newt.com> <871wxfnisy.fsf@olgas.newt.com> NNTP-Posting-Host: main.gmane.org X-Trace: sea.gmane.org 1142107759 3592 80.91.229.2 (11 Mar 2006 20:09:19 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Sat, 11 Mar 2006 20:09:19 +0000 (UTC) Cc: emacs-devel@gnu.org, mh-e-devel@lists.sourceforge.net Original-X-From: mh-e-devel-admin@lists.sourceforge.net Sat Mar 11 21:09:13 2006 Return-path: Envelope-to: gmmd-mh-e-devel@m.gmane.org Original-Received: from lists-outbound.sourceforge.net ([66.35.250.225]) by ciao.gmane.org with esmtp (Exim 4.43) id 1FIAOh-0007un-4X for gmmd-mh-e-devel@m.gmane.org; Sat, 11 Mar 2006 21:09:07 +0100 Original-Received: from sc8-sf-list1-b.sourceforge.net (sc8-sf-list1-b.sourceforge.net [10.3.1.7]) by sc8-sf-spam2.sourceforge.net (Postfix) with ESMTP id 6001112BFA; Sat, 11 Mar 2006 12:09:06 -0800 (PST) Original-Received: from sc8-sf-mx2-b.sourceforge.net ([10.3.1.92] helo=mail.sourceforge.net) by sc8-sf-list1.sourceforge.net with esmtp (Exim 4.30) id 1FIANq-0000X7-La for mh-e-devel@lists.sourceforge.net; Sat, 11 Mar 2006 12:08:14 -0800 Original-Received: from pop-cowbird.atl.sa.earthlink.net ([207.69.195.68]) by mail.sourceforge.net with esmtp (Exim 4.44) id 1FIANp-00073M-14 for mh-e-devel@lists.sourceforge.net; Sat, 11 Mar 2006 12:08:14 -0800 Original-Received: from h-68-165-5-58.snvacaid.dynamic.covad.net ([68.165.5.58] helo=olgas.newt.com) by pop-cowbird.atl.sa.earthlink.net with esmtp (Exim 3.36 #10) id 1FIANn-0005qk-00; Sat, 11 Mar 2006 15:08:11 -0500 Original-Received: by olgas.newt.com (Postfix, from userid 1000) id 8A38F1707E; Sat, 11 Mar 2006 12:08:10 -0800 (PST) Original-Received: from olgas.newt.com (localhost [127.0.0.1]) by olgas.newt.com (Postfix) with ESMTP id 8692716FB0; Sat, 11 Mar 2006 12:08:10 -0800 (PST) Original-To: Eli Zaretskii In-reply-to: Comments: In-reply-to Eli Zaretskii message dated "Sat, 11 Mar 2006 16:30:14 +0200." X-Mailer: MH-E 7.93+cvs; nmh 1.1; GNU Emacs 22.0.50.14 X-Image-URL: http://www.newt.com/wohler/images/bill-diving.png Mail-Followup-To: emacs-devel@gnu.org, mh-e-devel@lists.sourceforge.net X-Spam-Score: 1.0 (+) X-Spam-Report: Spam Filtering performed by sourceforge.net. See http://spamassassin.org/tag/ for more details. Report problems to http://sf.net/tracker/?func=add&group_id=1&atid=200001 1.0 FORGED_RCVD_HELO Received: contains a forged HELO Original-Sender: mh-e-devel-admin@lists.sourceforge.net Errors-To: mh-e-devel-admin@lists.sourceforge.net X-BeenThere: mh-e-devel@lists.sourceforge.net X-Mailman-Version: 2.0.9-sf.net Precedence: bulk List-Unsubscribe: , List-Id: Forum for the MH-E developers List-Post: List-Help: List-Subscribe: , List-Archive: X-Original-Date: Sat, 11 Mar 2006 12:08:10 -0800 Xref: news.gmane.org gmane.mail.mh-e.devel:11937 gmane.emacs.devel:51476 Archived-At: Eli Zaretskii 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" }. 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 > @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. 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 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. ------------------------------------------------------- This SF.Net email is sponsored by xPML, a groundbreaking scripting language that extends applications into web and mobile media. Attend the live webcast and join the prime developer group breaking into this new coding territory! http://sel.as-us.falkag.net/sel?cmd=lnk&kid=110944&bid=241720&dat=121642