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: [email protected]
For additional commands, e-mail: [email protected]
