[Dtddoc-develop] Documenting DTDs and their modules

[Yves F. (SRZ) <Y....@sr...>]

As far as I can see, DTDDoc's concept is to process a set of DTDs which 
are independent of each other, in the sense that their docs do not need 
to be linked. This does of course not prevent simple inclusion of one 
DTD in another, which would just lead to repeated descriptions of the 
included elements, attributes and entities.

By contrast to this model, I am faced with the situation of having a DTD 
which includes a set of modules. Rather than just constituting sub-DTDs, 
these modules are interrelated among each other and of course with the 
main DTD which includes them. (For simplicity, I am assuming that there 
is no hierarchy of modules, each of them is just included in the main 
DTD.) "Interrelated" essentially means three things here:

1 - At the DTD-syntactical level, module A may contain a declaration for 
element a1 that references element b1 which is declared in module B. 
While the main DTD, after inclusion of the modules, disposes of both 
declarations, the modules themselves do not (and do not need to do so 
because they are just modules, not DTDs on their own).

The effect of this is that when DTDDoc generates documentation for 
module A, the description of the content model of a1 will lack the 
complete link to b1, displaying a defective model like "(a2, , a3)" 
instead of the actual "(a2, b1, a3)", while the same description in the 
main DTD will be correct. The same applies of course to references in a 
module which rely on declarations occurring not in another module but in 
the main DTD.

2 - At the documentary level, each module has specific "global" 
information (purpose, version history etc.) aside the comments which 
accompany DTD-syntactical declarations. As a consequence, documentation 
must be generated not only for the whole DTD but for each module as 
well, because there is no reasonable other way to access this info 
(repeating it somehow in the main DTD is way too complicated: how to 
ensure it is transferred from the module? where to put it? how to access 
it?).

3 - The modules are logically related, and so is their documentation. At 
least, the documentation of a module may contain links to other parts of 
that same module's documentation. These links will be broken when the 
module is included together with its documentation into the main DTD.

Problem No. 3 seems easiest to solve: it should suffice to include the 
name of the file generated by DTDDoc for the module's documentation in 
the links, i.e. to use "module_A.dtd.html#my_target" instead of just 
"#my_target" when putting links in the module's documentation comments. 
That will allow reaching the link destination from any DTD documentation 
file in the directory.

The other two problems seem to be much more difficult to solve. Due to 
issue 2, I can't avoid to generate separate documentation for each of 
the modules. This means I have to deal with issue 1, i.e. avoiding links 
to element and attribute declarations from being broken because they 
reside in another module. These ideas came to my mind:

A) For any module, have DTDDoc ignore any declarations because they 
might not be interpreted correctly (if referenced declarations are 
missing) and will be done with anyway in the main DTD (supposing that 
all modules are included there). This raises the problem of knowing what 
is a module and of changing DTDDoc's behavior accordingly, but would 
allow all links to element documentation, both generated by DTDDoc and 
set up manually, to target places in a single file, namely the main 
DTD's documentation file ("main.dtd.html").

B) While parsing the DTD, take note of which module some declaration 
comes from, by examining the parameter entity references which are used 
for inclusion. When generating documentation for elements etc., draw on 
this info and

- either build links for child elements etc. that correctly target the 
documentation file of the concerned module (or alternatively, always 
that of the main DTD)

- or instead of creating a new documentation entry in the current 
module, just generate a cross-reference (a concept new to DTDDoc) to the 
documentation file of the module where the declaration originates from.


What do you think about this? Do you have any suggestion how to document 
DTDs and their modules while assuring that this does not break the links?

Yours,

   Yves