OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook message

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

Subject: DOCBOOK: DocBook as embedded documentation language


I would like to use a subset of DocBook to write documentation snippets
inside unrelated other schemas. There are a number of XML vocabularies
that could use some embedded documentation, XSLT and XML Schema being
the two that interest me most.

The proper way to do this is already hinted at in the XML Schema DTD: it
has an xs:documentation element with an as yet undefined content model.
an ideal place to slot some DocBook in.

A documentation-extracting XSLT stylesheet would transform (some parts)
of the other vocabulary into DocBook and copy the parts that are already

Now I have two problems implementing this idea:
1) What's a good subset to use, and how do I use the modular structure
   of the DTD to my advantage?
2) Ideally, the DocBook parts would live in their own namespace, so that
   literate-programming-like mixing of documentation and
   programming/definition is possible. The Schema DTD uses a neat trick
   [1] that makes it possible to pick your own namespace prefix while
   still using a DTD. I see the experimental Schema (of course) uses
   namespaces, but I'd like to use a DTD for greater choice of tools.
   Any chance of this trick appearing in an updated DocBook DTD

Lastly, some of you must have thought of this before and perhaps started
implementing it already. I'd like to hear from you.

[1] See http://www.w3.org/2001/XMLSchema.dtd
The idea is that the first face shown to people is one they can readily
accept - a more traditional logo. The lunacy element is only revealed
subsequently, via the LunaDude. [excerpted from the Lunatech Identity Manual]

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

Powered by eList eXpress LLC