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






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