[dbdoclet] dbdoclet 1.7 DocBook-XML Problems and PDF lines too long

Hi everybody,

I'm currently experimenting with DbDoclet version 1.7-210 and stumble about 
problems with the generated DocBook XML. But first, let me thank Michael Fuchs 
for his great work on DbDoclet and also for the DbDoclet distribution, which 
contains a working installation for a DocBook Java tool chain. Since I'm still 
a DocBook beginner and have only some limited experience with setting up a tool 
chain for DocBook I really appreciate that work.

Now the mentioned "XML problems".

1) Our Java code uses Java template classes, i.e. constructs like 
"java.util.List<com.wincornixdorf.SomeClass>". If I set the numbering scheme in 
DBDoclet to "java" this causes invalid XML files: 
the id attribute of a method with such a parameter contains the template 
syntax, for instance
id = 
"METHOD-COM.WINCORNIXDORF.OTHERCLASS.AMETHOD-JAVA.UTIL.LIST<COM.WINCORNIXDORF.SOMECLASS>-"
 

This is invalid XML because the "id" attribute must not contain "<" or ">" 
characters, neither as plain chars nor as entity-ref "&lt;".
The same problem occurs with the "linkend" attribute of link tags. My XML 
editor says something like "attribute value must be a name".
 XSLT fails.

2) In the generated DocBook XML the element "fieldsynopsis" contains an element 
"code" to describe the constant assignment to a member variable.
For instance:
        <fieldsynopsis language="java">
          <modifier>public</modifier>
          <modifier>static</modifier>
          <modifier>final</modifier>
          <type>int</type>
          <varname>VERSION</varname>
          <code> = 1</code>
        </fieldsynopsis>

According to the DocBook 4.5 DTD which I use, this should read "initializer" 
and should not contain the equals sign, i.e.
 
        <fieldsynopsis language="java">
          <modifier>public</modifier>
          <modifier>static</modifier>
          <modifier>final</modifier>
          <type>int</type>
          <varname>VERSION</varname>
          <initializer>1</initializer>
        </fieldsynopsis>

3) Although I've tried to enable line wrap in DBDoclet (param 
docbook.code.width=75) and in the xsl-fo template file "fo.xsl" 
(wrap-option=wrap), the generated PDF document still contains lines which are 
not wrapped and are too long to fit on the page. Enabling hyphenation for "fop" 
causes some strange hyphenation usages (and many good ones) but doesn't solve 
this problem.
 
This again seems to be related to the Java template classes used in our code. 
There are many situations where DbDoclet shortens the output line by dropping 
Java package names or reducing package names. However, sometimes this does not 
work. I can't see a complete pattern, when this shortening of package names 
occurs, but at least:

- if a method returns a templated collection, the type tag contains the fully 
qualified class name.
  instead of  
<type>java.util.List&lt;com.wincornixdorf.some.package.ADataClass&gt;</type>
  it might read <type>List&lt;package.ADataClass&gt;</type>
  
- if a constructor has a templated collection as parameter, same problem.

A method described in the "title" element inside "sect2", however, is perfect:
        <title>aMethod(anObject, List&lt;ADataClass&gt;)

Regards,
Udo Hempel

------------------------------------------------------
WINCOR NIXDORF International GmbH
Sitz der Gesellschaft: Paderborn
Registergericht Paderborn HRB 3507
Geschäftsführer: Eckard Heidloff (Vorsitzender), Stefan Auerbach, Jürgen Wilde, 
Dr. Jürgen Wunram
Vorsitzender des Aufsichtsrats: Karl-Heinz Stiller 
Steuernummer: 339/5884/0031
Ust-ID Nr.: DE812927716
WEEE-Reg.-Nr. DE44477193

Other related posts: