Re: [docbook-apps] Suggested Writing Style

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

I use DocBook for documenting Python, where indentation is
significant.  Furthermore, I use it for literate programming,
where the document includes the actual code that will be
executed.

Here's my preferred style for programlisting elements:

    ...
    <programlisting role='outFile:sample.py'
>def f(x):
    return 9*x + 0.5
</programlisting>
    ...

Explanations:

1.  I use the role attribute to indicate that this programlisting
    element will be written to a specific file (sample.py in this
    case).  Non-executable elements don't use this role attribute.

2.  XML allows any tag to be broken before its closing '>', so I
    place it at the front of the first code line.  That way,
    there is no whitespace at the front of the code snippet.

3.  The last line of the code snippet ends with a newline.
    The closing tag is unindented; if it were indented, that would
    place a partial blank line (with no newline) into the output
    file.

I've written a couple dozen applications in literate style.
All are online for your amusement at:

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

Most of these are in Python, but included on this page are
literate expositions of Relax NG schemas, XSLT, and emacs LISP.
These techniques are language-independent.

My approach was inspired by my colleague Dr. Allan Stavely, who
calls it 'lightweight literate programming'.  He felt that
Knuth's approach to literate programming carried too much
overhead, and as we all know, many programmers will cling to any
excuse to avoid writing documentation.  In his approach, anyone
who knows DocBook can master the literate extensions in a few
minutes.  The resulting documentation validates against the
DocBook schema, so nxml-emacs and other tools work normally.

Comments on generalities and specifics will be most welcome.

Best regards,
John Shipman (john@nmt.edu), Applications Specialist, NM Tech Computer Center,
Speare 119, Socorro, NM 87801, (505) 835-5950, http://www.nmt.edu/~john
  ``Let's go outside and commiserate with nature.''  --Dave Farber