From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: Documentation for "Clone Buffers" (corrected version) Date: 23 Mar 2004 08:10:26 +0200 Sender: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Message-ID: References: <200403211718.i2LHIpY06619@f7.net> Reply-To: Eli Zaretskii NNTP-Posting-Host: deer.gmane.org X-Trace: sea.gmane.org 1080022262 32131 80.91.224.253 (23 Mar 2004 06:11:02 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Tue, 23 Mar 2004 06:11:02 +0000 (UTC) Cc: emacs-devel@gnu.org, karl@freefriends.org Original-X-From: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Tue Mar 23 07:10:56 2004 Return-path: Original-Received: from quimby.gnus.org ([80.91.224.244]) by deer.gmane.org with esmtp (Exim 3.35 #1 (Debian)) id 1B5f7o-0004C0-00 for ; Tue, 23 Mar 2004 07:10:56 +0100 Original-Received: from monty-python.gnu.org ([199.232.76.173]) by quimby.gnus.org with esmtp (Exim 3.35 #1 (Debian)) id 1B5f7o-00013N-00 for ; Tue, 23 Mar 2004 07:10:56 +0100 Original-Received: from localhost ([127.0.0.1] helo=monty-python.gnu.org) by monty-python.gnu.org with esmtp (Exim 4.30) id 1B5f6I-0003lG-M8 for emacs-devel@quimby.gnus.org; Tue, 23 Mar 2004 01:09:22 -0500 Original-Received: from list by monty-python.gnu.org with tmda-scanned (Exim 4.30) id 1B5f5k-0003ix-DN for emacs-devel@gnu.org; Tue, 23 Mar 2004 01:08:48 -0500 Original-Received: from mail by monty-python.gnu.org with spam-scanned (Exim 4.30) id 1B5f5D-0003Vy-Qt for emacs-devel@gnu.org; Tue, 23 Mar 2004 01:08:47 -0500 Original-Received: from [207.232.27.5] (helo=WST0054) by monty-python.gnu.org with asmtp (Exim 4.30) id 1B5f5C-0003Mg-Oc; Tue, 23 Mar 2004 01:08:15 -0500 Original-To: rms@gnu.org In-reply-to: (message from Richard Stallman on Mon, 22 Mar 2004 22:04:10 -0500) X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.4 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Xref: main.gmane.org gmane.emacs.devel:20767 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:20767 > From: Richard Stallman > Date: Mon, 22 Mar 2004 22:04:10 -0500 > > If we want each category to go into a separate node of DIR, that would > require a relatively simple change to install-info, > > That is not what I suggested. My suggestion is much simpler: > create a few specific categories and put them in subnodes. How is that simpler (or do I again misunderstand you)? The category name that appears in the @dircategory directive is arbitrary text; install-info knows nothing about it, it just copies it verbatim to DIR and groups together @direntry groups that appear within the same @dircategory. The only way for DIR to have only a small number of categories is to ask the manual authors to exercise self-discipline and use a small set of standard categories. (The current list of recommended categories appears in the node "Installing Dir Entries" in the Texinfo manual.) [I'm sure I didn't say anything you didn't know already, but I'm writing this to make my thoughts explicit, so that you or someone else could point out what is it that I misunderstand.] Are you suggesting that install-info treats a few categories, like "Shell Commands" and "Library Functions", specially? Or are you suggesting that the modifications of the @dircategory groups should be the responsibility of manual maintainers, and that the ``few specific categories'' would be created because the manual maintainers use them in such a disciplined manner? > The Make manual now says: > > @dircategory GNU Packages > @direntry > * Make: (make). Remake files automatically. > @end direntry > > My proposal would change that to > > @dircategory GNU Packages > @dircategory Shell Commands > @direntry > * Make: (make). Remake files automatically. > @end direntry Okay, but what will this produce in DIR? Do you want the named @direntry go to 2 nodes in DIR, one for "GNU Packages", the other for "Shell Commands"? Also, the second form above, the one you proposed, does not work with the current versions of install-info: install-info needs one or more @direntry's between any two @dircategory's, not the other way around. In other words, if a manual wants to install menu items in more than one category, it needs to list those entries several times, one each for every category. So to be compatible with the current codebase, your example above needs to become @dircategory GNU Packages @direntry * Make: (make). Remake files automatically. @end direntry @dircategory Shell Commands @direntry * Make: (make). Remake files automatically. @end direntry Btw, as I wrote elsewhere in this thread, it might be more user-friendly for each category to point to a different node in the manual: in our Make example, people who look for the description of `make' the shell command are more likely to wish to see the node that describes how to run Make and what are its command-line switches.