Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-4663254

stddoclet: Generates non-HTML-compliant <A NAME> and <A HREF> anchors (spaces)

    Details

      Description

      There are problems with invalid characters in
      <A NAME="..."> identifiers generated by the standard doclet.

      As I'm sure you know, the HTML spec section 6.2 states that:
      http://www.w3.org/TR/html401/types.html#type-cdata

      "# ID and NAME tokens must begin with a letter ([A-Za-z]) and may be followed
      by any number of letters, digits ([0-9]), hyphens ("-"), underscores ("_"),
      colons (":"), and periods (".")."

      The current method of making tags like
      <A HREF="../../javax/swing/AbstractListModel.html#fireContentsChanged(java.lang.Object, int, int)">
      probably can't continue if correct HTML is desired. Introducing < and > to
      this for generics will probably break browsers that happen to tolerate the
      current syntax (although they shouldn't have to.)

      Name: boT120536 Date: 01/15/2001

      ===========================================================================

      Example from <URL:http://java.sun.com/j2se/1.3/docs/api/java/lang/Object.html&gt;:

      <A NAME="wait(long, int)"><!-- --></A><H3>
      wait</H3>

      The name attribute, though declared in the formal part of the DTD as
      CDATA, is described in the prose as having name token syntax. This
      means that the parenthesis, comma, and whitespace characters are not
      permitted where javadoc puts them.

      The two main problems with this stem from the whitespace in
      particular:

      1. It's impossible to write an URL containing such an invalid fragment-
          identifier in a plain-text context such as email. Either it's written
          naked, and is parsed as "...Object.html#wait(long" or it's enclosed
          with "<URL: ... >" brackets and the whitespace is ignored, giving
          "...Object.html#wait(long,int)".

          [Yes, sending the following URL by mail, the link stops at the space -Doug]
          http://java.sun.com/j2se/1.4.2/docs/api/java/lang/Object.html#wait(long, int)

      2. Browsers such as emacs-w3 that do their own whitespace stripping
          on passed URLs cannot follow links from other javadoc HTML, for
          the same reason.

      My reading of the spec doesn't allow the use of "%" URL-escaping in
      fragment identifiers, so perhaps a better scheme would be to use the
      type codes as in the VM - eg "wait.JI" - perhaps using "-" instead of
      ";" to delimit class names.

      Incidentally, the empty A element is probably a bad idea - the above
      would be better written as <H3><A NAME="wait.JI">wait</A></H3>
      (Review ID: 109616)

        Attachments

          Issue Links

            Activity

              People

              • Assignee:
                bpatel Bhavesh Patel (Inactive)
                Reporter:
                gafter Neal Gafter
              • Votes:
                0 Vote for this issue
                Watchers:
                1 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved:
                  Imported:
                  Indexed: