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 12:24:33 +0000 Message-ID: <87mw8dd9tq.fsf@newcastle.ac.uk> References: <87d299eu1d.fsf@newcastle.ac.uk> <20141030115949.GB7645@thyrsus.com> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain X-Trace: ger.gmane.org 1414778012 29625 80.91.229.3 (31 Oct 2014 17:53:32 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Fri, 31 Oct 2014 17:53:32 +0000 (UTC) Cc: emacs-devel@gnu.org To: Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Fri Oct 31 18:53:28 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 1XkGO7-00007z-IG for ged-emacs-devel@m.gmane.org; Fri, 31 Oct 2014 18:53:27 +0100 Original-Received: from localhost ([::1]:40261 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XkGO7-00051K-67 for ged-emacs-devel@m.gmane.org; Fri, 31 Oct 2014 13:53:27 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:55841) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XkEL1-00045C-93 for emacs-devel@gnu.org; Fri, 31 Oct 2014 11:43:13 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1XjomJ-00049a-Bo for emacs-devel@gnu.org; Thu, 30 Oct 2014 08:24:39 -0400 Original-Received: from cheviot22.ncl.ac.uk ([128.240.234.22]:40552) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XjomJ-00049F-6B for emacs-devel@gnu.org; Thu, 30 Oct 2014 08:24:35 -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 1XjomH-0003il-E0; Thu, 30 Oct 2014 12:24:33 +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 1XjomH-0002EI-8x; Thu, 30 Oct 2014 12:24:33 +0000 In-Reply-To: <20141030115949.GB7645@thyrsus.com> (Eric S. Raymond's message of "Thu, 30 Oct 2014 07:59:51 -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:176108 Archived-At: "Eric S. Raymond" writes: > Phillip Lord : >> I have written a mode which transforms an Emacs-Lisp file into an >> org-mode file. So you can view (and edit) your comments in org-mode, >> while maintaining a normal elisp file (i.e. it doesn't require tangling >> as an org-mode babel file would). In this process ";;; Commentary:" >> lines get transformed into Org mode section one headers. This works >> nicely, but the lack of a ";;; Header:" line, means that the metadata >> and copyright is outside of the org-mode structure. Adding a ";;; >> Header:" is a simple way of circumventing this. > > I believe I was the person who made the ";;; Commentary" header > general across the Lisp library, back around '92 or '93. (Possibly I > generalized it from previous sporadic examples rather than inventing it; > I don't remember.) > > When I did so, I was thinking explicitly of enabling text analysis by > introducing a structural semantic clue. I did not anticipate org > mode, but you are extending the concept in the direction I intended. > > +1 Thanks. Org-mode seems like an obvious choice as a literate format; in fact people are already using it for precisely this purpose. org-show is a nice example, which uses org mode to do a slide show. The source code is both an example slide show with org-show.el embedded. https://raw.githubusercontent.com/jkitchin/jmax/master/org/org-show.org But I dislike relegating the .el file to being generated, hence my approach. I think it's working quite well. The transformation between org and emacs-lisp is straight-forward. On the emacs-lisp side, adding a "Header:" tag is all I need. On the org-mode side, I need support for emacs-lisp `function-markup-syntax' which is currently only highlighted in emacs-lisp-mode. So, in emacs-lisp we have this... https://github.com/phillord/linked-buffer/blob/master/linked-buffer-org.el With the org-mode transformation looking like this: http://homepages.cs.ncl.ac.uk/phillip.lord/scratch/linked-buffer-org.org And exported to HTML by org-mode, like this: http://homepages.cs.ncl.ac.uk/phillip.lord/scratch/linked-buffer-org.html Still a work in progress, of course, but I am happy so far. Phil