[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Cp-tools-discuss] RFC: Gjdoc and valid HTML
From: |
Julian Scheid |
Subject: |
[Cp-tools-discuss] RFC: Gjdoc and valid HTML |
Date: |
Mon, 23 May 2005 15:12:49 +0200 |
User-agent: |
Debian Thunderbird 1.0.2 (X11/20050402) |
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
- [Cp-tools-discuss] RFC: Gjdoc and valid HTML,
Julian Scheid <=