[Cp-tools-discuss] Gjdoc 0.6.1

[Julian Scheid]

A new minor release of GNU Gjdoc is in CVS and brings another major
refactoring. I'm now satisfied with the basic design and don't plan to
make any further groundbreaking architectural changes.

I've labelled this one 0.6.1. For those in a hurry, this version
brings you the following goodies:

- supports Xalan, Saxon, LibxmlJ or any other JAXP-compliant XSLT
  processor.

- encapsulates the XSLT processing stage in a "DocTranslet"
  interface, providing an XSLT-based alternative to conventional
  Doclets.

- supports Taglets, and includes a @copyright taglet.

- includes an improved CSS stylesheet (i.e. produces nicer HTML
  documentation), and the HTML documentation now includes some
  previously missing features.

Read on for more details on these improvements.

* Gjdoc now performs all XSL transformations via standard JAXP. This
  means that the System.exec("xsltproc") kludge is no longer
  necessary. It also means that Gjdoc can now be used with every
  JAXP-compliant transformer, like Apache Xalan or Michael Kay's
  Saxon.

  You can now link Gjdoc with LibxmlJ. Native compilation and linking
  using gcj works, too.

* The XSL transformation part is now encapsulated in what I've named a
  "DocTranslet". Essentially, a DocTranslet is a Jar file containing
  the XSL stylesheets and supplementary files for one particular type
  of output, as well as instructions on how to apply the stylesheets
  to the raw XML documentation files. The files do not necessarily
  have to reside in a Jar file, they can be somewhere on the CLASSPATH
  as well. (Read more in upcomíng documentation.)

  The HTML DocTranslet is the default DocTranslet, just as
  gjdocxml2html.xsl was the default stylesheet before. This "standard"
  DocTranslet isn't distributed as a separate jar file, instead it's
  part of the main Gjdoc executable and the gjdoc.jar file.

  Note that formerly Gjdoc had only one XSL stylesheet per output
  format, and this stylesheet produced all output files in one single
  run of the XSL transformer. In the new version however, there is one
  stylesheet per output file type per output format, and the
  transformer is run once per output file. While the new approach is
  slower that the previous, it removes the dependency on the
  <xsl:document> extension tag, making the HTML DocTranslet fully XSLT
  1.0 compliant AFAICT.

* Gjdoc now includes Taglet support, and a Copyright taglet as
  suggested by Brian. Use like this:

     gjdoc -taglet gnu.classpath.tools.taglets.CopyrightTaglet ...

  Usage in javadoc comments:

     @copyright 2003 The Frobnicators

  ... will result in the following notice at the end of the class (or
  method or field) documentation, in italics:

     Copyright (C) 2003 The Frobnicators

  where (C) is actually the appropriate HTML entity for the
  C-in-a-circle symbol. In case it survives the transport: the `©'
  symbol. (The HTML entity renders fine on off-the-shelf browsers,
  though.)

  You can also use the tag multiple times in one comment to denote
  multiple Copyrights.

* The CSS stylesheet should now make the HTML documentation look more
  professional and more of a piece. Layout is lighter due to adjusted
  border and margin sizes. Tables now look nice on Mozilla and IE,
  haven't checked other browsers yet. Cheap yellow has been replaced
  by cheap blue.

  All elements are now relatively-sized, i.e. they display with your
  personally preferred font size and always look "relatively" nice, no
  matter what font size you use. Mozilla users can test this by doing
  Ctrl + and Ctrl -. In other words, now it scales well.

Where to go from here:

* Gjdoc lacks a proper build file. Ant is OK, but automake/autoconf or
  automakejar based would be better. The build files I wrote for
  LibxmlJ work well for me on several systems, except the dependency
  glitch I mentioned. Can you verify that it basically works? If yes,
  I'd adapt these build files for Gjdoc (after fixing the glitch).

* Serialization pages, class usage pages, documentation of static
  final field values, and an overview page are still missing as well.
  Also, I've reintroduced problems with HTML entities like &auml;
  will fix this soon.

* There are three uses of XmlDoclet beyond HTML generation I
  personally would find very useful: DocBook code generation, Info
  code generation, and C++ JNI wrapper generation. All of these are
  already more or less working locally (as a DocTranslet). I'll try
  to get them finished and checked in one by one during the coming
  weeks.

Feedback is welcome!

Julian