Re: 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: Re: Literate Programming with Org mode
Date: Tue, 28 Jul 2009 22:41:50 +0200	[thread overview]
Message-ID: <874oswpmk1.fsf@mundaneum.com> (raw)
In-Reply-To: 1e5bcefd0907280946r7b2eb7b9lac80ddc813fa9809@mail.gmail.com

Hi Marcelo,

Marcelo de Moraes Serpa wrote:
> Sébastien Vauban wrote:
>> 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.
>>
>> [...]
>>
>> 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 `noweb org-lit-prog.nw' 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.
>>
>> [...]
>>
>> 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.

Euh... Euh... Euh... I meant: I am _NOT_ *the* expert in literate programming.
Just a user of the approach... Sorry for misbehaving ;-)

>> Just an amateur being seduced by some of its features.
>
> Hmm, this seems interesting and something I'm looking for, but I'm not
> entirely sure what you mean by "literate programming" (I haven't
> googled yet either, I'm about to do it once I answer this message).

If I would have to summarize what it is in a sentence, it would be this: LP
(not logic programming) is about *putting the code in the documentation* -- at
the opposite of the current mainstream approach where one puts the
documentation inside the code (where there is documentation!).

I've heard that Knuth told about it in those words: it's when we will be able
to read the code of a software in our bed, reading a book made of 90% of
documentation and 10% of code. If someone can find this phrase somewhere...

> Anyway, I have a project I'm working on right now that requires me to
> set up a "publishing environment", in the sense that I might have
> source files (maybe in XML or whatever format makes sense) and be able
> to convert them to LaTeX (for pdf), html or whatever format I could
> think of, using XSLT, something like the "pragmatic programmers"
> publishing toolchain. Not sure if literate programming has anything to
> do with that :)

As far as I can understand, yes, as you're talking of inserting source code
(of whatever language) in your big documentation of the project. That's the
philosophy, yes, *iff* you produce the code out of that documentation. The
code is becoming an output of the documentation. Not the opposite.

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