[cp-patches] FYI: Fixed gjdoc documentation generation and renamed to --with-gjdoc

[Mark Wielaard]

Hi,

Our documentation generation with gjdoc was hugely out of date (and
completely broken). gjdoc has improved a lot and has a lot of
convenience arguments have been added. Most of our build infrastructure
has become unnecessary by the -subpackages argument and the -licensetext
option for example. To make the configure options more consistent I have
also renamed the option to enable it --with-gjdoc. You can give it as
argument a program or script to run when no gjdoc executable is in your
path.

2005-01-09  Mark Wielaard  <address@hidden>

        * acinclude.m4 (CLASSPATH_WITH_GJDOC): Renamed from
        CLASSPATH_ENABLE_GJDOC. Can now take argument to use as gjdoc program.
        Doesn't depend on xml tools.
        * configure.ac: Use CLASSPATH_WITH_GJDOC.
        * INSTALL: Mention --with-gjdoc option.
        * NEWS: Add --with-gjdoc addition.
        * doc/api/Makefile.am (EXTRA_DIST): Removed.
        (sourcepath): New variable.
        (htmllist): Removed.
        (core): Removed.
        (packages): Removed.
        (date): Removed.
        (clean): Also remove create_html file.
        (create_html): Rewritten.
        * doc/api/classpath-copyright.xml: Removed.

Committed.

I will put up a sample output on developer.classpath.org to show how it
currently looks.

Cheers,

Mark

Index: acinclude.m4
===================================================================
RCS file: /cvsroot/classpath/classpath/acinclude.m4,v
retrieving revision 1.46
diff -u -r1.46 acinclude.m4
--- acinclude.m4        2 Jan 2005 20:08:50 -0000       1.46
+++ acinclude.m4        9 Jan 2005 13:06:09 -0000
@@ -346,29 +346,32 @@
 ])
 
 dnl -----------------------------------------------------------
-dnl Enable generation of API documentation, assumes gjdoc
-dnl has been compiled to an executable or a suitable script
-dnl is in your PATH
+dnl Enable generation of API documentation, with gjdoc if it
+dnl has been compiled to an executable (or a suitable script
+dnl is in your PATH) or using the argument as gjdoc executable.
 dnl -----------------------------------------------------------
-AC_DEFUN([CLASSPATH_ENABLE_GJDOC],
+AC_DEFUN([CLASSPATH_WITH_GJDOC],
 [
-  AC_ARG_ENABLE([gjdoc],
-                [AS_HELP_STRING([--enable-gjdoc],[enable API doc. generation 
[default=no]])],
-                [
-                  case "${enableval}" in
-                    yes) ENABLE_GJDOC=yes ;;
-                    no) ENABLE_GJDOC=no ;;
-                    *) ENABLE_GJDOC=yes ;;
-                  esac
-                  if test "x${ENABLE_GJDOC}" = xyes; then
-                    AC_PATH_PROG(GJDOC, gjdoc)
-                    AC_PATH_PROG(XMLCATALOG, xmlcatalog)
-                    AC_PATH_PROG(XSLTPROC, xsltproc)
-                  fi
-                ],
-                [ENABLE_GJDOC=no])
+  AC_ARG_WITH([gjdoc],
+              AS_HELP_STRING([--with-gjdoc],
+                            [generate documentation using gjdoc (default is 
NO)]),
+              [if test "x${withval}" = xno; then
+                WITH_GJDOC=no;
+              elif test "x${withval}" = xyes -o "x{withval}" = x; then
+                WITH_GJDOC=yes;
+                AC_PATH_PROG(GJDOC, gjdoc, "no")
+                if test "x${JAY}" = xno; then
+                  AC_MSG_ERROR("jay executable not found");
+                fi
+              else
+                WITH_GJDOC=yes
+                GJDOC="${withval}"
+                AC_CHECK_FILE(${GJDOC}, AC_SUBST(GJDOC),
+                              AC_MSG_ERROR("Cannot use ${withval} as gjdoc 
executable since it doesn't exist"))
+              fi],
+              [WITH_GJDOC=no])
 
-  AM_CONDITIONAL(CREATE_API_DOCS, test "x${ENABLE_GJDOC}" = xyes)
+  AM_CONDITIONAL(CREATE_API_DOCS, test "x${WITH_GJDOC}" = xyes)
 ])
 
 dnl -----------------------------------------------------------
Index: configure.ac
===================================================================
RCS file: /cvsroot/classpath/classpath/configure.ac,v
retrieving revision 1.69
diff -u -r1.69 configure.ac
--- configure.ac        6 Jan 2005 17:43:58 -0000       1.69
+++ configure.ac        9 Jan 2005 13:06:09 -0000
@@ -366,7 +366,7 @@
 dnl -----------------------------------------------------------
 dnl Enable API documentation generation (disabled by default)
 dnl -----------------------------------------------------------
-CLASSPATH_ENABLE_GJDOC
+CLASSPATH_WITH_GJDOC
 
 dnl -----------------------------------------------------------
 dnl Whether to use jay to regenerate parsers.
Index: INSTALL
===================================================================
RCS file: /cvsroot/classpath/classpath/INSTALL,v
retrieving revision 1.25
diff -u -r1.25 INSTALL
--- INSTALL     6 Jan 2005 17:43:58 -0000       1.25
+++ INSTALL     9 Jan 2005 13:06:09 -0000
@@ -81,6 +81,7 @@
                           any compiler warning into a compilation failure
                           default=no
   --enable-xmlj           compile native libxml/xslt library default=no
