From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: Richard Stallman Newsgroups: gmane.emacs.devel Subject: Re: Documentation for "Clone Buffers" (corrected version) Date: Sun, 21 Mar 2004 00:00:27 -0500 Sender: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Message-ID: References: <200403191747.i2JHlPS28017@f7.net> <3405-Sat20Mar2004160433+0200-eliz@elta.co.il> Reply-To: rms@gnu.org NNTP-Posting-Host: deer.gmane.org X-Trace: sea.gmane.org 1079845948 19956 80.91.224.253 (21 Mar 2004 05:12:28 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Sun, 21 Mar 2004 05:12:28 +0000 (UTC) Cc: juri@jurta.org, emacs-devel@gnu.org, monnier@iro.umontreal.ca, karl@freefriends.org Original-X-From: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Sun Mar 21 06:12:22 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 1B4vG2-0001kd-00 for ; Sun, 21 Mar 2004 06:12:22 +0100 Original-Received: from monty-python.gnu.org ([199.232.76.173]) by quimby.gnus.org with esmtp (Exim 3.35 #1 (Debian)) id 1B4vG2-0005aY-00 for ; Sun, 21 Mar 2004 06:12:22 +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 1B4vEs-00044e-Qy for emacs-devel@quimby.gnus.org; Sun, 21 Mar 2004 00:11:10 -0500 Original-Received: from list by monty-python.gnu.org with tmda-scanned (Exim 4.30) id 1B4v9C-0001uF-D1 for emacs-devel@gnu.org; Sun, 21 Mar 2004 00:05:18 -0500 Original-Received: from mail by monty-python.gnu.org with spam-scanned (Exim 4.30) id 1B4v8f-0001gG-0t for emacs-devel@gnu.org; Sun, 21 Mar 2004 00:05:16 -0500 Original-Received: from [199.232.76.164] (helo=fencepost.gnu.org) by monty-python.gnu.org with esmtp (Exim 4.30) id 1B4v8e-0001g4-JI for emacs-devel@gnu.org; Sun, 21 Mar 2004 00:04:44 -0500 Original-Received: from rms by fencepost.gnu.org with local (Exim 4.24) id 1B4v4V-0000IM-8S; Sun, 21 Mar 2004 00:00:27 -0500 Original-To: Eli Zaretskii In-reply-to: <3405-Sat20Mar2004160433+0200-eliz@elta.co.il> 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:20669 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:20669 > Thus my original idea (although I guess I did not fully explain it): > 1have one subnode of dir for commands, one for library functions, one for > file formats, etc., analogous to the man sections. Keep the top level > dir itself for the manuals as a whole. I agree that we should find a way to collect commands, collect library functions for C, collect file formats, etc. However, having a node in `dir' with a list of commands, and another with a list of library functions, etc., seems like an inconvenient way to do it. The feature we want is to have an index of all commands. We could do this by creating a node which lists all commands, combining info from various manuals. But we could also make the combination virtually. Manuals could identify themselves as containing relevant entries for a certain area, and info could search the index of each manual. So imagine that there is a node in `dir' that has a menu which contains all the manuals that describe commands. When you ask to search for a command `foo', info would find this node, find all the manuals it points to, then search the index of each manual for `foo'. 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 the Unix Manual, "library function" implicit means "C library function". GNU users use many languages; we cannot assume that "function" means "C function". So I think that we should have a "manual section" for each language, which would list library functions for that language. You would want to do something like info C strcpy to look up the C function strcpy. `C' would specify the "section" of the manual to look in; it would equivalent to `man 2' and `man 3'. The other issue is precisely how to search each manual. Searching the index is useful in some cases, but which index? The Emacs Manual has a "Command Index", but searching in that index for `emacs' won't find it. This same example also illustrates the common case of a manual that documentsjust a small number of commands (or whatever). It would be silly for the Emacs manual to have an index of shell commands, because it defines only one. So a manual that adds itself to the node for "commands" needs to specify how to search that manual for a command. There should be at least two ways to do it: 1. Specify an index to search for a desired command name. 2. Specify specific command names documented in the manual. We could do this with stylized menu items in the Top node. A menu item like this * `emacs' Shell Command: Entering Emacs. could specify where to find the specific command `emacs', and a menu item like this * Index of Shell Commands: NODE NAME. could specify to look for a shell command in index NODE NAME. Likewise we could have * JPEG file format: NODE NAME. or * Index of C Functions: NODE NAME. That would work, but do we really have the power to enforce such an organization of DIR? Not to worry. If we implement this and support it with GNU manuals, people will find it useful and will adapt their manuals to fit it.