From: phillip.lord@newcastle.ac.uk (Phillip Lord)
To: "Stephen J. Turnbull" <stephen@xemacs.org>
Cc: Stefan Monnier <monnier@iro.umontreal.ca>, emacs-devel@gnu.org
Subject: Re: Comment conventions, adding an explicit Header.
Date: Mon, 03 Nov 2014 10:04:31 +0000 [thread overview]
Message-ID: <87mw88ha6o.fsf@newcastle.ac.uk> (raw)
In-Reply-To: <87d2973f94.fsf@uwakimon.sk.tsukuba.ac.jp> (Stephen J. Turnbull's message of "Sat, 1 Nov 2014 10:01:59 +0900")
"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
next prev parent reply other threads:[~2014-11-03 10:04 UTC|newest]
Thread overview: 18+ messages / expand[flat|nested] mbox.gz Atom feed top
2014-10-30 10:22 Comment conventions, adding an explicit Header Phillip Lord
2014-10-30 11:59 ` Eric S. Raymond
2014-10-30 12:24 ` Phillip Lord
2014-10-30 12:33 ` Thorsten Jolitz
2014-10-30 13:43 ` Stefan Monnier
2014-10-30 13:58 ` Phillip Lord
2014-10-30 15:36 ` Stefan Monnier
2014-10-30 16:38 ` Phillip Lord
2014-10-30 17:13 ` Stefan Monnier
2014-10-31 10:02 ` Phillip Lord
2014-10-31 14:07 ` Stefan Monnier
2014-10-31 16:10 ` Phillip Lord
2014-11-01 1:01 ` Stephen J. Turnbull
2014-11-03 10:04 ` Phillip Lord [this message]
2014-11-03 11:00 ` Stephen J. Turnbull
2014-11-03 15:22 ` Phillip Lord
2014-10-31 11:50 ` Gregor Zattler
2014-10-31 16:42 ` Phillip Lord
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/emacs/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87mw88ha6o.fsf@newcastle.ac.uk \
--to=phillip.lord@newcastle.ac.uk \
--cc=emacs-devel@gnu.org \
--cc=monnier@iro.umontreal.ca \
--cc=stephen@xemacs.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).