This is the mail archive of the
docbook-apps@lists.oasis-open.org
mailing list .
Literate Programming (first steps with litprog1.0)
- From: Georges Schmitz <georges dot schmitz at heitec dot de>
- To: docbook-apps <docbook-apps at lists dot oasis-open dot org>
- Date: Mon, 03 Mar 2003 15:16:58 +0100
- Subject: DOCBOOK-APPS: Literate Programming (first steps with litprog1.0)
Hi Norm,
I like your advance on Literate Programming and see some personal
application cases. But there are some points (conceptual uncertainties
from my side included), that prevent me from making full use of it. I'll
make a loose enumeration:
* I'm writing documentation for a DB-model that exists in SQL and XML
(tamino) as well. I use the "arch" attribute to profile the respective
parts (which is perfectly working). Literate Programming could be used
to embed XML Schema and SQL Script for database creation.
But - how do I separate XML Schema and SQL Script in the Tangle
process? I don't think that performing a "classical" profiling action
on the "arch" attribute first should be the way to go. Is there not a
need of *profiling* attributes in <src:fragment> itself?
These sorts of attributes could be useful in different scenarios:
- sw.feature (eg. demo, lite, pro,...)
- debug.level (useful in languages, scripts, macros,...
where features similar to log4j aren't available)
- arch
- ...
But maybe I'm wrong!
* Another point, where I'm lacking a clear concept is granularity of
hierarchical structure in DocBook XWeb: how do I work with
information, that has the character of inline comments? Example:
>>>>>>>
<section><title>Section B</title>
<para>Documentation Blabla ... </para>
<para>Comment Blabla ... </para>
<src:fragment id="B.1">
code B.1 ...
</src:fragment>
<para>Comment Blabla ... </para>
<src:fragment id="B.2">
<src:fragref linkend="A.1"/>
<src:fragref linkend="A.2"/>
</src:fragment>
<para>Comment Blabla ... </para>
<src:fragment id="B.3">
code B.3
</src:fragment>
</section>
<<<<<<<
[weawing this example results in no meaningful labeling]
Text in para of B.1-B.3 is just about 1 or 2 lines (or sentences) and
source fragments aren't longer either. Putting all these fragments
into sections (with title ...) results in an overstructured XWeb
document and output will suffer from readability. What is the
solution?
* You said, that until now you just support recursive "section"
structures in DocBook XWeb, in my eyes refsection would be fine too.
But as far as I know, DocBook stylesheets do not calculate any labels
for them, so I guess it will not be that easy to integrate it.
Regards,
Georges