From: "Stephen J. Turnbull" <stephen@xemacs.org>
To: phillip.lord@newcastle.ac.uk (Phillip Lord)
Cc: Stefan Monnier <monnier@iro.umontreal.ca>, emacs-devel@gnu.org
Subject: Re: Comment conventions, adding an explicit Header.
Date: Sat, 01 Nov 2014 10:01:59 +0900 [thread overview]
Message-ID: <87d2973f94.fsf@uwakimon.sk.tsukuba.ac.jp> (raw)
In-Reply-To: <87a94dd5hi.fsf@newcastle.ac.uk>
Phillip Lord writes:
> Stefan Monnier <monnier@iro.umontreal.ca> 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
next prev parent reply other threads:[~2014-11-01 1:01 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 [this message]
2014-11-03 10:04 ` Phillip Lord
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
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87d2973f94.fsf@uwakimon.sk.tsukuba.ac.jp \
--to=stephen@xemacs.org \
--cc=emacs-devel@gnu.org \
--cc=monnier@iro.umontreal.ca \
--cc=phillip.lord@newcastle.ac.uk \
/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 external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.