[Cp-tools-discuss] RFC: Gjdoc and valid HTML

[Julian Scheid]

Hi everyone,

I recently became aware of the following thread which discusses the 
quality of the HTML code generated by Gjdoc:

        http://www.jfree.org/phpBB2/viewtopic.php?t=12390&;

Yesterday I spent some time fixing a number of issues which led to the 
malformed HTML output.  The output is now valid XHTML1.1 Strict (plus 
the optional Target Module) except for one aspect.

Javadoc (and, currently, Gjdoc) uses the full method signature for 
naming HTML anchors for constructor and method detail descriptions.  For 
example, the following generated HTML code is taken straight from 
http://developer.classpath.org/doc/java/lang/Object.html:

        <a name="wait(long,int)"/>

The fact that Gjdoc uses the same naming scheme as Javadoc for anchors 
like this enables linking between Javadoc- and Gjdoc-generated 
documentation (using the -link/-linkoffline facilities.)

The problem with this is that parentheses and commas are not valid 
characters for the NAME attribute in both XHTML and HTML4.

For XHTML, the NAME attribute should actually be the ID attribute and 
must match the XML "Name" production which only allows the following 
ASCII7 characters: Letter, Digit, '.', '-', '_' and ':'.

See http://www.w3.org/TR/xhtml1/#C_8 and http://www.w3.org/TR/REC-xml/#id

The same limitation exists in HTML4, see 
http://www.w3.org/TR/html4/types.html#h-6.2

As far as I can see, this means that we have to either:

- keep generating invalid HTML/XHTML in order to retain the ability to 
link to Gjdoc-generated docs from Javadoc-generated docs, and vice versa.

- use a naming scheme which is conform to HTML/XHTML, breaking 
compatibility to Javadoc.

One could argue that since the only invalid aspect of the generated HTML 
 is the use of illegal characters in anchor names, which most likely 
does not interfere with the rendering of the page and is known to work 
in all major browsers, it is acceptable to generate invalid pages in 
order to retain the ability to link with Javadoc-generated pages.

On the other hand, one could argue that Javadoc compatibility should not 
be retained at all cost, especially when it requires violating 
well-established standards.

Perhaps this should be made configurable using a command line switch. 
Then the question would be whether to default to standard compliancy or 
to javadoc compatibility.

It should be noted that the incompatibility problem could be mitigated 
by having Gjdoc detect whether an external documentation set uses 
standard-compliant anchor naming (has been generated using Gjdoc in 
standard mode) or javadoc-compatible naming (has been generated using 
Javadoc or using Gjdoc in compatibility mode). Gjdoc could then use the 
appropriate scheme for linking to the external documentation set, 
emitting a warning if it is forced to generate invalid HTML code. This 
would however only work in one direction - it would still be impossible 
to use Javadoc to link to pages generated by Gjdoc in standards mode.

Please let me know your thoughts on this issue.

Thanks,

Julian