The J2SE specification is the document generated by javadoc plus
all specs that it references (usually by way of hyperlinks).

This is a request for a specification bibliography, in the sense
that it would be a summary of all documents outside the doc
bundle that are part of the spec.

In 1.4 we published to licensees a page that listed documents
that comprised the J2SE spec. It would be useful to incorporate
such a list into the J2SE specification, but only if it could be
automatically generated from spec references in the Javadoc, as
it duplicates information already in the spec.

For example, here is a reference under the heading "Additional Specification"

   AWT Focus Subsystem (which links to a file that resides in the source tree)
   http://java.sun.com/j2se/1.5.0/docs/api/java/awt/package-summary.html#package_description

As another example, here is a reference under the heading "Package Specification":

   JMX Specification (which links off to jcp.org)
    http://java.sun.com/j2se/1.5.0/docs/api/javax/management/package-summary.html#spec

We could work out some kind of tagging that identifies the document titles
and URLs to pick up and place on the summary page.

The guiding principle would be something like:

   This spec is composed of this document plus all documents referenced
   under specification headings such as "Additional Specifications" or
   "Package Specification". Non-normative documentation includes examples
   and documentation that is identified by <some "non-spec" subhead>.

###@###.### 2005-04-07 01:49:15 GMT

Javadoc block tags could be created that are similar to @see links.

In discussions with Stan and Patrick (the TCK manager), we lean
toward having a javadoc tag to indicate an "external" document is
part of the spec. Perhaps something along the lines of this:

  @refspec <a href="http://www.unicode.org">UNICODE Standard 4.0</a>
  @extspec <a href="http://www.unicode.org">UNICODE Standard 4.0</a>
  @addspec <a href="http://www.unicode.org">UNICODE Standard 4.0</a>
  @seespec <a href="http://www.unicode.org">UNICODE Standard 4.0</a>
  @supplspec <a href="http://www.unicode.org">UNICODE Standard 4.0</a>

It would be similar a @see tag in that it would generate a section
on that same page:

  Additional Specification
      * <a href="http://www.unicode.org">UNICODE Standard 4.0</a>

  in this example, on the page java.lang.Character:
  http://rhea:91/j2se/1.5.0/docs/api/java/lang/Character.html

plus it would add this entry to a new external reference specification
page that javadoc would generate, such as:
http://swpubs.sfbay/writing/j2se/1.4.0/OEMspec/api/Additional/index.html

###@###.### 2005-05-09 18:59:47 GMT