RE: DocBook and Jade for Literate Programming (The DSSSList Digest V2 #178)

[MARK.WROTH@xxxxxxxxxxx (Wroth, Mark)]

James H. Cloos Jr <cloos@xxxxxxxxxxx> asked:

> Date: 30 Oct 1998 18:38:34 -0600
> From: "James H. Cloos Jr." <cloos@xxxxxxxxxxx>
> Subject: DocBook and Jade for Literate Programming
> 
> I'm looking for a good base tool-suite for literate programming (a
> Knuthian Web -- as opposed to a Berners-Lee-esque Web -- if you will
> :)
> and am looking at something based on DocBook, using Jade for both
> conversion for publication (HTML, ps/pdf via TeX, etc) and extraction
> of the code.
> 
> Has anyone tried anything like this?  Any comments/ideas on how to
> best do it?
> 
Have you looked at W. Eliot Kimber's  "Using SGML Architectures and
DSSSL to Do Literate Programming"
(http://www.sil.org/sgml/kimberDSSSLLitProg.html)?  He appeared to be
attacking the same basic problem, although I confess that his approach
was beyond me (and appears specialized to DTDs, although I may be
misinterpreting him badly).

	I also note C. M. Sperberg-McQueen's "SWEB: an SGML Tag Set for
Literate Programming" (http://www.uic.edu/~cmsmcq/tech/sweb/sweb.html),
which appears to be even closer to what you are aiming at, although I
will point out the disclaimer  "This incomplete, unpublished document is
distributed privately for comment by friends and colleagues; it is not
now a formal publication and should not be quoted in published
material."

[...]

> Let's define a tag called, for example, CODE to contain each block of
> code; everythign else is the documentation.  The CODE tag should take
> a number of attributes, including the mandatory attribute FILE, which
> will take as its argument the filename that block of CODE is to be
> written to at extraction time.  
> 
Umm ... with this model, how would you handle a code "scrap" which is
included in several output files?  I would assert that the ability to
define reusable code scraps (a terminology adopted from Sperberg-McQueen
because it works so well) across different output files is an important
advantage of  literate programming.
	A possible approach (based on Nuweb) is to define two types of
"scrap"; an "output scrap", which defines a block of code to be written
to file, and a "definition scrap", which defines a block of code which
can be included in other scraps (of either type).

	[...]

> Also, all whitespace after the CODE tag and before the
> /CODE tag would be ignored during extraction.
> 
Consider this one carefully before you make it the only approach you
support; some potential output languages consider whitespace significant
(e.g. makefiles).

I'd be happy to discuss this general topic with you further, but we may
be going astray from the DSSSList's topics (or maybe not, since some of
the significant issues is how to process the resulting marked up text,
and what markup to use in the documentation parts -- while a new markup
could certainly be defined, it may make sense to use an existing one).




 DSSSList info and archive:  http://www.mulberrytech.com/dsssl/dssslist