The .html that is generated for
   <a href='http://....&#39;.

is ok for the page that contains it, but if the snippet has to be included
in an index/summary... page, it gets mangled. As if javadoc sees
the ' and thinks that what follows is a relative pathname - it prepends
the current location to the http://... and creates a broken link.

This does not occur if double quotes are used.

As far as I can tell , the above is legal html.

For example, see src/share/classes/org/w3c/dom/Text.java. It contains this:
-----
 * and represents the textual content (termed <a href='http://www.w3.org/TR/2004/REC-xml-20040204#syntax&#39;&gt;character data</a> in XML) of an <code>Element</code> or <code>Attr</code>. If there is no

-----
Which causes this bad link:
http://java.sun.com/j2se/1.5.0/docs/api/org/w3c/dom/&#39;http://www.w3.org/TR/2004/REC-xml-20040204#syntax&#39;

in file
   http://java.sun.com/j2se/1.5.0/docs/api/index-files/index-20.html