Re: Comment conventions, adding an explicit Header.

[Stephen J. Turnbull]

Phillip Lord writes:
 > Stefan Monnier <address@hidden> 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.

+1

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

I don't really see why this is a problem.  It may be a literate
programming style, but it's still a programming style.  I don't see
what's wrong with including pragmas in the documentation.  If you want
them removed, feel free to do so -- they're code, they have
well-defined syntax.  I personally think it a wart on such styles when
you need comments to mark a defun -- the format generators should do
that for you.  If you're going to do that much analysis, handling the
traditional lisp-mnt.el conventions shouldn't be all that hard.

IMHO YMMV of course, but pragmatically, I think your mode will be more
popular if it Just Works[tm] on the reams of lisp-mnt-formatted files
out there.

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

There aren't any in a Lisp file, and you're already treating this line
as special.  Why not just treat it as a special-case 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.

That's not semantics, that's syntax, and it's ad hoc: we (Eric?)
happened to standardize on those and Eric codified them in lisp-mnt,
but nobody has ever defined headers as matching "^;;;;* [A-za-z]+:$".

 > 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

Ugh.

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

I don't see why defining headers as matching "^;;;;*\s-+.*\S-" or
similar doesn't DWYM.  Few files are long enough to really need
subsection headers; submit patches for the ones that do need them and
don't have them in the traditional format.

Steve