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: Sun, 12 Mar 2006 00:10:00 +0200 Message-ID: References: <27306.1134088031@olgas.newt.com> <871wxfnisy.fsf@olgas.newt.com> <9353.1142107690@olgas.newt.com> Reply-To: Eli Zaretskii NNTP-Posting-Host: main.gmane.org X-Trace: sea.gmane.org 1142115114 28386 80.91.229.2 (11 Mar 2006 22:11:54 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Sat, 11 Mar 2006 22:11:54 +0000 (UTC) Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sat Mar 11 23:11:44 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 1FICI3-0001Lm-Di for ged-emacs-devel@m.gmane.org; Sat, 11 Mar 2006 23:10:23 +0100 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1FICI2-0006ax-R8 for ged-emacs-devel@m.gmane.org; Sat, 11 Mar 2006 17:10:22 -0500 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1FICHq-0006ae-KG for emacs-devel@gnu.org; Sat, 11 Mar 2006 17:10:10 -0500 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1FICHp-0006aK-Mt for emacs-devel@gnu.org; Sat, 11 Mar 2006 17:10:10 -0500 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1FICHp-0006aH-JP for emacs-devel@gnu.org; Sat, 11 Mar 2006 17:10:09 -0500 Original-Received: from [192.114.186.66] (helo=romy.inter.net.il) by monty-python.gnu.org with esmtp (Exim 4.52) id 1FICLR-0004y3-28 for emacs-devel@gnu.org; Sat, 11 Mar 2006 17:13:53 -0500 Original-Received: from HOME-C4E4A596F7 (IGLD-80-230-37-47.inter.net.il [80.230.37.47]) by romy.inter.net.il (MOS 3.7.3-GA) with ESMTP id DSO74360 (AUTH halo1); Sun, 12 Mar 2006 00:09:59 +0200 (IST) Original-To: emacs-devel@gnu.org, mh-e-devel@lists.sourceforge.net In-reply-to: <9353.1142107690@olgas.newt.com> (message from Bill Wohler on Sat, 11 Mar 2006 12:08:10 -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:51488 gmane.mail.mh-e.devel:11939 Archived-At: > cc: emacs-devel@gnu.org, mh-e-devel@lists.sourceforge.net > Comments: In-reply-to Eli Zaretskii > message dated "Sat, 11 Mar 2006 16:30:14 +0200." > Date: Sat, 11 Mar 2006 12:08:10 -0800 > From: Bill Wohler > > > 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". Sorry, I don't understand. My last suggestion was to remove the entries that begin with "Emacs, " altogether, so how are the other "Emacs" entries relevant? Anyway, it sounds like you are thinking about a user who looks at the printed version, while I think about someone who looks at the on-line Info version. In the latter case, typing "i Emacs RET" will (eventually) get us to the above entries as well, so nothing is lost. OTOH, with your entries, typing "i Emacs TAB" will show a very long list of entries, which is not too good, I think. In particular, a reader who wants to find the description of point is more likely to type "i point TAB" or "i point RET" than "i Emacs, point". > > 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. That's why I suggested an entry for "MH profile component". With that problem out of your way, you don't need this redundancy. > This indexing technique provides a nice quick-reference table. Index is not the proper vehicle for quick-reference tables. If you want a quick reference, add a short section that summarizes these commands/options, and have an index entry that points to it: @cindex MH profile components, quick reference > Now makeinfo ensures there is only entry per node ?? Perhaps there's a Texinfo feature I'm not aware of--could you show this at work? > 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? I didn't suggest to limit yourself to a single entry per node. I suggested not to have several entries that coincide in too many initial characters. The reason is that it makes TAB-completion less efficient in the `i' command. The `i' command is the key to using the manual as a reference, so anything that gets in the way of it is annoying when you just need to find that one piece of information. > 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? I agree that dropping the "section" part is a good idea.