RE: Regarding outline headings in emacs-lisp libraries

[Drew Adams <drew.adams@oracle.com>]

> > 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'
> 
> I used that library too for a while.  It's neat but ultimately I
> decided it wasn't *necessary*.
> 
> 1. Emacs already provided a convention and implementation for outlines
>    that I liked.
> 2. I didn't want to manually maintain an index in the commentary like
>    you do.  (And I realize that I don't have to do that.)
> 3. Links are orthogonal to sections and don't have to be implemented
>    in the same package.
> 
> But most importantly we would never be able to convince "everybody"
> to use this library.  I expect `outline-minor-mode' to be less
> controversial and thus the easier sell.

I just mentioned it as a FWIW.  Nothing is
"*necessary*".  I wasn't proposing to convince
everybody, or anybody for that matter, to use
`linkd.el'.  There's no contest with Org or
`outline-minor-mode' or anything else.

Using text anchors, or form-feed chars, or both,
for links are alternative ways to define sections
to the way you propose.  They're not orthogonal
to it. 

Any way of defining sections is orthogonal to
folding or otherwise focusing on a section or
hiding sections.

And any way of defining sections is orthogonal
to having a separate index/TOC that links to
sections.  And to having commands that go to
the next/previous section.

I personally don't need/use folding for Elisp
files, and I personally do want easy ways to
move among sections.

You'll say that folding provides, in a way, an
index/TOC, which is true.  But an explicit one
doesn't require anyone to know about or use
folding (or Linkd, for that matter).

> > Org Mode offers similar linking, of course,
> > but Linkd is simple.
> 
> I ended up implementing `orglink.el' which allows you to "use Org Mode
> links in other modes". ;P

Good.  So it sounds like it has some of the Linkd
features (the only ones I use, perhaps), but it
uses Org mode-style links.  Either style is OK by
me.  Not much difference between the two, anyway:

Unrendered:

 (* "Linkd-style anchor")
 (@ "Linkd-style link")

 <<Org-style anchor>>
 [[Org-style link]]

Rendered (and highlighted):

 * Linkd anchor    *, text in diff faces, + mouse-face
 > Linkd link      >, text in diff faces, + mouse-face

 <<Org anchor>>    in a face
 Org link          in a face, + mouse-face

Now that `orglink.el' exists, maybe I'll switch to
using that, who knows?  But it does require loading
Org - and dash.el, which is pretty heavyweight for
just what it offers, no?

BTW, I just downloaded it, loaded a version of dash.el
(required, unfortunately), loaded orglink.el, and got
this (Emacs 26.3) when I tried `M-x orglink-mode' in
buffer orglink.el:

Debugger entered--Lisp error: (void-variable org-link-descriptive)
  (set (make-local-variable (quote org-link-descriptive)) org-link-descriptive)
  (cond (orglink-mode (org-load-modules-maybe) (add-hook ...
  (let ((last-message (current-message))) (setq orglink-mode ...
  orglink-mode(toggle)
  funcall-interactively(orglink-mode toggle)
  call-interactively(orglink-mode record nil)
  command-execute(orglink-mode record)
  execute-extended-command(nil "orglink-mode" nil)
  funcall-interactively(execute-extended-command nil "orglink-mode" nil)
  call-interactively(execute-extended-command nil nil)
  command-execute(execute-extended-command)

HTH.