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

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


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


> 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">
         <ref name="db.all.inlines"/>
         <ref name="db.lineannotation"/>
	<ref name='dp.linebreak'/> <!-- DP extension -->
       <ref name="db.co"/>

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

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


Dave Pawson

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

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