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

[<her...@fr...>]

Hallo Yves,

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

Herv=E9

Le vendredi 02 novembre 2007, Yves Forkl (SRZ) a =E9crit :
> 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
>
> -------------------------------------------------------------------------
> This SF.net email is sponsored by: Splunk Inc.
> Still grepping through log files to find problems?  Stop.
> Now Search log events and configuration files using AJAX and a browser.
> Download your FREE copy of Splunk now >> http://get.splunk.com/
> _______________________________________________
> Dtddoc-develop mailing list
> Dtd...@li...
> https://lists.sourceforge.net/lists/listinfo/dtddoc-develop