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

[Richard Stallman <rms@gnu.org>]

    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.  It
would not make the list based on the entire Top node menus as a whole;
rather, it would obey certain special entries in them.

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?

If you think this won't work, could you explain the precise problem?

    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

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.

    Then, people can say
      info 'Shell Commands' emacsclient

They could, but that's awfully clumsy.  We would want to change info
so that something simpler can be used, such as

      info command emacsclient

Users won't get the benefit of that improvement until they install a
new version of Texinfo.  Perhaps that is unavoidable, but at least it
doesn't lengthen the critical path.

    Which brings up the point that it would be *ideal* if manual writers
    create separate @direntries for each function name, so that descriptions
    are available for searching:

    @dircategory libc, C
    @direntry
    * strcmp:(libc)Whatever.  Compare two strings.
    @end direntry

That is what I am trying to avoid!

There is no reason to clutter up the dir file by copying large amounts
of text from a few manuals.  It is much better for info readers to
search those few other manuals when the time comes.

The only case where it is worth copying the information into the dir
file is when it comes from many different manuals.