Re: Documentation for "Clone Buffers" (corrected version)

[Eli Zaretskii <eliz@elta.co.il>]

> From: Richard Stallman <rms@gnu.org>
> 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.