
    gjdoc - A doclet driver for the Java platform.
    Copyright (C) 2001 Free Software Foundation

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA

gjdoc
=====

Doclet driver with standard Doclet.

Version 0.4.1
(C) 2001, 2002, 2003 Free Software Foundation

Released under the GNU General Public License (GPL).

1. Overview
2. Missing Features
3. Installation
4. Usage
5. Evaluation
6. Feedback

1. Overview
------------------------------------------------------------------------------

`gjdoc' is a drop-in replacement for the command line tool `javadoc' 
shipped with Sun's JDK. 

It is written in pure Java and requires a 1.2 classpath. 

`gjdoc' aims at implementing all features of Sun's Javadoc 1.4, while
maintaining full compatibility. Currently, around 90% of the Doclet
API is implemented.

However, in contrast to Javadoc, `gjdoc' does not perfom syntax 
checking on the supplied sources. If necessary, use something like 
`jikes +B' for checking the sources beforehand. 

The gjdoc package also contains a standard doclet which allows you to
generate XML code and HTML code (HTML code generation currently
requires libxslt).

This tool is part of the GNU Classpath-Tools project. 
See http://www.gnu.org/software/cp-tools/


2. Missing Features
------------------------------------------------------------------------------

- No Javadoc 1.4 functionality. 
  For example, Taglets are not supported.

- Tags:
    @serial
    @serialData
    @serialField
    {@docRoot}

- Command Line Options:
    -overview
    -docletpath
    -1.1
    -bootclasspath
    -extdirs
    -verbose
    -locale
    -encoding
    -J<flag>

- Known Bugs: 
    @see and @link tags are not always interpreted correctly.

3. Installing
------------------------------------------------------------------------------

This version includes an Ant build file. To use it, make sure that
ant, java, javac, gcj and xsltproc all are on your path. Your gcj
needs to support threads.

Using Ant you can build the distribution as follows:
 
  cvs co gjdoc
  cd gjdoc

  cd src

  # --- Produce gjdoc/dist/gjdoc.jar
  ant              

  # --- Optionally produce gjdoc/dist/gjdoc executable
  ant gcj          

  cd ..

  # --- Test package by having it generate documentation for its own sources

  examples/gjdoc-docs.sh
  ls tmp/gjdoc-api-html

  # --- Test package by having it generate the full documentation for the
  # --- GNU Classpath API. This can take some time

  examples/classpath-docs.sh /path/to/classpath
  ls tmp/classpath-api-html

An automakejar based build coming up soon.


3.1 Manual installation
------------------------------------------------------------------------------

For now, just compile all sources and put them on your classpath
or into a jarball. Currently, when running the tool you need to
make sure that gjdoc is the current directory.

And you can use gcj (the GNU Compiler for Java - tested with version 3.2)
to compile it all into a nice binary:

  cd src; gcj -o ../bin/gjdoc --main=gnu.classpath.tools.gjdoc.Main \
      gnu/classpath/tools/gjdoc/*.java com/sun/javadoc/*.java \
      gnu/classpath/tools/doclets/xmldoclet/*.java


4. Usage
------------------------------------------------------------------------------

Run `gjdoc' without parameters for further usage information.

More information coming soon.


5. Feedback
------------------------------------------------------------------------------

Please send comments and suggestions to <cp-tools-discuss@gnu.org>.
