[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Comment conventions, adding an explicit Header.
From: |
Phillip Lord |
Subject: |
Re: Comment conventions, adding an explicit Header. |
Date: |
Mon, 03 Nov 2014 10:04:31 +0000 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/24.3 (gnu/linux) |
"Stephen J. Turnbull" <address@hidden> 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
- Re: Comment conventions, adding an explicit Header.,
Phillip Lord <=