Dave Pawson wrote:
Stefan Seefeld wrote:
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).
But XSLT can already do that Stefan?
As I mentioned, for me, being a developer, the documentation is embedded
into the code, not the other way around. Thus, the file to be processed
is primarily a source file that can readily be compiled / interpreted,
while documentation is embedded as annotation that may be extracted.
(This extraction is even part of the language / runtime in case of
Python, but not in other languages such as C++ or Java.)
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).
I guess my overall goal is to document the code. I.e.
cut up the code into small enough chunks to make
documentation easy.
http://www.dpawson.co.uk/temp/genWrapper.sh.html shows the start
of an example.
Have you any examples to compare Stefan?
Any piece of java code with embedded javadoc comments, for example. Here
is some C++ code, with embedded documentation, and cross-referenced via
Synopsis: http://synopsis.fresco.org/sxr/Source/src/Synopsis/Buffer.hh.html
The respective documentation is here:
http://synopsis.fresco.org/docs/Manual/cxx/index.html.
(I also have DocBook formatters in Synopsis, so I can generate DocBook
output from the above annotated source code, too.)
Note that this is not quite the same level of literate programming as
you seem to aim for, as I only document language artifacts themselves,
i.e. variables, types, functions, etc., while you want to annotate
individual statements.
Regards,
Stefan
--
...ich hab' noch einen Koffer in Berlin...
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
