[Top][All Lists]

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

RE: Regarding outline headings in emacs-lisp libraries

From: Drew Adams
Subject: RE: Regarding outline headings in emacs-lisp libraries
Date: Sat, 18 Jul 2020 16:15:25 +0000 (UTC)

> > 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.


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


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.

reply via email to

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