Dave Pawson wrote:
I've seen Norm using docbook to tangle and weave XML.
I'm wondering how well docbook would work for code?
I have a mixed bag of bash scripts, Python code and xslt.
I want to keep it up to date and documented.
I'm thinking about taking the working code (today)
and embedding it in docbook.
I have never attempted to do anything like this with XSLT. C++, Python,
etc. I usually handle the other way around: Instead of embedding the
code into documentation, I embed documentation (comments) into the
program, so I can extract it easily with special tools (I'm working on
Synopsis: http://synopsis.fresco.org, which does that).
The advantage is that the code is readily usable without pre-processing,
and the embedded docs are readable as mere code annotation. In
particular, I prefer those documentation strings to use a lightweight
markup (such as ReStructuredText:
http://docutils.sourceforge.net/rst.html, which can be easily mapped to
a subset of DocBook).
Easy enough to pull the various files out of it
(all d:programlisting in one file/chapter/sect1 etc).
Anyone ideas on versioning, should that become an issue?
use the version of the wrapper?
I'd expect the code to require finer-grained versioning than the
documentation.
Regards,
Stefan
--
...ich hab' noch einen Koffer in Berlin...
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
