From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel,gmane.mail.mh-e.devel Subject: Re: MH-E manual update Date: Sat, 11 Mar 2006 16:30:14 +0200 Message-ID: References: <27306.1134088031@olgas.newt.com> <871wxfnisy.fsf@olgas.newt.com> Reply-To: Eli Zaretskii NNTP-Posting-Host: main.gmane.org X-Trace: sea.gmane.org 1142087437 4717 80.91.229.2 (11 Mar 2006 14:30:37 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Sat, 11 Mar 2006 14:30:37 +0000 (UTC) Cc: mh-e-devel@lists.sourceforge.net, emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sat Mar 11 15:30:35 2006 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by ciao.gmane.org with esmtp (Exim 4.43) id 1FI574-0001lw-8Y for ged-emacs-devel@m.gmane.org; Sat, 11 Mar 2006 15:30:34 +0100 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1FI573-0002ak-Oi for ged-emacs-devel@m.gmane.org; Sat, 11 Mar 2006 09:30:33 -0500 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1FI56s-0002Zu-46 for emacs-devel@gnu.org; Sat, 11 Mar 2006 09:30:22 -0500 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1FI56r-0002ZV-Dn for emacs-devel@gnu.org; Sat, 11 Mar 2006 09:30:21 -0500 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1FI56r-0002ZR-AD for emacs-devel@gnu.org; Sat, 11 Mar 2006 09:30:21 -0500 Original-Received: from [192.114.186.17] (helo=gandalf.inter.net.il) by monty-python.gnu.org with esmtp (Exim 4.52) id 1FI5AO-0007F4-7N for emacs-devel@gnu.org; Sat, 11 Mar 2006 09:34:00 -0500 Original-Received: from nitzan.inter.net.il (nitzan.inter.net.il [192.114.186.20]) by gandalf.inter.net.il (MOS 3.7.1-GA) with ESMTP id ICU05913; Sat, 11 Mar 2006 16:30:15 +0200 (IST) Original-Received: from HOME-C4E4A596F7 (IGLD-83-130-214-30.inter.net.il [83.130.214.30]) by nitzan.inter.net.il (MOS 3.7.3-GA) with ESMTP id CWG64190 (AUTH halo1); Sat, 11 Mar 2006 16:30:14 +0200 (IST) Original-To: Bill Wohler In-reply-to: <871wxfnisy.fsf@olgas.newt.com> (message from Bill Wohler on Mon, 06 Mar 2006 17:29:49 -0800) X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:51466 gmane.mail.mh-e.devel:11936 Archived-At: > From: Bill Wohler > 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.