|Paul Millar||Jul 12, 2010 1:36 am|
|Dave Pawson||Jul 12, 2010 2:51 am|
|lars...@swedbank.se||Jul 12, 2010 4:14 am|
|Remko Tronçon||Jul 12, 2010 4:19 am|
|Dave Pawson||Jul 12, 2010 4:39 am|
|Jirka Kosek||Jul 12, 2010 4:43 am|
|Jirka Kosek||Jul 12, 2010 4:46 am|
|John W. Shipman||Jul 12, 2010 8:12 am|
|Robert Lucente||Jul 13, 2010 2:48 pm|
|Subject:||Re: [docbook-apps] Compact DocBook ?|
|From:||John W. Shipman (jo...@nmt.edu)|
|Date:||Jul 12, 2010 8:12:40 am|
+-- | I'm hoping to embed DocBook within some Java code (as | comments). Along with some support utilities, this should | allow embedding of documentation next to the code it describes. | This is somewhat similar to JavaDoc, but: | | a. using DocBook vocabulary, | | b. to be included within end-user documentation. | | The thought of writing DocBook XML inside Java comments isn't appealing. +--
Why not turn the whole process inside out?
For several years now, all my serious coding is done in "lightweight literate programming" (LLP) style. The idea is to have the documentation contain the program, not vice versa.
Here's how I develop code nowadays.
1. Write up the external interface in DocBook.
2. Document the "big picture" parts of the design, also in DocBook. For a small project, this can be the same document as the external spec; for substantial projects, I'll start a separate "Internal Maintenance Specification".
3. Write the program as a continuous narrative with embedded code blocks contained within DocBook <programlisting> elements. To distinguish example code blocks from live code blocks, I used the extension 'role' attribute to route the code into the files from which it will be run or compiled. Here's an example:
================================================================ <para> The first lines make this script self-executing, and point back to this documentation: </para> <programlisting role='outFile:myscript.py'> #!/usr/bin/env python # myscript.py: This script... # For documentation, see http://... <- HTML output from DocBook import sys ... </programlisting>
Writing a script to extract the source code files took me about an hour, including all documentation. It's trivial in any language with a decent XML toolset; I used Python and lxml.
Note that you can include any number of files in any number of languages. One drawback of JavaDocs is that it works only with Java. Sometimes the project includes non-Java files, such as CSS stylesheets; why not include them in literate form as well?
See the URL above for the code extractor and several dozen complete projects done in this style. The originator of Lightweight Literate Programming is my colleague Dr. Allan Stavely, based on the classic 1980s-era literate programming idea from Dr. Don Knuth.
Best regards, John Shipman (jo...@nmt.edu), Applications Specialist, NM Tech Computer Center, Speare 119, Socorro, NM 87801, (575) 835-5735, http://www.nmt.edu/~john ``Let's go outside and commiserate with nature.'' --Dave Farber