DocBook and Jade for Literate Programming

["James H. Cloos Jr." <cloos@xxxxxxxxxxx>]

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?

I'm thinking something like the following, if Jade can even do it:

(I will write the DTD code in pseudocode, just to ensure I correctly
state what I'm thinking; it has been too long since I last delved into
DTDs....)

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.  Additional, optional attributes would
provide hints to Jade (and the stylesheet) for determining the end of
the CODE block.  LANG would take an argument specifying the program
language the code is written in, EOB (for EndOfBlock) would take a
string; if present, the CODE block's closing tag would require a
matching EOB attribute, thus allowing the string `</CODE>' to exist in
the block.  Also, all whitespace after the CODE tag and before the
/CODE tag would be ignored during extraction.

When converting the SGML for publication, the CODE blocks would be set
as inset blocks in a monospace font.  If a LANG attribute is present,
and the stylesheet recognizes it, the block may be pretty-printed in a
manner appropriate for that language.  In that case, the monospace
requirement may be dropped.

For the most part, I see no reason why it shouldn't work.  The EOB
requirement, though, seems troublesome, both for validation and for
Jade.  Is it at all possible to write a DTD such that the data between
the open and close tags is completely opaque, even if it contains
characters that are special in SGML?  Can the stylesheet handle it?

Here is a contrived and simplistic example:

	==================================================
	<para>First parse the command line options</para>
	<code lang="c" eob="options" file="main.c">
	
	while ((c=getopt(argc,argv,"ab:c:"))!=-1) {
	    case 'a':
	        foo=1;
	        break;
	    case 'b':
	        o=atoi(optarg);
	        if (o < 1)
	            bar=1;
	        else if (o > 10)
	            bar=10;
	        else
	            bar=o;
		break;
	    /* an even more contrived comment :) */
	    case 'c':
	        check_baz(&dest_baz,optarg);
	        break;
	    default:
	        usage();
	        exit(1);
	}

	</code eob="options">
	==================================================

-JimC
-- 
James H. Cloos, Jr.       <http://www.jhcloos.com/cloos/pgp_public_key.txt>
<cloos@xxxxxxxxxxx>      E9E9 F828 61A4 6EA9 0F2B  63E7 997A 9F17 ED7D AEA6


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