[Cp-tools-discuss] Gjdoc URI Dilemma

[Julian Scheid]

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