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

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

> From: Richard Stallman <rms@gnu.org>
> Date: Mon, 22 Mar 2004 22:04:10 -0500
> 
>     If we want each category to go into a separate node of DIR, that would
>     require a relatively simple change to install-info, 
> 
> That is not what I suggested.  My suggestion is much simpler:
> create a few specific categories and put them in subnodes.

How is that simpler (or do I again misunderstand you)?  The category
name that appears in the @dircategory directive is arbitrary text;
install-info knows nothing about it, it just copies it verbatim to DIR
and groups together @direntry groups that appear within the same
@dircategory.  The only way for DIR to have only a small number of
categories is to ask the manual authors to exercise self-discipline
and use a small set of standard categories.  (The current list of
recommended categories appears in the node "Installing Dir Entries" in
the Texinfo manual.)

[I'm sure I didn't say anything you didn't know already, but I'm
writing this to make my thoughts explicit, so that you or someone else
could point out what is it that I misunderstand.]

Are you suggesting that install-info treats a few categories, like
"Shell Commands" and "Library Functions", specially?  Or are you
suggesting that the modifications of the @dircategory groups should be
the responsibility of manual maintainers, and that the ``few specific
categories'' would be created because the manual maintainers use them
in such a disciplined manner?

> The Make manual now says:
> 
>     @dircategory GNU Packages
>     @direntry
>     * Make: (make).            Remake files automatically.
>     @end direntry
> 
> My proposal would change that to
> 
>     @dircategory GNU Packages
>     @dircategory Shell Commands
>     @direntry
>     * Make: (make).            Remake files automatically.
>     @end direntry

Okay, but what will this produce in DIR?  Do you want the named
@direntry go to 2 nodes in DIR, one for "GNU Packages", the other for
"Shell Commands"?

Also, the second form above, the one you proposed, does not work with
the current versions of install-info: install-info needs one or more
@direntry's between any two @dircategory's, not the other way around.
In other words, if a manual wants to install menu items in more than
one category, it needs to list those entries several times, one each
for every category.  So to be compatible with the current codebase,
your example above needs to become

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

    @dircategory Shell Commands
    @direntry
    * Make: (make).            Remake files automatically.
    @end direntry

Btw, as I wrote elsewhere in this thread, it might be more
user-friendly for each category to point to a different node in the
manual: in our Make example, people who look for the description of
`make' the shell command are more likely to wish to see the node that
describes how to run Make and what are its command-line switches.