Re: [Dtddoc-develop] Documenting DTDs and their modules

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

Herv=E9 a =E9crit:

> I don't completely understand your need: I don't understand how two "mo=
dules"=20
> can refer each other, since it represents a circular dependency.
> Can you provide us a simplified sample, with as much as possible proble=
ms you=20
> identified? This will help us to understand what can be done.

(Sorry for replying only today, I have been rather busy... setting up a=20
complex build system that involves DTDDoc (among other things). :-))

OK, I'll try to be more concise and at the same time clearer about the=20
problem. First, here is what it is NOT. A circular dependency would=20
result from modules (or DTDs) that *import* each other, like this:

-- file m1.dtd --
<!ENTITY % m2 SYSTEM "m2.dtd">
%m2;
--

-- file m2.dtd --
<!ENTITY % m1 SYSTEM "m1.dtd">
%m1;
--

In contrast to this, I am talking about modules that *refer* to each=20
other, or more precisely, refer to declarations in their contents.=20
(Parts of the main DTD act as modules in that sense, too, see example=20
below.) For instance:

-- file module0.mod --
<!ENTITY inline_elements "b|i">
--

-- file module1.mod --
<!ENTITY % module0 SYSTEM "module0.mod">
%module0;
<!ELEMENT mo1 (momo1|momo2)+>
<!ELEMENT momo1 (#PCDATA|%inline_elements;)*>
--

-- file module2.mod --
<!ENTITY % module0 SYSTEM "module0.mod">
%module0;
<!ELEMENT mo2 (momo1|momo2)+>
<!ELEMENT momo2 (#PCDATA|%inline_elements;)*>
--

-- file main.mod --
<!ENTITY % module1 SYSTEM "module1.mod">
%module1;
<!ENTITY % module2 SYSTEM "module2.mod">
%module2;
<!ELEMENT root (para|mo1|mo2)+>
<!ELEMENT para (#PCDATA|%inline_elements;)*>
<!ELEMENT b (#PCDATA)>
<!ELEMENT i (#PCDATA)>
--

As you can see, the modules cannot be used on their own but need to be=20
included in the main DTD because only the whole makes up a syntactically =

valid DTD. This is why I insist on calling them "modules" rather than=20
sub-DTDs.

The problem is: DTDDoc only has access to all declarations when it is=20
processing the main DTD, because DTDParser (seemingly) returns it with=20
the entities expanded.

The docs generated for the modules, however, will be broken because of=20
the "forward references" allowed by the DTD mechanism: element and=20
entity declarations may refer to elements which have not yet been=20
declared. In module 1, this is the case for the references to the=20
elements b, i and momo2.

As their declarations are not available in the current module, DTDDoc=20
cannot link to the element entry. Consequently, the HTML link to this=20
(child) element will be completely left out from the parent's content=20
model in the documentation for the module, so for element mo1 in module=20
1 it will look like "(momo1 | )", likewise the content model of momo1=20
will be shown as "(#PCDATA | | )".

So why generate documentation for the modules at all? Because they carry =

important information about their contents, and I need to keep it there
rather than including it into the main DTD's documentation.

In my last mail, I have hoped to give some ideas on how this problem=20
could be tackled (as far as I have understood the processes).

   Yves