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: 22 Mar 2004 09:26:13 +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 1079940535 31166 80.91.224.253 (22 Mar 2004 07:28:55 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Mon, 22 Mar 2004 07:28:55 +0000 (UTC) Cc: emacs-devel@gnu.org, karl@freefriends.org Original-X-From: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Mon Mar 22 08:28:47 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 1B5Jrb-0005Oa-00 for ; Mon, 22 Mar 2004 08:28:47 +0100 Original-Received: from monty-python.gnu.org ([199.232.76.173]) by quimby.gnus.org with esmtp (Exim 3.35 #1 (Debian)) id 1B5Jrb-00067W-00 for ; Mon, 22 Mar 2004 08:28:47 +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 1B5Jnb-00045Y-GM for emacs-devel@quimby.gnus.org; Mon, 22 Mar 2004 02:24:39 -0500 Original-Received: from list by monty-python.gnu.org with tmda-scanned (Exim 4.30) id 1B5JnV-00041Y-QA for emacs-devel@gnu.org; Mon, 22 Mar 2004 02:24:33 -0500 Original-Received: from mail by monty-python.gnu.org with spam-scanned (Exim 4.30) id 1B5Jmw-0003jL-JT for emacs-devel@gnu.org; Mon, 22 Mar 2004 02:24:29 -0500 Original-Received: from [207.232.27.5] (helo=WST0054) by monty-python.gnu.org with asmtp (Exim 4.30) id 1B5Jmv-0003fT-SL; Mon, 22 Mar 2004 02:23:58 -0500 Original-To: rms@gnu.org In-reply-to: (message from Richard Stallman on Mon, 22 Mar 2004 00:25:15 -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:20715 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:20715 > From: Richard Stallman > Date: Mon, 22 Mar 2004 00:25:15 -0500 > > In your proposal of messing with Top node menus, I don't see that > @dircategory matters at all. The Info readers read the top-level dir > file, get the list of Info manuals to look in, then go look at each of > their Top menus to virtually construct the list of whatever the user is > interested in. Do I have the general idea right? > > Partly. It would not read all of the dir file, just a subnode. That would require a fundamental change in the Info reader. Currently, both Emacs and the stand-alone reader cannot read a single node, they always read the entire file and then create several data structures from its contents, before they even look at the first node. An Info file can include tag tables and indirect tables that need to be processed as part of this. > The point of using @dircategory is to put entries for certain manuals > into the subnode of dir. > > Along that line, what comes to my mind is a second optional argument to > @dircategory, specifying the subnode of dir to use (Shell Commands, C > Functions, or whatever). > > I don't understand why this optional argument is necessary. Can't > @dircategory already do this job with no change, if we set up the dir > file properly? I think Karl wants DIR to have both its current top-level, include-all menu, and the separate nodes, one each for each category. If we want each category to go into a separate node of DIR, that would require a relatively simple change to install-info, but it does have its disadvantages: no single menu with all the manuals listed in it, and no simple way of updating the DIR file except through install-info. But I, too, feel I don't understand your vision sufficiently well. Could you perhaps describe an approximate sequence of operations to be used by an Info reader to do what you want, starting with a sample command line? > install-info could then insert the given entries into a subnode of dir > named "Shell Commands", in a category "GNU Emacs'. > > I don't see a need for categories within the menu in the Shell > Commands node. That node would exist specifically for man-style > lookup. The order of manuals within that node would not matter. > > So it only needs to have one category, which could be called Shell > Commands. All the manual needs is > > @dircategory Shell Commands I don't think it's quite that simple, unfortunately. Take the GNU Make manual, for example: it mainly describes the features of Make itself, not `make' as a shell command. So its @dircategory and @direntry currently say @dircategory GNU Packages @direntry * Make: (make). Remake files automatically. @end direntry AFAIU, you want the manual author to provide 2 categories: one as above, the other saying something like @dircategory Shell Commands @direntry * Make: (make)Running. How to invoke GNU Make from the shell. @end direntry and you want install-info to put each one of these menu items into a different node: one node for "GNU Packages", the other for "Shell Commands". Is that true? The main disadvantage of this, as I see it, is that manuals will now require quite a few different @dircategory/@direntry directives, carefully thought out in terms of the resultant DIR organization. Past experience suggests that it is not easy to force DIR organization, especially since a coordinated effort of all GNU maintainers is required. That is why a more automated way of gleaning the necessary information from indices and top-level menus might be a better approach, as it requires less coordination between numerous humans. (As an aside, the current stand-alone Info reader's solution to quickly arrive at the node for Make that describes its usage as a shell command is to say info --usage make That lands you in the Running node without any help from @direntry, and provides the same functionality as the "man make" command.) > This way, no changes are needed in the specifications of the Texinfo > language. People could change manuals starting immediately, without > waiting to be able to install a new version of Texinfo. In practice, they do need to wait for a new Texinfo, since any change in the organization of DIR requires changes in install-info at least. The change you propose seems to require changes in the Info readers as well.