Re: Modern conventions for structuring Emacs Lisp libraries

[Thorsten Jolitz]

Richard Stallman <address@hidden> writes:

>         [ To any NSA and FBI agents reading my email: please consider
>         [ whether defending the US Constitution against all enemies,
>         [ foreign or domestic, requires you to follow Snowden's example.
>
> Our conventions for headings in Lisp code are not sacred.  We can
> change them if that is a good thing to do.  However, the transient of
> such a change is likely to cause some work and trouble for a lot of
> people.
>
> Your proposal for handling the conventional ;;; separator lines makes
> sense, and I see nothing inherently wrong with it.  But this seems to
> assume our code should wag our conventions.  It might be far less work
> to change Outline mode and Org mode to understand our existing
> conventions, than to change hundreds of Lisp files (including files we
> don't maintain).

I did already adapt my own library outshine.el to work with 'special  case'

,-------
| ^;;;+ 
`-------

headlines sometimes ago, because I understand very well that nobody wants to
change a huge code base only to please a new program tool (or a new idea about
file structuring conventions).

But its exactly the fact that I can use outshine.el/navi-mode.el with
oldschool Emacs Lisp libraries now, i.e. look at them like Org files, that
made me think there is room for improvement.

What I'm looking for is probably official recommendations that naturally
lead to sane file structuring and allow me (and others) to add their sanely
structured libraries to the package repos.

Assuming that
[[http://www.emacswiki.org/emacs/ElispAreaConventions][this page]]
reflects the official recommendations, they look like this:

,------------------------------------------------------------
| The major section headings are, in order:
| 
|     ;;; <name>.el --- <one-line description of the library>
|     ;;; Commentary:
|     ;;; Change Log: (optional)
|     ;;; Code:
|     ;;; <name>.el ends here
`------------------------------------------------------------

I would, as described in my proposal, critisize that

 1. that last line is no headline
 2. the 1st-level ";;; Code:" headline enforces one of two bad decisions:
    - accept that all following headlines must be level 2 or higher, since
      they are all subtrees of the libraries Code: section. 
    - ignore the logic of the file structuring and continue with other
      1st-level headlines that should really be subheadlines of "Code:"
 3. the trailing colons are no good when exporting to html, latex etc...

I would rather see recommendations like this:

,--------------------------------------------------------
| ;;; <name>.el --- <one-line description of the library>
| ;;;; Commentary
| ;;;; Change Log (optional)
| ;;; Requieres (optional)
| ;;; Variables (optional)
| [...] (other 1st-level code-section headlines)
| ;; <name>.el ends here
`--------------------------------------------------------

 1. assume an elisp library is naturally divided into two parts: the
    header-comment section and the code-section, but realize that it might be
    30 lines of header-comments vs 2000 lines of code (or even much more)
 2. therefore, drop the split into just two parts and define the
    header-comment as the first 1st-level headline in a file that can contain
    many more 1st-level headlines (that all belong to the implicitly defined
    code-section).
 3. use the file's first line as top-headline of the header-comment section,
    and make all other headlines in this comment-section subheaders of this
    line (level 2 or higher)
 4. thus, the second 1st-level headline of the file starts the code-section
    (without saying so explicitly)
 5. make the last line a simple comment
 6. drop the trailing colons

That would lead IMO to better structured Elisp files, and since its so easy to
convert from ";;; " to ";; * ", one could always use the favorite syntax and
convert to the other. 

Wouldn't it be possible to leave the existing libraries untouched, update the
conventions (for a better future), and somehow allow for both versions to
co-exist?

-- 
cheers,
Thorsten