From: <her...@fr...> - 2007-11-02 19:09:35
|
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 |