Re: Comment conventions, adding an explicit Header.

[phillip.lord@newcastle.ac.uk (Phillip Lord)]

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

>> Currently, emacs uses comments of the form ";;; Commentary;" to
>> effectively indicate section headers in the buffer.
>
> Section headers are defined as ";;; <something>".
> And subsection headers as ";;;; <something>".
>
>> ;;; blah.el --- Dull file
>   ^^^^^^^^^^^^^^^^^^^^^^^^^
>
> This *is* a section header.


True. Currently, I handle the first line specially (as does emacs)
because otherwise you end up with level 1 header with, for example, the
lexical-binding instruction in it. 

Also, in the org-mode transformation I translate this into a org-mode
comment. The reason for this is that org-mode also has a "start of file"
semantics -- the lines before the first header is special. If the first
line of the file is a header, then there are no lines before the first
header.

Also, all the other headers that I see ("Commentary", "Status", "Code"
and so forth) are single word and end with an ":". So, currently, I use
this semantics also.

The ;;;; <something> headers I could support, but there aren't that many
files which use this consistently (calc does, so they are some). For
section 2 headers I use

;; ** Header 2

which in org-mode just translates to:

** Header 2

Deeper headers work likewise. This is inconsistent but works well,
because emacs-lisp files are consistent in their use of ";;; Header:"
and inconsistent in their use of ";;;;".


It's a work in progress, of course, but I am looking to DWIM with as
many existing files as possible.

Phil