RE: Modern conventions for structuring Emacs Lisp libraries

[Drew Adams]

> > You skipped the part I was looking for: the "Commentary:"
> > section.  I do want this part to be refined.  More specifically, I'd
> > like someone to come up with a description of a markup format to use
> > there (99% compatible with what we already have), together with code
> > that can turn such a Commentary section into nicely rendered text in an
> > Emacs buffer.
> 
> Agreed.  It can also be rendered as HTML in the packages description on
> elpa.gnu.org (and other package archives, maybe), along with the README.

FWIW, I use something simple: `finder-commentary' plus `linkd-mode' (from
`linkd.el').  Finder renders the Commentary in a simple way (strips comment
chars, hyperlinks file names, etc.).  Linkd provides hyperlinked text.

I also usually provide a linkd-linked index to the Commentary sections (if
large) and other file sections.

Linkd is here: http://www.emacswiki.org/emacs/download/linkd.el.