Literate Programming III

Part, the third. End to end processing now complete. Most puzzles resolved, code in place, one schema processed end to end. That being the NVDL schema. This presents the lessons learned. I was going to be critical of Norms work, till I realised that most of the files were written in 2001. Now I'm really impressed. I'm puzzled that what I see as bugs remain there, but either it isn't being used, or there is (more likely) something I'm missing. OK, the lessons. These relate fairly narrowly to documenting XML, even then, my only real experience is in documenting a Relax NG schema. Also I'm aiming at docbook as the wrapper language.

• When to use it (Lit Prog that is). Far better, as Norm states when 'designing' from scratch. This compared with my usage, documenting an existing schema, designed by someone else. The comparator would be following a designer documenting his/her code. Yuk.
• Use it as suggested. Generate chunks of document, then write the schema section (probably a pattern) to match the documentation, taking that as the customer expectation. That leaves me wondering where the test cases are for a full TDD approach.
• Use the 'glue' section, the first <src:fragment/> along the way. You'll be in a mess if you don't. This just keeps a note of how you want these bits glueing together.
• I haven't used cross references (src:fragment//src:fragref) so I can't comment. I tend towards the opinion that some time I'll get an itch and find this is the scratch, if you see what I mean. The perl example in the paper doesn't do much for me.
• The namespace fixup is really neat. Go re-read the mundane-result-prefixes comments until you see what he's done.
• This morning I finally realized why the <src:frament/> markup was left in after weaving the xweb file. Norm made this casual remark that it (the system) was good for any language. I'd just changed his copy command into a docbook specific markup... then it hit me. Do it as a customisation! That way the xweb processing is language agnostic.

That's it, or as much as I can remember at the moment. As I noted, marking up an existant schema with docbook at xweb markup was a pain. The only thing it did for me was teach me about the system. And let me integrate the output into other docbook stuff far more neatly. And teach me just a little more about working with namespaces. (This is beginning to sound like the Spanish inquisition sketch!) If you want to learn more about namespace processing, literate programming, go document a new design this way. It's fun