DiML/DocBook (was: using modules; version attribute)

[Jakob Voss <jakob.voss@nichtich.de>]

Hi,

Tobias Reif pointed me to this discussion and asked me to explain why we 
"switched away from DocBook". I am a student working at the electronic 
publishing group of Computer and Media Service (CMS) at Humboldt 
University, Berlin. We are archiving electronic dissertations for 
several years - see our document server:  http://edoc.hu-berlin.de

Most universities are only archiving in PDF - which has disatvantages in 
long-term preservation and almost no semantic markup. But how do you get 
markup? We force ;-) the authors to use a Microsoft Word Template (also 
supporting WordPerfect and LaTeX) and used "SGML Author for Word" to 
transform the document to SGML. The Word-issue is a must because most of 
the authors are using it - you just have to support it.

We have used a modified version of the Electronic Thesis and 
Dissertations DTD "ETD.dtd" called "DiML" (in SGML) since 1997.
It was my job to create an XML version of DiML - so we never used 
DocBook. 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.

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:

<module name="lists" version="1.0">
   <refpurpose lang="en">...</refpurpose>
   <refpurpose lang="de">...</refpurpose>
   <refdescription lang="en">
     <para>...<!--DocBook-->...</para>...
   </refdescription>
   <element name="ul">
     <group>block</group>
     <refpurpose lang="de">...</refpurpose>
     ...
     <contentspec type="children"> <!-- (caption?, li+) -->
       <dtd-sequence>
         <dtd-element name="caption" occurence="optional"/>
         <dtd-element name="li" occurence="more"/>
       </dtd-sequence>
     </contentspec>
   </element>
   ...

You can "compile" a DTD out of several modules with an XSLT script and I 
used the DocBook XSLT Library and DocBook Website to create HTML. 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 (I think this 
is the reason why Tobi is working of another XSLT to transform DocBook 
into XHTML).

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. By the way the styles for our module 
"CALSTable" mainly consist of parts of DocBook XSLT which i will have
to clean up a lot. The single modules contain only 2 to 22 elements.

You can download DiML-DTD at  http://edoc.hu-berlin.de/diml/

And diml-xsl is accessible via

http://sourceforge.net/project/showfiles.php?group_id=66498&release_id=166350

But it's only documented in German. To use diml-xsl transforming a 
dissertation or some other document into single HTML-files:

-install diml-xsl to directory  $FOO/diml-xsl/
-install DiML-DTD to directory  $FOO/dtd/xdiml.dtd
-cd $FOO/diml-xsl/tools/
-DiMLTransform.bat ../samples/test.xml ../samples/ ../style/
  or with Xalan and '.' in your CLASSPATH
-java DiMLTransform ../samples/test.xml ../samples/ ../style/

Feedback is welcome :-)

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)

  Jakob Voß