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

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

> From: Richard Stallman <rms@gnu.org>
> Date: Mon, 22 Mar 2004 00:25:15 -0500
> 
>     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?
> 
> Partly.  It would not read all of the dir file, just a subnode.

That would require a fundamental change in the Info reader.
Currently, both Emacs and the stand-alone reader cannot read a single
node, they always read the entire file and then create several data
structures from its contents, before they even look at the first node.
An Info file can include tag tables and indirect tables that need to
be processed as part of this.

> The point of using @dircategory is to put entries for certain manuals
> into the subnode of dir.
> 
>     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 don't understand why this optional argument is necessary.  Can't
> @dircategory already do this job with no change, if we set up the dir
> file properly?

I think Karl wants DIR to have both its current top-level, include-all
menu, and the separate nodes, one each for each category.

If we want each category to go into a separate node of DIR, that would
require a relatively simple change to install-info, but it does have
its disadvantages: no single menu with all the manuals listed in it,
and no simple way of updating the DIR file except through
install-info.

But I, too, feel I don't understand your vision sufficiently well.
Could you perhaps describe an approximate sequence of operations to be
used by an Info reader to do what you want, starting with a sample
command line?

>     install-info could then insert the given entries into a subnode of dir
>     named "Shell Commands", in a category "GNU Emacs'.
> 
> I don't see a need for categories within the menu in the Shell
> Commands node.  That node would exist specifically for man-style
> lookup.  The order of manuals within that node would not matter.
> 
> So it only needs to have one category, which could be called Shell
> Commands.  All the manual needs is
> 
>   @dircategory Shell Commands

I don't think it's quite that simple, unfortunately.  Take the GNU
Make manual, for example: it mainly describes the features of Make
itself, not `make' as a shell command.  So its @dircategory and
@direntry currently say

    @dircategory GNU Packages
    @direntry
    * Make: (make).            Remake files automatically.
    @end direntry

AFAIU, you want the manual author to provide 2 categories: one as
above, the other saying something like

    @dircategory Shell Commands
    @direntry
    * Make: (make)Running.     How to invoke GNU Make from the shell.
    @end direntry

and you want install-info to put each one of these menu items into a
different node: one node for "GNU Packages", the other for "Shell
Commands".  Is that true?

The main disadvantage of this, as I see it, is that manuals will now
require quite a few different @dircategory/@direntry directives,
carefully thought out in terms of the resultant DIR organization.
Past experience suggests that it is not easy to force DIR
organization, especially since a coordinated effort of all GNU
maintainers is required.

That is why a more automated way of gleaning the necessary information
from indices and top-level menus might be a better approach, as it
requires less coordination between numerous humans.

(As an aside, the current stand-alone Info reader's solution to
quickly arrive at the node for Make that describes its usage as a
shell command is to say

	info --usage make

That lands you in the Running node without any help from @direntry,
and provides the same functionality as the "man make" command.)

> This way, no changes are needed in the specifications of the Texinfo
> language.  People could change manuals starting immediately, without
> waiting to be able to install a new version of Texinfo.

In practice, they do need to wait for a new Texinfo, since any change
in the organization of DIR requires changes in install-info at least.
The change you propose seems to require changes in the Info readers as
well.