Re: Modern conventions for structuring Emacs Lisp libraries

[Stefan Monnier]

> The first thing when looking at a library is getting an overview about
> its structure - with tools like e.g. navi-mode.
> For me its a huge difference then if I look at a well balanced and
> logical hierachical tree-structure (org-element.el and ox.el are perfect
> examples for this) or at something that seems inherently wrong and
> illogical at first sight.

Then fix navi-mode to show you the structure you want.  It's not like
the info is missing.

> This seems the least important point, but again I ask myself: why
> continue recommend the colons, when it turns out they don't look so
> good in exports?

Because I have much better things to do with my time than have to deal
with such nasty decades-long transitions.

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

> If I understand you right, maybe there is good news. Install and load
> outshine.el and outorg.el, move point on the "Commentary:" header and do
> 'M-x outorg-edit-as-org' (or M-# M-#).

> Then you will be offered that headline converted to Org in a temporary
> Org-mode edit buffer (*outorg-edit-buffer*). In that buffer, you can use
> the power of Org-mode for writing really complex commentary text, even
> using Org-Babel for executing code and inserts results, and then export
> the commentary section nicely formatted to HTML, LaTeX, ODT, ASCII and
> other backends.

Exporting to HTML will be useful, but I first and foremost want it to be
displayed nicely in an Emacs buffer.  The markup should be simple enough
that existing Commentary sections mostly follow it already, and that you
mostly don't need any extra support to write it.


        Stefan