From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: karl@freefriends.org (Karl Berry) Newsgroups: gmane.emacs.devel Subject: Re: Documentation for "Clone Buffers" (corrected version) Date: Sun, 21 Mar 2004 12:18:51 -0500 Sender: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Message-ID: <200403211718.i2LHIpY06619@f7.net> References: NNTP-Posting-Host: deer.gmane.org X-Trace: sea.gmane.org 1079889665 6234 80.91.224.253 (21 Mar 2004 17:21:05 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Sun, 21 Mar 2004 17:21:05 +0000 (UTC) Original-X-From: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Sun Mar 21 18:20:57 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 1B56d7-0006CO-00 for ; Sun, 21 Mar 2004 18:20:57 +0100 Original-Received: from monty-python.gnu.org ([199.232.76.173]) by quimby.gnus.org with esmtp (Exim 3.35 #1 (Debian)) id 1B56d7-0003hy-00 for ; Sun, 21 Mar 2004 18:20:57 +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 1B56cI-0002XQ-59 for emacs-devel@quimby.gnus.org; Sun, 21 Mar 2004 12:20:06 -0500 Original-Received: from list by monty-python.gnu.org with tmda-scanned (Exim 4.30) id 1B56cC-0002WQ-9C for emacs-devel@gnu.org; Sun, 21 Mar 2004 12:20:00 -0500 Original-Received: from mail by monty-python.gnu.org with spam-scanned (Exim 4.30) id 1B56bg-0002Na-Gu for emacs-devel@gnu.org; Sun, 21 Mar 2004 12:19:59 -0500 Original-Received: from [209.61.216.22] (helo=f7.net) by monty-python.gnu.org with esmtp (Exim 4.30) id 1B56bA-0002Er-77; Sun, 21 Mar 2004 12:18:56 -0500 Original-Received: (from karl@localhost) by f7.net (8.11.7-20030920/8.11.7) id i2LHIpY06619; Sun, 21 Mar 2004 12:18:51 -0500 Original-To: rms@gnu.org, emacs-devel@gnu.org In-Reply-To: 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:20688 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:20688 Perhaps the existing `@dircategory' command usable for manuals to insert themselves into these nodes when appropriate. Karl, will it work, or does it need some change? 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? I know you said that having subnodes seems inconvenient to you, but I don't understand why. Putting the information physically into the dir file via install-info, just as we do now with existing dir entries, seems a lot simpler to me. And then the Info readers only have to look at the dir file, rather than delving into every manual. 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 think we can then use @direntry as usual. For example, in the case you mention when there's just a few entries -- @dircategory GNU Emacs, Shell Commands @direntry * emacs: (emacs)Entering Emacs. Extensible, customizable, self-documenting, real-time display editor. * emacsclient: (emacs)Invoking emacsclient. Blah blah. * etags: (emacs)Create Tags Table. Blah blah. @end direntry No changes would be made in emacs.texi's Top node menu. Entries similar to this already exist in many manuals. (So people can type "info ls", for example, and get the ls documentation. This is very useful.) It will be easy to change them to specify subnodes. install-info could then insert the given entries into a subnode of dir named "Shell Commands", in a category "GNU Emacs'. (Such dir categories wouldn't be used by the Info readers, but they could help humans browsing through the nodes, just as categories in the main dir node do now.) Then, people can say info 'Shell Commands' emacsclient (I'm not sure about "Shell Commands" vs. "Commands", but the exact names are clearly a secondary issue.) Also, we could support simply info emacsclient by having the info readers search the subnodes, in some user-definable order, when no matching entry is in the top-level dir node. I also agree that it can be useful to be able to point to a whole index, for example, the glibc function index. Here is a suggestion for that: @dircategory libc, C @direntry * :(libc)Function and Macro Index. * :(libc)Type Index. * :(libc)Variable Index. @end direntry The lack of any menu term tells the info readers that it's an indirection. Or we could put a keyword there, such as "INFOINDEX". Whatever. Eli, about --apropos. If the dir file, with all its subnodes, plus index indirections, becomes a more complete listing of what is available on the system, then I think an apropos command could search that instead of just searching all the indexes of all the manuals. The new dir file will have the names, but more importantly the descriptions (where available). This would be more analogous to man's apropos, which I find quite useful on occasion. Which brings up the point that it would be *ideal* if manual writers create separate @direntries for each function name, so that descriptions are available for searching: @dircategory libc, C @direntry * strcmp:(libc)Whatever. Compare two strings. @end direntry Then users could say, hypothetically, "info-apropos compare" and get a match, just as they can now with man -k. However, since no existing manuals do that (except for commands, in some cases), and since documentation time is a precious commodity, falling back to being able to look at an index seems quite worthwhile. Anyway, those are my thoughts.