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: 21 Mar 2004 08:19:06 +0200 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: Eli Zaretskii NNTP-Posting-Host: deer.gmane.org X-Trace: sea.gmane.org 1079850122 26562 80.91.224.253 (21 Mar 2004 06:22:02 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Sun, 21 Mar 2004 06:22:02 +0000 (UTC) Cc: juri@jurta.org, emacs-devel@gnu.org, karl@freefriends.org Original-X-From: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Sun Mar 21 07:21: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 1B4wLM-0003Ao-00 for ; Sun, 21 Mar 2004 07:21: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 1B4wLL-0007fW-00 for ; Sun, 21 Mar 2004 07:21:55 +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 1B4wH1-0003hv-ML for emacs-devel@quimby.gnus.org; Sun, 21 Mar 2004 01:17:27 -0500 Original-Received: from list by monty-python.gnu.org with tmda-scanned (Exim 4.30) id 1B4wGu-0003hj-Qu for emacs-devel@gnu.org; Sun, 21 Mar 2004 01:17:20 -0500 Original-Received: from mail by monty-python.gnu.org with spam-scanned (Exim 4.30) id 1B4wGN-0003WL-VW for emacs-devel@gnu.org; Sun, 21 Mar 2004 01:17:19 -0500 Original-Received: from [207.232.27.5] (helo=WST0054) by monty-python.gnu.org with asmtp (Exim 4.30) id 1B4wGM-0003Vn-UB; Sun, 21 Mar 2004 01:16:47 -0500 Original-To: rms@gnu.org In-reply-to: (message from Richard Stallman on Sun, 21 Mar 2004 00:00:27 -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:20673 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:20673 > From: Richard Stallman > Date: Sun, 21 Mar 2004 00:00:27 -0500 > > 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'. If implemented naively, that could be prohibitively slow, I think. To get a feeling how slow, try "info --apropos=SOMETHING" with the stand-alone Info reader. The main problem here is, I think, that Info manuals tend to have very large indices, and the algorithms used to search through the index do not scale very well. > 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? I think we need a feature that could create and update a database like `apropos' from the `man' package does, and then use it for fast lookups like those suggested. The resultant database could be written into the DIR file, if that's what we want, but I'd suggest to keep it separate, since it generally is not meant for human consumption, while DIR is. install-info could be charged with the job of maintaining the database. > In the Unix Manual, "library function" implicit means "C library > function". Not on some of the systems I work on: Fortran functions are in section 3F, C library functions are in 3C, and there are other 3x sections for libraries other than libc. They all are searched if you say "man --section=3 FOO" or its equivalent. > 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'. Earlier in this thread, I suggested that "info libc strcpy" would do the job (and works with the current Texinfo codebase if the libc manual lists all the functions in the "Detailed Menu" part of its Top node), but others say that it's too much of a burden to remember the word "libc" in this context. > 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. I think we should not rely on automatic index searches: in my experience, they yield too many false hits. > 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: If we rely on humans to do any significant part of the job, why not ask them to do it all the way? Let's have a new Texinfo command that will add its argument to a global index used to do searches in all the manuals. For example, the following directive @gindex strcpy will produce something that install-info could copy to the system-wide database I mentioned above. (Actually, @gindex is a bad name, since some manual could already use it for its own private index names.) > 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. We have a very different experience with similar issues; Karl knows all about that, I think.