Re: DocBook and Jade for Literate Programming

Subject: Re: DocBook and Jade for Literate Programming
From: "Mitch C. Amiano" <amiamc@xxxxxxxxxxxxxxx>
Date: Tue, 03 Nov 1998 12:16:26 -0500
As an project for my own edification, I once wrote a little markup
language I called "NOpGen". This was before the web hit the streets, 
and before I'd learned about SGML.

The four primitive constructs of the language were named "Coupling",
"Block", "Paste" and "Inclusion". The first two were declarative, 
and corresponded roughly to the SGML notions of Entity/Notation
and Element instance, respectively. The last two were procedural 
directives which performed - as best I can describe it - something 
like a DSSSL "node-list-map" and "read-entity", respectively. The block
was defined to allow nested Paste and Inclusions, and the top level
document context was considered a predefined block. Parsing progressed
from the top down, and directives were evaluated at the time they 
reached a point of inclusion at the top. 

I later found that work done in other quarters went pretty far beyond
my simple language. Paul Bassett's frame-based engineering, for instance,
is well worth examining.

I found this approach to be quite interesting for situations in which  
external definitions (particularly RDBMS schema information) were driving a 
design.

I also found that conversion to plain-ol-SGML was not obvious, or at least 
not very graceful. DSSSL style sheet instances seem to be a MUCH 
better fit. The most promising technique, as I see it, is to think about 
the DSSSL style sheet itself as the literate program. Kudos to W. Eliot Kimber
for illuminating the techniques for doing this. 

James H. Cloos Jr. wrote:
> 
> 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

--     the KISS Rule of unskilled programming: Keep It Stupid, Simpleton    --
Mitch C. Amiano                                         amiamc@xxxxxxxxxxxxxxx
Technical Staff Member  Advanced Design Process Group  Alcatel Network Systems
Opinions expressed are my own and are not a representation of Alcatel


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


Current Thread