From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: phillip.lord@newcastle.ac.uk (Phillip Lord) Newsgroups: gmane.emacs.devel Subject: Re: Comment conventions, adding an explicit Header. Date: Thu, 30 Oct 2014 13:58:17 +0000 Message-ID: <87a94dd5hi.fsf@newcastle.ac.uk> References: <87d299eu1d.fsf@newcastle.ac.uk> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain X-Trace: ger.gmane.org 1414782739 14568 80.91.229.3 (31 Oct 2014 19:12:19 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Fri, 31 Oct 2014 19:12:19 +0000 (UTC) Cc: emacs-devel@gnu.org To: Stefan Monnier Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Fri Oct 31 20:12:12 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 1XkHcJ-00069x-Gy for ged-emacs-devel@m.gmane.org; Fri, 31 Oct 2014 20:12:11 +0100 Original-Received: from localhost ([::1]:41536 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XkHcI-0007ax-UC for ged-emacs-devel@m.gmane.org; Fri, 31 Oct 2014 15:12:11 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:60804) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XkEP9-00026K-VD for emacs-devel@gnu.org; Fri, 31 Oct 2014 11:47:39 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1XjqF1-0006Tm-TQ for emacs-devel@gnu.org; Thu, 30 Oct 2014 09:58:24 -0400 Original-Received: from cheviot22.ncl.ac.uk ([128.240.234.22]:39913) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XjqF1-0006Tc-OD for emacs-devel@gnu.org; Thu, 30 Oct 2014 09:58:19 -0400 Original-Received: from smtpauth-vm.ncl.ac.uk ([10.8.233.129] helo=smtpauth.ncl.ac.uk) by cheviot22.ncl.ac.uk with esmtp (Exim 4.63) (envelope-from ) id 1XjqEz-00082h-FP; Thu, 30 Oct 2014 13:58:17 +0000 Original-Received: from jangai.ncl.ac.uk ([10.66.67.223] helo=localhost) by smtpauth.ncl.ac.uk with esmtpsa (TLSv1:AES128-SHA:128) (Exim 4.63) (envelope-from ) id 1XjqEz-0004UL-HU; Thu, 30 Oct 2014 13:58:17 +0000 In-Reply-To: (Stefan Monnier's message of "Thu, 30 Oct 2014 09:43:28 -0400") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.3 (gnu/linux) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x X-Received-From: 128.240.234.22 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:176140 Archived-At: 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. 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. 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. If the first line of the file is a header, then there are no lines before the first 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. 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 which in org-mode just translates to: ** Header 2 Deeper headers work likewise. This is inconsistent but works well, because emacs-lisp files are consistent in their use of ";;; Header:" and inconsistent in their use of ";;;;". It's a work in progress, of course, but I am looking to DWIM with as many existing files as possible. Phil