Re: [docbook-apps] documenting code

[Dave Pawson <davep@dpawson.co.uk>]

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?


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


regards

-- 
Dave Pawson
XSLT XSL-FO FAQ.
http://www.dpawson.co.uk