Literate Programming with Org mode

From: "Sébastien Vauban" <wxhgmqzgwmuf-geNee64TY+gS+FvcfC7Uqw@public.gmane.org>
To: emacs-orgmode-mXXj517/zsQ@public.gmane.org
Subject: Literate Programming with Org mode
Date: Tue, 28 Jul 2009 18:14:50 +0200	[thread overview]
Message-ID: <87my6ordhh.fsf@mundaneum.com> (raw)

Hi Eric and all,

Here some promised description of how I'm using Literate Programming with
LaTeX (up to now -- soon directly from Org mode?).

I write an "enhanced LaTeX" file ([1], having the `.nw' -- for Nuweb --
extension). It is enhanced as I can put blocks of code in there (SQL blocks,
for example), and give them a name for further referencing.

Then, at some point in the file, I say how I want the code files to look like,
by assembling the blocks in a certain order, with some glue.

For example:

--8<---------------cut here---------------start------------->8---
<<Enterprise.sql>>=
<<sql-init>>
SELECT abcID, etpID, etpAssurATPolNum
FROM enterprise JOIN record
    ON (etpAbcID_fk = abcID)
WHERE etpAbcID_fk
<<sql-cond>>
@ %def 
--8<---------------cut here---------------end--------------->8---

The above file is made up of two defined blocks (`sql-init' and `sql-cond')
plus some glue in between.

The good thing is I can reuse the same blocks in other context, completely
avoiding copy/paste of code:

--8<---------------cut here---------------start------------->8---
<<Lessons.sql>>=
<<sql-init>>
SELECT abcID, lesAlternNbrSem, lesNbrSem,
       CONVERT(varchar(10), lesDateDeb, @dateFmtStyleOut) AS lesDateDeb,
       CONVERT(varchar(10), lesDateFin, @dateFmtStyleOut) AS lesDateFin
FROM lessons JOIN record
    ON (lesAbcID_fk = abcID)
WHERE lesAbcID_fk
<<sql-cond>>
@ %def 
--8<---------------cut here---------------end--------------->8---

OK. So, my `org-lit-prog.nw' file is ready, and committed under Subversion
(this is the only one I'm committing as it contains both the documentation of
the code, and the source code itself).

Then, I just type (in a terminal):

--8<---------------cut here---------------start------------->8---
noweb org-lit-prog.nw
--8<---------------cut here---------------end--------------->8---

to extract both:

    o   the LaTeX file [2] to be compiled into a PDF [3],
    o   the different source code files (Enterprise.sql [4], Lessons.sql [5],
        [6] and [7])

Just that easy to keep code and doc in sync, and get a very nice-to-read
documentation of the code.

Sometimes, I play an extra trick is made in the noweb file: I put blocks of
static code (for which I don't especially need any noweb feature) after the
end of the LaTeX document. That way, it gets outputted by noweb as a source
file during the Tangle process, and included in my LaTeX document via the
listings package.

Why that trick?  I could directly put the code in the body of the document!
Yes, but I want the code to be highlighted via listings. Otherwise, it's just
black and white display of the code...

For easy access, I've put all the above files on a my Web space:

[1] http://www.mygooglest.com/sva/org-lit-prog.nw
[2] http://www.mygooglest.com/sva/org-lit-prog.tex
[3] http://www.mygooglest.com/sva/org-lit-prog.pdf
[4] http://www.mygooglest.com/sva/Enterprise.sql
[5] http://www.mygooglest.com/sva/Lessons.sql
[6] http://www.mygooglest.com/sva/Payment.sql
[7] http://www.mygooglest.com/sva/prsNumNat.awk

From what I understand, what we both wanna reach is writing all of the `.nw'
file as an Org file directly, and let Org-babel extracts the source code files
and the documentation out of it.

What should be good in the future, when it will be ready for prime time, is
that this becomes complete part of the export process: no tangle operation
needed.

Is the above description worth for you?  Do you understand how I work when
documenting code?  Pay attention: I'm *the* expert in literate programming.
Just an amateur being seduced by some of its features.

Best regards,
  Seb

-- 
Sébastien Vauban

_______________________________________________
Emacs-orgmode mailing list
Remember: use `Reply All' to send replies to the list.
Emacs-orgmode-mXXj517/zsQ@public.gmane.org
http://lists.gnu.org/mailman/listinfo/emacs-orgmode