OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

docbook-apps message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: Re: [docbook-apps] documenting code


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



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]