Re: Modern Conventions for Emacs Lisp files?

[Thorsten Jolitz <tjolitz@gmail.com>]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> The modern conventions would just be that headlines are outcommented
>> Org-mode headlines with whatever comment syntax the major-mode at hand
>> uses.
>
> But that is incompatible with the current convention to use ";;;+" where
> the number of semi-colons indicates depth.  So it would require massive
> rewrites of pretty much all files.
> A non-starter.
>
>> That are of course different conventions, and I did not want to push any
>> big problematic moves or so. But with all the momentum and popularity
>> Org-mode enjoys, maybe such an 'Org-mode' style structuring of source
>> code files could become an accepted second choice (and if only in
>> libraries that are not part of Emacs).
>
> Couldn't "Org-mode" be made to work with the current convention?
> That would be a lot more useful since it would "just work" on all the
> existing files.

I modified 'outshine.el', 'outorg.el' and 'navi-mode.el' so that they
now deal with the special case of "oldschool" elisp headers (";;;+").

Using this library-trio the way described in their comment-sections or
in this article

,-----------------------------------------------------------
| http://orgmode.org/worg/org-tutorials/org-outside-org.html
`-----------------------------------------------------------

gives any Emacs Lisp buffer with (modern or oldschool) headlines the
looks of an Org-mode buffer and easy keybindings for outline
functionality. Each subtree or the whole buffer can be edited in
temporary Org-mode buffers, and a permanent 'remote-control' *Navi*
buffer can be opened.

I uploaded a short (4 min) demo-video on youtube using 'org-elements.el'
as example file:

,-------------------------------------------
| http://www.youtube.com/watch?v=I0hxTAAlGZQ
`-------------------------------------------

I tried this on several arbitrary .el files from Emacs itself and from
Org-mode, and it worked. Testing several files revealed that many Elisp
libraries did not make much use of outline structuring, or used it in an
inconsistent way. Well structured files I found were e.g. 'ox.el' and
'org-elements.el' from Org-mode, but it seems as if there is room for
improvement in this area.

And while its useless to talk about the esthetics of 'org-style' headers
vs. 'oldschool' headers, my impression is that there is a clear
usability problem with the old conventions. 

This is still easy to spot, while a bit strange (3 times ; signal the
1st level):

,--------------
| ;;; 1st level
`--------------

but this one? Would you recognize the level at first sight?

,-----------------
| ;;;;;; header
`-----------------

(its 4th level)

Are these two at the same or at different levels?

,------------------
| ;;;;;;; header1
| text text text
| text text text
| text text text
| ;;;;;;;; header2
`------------------

Compare the conventional headers to Org-mode style headers:

,--------------
| ;; * 1st level
`--------------

,-----------------
| ;; **** header
`-----------------

,---------------
| ;; ***** header1
| text text text
| text text text
| text text text
| ;; ****** header2
`---------------

But anyway, if this cannot be changed with reasonable effort, its
fruitless to discuss it, and now the new libraries discussed in this
thread can be used for both kinds of header styles.

PS
There is one strange problem I have:

I can not open org.el any more, now that the oldschool elisp headers are
recognized by 'outshine' too. Its a big file, but size can't be the
problem since other quite big files open within 1 or 2 seconds or so.
When I try to open org.el, Emacs apparently goes into an infinite loop
and uses 100pc CPU - I have to kill the Emacs process and restart Emacs
to recover from that.

What might be different in org.el than in all the other elisp files I
tested so far to cause this problem?

-- 
cheers,
Thorsten