+  --with-gjdoc           generate documentation using gjdoc default=no
   --with-jay              Regenerate the parsers with jay must be given the
                           path to the jay executable
 
Index: NEWS
===================================================================
RCS file: /cvsroot/classpath/classpath/NEWS,v
retrieving revision 1.66
diff -u -r1.66 NEWS
--- NEWS        7 Jan 2005 15:08:22 -0000       1.66
+++ NEWS        9 Jan 2005 13:06:09 -0000
@@ -5,6 +5,8 @@
   methods with non-native implementations. VM implementors are encouraged
   to provide more efficient versions.
 * VMRuntime.nativeLoad() now takes an additional ClassLoader parameter.
+* Full documentation for all classes can be generated (again) by using
+  the --with-gjdoc configure option.
 
 New in release 0.13 (Jan 6, 2005)
 
Index: doc/api/Makefile.am
===================================================================
RCS file: /cvsroot/classpath/classpath/doc/api/Makefile.am,v
retrieving revision 1.12
diff -u -r1.12 Makefile.am
--- doc/api/Makefile.am 3 Sep 2004 16:27:49 -0000       1.12
+++ doc/api/Makefile.am 9 Jan 2005 13:06:09 -0000
@@ -2,9 +2,9 @@
 noinst_DATA = html
 endif
 
-EXTRA_DIST = classpath-copyright.xml
+sourcepath = 
$(top_builddir):$(top_srcdir):$(top_srcdir)/vm/reference:$(top_srcdir)/external/w3c_dom:$(top_srcdir)/external/sax
 
-htmllist := $(shell $(FIND) html -print | grep -v "^html$$")
+classpathbox = "<span class='navbar item enabled'><a 
href='http://www.gnu.org/software/classpath'>GNU Classpath</a> ($(VERSION))"
 
 install-data-local:
        $(mkinstalldirs) $(DESTDIR)$(pkgdatadir)/api
@@ -27,47 +27,23 @@
           fi; \
         done
 
-#html: create_xml create_catalog create_html
 html: create_html
 
-core := $(shell cd $(top_srcdir) && $(FIND) java javax -type d ! -name CVS ! 
-name doc-files -print | tr '/' '.' | grep -v "java.awt.dnd.peer" | grep -v 
"java.awt.peer")
-
-# Just generate api doc for the core packages.
-# Adding the external ones takes a lot more time and we should reference
-# them anyway since we will place out own copyright notive on the generated
-# pages.
-packages = $(core)
-#| grep -v "^java\$" )
-date := $(shell $(DATE))
-
 clean:
-#      -rm -rf xml
-       -rm -rf html
-#      -rm -f gjdoccatalog.xml
-#      -rm -f gjdoc_rawcomment.cache
-
-#create_xml:
-#      -$(MKDIR) xml > /dev/null 2>&1
-#      $(GJDOC) -sourcepath \
-#              "$(top_srcdir):$(top_srcdir)/vm/reference" \
-#              -doclet gnu.classpath.tools.doclets.xmldoclet.Driver \
-#              -d xml $(packages) 
-#      -touch create_xml
-
-#create_catalog:
-#      $(XMLCATALOG) --noout --create \
-#              --add "public" \
-#              "-//GNU//DTD Gjdoc XML V0.1.1//EN" \
-#              http://www.gnu.org/software/cp-tools/dtd/gjdoc.dtd \
-#              --add "rewriteSystem" \
-#              http://www.gnu.org/software/cp-tools/dtd/ \
-#              file:///usr/local/share/gjdoc/dtd/ \
-#              gjdoccatalog.xml 
-#      -touch create_catalog
+       -rm -rf html create_html
 
 create_html:
        -$(MKDIR) html > /dev/null 2>&1
-       $(GJDOC) -sourcepath "$(top_srcdir):$(top_srcdir)/vm/reference" \
-       -d html -bottomnote "$(srcdir)/classpath-copyright.xml" \
-       $(packages)
-       -touch create_html
+       $(GJDOC) -public -use \
+       -sourcepath "$(sourcepath)" \
+       -encoding UTF-8 \
+       -breakiterator \
+       -licensetext \
+       -linksource \
+       -splitindex \
+       -d html \
+       -doctitle "GNU Classpath $(VERSION)" \
+       -windowtitle "GNU Classpath $(VERSION) Documentation" \
+       -header $(classpathbox) -footer $(classpathbox) \
+       -subpackages java:javax:org
+       touch create_html
Index: doc/api/classpath-copyright.xml
===================================================================
RCS file: doc/api/classpath-copyright.xml
diff -N doc/api/classpath-copyright.xml
--- doc/api/classpath-copyright.xml     17 Aug 2003 20:43:26 -0000      1.2
+++ /dev/null   1 Jan 1970 00:00:00 -0000
@@ -1,5 +0,0 @@
-<div class="footer">
-Copyright (C) 2003 Free Software Foundation, Inc.<br />
-See <a href="http://www.gnu.org/software/classpath/";>
-http://www.gnu.org/software/classpath/
-</a>.<hr /></div>

signature.asc
Description: This is a digitally signed message part