[Dtddoc-develop] Feature Request

[Alexander H. <ale...@al...>]

Hi all,

I just started using dtddoc, it is a great tool so far. My use case is
the following:

I auto-generate several dtd files for several xml namespaces including
dtddoc comments in order to generate human readable documentation for
the xml structure.

In principle everything works as expected, in practice I ran into
several smaller issues that would be nice to have fixed:

1. When passing several dtd files to dtddoc, the generated links to tags
from one dtd to another dtd do not always work and I get an error that
certain tags are undefined.

Currently, I fix this by generating only a single dtd file with the
content merged from the multiple files. When I do that, all links work
as expected and no errors are generated.

2. I generate links to sections in the html documentation of tags inside
the comments that document a tag (using <a href="#tagname">tagname</a>
where tagname is somehow related to the current tag). It would be
nice if there was a meta tag (e.g. @link(tagname)) that would be
replaced by the appropriate hyperlink by dtddoc. That would be
especially helpful, if my first issue is fixed so that sometimes
@link(tagname) is replaced by a link to a different html file, when a
tag from a different dtd is referenced. generally, I want to avoid to
generate any html myself, if I can.

3. I would like to have some more flexibility for the table that is
generated for a tag's children. Currently, this seems to be restricted
to two columns : Name and Cardinality. It would be very nice to have an
optional third row maybe using the following in the dtddoc comment in

front of an element declaration:
<!--
@child childname some comment 1
@child childname2 some comment 2
-->
<ELEMENT xxx (childname|childname2)>

should generate:

xxx's childs

Name Cardinality Comment
childname Any some comment 1
childname2 Any some comment 2

If the @child is present, the "some comment" text could be placed in the
third column. This could also be configured as a global option to dtd,
including the name of the additional child table column (so that it is
not "Comment" but something else set in the general dtddoc options).

In my case, different child tags belong to different categories of tags
and expose different behavior depending on the category (e.g. some tags
must have certain attributes when used as a child tag, other tags do not
have this restriction).

Currently, I manually generate a 3 column table in the element dtddoc
comment, so that I can document this information. If a third row was
added to the child table, I would be able to use the default table
instead and could abstain from manual html generation.

For uniformity reasons, it probably would be good to also have an
optional third row for the attributes table as well, where I can place
some custom info.

Thanks for your help and providing a great tool,
Regards,
Alex