From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: "Stephen J. Turnbull" Newsgroups: gmane.emacs.devel Subject: Re: Comment conventions, adding an explicit Header. Date: Sat, 01 Nov 2014 10:01:59 +0900 Message-ID: <87d2973f94.fsf@uwakimon.sk.tsukuba.ac.jp> References: <87d299eu1d.fsf@newcastle.ac.uk> <87a94dd5hi.fsf@newcastle.ac.uk> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 X-Trace: ger.gmane.org 1414803776 10450 80.91.229.3 (1 Nov 2014 01:02:56 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sat, 1 Nov 2014 01:02:56 +0000 (UTC) Cc: Stefan Monnier , emacs-devel@gnu.org To: phillip.lord@newcastle.ac.uk (Phillip Lord) Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sat Nov 01 02:02:33 2014 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1XkN5N-0001T8-6f for ged-emacs-devel@m.gmane.org; Sat, 01 Nov 2014 02:02:33 +0100 Original-Received: from localhost ([::1]:44737 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XkN5M-0005id-KD for ged-emacs-devel@m.gmane.org; Fri, 31 Oct 2014 21:02:32 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:57237) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XkN52-0005ap-Ph for emacs-devel@gnu.org; Fri, 31 Oct 2014 21:02:19 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1XkN4t-0006y1-Ej for emacs-devel@gnu.org; Fri, 31 Oct 2014 21:02:12 -0400 Original-Received: from shako.sk.tsukuba.ac.jp ([130.158.97.161]:43848) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XkN4t-0006wz-5q for emacs-devel@gnu.org; Fri, 31 Oct 2014 21:02:03 -0400 Original-Received: from uwakimon.sk.tsukuba.ac.jp (uwakimon.sk.tsukuba.ac.jp [130.158.99.156]) by shako.sk.tsukuba.ac.jp (Postfix) with ESMTP id 110AC1C399C; Sat, 1 Nov 2014 10:02:00 +0900 (JST) Original-Received: by uwakimon.sk.tsukuba.ac.jp (Postfix, from userid 1000) id 01A591A27CF; Sat, 1 Nov 2014 10:01:59 +0900 (JST) In-Reply-To: <87a94dd5hi.fsf@newcastle.ac.uk> X-Mailer: VM undefined under 21.5 (beta34) "kale" acf1c26e3019 XEmacs Lucid (x86_64-unknown-linux) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x X-Received-From: 130.158.97.161 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:176180 Archived-At: Phillip Lord writes: > Stefan Monnier writes: > > >> Currently, emacs uses comments of the form ";;; Commentary;" to > >> effectively indicate section headers in the buffer. > > > > Section headers are defined as ";;; ". > > And subsection headers as ";;;; ". > > > >> ;;; 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 ;;;; 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