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

[Richard Stallman <rms@gnu.org>]

    > 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.