RE: describe-bindings: ^L, bad order, naming

[Drew Adams]

    > Why not just do what the OP suggested: list the section titles in
    > the beginning, linked to the sections themselves (exactly as in
    > the *Help* buffer). That would be perfect. Such an approach is
    > common both on the Web and in technical documents (e.g.
    > reference-book chapters): a preliminary TOC with links.

    Though in practice, it's highly annoying in for instance
    describe-mode, because the "table of contents" is usually
    very bloated and pushes useful text off the screen.

I don't see that, but it could happen if there are many minor modes in
effect.

IIUC, we would have the same problem using Outline mode for `describe-mode'.
If the outline were all closed up, by default, then it would appear just
like the TOC. If it were only partly closed up, then the problem you mention
would be worse.

And worse would happen when any of the outline lines were opened - even more
stuff would be pushed off the screen.

The only way around the problem you raise, if it really is a problem, is to
have a hierarchical outline (or a hierachy of TOCs), which shows a smaller
number of more-major topic lines. I don't see the `describe-bindings'
content being organized that way - it's naturally flat.

I also don't see it having the problem you raise, however. Here's a
`describe-bindings' TOC for Dired mode (some other modes would have even
fewer entries). Each line would be a link to its list of bindings, and
*only* its bindings. IOW, instead of having pages in linear order
(^L...^L...^L...), we would have a hyperlinked (shallow) tree.

  Key Translations
  Minor Mode Bindings
  Major Mode Bindings
  Global Bindings
  Function Key Map Translations

(I'm not sure that's the best order, BTW, but that's the order we have
today. And is that "function-key map translations" or "function keymap
translations" - or perhaps just "function-key translations"?)

That's not too much for one screen, is it? The link could open the
appropriate bindings list in another window (another frame, if pop-up-frames
= non-nil), so that the TOC remains visible. If not, the bindings-list pages
should at least have a Back button, to get back to the TOC.

Yes, that's just like outline mode, but the link metaphor is more obvious
and more familiar. Yes, if we had +/- signs, outline mode would act like the
GUI trees that people are accustomed to, and it would be (almost) as good as
the TOC, here.