Re: Comment conventions, adding an explicit Header.

[Stefan Monnier]

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

outline-minor-mode doesn't handle it specially.  I don't mind having the
lexical-binding thingy in there, since it means that when the file
"fully folded" I can still immediately know whether the file is using
lexical-binding or not.

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

Not knowing what this "special" implies, it's hard to judge whether it's
important.

> 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 few files that use ";;;" for sectioning *within* the code itself
don't seem to use "single word with a colon" very much.  E.g. a quick
grep shows things like:

lisp/wid-edit.el:;;; Utility functions.
lisp/wid-edit.el:;;; Widget text specifications.
lisp/wid-edit.el:;;; Widget Properties.
lisp/view.el:;;; Commands that enter or exit view mode.
lisp/view.el:;;; Some help routines.
lisp/view.el:;;; Commands for moving around in the buffer.
lisp/vc/ediff-util.el:;;; Build keymaps
lisp/vc/ediff-util.el:;;; Setup functions
lisp/vc/ediff-util.el:;;; Commands for working with Ediff
lisp/vc/ediff-util.el:;;; Copying diffs.


        Stefan