RE: [docbook-apps] documenting code

["Casey Ackels" <casey@savirc.com>]

I may be completely off base here; but will RoboDoc do what you want?

 http://www.xs4all.nl/~rfsber/Robo/robodoc.html

- Casey

-----Original Message-----
From: Dave Pawson [mailto:davep@dpawson.co.uk] 
Sent: Wednesday, January 07, 2009 7:15 AM
To: Allan Stavely
Cc: Docbook Apps
Subject: Re: [docbook-apps] documenting code

Allan Stavely wrote:
> 
> May I jump in?

Please.

> 
> John sometimes does slightly more complicated things in his Python 
> scripts, things that aren't as easy to do with XSLT.  Myself, I usually 
> just use XSLT -- most of the time it does everything I need. Here's what 
> I use for most of my projects (eleven lines at its most
> complicated):
> 
>     http://www.nmt.edu/~al/Literate-programming/Examples/Extractcode

Looks very similar to the way I'm going, except I'm adapting the role
attribute for the language? So that I can get the revision history
from the docbook, and appropriately comment the revhistory in
the tangled python/xslt whatever

>> Not possible when the resultant command line needs to be on one line.
>> Embedded markup allows for better documentation. Again, easy
>> enough to strip out using XSLT.
> 
> Exactly, but this can just be another variation on the theme, if you 
> don't mind customizing your tools for your own needs. If DocBook doesn't 
> have the construct you mention, use it anyway and consider your notation 
> an "extended DocBook".  Write one XSLT transform to convert to standard 
> DocBook for use as a document (perhaps using a <programlisting> in this 
> case), and have your code-extractor transform do the other processing 
> you want (line concatentation in this case).  I've done this sort of 
> thing many a time.


Yes, one new empty element added to


  <define name="db.verbatim.inlines">
     <choice>
       <choice>
         <ref name="db.all.inlines"/>
         <ref name="db.lineannotation"/>
	<ref name='dp.linebreak'/> <!-- DP extension -->
       </choice>
       <ref name="db.co"/>
     </choice>
   </define>


<define name='dp.linebreak'>
   <element name='linebreak'>
     <empty/>
   </element>
</define>





> 
> 
>>> Another reply on this thread said that they prefer to keep the
>>> documentation inside the code, rather than the literate approach
>>> wherein the code is inside the documentation. 
>>
>> I prefer XML to wrap code simply to enable XSLT processing.
>>
>>
>> The drawback to
>>> their approach is that you need a different extractor for each
>>> language. 
>>
>> Or a more GP 'filter'. XSLT seems optimum to me.
> 
> I agree, at least for what I want to do most of the time.  But it's very 
> easy with Python too, or with lots of other programming languages.  To 
> each his own.

Fair comment

> 
> What we ought to be optimizing is (1) the writing process and (2) the
> end-product, so that reading is optimized.  Details of exactly what the 
> toolchain looks like are very, very trivial by comparison.  The
> transforms and scripts are a few dozen lines, but we'll use them to
> write many thousands of lines of product.
> 
> The important idea is putting the code inside the documentation, instead 
> of trying to so it the other way round, and I'm completely sold on that
> idea.

I agree with the approach, the xslt is trivial and I'm looking at
an ant setup to pull individual or all scripts/code out of the source,
passing
a) id of the element holding the code (currently sect1)
b) An output file name (which seems redundant; I'm using
the xml:id of the sect1 as the filename?

<sect1 xml:id='tangle.xslt' role='xslt'>
...


That provides all that I need for code extraction.
Documentation simply means a single template
for the linebreak element.
output <br /> for html
and fo:block for pdf




regards

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

---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org