[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Gjdoc URI Dilemma
From: |
Julian Scheid |
Subject: |
Gjdoc URI Dilemma |
Date: |
Wed, 25 May 2005 03:50:36 +0200 |
User-agent: |
Debian Thunderbird 1.0.2 (X11/20050402) |
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
- Gjdoc URI Dilemma,
Julian Scheid <=