Re: [docbook] DiML/DocBook (was: using modules; version attribute)

[Tobias Reif <tobiasreif@pinkjuice.com>]

Hi Jakob,

thank you very much for the detailed explanation :)
(more below)

 > When I started last year I also asked myself why not to use
 > DocBook or TEI but the main reason is simply the purpose: There are
 > several XML-based document formats (XHTML, TEI, DocBook, ISO Book,
 > Open
 > Office, NITF...) for different purposes. DocBook is full of elements
 > you
 > may need for documentations in computer science but it's not the right
 > language to write dissertations in for instance social sciences.

Some do it I think, but I agree that it's not the most appropriate 
language for this kind of task.

DocBook for documenting schemas (DTD/RNG/...) on the other hand should 
work well.

 > I rebuilt the DiML-DTD in a higly modularized way. Since I found no
 > satisfying XML based language to manage *and* document DTDs (DDML was
 > just a try) a wrote a system on my own. The elements of the DiML-DTD
 > are
 > stored in modules written in XML. I used parts of DocBook to write the
 > documentation in the same file with the definition:

Try Relax NG:

http://www.oasis-open.org/committees/relax-ng/spec-20011203.html#full-syntax-example

<?xml version="1.0"?>
<element name="foo"
          xmlns="http://relaxng.org/ns/structure/1.0"
          xmlns:a="http://relaxng.org/ns/annotation/1.0"
          xmlns:ex1="http://www.example.com/n1"
          xmlns:ex2="http://www.example.com/n2">
  <a:documentation>A foo element.</a:document>
  <element name="ex1:bar1">
   <empty/>
  </element>
  <element name="ex2:bar2">
   <empty/>
  </element>
</element>

You can generate DTDs from RNG schemas

....
 >     <para>...<!--DocBook-->...</para>...
...

Ah, that's how you used it ... :)

 > Since
 > we have parts of a "DiML XSLT library" (diml-xsl) now, I'm switching
 > to
 > DiML for documenting the DTD itself. Using DocBook was not comfortable
 > because there is this big DTD *and* the huge DocBook XSLT

Bob, to clarify: That's why I wrote that they "switched away from DocBook".

 > (I think this
 > is the reason why Tobi is working of another XSLT to transform DocBook
 > into XHTML).

Not really.

For the motivation and more info, check
http://www.pinkjuice.com/joocs/doc/

BTW:
http://www.pinkjuice.com/joocs/
is not meant to replace the popular docbook.sf.net XSLTs.

 > diml-xsl (diml2html) is modularized in the same way as the DiML DTD.
 > In the main file I import all the subdirectories via
 >
 > <xsl:include href="module-common/html.xsl"/>
 > <xsl:include href="module-media/html.xsl"/>
 > <xsl:include href="module-text/html.xsl"/>
 > <xsl:include href="module-structure/html.xsl"/>
 > <xsl:include href="module-citation/html.xsl"/>
 > <xsl:include href="module-documents/html.xsl"/>
 > <xsl:include href="module-mathematics/html.xsl"/>
 > <xsl:include href="module-CALStable/html.xsl"/>
 > <xsl:include href="module-lists/html.xsl"/>
 > <xsl:include href="module-diml/html.xsl"/>
 >
 > and if a module is not used in a DiML-file, then you also do not need
 > the according part of diml-xsl.

Makes a lot of sense.

You can also do that in Relax NG (specify why modules are used in the 
documents, then do what you did above):

Eg as in
http://thaiopensource.com/relaxng/xhtml/xhtml-strict.rng :

<grammar ns="http://www.w3.org/1999/xhtml"
          xmlns="http://relaxng.org/ns/structure/1.0">
   <include href="modules/datatypes.rng"/>
   <include href="modules/attribs.rng"/>
   <include href="modules/struct.rng"/>
   <include href="modules/text.rng"/>
   <include href="modules/hypertext.rng"/>
   <!-- ... -->
</grammar>

 > Personally I do not use DocBook because I prefer writing text in
 > WYSIWYG-editors. I think OpenOffice is on the right way (we use Open
 > Office to transform Word to XML and another XSLT to get DiML)

I think OOffice 1.1 will offer some DocBook export.

Tobi

-- 
http://www.pinkjuice.com/