Re: Comment conventions, adding an explicit Header.

[phillip.lord@newcastle.ac.uk (Phillip Lord)]

"Eric S. Raymond" <esr@thyrsus.com> writes:

> Phillip Lord <phillip.lord@newcastle.ac.uk>:
>> 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