[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [docbook-apps] Suggested Writing Style
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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]