Re: Comment conventions, adding an explicit Header.

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

"Stephen J. Turnbull" <stephen@xemacs.org> writes:

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


Well, I agree, it's not a particular disaster, and it is certainly one
option that I considered. However, the problem remains that org-mode
uses the lines before the first header to specify a set of variables,
which is something that I cannot do if the first line is a header.


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

I would agree with this also. It would be nice to change org-mode so
that it recognises at lisp blocks as code automatically.

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

As I said, because it prevents the full use of org-mode.


>  > 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]+:$".

Yes, you are right, this is syntax. It can be changed.


>  > 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 less ugly in the org-mode view of a file, where it just looks like
a normal org-mode header.


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

I'll think on this. It is most likely possible.

Phil