RE: Regarding outline headings in emacs-lisp libraries

[Drew Adams]

> > B) The OVERVIEW shown above isn't just not useful, for more complex
> >    libraries (which are split into more (sub*)sections) having a
> >    useful OVERVIEW is quite important.
> >
> >    For such libraries the TOC just isn't a suitable substitute for
> >    OVERVIEW.  It could be deeply nested and if one only wants a list
> >    of the "major sections of a program", then a deeply nested tree of
> >    sub*sections just isn't the same.
> 
> ... I haven't found a case of a file where the TOC is so
> large that it warrants the OVERVIEW.  And I'd even claim
> that such a file would be just too large and should
> likely benefit from splitting it into a few files.

FWIW -

In my Elisp libraries I often put an Index in the
Commentary, with links to the major sections.  For
this I use the simple library `linkd.el', which is
here:

https://www.emacswiki.org/emacs/download/linkd.el

When in minor-mode `linkd-mode', the links and
their targets are highlighted.

The major sections I use differ, depending on the
library.  Here's an example:

;;  (@> "Things Defined Here")
;;  (@> "Documentation")
;;  (@> "Macros")
;;  (@> "Faces (Customizable)")
;;  (@> "User Options (Customizable)")
;;  (@> "Internal Variables")
;;  (@> "New Commands")
;;  (@> "Replacements for Existing Functions")
;;  (@> "Non-Interactive Functions")

Each section begins with corresponding link-target
(anchor) text.  E.g., the "Macros" section has this:

;;(@* "Macros")

(I typically also put a formfeed (^L) char before
that line.  That lets me use `C-x ]' and `C-x [',
and with library `pp-c-l.el' I get clear visual
indication of ^L chars, i.e., of the sections.)

Org Mode offers similar linking, of course, but
Linkd is simple.