emacs-devel
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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


From: Karl Berry
Subject: Re: Documentation for "Clone Buffers" (corrected version)
Date: Sun, 21 Mar 2004 12:18:51 -0500

    Perhaps the existing address@hidden' command usable for manuals to
    insert themselves into these nodes when appropriate.  Karl, will it
    work, or does it need some change?

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?

I know you said that having subnodes seems inconvenient to you, but I
don't understand why.  Putting the information physically into the dir
file via install-info, just as we do now with existing dir entries,
seems a lot simpler to me.  And then the Info readers only have to look
at the dir file, rather than delving into every manual.

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 think we can then use @direntry as usual.
For example, in the case you mention when there's just a few entries --

@dircategory GNU Emacs, Shell Commands
@direntry
* emacs: (emacs)Entering Emacs.  Extensible, customizable,
                                 self-documenting, real-time display editor.
* emacsclient: (emacs)Invoking emacsclient.  Blah blah.
* etags: (emacs)Create Tags Table.  Blah blah.
@end direntry

No changes would be made in emacs.texi's Top node menu.

Entries similar to this already exist in many manuals.  (So people can
type "info ls", for example, and get the ls documentation.  This is very
useful.)  It will be easy to change them to specify subnodes.

install-info could then insert the given entries into a subnode of dir
named "Shell Commands", in a category "GNU Emacs'.  (Such dir categories
wouldn't be used by the Info readers, but they could help humans
browsing through the nodes, just as categories in the main dir node do now.)

Then, people can say
  info 'Shell Commands' emacsclient

(I'm not sure about "Shell Commands" vs. "Commands", but the exact names
are clearly a secondary issue.)

Also, we could support simply
  info emacsclient
by having the info readers search the subnodes, in some user-definable
order, when no matching entry is in the top-level dir node.


I also agree that it can be useful to be able to point to a whole index,
for example, the glibc function index.  Here is a suggestion for that:

@dircategory libc, C
@direntry
* :(libc)Function and Macro Index.
* :(libc)Type Index.
* :(libc)Variable Index.
@end direntry

The lack of any menu term tells the info readers that it's an indirection.
Or we could put a keyword there, such as "INFOINDEX".  Whatever.


Eli, about --apropos.  If the dir file, with all its subnodes, plus
index indirections, becomes a more complete listing of what is available
on the system, then I think an apropos command could search that instead
of just searching all the indexes of all the manuals.  The new dir file
will have the names, but more importantly the descriptions (where
available).  This would be more analogous to man's apropos, which I find
quite useful on occasion.

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

Then users could say, hypothetically, "info-apropos compare" and get a
match, just as they can now with man -k.

However, since no existing manuals do that (except for commands, in some
cases), and since documentation time is a precious commodity, falling
back to being able to look at an index seems quite worthwhile.


Anyway, those are my thoughts.




reply via email to

[Prev in Thread] Current Thread [Next in Thread]