Re: [docbook-apps] Compact DocBook ?

["John W. Shipman" <john@nmt.edu>]

+--
| 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?

     http://www.nmt.edu/~shipman/soft/litprog/

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 (john@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