I recently outlined a dilemma gjdoc is facing [1] [2]: it can be compatible to the traditional javadoc tool, or to HTML/XHTML, but not to both at the same time.
I'll try to summarize the issue briefly. - According to the XML, XHTML and HTML4 specifications, javadoc uses invalid fragment URIs. An example would be: http://developer.classpath.org/doc/java/io/InputStream.html#read(byte[],int,int) "()[]," are invalid characters according to the specification. See [1] for more. David Gilbert pointed out that this is a known bug "in progress" at Sun: http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4663254 Unfortunately it was filed three years ago and there hasn't been a follow-up since 2003. So it doesn't seem like Sun would address this anytime soon. - As a workaround, latest gjdoc CVS can either generate code conforming to javadoc (i.e., create invalid URIs compatible to javadoc) or conforming to XHTML (i.e. create valid URIs incompatible to javadoc). For the time being, the default is to generate javadoc-compatible code. Use -validhtml to enable HTML-compatible code. - In the context of a single, isolated documentation set, the URI naming scheme is mostly irrelevant, except for the way it displays in the browser status bar and plain-text messages etc. The naming scheme is very relevant though when interlinking documentation sets using -link or -linkoffline. - Thus, documentation sets generated by gjdoc in HTML-compatibility mode cannot be properly linked to by javadoc, and javadoc does not produce a warning for this problem. That's because above URL (abbreviated): InputStream.html#read(byte[],int,int) currently looks mangled for XML conformity like so: InputStream.html#read:byte-:int:int And there's no way for javadoc (or gjdoc, for that matter) to check whether a fragment URI actually maps to anything. (When using gjdoc, any documentation set can be linked to properly, regardless of whether it's been generated by javadoc, gjdoc, or gjdoc -validhtml. That's because gjdoc-generated documentation now includes a properties file which specifies the mangling mode, the absence of which tells gjdoc to use javadoc-compatibility mode) (Javadoc could be forced to refuse to link to the documentation set altogether and report an error, but there wouldn't be a way to inform users about the reason for the failure.) (It should also be noted that most inter-documentation hyperlinks are links to classes which aren't affected by this issue. This issue only affects links to method and constructor descriptions which are relatively rare in real life. Furthermore, if a fragment URI "fails" - that is, the anchor portion of a URI doesn't match anything - quiet any browser will fall back to the top of the corresponding page (the class documentation), which isn't too bad.) This situation raises two questions: 1) Which mode should the Classpath API documentation at http://developer.classpath.org/doc/ be generated in? 2) Which mode should be the default for the next release of gjdoc? This boils down to the question, how important is strict javadoc compatibility/interoperability as opposed to "doing the right thing"? I personally lean towards javadoc compatibility. I think in practice it's what hurts the least, even if W3C validator complains. After all, recent versions of gjdoc up to and including 0.7.5 had produced badly nested XHTML code and nobody has complained loudly so far. I doubt anybody is feeding HtmlDoclet output through an XML pipeline, so what matters is how it works on the different browsers. And it seems to work just fine - save complaints about IE, but I doubt that those are related to the URI scheme in use. In other words, while I'd like to have gjdoc produce 100% compliant XHTML 1.1 code, in practice I don't see an immediate need for it. I do see a need however to have compatibility to javadoc. So I plan to work around this dilemma by accepting not-so-valid XHTML output as long as nobody experiences any severe problems with this approach. With regard to the public Classpath API docs, I'd likewise recommend not to use -validhtml for the time being. Please share your opinion on this issue. Julian [1] http://article.gmane.org/gmane.comp.java.classpath.tools.general/15 [2] http://article.gmane.org/gmane.comp.java.classpath.tools.general/16 _______________________________________________ Cp-tools-discuss mailing list [email protected] http://lists.gnu.org/mailman/listinfo/cp-tools-discuss
