obtained gcc-4.6.4.tar.bz2 from upstream website;upstream

verified gcc-4.6.4.tar.bz2.sig;
imported gcc-4.6.4 source tree from verified upstream tarball.

downloading a git-generated archive based on the 'upstream' tag
should provide you with a source tree that is binary identical
to the one extracted from the above tarball.

if you have obtained the source via the command 'git clone',
however, do note that line-endings of files in your working
directory might differ from line-endings of the respective
files in the upstream repository.

25 files changed, 25711 insertions, 0 deletions

diff --git a/libjava/classpath/doc/.cvsignore b/libjava/classpath/doc/.cvsignore
new file mode 100644
index 000000000..1c4ea81e2
--- /dev/null
+++ b/libjava/classpath/doc/.cvsignore
@@ -0,0 +1,13 @@
+Makefile
+Makefile.in
+*.info
+*.aux
+*.cp
+*.dvi
+*.fn
+*.ky
+*.log
+*.pg
+*.toc
+*.tp
+*.vr
diff --git a/libjava/classpath/doc/Makefile.am b/libjava/classpath/doc/Makefile.am
new file mode 100644
index 000000000..a5f19b7e5
--- /dev/null
+++ b/libjava/classpath/doc/Makefile.am
@@ -0,0 +1,137 @@
+SUBDIRS = api
+
+EXTRA_DIST = README.jaxp texi2pod.pl $(man_MANS)
+
+## GCJ LOCAL: we don't want to install all of Classpath's info files.
+## info_TEXINFOS = cp-hacking.texinfo cp-vmintegration.texinfo cp-tools.texinfo
+TEXINFO_TEX = ../../gcc/doc/include/texinfo.tex
+info_TEXINFOS = cp-tools.texinfo
+
+.texinfo.dvi:
+	texi2dvi $<
+
+.dvi.ps:
+	dvips -o $@ $<
+
+docs: cp-hacking.ps cp-vmintegration.ps cp-tools.ps $(TOOLS_MANFILES)
+
+man_MANS = $(TOOLS_MANFILES)
+TOOLS_MANFILES = \
+	gappletviewer.1 \
+	gjar.1 \
+	gjarsigner.1 \
+	gjavah.1 \
+	gcjh.1 \
+	gkeytool.1 \
+	gnative2ascii.1 \
+	gorbd.1 \
+	grmid.1 \
+	grmiregistry.1 \
+	gserialver.1 \
+	gtnameserv.1 \
+	gjdoc.1
+
+POD2MAN = pod2man --center="GNU" --release="$(VERSION)" --date=$(shell sed -n '1s/ .*//p' <$(srcdir)/../ChangeLog)
+TEXI2POD = perl $(srcdir)/texi2pod.pl
+STAMP = echo timestamp >
+
+.pod.1:
+	$(STAMP) $@
+	-($(POD2MAN) --section=1 $< > $(@).T$$$$ && \
+		mv -f $(@).T$$$$ $@) || \
+		(rm -f $(@).T$$$$ && exit 1)
+
+.INTERMEDIATE: gappletviewer.pod gjarsigner.pod gjar.pod gjavah.pod \
+	gkeytool.pod gnative2ascii.pod gorbd.pod grmid.pod grmiregistry.pod \
+	gserialver.pod gtnameserv.pod gcjh.pod gjdoc.pod
+
+gappletviewer.pod: $(srcdir)/cp-tools.texinfo
+	-$(TEXI2POD) -D gappletviewer < $< > $@
+
+gjarsigner.pod: $(srcdir)/cp-tools.texinfo
+	-$(TEXI2POD) -D gjarsigner < $< > $@
+
+gjar.pod: $(srcdir)/cp-tools.texinfo
+	-$(TEXI2POD) -D gjar < $< > $@
+
+gcjh.pod: $(srcdir)/cp-tools.texinfo
+	-$(TEXI2POD) -D gcjh < $< > $@
+
+gjavah.pod: $(srcdir)/cp-tools.texinfo
+	-$(TEXI2POD) -D gjavah < $< > $@
+
+# hack around the cross references and the enumeration
+gkeytool.pod: $(srcdir)/cp-tools.texinfo
+	-$(TEXI2POD) -D gkeytool < $< \
+	  | sed -e 's/^For more details.*/See I<Common Options> for more details./' \
+	    -e 's/1\.<\([^>]*\)>/- \1/' \
+		> $@
+
+gnative2ascii.pod: $(srcdir)/cp-tools.texinfo
+	-$(TEXI2POD) -D gnative2ascii < $< > $@
+
+gorbd.pod: $(srcdir)/cp-tools.texinfo
+	-$(TEXI2POD) -D gorbd < $< > $@
+
+grmid.pod: $(srcdir)/cp-tools.texinfo
+	-$(TEXI2POD) -D grmid < $< > $@
+
+grmiregistry.pod: $(srcdir)/cp-tools.texinfo
+	-$(TEXI2POD) -D grmiregistry < $< > $@
+
+gserialver.pod: $(srcdir)/cp-tools.texinfo
+	-$(TEXI2POD) -D gserialver < $< > $@
+
+gtnameserv.pod: $(srcdir)/cp-tools.texinfo
+	-$(TEXI2POD) -D gtnameserv < $< > $@
+
+gjdoc.pod: $(srcdir)/cp-tools.texinfo
+	-$(TEXI2POD) -D gjdoc < $< > $@
+
+# GCJ LOCAL CHANGE
+#CLEANFILES = $(TOOLS_MANFILES)
+
+# GCJ LOCAL CHANGE
+# The following commands allow us to release tarballs with the man pages
+# and info documentation prebuilt.  This feature is enabled via 
+# --enable-generated-files-in-srcdir in the configure script.
+
+if GENINSRC
+STAMP_GENINSRC = stamp-geninsrc
+else
+STAMP_GENINSRC =
+endif
+
+all-local: $(STAMP_GENINSRC) 
+
+stamp-geninsrc: $(TOOLS_MANFILES) cp-tools.info
+	-cp -p gappletviewer.1 $(srcdir)/gappletviewer.1
+	-cp -p gjar.1 $(srcdir)/gjar.1
+	-cp -p gjarsigner.1 $(srcdir)/gjarsigner.1
+	-cp -p gjavah.1 $(srcdir)/gjavah.1
+	-cp -p gjdoc.1 $(srcdir)/gjdoc.1
+	-cp -p gkeytool.1 $(srcdir)/gkeytool.1
+	-cp -p gnative2ascii.1 $(srcdir)/gnative2ascii.1
+	-cp -p gorbd.1 $(srcdir)/gorbd.1
+	-cp -p grmid.1 $(srcdir)/grmid.1
+	-cp -p grmiregistry.1 $(srcdir)/grmiregistry.1
+	-cp -p gserialver.1 $(srcdir)/gserialver.1
+	-cp -p gtnameserv.1 $(srcdir)/gtnameserv.1
+	-cp -p cp-tools.info $(srcdir)/cp-tools.info
+	touch $@
+
+CLEANFILES = stamp-geninsrc cp-tools.info
+MAINTAINERCLEANFILES = \
+		$(srcdir)/gappletviewer.1 \
+		$(srcdir)/gjar.1 \
+		$(srcdir)/gjarsigner.1 \
+		$(srcdir)/gjavah.1 \
+		$(srcdir)/gjdoc.1 \
+		$(srcdir)/gkeytool.1 \
+		$(srcdir)/gnative2ascii.1 \
+		$(srcdir)/gorbd.1 \
+		$(srcdir)/grmid.1 \
+		$(srcdir)/grmiregistry.1 \
+		$(srcdir)/gserialver.1 \
+		$(srcdir)/gtnameserv.1 \
+		$(srcdir)/cp-tools.info
diff --git a/libjava/classpath/doc/Makefile.in b/libjava/classpath/doc/Makefile.in
new file mode 100644
index 000000000..781f601f2
--- /dev/null
+++ b/libjava/classpath/doc/Makefile.in
@@ -0,0 +1,1015 @@
+# Makefile.in generated by automake 1.11.1 from Makefile.am.
+# @configure_input@
+
+# Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
+# 2003, 2004, 2005, 2006, 2007, 2008, 2009  Free Software Foundation,
+# Inc.
+# This Makefile.in is free software; the Free Software Foundation
+# gives unlimited permission to copy and/or distribute it,
+# with or without modifications, as long as this notice is preserved.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY, to the extent permitted by law; without
+# even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+# PARTICULAR PURPOSE.
+
+@SET_MAKE@
+VPATH = @srcdir@
+pkgdatadir = $(datadir)/@PACKAGE@
+pkgincludedir = $(includedir)/@PACKAGE@
+pkglibdir = $(libdir)/@PACKAGE@
+pkglibexecdir = $(libexecdir)/@PACKAGE@
+am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd
+install_sh_DATA = $(install_sh) -c -m 644
+install_sh_PROGRAM = $(install_sh) -c
+install_sh_SCRIPT = $(install_sh) -c
+INSTALL_HEADER = $(INSTALL_DATA)
+transform = $(program_transform_name)
+NORMAL_INSTALL = :
+PRE_INSTALL = :
+POST_INSTALL = :
+NORMAL_UNINSTALL = :
+PRE_UNINSTALL = :
+POST_UNINSTALL = :
+build_triplet = @build@
+host_triplet = @host@
+target_triplet = @target@
+subdir = doc
+DIST_COMMON = $(srcdir)/Makefile.in $(srcdir)/Makefile.am
+ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
+am__aclocal_m4_deps = $(top_srcdir)/../../config/depstand.m4 \
+	$(top_srcdir)/../../config/lead-dot.m4 \
+	$(top_srcdir)/../../config/lib-ld.m4 \
+	$(top_srcdir)/../../config/lib-link.m4 \
+	$(top_srcdir)/../../config/lib-prefix.m4 \
+	$(top_srcdir)/../../config/multi.m4 \
+	$(top_srcdir)/../../config/no-executables.m4 \
+	$(top_srcdir)/../../config/override.m4 \
+	$(top_srcdir)/../../libtool.m4 \
+	$(top_srcdir)/../../ltoptions.m4 \
+	$(top_srcdir)/../../ltsugar.m4 \
+	$(top_srcdir)/../../ltversion.m4 \
+	$(top_srcdir)/../../lt~obsolete.m4 \
+	$(top_srcdir)/m4/ac_prog_antlr.m4 \
+	$(top_srcdir)/m4/ac_prog_java.m4 \
+	$(top_srcdir)/m4/ac_prog_java_works.m4 \
+	$(top_srcdir)/m4/ac_prog_javac.m4 \
+	$(top_srcdir)/m4/ac_prog_javac_works.m4 \
+	$(top_srcdir)/m4/acattribute.m4 $(top_srcdir)/m4/accross.m4 \
+	$(top_srcdir)/m4/acinclude.m4 \
+	$(top_srcdir)/m4/ax_create_stdint_h.m4 \
+	$(top_srcdir)/m4/ax_func_which_gethostbyname_r.m4 \
+	$(top_srcdir)/m4/gcc_attribute.m4 $(top_srcdir)/m4/iconv.m4 \
+	$(top_srcdir)/m4/pkg.m4 $(top_srcdir)/configure.ac
+am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \
+	$(ACLOCAL_M4)
+mkinstalldirs = $(SHELL) $(top_srcdir)/../../mkinstalldirs
+CONFIG_HEADER = $(top_builddir)/include/config.h
+CONFIG_CLEAN_FILES =
+CONFIG_CLEAN_VPATH_FILES =
+SOURCES =
+INFO_DEPS = cp-tools.info
+am__TEXINFO_TEX_DIR = $(srcdir)/../../gcc/doc/include
+DVIS = cp-tools.dvi
+PDFS = cp-tools.pdf
+PSS = cp-tools.ps
+HTMLS = cp-tools.html
+TEXINFOS = cp-tools.texinfo
+TEXI2DVI = texi2dvi
+TEXI2PDF = $(TEXI2DVI) --pdf --batch
+MAKEINFOHTML = $(MAKEINFO) --html
+AM_MAKEINFOHTMLFLAGS = $(AM_MAKEINFOFLAGS)
+DVIPS = dvips
+RECURSIVE_TARGETS = all-recursive check-recursive dvi-recursive \
+	html-recursive info-recursive install-data-recursive \
+	install-dvi-recursive install-exec-recursive \
+	install-html-recursive install-info-recursive \
+	install-pdf-recursive install-ps-recursive install-recursive \
+	installcheck-recursive installdirs-recursive pdf-recursive \
+	ps-recursive uninstall-recursive
+am__installdirs = "$(DESTDIR)$(infodir)" "$(DESTDIR)$(man1dir)"
+am__vpath_adj_setup = srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`;
+am__vpath_adj = case $$p in \
+    $(srcdir)/*) f=`echo "$$p" | sed "s|^$$srcdirstrip/||"`;; \
+    *) f=$$p;; \
+  esac;
+am__strip_dir = f=`echo $$p | sed -e 's|^.*/||'`;
+am__install_max = 40
+am__nobase_strip_setup = \
+  srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*|]/\\\\&/g'`
+am__nobase_strip = \
+  for p in $$list; do echo "$$p"; done | sed -e "s|$$srcdirstrip/||"
+am__nobase_list = $(am__nobase_strip_setup); \
+  for p in $$list; do echo "$$p $$p"; done | \
+  sed "s| $$srcdirstrip/| |;"' / .*\//!s/ .*/ ./; s,\( .*\)/[^/]*$$,\1,' | \
+  $(AWK) 'BEGIN { files["."] = "" } { files[$$2] = files[$$2] " " $$1; \
+    if (++n[$$2] == $(am__install_max)) \
+      { print $$2, files[$$2]; n[$$2] = 0; files[$$2] = "" } } \
+    END { for (dir in files) print dir, files[dir] }'
+am__base_list = \
+  sed '$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;s/\n/ /g' | \
+  sed '$$!N;$$!N;$$!N;$$!N;s/\n/ /g'
+man1dir = $(mandir)/man1
+NROFF = nroff
+MANS = $(man_MANS)
+RECURSIVE_CLEAN_TARGETS = mostlyclean-recursive clean-recursive	\
+  distclean-recursive maintainer-clean-recursive
+AM_RECURSIVE_TARGETS = $(RECURSIVE_TARGETS:-recursive=) \
+	$(RECURSIVE_CLEAN_TARGETS:-recursive=) tags TAGS ctags CTAGS
+ETAGS = etags
+CTAGS = ctags
+DIST_SUBDIRS = $(SUBDIRS)
+ACLOCAL = @ACLOCAL@
+AMTAR = @AMTAR@
+ANTLR = @ANTLR@
+ANTLR_JAR = @ANTLR_JAR@
+AR = @AR@
+AUTOCONF = @AUTOCONF@
+AUTOHEADER = @AUTOHEADER@
+AUTOMAKE = @AUTOMAKE@
+AWK = @AWK@
+CAIRO_CFLAGS = @CAIRO_CFLAGS@
+CAIRO_LIBS = @CAIRO_LIBS@
+CC = @CC@
+CCDEPMODE = @CCDEPMODE@
+CFLAGS = @CFLAGS@
+CLASSPATH_CONVENIENCE = @CLASSPATH_CONVENIENCE@
+CLASSPATH_INCLUDES = @CLASSPATH_INCLUDES@
+CLASSPATH_MODULE = @CLASSPATH_MODULE@
+COLLECTIONS_PREFIX = @COLLECTIONS_PREFIX@
+CP = @CP@
+CPP = @CPP@
+CPPFLAGS = @CPPFLAGS@
+CXX = @CXX@
+CXXCPP = @CXXCPP@
+CXXDEPMODE = @CXXDEPMODE@
+CXXFLAGS = @CXXFLAGS@
+CYGPATH_W = @CYGPATH_W@
+DATE = @DATE@
+DEFAULT_PREFS_PEER = @DEFAULT_PREFS_PEER@
+DEFS = @DEFS@
+DEPDIR = @DEPDIR@
+DSYMUTIL = @DSYMUTIL@
+DUMPBIN = @DUMPBIN@
+ECHO_C = @ECHO_C@
+ECHO_N = @ECHO_N@
+ECHO_T = @ECHO_T@
+ECJ_JAR = @ECJ_JAR@
+EGREP = @EGREP@
+ERROR_CFLAGS = @ERROR_CFLAGS@
+EXAMPLESDIR = @EXAMPLESDIR@
+EXEEXT = @EXEEXT@
+EXTRA_CFLAGS = @EXTRA_CFLAGS@
+FGREP = @FGREP@
+FIND = @FIND@
+FREETYPE2_CFLAGS = @FREETYPE2_CFLAGS@
+FREETYPE2_LIBS = @FREETYPE2_LIBS@
+GCONF_CFLAGS = @GCONF_CFLAGS@
+GCONF_LIBS = @GCONF_LIBS@
+GDK_CFLAGS = @GDK_CFLAGS@
+GDK_LIBS = @GDK_LIBS@
+GJDOC = @GJDOC@
+GLIB_CFLAGS = @GLIB_CFLAGS@
+GLIB_LIBS = @GLIB_LIBS@
+GMP_CFLAGS = @GMP_CFLAGS@
+GMP_LIBS = @GMP_LIBS@
+GREP = @GREP@
+GSTREAMER_BASE_CFLAGS = @GSTREAMER_BASE_CFLAGS@
+GSTREAMER_BASE_LIBS = @GSTREAMER_BASE_LIBS@
+GSTREAMER_CFLAGS = @GSTREAMER_CFLAGS@
+GSTREAMER_FILE_READER = @GSTREAMER_FILE_READER@
+GSTREAMER_LIBS = @GSTREAMER_LIBS@
+GSTREAMER_MIXER_PROVIDER = @GSTREAMER_MIXER_PROVIDER@
+GSTREAMER_PLUGINS_BASE_CFLAGS = @GSTREAMER_PLUGINS_BASE_CFLAGS@
+GSTREAMER_PLUGINS_BASE_LIBS = @GSTREAMER_PLUGINS_BASE_LIBS@
+GST_PLUGIN_LDFLAGS = @GST_PLUGIN_LDFLAGS@
+GTK_CFLAGS = @GTK_CFLAGS@
+GTK_LIBS = @GTK_LIBS@
+INIT_LOAD_LIBRARY = @INIT_LOAD_LIBRARY@
+INSTALL = @INSTALL@
+INSTALL_DATA = @INSTALL_DATA@
+INSTALL_PROGRAM = @INSTALL_PROGRAM@
+INSTALL_SCRIPT = @INSTALL_SCRIPT@
+INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@
+JAR = @JAR@
+JAVA = @JAVA@
+JAVAC = @JAVAC@
+JAVAC_IS_GCJ = @JAVAC_IS_GCJ@
+JAVAC_MEM_OPT = @JAVAC_MEM_OPT@
+JAVA_LANG_SYSTEM_EXPLICIT_INITIALIZATION = @JAVA_LANG_SYSTEM_EXPLICIT_INITIALIZATION@
+JAY = @JAY@
+JAY_SKELETON = @JAY_SKELETON@
+LD = @LD@
+LDFLAGS = @LDFLAGS@
+LIBDEBUG = @LIBDEBUG@
+LIBICONV = @LIBICONV@
+LIBMAGIC = @LIBMAGIC@
+LIBOBJS = @LIBOBJS@
+LIBS = @LIBS@
+LIBTOOL = @LIBTOOL@
+LIBVERSION = @LIBVERSION@
+LIPO = @LIPO@
+LN_S = @LN_S@
+LTLIBICONV = @LTLIBICONV@
+LTLIBOBJS = @LTLIBOBJS@
+MAINT = @MAINT@
+MAKEINFO = @MAKEINFO@
+MKDIR = @MKDIR@
+MKDIR_P = @MKDIR_P@
+MOC = @MOC@
+MOZILLA_CFLAGS = @MOZILLA_CFLAGS@
+MOZILLA_LIBS = @MOZILLA_LIBS@
+NM = @NM@
+NMEDIT = @NMEDIT@
+OBJDUMP = @OBJDUMP@
+OBJEXT = @OBJEXT@
+OTOOL = @OTOOL@
+OTOOL64 = @OTOOL64@
+PACKAGE = @PACKAGE@
+PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@
+PACKAGE_NAME = @PACKAGE_NAME@
+PACKAGE_STRING = @PACKAGE_STRING@
+PACKAGE_TARNAME = @PACKAGE_TARNAME@
+PACKAGE_URL = @PACKAGE_URL@
+PACKAGE_VERSION = @PACKAGE_VERSION@
+PANGOFT2_CFLAGS = @PANGOFT2_CFLAGS@
+PANGOFT2_LIBS = @PANGOFT2_LIBS@
+PATH_SEPARATOR = @PATH_SEPARATOR@
+PATH_TO_ESCHER = @PATH_TO_ESCHER@
+PATH_TO_GLIBJ_ZIP = @PATH_TO_GLIBJ_ZIP@
+PERL = @PERL@
+PKG_CONFIG = @PKG_CONFIG@
+PLUGIN_DIR = @PLUGIN_DIR@
+QT_CFLAGS = @QT_CFLAGS@
+QT_LIBS = @QT_LIBS@
+RANLIB = @RANLIB@
+REMOVE = @REMOVE@
+SED = @SED@
+SET_MAKE = @SET_MAKE@
+SHELL = @SHELL@
+STRICT_WARNING_CFLAGS = @STRICT_WARNING_CFLAGS@
+STRIP = @STRIP@
+TOOLSDIR = @TOOLSDIR@
+USER_JAVAH = @USER_JAVAH@
+VERSION = @VERSION@
+WANT_NATIVE_BIG_INTEGER = @WANT_NATIVE_BIG_INTEGER@
+WARNING_CFLAGS = @WARNING_CFLAGS@
+XMKMF = @XMKMF@
+XML_CFLAGS = @XML_CFLAGS@
+XML_LIBS = @XML_LIBS@
+XSLT_CFLAGS = @XSLT_CFLAGS@
+XSLT_LIBS = @XSLT_LIBS@
+XTEST_LIBS = @XTEST_LIBS@
+X_CFLAGS = @X_CFLAGS@
+X_EXTRA_LIBS = @X_EXTRA_LIBS@
+X_LIBS = @X_LIBS@
+X_PRE_LIBS = @X_PRE_LIBS@
+ZIP = @ZIP@
+abs_builddir = @abs_builddir@
+abs_srcdir = @abs_srcdir@
+abs_top_builddir = @abs_top_builddir@
+abs_top_srcdir = @abs_top_srcdir@
+ac_ct_ANTLR = @ac_ct_ANTLR@
+ac_ct_CC = @ac_ct_CC@
+ac_ct_CXX = @ac_ct_CXX@
+ac_ct_DUMPBIN = @ac_ct_DUMPBIN@
+am__include = @am__include@
+am__leading_dot = @am__leading_dot@
+am__quote = @am__quote@
+am__tar = @am__tar@
+am__untar = @am__untar@
+bindir = @bindir@
+build = @build@
+build_alias = @build_alias@
+build_cpu = @build_cpu@
+build_os = @build_os@
+build_vendor = @build_vendor@
+builddir = @builddir@
+datadir = @datadir@
+datarootdir = @datarootdir@
+default_toolkit = @default_toolkit@
+docdir = @docdir@
+dvidir = @dvidir@
+exec_prefix = @exec_prefix@
+glibjdir = @glibjdir@
+host = @host@
+host_alias = @host_alias@
+host_cpu = @host_cpu@
+host_os = @host_os@
+host_vendor = @host_vendor@
+htmldir = @htmldir@
+includedir = @includedir@
+infodir = @infodir@
+install_sh = @install_sh@
+libdir = @libdir@
+libexecdir = @libexecdir@
+localedir = @localedir@
+localstatedir = @localstatedir@
+mandir = @mandir@
+mkdir_p = @mkdir_p@
+multi_basedir = @multi_basedir@
+nativeexeclibdir = @nativeexeclibdir@
+oldincludedir = @oldincludedir@
+pdfdir = @pdfdir@
+prefix = @prefix@
+program_transform_name = @program_transform_name@
+psdir = @psdir@
+sbindir = @sbindir@
+sharedstatedir = @sharedstatedir@
+srcdir = @srcdir@
+sysconfdir = @sysconfdir@
+target = @target@
+target_alias = @target_alias@
+target_cpu = @target_cpu@
+target_os = @target_os@
+target_vendor = @target_vendor@
+toolexeclibdir = @toolexeclibdir@
+top_build_prefix = @top_build_prefix@
+top_builddir = @top_builddir@
+top_srcdir = @top_srcdir@
+uudecode = @uudecode@
+vm_classes = @vm_classes@
+SUBDIRS = api
+EXTRA_DIST = README.jaxp texi2pod.pl $(man_MANS)
+TEXINFO_TEX = ../../gcc/doc/include/texinfo.tex
+info_TEXINFOS = cp-tools.texinfo
+man_MANS = $(TOOLS_MANFILES)
+TOOLS_MANFILES = \
+	gappletviewer.1 \
+	gjar.1 \
+	gjarsigner.1 \
+	gjavah.1 \
+	gcjh.1 \
+	gkeytool.1 \
+	gnative2ascii.1 \
+	gorbd.1 \
+	grmid.1 \
+	grmiregistry.1 \
+	gserialver.1 \
+	gtnameserv.1 \
+	gjdoc.1
+
+POD2MAN = pod2man --center="GNU" --release="$(VERSION)" --date=$(shell sed -n '1s/ .*//p' <$(srcdir)/../ChangeLog)
+TEXI2POD = perl $(srcdir)/texi2pod.pl
+STAMP = echo timestamp >
+@GENINSRC_FALSE@STAMP_GENINSRC = 
+
+# GCJ LOCAL CHANGE
+#CLEANFILES = $(TOOLS_MANFILES)
+
+# GCJ LOCAL CHANGE
+# The following commands allow us to release tarballs with the man pages
+# and info documentation prebuilt.  This feature is enabled via 
+# --enable-generated-files-in-srcdir in the configure script.
+@GENINSRC_TRUE@STAMP_GENINSRC = stamp-geninsrc
+CLEANFILES = stamp-geninsrc cp-tools.info
+MAINTAINERCLEANFILES = \
+		$(srcdir)/gappletviewer.1 \
+		$(srcdir)/gjar.1 \
+		$(srcdir)/gjarsigner.1 \
+		$(srcdir)/gjavah.1 \
+		$(srcdir)/gjdoc.1 \
+		$(srcdir)/gkeytool.1 \
+		$(srcdir)/gnative2ascii.1 \
+		$(srcdir)/gorbd.1 \
+		$(srcdir)/grmid.1 \
+		$(srcdir)/grmiregistry.1 \
+		$(srcdir)/gserialver.1 \
+		$(srcdir)/gtnameserv.1 \
+		$(srcdir)/cp-tools.info
+
+all: all-recursive
+
+.SUFFIXES:
+.SUFFIXES: .1 .dvi .pod .ps .texinfo
+$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am  $(am__configure_deps)
+	@for dep in $?; do \
+	  case '$(am__configure_deps)' in \
+	    *$$dep*) \
+	      ( cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh ) \
+	        && { if test -f $@; then exit 0; else break; fi; }; \
+	      exit 1;; \
+	  esac; \
+	done; \
+	echo ' cd $(top_srcdir) && $(AUTOMAKE) --gnu doc/Makefile'; \
+	$(am__cd) $(top_srcdir) && \
+	  $(AUTOMAKE) --gnu doc/Makefile
+.PRECIOUS: Makefile
+Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status
+	@case '$?' in \
+	  *config.status*) \
+	    cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \
+	  *) \
+	    echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \
+	    cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \
+	esac;
+
+$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES)
+	cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
+
+$(top_srcdir)/configure: @MAINTAINER_MODE_TRUE@ $(am__configure_deps)
+	cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
+$(ACLOCAL_M4): @MAINTAINER_MODE_TRUE@ $(am__aclocal_m4_deps)
+	cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
+$(am__aclocal_m4_deps):
+
+mostlyclean-libtool:
+	-rm -f *.lo
+
+clean-libtool:
+	-rm -rf .libs _libs
+
+cp-tools.info: cp-tools.texinfo 
+	restore=: && backupdir="$(am__leading_dot)am$$$$" && \
+	rm -rf $$backupdir && mkdir $$backupdir && \
+	if ($(MAKEINFO) --version) >/dev/null 2>&1; then \
+	  for f in $@ $@-[0-9] $@-[0-9][0-9] $(@:.info=).i[0-9] $(@:.info=).i[0-9][0-9]; do \
+	    if test -f $$f; then mv $$f $$backupdir; restore=mv; else :; fi; \
+	  done; \
+	else :; fi && \
+	if $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \
+	 -o $@ `test -f 'cp-tools.texinfo' || echo '$(srcdir)/'`cp-tools.texinfo; \
+	then \
+	  rc=0; \
+	else \
+	  rc=$$?; \
+	  $$restore $$backupdir/* `echo "./$@" | sed 's|[^/]*$$||'`; \
+	fi; \
+	rm -rf $$backupdir; exit $$rc
+
+cp-tools.dvi: cp-tools.texinfo  
+	TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \
+	MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \
+	$(TEXI2DVI) -o $@ `test -f 'cp-tools.texinfo' || echo '$(srcdir)/'`cp-tools.texinfo
+
+cp-tools.pdf: cp-tools.texinfo  
+	TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \
+	MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \
+	$(TEXI2PDF) -o $@ `test -f 'cp-tools.texinfo' || echo '$(srcdir)/'`cp-tools.texinfo
+
+cp-tools.html: cp-tools.texinfo  
+	rm -rf $(@:.html=.htp)
+	if $(MAKEINFOHTML) $(AM_MAKEINFOHTMLFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \
+	 -o $(@:.html=.htp) `test -f 'cp-tools.texinfo' || echo '$(srcdir)/'`cp-tools.texinfo; \
+	then \
+	  rm -rf $@; \
+	  if test ! -d $(@:.html=.htp) && test -d $(@:.html=); then \
+	    mv $(@:.html=) $@; else mv $(@:.html=.htp) $@; fi; \
+	else \
+	  if test ! -d $(@:.html=.htp) && test -d $(@:.html=); then \
+	    rm -rf $(@:.html=); else rm -Rf $(@:.html=.htp) $@; fi; \
+	  exit 1; \
+	fi
+
+uninstall-dvi-am:
+	@$(NORMAL_UNINSTALL)
+	@list='$(DVIS)'; test -n "$(dvidir)" || list=; \
+	for p in $$list; do \
+	  $(am__strip_dir) \
+	  echo " rm -f '$(DESTDIR)$(dvidir)/$$f'"; \
+	  rm -f "$(DESTDIR)$(dvidir)/$$f"; \
+	done
+
+uninstall-html-am:
+	@$(NORMAL_UNINSTALL)
+	@list='$(HTMLS)'; test -n "$(htmldir)" || list=; \
+	for p in $$list; do \
+	  $(am__strip_dir) \
+	  echo " rm -rf '$(DESTDIR)$(htmldir)/$$f'"; \
+	  rm -rf "$(DESTDIR)$(htmldir)/$$f"; \
+	done
+
+uninstall-info-am:
+	@$(PRE_UNINSTALL)
+	@if test -d '$(DESTDIR)$(infodir)' && \
+	    (install-info --version && \
+	     install-info --version 2>&1 | sed 1q | grep -i -v debian) >/dev/null 2>&1; then \
+	  list='$(INFO_DEPS)'; \
+	  for file in $$list; do \
+	    relfile=`echo "$$file" | sed 's|^.*/||'`; \
+	    echo " install-info --info-dir='$(DESTDIR)$(infodir)' --remove '$(DESTDIR)$(infodir)/$$relfile'"; \
+	    if install-info --info-dir="$(DESTDIR)$(infodir)" --remove "$(DESTDIR)$(infodir)/$$relfile"; \
+	    then :; else test ! -f "$(DESTDIR)$(infodir)/$$relfile" || exit 1; fi; \
+	  done; \
+	else :; fi
+	@$(NORMAL_UNINSTALL)
+	@list='$(INFO_DEPS)'; \
+	for file in $$list; do \
+	  relfile=`echo "$$file" | sed 's|^.*/||'`; \
+	  relfile_i=`echo "$$relfile" | sed 's|\.info$$||;s|$$|.i|'`; \
+	  (if test -d "$(DESTDIR)$(infodir)" && cd "$(DESTDIR)$(infodir)"; then \
+	     echo " cd '$(DESTDIR)$(infodir)' && rm -f $$relfile $$relfile-[0-9] $$relfile-[0-9][0-9] $$relfile_i[0-9] $$relfile_i[0-9][0-9]"; \
+	     rm -f $$relfile $$relfile-[0-9] $$relfile-[0-9][0-9] $$relfile_i[0-9] $$relfile_i[0-9][0-9]; \
+	   else :; fi); \
+	done
+
+uninstall-pdf-am:
+	@$(NORMAL_UNINSTALL)
+	@list='$(PDFS)'; test -n "$(pdfdir)" || list=; \
+	for p in $$list; do \
+	  $(am__strip_dir) \
+	  echo " rm -f '$(DESTDIR)$(pdfdir)/$$f'"; \
+	  rm -f "$(DESTDIR)$(pdfdir)/$$f"; \
+	done
+
+uninstall-ps-am:
+	@$(NORMAL_UNINSTALL)
+	@list='$(PSS)'; test -n "$(psdir)" || list=; \
+	for p in $$list; do \
+	  $(am__strip_dir) \
+	  echo " rm -f '$(DESTDIR)$(psdir)/$$f'"; \
+	  rm -f "$(DESTDIR)$(psdir)/$$f"; \
+	done
+
+dist-info: $(INFO_DEPS)
+	@srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \
+	list='$(INFO_DEPS)'; \
+	for base in $$list; do \
+	  case $$base in \
+	    $(srcdir)/*) base=`echo "$$base" | sed "s|^$$srcdirstrip/||"`;; \
+	  esac; \
+	  if test -f $$base; then d=.; else d=$(srcdir); fi; \
+	  base_i=`echo "$$base" | sed 's|\.info$$||;s|$$|.i|'`; \
+	  for file in $$d/$$base $$d/$$base-[0-9] $$d/$$base-[0-9][0-9] $$d/$$base_i[0-9] $$d/$$base_i[0-9][0-9]; do \
+	    if test -f $$file; then \
+	      relfile=`expr "$$file" : "$$d/\(.*\)"`; \
+	      test -f "$(distdir)/$$relfile" || \
+		cp -p $$file "$(distdir)/$$relfile"; \
+	    else :; fi; \
+	  done; \
+	done
+
+mostlyclean-aminfo:
+	-rm -rf cp-tools.aux cp-tools.cp cp-tools.cps cp-tools.fn cp-tools.fns \
+	  cp-tools.ky cp-tools.kys cp-tools.log cp-tools.pg \
+	  cp-tools.pgs cp-tools.tmp cp-tools.toc cp-tools.tp \
+	  cp-tools.tps cp-tools.vr cp-tools.vrs
+
+clean-aminfo:
+	-test -z "cp-tools.dvi cp-tools.pdf cp-tools.ps cp-tools.html" \
+	|| rm -rf cp-tools.dvi cp-tools.pdf cp-tools.ps cp-tools.html
+
+maintainer-clean-aminfo:
+	@list='$(INFO_DEPS)'; for i in $$list; do \
+	  i_i=`echo "$$i" | sed 's|\.info$$||;s|$$|.i|'`; \
+	  echo " rm -f $$i $$i-[0-9] $$i-[0-9][0-9] $$i_i[0-9] $$i_i[0-9][0-9]"; \
+	  rm -f $$i $$i-[0-9] $$i-[0-9][0-9] $$i_i[0-9] $$i_i[0-9][0-9]; \
+	done
+install-man1: $(man_MANS)
+	@$(NORMAL_INSTALL)
+	test -z "$(man1dir)" || $(MKDIR_P) "$(DESTDIR)$(man1dir)"
+	@list=''; test -n "$(man1dir)" || exit 0; \
+	{ for i in $$list; do echo "$$i"; done; \
+	l2='$(man_MANS)'; for i in $$l2; do echo "$$i"; done | \
+	  sed -n '/\.1[a-z]*$$/p'; \
+	} | while read p; do \
+	  if test -f $$p; then d=; else d="$(srcdir)/"; fi; \
+	  echo "$$d$$p"; echo "$$p"; \
+	done | \
+	sed -e 'n;s,.*/,,;p;h;s,.*\.,,;s,^[^1][0-9a-z]*$$,1,;x' \
+	      -e 's,\.[0-9a-z]*$$,,;$(transform);G;s,\n,.,' | \
+	sed 'N;N;s,\n, ,g' | { \
+	list=; while read file base inst; do \
+	  if test "$$base" = "$$inst"; then list="$$list $$file"; else \
+	    echo " $(INSTALL_DATA) '$$file' '$(DESTDIR)$(man1dir)/$$inst'"; \
+	    $(INSTALL_DATA) "$$file" "$(DESTDIR)$(man1dir)/$$inst" || exit $$?; \
+	  fi; \
+	done; \
+	for i in $$list; do echo "$$i"; done | $(am__base_list) | \
+	while read files; do \
+	  test -z "$$files" || { \
+	    echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(man1dir)'"; \
+	    $(INSTALL_DATA) $$files "$(DESTDIR)$(man1dir)" || exit $$?; }; \
+	done; }
+
+uninstall-man1:
+	@$(NORMAL_UNINSTALL)
+	@list=''; test -n "$(man1dir)" || exit 0; \
+	files=`{ for i in $$list; do echo "$$i"; done; \
+	l2='$(man_MANS)'; for i in $$l2; do echo "$$i"; done | \
+	  sed -n '/\.1[a-z]*$$/p'; \
+	} | sed -e 's,.*/,,;h;s,.*\.,,;s,^[^1][0-9a-z]*$$,1,;x' \
+	      -e 's,\.[0-9a-z]*$$,,;$(transform);G;s,\n,.,'`; \
+	test -z "$$files" || { \
+	  echo " ( cd '$(DESTDIR)$(man1dir)' && rm -f" $$files ")"; \
+	  cd "$(DESTDIR)$(man1dir)" && rm -f $$files; }
+
+# This directory's subdirectories are mostly independent; you can cd
+# into them and run `make' without going through this Makefile.
+# To change the values of `make' variables: instead of editing Makefiles,
+# (1) if the variable is set in `config.status', edit `config.status'
+#     (which will cause the Makefiles to be regenerated when you run `make');
+# (2) otherwise, pass the desired values on the `make' command line.
+$(RECURSIVE_TARGETS):
+	@fail= failcom='exit 1'; \
+	for f in x $$MAKEFLAGS; do \
+	  case $$f in \
+	    *=* | --[!k]*);; \
+	    *k*) failcom='fail=yes';; \
+	  esac; \
+	done; \
+	dot_seen=no; \
+	target=`echo $@ | sed s/-recursive//`; \
+	list='$(SUBDIRS)'; for subdir in $$list; do \
+	  echo "Making $$target in $$subdir"; \
+	  if test "$$subdir" = "."; then \
+	    dot_seen=yes; \
+	    local_target="$$target-am"; \
+	  else \
+	    local_target="$$target"; \
+	  fi; \
+	  ($(am__cd) $$subdir && $(MAKE) $(AM_MAKEFLAGS) $$local_target) \
+	  || eval $$failcom; \
+	done; \
+	if test "$$dot_seen" = "no"; then \
+	  $(MAKE) $(AM_MAKEFLAGS) "$$target-am" || exit 1; \
+	fi; test -z "$$fail"
+
+$(RECURSIVE_CLEAN_TARGETS):
+	@fail= failcom='exit 1'; \
+	for f in x $$MAKEFLAGS; do \
+	  case $$f in \
+	    *=* | --[!k]*);; \
+	    *k*) failcom='fail=yes';; \
+	  esac; \
+	done; \
+	dot_seen=no; \
+	case "$@" in \
+	  distclean-* | maintainer-clean-*) list='$(DIST_SUBDIRS)' ;; \
+	  *) list='$(SUBDIRS)' ;; \
+	esac; \
+	rev=''; for subdir in $$list; do \
+	  if test "$$subdir" = "."; then :; else \
+	    rev="$$subdir $$rev"; \
+	  fi; \
+	done; \
+	rev="$$rev ."; \
+	target=`echo $@ | sed s/-recursive//`; \
+	for subdir in $$rev; do \
+	  echo "Making $$target in $$subdir"; \
+	  if test "$$subdir" = "."; then \
+	    local_target="$$target-am"; \
+	  else \
+	    local_target="$$target"; \
+	  fi; \
+	  ($(am__cd) $$subdir && $(MAKE) $(AM_MAKEFLAGS) $$local_target) \
+	  || eval $$failcom; \
+	done && test -z "$$fail"
+tags-recursive:
+	list='$(SUBDIRS)'; for subdir in $$list; do \
+	  test "$$subdir" = . || ($(am__cd) $$subdir && $(MAKE) $(AM_MAKEFLAGS) tags); \
+	done
+ctags-recursive:
+	list='$(SUBDIRS)'; for subdir in $$list; do \
+	  test "$$subdir" = . || ($(am__cd) $$subdir && $(MAKE) $(AM_MAKEFLAGS) ctags); \
+	done
+
+ID: $(HEADERS) $(SOURCES) $(LISP) $(TAGS_FILES)
+	list='$(SOURCES) $(HEADERS) $(LISP) $(TAGS_FILES)'; \
+	unique=`for i in $$list; do \
+	    if test -f "$$i"; then echo $$i; else echo $(srcdir)/$$i; fi; \
+	  done | \
+	  $(AWK) '{ files[$$0] = 1; nonempty = 1; } \
+	      END { if (nonempty) { for (i in files) print i; }; }'`; \
+	mkid -fID $$unique
+tags: TAGS
+
+TAGS: tags-recursive $(HEADERS) $(SOURCES)  $(TAGS_DEPENDENCIES) \
+		$(TAGS_FILES) $(LISP)
+	set x; \
+	here=`pwd`; \
+	if ($(ETAGS) --etags-include --version) >/dev/null 2>&1; then \
+	  include_option=--etags-include; \
+	  empty_fix=.; \
+	else \
+	  include_option=--include; \
+	  empty_fix=; \
+	fi; \
+	list='$(SUBDIRS)'; for subdir in $$list; do \
+	  if test "$$subdir" = .; then :; else \
+	    test ! -f $$subdir/TAGS || \
+	      set "$$@" "$$include_option=$$here/$$subdir/TAGS"; \
+	  fi; \
+	done; \
+	list='$(SOURCES) $(HEADERS)  $(LISP) $(TAGS_FILES)'; \
+	unique=`for i in $$list; do \
+	    if test -f "$$i"; then echo $$i; else echo $(srcdir)/$$i; fi; \
+	  done | \
+	  $(AWK) '{ files[$$0] = 1; nonempty = 1; } \
+	      END { if (nonempty) { for (i in files) print i; }; }'`; \
+	shift; \
+	if test -z "$(ETAGS_ARGS)$$*$$unique"; then :; else \
+	  test -n "$$unique" || unique=$$empty_fix; \
+	  if test $$# -gt 0; then \
+	    $(ETAGS) $(ETAGSFLAGS) $(AM_ETAGSFLAGS) $(ETAGS_ARGS) \
+	      "$$@" $$unique; \
+	  else \
+	    $(ETAGS) $(ETAGSFLAGS) $(AM_ETAGSFLAGS) $(ETAGS_ARGS) \
+	      $$unique; \
+	  fi; \
+	fi
+ctags: CTAGS
+CTAGS: ctags-recursive $(HEADERS) $(SOURCES)  $(TAGS_DEPENDENCIES) \
+		$(TAGS_FILES) $(LISP)
+	list='$(SOURCES) $(HEADERS)  $(LISP) $(TAGS_FILES)'; \
+	unique=`for i in $$list; do \
+	    if test -f "$$i"; then echo $$i; else echo $(srcdir)/$$i; fi; \
+	  done | \
+	  $(AWK) '{ files[$$0] = 1; nonempty = 1; } \
+	      END { if (nonempty) { for (i in files) print i; }; }'`; \
+	test -z "$(CTAGS_ARGS)$$unique" \
+	  || $(CTAGS) $(CTAGSFLAGS) $(AM_CTAGSFLAGS) $(CTAGS_ARGS) \
+	     $$unique
+
+GTAGS:
+	here=`$(am__cd) $(top_builddir) && pwd` \
+	  && $(am__cd) $(top_srcdir) \
+	  && gtags -i $(GTAGS_ARGS) "$$here"
+
+distclean-tags:
+	-rm -f TAGS ID GTAGS GRTAGS GSYMS GPATH tags
+check-am: all-am
+check: check-recursive
+all-am: Makefile $(INFO_DEPS) $(MANS) all-local
+installdirs: installdirs-recursive
+installdirs-am:
+	for dir in "$(DESTDIR)$(infodir)" "$(DESTDIR)$(man1dir)"; do \
+	  test -z "$$dir" || $(MKDIR_P) "$$dir"; \
+	done
+install: install-recursive
+install-exec: install-exec-recursive
+install-data: install-data-recursive
+uninstall: uninstall-recursive
+
+install-am: all-am
+	@$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am
+
+installcheck: installcheck-recursive
+install-strip:
+	$(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \
+	  install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \
+	  `test -z '$(STRIP)' || \
+	    echo "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'"` install
+mostlyclean-generic:
+
+clean-generic:
+	-test -z "$(CLEANFILES)" || rm -f $(CLEANFILES)
+
+distclean-generic:
+	-test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES)
+	-test . = "$(srcdir)" || test -z "$(CONFIG_CLEAN_VPATH_FILES)" || rm -f $(CONFIG_CLEAN_VPATH_FILES)
+
+maintainer-clean-generic:
+	@echo "This command is intended for maintainers to use"
+	@echo "it deletes files that may require special tools to rebuild."
+	-test -z "$(MAINTAINERCLEANFILES)" || rm -f $(MAINTAINERCLEANFILES)
+clean: clean-recursive
+
+clean-am: clean-aminfo clean-generic clean-libtool mostlyclean-am
+
+distclean: distclean-recursive
+	-rm -f Makefile
+distclean-am: clean-am distclean-generic distclean-tags
+
+dvi: dvi-recursive
+
+dvi-am: $(DVIS)
+
+html: html-recursive
+
+html-am: $(HTMLS)
+
+info: info-recursive
+
+info-am: $(INFO_DEPS)
+
+install-data-am: install-info-am install-man
+
+install-dvi: install-dvi-recursive
+
+install-dvi-am: $(DVIS)
+	@$(NORMAL_INSTALL)
+	test -z "$(dvidir)" || $(MKDIR_P) "$(DESTDIR)$(dvidir)"
+	@list='$(DVIS)'; test -n "$(dvidir)" || list=; \
+	for p in $$list; do \
+	  if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \
+	  echo "$$d$$p"; \
+	done | $(am__base_list) | \
+	while read files; do \
+	  echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(dvidir)'"; \
+	  $(INSTALL_DATA) $$files "$(DESTDIR)$(dvidir)" || exit $$?; \
+	done
+install-exec-am:
+
+install-html: install-html-recursive
+
+install-html-am: $(HTMLS)
+	@$(NORMAL_INSTALL)
+	test -z "$(htmldir)" || $(MKDIR_P) "$(DESTDIR)$(htmldir)"
+	@list='$(HTMLS)'; list2=; test -n "$(htmldir)" || list=; \
+	for p in $$list; do \
+	  if test -f "$$p" || test -d "$$p"; then d=; else d="$(srcdir)/"; fi; \
+	  $(am__strip_dir) \
+	  if test -d "$$d$$p"; then \
+	    echo " $(MKDIR_P) '$(DESTDIR)$(htmldir)/$$f'"; \
+	    $(MKDIR_P) "$(DESTDIR)$(htmldir)/$$f" || exit 1; \
+	    echo " $(INSTALL_DATA) '$$d$$p'/* '$(DESTDIR)$(htmldir)/$$f'"; \
+	    $(INSTALL_DATA) "$$d$$p"/* "$(DESTDIR)$(htmldir)/$$f" || exit $$?; \
+	  else \
+	    list2="$$list2 $$d$$p"; \
+	  fi; \
+	done; \
+	test -z "$$list2" || { echo "$$list2" | $(am__base_list) | \
+	while read files; do \
+	  echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(htmldir)'"; \
+	  $(INSTALL_DATA) $$files "$(DESTDIR)$(htmldir)" || exit $$?; \
+	done; }
+install-info: install-info-recursive
+
+install-info-am: $(INFO_DEPS)
+	@$(NORMAL_INSTALL)
+	test -z "$(infodir)" || $(MKDIR_P) "$(DESTDIR)$(infodir)"
+	@srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \
+	list='$(INFO_DEPS)'; test -n "$(infodir)" || list=; \
+	for file in $$list; do \
+	  case $$file in \
+	    $(srcdir)/*) file=`echo "$$file" | sed "s|^$$srcdirstrip/||"`;; \
+	  esac; \
+	  if test -f $$file; then d=.; else d=$(srcdir); fi; \
+	  file_i=`echo "$$file" | sed 's|\.info$$||;s|$$|.i|'`; \
+	  for ifile in $$d/$$file $$d/$$file-[0-9] $$d/$$file-[0-9][0-9] \
+	               $$d/$$file_i[0-9] $$d/$$file_i[0-9][0-9] ; do \
+	    if test -f $$ifile; then \
+	      echo "$$ifile"; \
+	    else : ; fi; \
+	  done; \
+	done | $(am__base_list) | \
+	while read files; do \
+	  echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(infodir)'"; \
+	  $(INSTALL_DATA) $$files "$(DESTDIR)$(infodir)" || exit $$?; done
+	@$(POST_INSTALL)
+	@if (install-info --version && \
+	     install-info --version 2>&1 | sed 1q | grep -i -v debian) >/dev/null 2>&1; then \
+	  list='$(INFO_DEPS)'; test -n "$(infodir)" || list=; \
+	  for file in $$list; do \
+	    relfile=`echo "$$file" | sed 's|^.*/||'`; \
+	    echo " install-info --info-dir='$(DESTDIR)$(infodir)' '$(DESTDIR)$(infodir)/$$relfile'";\
+	    install-info --info-dir="$(DESTDIR)$(infodir)" "$(DESTDIR)$(infodir)/$$relfile" || :;\
+	  done; \
+	else : ; fi
+install-man: install-man1
+
+install-pdf: install-pdf-recursive
+
+install-pdf-am: $(PDFS)
+	@$(NORMAL_INSTALL)
+	test -z "$(pdfdir)" || $(MKDIR_P) "$(DESTDIR)$(pdfdir)"
+	@list='$(PDFS)'; test -n "$(pdfdir)" || list=; \
+	for p in $$list; do \
+	  if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \
+	  echo "$$d$$p"; \
+	done | $(am__base_list) | \
+	while read files; do \
+	  echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(pdfdir)'"; \
+	  $(INSTALL_DATA) $$files "$(DESTDIR)$(pdfdir)" || exit $$?; done
+install-ps: install-ps-recursive
+
+install-ps-am: $(PSS)
+	@$(NORMAL_INSTALL)
+	test -z "$(psdir)" || $(MKDIR_P) "$(DESTDIR)$(psdir)"
+	@list='$(PSS)'; test -n "$(psdir)" || list=; \
+	for p in $$list; do \
+	  if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \
+	  echo "$$d$$p"; \
+	done | $(am__base_list) | \
+	while read files; do \
+	  echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(psdir)'"; \
+	  $(INSTALL_DATA) $$files "$(DESTDIR)$(psdir)" || exit $$?; done
+installcheck-am:
+
+maintainer-clean: maintainer-clean-recursive
+	-rm -f Makefile
+maintainer-clean-am: distclean-am maintainer-clean-aminfo \
+	maintainer-clean-generic
+
+mostlyclean: mostlyclean-recursive
+
+mostlyclean-am: mostlyclean-aminfo mostlyclean-generic \
+	mostlyclean-libtool
+
+pdf: pdf-recursive
+
+pdf-am: $(PDFS)
+
+ps: ps-recursive
+
+ps-am: $(PSS)
+
+uninstall-am: uninstall-dvi-am uninstall-html-am uninstall-info-am \
+	uninstall-man uninstall-pdf-am uninstall-ps-am
+
+uninstall-man: uninstall-man1
+
+.MAKE: $(RECURSIVE_CLEAN_TARGETS) $(RECURSIVE_TARGETS) ctags-recursive \
+	install-am install-strip tags-recursive
+
+.PHONY: $(RECURSIVE_CLEAN_TARGETS) $(RECURSIVE_TARGETS) CTAGS GTAGS \
+	all all-am all-local check check-am clean clean-aminfo \
+	clean-generic clean-libtool ctags ctags-recursive dist-info \
+	distclean distclean-generic distclean-libtool distclean-tags \
+	dvi dvi-am html html-am info info-am install install-am \
+	install-data install-data-am install-dvi install-dvi-am \
+	install-exec install-exec-am install-html install-html-am \
+	install-info install-info-am install-man install-man1 \
+	install-pdf install-pdf-am install-ps install-ps-am \
+	install-strip installcheck installcheck-am installdirs \
+	installdirs-am maintainer-clean maintainer-clean-aminfo \
+	maintainer-clean-generic mostlyclean mostlyclean-aminfo \
+	mostlyclean-generic mostlyclean-libtool pdf pdf-am ps ps-am \
+	tags tags-recursive uninstall uninstall-am uninstall-dvi-am \
+	uninstall-html-am uninstall-info-am uninstall-man \
+	uninstall-man1 uninstall-pdf-am uninstall-ps-am
+
+
+.texinfo.dvi:
+	texi2dvi $<
+
+.dvi.ps:
+	dvips -o $@ $<
+
+docs: cp-hacking.ps cp-vmintegration.ps cp-tools.ps $(TOOLS_MANFILES)
+
+.pod.1:
+	$(STAMP) $@
+	-($(POD2MAN) --section=1 $< > $(@).T$$$$ && \
+		mv -f $(@).T$$$$ $@) || \
+		(rm -f $(@).T$$$$ && exit 1)
+
+.INTERMEDIATE: gappletviewer.pod gjarsigner.pod gjar.pod gjavah.pod \
+	gkeytool.pod gnative2ascii.pod gorbd.pod grmid.pod grmiregistry.pod \
+	gserialver.pod gtnameserv.pod gcjh.pod gjdoc.pod
+
+gappletviewer.pod: $(srcdir)/cp-tools.texinfo
+	-$(TEXI2POD) -D gappletviewer < $< > $@
+
+gjarsigner.pod: $(srcdir)/cp-tools.texinfo
+	-$(TEXI2POD) -D gjarsigner < $< > $@
+
+gjar.pod: $(srcdir)/cp-tools.texinfo
+	-$(TEXI2POD) -D gjar < $< > $@
+
+gcjh.pod: $(srcdir)/cp-tools.texinfo
+	-$(TEXI2POD) -D gcjh < $< > $@
+
+gjavah.pod: $(srcdir)/cp-tools.texinfo
+	-$(TEXI2POD) -D gjavah < $< > $@
+
+# hack around the cross references and the enumeration
+gkeytool.pod: $(srcdir)/cp-tools.texinfo
+	-$(TEXI2POD) -D gkeytool < $< \
+	  | sed -e 's/^For more details.*/See I<Common Options> for more details./' \
+	    -e 's/1\.<\([^>]*\)>/- \1/' \
+		> $@
+
+gnative2ascii.pod: $(srcdir)/cp-tools.texinfo
+	-$(TEXI2POD) -D gnative2ascii < $< > $@
+
+gorbd.pod: $(srcdir)/cp-tools.texinfo
+	-$(TEXI2POD) -D gorbd < $< > $@
+
+grmid.pod: $(srcdir)/cp-tools.texinfo
+	-$(TEXI2POD) -D grmid < $< > $@
+
+grmiregistry.pod: $(srcdir)/cp-tools.texinfo
+	-$(TEXI2POD) -D grmiregistry < $< > $@
+
+gserialver.pod: $(srcdir)/cp-tools.texinfo
+	-$(TEXI2POD) -D gserialver < $< > $@
+
+gtnameserv.pod: $(srcdir)/cp-tools.texinfo
+	-$(TEXI2POD) -D gtnameserv < $< > $@
+
+gjdoc.pod: $(srcdir)/cp-tools.texinfo
+	-$(TEXI2POD) -D gjdoc < $< > $@
+
+all-local: $(STAMP_GENINSRC) 
+
+stamp-geninsrc: $(TOOLS_MANFILES) cp-tools.info
+	-cp -p gappletviewer.1 $(srcdir)/gappletviewer.1
+	-cp -p gjar.1 $(srcdir)/gjar.1
+	-cp -p gjarsigner.1 $(srcdir)/gjarsigner.1
+	-cp -p gjavah.1 $(srcdir)/gjavah.1
+	-cp -p gjdoc.1 $(srcdir)/gjdoc.1
+	-cp -p gkeytool.1 $(srcdir)/gkeytool.1
+	-cp -p gnative2ascii.1 $(srcdir)/gnative2ascii.1
+	-cp -p gorbd.1 $(srcdir)/gorbd.1
+	-cp -p grmid.1 $(srcdir)/grmid.1
+	-cp -p grmiregistry.1 $(srcdir)/grmiregistry.1
+	-cp -p gserialver.1 $(srcdir)/gserialver.1
+	-cp -p gtnameserv.1 $(srcdir)/gtnameserv.1
+	-cp -p cp-tools.info $(srcdir)/cp-tools.info
+	touch $@
+
+# Tell versions [3.59,3.63) of GNU make to not export all variables.
+# Otherwise a system limit (for SysV at least) may be exceeded.
+.NOEXPORT:
diff --git a/libjava/classpath/doc/README.jaxp b/libjava/classpath/doc/README.jaxp
new file mode 100644
index 000000000..afafb083c
--- /dev/null
+++ b/libjava/classpath/doc/README.jaxp
@@ -0,0 +1,204 @@
+This file describes the jaxp (xml processing) implementation of GNU Classpath.
+GNU Classpath includes interfaces and implementations for basic XML processing
+in in the java programming language, some general purpose SAX2 utilities, and
+transformation.
+
+These classes used to be maintained as part of an external project GNU JAXP
+but are now integrated with the rest of the core class library provided by
+GNU Classpath.
+
+PACKAGES
+    
+. javax.xml.* ... JAXP 1.3 interfaces
+
+. gnu.xml.aelfred2.* ... SAX2 parser + validator
+. gnu.xml.dom.* ... DOM Level 3 Core, Traversal, XPath implementation
+. gnu.xml.dom.ls.* ... DOM Level 3 Load & Save implementation
+. gnu.xml.xpath.* ... JAXP XPath implementation
+. gnu.xml.transform.* ... JAXP XSL transformer implementation
+. gnu.xml.pipeline.* ... SAX2 event pipeline support
+. gnu.xml.stream.* ... StAX pull parser and SAX-over-StAX driver
+. gnu.xml.util.* ... various XML utility classes
+. gnu.xml.libxmlj.dom.* ... libxmlj DOM Level 3 Core and XPath
+. gnu.xml.libxmlj.sax.* ... libxmlj SAX parser
+. gnu.xml.libxmlj.transform.* ... libxmlj XSL transformer
+. gnu.xml.libxmlj.util.* ... libxmlj utility classes
+
+In the external directory you can find the following packages.
+They are not maintained as part of GNU Classpath, but are used by the
+classes in the above packages.
+
+. org.xml.sax.* ... SAX2 interfaces
+. org.w3c.dom.* ... DOM Level 3 interfaces
+. org.relaxng.datatype.* ... RELAX NG pluggable datatypes API
+
+CONFORMANCE
+
+    The primary test resources are at http://xmlconf.sourceforge.net
+    and include:
+
+    SAX2/XML conformance tests
+	That the "xml.testing.Driver" addresses the core XML 1.0
+	specification requirements, which closely correspond to the
+	functionality SAX1 provides.  The driver uses SAX2 APIs to
+	test that functionality It is used with a bugfixed version of
+	the NIST/OASIS XML conformance test cases.
+	
+	The AElfred2 parser is highly conformant, though it still takes
+	a few implementation shortcuts.  See its package documentation
+	for information about known XML conformance issues in AElfred2.
+
+	The primary issue is using Unicode character tables, rather than
+	those in the XML specification, for determining what names are
+	valid.  Most applications won't notice the difference, and this
+	solution is smaller and faster than the alternative.
+
+	For validation, a secondary issue is that issues relating to
+	entity modularity are not validated; they can't all be cleanly
+	layered.  For example, validity constraints related to standalone
+	declarations and PE nesting are not checked.
+
+        The current implementation has also been tested against Elliotte
+        Rusty Harold's SAXTest test suite (http://www.cafeconleche.org/SAXTest)
+        and achieves approximately 93% conformance to the SAX specification
+        according to these tests, higher than any other current Java parser.
+
+    SAX2
+	SAX2 API conformance currently has a minimal JUNIT (0.2) test suite,
+	which can be accessed at the xmlconf site listed above.  It does
+	not cover namespaces or LexicalHandler and Declhandler extensions
+	anywhere as exhaustively as the SAX1 level functionality is
+	tested by the "xml.testing.Driver".  However:
+
+	    - Applying the DOM unit tests to this implementation gives
+	      the LexicalHandler (comments, and boundaries of DTDs,
+	      CDATA sections, and general entities) a workout, and
+	      does the same for DeclHandler entity declarations.
+	    
+	    - The pipeline package's layered validator demands that
+	      element and attribute declarations are reported correctly.
+	
+	By those metrics, SAX2 conformance for AElfred2 is also strong. 
+    
+    DOM Level 3 Core Tests
+        The DOM implementation has been tested against the W3C DOM Level 3
+        Core conformance test suite (http://www.w3.org/DOM/Test/). Current
+        conformance according to these tests is 72.3%. Many of the test
+        failures are due to the fact that GNU JAXP does not currently
+        provide any W3C XML Schema support.
+
+    XSL transformation
+        The transformer and XPath implementation have been tested against
+        the OASIS XSLT and XPath TC test suite. Conformance against the
+        Xalan tests is currently 77%.
+
+
+libxmlj
+========================================================================
+
+libxmlj is an effort to create a 100% JAXP-compatible Java wrapper for
+libxml2 and libxslt. JAXP is the Java API for XML processing, libxml2
+is the XML C library for Gnome, and libxslt is the XSLT C library for
+Gnome.
+
+libxmlj currently supports most of the DOM Level 3 Core, Traversal, and
+XPath APIs, SAX2, and XSLT transformations. There is no W3C XML Schema
+support yet.
+
+libxmlj can parse and transform XML documents extremely quickly in
+comparison to Java-based JAXP implementations. DOM manipulations, however,
+involve JNI overhead, so the speed of DOM tree construction and traversal
+can be slower than the Java implementation.
+
+libxmlj is highly experimental, doesn't always conform to the DOM
+specification correctly, and may leak memory. Production use is not advised.
+
+The implementation can be found in gnu/xml/libxmlj and native/jni/xmlj.
+See the INSTALL file for the required versions of libxml2 and libxslt.
+configure --enable-xmlj will build it.
+
+Usage
+------------------------------------------------------------------------
+
+To enable the various GNU JAXP factories, set the following system properties
+(command-line version shown, but they can equally be set programmatically):
+
+  AElfred2:
+   -Djavax.xml.parsers.SAXParserFactory=gnu.xml.aelfred2.JAXPFactory
+
+  GNU DOM (using DOM Level 3 Load & Save):
+   -Djavax.xml.parsers.DocumentBuilderFactory=gnu.xml.dom.DomDocumentBuilderFactory
+
+  GNU DOM (using AElfred-only pipeline classes):
+   -Djavax.xml.parsers.DocumentBuilderFactory=gnu.xml.dom.JAXPFactory
+
+  GNU XSL transformer:
+   -Djavax.xml.transform.TransformerFactory=gnu.xml.transform.TransformerFactoryImpl
+
+  GNU StAX:
+   -Djavax.xml.stream.XMLEventFactory=gnu.xml.stream.XMLEventFactoryImpl
+   -Djavax.xml.stream.XMLInputFactory=gnu.xml.stream.XMLInputFactoryImpl
+   -Djavax.xml.stream.XMLOutputFactory=gnu.xml.stream.XMLOutputFactoryImpl
+
+  GNU SAX-over-StAX:
+   -Djavax.xml.parsers.SAXParserFactory=gnu.xml.stream.SAXParserFactory
+
+  libxmlj SAX:
+   -Djavax.xml.parsers.SAXParserFactory=gnu.xml.libxmlj.sax.GnomeSAXParserFactory
+
+  libxmlj DOM:
+   -Djavax.xml.parsers.DocumentBuilderFactory=gnu.xml.libxmlj.dom.GnomeDocumentBuilderFactory
+
+  libxmlj XSL transformer:
+   -Djavax.xml.transform.TransformerFactory=gnu.xml.libxmlj.transform.GnomeTransformerFactory
+
+When using libxmlj, the libxmlj shared library must be available.
+In general it is picked up by the runtime using GNU Classpath. If not you
+might want to try adding the directory where libxmlj.so is installed
+(by default ${prefix}/lib/classpath/) with ldconfig or specifying in the
+LD_LIBRARY_PATH environment variable. Additionally, you may need to specify
+the location of your shared libraries to the runtime environment using the
+java.library.path system property.
+
+Missing (libxmlj) Features
+------------------------------------------------------------------------ 
+
+See BUGS in native/jni/xmlj for known bugs in the libxmlj native bindings.
+
+This implementation should be thread-safe, but currently all
+transformation requests are queued via Java synchronization, which
+means that it effectively performs single-threaded. Long story short,
+both libxml2 and libxslt are not fully reentrant.  
+
+Update: it may be possible to make libxmlj thread-safe nonetheless
+using thread context variables.
+
+Update: thread context variables have been introduced. This is very
+untested though, libxmlj therefore still has the single thread
+bottleneck.
+
+
+Validation
+===================================================
+
+Pluggable datatypes
+---------------------------------------------------
+Validators should use the RELAX NG pluggable datatypes API to retrieve
+datatype (XML Schema simple type) implementations in a schema-neutral
+fashion. The following code demonstrates looking up a W3C XML Schema
+nonNegativeInteger datatype:
+
+  DatatypeLibrary xsd = DatatypeLibraryLoader
+    .createDatatypeLibrary(XMLConstants.W3C_XML_SCHEMA_NS_URI);
+  Datatype nonNegativeInteger = xsd.createDatatype("nonNegativeInteger");
+
+It is also possible to create new types by derivation. For instance,
+to create a datatype that will match a US ZIP code:
+
+  DatatypeBuilder b = xsd.createDatatypeBuilder("string");
+  b.addParameter("pattern", "(^[0-9]{5}$)|(^[0-9]{5}-[0-9]{4}$)");
+  Datatype zipCode = b.createDatatype();
+
+A datatype library implementation for XML Schema is provided; other
+library implementations may be added.
+
diff --git a/libjava/classpath/doc/api/.cvsignore b/libjava/classpath/doc/api/.cvsignore
new file mode 100644
index 000000000..282522db0
--- /dev/null
+++ b/libjava/classpath/doc/api/.cvsignore
@@ -0,0 +1,2 @@
+Makefile
+Makefile.in
diff --git a/libjava/classpath/doc/api/Makefile.am b/libjava/classpath/doc/api/Makefile.am
new file mode 100644
index 000000000..76b35c5f8
--- /dev/null
+++ b/libjava/classpath/doc/api/Makefile.am
@@ -0,0 +1,55 @@
+if CREATE_API_DOCS
+noinst_DATA = html
+endif
+
+sourcepath = $(top_builddir):$(top_srcdir):$(top_srcdir)/vm/reference:$(top_srcdir)/external/w3c_dom:$(top_srcdir)/external/sax:$(top_srcdir)/external/jsr166
+
+classpathbox = "<span class='logo'><a href='http://www.gnu.org/software/classpath' target='_top'>GNU Classpath</a> ($(VERSION))"
+
+if CREATE_API_DOCS
+install-data-local:
+	$(mkinstalldirs) $(DESTDIR)$(pkgdatadir)/api
+	@list='$(htmllist)'; for p in $$list; do \
+	  f="`echo $$p | sed -e 's|^.*/||'`"; \
+	  if test -f "$$p"; then \
+	    echo " $(INSTALL_DATA) $$p $(DESTDIR)$(pkgdatadir)/api/$$f"; \
+	    $(INSTALL_DATA) $$p $(DESTDIR)$(pkgdatadir)/api/$$f; \
+	  elif test -d "$$p"; then \
+	    $(mkinstalldirs) $(DESTDIR)$(pkgdatadir)/api/$$f; \
+          fi; \
+        done
+
+uninstall-local:
+	@list='$(htmllist)'; for p in $$list; do \
+	  f="`echo $$p | sed -e 's|^.*/||'`"; \
+	  if test -f "$$p"; then \
+	    echo " rm -f $(DESTDIR)$(pkgdatadir)/api/$$f"; \
+	    rm -f $(DESTDIR)$(pkgdatadir)/api/$$f; \
+          fi; \
+        done
+endif
+
+html: create_html
+
+clean-local:
+	-rm -rf html create_html gjdoc_rawcomment.cache
+
+create_html:
+	-$(MKDIR) html > /dev/null 2>&1
+if CREATE_API_DOCS
+	$(GJDOC) \
+	-use \
+	-sourcepath "$(sourcepath)" \
+	-encoding UTF-8 \
+	-breakiterator \
+	-licensetext \
+	-linksource \
+	-splitindex \
+	-validhtml \
+	-d html \
+	-doctitle "GNU Classpath $(VERSION)" \
+	-windowtitle "GNU Classpath $(VERSION) Documentation" \
+	-header $(classpathbox) -footer $(classpathbox) \
+	-subpackages java:javax:org
+	touch create_html
+endif
diff --git a/libjava/classpath/doc/api/Makefile.in b/libjava/classpath/doc/api/Makefile.in
new file mode 100644
index 000000000..b5c7becf1
--- /dev/null
+++ b/libjava/classpath/doc/api/Makefile.in
@@ -0,0 +1,487 @@
+# Makefile.in generated by automake 1.11.1 from Makefile.am.
+# @configure_input@
+
+# Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
+# 2003, 2004, 2005, 2006, 2007, 2008, 2009  Free Software Foundation,
+# Inc.
+# This Makefile.in is free software; the Free Software Foundation
+# gives unlimited permission to copy and/or distribute it,
+# with or without modifications, as long as this notice is preserved.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY, to the extent permitted by law; without
+# even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+# PARTICULAR PURPOSE.
+
+@SET_MAKE@
+
+VPATH = @srcdir@
+pkgdatadir = $(datadir)/@PACKAGE@
+pkgincludedir = $(includedir)/@PACKAGE@
+pkglibdir = $(libdir)/@PACKAGE@
+pkglibexecdir = $(libexecdir)/@PACKAGE@
+am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd
+install_sh_DATA = $(install_sh) -c -m 644
+install_sh_PROGRAM = $(install_sh) -c
+install_sh_SCRIPT = $(install_sh) -c
+INSTALL_HEADER = $(INSTALL_DATA)
+transform = $(program_transform_name)
+NORMAL_INSTALL = :
+PRE_INSTALL = :
+POST_INSTALL = :
+NORMAL_UNINSTALL = :
+PRE_UNINSTALL = :
+POST_UNINSTALL = :
+build_triplet = @build@
+host_triplet = @host@
+target_triplet = @target@
+subdir = doc/api
+DIST_COMMON = $(srcdir)/Makefile.in $(srcdir)/Makefile.am
+ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
+am__aclocal_m4_deps = $(top_srcdir)/../../config/depstand.m4 \
+	$(top_srcdir)/../../config/lead-dot.m4 \
+	$(top_srcdir)/../../config/lib-ld.m4 \
+	$(top_srcdir)/../../config/lib-link.m4 \
+	$(top_srcdir)/../../config/lib-prefix.m4 \
+	$(top_srcdir)/../../config/multi.m4 \
+	$(top_srcdir)/../../config/no-executables.m4 \
+	$(top_srcdir)/../../config/override.m4 \
+	$(top_srcdir)/../../libtool.m4 \
+	$(top_srcdir)/../../ltoptions.m4 \
+	$(top_srcdir)/../../ltsugar.m4 \
+	$(top_srcdir)/../../ltversion.m4 \
+	$(top_srcdir)/../../lt~obsolete.m4 \
+	$(top_srcdir)/m4/ac_prog_antlr.m4 \
+	$(top_srcdir)/m4/ac_prog_java.m4 \
+	$(top_srcdir)/m4/ac_prog_java_works.m4 \
+	$(top_srcdir)/m4/ac_prog_javac.m4 \
+	$(top_srcdir)/m4/ac_prog_javac_works.m4 \
+	$(top_srcdir)/m4/acattribute.m4 $(top_srcdir)/m4/accross.m4 \
+	$(top_srcdir)/m4/acinclude.m4 \
+	$(top_srcdir)/m4/ax_create_stdint_h.m4 \
+	$(top_srcdir)/m4/ax_func_which_gethostbyname_r.m4 \
+	$(top_srcdir)/m4/gcc_attribute.m4 $(top_srcdir)/m4/iconv.m4 \
+	$(top_srcdir)/m4/pkg.m4 $(top_srcdir)/configure.ac
+am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \
+	$(ACLOCAL_M4)
+mkinstalldirs = $(SHELL) $(top_srcdir)/../../mkinstalldirs
+CONFIG_HEADER = $(top_builddir)/include/config.h
+CONFIG_CLEAN_FILES =
+CONFIG_CLEAN_VPATH_FILES =
+SOURCES =
+DATA = $(noinst_DATA)
+ACLOCAL = @ACLOCAL@
+AMTAR = @AMTAR@
+ANTLR = @ANTLR@
+ANTLR_JAR = @ANTLR_JAR@
+AR = @AR@
+AUTOCONF = @AUTOCONF@
+AUTOHEADER = @AUTOHEADER@
+AUTOMAKE = @AUTOMAKE@
+AWK = @AWK@
+CAIRO_CFLAGS = @CAIRO_CFLAGS@
+CAIRO_LIBS = @CAIRO_LIBS@
+CC = @CC@
+CCDEPMODE = @CCDEPMODE@
+CFLAGS = @CFLAGS@
+CLASSPATH_CONVENIENCE = @CLASSPATH_CONVENIENCE@
+CLASSPATH_INCLUDES = @CLASSPATH_INCLUDES@
+CLASSPATH_MODULE = @CLASSPATH_MODULE@
+COLLECTIONS_PREFIX = @COLLECTIONS_PREFIX@
+CP = @CP@
+CPP = @CPP@
+CPPFLAGS = @CPPFLAGS@
+CXX = @CXX@
+CXXCPP = @CXXCPP@
+CXXDEPMODE = @CXXDEPMODE@
+CXXFLAGS = @CXXFLAGS@
+CYGPATH_W = @CYGPATH_W@
+DATE = @DATE@
+DEFAULT_PREFS_PEER = @DEFAULT_PREFS_PEER@
+DEFS = @DEFS@
+DEPDIR = @DEPDIR@
+DSYMUTIL = @DSYMUTIL@
+DUMPBIN = @DUMPBIN@
+ECHO_C = @ECHO_C@
+ECHO_N = @ECHO_N@
+ECHO_T = @ECHO_T@
+ECJ_JAR = @ECJ_JAR@
+EGREP = @EGREP@
+ERROR_CFLAGS = @ERROR_CFLAGS@
+EXAMPLESDIR = @EXAMPLESDIR@
+EXEEXT = @EXEEXT@
+EXTRA_CFLAGS = @EXTRA_CFLAGS@
+FGREP = @FGREP@
+FIND = @FIND@
+FREETYPE2_CFLAGS = @FREETYPE2_CFLAGS@
+FREETYPE2_LIBS = @FREETYPE2_LIBS@
+GCONF_CFLAGS = @GCONF_CFLAGS@
+GCONF_LIBS = @GCONF_LIBS@
+GDK_CFLAGS = @GDK_CFLAGS@
+GDK_LIBS = @GDK_LIBS@
+GJDOC = @GJDOC@
+GLIB_CFLAGS = @GLIB_CFLAGS@
+GLIB_LIBS = @GLIB_LIBS@
+GMP_CFLAGS = @GMP_CFLAGS@
+GMP_LIBS = @GMP_LIBS@
+GREP = @GREP@
+GSTREAMER_BASE_CFLAGS = @GSTREAMER_BASE_CFLAGS@
+GSTREAMER_BASE_LIBS = @GSTREAMER_BASE_LIBS@
+GSTREAMER_CFLAGS = @GSTREAMER_CFLAGS@
+GSTREAMER_FILE_READER = @GSTREAMER_FILE_READER@
+GSTREAMER_LIBS = @GSTREAMER_LIBS@
+GSTREAMER_MIXER_PROVIDER = @GSTREAMER_MIXER_PROVIDER@
+GSTREAMER_PLUGINS_BASE_CFLAGS = @GSTREAMER_PLUGINS_BASE_CFLAGS@
+GSTREAMER_PLUGINS_BASE_LIBS = @GSTREAMER_PLUGINS_BASE_LIBS@
+GST_PLUGIN_LDFLAGS = @GST_PLUGIN_LDFLAGS@
+GTK_CFLAGS = @GTK_CFLAGS@
+GTK_LIBS = @GTK_LIBS@
+INIT_LOAD_LIBRARY = @INIT_LOAD_LIBRARY@
+INSTALL = @INSTALL@
+INSTALL_DATA = @INSTALL_DATA@
+INSTALL_PROGRAM = @INSTALL_PROGRAM@
+INSTALL_SCRIPT = @INSTALL_SCRIPT@
+INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@
+JAR = @JAR@
+JAVA = @JAVA@
+JAVAC = @JAVAC@
+JAVAC_IS_GCJ = @JAVAC_IS_GCJ@
+JAVAC_MEM_OPT = @JAVAC_MEM_OPT@
+JAVA_LANG_SYSTEM_EXPLICIT_INITIALIZATION = @JAVA_LANG_SYSTEM_EXPLICIT_INITIALIZATION@
+JAY = @JAY@
+JAY_SKELETON = @JAY_SKELETON@
+LD = @LD@
+LDFLAGS = @LDFLAGS@
+LIBDEBUG = @LIBDEBUG@
+LIBICONV = @LIBICONV@
+LIBMAGIC = @LIBMAGIC@
+LIBOBJS = @LIBOBJS@
+LIBS = @LIBS@
+LIBTOOL = @LIBTOOL@
+LIBVERSION = @LIBVERSION@
+LIPO = @LIPO@
+LN_S = @LN_S@
+LTLIBICONV = @LTLIBICONV@
+LTLIBOBJS = @LTLIBOBJS@
+MAINT = @MAINT@
+MAKEINFO = @MAKEINFO@
+MKDIR = @MKDIR@
+MKDIR_P = @MKDIR_P@
+MOC = @MOC@
+MOZILLA_CFLAGS = @MOZILLA_CFLAGS@
+MOZILLA_LIBS = @MOZILLA_LIBS@
+NM = @NM@
+NMEDIT = @NMEDIT@
+OBJDUMP = @OBJDUMP@
+OBJEXT = @OBJEXT@
+OTOOL = @OTOOL@
+OTOOL64 = @OTOOL64@
+PACKAGE = @PACKAGE@
+PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@
+PACKAGE_NAME = @PACKAGE_NAME@
+PACKAGE_STRING = @PACKAGE_STRING@
+PACKAGE_TARNAME = @PACKAGE_TARNAME@
+PACKAGE_URL = @PACKAGE_URL@
+PACKAGE_VERSION = @PACKAGE_VERSION@
+PANGOFT2_CFLAGS = @PANGOFT2_CFLAGS@
+PANGOFT2_LIBS = @PANGOFT2_LIBS@
+PATH_SEPARATOR = @PATH_SEPARATOR@
+PATH_TO_ESCHER = @PATH_TO_ESCHER@
+PATH_TO_GLIBJ_ZIP = @PATH_TO_GLIBJ_ZIP@
+PERL = @PERL@
+PKG_CONFIG = @PKG_CONFIG@
+PLUGIN_DIR = @PLUGIN_DIR@
+QT_CFLAGS = @QT_CFLAGS@
+QT_LIBS = @QT_LIBS@
+RANLIB = @RANLIB@
+REMOVE = @REMOVE@
+SED = @SED@
+SET_MAKE = @SET_MAKE@
+SHELL = @SHELL@
+STRICT_WARNING_CFLAGS = @STRICT_WARNING_CFLAGS@
+STRIP = @STRIP@
+TOOLSDIR = @TOOLSDIR@
+USER_JAVAH = @USER_JAVAH@
+VERSION = @VERSION@
+WANT_NATIVE_BIG_INTEGER = @WANT_NATIVE_BIG_INTEGER@
+WARNING_CFLAGS = @WARNING_CFLAGS@
+XMKMF = @XMKMF@
+XML_CFLAGS = @XML_CFLAGS@
+XML_LIBS = @XML_LIBS@
+XSLT_CFLAGS = @XSLT_CFLAGS@
+XSLT_LIBS = @XSLT_LIBS@
+XTEST_LIBS = @XTEST_LIBS@
+X_CFLAGS = @X_CFLAGS@
+X_EXTRA_LIBS = @X_EXTRA_LIBS@
+X_LIBS = @X_LIBS@
+X_PRE_LIBS = @X_PRE_LIBS@
+ZIP = @ZIP@
+abs_builddir = @abs_builddir@
+abs_srcdir = @abs_srcdir@
+abs_top_builddir = @abs_top_builddir@
+abs_top_srcdir = @abs_top_srcdir@
+ac_ct_ANTLR = @ac_ct_ANTLR@
+ac_ct_CC = @ac_ct_CC@
+ac_ct_CXX = @ac_ct_CXX@
+ac_ct_DUMPBIN = @ac_ct_DUMPBIN@
+am__include = @am__include@
+am__leading_dot = @am__leading_dot@
+am__quote = @am__quote@
+am__tar = @am__tar@
+am__untar = @am__untar@
+bindir = @bindir@
+build = @build@
+build_alias = @build_alias@
+build_cpu = @build_cpu@
+build_os = @build_os@
+build_vendor = @build_vendor@
+builddir = @builddir@
+datadir = @datadir@
+datarootdir = @datarootdir@
+default_toolkit = @default_toolkit@
+docdir = @docdir@
+dvidir = @dvidir@
+exec_prefix = @exec_prefix@
+glibjdir = @glibjdir@
+host = @host@
+host_alias = @host_alias@
+host_cpu = @host_cpu@
+host_os = @host_os@
+host_vendor = @host_vendor@
+htmldir = @htmldir@
+includedir = @includedir@
+infodir = @infodir@
+install_sh = @install_sh@
+libdir = @libdir@
+libexecdir = @libexecdir@
+localedir = @localedir@
+localstatedir = @localstatedir@
+mandir = @mandir@
+mkdir_p = @mkdir_p@
+multi_basedir = @multi_basedir@
+nativeexeclibdir = @nativeexeclibdir@
+oldincludedir = @oldincludedir@
+pdfdir = @pdfdir@
+prefix = @prefix@
+program_transform_name = @program_transform_name@
+psdir = @psdir@
+sbindir = @sbindir@
+sharedstatedir = @sharedstatedir@
+srcdir = @srcdir@
+sysconfdir = @sysconfdir@
+target = @target@
+target_alias = @target_alias@
+target_cpu = @target_cpu@
+target_os = @target_os@
+target_vendor = @target_vendor@
+toolexeclibdir = @toolexeclibdir@
+top_build_prefix = @top_build_prefix@
+top_builddir = @top_builddir@
+top_srcdir = @top_srcdir@
+uudecode = @uudecode@
+vm_classes = @vm_classes@
+@CREATE_API_DOCS_TRUE@noinst_DATA = html
+sourcepath = $(top_builddir):$(top_srcdir):$(top_srcdir)/vm/reference:$(top_srcdir)/external/w3c_dom:$(top_srcdir)/external/sax:$(top_srcdir)/external/jsr166
+classpathbox = "<span class='logo'><a href='http://www.gnu.org/software/classpath' target='_top'>GNU Classpath</a> ($(VERSION))"
+all: all-am
+
+.SUFFIXES:
+$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am  $(am__configure_deps)
+	@for dep in $?; do \
+	  case '$(am__configure_deps)' in \
+	    *$$dep*) \
+	      ( cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh ) \
+	        && { if test -f $@; then exit 0; else break; fi; }; \
+	      exit 1;; \
+	  esac; \
+	done; \
+	echo ' cd $(top_srcdir) && $(AUTOMAKE) --gnu doc/api/Makefile'; \
+	$(am__cd) $(top_srcdir) && \
+	  $(AUTOMAKE) --gnu doc/api/Makefile
+.PRECIOUS: Makefile
+Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status
+	@case '$?' in \
+	  *config.status*) \
+	    cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \
+	  *) \
+	    echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \
+	    cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \
+	esac;
+
+$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES)
+	cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
+
+$(top_srcdir)/configure: @MAINTAINER_MODE_TRUE@ $(am__configure_deps)
+	cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
+$(ACLOCAL_M4): @MAINTAINER_MODE_TRUE@ $(am__aclocal_m4_deps)
+	cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
+$(am__aclocal_m4_deps):
+
+mostlyclean-libtool:
+	-rm -f *.lo
+
+clean-libtool:
+	-rm -rf .libs _libs
+tags: TAGS
+TAGS:
+
+ctags: CTAGS
+CTAGS:
+
+check-am: all-am
+check: check-am
+all-am: Makefile $(DATA)
+installdirs:
+install: install-am
+install-exec: install-exec-am
+install-data: install-data-am
+uninstall: uninstall-am
+
+install-am: all-am
+	@$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am
+
+installcheck: installcheck-am
+install-strip:
+	$(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \
+	  install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \
+	  `test -z '$(STRIP)' || \
+	    echo "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'"` install
+mostlyclean-generic:
+
+clean-generic:
+
+distclean-generic:
+	-test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES)
+	-test . = "$(srcdir)" || test -z "$(CONFIG_CLEAN_VPATH_FILES)" || rm -f $(CONFIG_CLEAN_VPATH_FILES)
+
+maintainer-clean-generic:
+	@echo "This command is intended for maintainers to use"
+	@echo "it deletes files that may require special tools to rebuild."
+@CREATE_API_DOCS_FALSE@uninstall-local:
+@CREATE_API_DOCS_FALSE@install-data-local:
+clean: clean-am
+
+clean-am: clean-generic clean-libtool clean-local mostlyclean-am
+
+distclean: distclean-am
+	-rm -f Makefile
+distclean-am: clean-am distclean-generic
+
+dvi: dvi-am
+
+dvi-am:
+
+html-am:
+
+info: info-am
+
+info-am:
+
+install-data-am: install-data-local
+
+install-dvi: install-dvi-am
+
+install-dvi-am:
+
+install-exec-am:
+
+install-html: install-html-am
+
+install-html-am:
+
+install-info: install-info-am
+
+install-info-am:
+
+install-man:
+
+install-pdf: install-pdf-am
+
+install-pdf-am:
+
+install-ps: install-ps-am
+
+install-ps-am:
+
+installcheck-am:
+
+maintainer-clean: maintainer-clean-am
+	-rm -f Makefile
+maintainer-clean-am: distclean-am maintainer-clean-generic
+
+mostlyclean: mostlyclean-am
+
+mostlyclean-am: mostlyclean-generic mostlyclean-libtool
+
+pdf: pdf-am
+
+pdf-am:
+
+ps: ps-am
+
+ps-am:
+
+uninstall-am: uninstall-local
+
+.MAKE: install-am install-strip
+
+.PHONY: all all-am check check-am clean clean-generic clean-libtool \
+	clean-local distclean distclean-generic distclean-libtool dvi \
+	dvi-am html html-am info info-am install install-am \
+	install-data install-data-am install-data-local install-dvi \
+	install-dvi-am install-exec install-exec-am install-html \
+	install-html-am install-info install-info-am install-man \
+	install-pdf install-pdf-am install-ps install-ps-am \
+	install-strip installcheck installcheck-am installdirs \
+	maintainer-clean maintainer-clean-generic mostlyclean \
+	mostlyclean-generic mostlyclean-libtool pdf pdf-am ps ps-am \
+	uninstall uninstall-am uninstall-local
+
+
+@CREATE_API_DOCS_TRUE@install-data-local:
+@CREATE_API_DOCS_TRUE@	$(mkinstalldirs) $(DESTDIR)$(pkgdatadir)/api
+@CREATE_API_DOCS_TRUE@	@list='$(htmllist)'; for p in $$list; do \
+@CREATE_API_DOCS_TRUE@	  f="`echo $$p | sed -e 's|^.*/||'`"; \
+@CREATE_API_DOCS_TRUE@	  if test -f "$$p"; then \
+@CREATE_API_DOCS_TRUE@	    echo " $(INSTALL_DATA) $$p $(DESTDIR)$(pkgdatadir)/api/$$f"; \
+@CREATE_API_DOCS_TRUE@	    $(INSTALL_DATA) $$p $(DESTDIR)$(pkgdatadir)/api/$$f; \
+@CREATE_API_DOCS_TRUE@	  elif test -d "$$p"; then \
+@CREATE_API_DOCS_TRUE@	    $(mkinstalldirs) $(DESTDIR)$(pkgdatadir)/api/$$f; \
+@CREATE_API_DOCS_TRUE@          fi; \
+@CREATE_API_DOCS_TRUE@        done
+
+@CREATE_API_DOCS_TRUE@uninstall-local:
+@CREATE_API_DOCS_TRUE@	@list='$(htmllist)'; for p in $$list; do \
+@CREATE_API_DOCS_TRUE@	  f="`echo $$p | sed -e 's|^.*/||'`"; \
+@CREATE_API_DOCS_TRUE@	  if test -f "$$p"; then \
+@CREATE_API_DOCS_TRUE@	    echo " rm -f $(DESTDIR)$(pkgdatadir)/api/$$f"; \
+@CREATE_API_DOCS_TRUE@	    rm -f $(DESTDIR)$(pkgdatadir)/api/$$f; \
+@CREATE_API_DOCS_TRUE@          fi; \
+@CREATE_API_DOCS_TRUE@        done
+
+html: create_html
+
+clean-local:
+	-rm -rf html create_html gjdoc_rawcomment.cache
+
+create_html:
+	-$(MKDIR) html > /dev/null 2>&1
+@CREATE_API_DOCS_TRUE@	$(GJDOC) \
+@CREATE_API_DOCS_TRUE@	-use \
+@CREATE_API_DOCS_TRUE@	-sourcepath "$(sourcepath)" \
+@CREATE_API_DOCS_TRUE@	-encoding UTF-8 \
+@CREATE_API_DOCS_TRUE@	-breakiterator \
+@CREATE_API_DOCS_TRUE@	-licensetext \
+@CREATE_API_DOCS_TRUE@	-linksource \
+@CREATE_API_DOCS_TRUE@	-splitindex \
+@CREATE_API_DOCS_TRUE@	-validhtml \
+@CREATE_API_DOCS_TRUE@	-d html \
+@CREATE_API_DOCS_TRUE@	-doctitle "GNU Classpath $(VERSION)" \
+@CREATE_API_DOCS_TRUE@	-windowtitle "GNU Classpath $(VERSION) Documentation" \
+@CREATE_API_DOCS_TRUE@	-header $(classpathbox) -footer $(classpathbox) \
+@CREATE_API_DOCS_TRUE@	-subpackages java:javax:org
+@CREATE_API_DOCS_TRUE@	touch create_html
+
+# Tell versions [3.59,3.63) of GNU make to not export all variables.
+# Otherwise a system limit (for SysV at least) may be exceeded.
+.NOEXPORT:
diff --git a/libjava/classpath/doc/cp-hacking.texinfo b/libjava/classpath/doc/cp-hacking.texinfo
new file mode 100644
index 000000000..2914c5be5
--- /dev/null
+++ b/libjava/classpath/doc/cp-hacking.texinfo
@@ -0,0 +1,2081 @@
+\input texinfo @c -*-texinfo-*-
+
+@c %**start of header
+@setfilename cp-hacking.info
+@settitle GNU Classpath Hacker's Guide
+@c %**end of header
+
+@setchapternewpage off
+
+@ifinfo
+This file contains important information you will need to know if you
+are going to hack on the GNU Classpath project code.
+
+Copyright (C) 1998,1999,2000,2001,2002,2003,2004,2005,2007,2009 Free Software Foundation, Inc.
+
+@ifnotplaintext
+@dircategory GNU Libraries
+@direntry
+* Classpath Hacking: (cp-hacking).  GNU Classpath Hacker's Guide
+@end direntry
+@end ifnotplaintext
+@end ifinfo
+
+@titlepage
+@title GNU Classpath Hacker's Guide
+@author Aaron M. Renn
+@author Paul N. Fisher
+@author John Keiser
+@author C. Brian Jones
+@author Mark J. Wielaard
+
+@page
+@vskip 0pt plus 1filll
+Copyright @copyright{} 1998,1999,2000,2001,2002,2003,2004 Free Software Foundation, Inc.
+@sp 2
+Permission is granted to make and distribute verbatim copies of
+this document provided the copyright notice and this permission notice
+are preserved on all copies.
+
+Permission is granted to copy and distribute modified versions of this
+document under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions,
+except that this permission notice may be stated in a translation
+approved by the Free Software Foundation.
+
+@end titlepage
+
+@ifinfo
+@node Top, Introduction, (dir), (dir)
+@top GNU Classpath Hacker's Guide
+
+This document contains important information you'll want to know if
+you want to hack on GNU Classpath, Essential Libraries for Java, to
+help create free core class libraries for use with virtual machines
+and compilers for the java programming language.
+@end ifinfo
+
+@menu
+* Introduction::                An introduction to the GNU Classpath project
+* Requirements::                Very important rules that must be followed
+* Volunteering::                So you want to help out
+* Project Goals::               Goals of the GNU Classpath project
+* Needed Tools and Libraries::  A list of programs and libraries you will need
+* Installation::                Installation instructions
+* Building and running with the X AWT peers:: Building and running with the X AWT peers
+* Misc. Notes::                 Miscellaneous notes
+* Programming Standards::       Standards to use when writing code
+* Hacking Code::                Working on code, Working with others
+* Programming Goals::           What to consider when writing code
+* API Compatibility::           How to handle serialization and deprecated methods
+* Specification Sources::       Where to find class library specs
+* Naming Conventions::          How files and directories are named
+* Character Conversions::       Working on Character conversions
+* Localization::                How to handle localization/internationalization
+
+@detailmenu
+ --- The Detailed Node Listing ---
+
+Programming Standards
+
+* Source Code Style Guide::     
+
+Working on the code, Working with others
+
+* Branches::                    
+* Writing ChangeLogs::          
+
+Working with branches
+
+* Writing ChangeLogs::          
+
+Programming Goals
+
+* Portability::                 Writing Portable Software                
+* Utility Classes::             Reusing Software
+* Robustness::                  Writing Robust Software               
+* Java Efficiency::             Writing Efficient Java            
+* Native Efficiency::           Writing Efficient JNI          
+* Security::                    Writing Secure Software
+
+API Compatibility
+
+* Serialization::               Serialization
+* Deprecated Methods::          Deprecated methods
+
+Localization
+
+* String Collation::            Sorting strings in different locales
+* Break Iteration::             Breaking up text into words, sentences, and lines
+* Date Formatting and Parsing::  Locale specific date handling
+* Decimal/Currency Formatting and Parsing::  Local specific number handling
+
+@end detailmenu
+@end menu
+
+@node Introduction, Requirements, Top, Top
+@comment node-name, next, previous, up
+@chapter Introduction
+
+The GNU Classpath Project is dedicated to providing a 100% free,
+clean room implementation of the standard core class libraries for
+compilers and runtime environments for the java programming language.
+It offers free software developers an alternative core library
+implementation upon which larger java-like programming environments
+can be built.  The GNU Classpath Project was started in the Spring of
+1998 as an official Free Software Foundation project.  Most of the
+volunteers working on GNU Classpath do so in their spare time, but a
+couple of projects based on GNU Classpath have paid programmers to
+improve the core libraries.  We appreciate everyone's efforts in the
+past to improve and help the project and look forward to future
+contributions by old and new members alike.
+
+@node Requirements, Volunteering, Introduction, Top
+@comment node-name, next, previous, up
+@chapter Requirements
+
+Although GNU Classpath is following an open development model where input
+from developers is welcome, there are certain base requirements that
+need to be met by anyone who wants to contribute code to this project.
+They are mostly dictated by legal requirements and are not arbitrary
+restrictions chosen by the GNU Classpath team.
+
+You will need to adhere to the following things if you want to donate
+code to the GNU Classpath project:
+
+@itemize @bullet
+@item
+@strong{Never under any circumstances refer to proprietary code while
+working on GNU Classpath.}  It is best if you have never looked at
+alternative proprietary core library code at all.  To reduce
+temptation, it would be best if you deleted the @file{src.zip} file
+from your proprietary JDK distribution (note that recent versions of
+GNU Classpath and the compilers and environments build on it are
+mature enough to not need any proprietary implementation at all when
+working on GNU Classpath, except in exceptional cases where you need
+to test compatibility issues pointed out by users).  If you have
+signed Sun's non-disclosure statement, then you unfortunately cannot
+work on Classpath code at all.  If you have any reason to believe that
+your code might be ``tainted'', please say something on the mailing
+list before writing anything.  If it turns out that your code was not
+developed in a clean room environment, we could be very embarrassed
+someday in court.  Please don't let that happen.
+
+@item
+@strong{Never decompile proprietary class library implementations.}  While
+the wording of the license in Sun's Java 2 releases has changed, it is
+not acceptable, under any circumstances, for a person working on
+GNU Classpath to decompile Sun's class libraries.  Allowing the use of
+decompilation in the GNU Classpath project would open up a giant can of
+legal worms, which we wish to avoid.
+
+@item
+Classpath is licensed under the terms of the
+@uref{http://www.fsf.org/copyleft/gpl.html,GNU General Public
+License}, with a special exception included to allow linking with
+non-GPL licensed works as long as no other license would restrict such
+linking.  To preserve freedom for all users and to maintain uniform
+licensing of Classpath, we will not accept code into the main
+distribution that is not licensed under these terms.  The exact
+wording of the license of the current version of GNU Classpath can be
+found online from the
+@uref{http://www.gnu.org/software/classpath/license.html, GNU
+Classpath license page} and is of course distributed with current
+snapshot release from @uref{ftp://ftp.gnu.org/gnu/classpath/} or by
+obtaining a copy of the current CVS tree.
+
+@item
+GNU Classpath is GNU software and this project is being officially sponsored
+by the @uref{http://www.fsf.org/,Free Software Foundation}.  Because of
+this, the FSF will hold copyright to all code developed as part of
+GNU Classpath.  This will allow them to pursue copyright violators in court,
+something an individual developer may neither have the time nor
+resources to do.  Everyone contributing code to GNU Classpath will need to
+sign a copyright assignment statement.  Additionally, if you are
+employed as a programmer, your employer may need to sign a copyright
+waiver disclaiming all interest in the software.  This may sound harsh,
+but unfortunately, it is the only way to ensure that the code you write
+is legally yours to distribute.
+@end itemize
+
+@node Volunteering, Project Goals, Requirements, Top
+@comment node-name, next, previous, up
+@chapter Volunteering to Help
+
+The GNU Classpath project needs volunteers to help us out.  People are
+needed to write unimplemented core packages, to test GNU Classpath on
+free software programs written in the java programming language, to
+test it on various platforms, and to port it to platforms that are
+currently unsupported.
+
+While pretty much all contributions are welcome (but see 
+@pxref{Requirements}) it is always preferable that volunteers do the
+whole job when volunteering for a task.  So when you volunteer to write
+a Java package, please be willing to do the following:
+
+@itemize @bullet
+@item
+Implement a complete drop-in replacement for the particular package.
+That means implementing any ``internal'' classes.  For example, in the
+java.net package, there are non-public classes for implementing sockets.
+Without those classes, the public socket interface is useless.  But do
+not feel obligated to completely implement all of the functionality at
+once.  For example, in the java.net package, there are different types
+of protocol handlers for different types of URLs.  Not all of these
+need to be written at once.
+
+@item
+Please write complete and thorough API documentation comments for
+every public and protected method and variable.  These should be
+superior to Sun's and cover everything about the item being
+documented.
+
+@item
+Please write a regression test package that can be used to run tests
+of your package's functionality.  GNU Classpath uses the
+@uref{http://sources.redhat.com/mauve/,Mauve project} for testing the
+functionality of the core class libraries.  The Classpath Project is
+fast approaching the point in time where all modifications to the
+source code repository will require appropriate test cases in Mauve to
+ensure correctness and prevent regressions.  
+@end itemize
+
+Writing good documentation, tests and fixing bugs should be every
+developer's top priority in order to reach the elusive release of
+version 1.0.
+
+@node Project Goals, Needed Tools and Libraries, Volunteering, Top
+@comment node-name, next, previous, up
+@chapter Project Goals
+
+The goal of the Classpath project is to produce a
+@uref{http://www.fsf.org/philosophy/free-sw.html,free} implementation of
+the standard class library for Java.  However, there are other more
+specific goals as to which platforms should be supported.
+
+Classpath is targeted to support the following operating systems:
+
+@enumerate
+@item
+Free operating systems.  This includes GNU/Linux, GNU/Hurd, and the free
+BSDs.
+
+@item
+Other Unix-like operating systems.
+
+@item
+Platforms which currently have no Java support at all.
+
+@item 
+Other platforms such as MS-Windows.
+@end enumerate
+
+While free operating systems are the top priority, the other priorities
+can shift depending on whether or not there is a volunteer to port
+Classpath to those platforms and to test releases.
+
+Eventually we hope the Classpath will support all JVMs that provide
+JNI or CNI support.  However, the top priority is free JVMs.  A small
+list of Compiler/VM environments that are currently actively
+incorporating GNU Classpath is below.  A more complete overview of
+projects based on GNU classpath can be found online at
+@uref{http://www.gnu.org/software/classpath/stories.html,the GNU
+Classpath stories page}.
+
+@enumerate
+@item
+@uref{http://gcc.gnu.org/java/,GCJ}
+@item 
+@uref{http://jamvm.sourceforge.net/,jamvm}
+@item 
+@uref{http://www.cacaojvm.org/,cacao}
+@item
+@uref{http://jikesrvm.org,Jikes RVM}
+@item
+@uref{http://www.kaffe.org/,Kaffe}
+@item
+@uref{http://www.ikvm.net/,IKVM}
+@end enumerate
+
+As with OS platform support, this priority list could change if a
+volunteer comes forward to port, maintain, and test releases for a
+particular JVM@.  Since gcj is part of the GNU Compiler Collective it
+is one of the most important targets.  But since it doesn't currently
+work out of the box with GNU Classpath it is not the easiest
+target.  When hacking on GNU Classpath the easiest solution is to use
+compilers and runtime environments that work out of the box with
+it, such as the Eclipse compiler, ecj, and the runtime environments jamvm and
+cacao.  Both Jikes RVM and Kaffe use an included version of GNU Classpath by
+default, but Kaffe can now use a pre-installed version and Jikes RVM supports 
+using a CVS snapshot as well as the latest release.  Working directly with
+targets such as Jikes RVM, gcj and IKVM is possible but can be a little more
+difficult as changes have to be merged back into GNU Classpath proper,
+which requires additional work.  Due to a recent switch to the use of 1.5 language
+features within GNU Classpath, a compiler compatible with these features is required.
+At present, this includes the Eclipse compiler, ecj, and the OpenJDK compiler.
+
+GNU Classpath currently implements the majority of the 1.4 and 1.5 APIs
+(binary compatibility is above 95% for both, but does not take into account
+internal implementations of features such as graphic and sound support).  There
+is support for some 1.6 APIs but this is still nascent.  Please do not create classes
+that depend on features in other packages unless GNU Classpath already
+contains those features.  GNU Classpath has been free of any
+proprietary dependencies for a long time now and we like to keep it
+that way.  Finishing, polishing up, documenting, testing and
+debugging current functionality is of higher priority then adding new
+functionality.
+
+@node Needed Tools and Libraries, Installation, Project Goals, Top
+@comment node-name, next, previous, up
+@chapter Needed Tools and Libraries
+
+If you want to hack on Classpath, you should at least download and
+install the following tools and try to familiarize yourself with
+them.  In most cases having these tools installed will be all
+you really need to know about them.  Also note that when working on
+(snapshot) releases only a 1.5 compiler (plus a free VM from the list above
+and the libraries listed below) is required.  The other tools are only
+needed when working directly on the CVS version.
+
+@itemize @bullet
+@item
+GNU make 3.80+
+@item
+GCC 2.95+
+@item
+Eclipse Compiler for Java 3.1+
+@item
+CVS 1.11+
+@item
+automake 1.11+
+@item
+autoconf 2.64+
+@item
+libtool 1.5+
+@item
+GNU m4 1.4.6
+@item
+texinfo 4.2+
+@end itemize
+
+All of these tools are available from
+@uref{ftp://gnudist.gnu.org/pub/gnu/,gnudist.gnu.org} via anonymous
+ftp, except CVS which is available from
+@uref{http://www.cvshome.org/,www.cvshome.org} and the Eclipse 
+Compiler for Java, which is available from 
+@uref{http://www.eclipse.org/jdt/core,www.eclipse.org/jdt/core}.
+
+Except for the Eclipse Compiler for Java, they are fully documented 
+with texinfo manuals.  Texinfo can be browsed with the Emacs editor, 
+or with the text editor of your choice, or transformed into nicely 
+printable Postscript.
+
+Here is a brief description of the purpose of those tools.
+
+@table @b
+
+@item make
+GNU make ("gmake") is required for building Classpath.
+
+@item GCC
+The GNU Compiler Collection. This contains a C compiler (gcc) for
+compiling the native C code and a compiler for the java programming
+language (gcj).  You will need at least gcc version 2.95 or higher
+in order to compile the native code. There is currently no 
+released version of gcj that can compile the Java 1.5 programming 
+language used by GNU Classpath.
+
+@item ecj
+The Eclipse Compiler for Java. This is a compiler for the Java 1.5
+programming language. It translates source code to bytecode. The
+Eclipse Foundation makes ``ecj.jar'' available as the JDT Core Batch
+Compiler download.
+
+@item CVS  
+A version control system that maintains a centralized Internet
+repository of all code in the Classpath system.
+
+@item automake  
+This tool automatically creates @file{Makefile.in} files from 
+@file{Makefile.am} files.  The @file{Makefile.in} is turned into a 
+@file{Makefile} by @command{autoconf}.  
+
+Why use this?  Because it automatically generates every makefile 
+target you would ever want (@option{clean}, @option{install}, 
+@option{dist}, etc) in full compliance with the GNU coding standards.  
+It also simplifies Makefile creation in a number of ways that cannot 
+be described here.  Read the docs for more info.
+
+@item autoconf  
+Automatically configures a package for the platform on which it is
+being built and generates the Makefile for that platform.
+
+@item libtool  
+Handles all of the zillions of hairy platform specific options needed
+to build shared libraries.
+
+@item m4
+The free GNU replacement for the standard Unix macro processor.
+Proprietary m4 programs are broken and so GNU m4 is required for
+autoconf to work though knowing a lot about GNU m4 is not required to
+work with autoconf.
+
+@item perl
+Larry Wall's scripting language.  It is used internally by automake.
+
+@item texinfo
+Manuals and documentation (like this guide) are written in texinfo.
+Texinfo is the official documentation format of the GNU project.
+Texinfo uses a single source file to produce output in a number of formats,
+both online and printed (dvi, info, html, xml, etc.). This means that
+instead of writing different documents for online information and another
+for a printed manual, you need write only one document. And when the work
+is revised, you need revise only that one document.
+
+@end table
+
+For any build environment involving native libraries, recent 
+versions of @command{autoconf}, @command{automake}, and @command{libtool}
+are required if changes are made that require rebuilding @file{configure}, 
+@file{Makefile.in}, @file{aclocal.m4}, or @file{config.h.in}.
+
+When working from CVS you can run those tools by executing
+@command{autogen.sh} in the source directory.
+
+For building the Java bytecode (.class files), you can select 
+which compiler should be employed using @option{--with-javac} or 
+@option{--with-ecj} as an argument to @command{configure}; 
+the present default is @command{ecj} if found.
+
+Instead of @command{ecj}, you can also use @command{javac}, which is 
+available at 
+@uref{https://openjdk.dev.java.net/compiler, openjdk.dev.java.net/compiler}.
+
+For compiling the native AWT libraries you need to have the following
+libraries installed (unless @option{--disable-gtk-peer} is used as an argument 
+to @command{configure}):
+
+@table @b
+@item GTK+ 2.8.x
+@uref{http://www.gtk.org/,GTK+} is a multi-platform toolkit for
+creating graphical user interfaces.  It is used as the basis of the
+GNU desktop project GNOME.
+
+@item gdk-pixbuf
+@uref{http://www.gnome.org/start/,gdk-pixbuf} is a GNOME library for
+representing images.
+
+@item XTest 
+@uref{http://www.x.org,www.x.org} hosts the XTest Extension (libXtst).
+It is necessary for GdkRobot support in java.awt.
+
+@end table
+
+There is a bug in earlier versions of at-spi, atk, and gail, which are
+used for GNOME accessibility.  Prior to version 1.18.0 of these packages,
+gtk graphical applications should be run without accessibility (clear the
+GTK_MODULES environment variable).
+
+For building the Qt AWT peer JNI native libraries you have to
+specify @option{--enable-qt-peer} and need the following library:
+
+@table @b
+@item Qt
+@uref{http://www.trolltech.com/products/qt,Qt} version 4.0.1 or higher.
+The Qt library is a cross-platform graphics toolkit.
+
+@end table
+
+Please note that at the moment most operating systems do not
+ship Qt version 4.0.1 by default. We recommend using GNU Classpath' Qt
+support only for its developers and bug reporters. See
+@uref{http://developer.classpath.org/mediation/ClasspathShowcase, the wiki}
+for details on how to get it to work.
+
+For building the X AWT peers you have to specify where to find the
+Escher library on your system using the @option{--with-escher=ABS.PATH} option. 
+You will need the following library:
+
+@table @b
+@item Escher
+@uref{http://escher.sourceforge.net,Escher} version 0.2.3 or higher.
+The Escher library is an implementation of X protocol and associated
+libraries written in the Java programming language.
+
+@end table
+
+For building the ALSA midi provider code you will need
+the following library:
+
+
+@table @b
+@item ALSA
+@uref{http://www.alsa-project.org,ALSA} libraries.
+
+The ALSA project provides sound device drivers and associated 
+libraries for the Linux kernel.
+
+@end table
+
+Building the ALSA midi provider code can be disabled by passing
+@option{--disable-alsa} to @command{configure}.
+
+For building the DSSI midi synthesizer provider code you will
+need the following libraries:
+
+@table @b
+@item DSSI
+@uref{http://dssi.sourceforge.net,DSSI} library for audio
+processing plugins.
+
+@item liblo
+@uref{http://plugin.org.uk/liblo/,liblo}, the Lightweight OSC 
+implementation.
+
+@item LADSPA
+@uref{http://www.ladspa.org,LADSPA}, the Linux Audio Developer's 
+Simple Plugin API.
+    
+@item JACK
+@uref{http://jackit.sourceforge.net,JACK}, a low latency audio 
+server.
+    
+@item libsndfile
+@uref{http://www.mega-nerd.com/libsndfile/,libsndfile}, an audio 
+file I/O library.
+    
+@item fluidsynth
+@uref{http://www.fluidsynth.org/,fluidsynth}, a real-time SoundFont 
+2 based soft-synth.
+
+@end table    
+
+The GConf-based backend for java.util.prefs needs the following
+library headers:
+
+@table @b
+@item GConf
+@uref{http://www.gnome.org/projects/gconf/,GConf} version 2.11.2
+(or higher). GConf is used for storing desktop and application
+configuration settings in GNOME.
+
+@end table
+
+The GStreamer backend for javax.sound.sampled (The Java Sound API, not
+including the MIDI portion) needs the following library headers:
+
+@table @b
+@item GStreamer
+@uref{http://gstreamer.freedesktop.org/,GStreamer} version 0.10.10
+(or higher). You will also need at least gstreamer-base and
+gstreamer-plugins-base. More plugins can be used to allow streaming of
+different sound types but are not a compile time requirement. See
+README.gstreamer in the source distribution for more informations.
+
+@end table
+
+For building @command{gcjwebplugin} you'll need the Mozilla plugin
+support headers and libraries, which are available at 
+@uref{http://www.mozilla.org,www.mozilla.org}.
+
+For enabling the com.sun.tools.javac support in tools.zip you
+will need a jar file containing the Eclipse Java Compiler.
+Otherwise com.sun.tools.javac will not be included in @file{tools.zip}.
+
+For building the xmlj JAXP implementation (disabled by default, 
+use @command{configure --enable-xmlj}) you need the following libraries:
+
+@table @b
+@item libxml2
+@uref{http://www.xmlsoft.org/,libxml2} version 2.6.8 or higher.
+
+The libxml2 library is the XML C library for the Gnome desktop.
+
+@item libxslt
+@uref{http://www.xmlsoft.org/XSLT/,libxslt} version 1.1.11 or higher.
+
+The libxslt library if the XSLT C library for the Gnome desktop.
+@end table
+
+GNU Classpath comes with a couple of libraries included in the source
+that are not part of GNU Classpath proper, but that have been included
+to provide certain needed functionality.  All these external libraries
+should be clearly marked as such.  In general we try to use as much as
+possible the clean upstream versions of these sources.  That way
+merging in new versions will be easier.  You should always try to get
+bug fixes to these files accepted upstream first.  Currently we
+include the following 'external' libraries.  Most of these sources are
+included in the @file{external} directory.  That directory also
+contains a @file{README} file explaining how to import newer versions.
+
+@table @b
+
+@item JSR166 concurrency support
+Can be found in @file{external/jsr166}.  Provides java.util.concurrent
+and its subpackages.  Upstream is
+@uref{http://g.oswego.edu/dl/concurrency-interest/,Doug Lea's Concurrency Interest Site}.
+
+@item RelaxNG Datatype Interfaces
+Can be found in @file{external/relaxngDatatype}.  Provides org.relaxng.datatype
+and its subpackages.  Upstream is
+@uref{http://www.oasis-open.org/committees/relax-ng/}.
+
+@item Simple API for XML (SAX)
+Can be found in @file{external/sax}.  Provides org.xml.sax and its subpackages.
+Upstream is
+@uref{http://www.saxproject.org}.
+
+@item Document Object Model (DOM) bindings
+Can be found in @file{external/w3c_dom}.  Provides org.w3c.dom and its subpackages.
+Upstream locations are listed in @file{external/w3c_dom/README}.
+
+@item fdlibm
+Can be found in @file{native/fdlibm}.  Provides native implementations
+of some of the Float and Double operations.  Upstream is
+@uref{http://gcc.gnu.org/java/,libgcj}, they sync again with the
+'real' upstream @uref{http://www.netlib.org/fdlibm/readme}.  See also
+java.lang.StrictMath.
+
+@end table
+
+@node Installation, Building and running with the X AWT peers, Needed Tools and Libraries, Top
+@comment node-name, next, previous, up
+@chapter Installation instructions
+
+This package was designed to use the GNU standard for configuration
+and makefiles.  To build and install do the following:
+
+@enumerate
+@item Configuration
+
+Run the @command{configure} script to configure the package.  There are
+various options you might want to pass to @command{configure} to control how the
+package is built.  Consider the following options, @command{configure --help}
+gives a complete list.  
+
+@table @option
+@item --enable-java       
+
+compile Java source (default=@option{yes}).
+
+@item --enable-jni
+
+compile JNI source (default=@option{yes}).
+
+@item --enable-gtk-peer
+
+compile GTK native peers (default=@option{yes}).
+
+@item --enable-qt-peer
+
+compile Qt4 native peers (default=@option{no}).
+
+@item --enable-default-toolkit
+
+fully qualified class name of default AWT toolkit (default=@option{no}).
+
+@item --enable-xmlj
+
+compile native libxml/xslt library (default=@option{no}).
+
+@item --enable-load-library
+
+enable to use JNI native methods (default=@option{yes}).
+
+@item --enable-local-sockets
+
+enable build of local Unix sockets.
+
+@item --with-glibj
+define what to install @option{(zip|flat|both|none)} (default=@option{zip}).
+
+@item --with-escher=/path/to/escher
+
+enable build of the X/Escher peers, with
+the escher library at @file{/path/to/escher}, either
+in the form of a JAR file, or a directory
+containing the .class files of Escher.
+
+@item --enable-Werror
+
+whether to compile C code with @option{-Werror} which turns
+any compiler warning into a compilation failure
+(default=@option{no}).
+
+@item --with-gjdoc
+
+generate documentation using @command{gjdoc} (default=@option{no}).
+
+@item --with-jay
+
+Regenerate the parsers with @command{jay}, must be given the
+path to the @command{jay} executable
+
+@item --with-glibj-zip=ABS.PATH
+
+use prebuilt glibj.zip class library
+
+@item --with-ecj-jar=ABS.PATH 
+
+specify jar file containing the Eclipse Java Compiler
+
+@item --with-gstreamer-peer
+
+build the experimental GStreamer peer (see @file{README.gstreamer})
+
+@end table
+
+For more flags run @command{configure --help}.
+
+@item Building
+
+Type @command{gmake} to build the package.  There is no longer a
+dependency problem and we aim to keep it that way.
+
+@item Installation
+
+Type @command{gmake install} to install everything.  This may require
+being the superuser. The default install path is /usr/local/classpath
+you may change it by giving @command{configure} the 
+@option{--prefix=<path>} option.
+
+@end enumerate
+
+Report bugs to @email{classpath@@gnu.org} or much better to the 
+GNU Classpath bug tracker at 
+@uref{http://savannah.gnu.org/support/?func=addsupport&group=classpath,Savannah}.
+
+Happy Hacking!
+
+Once installed, GNU Classpath is ready to be used by any VM that supports
+using the official version of GNU Classpath.  Simply ensure that
+@file{/usr/local/classpath/share/classpath} is in your @env{CLASSPATH} environment
+variable.  You'll also have to set your @env{LD_LIBRARY_PATH}
+variable (or similar system configuration) to include the Classpath
+native libraries in @file{/usr/local/classpath/lib/classpath}.
+
+*NOTE* All example paths assume the default prefix is used with @command{configure}.
+If you don't know what this means then the examples are correct.
+
+@example
+LD_LIBRARY_PATH=/usr/local/classpath/lib/classpath
+CLASSPATH=/usr/local/classpath/share/classpath/glibj.zip:.
+export LD_LIBRARY_PATH CLASSPATH
+@end example
+
+More information about the VMs that use GNU Classpath can be found in the
+@file{README} file.
+
+@node Building and running with the X AWT peers, Misc. Notes, Installation, Top
+@comment node-name, next, previous, up
+@chapter Building and running with the X AWT peers
+
+In order build the X peers you need the Escher library version 0.2.3
+from @uref{http://escher.sourceforge.net,escher.sourceforge.net}. 
+Unpack (and optionally build) the
+Escher library following the instructions in the downloaded
+package. Enable the build of the X peers by passing
+@option{--with-escher=/path/to/escher} to @command{configure} where @file{/path/to/escher}
+either points to a directory structure or JAR file containing the
+Escher classes. For Unix systems it is preferable to also build local
+socket support by passing @option{--enable-local-sockets}, which accelerates
+the network communication to the X server significantly.
+
+In this release you have to enable the X peers at runtime by
+setting the system property awt.toolkit=gnu.java.awt.peer.x.XToolkit
+by passing @option{-Dawt.toolkit=gnu.java.awt.peer.x.XToolkit} to the @command{java}
+command when running an application.
+
+@node Misc. Notes, Programming Standards, Building and running with the X AWT peers, Top
+@comment node-name, next, previous, up
+@chapter Misc. Notes
+
+Compilation is accomplished using a compiler's @@file syntax.  For our
+part, we avoid placing make style dependencies as rules upon the
+compilation of a particular class file and leave this up to the Java
+compiler instead.
+
+The @option{--enable-maintainer-mode} option to @command{configure} currently does very 
+little and shouldn't be used by ordinary developers or users anyway.
+
+On Windows machines, the native libraries do not currently build, but
+the Java bytecode library will.  GCJ trunk is beginning to work under
+Cygwin.
+
+@node Programming Standards, Hacking Code, Misc. Notes, Top
+@comment node-name, next, previous, up
+@chapter Programming Standards
+
+For C source code, follow the
+@uref{http://www.gnu.org/prep/standards/,GNU Coding Standards}.
+The standards also specify various things like the install directory
+structure.  These should be followed if possible.
+
+For Java source code, please follow the
+@uref{http://www.gnu.org/prep/standards/,GNU Coding
+Standards}, as much as possible.  There are a number of exceptions to
+the GNU Coding Standards that we make for GNU Classpath as documented
+in this guide.  We will hopefully be providing developers with a code
+formatting tool that closely matches those rules soon.
+
+For API documentation comments, please follow
+@uref{http://java.sun.com/products/jdk/javadoc/writingdoccomments.html,How
+to Write Doc Comments for Javadoc}.  We would like to have a set of
+guidelines more tailored to GNU Classpath as part of this document.
+
+@menu
+* Source Code Style Guide::     
+@end menu
+
+@node Source Code Style Guide,  , Programming Standards, Programming Standards
+@comment node-name, next, previous, up
+@section Java source coding style
+
+Here is a list of some specific rules used when hacking on GNU
+Classpath java source code. We try to follow the standard
+@uref{http://www.gnu.org/prep/standards/,GNU Coding Standards}
+for that. There are lots of tools that can automatically generate it
+(although most tools assume C source, not java source code) and it
+seems as good a standard as any. There are a couple of exceptions and
+specific rules when hacking on GNU Classpath java source code however.
+The following lists how code is formatted (and some other code
+conventions):
+
+
+@itemize @bullet
+
+@item
+Java source files in GNU Classpath are encoded using UTF-8.  However,
+ordinarily it is considered best practice to use the ASCII subset of
+UTF-8 and write non-ASCII characters using \u escapes.
+
+@item
+If possible, generate specific imports (expand) over java.io.* type
+imports. Order by gnu, java, javax, org. There must be one blank line
+between each group. The imports themselves are ordered alphabetically by
+package name. Classes and interfaces occur before sub-packages. The
+classes/interfaces are then also sorted alphabetical. Note that uppercase
+characters occur before lowercase characters.
+
+@example
+import gnu.java.awt.EmbeddedWindow;
+
+import java.io.IOException;
+import java.io.InputStream;
+
+import javax.swing.JFrame;
+@end example
+
+@item
+Blank line after package statement, last import statement, classes,
+interfaces, methods.
+
+@item
+Opening/closing brace for class and method is at the same level of
+indent as the declaration.  All other braces are indented and content
+between braces indented again.
+
+@item
+Since method definitions don't start in column zero anyway (since they
+are always inside a class definition), the rational for easy grepping
+for ``^method_def'' is mostly gone already. Since it is customary for
+almost everybody who writes java source code to put modifiers, return
+value and method name on the same line, we do too.
+
+@c fixme Another rational for always indenting the method definition is that it makes it a bit easier to distinguish methods in inner and anonymous classes from code in their enclosing context. NEED EXAMPLE.
+
+@item
+Implements and extends on separate lines, throws too.  Indent extends,
+implements, throws.  Apply deep indentation for method arguments.
+
+@c fixme Needs example.
+
+@item
+Don't add a space between a method or constructor call/definition and
+the open-bracket. This is because often the return value is an object on
+which you want to apply another method or from which you want to access
+a field.
+        
+Don't write:
+
+@example
+  getToolkit ().createWindow (this);
+@end example
+
+But write:
+@example
+  getToolkit().createWindow(this);
+@end example
+
+@item
+The GNU Coding Standard it gives examples for almost every construct
+(if, switch, do, while, etc.).  One missing is the try-catch construct
+which should be formatted as:
+
+@example
+  try
+    @{
+      //
+    @}
+  catch (...)
+    @{
+      //
+    @}
+@end example
+
+@item
+Wrap lines at 80 characters after assignments and before operators.
+Wrap always before extends, implements, throws, and labels.
+
+@item
+Don't put multiple class definitions in the same file, except for
+inner classes. File names (plus .java) and class names should be the
+same.
+
+@item
+Don't catch a @code{NullPointerException} as an alternative to simply
+checking for @code{null}.  It is clearer and usually more efficient
+to simply write an explicit check.
+
+For instance, don't write:
+
+@example
+try
+  @{
+    return foo.doit();
+  @}
+catch (NullPointerException _)
+  @{
+    return 7;
+  @}
+@end example
+
+If your intent above is to check whether @samp{foo} is @code{null},
+instead write:
+
+@example
+if (foo == null)
+  return 7;
+else
+  return foo.doit();
+@end example
+
+@item
+Don't use redundant modifiers or other redundant constructs.  Here is
+some sample code that shows various redundant items in comments:
+
+@example
+/*import java.lang.Integer;*/
+/*abstract*/ interface I @{
+   /*public abstract*/ void m();
+   /*public static final*/ int i = 1;
+   /*public static*/ class Inner @{@}
+@}
+final class C /*extends Object*/ @{
+   /*final*/ void m() @{@}
+@}
+@end example
+
+Note that Jikes will generate warnings for redundant modifiers if you
+use @code{+Predundant-modifiers} on the command line.
+
+@item
+Modifiers should be listed in the standard order recommended by the
+JLS@.  Jikes will warn for this when given @code{+Pmodifier-order}.
+
+@item
+Because the output of different compilers differs, we have
+standardized on explicitly specifying @code{serialVersionUID} in
+@code{Serializable} classes in Classpath.  This field should be
+declared as @code{private static final}.  Note that a class may be
+@code{Serializable} without being explicitly marked as such, due to
+inheritance.  For instance, all subclasses of @code{Throwable} need to
+have @code{serialVersionUID} declared.
+@c fixme index
+@c fixme link to the discussion
+
+@item
+Don't declare unchecked exceptions in the @code{throws} clause of a
+method.  However, if throwing an unchecked exception is part of the
+method's API, you should mention it in the Javadoc.  There is one
+important exception to this rule, which is that a stub method should
+be marked as throwing @code{gnu.classpath.NotImplementedException}.
+This will let our API comparison tools note that the method is not
+fully implemented.
+
+@item
+When overriding @code{Object.equals}, remember that @code{instanceof}
+filters out @code{null}, so an explicit check is not needed.
+
+@item
+When catching an exception and rethrowing a new exception you should
+``chain'' the Throwables.  Don't just add the String representation of
+the caught exception.
+
+@example
+  try
+    @{
+      // Some code that can throw
+    @}
+  catch (IOException ioe)
+    @{
+      throw (SQLException) new SQLException("Database corrupt").setCause(ioe);
+    @}
+@end example
+
+@item
+Avoid the use of reserved words for identifiers.  This is obvious with those
+such as @code{if} and @code{while} which have always been part of the Java
+programming language, but you should be careful about accidentally using
+words which have been added in later versions.  Notable examples are
+@code{assert} (added in 1.4) and @code{enum} (added in 1.5).  Jikes will warn
+of the use of the word @code{enum}, but, as it doesn't yet support the 1.5
+version of the language, it will still allow this usage through.  A
+compiler which supports 1.5 (e.g.@: the Eclipse compiler, ecj) will simply
+fail to compile the offending source code.
+
+@c fixme Describe Anonymous classes (example).
+@c fixme Descibe Naming conventions when different from GNU Coding Standards.
+@c fixme Describee API doc javadoc tags used.
+
+@end itemize
+
+Some things are the same as in the normal GNU Coding Standards:
+
+@itemize @bullet
+
+@item
+Unnecessary braces can be removed, one line after an if, for, while as
+examples.
+
+@item
+Space around operators (assignment, logical, relational, bitwise,
+mathematical, shift).
+
+@item
+Blank line before single-line comments, multi-line comments, javadoc
+comments.
+
+@item
+If more than 2 blank lines, trim to 2.
+
+@item
+Don't keep commented out code.  Just remove it or add a real comment
+describing what it used to do and why it is changed to the current
+implementation.
+@end itemize
+
+
+@node Hacking Code, Programming Goals, Programming Standards, Top
+@comment node-name, next, previous, up
+@chapter Working on the code, Working with others
+
+There are a lot of people helping out with GNU Classpath.  Here are a
+couple of practical guidelines to make working together on the code
+smoother.
+
+The main thing is to always discuss what you are up to on the
+mailinglist.  Making sure that everybody knows who is working on what
+is the most important thing to make sure we cooperate most
+effectively.
+
+We maintain a
+@uref{http://www.gnu.org/software/classpath/tasks.html,Task List}
+which contains items that you might want to work on.
+
+Before starting to work on something please make sure you read this
+complete guide.  And discuss it on list to make sure your work does
+not duplicate or interferes with work someone else is already doing.
+Always make sure that you submit things that are your own work.  And
+that you have paperwork on file (as stated in the requirements
+section) with the FSF authorizing the use of your additions.
+
+Technically the GNU Classpath project is hosted on
+@uref{http://savannah.gnu.org/,Savannah} a central point for
+development, distribution and maintenance of GNU Software.  Here you
+will find the
+@uref{https://savannah.gnu.org/projects/classpath/,project page}, bug
+reports, pending patches, links to mailing lists, news items and CVS.
+
+You can find instructions on getting a CVS checkout for classpath at
+@uref{https://savannah.gnu.org/cvs/?group=classpath}.
+
+You don't have to get CVS commit write access to contribute, but it is
+sometimes more convenient to be able to add your changes directly to
+the project CVS@. Please contact the GNU Classpath savannah admins to
+arrange CVS access if you would like to have it.
+
+Make sure to be subscribed to the commit-classpath mailinglist while
+you are actively hacking on Classpath.  You have to send patches (cvs
+diff -uN) to this list before committing.
+
+We really want to have a pretty open check-in policy.  But this means
+that you should be extra careful if you check something in.  If at all
+in doubt or if you think that something might need extra explaining
+since it is not completely obvious please make a little announcement
+about the change on the mailinglist.  And if you do commit something
+without discussing it first and another GNU Classpath hackers asks for
+extra explanation or suggests to revert a certain commit then please
+reply to the request by explaining why something should be so or if
+you agree to revert it.  (Just reverting immediately is OK without
+discussion, but then please don't mix it with other changes and please
+say so on list.)
+
+Patches that are already approved for libgcj or also OK for Classpath.
+(But you still have to send a patch/diff to the list.)  All other
+patches require you to think whether or not they are really OK and
+non-controversial, or if you would like some feedback first on them
+before committing.  We might get real commit rules in the future, for
+now use your own judgement, but be a bit conservative.
+
+Always contact the GNU Classpath maintainer before adding anything
+non-trivial that you didn't write yourself and that does not come from
+libgcj or from another known GNU Classpath or libgcj hacker.  If you
+have been assigned to commit changes on behalf of another project or
+a company always make sure they come from people who have signed the
+papers for the FSF and/or fall under the arrangement your company made
+with the FSF for contributions.  Mention in the ChangeLog who actually
+wrote the patch.
+
+Commits for completely unrelated changes they should be committed
+separately (especially when doing a formatting change and a logical
+change, do them in two separate commits). But do try to do a commit of
+as much things/files that are done at the same time which can
+logically be seen as part of the same change/cleanup etc.
+
+When the change fixes an important bug or adds nice new functionality
+please write a short entry for inclusion in the @file{NEWS} file.  If it
+changes the VM interface you must mention that in both the @file{NEWS} file
+and the VM Integration Guide.
+
+All the ``rules'' are really meant to make sure that GNU Classpath
+will be maintainable in the long run and to give all the projects that
+are now using GNU Classpath an accurate view of the changes we make to
+the code and to see what changed when.  If you think the requirements
+are ``unworkable'' please try it first for a couple of weeks.  If you
+still feel the same after having some more experience with the project
+please feel free to bring up suggestions for improvements on the list.
+But don't just ignore the rules!  Other hackers depend on them being
+followed to be the most productive they can be (given the above
+constraints).
+
+@menu
+* Branches::                    
+* Writing ChangeLogs::          
+@end menu
+
+@node Branches, Writing ChangeLogs, Hacking Code, Hacking Code
+@comment node-name, next, previous, up
+@section Working with branches
+
+Sometimes it is necessary to create branch of the source for doing new
+work that is disruptive to the other hackers, or that needs new
+language or libraries not yet (easily) available.
+
+After discussing the need for a branch on the main mailinglist with
+the other hackers explaining the need of a branch and suggestion of
+the particular branch rules (what will be done on the branch, who will
+work on it, will there be different commit guidelines then for the
+mainline trunk and when is the branch estimated to be finished and
+merged back into the trunk) every GNU Classpath hacker with commit
+access should feel free to create a branch. There are however a couple
+of rules that every branch should follow:
+
+@itemize @bullet
+
+@item All branches ought to be documented in the developer wiki at
+@uref{http://developer.classpath.org/mediation/ClasspathBranches}, so
+we can know which are live, who owns them, and when they die.
+
+@item Some rules can be changed on a branch.  In particular the branch
+maintainer can change the review requirements, and the requirement of
+keeping things building, testing, etc, can also be lifted.  (These
+should be documented along with the branch name and owner if they
+differ from the trunk.)
+
+@item Requirements for patch email to classpath-patches and for paperwork
+@strong{cannot} be lifted. See @ref{Requirements}.
+
+@item A branch should not be seen as ``private'' or
+``may be completely broken''. It should be as much as possible
+something that you work on with a team (and if there is no team - yet
+- then there is nothing as bad as having a completely broken build to
+get others to help out). There can of course be occasional breakage, but
+it should be planned and explained. And you can certainly have a rule
+like ``please ask me before committing to this branch''.
+
+@item Merges from the trunk to a branch are at the discretion of the
+branch maintainer.
+
+@item A merge from a branch to the trunk is treated like any other patch.
+In particular, it has to go through review, it must satisfy all the
+trunk requirements (build, regression test, documentation).
+
+@item There may be additional timing requirements on merging a branch to
+the trunk depending on the release schedule, etc.  For instance we may
+not want to do a branch merge just before a release.
+
+@end itemize
+
+If any of these rules are unclear please discuss on the list first.
+
+@menu
+* Writing ChangeLogs::          
+@end menu
+
+@node Writing ChangeLogs,  , Branches, Hacking Code
+@comment node-name, next, previous, up
+@section Documenting what changed when with ChangeLog entries
+
+To keep track of who did what when we keep an explicit ChangeLog entry
+together with the code.  This mirrors the CVS commit messages and in
+general the ChangeLog entry is the same as the CVS commit message.
+This provides an easy way for people getting a (snapshot) release or
+without access to the CVS server to see what happened when.  We do not
+generate the ChangeLog file automatically from the CVS server since
+that is not reliable.
+
+A good ChangeLog entry guideline can be found in the Guile Manual at
+@uref{http://www.gnu.org/software/guile/changelogs/guile-changelogs_3.html}.
+
+Here are some example to explain what should or shouldn't be in a
+ChangeLog entry (and the corresponding commit message):
+
+@itemize @bullet
+
+@item
+The first line of a ChangeLog entry should be:
+
+@example
+[date] <two spaces> [full name] <two spaces> [email-contact]
+@end example
+
+The second line should be blank. All other lines should be indented
+with one tab.
+
+@item
+Just state what was changed.  Why something is done as it is done in
+the current code should be either stated in the code itself or be
+added to one of the documentation files (like this Hacking Guide).
+
+So don't write:
+
+@example
+        * java/awt/font/OpenType.java: Remove 'public static final'
+        from OpenType tags, reverting the change of 2003-08-11.  See
+        Classpath discussion list of 2003-08-11.
+@end example
+
+Just state:
+
+@example
+        * java/awt/font/OpenType.java: Remove 'public static final' from
+        all member fields.
+@end example
+
+In this case the reason for the change was added to this guide.
+
+@item
+Just as with the normal code style guide, don't make lines longer then
+80 characters.
+
+@item
+Just as with comments in the code. The ChangeLog entry should be a
+full sentence, starting with a capital and ending with a period.
+
+@item
+Be precise in what changed, not the effect of the change (which should
+be clear from the code/patch).  So don't write:
+
+@example
+ * java/io/ObjectOutputStream.java : Allow putFields be called more 
+ than once.
+@end example
+
+But explain what changed and in which methods it was changed:
+
+@example
+ * java/io/ObjectOutputStream.java (putFields): Don't call
+ markFieldsWritten(). Only create new PutField when
+ currentPutField is null.
+ (writeFields): Call markFieldsWritten().
+@end example
+
+@end itemize
+
+The above are all just guidelines.  We all appreciate the fact that writing
+ChangeLog entries, using a coding style that is not ``your own'' and the
+CVS, patch and diff tools do take some time to getting used to.  So don't
+feel like you have to do it perfect right away or that contributions
+aren't welcome if they aren't ``perfect''.  We all learn by doing and
+interacting with each other.
+
+
+@node Programming Goals, API Compatibility, Hacking Code, Top
+@comment node-name, next, previous, up
+@chapter Programming Goals
+
+When you write code for Classpath, write with three things in mind, and
+in the following order: portability, robustness, and efficiency.
+
+If efficiency breaks portability or robustness, then don't do it the
+efficient way.  If robustness breaks portability, then bye-bye robust
+code.  Of course, as a programmer you would probably like to find sneaky
+ways to get around the issue so that your code can be all three ... the
+following chapters will give some hints on how to do this.
+
+@menu
+* Portability::                 Writing Portable Software                
+* Utility Classes::             Reusing Software
+* Robustness::                  Writing Robust Software               
+* Java Efficiency::             Writing Efficient Java            
+* Native Efficiency::           Writing Efficient JNI          
+* Security::                    Writing Secure Software
+@end menu
+
+@node Portability, Utility Classes, Programming Goals, Programming Goals
+@comment node-name, next, previous, up
+@section Portability
+
+The portability goal for Classpath is the following:
+
+@enumerate
+@item
+native functions for each platform that work across all VMs on that
+platform
+@item
+a single classfile set that work across all VMs on all platforms that
+support the native functions.
+@end enumerate
+
+For almost all of Classpath, this is a very feasible goal, using a
+combination of JNI and native interfaces.  This is what you should shoot
+for.  For those few places that require knowledge of the Virtual Machine
+beyond that provided by the Java standards, the VM Interface was designed.
+Read the Virtual Machine Integration Guide for more information.
+
+Right now the only supported platform is Linux.  This will change as that
+version stabilizes and we begin the effort to port to many other
+platforms.  Jikes RVM runs Classpath on AIX, and generally the Jikes
+RVM team fixes Classpath to work on that platform. 
+
+@node Utility Classes, Robustness, Portability, Programming Goals
+@comment  node-name,  next,  previous,  up
+@section Utility Classes
+
+At the moment, we are not very good at reuse of the JNI code.  There
+have been some attempts, called @dfn{libclasspath}, to
+create generally useful utility classes.  The utility classes are in
+the directory @file{native/jni/classpath} and they are mostly declared
+in @file{native/jni/classpath/jcl.h}.  These utility classes are
+currently only discussed in @ref{Robustness} and in @ref{Native
+Efficiency}.
+
+There are more utility classes available that could be factored out if
+a volunteer wants something nice to hack on.  The error reporting and
+exception throwing functions and macros in
+@file{native/jni/gtk-peer/gthread-jni.c} might be good
+candidates for reuse.  There are also some generally useful utility
+functions in @file{gnu_java_awt_peer_gtk_GtkMainThread.c} that could
+be split out and put into libclasspath.
+
+@node Robustness, Java Efficiency, Utility Classes, Programming Goals
+@comment node-name, next, previous, up
+@section Robustness
+
+Native code is very easy to make non-robust.  (That's one reason Java is
+so much better!)  Here are a few hints to make your native code more
+robust.
+
+Always check return values for standard functions.  It's sometimes easy
+to forget to check that malloc() return for an error.  Don't make that
+mistake.  (In fact, use JCL_malloc() in the jcl library instead--it will
+check the return value and throw an exception if necessary.)
+
+Always check the return values of JNI functions, or call
+@code{ExceptionOccurred} to check whether an error occurred.  You must
+do this after @emph{every} JNI call.  JNI does not work well when an
+exception has been raised, and can have unpredictable behavior.
+
+Throw exceptions using @code{JCL_ThrowException}.  This guarantees that if
+something is seriously wrong, the exception text will at least get out
+somewhere (even if it is stderr).
+
+Check for null values of @code{jclass}es before you send them to JNI functions.
+JNI does not behave nicely when you pass a null class to it: it
+terminates Java with a "JNI Panic."
+
+In general, try to use functions in @file{native/jni/classpath/jcl.h}.  They
+check exceptions and return values and throw appropriate exceptions.
+
+@node Java Efficiency, Native Efficiency, Robustness, Programming Goals
+@comment node-name, next, previous, up
+@section Java Efficiency
+
+For methods which explicitly throw a @code{NullPointerException} when an
+argument is passed which is null, per a Sun specification, do not write
+code like:
+
+@example
+int 
+strlen (String foo) throws NullPointerException
+@{
+  if (foo == null)
+    throw new NullPointerException ("foo is null");
+  return foo.length ();
+@}
+@end example
+
+Instead, the code should be written as:
+
+@example
+int
+strlen (String foo) throws NullPointerException
+@{
+  return foo.length ();
+@}
+@end example
+
+Explicitly comparing foo to null is unnecessary, as the virtual machine
+will throw a NullPointerException when length() is invoked.  Classpath
+is designed to be as fast as possible -- every optimization, no matter
+how small, is important.
+
+@node Native Efficiency, Security, Java Efficiency, Programming Goals
+@comment node-name, next, previous, up
+@section Native Efficiency
+
+You might think that using native methods all over the place would give
+our implementation of Java speed, speed, blinding speed.  You'd be
+thinking wrong.  Would you believe me if I told you that an empty
+@emph{interpreted} Java method is typically about three and a half times
+@emph{faster} than the equivalent native method?
+
+Bottom line: JNI is overhead incarnate.  In Sun's implementation, even
+the JNI functions you use once you get into Java are slow.
+
+A final problem is efficiency of native code when it comes to things
+like method calls, fields, finding classes, etc.  Generally you should
+cache things like that in static C variables if you're going to use them
+over and over again.  GetMethodID(), GetFieldID(), and FindClass() are
+@emph{slow}.  Classpath provides utility libraries for caching methodIDs
+and fieldIDs in @file{native/jni/classpath/jnilink.h}.  Other native data can
+be cached between method calls using functions found in
+@file{native/jni/classpath/native_state.h}.
+
+Here are a few tips on writing native code efficiently:
+
+Make as few native method calls as possible.  Note that this is not the
+same thing as doing less in native method calls; it just means that, if
+given the choice between calling two native methods and writing a single
+native method that does the job of both, it will usually be better to
+write the single native method.  You can even call the other two native
+methods directly from your native code and not incur the overhead of a
+method call from Java to C.
+
+Cache @code{jmethodID}s and @code{jfieldID}s wherever you can.  String
+lookups are 
+expensive.  The best way to do this is to use the 
+@file{native/jni/classpath/jnilink.h}
+library.  It will ensure that @code{jmethodID}s are always valid, even if the
+class is unloaded at some point.  In 1.1, jnilink simply caches a
+@code{NewGlobalRef()} to the method's underlying class; however, when 1.2 comes
+along, it will use a weak reference to allow the class to be unloaded
+and then re-resolve the @code{jmethodID} the next time it is used.
+
+Cache classes that you need to access often.  jnilink will help with
+this as well.  The issue here is the same as the methodID and fieldID
+issue--how to make certain the class reference remains valid.
+
+If you need to associate native C data with your class, use Paul
+Fisher's native_state library (NSA).  It will allow you to get and set
+state fairly efficiently.  Japhar now supports this library, making
+native state get and set calls as fast as accessing a C variable
+directly.
+
+If you are using native libraries defined outside of Classpath, then
+these should be wrapped by a Classpath function instead and defined
+within a library of their own.  This makes porting Classpath's native
+libraries to new platforms easier in the long run.  It would be nice
+to be able to use Mozilla's NSPR or Apache's APR, as these libraries
+are already ported to numerous systems and provide all the necessary
+system functions as well.
+
+@node Security,  , Native Efficiency, Programming Goals
+@comment  node-name,  next,  previous,  up
+@section Security
+
+Security is such a huge topic it probably deserves its own chapter.
+Most of the current code needs to be audited for security to ensure
+all of the proper security checks are in place within the Java
+platform, but also to verify that native code is reasonably secure and
+avoids common pitfalls, buffer overflows, etc.  A good source for
+information on secure programming is the excellent HOWTO by David
+Wheeler,
+@uref{http://www.dwheeler.com/secure-programs/Secure-Programs-HOWTO/index.html,Secure
+Programming for Linux and Unix HOWTO}.
+
+@node API Compatibility, Specification Sources, Programming Goals, Top
+@comment  node-name,  next,  previous,  up
+@chapter API Compatibility
+
+@menu
+* Serialization::               Serialization
+* Deprecated Methods::          Deprecated methods
+@end menu
+
+@node Serialization, Deprecated Methods, API Compatibility, API Compatibility
+@comment  node-name,  next,  previous,  up
+@section Serialization
+
+Sun has produced documentation concerning much of the information
+needed to make Classpath serializable compatible with Sun
+implementations.  Part of doing this is to make sure that every class
+that is Serializable actually defines a field named serialVersionUID
+with a value that matches the output of serialver on Sun's
+implementation.  The reason for doing this is below.
+
+If a class has a field (of any accessibility) named serialVersionUID
+of type long, that is what serialver uses. Otherwise it computes a
+value using some sort of hash function on the names of all method
+signatures in the .class file.  The fact that different compilers
+create different synthetic method signatures, such as access$0() if an
+inner class needs access to a private member of an enclosing class,
+make it impossible for two distinct compilers to reliably generate the
+same serial #, because their .class files differ. However, once you
+have a .class file, its serial # is unique, and the computation will
+give the same result no matter what platform you execute on.
+
+Serialization compatibility can be tested using tools provided with
+@uref{http://www.kaffe.org/~stuart/japi/,Japitools}.  These
+tools can test binary serialization compatibility and also provide
+information about unknown serialized formats by writing these in XML
+instead.  Japitools is also the primary means of checking API
+compatibility for GNU Classpath with Sun's Java Platform.
+
+@node Deprecated Methods,  , Serialization, API Compatibility
+@comment  node-name,  next,  previous,  up
+@section Deprecated Methods
+
+Sun has a practice of creating ``alias'' methods, where a public or
+protected method is deprecated in favor of a new one that has the same
+function but a different name.  Sun's reasons for doing this vary; as
+an example, the original name may contain a spelling error or it may
+not follow Java naming conventions.
+
+Unfortunately, this practice complicates class library code that calls
+these aliased methods.  Library code must still call the deprecated
+method so that old client code that overrides it continues to work.
+But library code must also call the new version, because new code is
+expected to override the new method.
+
+The correct way to handle this (and the way Sun does it) may seem
+counterintuitive because it means that new code is less efficient than
+old code: the new method must call the deprecated method, and throughout
+the library code calls to the old method must be replaced with calls to
+the new one.
+
+Take the example of a newly-written container laying out a component and
+wanting to know its preferred size.  The Component class has a
+deprecated preferredSize method and a new method, getPreferredSize. 
+Assume that the container is laying out an old component that overrides
+preferredSize and a new component that overrides getPreferredSize.  If
+the container calls getPreferredSize and the default implementation of
+getPreferredSize calls preferredSize, then the old component will have
+its preferredSize method called and new code will have its
+getPreferredSize method called.
+
+Even using this calling scheme, an old component may still be laid out
+improperly if it implements a method, getPreferredSize, that has the
+same signature as the new Component.getPreferredSize.  But that is a
+general problem -- adding new public or protected methods to a
+widely-used class that calls those methods internally is risky, because
+existing client code may have already declared methods with the same
+signature.
+
+The solution may still seem counterintuitive -- why not have the
+deprecated method call the new method, then have the library always call
+the old method?  One problem with that, using the preferred size example
+again, is that new containers, which will use the non-deprecated
+getPreferredSize, will not get the preferred size of old components.
+
+@node Specification Sources, Naming Conventions, API Compatibility, Top
+@comment node-name, next, previous, up
+@chapter Specification Sources
+
+There are a number of specification sources to use when working on
+Classpath.  In general, the only place you'll find your classes
+specified is in the JavaDoc documentation or possibly in the
+corresponding white paper.  In the case of java.lang, java.io and
+java.util, you should look at the Java Language Specification.
+
+Here, however, is a list of specs, in order of canonicality:
+
+@enumerate
+@item
+@uref{http://java.sun.com/docs/books/jls/clarify.html,Clarifications and Amendments to the JLS - 1.1}
+@item
+@uref{http://java.sun.com/docs/books/jls/html/1.1Update.html,JLS Updates
+- 1.1}
+@item
+@uref{http://java.sun.com/docs/books/jls/html/index.html,The 1.0 JLS}
+@item
+@uref{http://java.sun.com/docs/books/vmspec/index.html,JVM spec - 1.1}
+@item
+@uref{http://java.sun.com/products/jdk/1.1/docs/guide/jni/spec/jniTOC.doc.html,JNI spec - 1.1}
+@item
+@uref{http://java.sun.com/products/jdk/1.1/docs/api/packages.html,Sun's javadoc - 1.1}
+(since Sun's is the reference implementation, the javadoc is
+documentation for the Java platform itself.)
+@item
+@uref{http://java.sun.com/products/jdk/1.2/docs/guide/jvmdi/jvmdi.html,JVMDI spec - 1.2},
+@uref{http://java.sun.com/products/jdk/1.2/docs/guide/jni/jni-12.html,JNI spec - 1.2}
+(sometimes gives clues about unspecified things in 1.1; if
+it was not specified accurately in 1.1, then use the spec
+for 1.2; also, we are using JVMDI in this project.)
+@item
+@uref{http://java.sun.com/products/jdk/1.2/docs/api/frame.html,Sun's javadoc - 1.2}
+(sometimes gives clues about unspecified things in 1.1; if
+it was not specified accurately in 1.1, then use the spec
+for 1.2)
+@item
+@uref{http://developer.java.sun.com/developer/bugParade/index.html,The
+Bug Parade}: I have obtained a ton of useful information about how
+things do work and how they *should* work from the Bug Parade just by
+searching for related bugs.  The submitters are very careful about their
+use of the spec.  And if something is unspecified, usually you can find
+a request for specification or a response indicating how Sun thinks it
+should be specified here.
+@end enumerate
+
+You'll notice that in this document, white papers and specification
+papers are more canonical than the JavaDoc documentation.  This is true
+in general.
+
+
+@node Naming Conventions, Character Conversions, Specification Sources, Top
+@comment node-name, next, previous, up
+@chapter Directory and File Naming Conventions
+
+The Classpath directory structure is laid out in the following manner:
+
+@example
+classpath
+ |
+ |---->java
+ |       |
+ |       |-->awt
+ |       |-->io
+ |       |-->lang
+ |       |-->util
+ |       |     |
+ |       |     |--->zip
+ |       |     |--->jar
+ |       |-->net
+ |       |-->etc
+ |
+ |---->gnu
+ |       |
+ |       |-->java
+ |             |
+ |             |-->awt
+ |             |-->lang
+ |             |-->util
+ |             |     |
+ |             |     |-->zip
+ |             |-->etc
+ |
+ |---->native
+         |
+         |-->jni
+         |    |-->classpath
+         |    |-->gtk-peer
+         |    |-->java-io
+         |    |-->java-lang
+         |    |-->java-net
+         |    |-->java-util
+         |    |-->etc
+         |-->cni
+  
+@end example
+
+Here is a brief description of the toplevel directories and their contents.
+
+@table @b
+
+@item java
+Contains the source code to the Java packages that make up the core
+class library.  Because this is the public interface to Java, it is
+important that the public classes, interfaces, methods, and variables
+are exactly the same as specified in Sun's documentation.  The directory
+structure is laid out just like the java package names.  For example,
+the class java.util.zip would be in the directory java-util.
+
+@item gnu/java
+Internal classes (roughly analogous to Sun's sun.* classes) should go
+under the @file{gnu/java} directory.  Classes related to a particular public
+Java package should go in a directory named like that package.  For
+example, classes related to java.util.zip should go under a directory
+@file{gnu/java/util/zip}.  Sub-packages under the main package name are
+allowed.  For classes spanning multiple public Java packages, pick an
+appropriate name and see what everybody else thinks.
+
+@item native
+This directory holds native code needed by the public Java packages.
+Each package has its own subdirectory, which is the ``flattened'' name
+of the package.  For example, native method implementations for
+java.util.zip should go in @file{native/classpath/java-util}.  Classpath
+actually includes an all Java version of the zip classes, so no native
+code is required.
+
+@end table
+
+Each person working on a package get's his or her own ``directory
+space'' underneath each of the toplevel directories.  In addition to the
+general guidelines above, the following standards should be followed:
+
+@itemize @bullet
+
+@item
+Classes that need to load native code should load a library with the
+same name as the flattened package name, with all hyphens removed.  For
+example, the native library name specified in LoadLibrary for
+java-util would be ``javautil''.
+
+@item
+Each package has its own shared library for native code (if any).
+
+@item
+The main native method implementation for a given method in class should
+go in a file with the same name as the class with a ``.c'' extension.
+For example, the JNI implementation of the native methods in
+java.net.InetAddress would go in @file{native/jni/java-net/InetAddress.c}.
+``Internal'' native functions called from the main native method can
+reside in files of any name.
+@end itemize
+
+@node Character Conversions, Localization, Naming Conventions, Top
+@comment node-name, next, previous, up
+@chapter Character Conversions
+
+Java uses the Unicode character encoding system internally.  This is a
+sixteen bit (two byte) collection of characters encompassing most of the
+world's written languages.  However, Java programs must often deal with
+outside interfaces that are byte (eight bit) oriented.  For example, a
+Unix file, a stream of data from a network socket, etc.  Beginning with
+Java 1.1, the @code{Reader} and @code{Writer} classes provide functionality
+for dealing with character oriented streams.  The classes 
+@code{InputStreamReader} and @code{OutputStreamWriter} bridge the gap
+between byte streams and character streams by converting bytes to 
+Unicode characters and vice versa.
+
+In Classpath, @code{InputStreamReader} and @code{OutputStreamWriter}
+rely on an internal class called @code{gnu.java.io.EncodingManager} to load
+translators that perform the actual conversion.  There are two types of
+converters, encoders and decoders.  Encoders are subclasses of
+@code{gnu.java.io.encoder.Encoder}.  This type of converter takes a Java
+(Unicode) character stream or buffer and converts it to bytes using
+a specified encoding scheme.  Decoders are a subclass of 
+@code{gnu.java.io.decoder.Decoder}.  This type of converter takes a 
+byte stream or buffer and converts it to Unicode characters.  The
+@code{Encoder} and @code{Decoder} classes are subclasses of
+@code{Writer} and @code{Reader} respectively, and so can be used in
+contexts that require character streams, but the Classpath implementation
+currently does not make use of them in this fashion.
+
+The @code{EncodingManager} class searches for requested encoders and
+decoders by name.  Since encoders and decoders are separate in Classpath,
+it is possible to have a decoder without an encoder for a particular 
+encoding scheme, or vice versa.  @code{EncodingManager} searches the
+package path specified by the @code{file.encoding.pkg} property.  The
+name of the encoder or decoder is appended to the search path to
+produce the required class name.  Note that @code{EncodingManager} knows
+about the default system encoding scheme, which it retrieves from the
+system property @code{file.encoding}, and it will return the proper
+translator for the default encoding if no scheme is specified.  Also, the 
+Classpath standard translator library, which is the @code{gnu.java.io} package, 
+is automatically appended to the end of the path.
+
+For efficiency, @code{EncodingManager} maintains a cache of translators
+that it has loaded.  This eliminates the need to search for a commonly
+used translator each time it is requested.
+
+Finally, @code{EncodingManager} supports aliasing of encoding scheme names.
+For example, the ISO Latin-1 encoding scheme can be referred to as
+''8859_1'' or ''ISO-8859-1''.  @code{EncodingManager} searches for 
+aliases by looking for the existence of a system property called
+@code{gnu.java.io.encoding_scheme_alias.<encoding name>}.  If such a
+property exists.  The value of that property is assumed to be the
+canonical name of the encoding scheme, and a translator with that name is 
+looked up instead of one with the original name.
+
+Here is an example of how @code{EncodingManager} works.  A class requests
+a decoder for the ''UTF-8'' encoding scheme by calling
+@code{EncodingManager.getDecoder("UTF-8")}.  First, an alias is searched
+for by looking for the system property 
+@code{gnu.java.io.encoding_scheme_alias.UTF-8}.  In our example, this
+property exists and has the value ''UTF8''.  That is the actual
+decoder that will be searched for.  Next, @code{EncodingManager} looks
+in its cache for this translator.  Assuming it does not find it, it
+searches the translator path, which is this example consists only of
+the default @code{gnu.java.io}.  The ''decoder'' package name is 
+appended since we are looking for a decoder.  (''encoder'' would be 
+used if we were looking for an encoder).  Then name name of the translator
+is appended.  So @code{EncodingManager} attempts to load a translator
+class called @code{gnu.java.io.decoder.UTF8}.  If that class is found,
+an instance of it is returned.  If it is not found, a
+@code{UnsupportedEncodingException}.
+
+To write a new translator, it is only necessary to subclass 
+@code{Encoder} and/or @code{Decoder}.  Only a handful of abstract
+methods need to be implemented.  In general, no methods need to be
+overridden.  The needed methods calculate the number of bytes/chars
+that the translation will generate, convert buffers to/from bytes,
+and read/write a requested number of characters to/from a stream.
+
+Many common encoding schemes use only eight bits to encode characters.
+Writing a translator for these encodings is very easy.  There are 
+abstract translator classes @code{gnu.java.io.decode.DecoderEightBitLookup}
+and @code{gnu.java.io.encode.EncoderEightBitLookup}.  These classes
+implement all of the necessary methods.  All that is necessary to
+create a lookup table array that maps bytes to Unicode characters and
+set the class variable @code{lookup_table} equal to it in a static
+initializer.  Also, a single constructor that takes an appropriate
+stream as an argument must be supplied.  These translators are
+exceptionally easy to create and there are several of them supplied
+in the Classpath distribution.
+
+Writing multi-byte or variable-byte encodings is more difficult, but
+often not especially challenging.  The Classpath distribution ships with
+translators for the UTF8 encoding scheme which uses from one to three
+bytes to encode Unicode characters.  This can serve as an example of
+how to write such a translator.
+
+Many more translators are needed.  All major character encodings should
+eventually be supported.
+
+@node Localization,  , Character Conversions, Top
+@comment node-name, next, previous, up
+@chapter Localization
+
+There are many parts of the Java standard runtime library that must
+be customized to the particular locale the program is being run in.
+These include the parsing and display of dates, times, and numbers;
+sorting words alphabetically; breaking sentences into words, etc.
+In general, Classpath uses general classes for performing these tasks,
+and customizes their behavior with configuration data specific to a
+given locale.
+
+@menu
+* String Collation::            Sorting strings in different locales
+* Break Iteration::             Breaking up text into words, sentences, and lines
+* Date Formatting and Parsing::  Locale specific date handling
+* Decimal/Currency Formatting and Parsing::  Local specific number handling
+@end menu
+
+In Classpath, all locale specific data is stored in a 
+@code{ListResourceBundle} class in the package @code{gnu/java/locale}.
+The basename of the bundle is @code{LocaleInformation}.  See the
+documentation for the @code{java.util.ResourceBundle} class for details
+on how the specific locale classes should be named.
+
+@code{ListResourceBundle}'s are used instead of 
+@code{PropertyResourceBundle}'s because data more complex than simple
+strings need to be provided to configure certain Classpath components.
+Because @code{ListResourceBundle} allows an arbitrary Java object to
+be associated with a given configuration option, it provides the
+needed flexibility to accomodate Classpath's needs.
+
+Each Java library component that can be localized requires that certain
+configuration options be specified in the resource bundle for it.  It is
+important that each and every option be supplied for a specific 
+component or a critical runtime error will most likely result.
+
+As a standard, each option should be assigned a name that is a string.
+If the value is stored in a class or instance variable, then the option
+should name should have the name name as the variable.  Also, the value
+associated with each option should be a Java object with the same name
+as the option name (unless a simple scalar value is used).  Here is an
+example:
+
+A class loads a value for the @code{format_string} variable from the
+resource bundle in the specified locale.  Here is the code in the
+library class:
+
+@example
+  ListResourceBundle lrb = 
+    ListResourceBundle.getBundle ("gnu/java/locale/LocaleInformation", locale);
+  String format_string = lrb.getString ("format_string");
+@end example
+
+In the actual resource bundle class, here is how the configuration option
+gets defined:
+
+@example
+/**
+  * This is the format string used for displaying values
+  */
+private static final String format_string = "%s %d %i";
+
+private static final Object[][] contents =
+@{
+  @{ "format_string", format_string @}
+@};
+@end example
+
+Note that each variable should be @code{private}, @code{final}, and
+@code{static}.  Each variable should also have a description of what it
+does as a documentation comment.  The @code{getContents()} method returns
+the @code{contents} array.
+
+There are many functional areas of the standard class library that are
+configured using this mechanism.  A given locale does not need to support
+each functional area.  But if a functional area is supported, then all
+of the specified entries for that area must be supplied.  In order to
+determine which functional areas are supported, there is a special key
+that is queried by the affected class or classes.  If this key exists, 
+and has a value that is a @code{Boolean} object wrappering the
+@code{true} value, then full support is assumed.  Otherwise it is
+assumed that no support exists for this functional area.  Every class
+using resources for configuration must use this scheme and define a special
+scheme that indicates the functional area is supported.  Simply checking
+for the resource bundle's existence is not sufficient to ensure that a
+given functional area is supported.
+
+The following sections define the functional areas that use resources
+for locale specific configuration in GNU Classpath.  Please refer to the 
+documentation for the classes mentioned for details on how these values 
+are used.  You may also wish to look at the source file for 
+@file{gnu/java/locale/LocaleInformation_en} as an example.
+
+@node String Collation, Break Iteration, Localization, Localization
+@comment node-name, next, previous, up
+@section String Collation
+
+Collation involves the sorting of strings.  The Java class library provides
+a public class called @code{java.text.RuleBasedCollator} that performs
+sorting based on a set of sorting rules.
+
+@itemize @bullet
+@item RuleBasedCollator - A @code{Boolean} wrappering @code{true} to indicate
+that this functional area is supported.
+@item collation_rules - The rules the specify how string collation is to
+be performed.
+@end itemize
+
+Note that some languages might be too complex for @code{RuleBasedCollator}
+to handle.  In this case an entirely new class might need to be written in
+lieu of defining this rule string.
+
+@node Break Iteration, Date Formatting and Parsing, String Collation, Localization
+@comment node-name, next, previous, up
+@section Break Iteration
+
+The class @code{java.text.BreakIterator} breaks text into words, sentences,
+and lines.  It is configured with the following resource bundle entries:
+
+@itemize @bullet
+@item BreakIterator - A @code{Boolean} wrappering @code{true} to indicate
+that this functional area is supported.
+@item word_breaks - A @code{String} array of word break character sequences.
+@item sentence_breaks - A @code{String} array of sentence break character
+sequences.
+@item line_breaks - A @code{String} array of line break character sequences.
+@end itemize
+
+@node Date Formatting and Parsing, Decimal/Currency Formatting and Parsing, Break Iteration, Localization
+@comment node-name, next, previous, up
+@section Date Formatting and Parsing
+
+Date formatting and parsing is handled by the 
+@code{java.text.SimpleDateFormat} class in most locales.  This class is
+configured by attaching an instance of the @code{java.text.DateFormatSymbols}
+class.  That class simply reads properties from our locale specific
+resource bundle.  The following items are required (refer to the 
+documentation of the @code{java.text.DateFormatSymbols} class for details
+io what the actual values should be):
+
+@itemize @bullet
+@item DateFormatSymbols - A @code{Boolean} wrappering @code{true} to indicate
+that this functional area is supported.
+@item months - A @code{String} array of month names.
+@item shortMonths - A @code{String} array of abbreviated month names.
+@item weekdays - A @code{String} array of weekday names.
+@item shortWeekdays - A @code{String} array of abbreviated weekday names.
+@item ampms - A @code{String} array containing AM/PM names.
+@item eras - A @code{String} array containing era (i.e., BC/AD) names.
+@item zoneStrings - An array of information about valid timezones for this 
+locale.
+@item localPatternChars - A @code{String} defining date/time pattern symbols.
+@item shortDateFormat - The format string for dates used by 
+@code{DateFormat.SHORT}
+@item mediumDateFormat - The format string for dates used by 
+@code{DateFormat.MEDIUM}
+@item longDateFormat - The format string for dates used by 
+@code{DateFormat.LONG}
+@item fullDateFormat - The format string for dates used by 
+@code{DateFormat.FULL}
+@item shortTimeFormat - The format string for times used by 
+@code{DateFormat.SHORT}
+@item mediumTimeFormat - The format string for times used by 
+@code{DateFormat.MEDIUM}
+@item longTimeFormat - The format string for times used by 
+@code{DateFormat.LONG}
+@item fullTimeFormat - The format string for times used by 
+@code{DateFormat.FULL}
+@end itemize
+
+Note that it may not be possible to use this mechanism for all locales.
+In those cases a special purpose class may need to be written to handle 
+date/time processing.
+
+@node Decimal/Currency Formatting and Parsing,  , Date Formatting and Parsing, Localization
+@comment node-name, next, previous, up
+@section Decimal/Currency Formatting and Parsing
+
+@code{NumberFormat} is an abstract class for formatting and parsing numbers.
+The class @code{DecimalFormat} provides a concrete subclass that handles
+this is in a locale independent manner.  As with @code{SimpleDateFormat},
+this class gets information on how to format numbers from a class that
+wrappers a collection of locale specific formatting values.  In this case,
+the class is @code{DecimalFormatSymbols}.  That class reads its default
+values for a locale from the resource bundle.  The required entries are:
+
+@itemize @bullet
+@item DecimalFormatSymbols - A @code{Boolean} wrappering @code{true} to 
+indicate that this functional area is supported.
+@item currencySymbol - The string representing the local currency.
+@item intlCurrencySymbol - The string representing the local currency in an
+international context.
+@item decimalSeparator - The character to use as the decimal point as a
+@code{String}.
+@item digit - The character used to represent digits in a format string,
+as a @code{String}.
+@item exponential - The char used to represent the exponent separator of a 
+number written in scientific notation, as a @code{String}.
+@item groupingSeparator - The character used to separate groups of numbers
+in a large number, such as the ``,'' separator for thousands in the US, as
+a @code{String}.
+@item infinity - The string representing infinity.
+@item NaN - The string representing the Java not a number value.
+@item minusSign - The character representing the negative sign, as a 
+@code{String}.
+@item monetarySeparator - The decimal point used in currency values, as a
+@code{String}.
+@item patternSeparator - The character used to separate positive and 
+negative format patterns, as a @code{String}.
+@item percent - The percent sign, as a @code{String}.
+@item perMill - The per mille sign, as a @code{String}.
+@item zeroDigit - The character representing the digit zero, as a @code{String}.
+@end itemize
+
+Note that several of these values are an individual character.  These should
+be wrappered in a @code{String} at character position 0, not in a
+@code{Character} object.
+
+@bye
+
diff --git a/libjava/classpath/doc/cp-tools.info b/libjava/classpath/doc/cp-tools.info
new file mode 100644
index 000000000..bb59012b2
--- /dev/null
+++ b/libjava/classpath/doc/cp-tools.info
@@ -0,0 +1,3177 @@
+This is cp-tools.info, produced by makeinfo version 4.13 from
+/home/jakub/gcc-4.6.4/gcc-4.6.4/libjava/classpath/doc/cp-tools.texinfo.
+
+This file documents the Tools included in a standard distribution of
+the GNU Classpath project deliverables.
+
+   Copyright (C) 2006, 2007 Free Software Foundation, Inc.
+
+INFO-DIR-SECTION GNU Libraries
+START-INFO-DIR-ENTRY
+* Classpath Tools: (cp-tools).  GNU Classpath Tools Guide
+END-INFO-DIR-ENTRY
+
+
+File: cp-tools.info,  Node: Top,  Next: Applet Tools,  Prev: (dir),  Up: (dir)
+
+GNU Classpath Tools Guide
+*************************
+
+This document contains important information you need to know in order
+to use the tools included in the GNU Classpath project deliverables.
+
+   The Tools aim at providing a free replacement, similar in their
+behavior, to their counter-parts found in the Reference Implementation
+(RI) of the Java Software Development Kit (SDK).
+
+* Menu:
+
+* Applet Tools::               Work with applets
+* Security Tools::             Work securely with Java applications
+* Other Tools::                Other tools in classpath
+* I18N Issues::                How to add support for non-English languages
+
+ --- The Detailed Node Listing ---
+
+Applet Tools
+
+* appletviewer Tool::          Load applets
+* gcjwebplugin::               Load applets in a web browser
+
+Security Tools
+
+* jarsigner Tool::             Sign and verify .JAR files
+* keytool Tool::               Manage private keys and public certificates
+
+jarsigner Tool
+
+* Common jarsigner Options::   Options used when signing or verifying a file
+* Signing Options::            Options only used when signing a .JAR file
+* Verification Options::       Options only used when verifying a .JAR file
+
+keytool Tool
+
+* Getting Help::               How to get help with keytool commands
+* Common keytool Options::     Options used in more than one command
+* Distinguished Names::        X.500 Distinguished Names used in certificates
+* Add/Update Commands::        Commands for adding data to a Key Store
+* Export Commands::            Commands for exporting data from a Key Store
+* Display Commands::           Commands for displaying data in a Key Store
+* Management Commands::        Commands for managing a Key Store
+
+Add/Update Commands
+
+* Command -genkey::            Generate private key and self-signed certificate
+* Command -import::            Import certificates and certificate replies
+* Command -selfcert::          Generate self-signed certificate
+* Command -cacert::            Import a CA Trusted Certificate
+* Command -identitydb::        Import JDK-1 style identities
+
+Export Commands
+
+* Command -certreq::           Generate Certificate Signing Requests (CSR)
+* Command -export::            Export a certificate in a Key Store
+
+Display Commands
+
+* Command -list::              Display information about one or all Aliases
+* Command -printcert::         Print a certificate or a certificate fingerprint
+
+Management Commands
+
+* Command -keyclone::          Clone a Key Entry in a Key Store
+* Command -storepasswd::       Change the password protecting a Key Store
+* Command -keypasswd::         Change the password protecting a Key Entry
+* Command -delete::            Remove an entry in a Key Store
+
+Other Tools
+
+* jar Tool::                   Archive tool for Java archives
+* javah Tool::                 A java header compiler
+* gcjh Tool::                  A java header compiler (old version)
+* native2ascii Tool::          An encoding converter
+* orbd Tool::                  An object request broker daemon
+* serialver Tool::             A serial version command
+* rmid Tool::                  RMI activation daemon
+* rmiregistry Tool::           Remote object registry
+* tnameserv Tool::             Naming service
+* gjdoc Tool::                 Documenation generator tool.
+
+Generating HTML Documentation
+
+* Invoking the Standard Doclet::   How to generate HTML documentation.
+* Invoking a Custom Doclet::       How to run third-party and other
+                                   built-in Doclets.
+
+* Option Summary by Type::         Brief list of all options, grouped by type.
+* Gjdoc Option Summary::           List of all options accepted by Gjdoc.
+
+* Source Set Options::      Select the set of source codes to run Gjdoc on.
+* Source Format Options::   Specify the format of the source codes to document.
+
+* Interlinking Options::    Connection your documentation with other projects.
+* Output Control Options::  Specify the target directory and locale, and more.
+* Generation Options::      Select which pieces of information to generate.
+* Decoration Options::      Add or modify some titles, headers and footers or
+                            override/amend static resources like stylesheets.
+* Taglet Options::          Define your own javadoc @tags.
+
+* Virtual Machine Options:: Controlling the kind of output:
+                            an executable, object files, assembler files,
+                            or preprocessed source.
+* Verbosity Options::
+* Doclet Options::
+
+* Other Doclets::           Generating Other Output Types.
+
+* Built-in Doclets::        Using the Built-in Doclets.
+* Using XmlDoclet::
+* Using TexiDoclet::
+* Using IspellDoclet::
+* Using DebugDoclet::
+
+* Third-party Doclets::     Using Third-Party Doclets.
+* DocBook Doclet::
+* PDFDoclet::
+* JUnitDoclet::
+
+* Gjdoc Concepts::          Advanced Concepts.
+* Writing Doclets::
+
+* Doclet Invocation Interface::    Implementing the Doclet Invocation Interface
+* Using AbstractDoclet::           Deriving Your Doclet from AbstractDoclet.
+* GNU Doclet SPI::                 Preparing the GNU Doclet Service Provider
+                                   Interface.
+
+* Taglets::                        Adding Custom Tags to the Documentation.
+* XHTML Fragments::                Well-Formed Documentation Fragments.
+* First Sentence Detector::        How Gjdoc Determines where the First
+                                   Sentence Ends.
+* Adding Custom Resources::        Adding Images and Other Resources.
+
+I18N Issues
+
+* Language Resources::         Where resources are located
+* Message Formats::            How messages are internationalized
+
+
+File: cp-tools.info,  Node: Applet Tools,  Next: Security Tools,  Prev: Top,  Up: Top
+
+1 Applet Tools
+**************
+
+Two Applet Tools are available with GNU Classpath: appletviewer and
+gcjwebplugin.
+
+   To avoid conflicts with other implementations, the appletviewer
+executable is called "gappletviewer".
+
+* Menu:
+
+* appletviewer Tool::          Load applets
+* gcjwebplugin::               Load applets in a web browser
+
+   If while using these tools you think you found a bug, then please
+report it at classpath-bugs
+(http://www.gnu.org/software/classpath/bugs.html).
+
+
+File: cp-tools.info,  Node: appletviewer Tool,  Next: gcjwebplugin,  Prev: Applet Tools,  Up: Applet Tools
+
+1.1 The `appletviewer' Tool
+===========================
+
+SYNOPSIS
+
+   appletviewer [OPTION]... URL...
+appletviewer [OPTION]... `-code' CODE
+appletviewer [OPTION]... `-plugin' INPUT,OUTPUT
+
+   DESCRIPTION The `appletviewer' tool loads and runs an applet.
+
+   Use the first form to test applets specified by tag.  The URL should
+resolve to an HTML document from which the `appletviewer' will extract
+applet tags.  The APPLET, EMBED and OBJECT tags are supported.  If a
+given document contains multiple applet tags, all the applets will be
+loaded, with each applet appearing in its own window.  Likewise, when
+multiple URLs are specified, each applet tag instance is given its own
+window.  If a given document contains no recognized tags the
+`appletviewer' does nothing.
+
+     appletviewer http://www.gnu.org/software/classpath/
+
+   Use the second form to test an applet in development.  This form
+allows applet tag attributes to be supplied on the command line.  Only
+one applet may be specified using the `-code' option.  The `-code'
+option overrides the URL form - any URLs specified will be ignored.
+
+     appletviewer -code Test.class -param datafile,data.txt
+
+   `gcjwebplugin' uses the third form to communicate with the
+`appletviewer' through named pipes.
+
+   URL OPTIONS
+`-debug'
+     This option is not yet implemented but is provided for
+     compatibility.
+
+`-encoding CHARSET'
+     Use this option to specify an alternate character encoding for the
+     specified HTML page.
+
+
+   APPLET TAG OPTIONS
+`-code CODE'
+     Use the `-code' option to specify the value of the applet tag CODE
+     attribute.
+
+`-codebase CODEBASE'
+     Use the `-codebase' option to specify the value of the applet tag
+     CODEBASE attribute.
+
+`-archive ARCHIVE'
+     Use the `-archive' option to specify the value of the applet tag
+     ARCHIVE attribute.
+
+`-width WIDTH'
+     Use the `-width' option to specify the value of the applet tag
+     WIDTH attribute.
+
+`-height HEIGHT'
+     Use the `-height' option to specify the value of the applet tag
+     HEIGHT attribute.
+
+`-param NAME,VALUE'
+     Use the `-param' option to specify values for the NAME and VALUE
+     attributes of an applet PARAM tag.
+
+
+   PLUGIN OPTION
+`-plugin INPUT,OUTPUT'
+     `gcjwebplugin' uses the `-plugin' option to specify the named pipe
+     the `appletviewer' should use for receiving commands (INPUT) and
+     the one it should use for sending commands to `gcjwebplugin'
+     (OUTPUT).
+
+
+   DEBUGGING OPTION
+`-verbose'
+     Use the `-verbose' option to have the `appletviewer' print
+     debugging messages.
+
+
+   STANDARD OPTIONS
+
+`-help'
+     Use the `-help' option to have the `appletviewer' print a usage
+     message, then exit.
+
+`-version'
+     Use the `-version' option to have the `appletviewer' print its
+     version, then exit.
+
+`-JOPTION'
+     Use the `-J' option to pass OPTION to the virtual machine that
+     will run the `appletviewer'.  Unlike other options, there must not
+     be a space between the `-J' and OPTION.
+
+
+
+File: cp-tools.info,  Node: gcjwebplugin,  Prev: appletviewer Tool,  Up: Applet Tools
+
+1.2 The `gcjwebplugin' Tool
+===========================
+
+`gcjwebplugin' is a plugin that adds applet support to web browsers.
+Currently `gcjwebplugin' only supports Mozilla-based browsers (e.g.,
+Firefox, Galeon, Mozilla).
+
+
+File: cp-tools.info,  Node: Security Tools,  Next: Other Tools,  Prev: Applet Tools,  Up: Top
+
+2 Security Tools
+****************
+
+Two Security Tools are available with GNU Classpath: `jarsigner' and
+`keytool'.
+
+   To avoid conflicts with other implementations, the jarsigner
+executable is called `gjarsigner' and the keytool executable is called
+`gkeytool'.
+
+* Menu:
+
+* jarsigner Tool::             Sign and verify .JAR files
+* keytool Tool::               Manage private keys and public certificates
+
+   If while using these tools you think you found a bug, then please
+report it at classpath-bugs
+(http://www.gnu.org/software/classpath/bugs.html).
+
+
+File: cp-tools.info,  Node: jarsigner Tool,  Next: keytool Tool,  Prev: Security Tools,  Up: Security Tools
+
+2.1 The `jarsigner' Tool
+========================
+
+The `jarsigner' tool is invoked from the command line, in one of two
+forms, as follows:
+
+     jarsigner [OPTION]... FILE ALIAS
+
+     jarsigner `-verify' [OPTION]... FILE
+
+   When the first form is used, the tool signs the designated JAR file.
+The second form, on the other hand, is used to verify a previously
+signed JAR file.
+
+   FILE is the .JAR file to process; i.e., to sign if the first syntax
+form is used, or to verify if the second syntax form is used instead.
+
+   ALIAS must be a known Alias of a Key Entry in the designated Key
+Store. The private key material associated with this Alias is then used
+for signing the designated .JAR file.
+
+* Menu:
+
+* Common jarsigner Options::   Options used when signing or verifying a file
+* Signing Options::            Options only used when signing a .JAR file
+* Verification Options::       Options only used when verifying a .JAR file
+
+
+File: cp-tools.info,  Node: Common jarsigner Options,  Next: Signing Options,  Prev: jarsigner Tool,  Up: jarsigner Tool
+
+2.1.1 Common options
+--------------------
+
+The following options may be used when the tool is used for either
+signing, or verifying, a .JAR file.
+
+`-verbose'
+     Use this option to force the tool to generate more verbose
+     messages, during its processing.
+
+`-internalsf'
+     When present, the tool will include -which otherwise it does not-
+     the `.SF' file in the `.DSA' generated file.
+
+`-sectionsonly'
+     When present, the tool will include in the `.SF' generated file
+     -which otherwise it does not- a header containing a hash of the
+     whole manifest file.  When that header is included, the tool can
+     quickly check, during verification, if the hash (in the header)
+     matches or not the manifest file.
+
+`-provider PROVIDER_CLASS_NAME'
+     A fully qualified class name of a Security Provider to add to the
+     current list of Security Providers already installed in the JVM
+     in-use. If a provider class is specified with this option, and was
+     successfully added to the runtime -i.e. it was not already
+     installed- then the tool will attempt to remove this Security
+     Provider before exiting.
+
+`-help'
+     Prints a help text similar to this one.
+
+
+
+File: cp-tools.info,  Node: Signing Options,  Next: Verification Options,  Prev: Common jarsigner Options,  Up: jarsigner Tool
+
+2.1.2 Signing options
+---------------------
+
+The following options may be specified when using the tool for signing
+purposes.
+
+`-keystore URL'
+     Use this option to specify the location of the key store to use.
+     The default value is a file URL referencing the file named
+     `.keystore' located in the path returned by the call to
+     `java.lang.System#getProperty(String)' using `user.home' as
+     argument.
+
+     If a URL was specified, but was found to be malformed -e.g.
+     missing protocol element- the tool will attempt to use the URL
+     value as a file-name (with absolute or relative path-name) of a
+     key store -as if the protocol was `file:'.
+
+`-storetype STORE_TYPE'
+     Use this option to specify the type of the key store to use. The
+     default value, if this option is omitted, is that of the property
+     `keystore.type' in the security properties file, which is obtained
+     by invoking the static method call `getDefaultType()' in
+     `java.security.KeyStore'.
+
+`-storepass PASSWORD'
+     Use this option to specify the password which will be used to
+     unlock the key store. If this option is missing, the User will be
+     prompted to provide a password.
+
+`-keypass PASSWORD'
+     Use this option to specify the password which the tool will use to
+     unlock the Key Entry associated with the designated Alias.
+
+     If this option is omitted, the tool will first attempt to unlock
+     the Key Entry using the same password protecting the key store. If
+     this fails, you will then be prompted to provide a password.
+
+`-sigfile NAME'
+     Use this option to designate a literal that will be used to
+     construct file names for both the `.SF' and `.DSA' signature
+     files. These files  will be generated, by the tool, and placed in
+     the `META-INF' directory of the signed JAR.  Permissible
+     characters for NAME must be in the range "a-zA-Z0-9_-".  All
+     characters will be converted to upper-case ones.
+
+     If this option is missing, the first eight characters of the ALIAS
+     argument will be used. When this is the case, any character in
+     ALIAS that is outside the permissible range of characters will be
+     replaced by an underscore.
+
+`-signedjar FILE'
+     Use this option to specify the file name of the signed JAR. If
+     this option is omitted, then the signed JAR will be named the same
+     as FILE; i.e., the input JAR file will be replaced with the signed
+     copy.
+
+
+
+File: cp-tools.info,  Node: Verification Options,  Prev: Signing Options,  Up: jarsigner Tool
+
+2.1.3 Verification options
+--------------------------
+
+The following options may be specified when using the tool for
+verification purposes.
+
+`-verify'
+     Use this option to indicate that the tool is to be used for
+     verification purposes.
+
+`-certs'
+     This option is used in conjunction with the `-verbose' option.
+     When present, along with the `-verbose' option, the tool will
+     print more detailed information about the certificates of the
+     signer(s) being processed.
+
+
+
+File: cp-tools.info,  Node: keytool Tool,  Prev: jarsigner Tool,  Up: Security Tools
+
+2.2 The `keytool' Tool
+======================
+
+Cryptographic credentials, in a Java environment, are usually stored in
+a Key Store. The Java SDK specifies a Key Store as a persistent
+container of two types of objects: Key Entries and Trusted
+Certificates. The security tool `keytool' is a Java-based application
+for managing those types of objects.
+
+   A Key Entry represents the private key part of a key-pair used in
+Public-Key Cryptography, and a signed X.509 certificate which
+authenticates the public key part for a known entity; i.e. the owner of
+the key-pair. The X.509 certificate itself contains the public key part
+of the key-pair.
+
+   A Trusted Certificate is a signed X.509 certificate issued by a
+trusted entity. The Trust in this context is relative to the User of
+the `keytool'. In other words, the existence of a Trusted Certificate
+in the Key Store processed by a `keytool' command implies that the User
+trusts the Issuer of that Trusted Certificate to also sign, and hence
+authenticates, other Subjects the tool may process.
+
+   Trusted Certificates are important because they allow the tool to
+mechanically construct Chains of Trust starting from one of the Trusted
+Certificates in a Key Store and ending with a certificate whose Issuer
+is potentially unknown. A valid chain is an ordered list, starting with
+a Trusted Certificate (also called the anchor), ending with the target
+certificate, and satisfying the condition that the Subject of
+certificate `#i' is the Issuer of certificate `#i + 1'.
+
+   The `keytool' is invoked from the command line as follows:
+
+     keytool [COMMAND] ...
+
+   Multiple COMMANDs may be specified at once, each complete with its
+own options. `keytool' will parse all the arguments, before processing,
+and executing, each `COMMAND'. If an exception occurs while executing
+one COMMAND `keytool' will abort. Note however that because the
+implementation of the tool uses code to parse command line options that
+also supports GNU-style options, you have to separate each command
+group with a double-hyphen; e.g
+
+     keytool -list -- -printcert -alias mykey
+
+   Here is a summary of the commands supported by the tool:
+
+  1. Add/Update commands
+    `-genkey [OPTION]...'
+          Generate a new Key Entry, eventually creating a new key store.
+
+    `-import [OPTION]...'
+          Add, to a key store, Key Entries (private keys and
+          certificate chains authenticating the public keys) and
+          Trusted Certificates (3rd party certificates which can be
+          used as Trust Anchors when building chains-of-trust).
+
+    `-selfcert [OPTION]...'
+          Generate a new self-signed Trusted Certificate.
+
+    `-cacert [OPTION]...'
+          Import a CA Trusted Certificate.
+
+    `-identitydb [OPTION]...'
+          NOT IMPLEMENTED YET.
+          Import a JDK 1.1 style Identity Database.
+
+  2. Export commands
+    `-certreq [OPTION]...'
+          Issue a Certificate Signing Request (CSR) which can be then
+          sent to a Certification Authority (CA) to issue a certificate
+          signed (by the CA) and authenticating the Subject of the
+          request.
+
+    `-export [OPTION]...'
+          Export a certificate from a key store.
+
+  3. Display commands
+    `-list [OPTION]...'
+          Print one or all certificates in a key store to `STDOUT'.
+
+    `-printcert [OPTION]...'
+          Print a human-readable form of a certificate, in a designated
+          file, to `STDOUT'.
+
+  4. Management commands
+    `-keyclone [OPTION]...'
+          Clone a Key Entry in a key store.
+
+    `-storepasswd [OPTION]...'
+          Change the password protecting a key store.
+
+    `-keypasswd [OPTION]...'
+          Change the password protecting a Key Entry in a key store.
+
+    `-delete [OPTION]...'
+          Delete a Key Entry or a Trusted Certificate from a key store.
+
+* Menu:
+
+* Getting Help::               How to get help with keytool commands
+* Common keytool Options::     Options used in more than one command
+* Distinguished Names::        X.500 Distinguished Names used in certificates
+* Add/Update Commands::        Commands for adding data to a Key Store
+* Export Commands::            Commands for exporting data from a Key Store
+* Display Commands::           Commands for displaying data in a Key Store
+* Management Commands::        Commands for managing a Key Store
+
+
+File: cp-tools.info,  Node: Getting Help,  Next: Common keytool Options,  Prev: keytool Tool,  Up: keytool Tool
+
+2.2.1 Getting help
+------------------
+
+To get a general help text about the tool, use the `-help' option; e.g.
+
+     `keytool -help'
+
+   To get more specific help text about one of the tool's command use
+the `-help' option for that command; e.g.
+
+     `keytool -genkey -help'
+
+   In both instances, the tool will print a help text and then will
+exit the running JVM.
+
+   It is worth noting here that the help messages printed by the tool
+are I18N-ready. This means that if/when the contents of the tool's
+Message Bundle properties file are available in languages other than
+English, you may see those messages in that language.
+
+
+File: cp-tools.info,  Node: Common keytool Options,  Next: Distinguished Names,  Prev: Getting Help,  Up: keytool Tool
+
+2.2.2 Common options
+--------------------
+
+The following `OPTION's are used in more than one `COMMAND'. They are
+described here to reduce redundancy.
+
+`-alias ALIAS'
+     Every entry, be it a Key Entry or a Trusted Certificate, in a key
+     store is uniquely identified by a user-defined ALIAS string. Use
+     this option to specify the ALIAS to use when referring to an entry
+     in the key store. Unless specified otherwise, a default value of
+     `mykey' shall be used when this option is omitted from the command
+     line.
+
+`-keyalg ALGORITHM'
+     Use this option to specify the canonical name of the key-pair
+     generation algorithm. The default value for this option is `DSS'
+     (a synonym for the Digital Signature Algorithm also known as DSA).
+
+`-keysize SIZE'
+     Use this option to specify the number of bits of the shared
+     modulus (for both the public and private keys) to use when
+     generating new keys. A default value of `1024' will be used if
+     this option is omitted from the command line.
+
+`-validity DAY_COUNT'
+     Use this option to specify the number of days a newly generated
+     certificate will be valid for. The default value is `90' (days) if
+     this option is omitted from the command line.
+
+`-storetype STORE_TYPE'
+     Use this option to specify the type of the key store to use. The
+     default value, if this option is omitted, is that of the property
+     `keystore.type' in the security properties file, which is obtained
+     by invoking the static method call `getDefaultType()' in
+     `java.security.KeyStore'.
+
+`-storepass PASSWORD'
+     Use this option to specify the password protecting the key store.
+     If this option is omitted from the command line, you will be
+     prompted to provide a password.
+
+`-keystore URL'
+     Use this option to specify the location of the key store to use.
+     The default value is a file URL referencing the file named
+     `.keystore' located in the path returned by the call to
+     `java.lang.System#getProperty(String)' using `user.home' as
+     argument.
+
+     If a URL was specified, but was found to be malformed -e.g.
+     missing protocol element- the tool will attempt to use the URL
+     value as a file-name (with absolute or relative path-name) of a
+     key store -as if the protocol was `file:'.
+
+`-provider PROVIDER_CLASS_NAME'
+     A fully qualified class name of a Security Provider to add to the
+     current list of Security Providers already installed in the JVM
+     in-use. If a provider class is specified with this option, and was
+     successfully added to the runtime -i.e. it was not already
+     installed- then the tool will attempt to removed this Security
+     Provider before exiting.
+
+`-file FILE'
+     Use this option to designate a file to use with a command. When
+     specified with this option, the value is expected to be the fully
+     qualified path of a file accessible by the File System. Depending
+     on the command, the file may be used as input or as output. When
+     this option is omitted from the command line, `STDIN' will be used
+     instead, as the source of input, and `STDOUT' will be used instead
+     as the output destination.
+
+`-v'
+     Unless specified otherwise, use this option to enable more verbose
+     output.
+
+
+
+File: cp-tools.info,  Node: Distinguished Names,  Next: Add/Update Commands,  Prev: Common keytool Options,  Up: keytool Tool
+
+2.2.3 X.500 Distinguished Names
+-------------------------------
+
+A Distinguished Name (or DN) MUST be supplied with some of the
+`COMMAND's using a `-dname' option. The syntax of a valid value for
+this option MUST follow RFC-2253 specifications. Namely the following
+components (with their accepted meaning) will be recognized. Note that
+the component name is case-insensitive:
+
+CN
+     The Common Name; e.g. `host.domain.com'
+
+OU
+     The Organizational Unit; e.g. `IT Department'
+
+O
+     The Organization Name; e.g. `The Sample Company'
+
+L
+     The Locality Name; e.g. `Sydney'
+
+ST
+     The State Name; e.g. `New South Wales'
+
+C
+     The 2-letter Country identifier; e.g. `AU'
+
+   When specified with a `-dname' option, each pair of component/value
+will be separated from the other with a comma. Each component and value
+pair MUST be separated by an equal sign. For example, the following is
+a valid DN value:
+CN=host.domain.com, O=The Sample Company, L=Sydney, ST=NSW, C=AU
+
+If the Distinguished Name is required, and no valid default value can
+be used, the tool will prompt you to enter the information through the
+console.
+
+
+File: cp-tools.info,  Node: Add/Update Commands,  Next: Export Commands,  Prev: Distinguished Names,  Up: keytool Tool
+
+2.2.4 Add/Update commands
+-------------------------
+
+* Menu:
+
+* Command -genkey::            Generate private key and self-signed certificate
+* Command -import::            Import certificates and certificate replies
+* Command -selfcert::          Generate self-signed certificate
+* Command -cacert::            Import a CA Trusted Certificate
+* Command -identitydb::        Import JDK-1 style identities
+
+
+File: cp-tools.info,  Node: Command -genkey,  Next: Command -import,  Prev: Add/Update Commands,  Up: Add/Update Commands
+
+2.2.4.1 The `-genkey' command
+.............................
+
+Use this command to generate a new key-pair (both private and public
+keys), and save these credentials in the key store as a Key Entry,
+associated with the designated (if was specified with the `-alias'
+option) or default (if the `-alias' option is omitted) Alias.
+
+   The private key material will be protected with a user-defined
+password (see `-keypass' option). The public key on the other hand will
+be part of a self-signed X.509 certificate, which will form a 1-element
+chain and will be saved in the key store.
+
+`-alias ALIAS'
+     For more details *note ALIAS: alias.
+
+`-keyalg ALGORITHM'
+     For more details *note ALGORITHM: keyalg.
+
+`-keysize KEY_SIZE'
+     For more details *note KEY_SIZE: keysize.
+
+`-sigalg ALGORITHM'
+     The canonical name of the digital signature algorithm to use for
+     signing certificates. If this option is omitted, a default value
+     will be chosen based on the type of the key-pair; i.e., the
+     algorithm that ends up being used by the -keyalg option. If the
+     key-pair generation algorithm is `DSA', the value for the
+     signature algorithm will be `SHA1withDSA'. If on the other hand
+     the key-pair generation algorithm is `RSA', then the tool will use
+     `MD5withRSA' as the signature algorithm.
+
+`-dname NAME'
+     This a mandatory value for the command. If no value is specified
+     -i.e. the `-dname' option is omitted- the tool will prompt you to
+     enter a Distinguished Name to use as both the Owner and Issuer of
+     the generated self-signed certificate.
+
+     For more details *note X.500 DISTINGUISHED NAME: dn.
+
+`-keypass PASSWORD'
+     Use this option to specify the password which the tool will use to
+     protect the newly created Key Entry.
+
+     If this option is omitted, you will be prompted to provide a
+     password.
+
+`-validity DAY_COUNT'
+     For more details *note DAY_COUNT: validity.
+
+`-storetype STORE_TYPE'
+     For more details *note STORE_TYPE: storetype.
+
+`-keystore URL'
+     For more details *note URL: keystore.
+
+`-storepass PASSWORD'
+     For more details *note PASSWORD: storepass.
+
+`-provider PROVIDER_CLASS_NAME'
+     For more details *note PROVIDER_CLASS_NAME: provider.
+
+`-v'
+     For more details *note verbose::.
+
+
+
+File: cp-tools.info,  Node: Command -import,  Next: Command -selfcert,  Prev: Command -genkey,  Up: Add/Update Commands
+
+2.2.4.2 The `-import' command
+.............................
+
+Use this command to read an X.509 certificate, or a PKCS#7 Certificate
+Reply from a designated input source and incorporate the certificates
+into the key store.
+
+   If the Alias does not already exist in the key store, the tool
+treats the certificate read from the input source as a new Trusted
+Certificate. It then attempts to discover a chain-of-trust, starting
+from that certificate and ending at another Trusted Certificate,
+already stored in the key store. If the `-trustcacerts' option is
+present, an additional key store, of type `JKS' named `cacerts', and
+assumed to be present in `${JAVA_HOME}/lib/security' will also be
+consulted if found -`${JAVA_HOME}' refers to the location of an
+installed Java Runtime Environment (JRE). If no chain-of-trust can be
+established, and unless the `-noprompt' option has been specified, the
+certificate is printed to `STDOUT' and the user is prompted for a
+confirmation.
+
+   If Alias exists in the key store, the tool will treat the
+certificate(s) read from the input source as a Certificate Reply, which
+can be a chain of certificates, that eventually would replace the chain
+of certificates associated with the Key Entry of that Alias. The
+substitution of the certificates only occurs if a chain-of-trust can be
+established between the bottom certificate of the chain read from the
+input file and the Trusted Certificates already present in the key
+store. Again, if the `-trustcacerts' option is specified, additional
+Trusted Certificates in the same `cacerts' key store will be
+considered. If no chain-of-trust can be established, the operation will
+abort.
+
+`-alias ALIAS'
+     For more details *note ALIAS: alias.
+
+`-file FILE'
+     For more details *note FILE: file.
+
+`-keypass PASSWORD'
+     Use this option to specify the password which the tool will use to
+     protect the Key Entry associated with the designated Alias, when
+     replacing this Alias' chain of certificates with that found in the
+     certificate reply.
+
+     If this option is omitted, and the chain-of-trust for the
+     certificate reply has been established, the tool will first
+     attempt to unlock the Key Entry using the same password protecting
+     the key store. If this fails, you will then be prompted to provide
+     a password.
+
+`-noprompt'
+     Use this option to prevent the tool from prompting the user.
+
+`-trustcacerts'
+     Use this option to indicate to the tool that a key store, of type
+     `JKS', named `cacerts', and usually located in `lib/security' in
+     an installed Java Runtime Environment should be considered when
+     trying to establish chain-of-trusts.
+
+`-storetype STORE_TYPE'
+     For more details *note STORE_TYPE: storetype.
+
+`-keystore URL'
+     For more details *note URL: keystore.
+
+`-storepass PASSWORD'
+     For more details *note PASSWORD: storepass.
+
+`-provider PROVIDER_CLASS_NAME'
+     For more details *note PROVIDER_CLASS_NAME: provider.
+
+`-v'
+     For more details *note verbose::.
+
+
+
+File: cp-tools.info,  Node: Command -selfcert,  Next: Command -cacert,  Prev: Command -import,  Up: Add/Update Commands
+
+2.2.4.3 The `-selfcert' command
+...............................
+
+Use this command to generate a self-signed X.509 version 1 certificate.
+The newly generated certificate will form a chain of one element which
+will replace the previous chain associated with the designated Alias
+(if `-alias' option was specified), or the default Alias (if `-alias'
+option was omitted).
+
+`-alias ALIAS'
+     For more details *note ALIAS: alias.
+
+`-sigalg ALGORITHM'
+     The canonical name of the digital signature algorithm to use for
+     signing the certificate. If this option is omitted, a default
+     value will be chosen based on the type of the private key
+     associated with the designated Alias. If the private key is a
+     `DSA' one, the value for the signature algorithm will be
+     `SHA1withDSA'. If on the other hand the private key is an `RSA'
+     one, then the tool will use `MD5withRSA' as the signature
+     algorithm.
+
+`-dname NAME'
+     Use this option to specify the Distinguished Name of the newly
+     generated self-signed certificate. If this option is omitted, the
+     existing Distinguished Name of the base certificate in the chain
+     associated with the designated Alias will be used instead.
+
+     For more details *note X.500 DISTINGUISHED NAME: dn.
+
+`-validity DAY_COUNT'
+     For more details *note DAY_COUNT: validity.
+
+`-keypass PASSWORD'
+     Use this option to specify the password which the tool will use to
+     unlock the Key Entry associated with the designated Alias.
+
+     If this option is omitted, the tool will first attempt to unlock
+     the Key Entry using the same password protecting the key store. If
+     this fails, you will then be prompted to provide a password.
+
+`-storetype STORE_TYPE'
+     For more details *note STORE_TYPE: storetype.
+
+`-keystore URL'
+     For more details *note URL: keystore.
+
+`-storepass PASSWORD'
+     For more details *note PASSWORD: storepass.
+
+`-provider PROVIDER_CLASS_NAME'
+     For more details *note PROVIDER_CLASS_NAME: provider.
+
+`-v'
+     For more details *note verbose::.
+
+
+
+File: cp-tools.info,  Node: Command -cacert,  Next: Command -identitydb,  Prev: Command -selfcert,  Up: Add/Update Commands
+
+2.2.4.4 The `-cacert' command
+.............................
+
+Use this command to import, a CA certificate and add it to the key
+store as a Trusted Certificate. The Alias for this new entry will be
+constructed from the FILE's base-name after replacing hyphens and dots
+with underscores.
+
+   This command is useful when used in a script that recursively visits
+a directory of CA certificates to populate a `cacerts.gkr' Key Store of
+trusted certificates which can then be used commands that specify the
+`-trustcacerts' option.
+
+`-file FILE'
+     For more details *note FILE: file.
+
+`-storetype STORE_TYPE'
+     For more details *note STORE_TYPE: storetype.
+
+`-keystore URL'
+     For more details *note URL: keystore.
+
+`-storepass PASSWORD'
+     For more details *note PASSWORD: storepass.
+
+`-provider PROVIDER_CLASS_NAME'
+     For more details *note PROVIDER_CLASS_NAME: provider.
+
+`-v'
+     For more details *note verbose::.
+
+
+
+File: cp-tools.info,  Node: Command -identitydb,  Prev: Command -cacert,  Up: Add/Update Commands
+
+2.2.4.5 The `-identitydb' command
+.................................
+
+NOT IMPLEMENTED YET.
+
+   Use this command to import a JDK 1.1 style Identity Database.
+
+`-file FILE'
+     For more details *note FILE: file.
+
+`-storetype STORE_TYPE'
+     For more details *note STORE_TYPE: storetype.
+
+`-keystore URL'
+     For more details *note URL: keystore.
+
+`-storepass PASSWORD'
+     For more details *note PASSWORD: storepass.
+
+`-provider PROVIDER_CLASS_NAME'
+     For more details *note PROVIDER_CLASS_NAME: provider.
+
+`-v'
+     For more details *note verbose::.
+
+
+
+File: cp-tools.info,  Node: Export Commands,  Next: Display Commands,  Prev: Add/Update Commands,  Up: keytool Tool
+
+2.2.5 Export commands
+---------------------
+
+* Menu:
+
+* Command -certreq::           Generate Certificate Signing Requests (CSR)
+* Command -export::            Export a certificate in a Key Store
+
+
+File: cp-tools.info,  Node: Command -certreq,  Next: Command -export,  Prev: Export Commands,  Up: Export Commands
+
+2.2.5.1 The `-certreq' command
+..............................
+
+Use this command to generate a PKCS#10 Certificate Signing Request
+(CSR) and write it to a designated output destination. The contents of
+the destination should look something like the following:
+
+     -----BEGIN NEW CERTIFICATE REQUEST-----
+     MI...QAwXzEUMBIGA1UEAwwLcnNuQGdudS5vcmcxGzAZBgNVBAoMElUg
+     Q2...A0GA1UEBwwGU3lkbmV5MQwwCgYDVQQIDANOU1cxCzAJBgNVBACC
+     ...
+     FC...IVwNVOfQLRX+O5kAhQ/a4RTZme2L8PnpvgRwrf7Eg8D6w==
+     -----END NEW CERTIFICATE REQUEST-----
+
+   IMPORTANT: Some documentation (e.g. RSA examples) claims that the
+`Attributes' field, in the CSR is `OPTIONAL' while RFC-2986 implies the
+opposite. This implementation considers this field, by default, as
+`OPTIONAL', unless the option `-attributes' is specified on the command
+line.
+
+`-alias ALIAS'
+     For more details *note ALIAS: alias.
+
+`-sigalg ALGORITHM'
+     The canonical name of the digital signature algorithm to use for
+     signing the certificate. If this option is omitted, a default
+     value will be chosen based on the type of the private key
+     associated with the designated Alias. If the private key is a
+     `DSA' one, the value for the signature algorithm will be
+     `SHA1withDSA'. If on the other hand the private key is an `RSA'
+     one, then the tool will use `MD5withRSA' as the signature
+     algorithm.
+
+`-file FILE'
+     For more details *note FILE: file.
+
+`-keypass PASSWORD'
+     Use this option to specify the password which the tool will use to
+     unlock the Key Entry associated with the designated Alias.
+
+     If this option is omitted, the tool will first attempt to unlock
+     the Key Entry using the same password protecting the key store. If
+     this fails, you will then be prompted to provide a password.
+
+`-storetype STORE_TYPE'
+     For more details *note STORE_TYPE: storetype.
+
+`-keystore URL'
+     For more details *note URL: keystore.
+
+`-storepass PASSWORD'
+     For more details *note PASSWORD: storepass.
+
+`-provider PROVIDER_CLASS_NAME'
+     For more details *note PROVIDER_CLASS_NAME: provider.
+
+`-v'
+     For more details *note verbose::.
+
+`-attributes'
+     Use this option to force the tool to encode a `NULL' DER value in
+     the CSR as the value of the `Attributes' field.
+
+
+
+File: cp-tools.info,  Node: Command -export,  Prev: Command -certreq,  Up: Export Commands
+
+2.2.5.2 The `-export' command
+.............................
+
+Use this command to export a certificate stored in a key store to a
+designated output destination, either in binary format (if the `-v'
+option is specified), or in RFC-1421 compliant encoding (if the `-rfc'
+option is specified instead).
+
+`-alias ALIAS'
+     For more details *note ALIAS: alias.
+
+`-file FILE'
+     For more details *note FILE: file.
+
+`-storetype STORE_TYPE'
+     For more details *note STORE_TYPE: storetype.
+
+`-keystore URL'
+     For more details *note URL: keystore.
+
+`-storepass PASSWORD'
+     For more details *note PASSWORD: storepass.
+
+`-provider PROVIDER_CLASS_NAME'
+     For more details *note PROVIDER_CLASS_NAME: provider.
+
+`-rfc'
+     Use RFC-1421 specifications when encoding the output.
+
+`-v'
+     Output the certificate in binary DER encoding. This is the default
+     output format of the command if neither `-rfc' nor `-v' options
+     were detected on the command line. If both this option and the
+     `-rfc' option are detected on the command line, the tool will opt
+     for the RFC-1421 style encoding.
+
+
+
+File: cp-tools.info,  Node: Display Commands,  Next: Management Commands,  Prev: Export Commands,  Up: keytool Tool
+
+2.2.6 Display commands
+----------------------
+
+* Menu:
+
+* Command -list::              Display information about one or all Aliases
+* Command -printcert::         Print a certificate or a certificate fingerprint
+
+
+File: cp-tools.info,  Node: Command -list,  Next: Command -printcert,  Prev: Display Commands,  Up: Display Commands
+
+2.2.6.1 The `-list' command
+...........................
+
+Use this command to print one or all of a key store entries to
+`STDOUT'. Usually this command will only print a fingerprint of the
+certificate, unless either the `-rfc' or the `-v' option is specified.
+
+`-alias ALIAS'
+     If this option is omitted, the tool will print ALL the entries
+     found in the key store.
+
+     For more details *note ALIAS: alias.
+
+`-storetype STORE_TYPE'
+     For more details *note STORE_TYPE: storetype.
+
+`-keystore URL'
+     For more details *note URL: keystore.
+
+`-storepass PASSWORD'
+     For more details *note PASSWORD: storepass.
+
+`-provider PROVIDER_CLASS_NAME'
+     For more details *note PROVIDER_CLASS_NAME: provider.
+
+`-rfc'
+     Use RFC-1421 specifications when encoding the output.
+
+`-v'
+     Output the certificate in human-readable format. If both this
+     option and the `-rfc' option are detected on the command line, the
+     tool will opt for the human-readable form and will not abort the
+     command.
+
+
+
+File: cp-tools.info,  Node: Command -printcert,  Prev: Command -list,  Up: Display Commands
+
+2.2.6.2 The `-printcert' command
+................................
+
+Use this command to read a certificate from a designated input source
+and print it to `STDOUT' in a human-readable form.
+
+`-file FILE'
+     For more details *note FILE: file.
+
+`-v'
+     For more details *note verbose::.
+
+
+
+File: cp-tools.info,  Node: Management Commands,  Prev: Display Commands,  Up: keytool Tool
+
+2.2.7 Management commands
+-------------------------
+
+* Menu:
+
+* Command -keyclone::          Clone a Key Entry in a Key Store
+* Command -storepasswd::       Change the password protecting a Key Store
+* Command -keypasswd::         Change the password protecting a Key Entry
+* Command -delete::            Remove an entry in a Key Store
+
+
+File: cp-tools.info,  Node: Command -keyclone,  Next: Command -storepasswd,  Prev: Management Commands,  Up: Management Commands
+
+2.2.7.1 The `-keyclone' command
+...............................
+
+Use this command to clone an existing Key Entry and store it under a
+new (different) Alias protecting, its private key material with
+possibly a new password.
+
+`-alias ALIAS'
+     For more details *note ALIAS: alias.
+
+`-dest ALIAS'
+     Use this option to specify the new Alias which will be used to
+     identify the cloned copy of the Key Entry.
+
+`-keypass PASSWORD'
+     Use this option to specify the password which the tool will use to
+     unlock the Key Entry associated with the designated Alias.
+
+     If this option is omitted, the tool will first attempt to unlock
+     the Key Entry using the same password protecting the key store. If
+     this fails, you will then be prompted to provide a password.
+
+`-new PASSWORD'
+     Use this option to specify the password protecting the private key
+     material of the newly cloned copy of the Key Entry.
+
+`-storetype STORE_TYPE'
+     For more details *note STORE_TYPE: storetype.
+
+`-keystore URL'
+     For more details *note URL: keystore.
+
+`-storepass PASSWORD'
+     For more details *note PASSWORD: storepass.
+
+`-provider PROVIDER_CLASS_NAME'
+     For more details *note PROVIDER_CLASS_NAME: provider.
+
+`-v'
+     For more details *note verbose::.
+
+
+
+File: cp-tools.info,  Node: Command -storepasswd,  Next: Command -keypasswd,  Prev: Command -keyclone,  Up: Management Commands
+
+2.2.7.2 The `-storepasswd' command
+..................................
+
+Use this command to change the password protecting a key store.
+
+`-new PASSWORD'
+     The new, and different, password which will be used to protect the
+     designated key store.
+
+`-storetype STORE_TYPE'
+     For more details *note STORE_TYPE: storetype.
+
+`-keystore URL'
+     For more details *note URL: keystore.
+
+`-storepass PASSWORD'
+     For more details *note PASSWORD: storepass.
+
+`-provider PROVIDER_CLASS_NAME'
+     For more details *note PROVIDER_CLASS_NAME: provider.
+
+`-v'
+     For more details *note verbose::.
+
+
+
+File: cp-tools.info,  Node: Command -keypasswd,  Next: Command -delete,  Prev: Command -storepasswd,  Up: Management Commands
+
+2.2.7.3 The `-keypasswd' command
+................................
+
+Use this command to change the password protecting the private key
+material of a designated Key Entry.
+
+`-alias ALIAS'
+     For more details *note ALIAS: alias.
+
+     Use this option to specify the password which the tool will use to
+     unlock the Key Entry associated with the designated Alias.
+
+     If this option is omitted, the tool will first attempt to unlock
+     the Key Entry using the same password protecting the key store. If
+     this fails, you will then be prompted to provide a password.
+
+`-new PASSWORD'
+     The new, and different, password which will be used to protect the
+     private key material of the designated Key Entry.
+
+`-storetype STORE_TYPE'
+     For more details *note STORE_TYPE: storetype.
+
+`-keystore URL'
+     For more details *note URL: keystore.
+
+`-storepass PASSWORD'
+     For more details *note PASSWORD: storepass.
+
+`-provider PROVIDER_CLASS_NAME'
+     For more details *note PROVIDER_CLASS_NAME: provider.
+
+`-v'
+     For more details *note verbose::.
+
+
+
+File: cp-tools.info,  Node: Command -delete,  Prev: Command -keypasswd,  Up: Management Commands
+
+2.2.7.4 The `-delete' command
+.............................
+
+Use this command to delete a designated key store entry.
+
+`-alias ALIAS'
+     For more details *note ALIAS: alias.
+
+`-storetype STORE_TYPE'
+     For more details *note STORE_TYPE: storetype.
+
+`-keystore URL'
+     For more details *note URL: keystore.
+
+`-storepass PASSWORD'
+     For more details *note PASSWORD: storepass.
+
+`-provider PROVIDER_CLASS_NAME'
+     For more details *note PROVIDER_CLASS_NAME: provider.
+
+`-v'
+     For more details *note verbose::.
+
+
+
+File: cp-tools.info,  Node: Other Tools,  Next: I18N Issues,  Prev: Security Tools,  Up: Top
+
+3 Other Tools
+*************
+
+This is a list of currently undocumented classpath tools: jar, javah,
+gcjh, native2ascii, orbd, serialver, rmid, rmiregistry and tnameserv.
+
+* Menu:
+
+* jar Tool::                   Archive tool for Java archives
+* javah Tool::                 A java header compiler
+* gcjh Tool::                  A java header compiler (old version)
+* native2ascii Tool::          An encoding converter
+* orbd Tool::                  An object request broker daemon
+* serialver Tool::             A serial version command
+* rmid Tool::                  RMI activation daemon
+* rmiregistry Tool::           Remote object registry
+* tnameserv Tool::             Naming service
+* gjdoc Tool::                 A documentation generator
+
+
+File: cp-tools.info,  Node: jar Tool,  Next: javah Tool,  Up: Other Tools
+
+3.1 The `jar' Tool
+==================
+
+`gjar' is an implementation of Sun's jar utility that comes with the
+JDK.
+
+   If any file is a directory then it is processed recursively.  The
+manifest file name and the archive file name needs to be specified in
+the same order the `-m' and `-f' flags are specified.
+
+   Operation mode:
+
+`-c'
+     Create new archive.
+
+`-t'
+     List table of contents for archive.
+
+`-x'
+     Extract named (or all) files from archive.
+
+`-u'
+     Update existing archive.
+
+`-i FILE'
+     Compute archive index.
+
+   Operation modifiers:
+
+`-f FILE'
+     Specify archive file name.
+
+`-0'
+     Store only; use no ZIP compression.
+
+`-v'
+     Generate verbose output on standard output.
+
+`-M'
+     Do not create a manifest file for the entries.
+
+`-m MANIFEST'
+     Include manifest information from specified MANIFEST file.
+
+   File name selection:
+
+`-C DIR FILE'
+     Change to the DIR and include the following FILE.
+
+`-@'
+     Read the names of the files to add to the archive from stdin.  This
+     option is supported only in combination with `-c' or `-u'.  Non
+     standard option added in the GCC version.
+
+   Standard options:
+
+`-help'
+     Print help text, then exit.
+
+`-version'
+     Print version number, then exit.
+
+`-JOPTION'
+     Pass argument to the Java runtime.
+
+   java(1), ...
+
+
+File: cp-tools.info,  Node: javah Tool,  Next: gcjh Tool,  Prev: jar Tool,  Up: Other Tools
+
+3.2 The `javah' Tool
+====================
+
+The `gjavah' program is used to generate header files from class files.
+It can generate both CNI and JNI header files, as well as stub
+implementation files which can be used as a basis for implementing the
+required native methods.
+
+`-d DIR'
+     Set output directory.
+
+`-o FILE'
+     Set output file (only one of `-d' or `-o' may be used).
+
+`-cmdfile FILE'
+     Read command file.
+
+`-all DIR'
+     Operate on all class files under directory DIR.
+
+`-stubs'
+     Emit stub implementation.
+
+`-jni'
+     Emit JNI stubs or header (default).
+
+`-cni'
+     Emit CNI stubs or header (default JNI).
+
+`-verbose'
+     Set verbose mode.
+
+`-force'
+     Output files should always be written.
+
+   Class path options:
+`-classpath PATH'
+     Set the class path.
+
+`-IDIR'
+     Add directory to class path.
+
+`-bootclasspath PATH'
+     Set the boot class path.
+
+`-extdirs PATH'
+     Set the extension directory path.
+
+   Standard options:
+`-help'
+     Print help text, then exit.
+
+`-version'
+     Print version number, then exit.
+
+`-JOPTION'
+     Pass argument to the Java runtime.
+
+   javac(1), ...
+
+
+File: cp-tools.info,  Node: gcjh Tool,  Next: native2ascii Tool,  Prev: javah Tool,  Up: Other Tools
+
+3.3 The `gcjh' Tool
+===================
+
+The `gcjh' program is used to generate header files from class files.
+It can generate both CNI and JNI header files, as well as stub
+implementation files which can be used as a basis for implementing the
+required native methods.  It is similar to `javah' but has slightly
+different command line options, and defaults to CNI.
+
+   See `javah' for a full description; this page only lists the
+additional options provided by `gcjh'.
+
+   CNI text options
+`-add TEXT'
+     Insert TEXT into class body.
+
+`-append TEXT'
+     Append TEXT after class declaration.
+
+`-friend TEXT'
+     Insert TEXT as a `friend' declaration.
+
+`-prepend TEXT'
+     Insert TEXT before start of class.
+
+   Compatibility options (unused)
+`-td DIR'
+`-M'
+`-MM'
+`-MD'
+`-MMD'
+     Unused compatibility option.
+
+   Standard options:
+`-help'
+     Print help text, then exit.
+
+`-version'
+     Print version number, then exit.
+
+`-JOPTION'
+     Pass argument to the Java runtime.
+
+   javac(1), javah(1), ...
+
+
+File: cp-tools.info,  Node: native2ascii Tool,  Next: orbd Tool,  Prev: gcjh Tool,  Up: Other Tools
+
+3.4 The `native2ascii' Tool
+===========================
+
+To be written ...
+
+`-encoding NAME'
+     Set the encoding to use.
+
+`-reversed'
+     Convert from encoding to native.
+
+   Standard options:
+`-help'
+     Print help text, then exit.
+
+`-version'
+     Print version number, then exit.
+
+`-JOPTION'
+     Pass argument to the Java runtime.
+
+   javac(1), ...
+
+
+File: cp-tools.info,  Node: orbd Tool,  Next: serialver Tool,  Prev: native2ascii Tool,  Up: Other Tools
+
+3.5 The `orbd' object request broker daemon
+===========================================
+
+To be written ...
+
+`-ORBInitialPort PORT'
+     Port on which persistent naming service is to be started.
+
+`-ior FILE'
+     File in which to store persistent naming service's IOR reference
+
+`-directory DIR'
+     Directory in which to store persistent data.
+
+`-restart'
+     Restart persistent naming service, clearing persistent naming
+     database.
+
+   Standard options:
+`-help'
+     Print help text, then exit.
+
+`-version'
+     Print version number, then exit.
+
+`-JOPTION'
+     Pass argument to the Java runtime.
+
+   java(1), ...
+
+
+File: cp-tools.info,  Node: serialver Tool,  Next: rmid Tool,  Prev: orbd Tool,  Up: Other Tools
+
+3.6 The `serialver' version command
+===================================
+
+Print the serialVersionUID of the specified classes.
+
+`-classpath PATH'
+     Class path to use to find classes.
+
+   Standard options:
+`-help'
+     Print help text, then exit.
+
+`-version'
+     Print version number, then exit.
+
+`-JOPTION'
+     Pass argument to the Java runtime.
+
+   javac(1), ...
+
+
+File: cp-tools.info,  Node: rmid Tool,  Next: rmiregistry Tool,  Prev: serialver Tool,  Up: Other Tools
+
+3.7 The `rmid' RMI activation system daemon
+===========================================
+
+`rmiregistry' starts a remote object registry on the current host.  If
+no port number is specified, then port 1099 is used.
+
+   Activation process control:
+`-port PORT'
+     Port on which activation system is to be started.
+
+`-restart'
+     Restart activation system, clearing persistent naming database, if
+     any.
+
+`-stop'
+     Stop activation system.
+
+   Persistence:
+`-persistent'
+     Make activation system persistent.
+
+`-directory DIR'
+     Directory in which to store persistent data.
+
+   Debugging:
+`-verbose'
+     Log binding events to standard out.
+
+   Standard options:
+`-help'
+     Print help text, then exit.
+
+`-version'
+     Print version number, then exit.
+
+`-JOPTION'
+     Pass argument to the Java runtime.
+
+   java(1), ...
+
+
+File: cp-tools.info,  Node: rmiregistry Tool,  Next: tnameserv Tool,  Prev: rmid Tool,  Up: Other Tools
+
+3.8 The `rmiregistry' Tool
+==========================
+
+`grmiregistry' starts a remote object registry on the current host.  If
+no port number is specified, then port 1099 is used.
+
+   Registry process control:
+`-restart'
+     Restart RMI naming service, clearing persistent naming database, if
+     any.
+
+`-stop'
+     Stop RMI naming service.
+
+   Persistence:
+`-persistent'
+     Make RMI naming service persistent.
+
+`-directory DIR'
+     Directory in which to store persistent data.
+
+   Debugging:
+`-verbose'
+     Log binding events to standard out.
+
+   Standard options:
+`-help'
+     Print help text, then exit.
+
+`-version'
+     Print version number, then exit.
+
+`-JOPTION'
+     Pass argument to the Java runtime.
+
+   java(1), ...
+
+
+File: cp-tools.info,  Node: tnameserv Tool,  Next: gjdoc Tool,  Prev: rmiregistry Tool,  Up: Other Tools
+
+3.9 The `tnameserv' Tool
+========================
+
+To be written ...
+
+`-ORBInitialPort PORT'
+     Port on which naming service is to be started.
+
+`-ior FILE'
+     File in which to store naming service's IOR reference.
+
+   Standard options:
+`-help'
+     Print help text, then exit.
+
+`-version'
+     Print version number, then exit.
+
+`-JOPTION'
+     Pass argument to the Java runtime.
+
+   java(1), ...
+
+   Info entry for `gjdoc'.  Please report bugs to
+`http://savannah.gnu.org/bugs/?group=classpath'.  Julian Scheid
+
+
+File: cp-tools.info,  Node: gjdoc Tool,  Prev: tnameserv Tool,  Up: Other Tools
+
+4 Generating HTML Documentation
+*******************************
+
+Gjdoc can be used in two ways: as a stand-alone documentation tool, or
+as a driver for a user-specified Doclet. *Note Other Doclets::.
+
+   In the default mode, Gjdoc will use the Standard Doclet `HtmlDoclet'
+to generate a set of HTML pages.  The canonical usage is:
+
+     gjdoc -s src/java/ -all -d api-docs/
+
+   Here, `src/java/' is the root of your source code class hierarchy,
+`-all' means that all valid Java files found under this root directory
+should be processed, and `api-docs/' is the directory where the
+generated documentation should be placed.
+
+   To learn more about running Doclets other than the Standard Doclet,
+refer to the manual.  *Note Invoking a Custom Doclet::.
+
+* Menu:
+
+* Invoking the Standard Doclet::   How to generate HTML documentation.
+* Invoking a Custom Doclet::       How to run third-party and other
+                                   built-in Doclets.
+
+* Option Summary by Type::         Brief list of all options, grouped by type.
+* Gjdoc Option Summary::           List of all options accepted by Gjdoc.
+
+* Source Set Options::      Select the set of source codes to run Gjdoc on.
+* Source Format Options::   Specify the format of the source codes to document.
+
+* Interlinking Options::    Connection your documentation with other projects.
+* Output Control Options::  Specify the target directory and locale, and more.
+* Generation Options::       Select which pieces of information to generate.
+* Decoration Options::      Add or modify some titles, headers and footers or
+                              override/amend static resources like stylesheets.
+* Taglet Options::          Define your own javadoc @tags
+
+* Virtual Machine Options::
+* Verbosity Options::
+* Doclet Options::
+
+* Other Doclets::                  Generating Other Output Types
+* Gjdoc Concepts::                 Advanced Concepts
+
+
+File: cp-tools.info,  Node: Invoking the Standard Doclet,  Next: Invoking a Custom Doclet,  Up: gjdoc Tool
+
+4.1 Invoking the Standard Doclet
+================================
+
+Running the Gjdoc Standard Doclet `HtmlDoclet' is the default mode of
+operation for Gjdoc.  This section lists the command line options you
+can specify in this mode.  It doesn't distinguish between general Gjdoc
+options and options specific to the Standard Doclet.
+
+   If you want to learn which options are accepted when Gjdoc is used as
+a doclet driver, *Note Invoking a Custom Doclet::.
+
+* Menu:
+
+* Source Set Options::      Select the set of source codes to run Gjdoc on.
+* Source Format Options::   Specify the format of the source codes to document.
+
+* Output Control Options::  Specify the target directory and locale, and more.
+* Generation Options::       Select which pieces of information to generate.
+* Decoration Options::      Add or modify some titles, headers and footers or
+                              override/amend static resources like stylesheets.
+* Taglet Options::          Define your own javadoc @tags
+
+* Virtual Machine Options::
+* Doclet Options::
+
+
+File: cp-tools.info,  Node: Option Summary by Type,  Next: Gjdoc Option Summary,  Prev: Invoking a Custom Doclet,  Up: gjdoc Tool
+
+4.2 Option Summary by Type
+==========================
+
+Here is a summary of all the options of both Gjdoc and the Standard
+Doclet, grouped by type.  Explanations are in the following sections.
+
+_Source Set Options_
+     *Note Options For Specifying the Source Files To Operate on:
+     Source Set Options.
+          -sourcepath PATHLIST  -subpackages PKGLIST  -exclude PKGLIST
+
+_Source Format Options_
+     *Note Options For Specifying the Source Format: Source Format
+     Options.
+          -source RELEASE  -encoding ENCODING  -breakiterator
+
+_Interlinking Options_
+     *Note Options For Specifying the Source Files To Operate on:
+     Interlinking Options.
+          -link URL  -linkoffline URL FILE  -noqualifier PKG:PKG:...
+
+_Generation Options_
+     *Note Options Controlling What is Included in the Output:
+     Generation Options.
+          -author  -licensetext  -use  -version  -splitindex  -noindex
+           -nodeprecated  -nodeprecatedlist  -nohelp  -nonavbar
+           -nosince  -notree  -public  -protected  -package  -private
+           -docfilessubdirs  -excludedocfilessubdir DIRNAME
+           -linksource
+
+_Output Options_
+     *Note Options Controlling the Output: Generation Options.
+          -d  -locale NAME  -charset CHARSET  -docencoding CHARSET
+           -validhtml  -baseurl URL
+
+_Decoration Options_
+          -windowtitle TEXT  -doctitle TEXT  -title TEXT
+           -header TEXT  -footer TEXT  -bottom TEXT
+           -helpfile FILE  -stylesheetfile FILE  -addstylesheet FILE
+           -group GROUPHEADING PKGPATTERN:PKGPATTERN:...
+
+_Taglet Options_
+     *Note Options For Specifying user-defined Taglets: Taglet Options.
+          -tagletpath  -taglet CLASSNAME  -tag TAGSPEC
+
+_Doclet Options_
+     *Note Options For Specifying the Doclet to use: Doclet Options.
+          -docletpath  -doclet CLASSNAME
+
+_Verbosity Options_
+     *Note Options Controlling Gjdoc Behavior: Verbosity Options.
+          -quiet  -verbose
+
+_Virtual Machine Options_
+     *Note Options Controlling Gjdoc Behavior: Virtual Machine Options.
+          -classpath  -bootclasspath  -J VMOPT
+
+
+* Menu:
+
+* Virtual Machine Options::     Controlling the kind of output:
+                        an executable, object files, assembler files,
+                        or preprocessed source.
+
+
+File: cp-tools.info,  Node: Source Set Options,  Next: Source Format Options,  Prev: Gjdoc Option Summary,  Up: gjdoc Tool
+
+4.3 Selecting which Source Files to Process
+===========================================
+
+`-s PATHLIST'
+
+`-sourcepath PATHLIST'
+     Look for source files in the specified directory or directories.
+
+     PATHLIST should be one or more directory paths separated by your
+     platform's path separator (usually `:' or `;').
+
+     If this option is not given, `gjdoc' will look for source files in
+     the current directory.
+
+     The directories specified should be root directories in terms of
+     the Java package system.  For example, if you want to generate
+     documentation for classes in package `foo.bar', you must specify
+     the directory containing the top-level ``foo'' sub-directory, not
+     the directory ``foo/bar/'' in which the Java source files reside.
+
+     The short-hand alias `-s' is specific to `gjdoc' and not
+     compatible to Sun `javadoc'.
+
+`-all'
+     _[EXPERIMENTAL]_ Process all valid Java source files found in the
+     directories listed in the source path and their sub-directories.
+
+     This is an option specific to `gjdoc' and not compatible to Sun
+     `javadoc'.
+
+`-subpackages PKG:PKG:...'
+     Process the classes in the given Java packages and all
+     sub-packages, recursively.  Note that multiple package names must
+     be separated with colons instead of whitespace.
+
+`-exclude PKG:PKG:...'
+     Do not process classes in the given Java packages and all
+     sub-packages, recursively.  This option can be used in conjunction
+     with `-all' or `-subpackages' in order to exclude individual
+     packages or package sub-trees from the output.
+
+`PACKAGES...'
+     Process all classes in the given Java packages.
+
+`SOURCEFILES...'
+     Process the classes in the given Java source files.
+
+
+File: cp-tools.info,  Node: Source Format Options,  Next: Interlinking Options,  Prev: Source Set Options,  Up: gjdoc Tool
+
+4.4 Specifying the Format of Input Files
+========================================
+
+`-source RELEASE'
+     Assume that the source files are targeted at the given release of
+     the Java platform.
+
+     RELEASE should be the version number of a Java platform release in
+     the format MAJOR.MINOR, for example `1.4'.
+
+     This option is currently ignored except that an error is raised if
+     a release number other than `1.2', `1.3' or `1.4' is specified.
+
+`-encoding CHARSET'
+     Assume that the source files are encoded using CHARSET.
+
+     Examples for CHARSET are `US-ASCII', `ISO-8859-1' or `UTF-8'.
+
+     The semantics of CHARSET are identical to those of
+     `java.nio.charset.Charset.forName(String)'.
+
+`-breakiterator'
+     Use the locale's java.text.BreakIterator instead of the internal
+     first sentence detector.
+
+     By default, `gjdoc' uses an internal algorithm to determine where
+     a sentence ends. When this option is given, it will instead use
+     the `java.text.BreakIterator' instance for the locale given with
+     `-locale' (or the default locale).
+
+     This option should be specified when applying `gjdoc' to source
+     code commented in a non-latin language for which the default first
+     sentence detector does not work. For all other cases, the default
+     (do not use BreakIterator) produces better results at the time of
+     this writing.
+
+
+File: cp-tools.info,  Node: Interlinking Options,  Next: Output Control Options,  Prev: Source Format Options,  Up: gjdoc Tool
+
+4.5 Interlinking with other Documentation Sets
+==============================================
+
+`-link URL'
+     Create hyperlinks to another documentation set.
+
+     By default, `gjdoc' will only create hyperlinks to classes in the
+     source set.  Use this option to additionally create hyperlinks to
+     classes covered by the specified documentation set.
+
+     URL should be the root URL of the other documentation set. For
+     example, to add hyperlinks to GNU Classpath, specify the following:
+
+          -link http://developer.classpath.org/doc/
+
+     The `-link' option can be specified multiple times.
+
+     Note that specifying the `-link' option will cause an HTTP access
+     every time gjdoc is invoked. You can use `-linkoffline' instead to
+     avoid this access.
+
+`-linkoffline URL FILE'
+     Create hyperlinks to another documentation set which is also
+     present on the local file system.
+
+     This option works exactly like `-link', except that it accesses
+     the local file system instead of the network for determining which
+     classes are covered by the linked documentation set.
+
+     When using `-linkoffline' the remote documentation set is not
+     accessed at all, which can significantly speed up generation time
+     depending on your network connection.  The generated hyperlinks to
+     the documentation set however refer to the remote set, not to the
+     local one, so that you can distribute the documentation without
+     any further dependencies.
+
+     The `-linkoffline' option can be specified multiple times.
+
+`-noqualifier PKG:PKG:...'
+     Do not qualify names of classes in the given packages with their
+     package name.
+
+     By default, a class name is displayed unqualified only if the
+     class is part of the source set or a linked documentation set, and
+     qualified with the name of its containing package if it is not.
+     You can use this option to force unqualified names for classes
+     even if they are not part of the documentation set.
+
+     For example, usually a reference to the String class is represented
+     fully-qualified as `java.lang.String' (unless you link to the
+     appropriate documentation set using `-link') because it isn't part
+     of the documentation set.  You can specify `-noqualifier
+     java.lang' to render the same references just as `String'.
+
+     Note that for all unqualified class names, a tooltip is provided
+     when you place your mouse pointer over it in the HTML
+     documentation.
+
+`-noqualifier `all''
+     Omit package name qualifier from all class names.
+
+     Specify this option to omit package name qualifiers altogether,
+
+
+
+File: cp-tools.info,  Node: Generation Options,  Next: Decoration Options,  Prev: Output Control Options,  Up: gjdoc Tool
+
+4.6 Selecting which Information to Generate
+===========================================
+
+`-public'
+     Only include public members of public classes in the output.  By
+     default, protected class members are included as well.
+
+`-protected'
+     Include public or protected members of public classes in the
+     output.  This is the default.
+
+`-package'
+     Include public, protected and package-private members of public and
+     package-private classes.
+
+`-private'
+     Include all classes and class members regardless of their access
+     level.
+
+`-splitindex'
+     Generate one index page per letter instead of a single, monolithic
+     index page.
+
+     By default, the index created by the Standard Doclet contains all
+     entries on a single page.  This is fine for small documentation
+     sets, but for large sets you should specify this option.
+
+`-nosince'
+     Ignore `@since' tags in javadoc comments.
+
+     By default, the generated output contains sections listing the
+     version of your API since which the package, class or class member
+     in question exists when this tag is encountered.  Specify this
+     option to omit this information.
+
+`-notree'
+     Do not generate any tree pages.
+
+     By default, the generated output includes one inheritance tree per
+     package, and - if the documentation set consists of multiple
+     packages - a page with the full inheritance tree.  Specify this
+     option to omit generation of these pages.
+
+`-noindex'
+     Do not output the alphabetical index.
+
+     By default, gjdoc generates an alphabetical index of all program
+     elements in the documentation set (packages, classes, inner
+     classes, constructors, methods, and fields).  Specify this option
+     to omit this information.
+
+`-nohelp'
+     Do not generate the help page.
+
+     This option is currently ignored as the Standard Doclet doesn't
+     provide a help page.
+
+`-nodeprecated'
+     Do not output inline information about deprecated packages,
+     classes or class members.
+
+     By default, the Standard Doclet adds a highlighted paragraph with
+     deprecation information to the description of each deprecated
+     program element.  Specify this option to omit this information.
+
+`-nodeprecatedlist'
+     Do not output the summary page for deprecated API elements.
+
+     By default, the Standard Doclet generates a page listing all
+     deprecated API elements along with a deprecation description which
+     usually includes the reason for deprecation and possible
+     alternatives.  Specify this option to omit this information.
+
+`-nonavbar'
+     Do not output the navigation bar, header, and footer.
+
+     By default, each output page is equipped with a top navigation bar
+     (which may include a user-specified header) and a bottom navigation
+     bar (which may include a user-specified footer).  Specify this
+     option to omit this decoration.
+
+`-nocomment'
+     Omit all documentation text from the generated files and output
+     only declarations and program element relationships.
+
+     This option is here for compatibility with `javadoc'.  If you plan
+     on extracting information about your project via `gjdoc', you
+     should consider using a different Doclet for your purposes
+     instead, for example XmlDoclet.  You could also use the Doclet API
+     directly by implementing a new Doclet.
+
+`-linksource'
+     Generate a page with syntax-highlighted source code for each class.
+     By default, this page is not generated.
+
+     The source code can be accessed by clicking on the button labelled
+     "Source" in the navigation bar, or by clicking on the name of a
+     constructor, field, method, or inner class in the detail section
+     of a class documentation page.
+
+`-use'
+     Generate a page with cross-reference information. By default, this
+     page is not generated.
+
+     The cross-reference information can be accessed by clicking on the
+     button labelled `Use' in the navigation bar.
+
+     The `Use' page lists all classes/interfaces in the documentation
+     set that extend/implement the class (type) in question; fields of
+     the type; methods or constructors accepting a parameter of the
+     type; methods returning the type; and methods or constructors
+     throwing the type.
+
+`-author'
+     Include author information in the output.
+
+     When specified, author information as specified using the
+     `@author' tag in javadoc comments is incorporated into the output.
+     By default, `@author' tags are ignored.
+
+`-version'
+     Include version information in the output.
+
+     When specified, version information as specified using the
+     `@version' tag in javadoc comments is incorporated into the
+     output. By default, `@version' tags are ignored.
+
+`-licensetext'
+     Assume that the first comment in each source file contains the
+     license text, and add license information to the footer of each
+     generated class page.
+
+     This is an option specific to `gjdoc' and not compatible to Sun
+     `javadoc'.
+
+     This option is intended for use with free and open source projects
+     where source code is typically prefixed with a boilerplate license
+     comment, when there are legal reasons for including the license in
+     the documentation.
+
+`-docfilessubdirs'
+     Recursively copy all files in the `doc-files' sub-directory of each
+     package directory.
+
+     Usually, only the files in the `doc-files' sub-directory are copied
+     without descending recursively.
+
+     *Note Adding Custom Resources::.
+
+`-excludedocfilessubdir NAME:NAME:...'
+     Do not copy some directories directly under the `doc-files'
+     sub-directories when descending recursively.
+
+     The argument to this option should be a colon-separated list of
+     directory names.
+
+     This option only makes sense if `-docfilessubdirs' is also
+     specified.  In this case, any sub-directory located directly
+     beneath a `doc-files' directory is omitted if listed.
+
+
+
+File: cp-tools.info,  Node: Taglet Options,  Next: Virtual Machine Options,  Prev: Decoration Options,  Up: gjdoc Tool
+
+4.7 Custom Documentation Tags
+=============================
+
+`-tagletpath PATHLIST'
+     Search PATHLIST when loading subsequent Taglet classes specified
+     using `-taglet'.
+
+     PATHLIST should be one or more paths to a directory or jar file,
+     separated by your platform's path separator (usually `:' or `;').
+
+`-taglet CLASSNAME'
+     Register a Taglet.
+
+     CLASSNAME should be the fully-qualified name of a Java class
+     implementing `com.sun.tools.doclets.Taglet'.
+
+     The Taglet classes will be loaded from the classpath specified
+     using `-tagletpath', from the classpath specified using
+     `-classpath' and from the default classpath.
+
+     See the documentation of `com.sun.tools.doclets.Taglet' for
+     further information.
+
+     Note that for simple tags, there is also `-tag'.
+
+`-tag TAGSPEC'
+     Register a generic Taglet.
+
+     The format of TAGSPEC must be `<tagname>:<flags>:"<taghead>"'.
+
+     TAGNAME is the tag name to match, without the leading @ sign.
+
+     FLAGS is one or more of the following characters, where each
+     character specifies a source code context in which the tag is to be
+     recognized.
+
+    `a'
+          all contexts
+
+    `c'
+          constructors
+
+    `f'
+          fields
+
+    `m'
+          methods
+
+    `o'
+          overview
+
+    `p'
+          packages
+
+    `t'
+          types (classes, interfaces, exceptions, errors)
+
+    `X'
+          special character which temporarily disables the Taglet
+          altogether.
+
+     TAGHEAD is the string to display in the header of the section
+     devoted to the tag in question.
+
+     For example, to define a tag matching `@cvsid' which is to be
+     accepted in overview, package and type pages and which is labelled
+     with the header `CVS ID', you would specify:
+
+          -tag cvsid:tpo:"CVS ID"
+
+     Let's say that a class javadoc comment contains
+
+          @cvsid $Id: cp-tools.texinfo,v 1.7 2008/08/13 13:32:05 jsumali Exp $
+
+     Then the HTML output will contain something like
+
+          CVS ID:
+            $Id: cp-tools.texinfo,v 1.7 2008/08/13 13:32:05 jsumali Exp $
+
+
+File: cp-tools.info,  Node: Doclet Options,  Next: Other Doclets,  Prev: Verbosity Options,  Up: gjdoc Tool
+
+4.8 Running Other Doclets
+=========================
+
+`-docletpath PATHLIST'
+     Search PATHLIST when loading classes for the Doclet specified
+     using `-doclet'.
+
+     PATHLIST should be one or more paths to a directory or jar file,
+     separated by your platform's path separator (usually `:' or `;').
+
+`-doclet CLASSNAME'
+     Run the specified doclet instead of the standard HtmlDoclet.
+
+     CLASSNAME should be the fully-qualified name of a class which has
+     a public default constructor and contain a method with the
+     following signature:
+
+             import com.sun.javadoc.RootDoc;
+             public static boolean start(RootDoc rootDoc)
+
+     The Doclet classes will be loaded from the classpath specified
+     using `-docletpath', from the classpath specified using
+     `-classpath' and from the default classpath.
+
+     The `start' method should process the information exposed by the
+     Doclet API via `rootDoc' and return `true' on success, `false' on
+     failure.
+
+     If you are using a third-party doclet, refer to its documentation
+     for further instructions.  Note that support for third-party
+     doclets is experimental.  Please report any problems you
+     encounter, or provide feedback when successfully running
+     third-party applets.
+
+     This option can be specified multiple times, in which case all
+     doclets are executed with the same information tree exposed via
+     the Doclet API for each Doclet run.
+
+
+
+File: cp-tools.info,  Node: Decoration Options,  Next: Taglet Options,  Prev: Generation Options,  Up: gjdoc Tool
+
+4.9 Adding Information to the Output
+====================================
+
+`-windowtitle TEXT'
+     Use TEXT as the browser window title prefix.
+
+     When specified, the browser window title for each page will be
+     prefixed with TEXT instead of the default string `Generated API
+     Documentation'.
+
+     TEXT should be plain text (it should not contain HTML tags).
+
+`-doctitle TEXT'
+     Set the header text of the overview page to TEXT.
+
+     TEXT should be a short plain text string.
+
+     When generating documentation for a single package, specifying this
+     option forces generation of the overview page.
+
+`-header HTMLTEXT'
+     Add HTMLTEXT to the right upper corner of every generated page.
+     HTMLTEXT is usually set to the name of the project being
+     documented.
+
+`-footer HTMLTEXT'
+     Add HTMLTEXT to the right bottom corner of every generated page.
+     HTMLTEXT is often set to the same value as for `-header'.
+
+`-bottom HTMLTEXT'
+     Add HTMLTEXT to the very bottom of every generated page, spanning
+     the whole width of the page.  When specified, HTMLTEXT usually
+     consists of a copyright notice and/or links to other project pages.
+
+`-addstylesheet FILE'
+     Augment the default CSS style sheets with the user-specified
+     stylesheet FILE.
+
+     The given stylesheet is simply loaded by each HTML page in
+     addition to the default ones, as the last stylesheet.
+
+     Note that the CSS cascading rules apply.  That is, your style
+     properties will only be assigned if they have a higher cascading
+     order than `gjdoc''s default style.  One simple way to make sure
+     that this is the case is to declare your overrides `!important'.
+
+     See `http://www.w3.org/TR/REC-CSS2/cascade.html#cascading-order'.
+
+`-group HEADING PKGWILDCARD:PKGWILDCARD:...'
+     Arrange the given packages in a separate group on the overview
+     page.
+
+     The first argument should be a short plain text which is used as
+     the title of the package group.  The second argument should be a
+     colon-separated list of package wildcards.  The group will consist
+     of all packages in the documentation set whose name matches any of
+     the given wildcards.
+
+     There is only one wildcard character, `*', which matches both
+     letters in package name components and the `.' separating package
+     name components.  For example, `j*regex' would match package
+     `java.util.regex'.  A more useful example would be `javax.swing*'
+     to match `javax.swing' and all of its sub-packages.
+
+     This option can be given multiple times.
+
+     FIXME: Information about group nesting here.
+
+          gjdoc -group "Core Classes" 'java*' \
+                -group "Swing" 'javax.swing*' \
+                -group "XML APIs" 'javax.xml*' \
+                -group "Other Extensions" javax* \
+                ...
+
+`-overview FILE'
+     Add the XHTML body fragment from FILE to the overview page.
+
+     FILE should contain an XHTML fragment with the HTML `body' tag as
+     the root node.  *Note XHTML Fragments::.
+
+     This option can be used to supply a description of the
+     documentation set as a whole.
+
+     When specified, the first sentence of the fragment will be put
+     above the tables listing the documented packages, along with a
+     link to the full copy of the fragment which is put below the
+     tables.  *Note First Sentence Detector::.
+
+     When generating documentation for a single package, specifying this
+     option forces generation of the overview page.
+
+`-stylesheetfile FILE'
+     Use the CSS stylesheet in FILE instead of the default CSS
+     stylesheets.
+
+     If you only want to override parts of the default stylesheets, use
+     `-addstylesheet' instead.
+
+`-title TEXT'
+     _Deprecated._ Use `-doctitle' TEXT instead.
+
+`-helpfile FILE'
+     This option is currently ignored.
+
+     When implemented, it will use the XHTML fragment in FILE for the
+     help page contents instead of the default help text.
+
+
+
+File: cp-tools.info,  Node: Output Control Options,  Next: Generation Options,  Prev: Interlinking Options,  Up: gjdoc Tool
+
+4.10 Controlling the Output.
+============================
+
+`-d DIRECTORY'
+     Place all output files into DIRECTORY (and sub-directories).
+     DIRECTORY will be created if it does not exist, including all
+     non-existing parent directories and all required sub-directories.
+
+     If not specified, output will be placed into the current directory.
+
+`-locale NAME'
+     Use locale NAME instead of the default locale for all purposes.
+
+     NAME should be a locale specifier in the form `ll_CC[_VAR]' where
+     `ll' is a lowercase two-letter ISO-639 language code, `CC' is an
+     optional uppercase two-letter ISO-3166 country code, and `VAR' is
+     an optional variant code.  For example, `en' specifies English,
+     `en_US' specifies US English, and `en_US_WIN' specifies a deviant
+     variant of the US English locale.
+
+     Note that the semantics of this option correspond exactly to those
+     of the constructors of class `java.util.Locale'.
+
+     This option currently only determines which Collator is being used
+     for sorting output elements.  This means that the locale will only
+     have an effect when you are using non-ASCII characters in
+     identifiers.
+
+`-charset CHARSET'
+     _Deprecated._ Override the specified encoding in output XHTML
+     files with the one given by `charset'.
+
+     If this option is not given, the encoding specification in output
+     XHTML is chosen to match the encoding used when writing the file
+     (the encoding given with `-docencoding', or your platform's default
+     encoding).
+
+     The semantics for CHARSET are specified here:
+     `http://www.w3.org/TR/2000/REC-xml-20001006#NT-EncName'.  For all
+     practical purposes, they are identical to those of the other
+     options accepting charset parameters.
+
+     This option is here for compatibility with `javadoc' and should be
+     avoided.
+
+`-docencoding CHARSET'
+     Use the given charset encoding when writing output files instead of
+     your platform's default encoding.
+
+     Examples for CHARSET are `US-ASCII', `ISO-8859-1' or `UTF-8'.
+
+     The semantics of this option correspond exactly to those of the
+     constructors of class `java.util.Locale'.
+
+`-validhtml'
+     Force generation of valid XHTML code.  This breaks compatibility to
+     the traditional Javadoc tool to some extent.
+
+     If this option is specified, anchor names will be mangled so that
+     they are valid according to the XHTML 1.1 specification.  However,
+     a documentation set generated with this option cannot be linked to
+     properly using the traditional Javadoc tool.  It can be linked to
+     just fine using Gjdoc, though.
+
+     Without this option, anchor names for executable class members use
+     the traditional format, for example: "foo(String,int[])".  This is
+     compatible to the traditional Javadoc tool, but according to both
+     the HTML 4.0 and XHTML 1.0 and 1.1 specifications, this format
+     includes illegal characters.  Parentheses, square brackets, and
+     the comma are not allowed in anchor names.
+
+`-baseurl URL'
+     Hardwire a page URL relative to URL into each generated page.
+
+     If you are generating documentation which will exclusively be
+     available at a certain URL, you should use this option to specify
+     this URL.
+
+     This can help avoid certain redirect attacks used by spammers, and
+     it can be helpful for certain web clients.
+
+
+
+File: cp-tools.info,  Node: Verbosity Options,  Next: Doclet Options,  Prev: Virtual Machine Options,  Up: gjdoc Tool
+
+4.11 Verbosity Options
+======================
+
+`-quiet'
+     Suppress all output except for warnings and error messages.
+
+`-verbose'
+     Be very verbose about what `gjdoc' is doing.
+
+     This option is currently ignored.
+
+
+
+File: cp-tools.info,  Node: Virtual Machine Options,  Next: Verbosity Options,  Prev: Taglet Options,  Up: gjdoc Tool
+
+4.12 Virtual Machine Options
+============================
+
+Sun's `javadoc' tool seems to be based on `javac' and as such it seems
+to operate on the VM level.  `gjdoc', in contrast, is a pure Java
+application.
+
+   Therefore, `gjdoc' can only fake, or simulate, the following
+VM-level options.
+
+`-classpath PATHLIST'
+     Set the Virtual Machine `classpath' to PATHLIST.
+
+     In most cases you should use `-docletpath' or `-tagletpath'
+     instead of this option.
+
+     PATHLIST should be one or more paths to a directory or jar file,
+     separated by your platform's path separator (usually `:' or `;').
+
+     If this option is not intercepted at the wrapper level, `gjdoc'
+     currently fakes it by calling
+     `System.setProperty("java.class.path", PATHLIST);' and outputs a
+     warning.
+
+`-bootclasspath PATHLIST'
+     Set the Virtual Machine `bootclasspath' to PATHLIST.
+
+     If this option is not intercepted at the wrapper level, `gjdoc'
+     outputs a warning.
+
+`-JVMOPT'
+     Pass an arbitrary parameter to the Virtual Machine `gjdoc' runs on.
+
+     If this option is not intercepted at the wrapper level, `gjdoc'
+     tries to emulate the option and outputs a warning.
+
+     Currently, only the VM option `-D' for setting system properties
+     is emulated.
+
+
+
+File: cp-tools.info,  Node: Invoking a Custom Doclet,  Next: Option Summary by Type,  Prev: Invoking the Standard Doclet,  Up: gjdoc Tool
+
+4.13 Invoking a Custom Doclet
+=============================
+
+For invoking one of the other doclets shipping with `gjdoc' or a
+third-party doclet, the canonical usage is:
+
+     gjdoc -s src/java/ -all \
+       -docletpath /path/to/doclet.jar -doclet foo.BarDoclet \
+       (more Gjdoc core options and Doclet-specific options here)
+
+   `/path/to/doclet.jar' is a placeholder for a class path specifying
+where the Doclet classes and dependencies can be found and
+`foo.BarDoclet' is the fully-qualified name of the Doclet's main class.
+
+
+File: cp-tools.info,  Node: Gjdoc Option Summary,  Next: Source Set Options,  Prev: Option Summary by Type,  Up: gjdoc Tool
+
+4.14 Gjdoc Option Summary
+=========================
+
+
+File: cp-tools.info,  Node: Other Doclets,  Next: Gjdoc Concepts,  Prev: Doclet Options,  Up: gjdoc Tool
+
+5 Generating Other Output Types
+*******************************
+
+* Menu:
+
+* Built-in Doclets::
+* Third-party Doclets::
+
+
+File: cp-tools.info,  Node: Built-in Doclets,  Next: Third-party Doclets,  Up: Other Doclets
+
+5.1 Using the Built-in Doclets
+==============================
+
+* Menu:
+
+* Using XmlDoclet::
+* Using TexiDoclet::
+* Using IspellDoclet::
+* Using DebugDoclet::
+
+
+File: cp-tools.info,  Node: Using TexiDoclet,  Next: Using XmlDoclet,  Up: Built-in Doclets
+
+5.1.1 TexiDoclet: Generating Info, PDF, and other formats
+---------------------------------------------------------
+
+Missing.
+
+
+File: cp-tools.info,  Node: Using XmlDoclet,  Next: Using IspellDoclet,  Prev: Using TexiDoclet,  Up: Built-in Doclets
+
+5.1.2 XmlDoclet: Generating XML Documentation
+---------------------------------------------
+
+Missing.
+
+
+File: cp-tools.info,  Node: Using IspellDoclet,  Next: Using DebugDoclet,  Prev: Using XmlDoclet,  Up: Built-in Doclets
+
+5.1.3 IspellDoclet: Spell-checking Source Code
+----------------------------------------------
+
+Missing.
+
+
+File: cp-tools.info,  Node: Using DebugDoclet,  Prev: Using IspellDoclet,  Up: Built-in Doclets
+
+5.1.4 DebugDoclet: Inspecting the Doclet API
+--------------------------------------------
+
+Missing.
+
+
+File: cp-tools.info,  Node: Third-party Doclets,  Prev: Built-in Doclets,  Up: Other Doclets
+
+5.2 Using Third-Party Doclets
+=============================
+
+* Menu:
+
+* DocBook Doclet::
+* PDFDoclet::
+* JUnitDoclet::
+
+
+File: cp-tools.info,  Node: DocBook Doclet,  Next: PDFDoclet,  Up: Third-party Doclets
+
+5.2.1 DocBook Doclet
+--------------------
+
+Missing.
+
+
+File: cp-tools.info,  Node: PDFDoclet,  Next: JUnitDoclet,  Prev: DocBook Doclet,  Up: Third-party Doclets
+
+5.2.2 PDFDoclet
+---------------
+
+Missing.
+
+
+File: cp-tools.info,  Node: JUnitDoclet,  Prev: PDFDoclet,  Up: Third-party Doclets
+
+5.2.3 JUnitDoclet
+-----------------
+
+Missing.
+
+
+File: cp-tools.info,  Node: Gjdoc Concepts,  Prev: Other Doclets,  Up: gjdoc Tool
+
+6 Advanced Concepts
+*******************
+
+* Menu:
+
+* Writing Doclets::
+* Taglets::
+* XHTML Fragments::
+* First Sentence Detector::
+* Adding Custom Resources::
+
+
+File: cp-tools.info,  Node: Taglets,  Next: Writing Doclets,  Up: Gjdoc Concepts
+
+6.1 Adding Custom Tags to the Documentation
+===========================================
+
+Missing.
+
+
+File: cp-tools.info,  Node: Writing Doclets,  Next: XHTML Fragments,  Prev: Taglets,  Up: Gjdoc Concepts
+
+6.2 Writing Doclets
+===================
+
+If the various Doclets already available don't suit your needs, you can
+write a custom Doclet yourself.
+
+* Menu:
+
+* Doclet Invocation Interface::
+* Using AbstractDoclet::
+* GNU Doclet SPI::
+
+
+File: cp-tools.info,  Node: Doclet Invocation Interface,  Next: Using AbstractDoclet,  Up: Writing Doclets
+
+6.2.1 Implementing the Doclet Invocation Interface
+--------------------------------------------------
+
+A Doclet is a class that contains a method with the following signature:
+
+     public static boolean start(RootDoc rootDoc);
+
+   ROOTDOC is the root of an object hierarchy containing the
+information `gjdoc' extracted from the source files.  See the Doclet
+API for more details.
+
+   `start' should process all the information and return `true' on
+success, `false' on failure.
+
+   For printing status information, the Doclet should use methods
+`printNotice', `printWarning' and `printError' instead of `System.err'.
+The Doclet can opt to use `System.out' for redirectable output.
+
+
+File: cp-tools.info,  Node: Using AbstractDoclet,  Next: GNU Doclet SPI,  Prev: Doclet Invocation Interface,  Up: Writing Doclets
+
+6.2.2 Deriving Your Doclet from AbstractDoclet
+----------------------------------------------
+
+You may want your Doclet to provide functionality similar to
+HtmlDoclet.  For example, you may want it to support Taglets, generate
+Index, Tree, and Uses pages, or show other cross-reference information
+like `Overrides' and `All Implementing Classes'.
+
+   This information is not directly provided by the Doclet API, so your
+Doclet would normally have to assemble it itself.  For example, it
+would have to add the names of all program elements to a list and sort
+this list in order to create the Index page.
+
+   If you want to provide this information or part of it, you should
+consider deriving your class from
+`gnu.classpath.tools.doclets.AbstractDoclet'.  This class provides the
+following benefits:
+
+   * Handles options `-tag', `-taglet', `-tagletpath' (Taglets)
+
+   * Provides standard taglets for @version, @author, @since, @serial,
+     @deprecated, @see, @param, @return and handles all related options
+     (`-version', `-author', `-nosince', `-nodeprecated')
+
+   * Handles option `-d' (destination directory)
+
+   * Handles option `-noqualifier' (classes to omit qualifier for)
+
+   * Handles options `-docfilessubdirs' and `-excludedocfilessubdir'
+     (resource copying)
+
+   * Can generate a full index or an index split by first letter
+
+   * Can generate a full tree and package trees
+
+   * Can generate cross-reference information
+
+   * Can aggregate interface information (all superinterfaces, all
+     subinterfaces, all implementing classes)
+
+   * Provides convenient access to constructors, fields, methods, and
+     inner classes sorted by name/signature instead of the default sort
+     order.
+
+   * Provides various other convenience methods
+
+
+   If you derive from `AbstractDoclet', there are a number of things
+you need to take care of:
+
+   *
+   you should not implement the `start(RootDoc)' method as it is
+already defined by `AbstractDoclet' so that it can care about parsing
+the options.
+
+   Instead, you implement method `run()', `getOptions()' and the other
+abstract methods to define your Doclet's behavior.
+
+   Note that all information provided by `AbstractDoclet' is evaluated
+lazily.  That is, if your Doclet doesn't need to create an Index page,
+then `AbstractDoclet' will not spend resources on creating the
+corresponding information.
+
+   See the API documentation for
+`gnu.classpath.tools.doclets.AbstractDoclet' for more details.
+
+   You should be aware that if you base your Doclet on `AbstractDoclet'
+then you have to bundle this and all related classes with your Doclet,
+with all implications such as possible licensing issues.  Otherwise,
+your Doclet will only be runnable on `gjdoc' and not on other
+documentation systems.  Also note that `AbstractDoclet' has not been
+extensively tested in environments other than `gjdoc'.
+
+
+File: cp-tools.info,  Node: GNU Doclet SPI,  Prev: Using AbstractDoclet,  Up: Writing Doclets
+
+6.2.3 Preparing for the GNU Doclet Service Provider Interface
+-------------------------------------------------------------
+
+In addition to the standard Doclet invocation interface described
+above, `gjdoc' also offers a Service Provider Interface conforming to
+the Java standard.  Adding support for this interface to your Doclet
+simplifies usage for `gjdoc' users because it makes your Doclet
+"discoverable".
+
+   In order to provide the alternate interface, you have to add a class
+implementing `gnu.classpath.tools.gjdoc.spi.DocletSpi' to your Doclet
+classes, and bundle all Doclet classes in a Jar file along with a file
+named `META_INF/services/gnu.classpath.tools.gjdoc.spi.DocletSpi' which
+contains the name of your class implementing DocletSpi on a single line.
+
+   Note that if your Doclet depends on third-party classes bundled in
+separate Jar files, you can link in these classes using the
+`Class-path:' Manifest attribute of your Doclet Jar.
+
+   Your Doclet can then be invoked in one of the following ways:
+     gjdoc -docletjar /path/to/doclet.jar
+     gjdoc -docletpath /path/to/doclet.jar -docletname DOCLETNAME
+     gjdoc -docletname DOCLETNAME
+
+   Here, DOCLETNAME is the name of your doclet as returned by
+`DocletSpi.getDocletName()'.
+
+   The last example will only work if your Doclet Jar is in `gjdoc''s
+`doclets' directory or if it is on the classpath.
+
+
+File: cp-tools.info,  Node: XHTML Fragments,  Next: First Sentence Detector,  Prev: Writing Doclets,  Up: Gjdoc Concepts
+
+6.3 Well-formed Documentation Fragments
+=======================================
+
+For many Doclets it is advantagous if the HTML code in the comments and
+HTML code passed via the command line is well-formed.  For example,
+HtmlDoclet outputs XHTML code, and XmlDoclet XML code, both of which
+results in invalid files if the user-specified HTML isn't wellformed.
+
+   Unfortunately, comments were never required to contain well-formed
+HTML code, which means that every Doclet must deal with non-wellformed
+code as well.
+
+   The `gjdoc' built-in Doclets deal with this problem by "fixing" the
+HTML code - making sure that all tags are closed, attribute values are
+provided and quoted, tags are properly nested, etc.
+
+   This approach works OK in most instances, but since it uses some
+crude heuristics it can sometimes produce undesirable result.
+
+   Therefore, in order to make sure that your comments are always
+properly formatted, make sure they are well-formed as described in
+XHTML 1.0: Documents must be well-formed (http://www.w3.org/TR/xhtml1/#h-4.1).
+
+   In addition, you should use meaningful tags instead of text
+formatting tags to make your output look better in other output formats
+derived from your HTML code.  For example, you should use the <em> tag
+instead of <b> if you want to emphasize text.
+
+
+File: cp-tools.info,  Node: First Sentence Detector,  Next: Adding Custom Resources,  Prev: XHTML Fragments,  Up: Gjdoc Concepts
+
+6.4 How Gjdoc Determines where the First Sentence Ends
+======================================================
+
+For a package, class or member summary, `gjdoc' only shows the first
+sentence of the documentation comment in question.  Because `gjdoc' is
+not human, it is not always obvious to `gjdoc' where the first sentence
+ends.
+
+   You might be tempted to say that the first sentence ends at the first
+occurrence of a punctuation character like `.' or `!'. However,
+consider examples like this:
+     This work, by Thomas J. Shahan et al., is about the middle ages.
+
+   As you can see, it is not trivial to determine the end of the
+sentence.
+
+   `gjdoc' gives you the choice between two approaches.  By default it
+uses built-in heuristics which should be compatible to Sun's `javadoc'
+tool.  This approach works quiet well in most cases, at least for
+english comments.
+
+   Alternatively, you can specify option `-breakiterator' in which case
+`gjdoc' will use
+`java.text.BreakIterator.getSentenceInstance(LOCALE).next()' to find
+the end of sentence, where LOCALE is the locale specified by option
+`-locale' or the default locale if none specified.
+
+   _NOT YET IMPLEMENTED:_
+
+   `gjdoc' also allows you to explicitly delineate the first sentence
+by putting it in a `<span>' tag with the CSS class `first-sentence'.
+For example:
+     /**
+      *  <span class="first-sentence">This. is. the. first.
+      *  sentence.</span> This is the second sentence.
+      */
+
+   Note that this will only work with `gjdoc', but shouldn't hurt when
+using another documentation system since the `<span>' tag usually
+doesn't show up in the output.
+
+
+File: cp-tools.info,  Node: Adding Custom Resources,  Prev: First Sentence Detector,  Up: Gjdoc Concepts
+
+6.5 Adding Images and Other Resources
+=====================================
+
+Sometimes you want to decorate your documentation with secondary
+resources such as images, SVG graphics, applets, and so on.  To do so,
+simply put the required files in a subdirectory 'doc-files' in the
+package directory corresponding to the documentation entry you want to
+decorate, and refer to it with the URL `doc-files/FILENAME'.
+
+   For example, if you want to add an image to the description of class
+`baz.FooBar', create a directory `doc-files' in the directory `baz'
+containing `FooBar.java' and put your file, say `diagram.png', into
+that directory.  Then, add the HTML code like this to a comment in
+`FooBar.java':
+     <img src="doc-files/diagram.png" width="200" height="150"
+       alt="Foo Diagram"/>
+
+   This works because the `doc-files' subdirectories will be copied to
+the target documentation directory every time you generate the
+documentation.
+
+   Note however that by default, the `doc-files' directory will not be
+copied deeply.  In other words, if you create subdirectories under
+`doc-files' they will not be copied and any resources located in these
+subdirectories will not be accessible in your generated documentation.
+You can specify option `-docfilessubdirs' to remove this limitation.
+
+   Sometimes you want to use option `-docfilessubdirs', but there are
+certain directories which you don't want to be copied, for example
+because they contain source files for the resources in `doc-files'.
+For cases like this, use `-excludedocfilessubdir' to specify
+directories to be omitted.
+
+
+File: cp-tools.info,  Node: I18N Issues,  Prev: Other Tools,  Up: Top
+
+7 I18N Issues
+*************
+
+Some tools -*note Security Tools::- allow using other than the English
+language when prompting the User for input, and outputting messages.
+This chapter describes the elements used to offer this support and how
+they can be adapted for use with specific languages.
+
+* Menu:
+
+* Language Resources::         Where resources are located
+* Message Formats::            How messages are internationalized
+
+
+File: cp-tools.info,  Node: Language Resources,  Next: Message Formats,  Prev: I18N Issues,  Up: I18N Issues
+
+7.1 Language-specific resources
+===============================
+
+The Tools use Java `ResourceBundle's to store messages, and message
+templates they use at runtime to generate the message text itself,
+depending on the locale in use at the time.
+
+   The Resource Bundles these tools use are essentially Java Properties
+files consisting of a set of Name/Value pairs. The Name is the Property
+Name and the Value is a substitution string that is used when the code
+references the associated Name. For example the following is a line in
+a Resource Bundle used by the `keytool' Tool:
+
+     Command.23=A correct key password MUST be provided
+
+   When the tool needs to signal a mandatory but missing key password,
+it would reference the property named `Command.23' and the message "`A
+correct key password MUST be provided'" will be used instead. This
+indirect referencing of "resources" permits replacing, as late as
+possible, the English strings with strings in other languages, provided
+of course Resource Bundles in those languages are provided.
+
+   For the GNU Classpath Tools described in this Guide, the Resource
+Bundles are files named `messages[_ll[_CC[_VV]]].properties' where:
+
+LL
+     Is the 2-letter code for the Language,
+
+CC
+     Is the 2-letter code for the Region, and
+
+VV
+     Is the 2-letter code for the Variant of the language.
+
+   The complete list of language codes can be found at Code for the
+representation of names of languages
+(http://ftp.ics.uci.edu/pub/ietf/http/related/iso639.txt). A similar
+list for the region codes can be found at ISO 3166 Codes (Countries)
+(http://userpage.chemie.fu-berlin.de/diverse/doc/ISO_3166.html).
+
+   The location of the Resource Bundles for the GNU Classpath Tools is
+specific to each tool. The next table shows where these files are found
+in a standard GNU Classpath distribution:
+
+`jarsigner'
+     `gnu/classpath/tools/jarsigner'
+
+`keytool'
+     `gnu/classpath/tools/keytool'
+
+   The collection of Resource Bundles in a location act as an inverted
+tree with a parent-child relationship. For example suppose in the
+`gnu/classpath/tools/keytool' there are 3 message bundles named:
+
+  1. `messages.properties'
+
+  2. `messages_fr.properties'
+
+  3. `messages_fr_FR.properties'
+
+   In the above example, bundle #1 will act as the parent of bundle #2,
+which in turn will act as the parent for bundle #3. This ordering is
+used by the Java runtime to choose which file to load based on the set
+Locale. For example if the Locale is `fr_CH', `messages_fr.properties'
+will be used because (a) `messages_fr_CH.properties' does not exist,
+but (b) `messages_fr.properties' is the parent for the required bundle,
+and it exists. As another example, suppose the Locale was set to
+`en_AU'; then the tool will end up using `messages.properties' because
+(a) `messages_en_AU.properties' does not exist, (b)
+`messages_en.properties' which is the parent for the required bundle
+does not exist, but (c) `messages.properties' exists and is the root of
+the hierarchy.
+
+   You can see from the examples above that `messages.properties' is
+the safety net that the Java runtime falls back to when failing to find
+a specific bundle and its parent(s). This file is always provided with
+the Tool. In time, more localized versions will be included to cater
+for other languages.
+
+   In the meantime, if you are willing to contribute localized versions
+of these resources, grab the `messages.properties' for a specific tool;
+translate it; save it with the appropriate language and region suffix
+and mail it to `classpath@gnu.org'.
+
+
+File: cp-tools.info,  Node: Message Formats,  Prev: Language Resources,  Up: I18N Issues
+
+7.2 Message formats
+===================
+
+If you open any of the `messages.properties' described in the previous
+section, you may see properties that look like so:
+
+     Command.67=Issuer: {0}
+     Command.68=Serial number: {0,number}
+     Command.69=Valid from: {0,date,full} - {0,time,full}
+     Command.70=\ \ \ \ \ until: {0,date,full} - {0,time,full}
+
+   These are Message Formats used by the tools to customize a text
+string that will then be used either as a prompt for User input or as
+output.
+
+   If you are translating a `messages.properties' be careful not to
+alter text between curly braces.
+
+
+
+Tag Table:
+Node: Top435
+Node: Applet Tools6155
+Node: appletviewer Tool6728
+Node: gcjwebplugin9843
+Node: Security Tools10155
+Node: jarsigner Tool10808
+Node: Common jarsigner Options11856
+Node: Signing Options13171
+Node: Verification Options15754
+Node: keytool Tool16342
+Node: Getting Help20770
+Node: Common keytool Options21514
+Ref: alias21787
+Ref: keyalg22169
+Ref: keysize22399
+Ref: validity22664
+Ref: storetype22879
+Ref: storepass23210
+Ref: keystore23407
+Ref: provider23950
+Ref: file24357
+Ref: verbose24828
+Node: Distinguished Names24920
+Ref: dn25114
+Node: Add/Update Commands26177
+Node: Command -genkey26705
+Node: Command -import29114
+Node: Command -selfcert32258
+Node: Command -cacert34437
+Node: Command -identitydb35490
+Node: Export Commands36148
+Node: Command -certreq36464
+Node: Command -export38870
+Node: Display Commands40067
+Node: Command -list40399
+Node: Command -printcert41532
+Node: Management Commands41916
+Node: Command -keyclone42348
+Node: Command -storepasswd43751
+Node: Command -keypasswd44480
+Node: Command -delete45674
+Node: Other Tools46297
+Node: jar Tool47139
+Node: javah Tool48531
+Node: gcjh Tool49750
+Node: native2ascii Tool50863
+Node: orbd Tool51324
+Node: serialver Tool52054
+Node: rmid Tool52523
+Node: rmiregistry Tool53464
+Node: tnameserv Tool54304
+Node: gjdoc Tool54928
+Node: Invoking the Standard Doclet56916
+Node: Option Summary by Type58071
+Node: Source Set Options60501
+Node: Source Format Options62365
+Node: Interlinking Options63879
+Node: Generation Options66656
+Node: Taglet Options72753
+Node: Doclet Options74974
+Node: Decoration Options76550
+Node: Output Control Options80641
+Node: Verbosity Options84173
+Node: Virtual Machine Options84519
+Node: Invoking a Custom Doclet85915
+Node: Gjdoc Option Summary86590
+Node: Other Doclets86770
+Node: Built-in Doclets86998
+Node: Using TexiDoclet87253
+Node: Using XmlDoclet87475
+Node: Using IspellDoclet87700
+Node: Using DebugDoclet87928
+Node: Third-party Doclets88128
+Node: DocBook Doclet88344
+Node: PDFDoclet88487
+Node: JUnitDoclet88640
+Node: Gjdoc Concepts88774
+Node: Taglets89018
+Node: Writing Doclets89201
+Node: Doclet Invocation Interface89541
+Node: Using AbstractDoclet90333
+Node: GNU Doclet SPI93327
+Node: XHTML Fragments94799
+Node: First Sentence Detector96232
+Node: Adding Custom Resources97994
+Node: I18N Issues99690
+Node: Language Resources100192
+Node: Message Formats103856
+
+End Tag Table
diff --git a/libjava/classpath/doc/cp-tools.texinfo b/libjava/classpath/doc/cp-tools.texinfo
new file mode 100644
index 000000000..727696248
--- /dev/null
+++ b/libjava/classpath/doc/cp-tools.texinfo
@@ -0,0 +1,3287 @@
+\input texinfo @c -*-texinfo-*-
+
+@c %**start of header
+@setfilename cp-tools.info
+@settitle GNU Classpath Tools Guide
+@c %**end of header
+
+@setchapternewpage on
+
+@c Common macros to support generating man pages:
+
+@macro gcctabopt{body}
+@code{\body\}
+@end macro
+@macro gccoptlist{body}
+@smallexample
+\body\
+@end smallexample
+@end macro
+
+@ifinfo
+This file documents the Tools included in a standard distribution of the GNU
+Classpath project deliverables.
+
+Copyright (C) 2006, 2007 Free Software Foundation, Inc.
+
+@ifnotplaintext
+@dircategory GNU Libraries
+@direntry
+* Classpath Tools: (cp-tools).  GNU Classpath Tools Guide
+@end direntry
+@end ifnotplaintext
+@end ifinfo
+
+@titlepage
+@title GNU Classpath Tools Guide
+@author The GNU Classpath Team
+
+@page
+@vskip 0pt plus 1filll
+Copyright @copyright{} 2006 Free Software Foundation, Inc.
+@sp 2
+Permission is granted to make and distribute verbatim copies of this document provided the copyright notice and this permission notice are preserved on all copies.
+
+Permission is granted to copy and distribute modified versions of this document under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Free Software Foundation.
+
+@end titlepage
+
+@contents
+
+@ifinfo
+@node Top, Applet Tools, (dir), (dir)
+@top GNU Classpath Tools Guide
+
+This document contains important information you need to know in order to use
+the tools included in the GNU Classpath project deliverables.
+
+The Tools aim at providing a free replacement, similar in their behavior, to
+their counter-parts found in the Reference Implementation (RI) of the Java
+Software Development Kit (SDK).
+
+@end ifinfo
+
+@menu
+* Applet Tools::               Work with applets
+* Security Tools::             Work securely with Java applications
+* Other Tools::                Other tools in classpath
+* I18N Issues::                How to add support for non-English languages
+
+@detailmenu
+ --- The Detailed Node Listing ---
+
+Applet Tools
+
+* appletviewer Tool::          Load applets
+* gcjwebplugin::               Load applets in a web browser
+
+Security Tools
+
+* jarsigner Tool::             Sign and verify .JAR files
+* keytool Tool::               Manage private keys and public certificates
+
+jarsigner Tool
+
+* Common jarsigner Options::   Options used when signing or verifying a file
+* Signing Options::            Options only used when signing a .JAR file
+* Verification Options::       Options only used when verifying a .JAR file
+
+keytool Tool
+
+* Getting Help::               How to get help with keytool commands
+* Common keytool Options::     Options used in more than one command
+* Distinguished Names::        X.500 Distinguished Names used in certificates
+* Add/Update Commands::        Commands for adding data to a Key Store
+* Export Commands::            Commands for exporting data from a Key Store
+* Display Commands::           Commands for displaying data in a Key Store
+* Management Commands::        Commands for managing a Key Store
+
+Add/Update Commands
+
+* Command -genkey::            Generate private key and self-signed certificate
+* Command -import::            Import certificates and certificate replies
+* Command -selfcert::          Generate self-signed certificate
+* Command -cacert::            Import a CA Trusted Certificate
+* Command -identitydb::        Import JDK-1 style identities
+
+Export Commands
+
+* Command -certreq::           Generate Certificate Signing Requests (CSR)
+* Command -export::            Export a certificate in a Key Store
+
+Display Commands
+
+* Command -list::              Display information about one or all Aliases
+* Command -printcert::         Print a certificate or a certificate fingerprint
+
+Management Commands
+
+* Command -keyclone::          Clone a Key Entry in a Key Store
+* Command -storepasswd::       Change the password protecting a Key Store
+* Command -keypasswd::         Change the password protecting a Key Entry
+* Command -delete::            Remove an entry in a Key Store
+
+Other Tools
+
+* jar Tool::                   Archive tool for Java archives
+* javah Tool::                 A java header compiler
+* gcjh Tool::                  A java header compiler (old version)
+* native2ascii Tool::          An encoding converter
+* orbd Tool::                  An object request broker daemon
+* serialver Tool::             A serial version command
+* rmid Tool::                  RMI activation daemon
+* rmiregistry Tool::           Remote object registry
+* tnameserv Tool::             Naming service
+* gjdoc Tool::                 Documenation generator tool.
+
+Generating HTML Documentation
+
+* Invoking the Standard Doclet::   How to generate HTML documentation.
+* Invoking a Custom Doclet::       How to run third-party and other 
+                                   built-in Doclets.
+
+* Option Summary by Type::         Brief list of all options, grouped by type.
+* Gjdoc Option Summary::           List of all options accepted by Gjdoc.
+
+* Source Set Options::      Select the set of source codes to run Gjdoc on.
+* Source Format Options::   Specify the format of the source codes to document.
+
+* Interlinking Options::    Connection your documentation with other projects.
+* Output Control Options::  Specify the target directory and locale, and more.
+* Generation Options::      Select which pieces of information to generate.
+* Decoration Options::      Add or modify some titles, headers and footers or
+                            override/amend static resources like stylesheets.
+* Taglet Options::          Define your own javadoc @@tags.
+
+* Virtual Machine Options:: Controlling the kind of output:
+                            an executable, object files, assembler files,
+                            or preprocessed source.
+* Verbosity Options::
+* Doclet Options::
+
+* Other Doclets::           Generating Other Output Types. 
+
+* Built-in Doclets::        Using the Built-in Doclets.
+* Using XmlDoclet::
+* Using TexiDoclet::
+* Using IspellDoclet::
+* Using DebugDoclet::
+
+* Third-party Doclets::     Using Third-Party Doclets.
+* DocBook Doclet::
+* PDFDoclet::
+* JUnitDoclet::
+
+* Gjdoc Concepts::          Advanced Concepts.
+* Writing Doclets::
+
+* Doclet Invocation Interface::    Implementing the Doclet Invocation Interface
+* Using AbstractDoclet::           Deriving Your Doclet from AbstractDoclet.
+* GNU Doclet SPI::                 Preparing the GNU Doclet Service Provider
+                                   Interface.
+
+* Taglets::                        Adding Custom Tags to the Documentation.
+* XHTML Fragments::                Well-Formed Documentation Fragments.
+* First Sentence Detector::        How Gjdoc Determines where the First
+                                   Sentence Ends.
+* Adding Custom Resources::        Adding Images and Other Resources.
+
+I18N Issues
+
+* Language Resources::         Where resources are located
+* Message Formats::            How messages are internationalized
+
+@end detailmenu
+@end menu
+
+@comment ----------------------------------------------------------------------
+
+@node Applet Tools, Security Tools, Top, Top
+@comment node-name, next, previous, up
+@chapter Applet Tools
+
+Two Applet Tools are available with GNU Classpath: @b{appletviewer}
+and @b{gcjwebplugin}.
+
+To avoid conflicts with other implementations, the appletviewer
+executable is called ``gappletviewer''.
+
+@menu
+* appletviewer Tool::          Load applets
+* gcjwebplugin::               Load applets in a web browser
+@end menu
+
+If while using these tools you think you found a bug, then please report it at @uref{http://www.gnu.org/software/classpath/bugs.html,classpath-bugs}.
+
+@comment ----------------------------------------------------------------------
+
+@node appletviewer Tool, gcjwebplugin, Applet Tools, Applet Tools
+@comment node-name, next, previous, up
+@section The @code{appletviewer} Tool
+@c man title gappletviewer Load and runs an applet
+
+SYNOPSIS
+
+@c man begin SYNOPSIS gappletviewer
+appletviewer [@var{OPTION}]@dots{} @var{URL}@dots{} @var{@*}
+
+appletviewer [@var{OPTION}]@dots{} @option{-code} @var{CODE} @var{@*}
+
+appletviewer [@var{OPTION}]@dots{} @option{-plugin} @var{INPUT},@var{OUTPUT}
+@c man end
+
+DESCRIPTION
+@c man begin DESCRIPTION gappletviewer
+The @command{appletviewer} tool loads and runs an applet.
+
+Use the first form to test applets specified by tag.  The URL should
+resolve to an HTML document from which the @command{appletviewer} will
+extract applet tags.  The APPLET, EMBED and OBJECT tags are supported.
+If a given document contains multiple applet tags, all the applets
+will be loaded, with each applet appearing in its own window.
+Likewise, when multiple URLs are specified, each applet tag instance
+is given its own window.  If a given document contains no recognized
+tags the @command{appletviewer} does nothing.
+
+@smallexample
+appletviewer http://www.gnu.org/software/classpath/
+@end smallexample
+
+Use the second form to test an applet in development.  This form
+allows applet tag attributes to be supplied on the command line.  Only
+one applet may be specified using the @option{-code} option.  The
+@option{-code} option overrides the URL form -- any URLs specified will
+be ignored.
+
+@smallexample
+appletviewer -code Test.class -param datafile,data.txt
+@end smallexample
+
+@command{gcjwebplugin} uses the third form to communicate with the
+@command{appletviewer} through named pipes.
+@c man end
+
+@c man begin OPTIONS gappletviewer
+URL OPTIONS
+@table @gcctabopt
+@item -debug
+This option is not yet implemented but is provided for compatibility.
+
+@item -encoding @var{CHARSET}
+Use this option to specify an alternate character encoding for the
+specified HTML page.
+
+@end table
+
+APPLET TAG OPTIONS
+@table @gcctabopt
+@item -code @var{CODE}
+Use the @option{-code} option to specify the value of the applet tag
+@var{CODE} attribute.
+
+@item -codebase @var{CODEBASE}
+Use the @option{-codebase} option to specify the value of the applet tag
+@var{CODEBASE} attribute.
+
+@item -archive @var{ARCHIVE}
+Use the @option{-archive} option to specify the value of the applet tag
+@var{ARCHIVE} attribute.
+
+@item -width @var{WIDTH}
+Use the @option{-width} option to specify the value of the applet tag
+@var{WIDTH} attribute.
+
+@item -height @var{HEIGHT}
+Use the @option{-height} option to specify the value of the applet tag
+@var{HEIGHT} attribute.
+
+@item -param @var{NAME},@var{VALUE}
+Use the @option{-param} option to specify values for the @var{NAME}
+and @var{VALUE} attributes of an applet PARAM tag.
+
+@end table
+
+PLUGIN OPTION
+@table @gcctabopt
+@item -plugin @var{INPUT},@var{OUTPUT}
+@command{gcjwebplugin} uses the @option{-plugin} option to specify the
+named pipe the @command{appletviewer} should use for receiving commands
+(@var{INPUT}) and the one it should use for sending commands to
+@command{gcjwebplugin} (@var{OUTPUT}).
+
+@end table
+
+DEBUGGING OPTION
+@table @gcctabopt
+@item -verbose
+Use the @option{-verbose} option to have the @command{appletviewer} print
+debugging messages.
+
+@end table
+
+STANDARD OPTIONS
+
+@table @gcctabopt
+@item -help
+Use the @option{-help} option to have the @command{appletviewer} print a
+usage message, then exit.
+
+@item -version
+Use the @option{-version} option to have the @command{appletviewer} print
+its version, then exit.
+
+@item -J@var{OPTION}
+Use the @option{-J} option to pass @var{OPTION} to the virtual machine that
+will run the @command{appletviewer}.  Unlike other options, there must
+not be a space between the @option{-J} and @var{OPTION}.
+
+@end table
+@c man end
+
+@comment ----------------------------------------------------------------------
+
+@node gcjwebplugin, , appletviewer Tool, Applet Tools
+@comment node-name, next, previous, up
+@section The @code{gcjwebplugin} Tool
+
+@code{gcjwebplugin} is a plugin that adds applet support to web
+browsers.  Currently @code{gcjwebplugin} only supports Mozilla-based
+browsers (e.g., Firefox, Galeon, Mozilla).
+
+@comment ----------------------------------------------------------------------
+
+@node Security Tools, Other Tools, Applet Tools, Top
+@comment node-name, next, previous, up
+@chapter Security Tools
+
+Two Security Tools are available with GNU Classpath:
+@command{jarsigner} and @command{keytool}.
+
+To avoid conflicts with other implementations, the jarsigner
+executable is called @command{gjarsigner} and the keytool executable is
+called @command{gkeytool}.
+
+@menu
+* jarsigner Tool::             Sign and verify .JAR files
+* keytool Tool::               Manage private keys and public certificates
+@end menu
+
+If while using these tools you think you found a bug, then please report it at @uref{http://www.gnu.org/software/classpath/bugs.html,classpath-bugs}.
+
+@comment ----------------------------------------------------------------------
+
+@node jarsigner Tool, keytool Tool, Security Tools, Security Tools
+@comment node-name, next, previous, up
+@section The @code{jarsigner} Tool
+@c man title gjarsigner Java ARchive (JAR) file signing and verification tool
+
+The @command{jarsigner} tool is invoked from the command line, in one
+of two forms, as follows:
+
+@example
+@c man begin SYNOPSIS gjarsigner
+jarsigner [@var{OPTION}]@dots{} @var{FILE} @var{ALIAS}
+
+jarsigner @option{-verify} [@var{OPTION}]@dots{} @var{FILE}
+@c man end
+@end example
+
+@c man begin DESCRIPTION gjarsigner
+When the first form is used, the tool signs the designated JAR file. The second form, on the other hand, is used to verify a previously signed JAR file.
+
+@var{FILE} is the .JAR file to process; i.e., to sign if the first syntax form is used, or to verify if the second syntax form is used instead.
+
+@var{ALIAS} must be a known @i{Alias} of a @i{Key Entry} in the designated @i{Key Store}. The private key material associated with this @i{Alias} is then used for signing the designated .JAR file.
+@c man end
+
+@menu
+* Common jarsigner Options::   Options used when signing or verifying a file
+* Signing Options::            Options only used when signing a .JAR file
+* Verification Options::       Options only used when verifying a .JAR file
+@end menu
+
+@comment ----------------------------------------------------------------------
+
+@node Common jarsigner Options, Signing Options, jarsigner Tool, jarsigner Tool
+@comment node-name, next, previous, up
+@c man begin OPTIONS gjarsigner
+@subsection Common options
+
+The following options may be used when the tool is used for either signing, or verifying, a .JAR file.
+
+@table @gcctabopt
+@item -verbose
+Use this option to force the tool to generate more verbose messages, during its processing.
+
+@item -internalsf
+When present, the tool will include --which otherwise it does not-- the @code{.SF} file in the @code{.DSA} generated file.
+
+@item -sectionsonly
+When present, the tool will include in the @code{.SF} generated file --which otherwise it does not-- a header containing a hash of the whole manifest file.  When that header is included, the tool can quickly check, during verification, if the hash (in the header) matches or not the manifest file.
+
+@item -provider PROVIDER_CLASS_NAME
+A fully qualified class name of a @i{Security Provider} to add to the current list of @i{Security Providers} already installed in the JVM in-use. If a provider class is specified with this option, and was successfully added to the runtime --i.e.@: it was not already installed-- then the tool will attempt to remove this @i{Security Provider} before exiting.
+
+@item -help
+Prints a help text similar to this one.
+
+@end table
+@c man end
+
+@comment ----------------------------------------------------------------------
+
+@node Signing Options, Verification Options, Common jarsigner Options, jarsigner Tool
+@comment node-name, next, previous, up
+@c man begin OPTIONS gjarsigner
+@subsection Signing options
+
+The following options may be specified when using the tool for signing purposes.
+
+@table @gcctabopt
+@item -keystore @var{URL}
+Use this option to specify the location of the key store to use. The default value is a file URL referencing the file named @file{.keystore} located in the path returned by the call to @code{java.lang.System#getProperty(String)} using @code{user.home} as argument.
+
+If a URL was specified, but was found to be malformed --e.g.@: missing protocol element-- the tool will attempt to use the URL value as a file-name (with absolute or relative path-name) of a key store --as if the protocol was @code{file:}.
+
+@item -storetype @var{STORE_TYPE}
+Use this option to specify the type of the key store to use. The default value, if this option is omitted, is that of the property @code{keystore.type} in the security properties file, which is obtained by invoking the static method call @code{getDefaultType()} in @code{java.security.KeyStore}.
+
+@item -storepass @var{PASSWORD}
+Use this option to specify the password which will be used to unlock the key store. If this option is missing, the User will be prompted to provide a password.
+
+@item -keypass @var{PASSWORD}
+Use this option to specify the password which the tool will use to unlock the @i{Key Entry} associated with the designated @i{Alias}.
+
+If this option is omitted, the tool will first attempt to unlock the @i{Key Entry} using the same password protecting the key store. If this fails, you will then be prompted to provide a password.
+
+@item -sigfile @var{NAME}
+Use this option to designate a literal that will be used to construct file names for both the @code{.SF} and @code{.DSA} signature files. These files  will be generated, by the tool, and placed in the @file{META-INF} directory of the signed JAR@.  Permissible characters for @var{NAME} must be in the range "a-zA-Z0-9_-".  All characters will be converted to upper-case ones.
+
+If this option is missing, the first eight characters of the @var{ALIAS} argument will be used. When this is the case, any character in @var{ALIAS} that is outside the permissible range of characters will be replaced by an underscore.
+
+@item -signedjar @var{FILE}
+Use this option to specify the file name of the signed JAR@. If this option is omitted, then the signed JAR will be named the same as @var{FILE}; i.e., the input JAR file will be replaced with the signed copy.
+
+@end table
+@c man end
+
+@comment ----------------------------------------------------------------------
+
+@node Verification Options, , Signing Options, jarsigner Tool
+@comment node-name, next, previous, up
+@c man begin OPTIONS gjarsigner
+@subsection Verification options
+
+The following options may be specified when using the tool for verification purposes.
+
+@table @gcctabopt
+@item -verify
+Use this option to indicate that the tool is to be used for verification purposes.
+
+@item -certs
+This option is used in conjunction with the @option{-verbose} option. When present, along with the @option{-verbose} option, the tool will print more detailed information about the certificates of the signer(s) being processed.
+
+@end table
+@c man end
+
+@comment ----------------------------------------------------------------------
+
+@node keytool Tool, , jarsigner Tool, Security Tools
+@comment node-name, next, previous, up
+@section The @code{keytool} Tool
+@c man title gkeytool Manage private keys and public certificates
+
+@ignore
+@c man begin SYNOPSIS gkeytool
+keytool [@var{COMMAND}] @dots{}
+@c man end
+@end ignore
+
+@c man begin DESCRIPTION gkeytool
+Cryptographic credentials, in a Java environment, are usually stored in a @i{Key Store}. The Java SDK specifies a @i{Key Store} as a persistent container of two types of objects: @i{Key Entries} and @i{Trusted Certificates}. The security tool @command{keytool} is a Java-based application for managing those types of objects.
+
+A @i{Key Entry} represents the private key part of a key-pair used in Public-Key Cryptography, and a signed X.509 certificate which authenticates the public key part for a known entity; i.e.@: the owner of the key-pair. The X.509 certificate itself contains the public key part of the key-pair.
+
+A @i{Trusted Certificate} is a signed X.509 certificate issued by a trusted entity. The @i{Trust} in this context is relative to the User of the @command{keytool}. In other words, the existence of a @i{Trusted Certificate} in the @i{Key Store} processed by a @command{keytool} command implies that the User trusts the @i{Issuer} of that @i{Trusted Certificate} to also sign, and hence authenticates, other @i{Subjects} the tool may process.
+
+@i{Trusted Certificates} are important because they allow the tool to mechanically construct @i{Chains of Trust} starting from one of the @i{Trusted Certificates} in a @i{Key Store} and ending with a certificate whose @i{Issuer} is potentially unknown. A valid chain is an ordered list, starting with a @i{Trusted Certificate} (also called the @i{anchor}), ending with the target certificate, and satisfying the condition that the @i{Subject} of certificate @code{#i} is the @i{Issuer} of certificate @code{#i + 1}.
+
+The @command{keytool} is invoked from the command line as follows:
+
+@smallexample
+keytool [COMMAND] ...
+@end smallexample
+
+Multiple @var{COMMAND}s may be specified at once, each complete with its own options. @command{keytool} will parse all the arguments, before processing, and executing, each @code{COMMAND}. If an exception occurs while executing one @var{COMMAND} @command{keytool} will abort. Note however that because the implementation of the tool uses code to parse command line options that also supports GNU-style options, you have to separate each command group with a double-hyphen; e.g
+
+@smallexample
+keytool -list -- -printcert -alias mykey
+@end smallexample
+@c man end
+
+Here is a summary of the commands supported by the tool:
+
+@c man begin OPTIONS gkeytool
+@enumerate
+@item Add/Update commands
+@table @gcctabopt
+@item -genkey [@var{OPTION}]@dots{}
+Generate a new @i{Key Entry}, eventually creating a new key store.
+
+@item -import [@var{OPTION}]@dots{}
+Add, to a key store, @i{Key Entries} (private keys and certificate chains authenticating the public keys) and @i{Trusted Certificates} (3rd party certificates which can be used as @i{Trust Anchors} when building chains-of-trust).
+
+@item -selfcert [@var{OPTION}]@dots{}
+Generate a new self-signed @i{Trusted Certificate}.
+
+@item -cacert [@var{OPTION}]@dots{}
+Import a CA @i{Trusted Certificate}.
+
+@item -identitydb [@var{OPTION}]@dots{}
+@b{NOT IMPLEMENTED YET}.@*
+Import a JDK 1.1 style Identity Database.
+@end table
+
+@item Export commands
+@table @gcctabopt
+@item -certreq [@var{OPTION}]@dots{}
+Issue a @i{Certificate Signing Request} (CSR) which can be then sent to a @i{Certification Authority} (CA) to issue a certificate signed (by the CA) and authenticating the @i{Subject} of the request.
+
+@item -export [@var{OPTION}]@dots{}
+Export a certificate from a key store.
+@end table
+
+@item  Display commands
+@table @gcctabopt
+@item -list [@var{OPTION}]@dots{}
+Print one or all certificates in a key store to @code{STDOUT}.
+
+@item -printcert [@var{OPTION}]@dots{}
+Print a human-readable form of a certificate, in a designated file, to @code{STDOUT}.
+@end table
+
+@item Management commands
+@table @gcctabopt
+@item -keyclone [@var{OPTION}]@dots{}
+Clone a @i{Key Entry} in a key store.
+
+@item -storepasswd [@var{OPTION}]@dots{}
+Change the password protecting a key store.
+
+@item -keypasswd [@var{OPTION}]@dots{}
+Change the password protecting a @i{Key Entry} in a key store.
+
+@item -delete [@var{OPTION}]@dots{}
+Delete a @i{Key Entry} or a @i{Trusted Certificate} from a key store.
+@end table
+@end enumerate
+@c man end
+
+@menu
+* Getting Help::               How to get help with keytool commands
+* Common keytool Options::     Options used in more than one command
+* Distinguished Names::        X.500 Distinguished Names used in certificates
+* Add/Update Commands::        Commands for adding data to a Key Store
+* Export Commands::            Commands for exporting data from a Key Store
+* Display Commands::           Commands for displaying data in a Key Store
+* Management Commands::        Commands for managing a Key Store
+@end menu
+
+@comment ----------------------------------------------------------------------
+
+@node Getting Help, Common keytool Options, keytool Tool, keytool Tool
+@comment node-name, next, previous, up
+@subsection Getting help
+
+To get a general help text about the tool, use the @code{-help} option; e.g.
+
+@example
+@code{keytool -help}
+@end example
+
+To get more specific help text about one of the tool's command use the @code{-help} option for that command; e.g.
+
+@example
+@code{keytool -genkey -help}
+@end example
+
+In both instances, the tool will print a help text and then will exit the running JVM.
+
+It is worth noting here that the help messages printed by the tool are I18N-ready. This means that if/when the contents of the tool's @i{Message Bundle} properties file are available in languages other than English, you may see those messages in that language.
+
+@comment ----------------------------------------------------------------------
+
+@node Common keytool Options, Distinguished Names, Getting Help, keytool Tool
+@comment node-name, next, previous, up
+@c man begin OPTIONS gkeytool
+@subsection Common options
+
+The following @option{OPTION}s are used in more than one @command{COMMAND}. They are described here to reduce redundancy.
+
+@table @gcctabopt
+@anchor{alias}
+@item -alias @var{Alias}
+Every entry, be it a @i{Key Entry} or a @i{Trusted Certificate}, in a key store is uniquely identified by a user-defined @var{Alias} string. Use this option to specify the @var{Alias} to use when referring to an entry in the key store. Unless specified otherwise, a default value of @code{mykey} shall be used when this option is omitted from the command line.
+
+@anchor{keyalg}
+@item -keyalg @var{ALGORITHM}
+Use this option to specify the canonical name of the key-pair generation algorithm. The default value for this option is @code{DSS} (a synonym for the Digital Signature Algorithm also known as DSA).
+
+@anchor{keysize}
+@item -keysize @var{SIZE}
+Use this option to specify the number of bits of the shared modulus (for both the public and private keys) to use when generating new keys. A default value of @code{1024} will be used if this option is omitted from the command line.
+
+@anchor{validity}
+@item -validity @var{DAY_COUNT}
+Use this option to specify the number of days a newly generated certificate will be valid for. The default value is @code{90} (days) if this option is omitted from the command line.
+
+@anchor{storetype}
+@item -storetype @var{STORE_TYPE}
+Use this option to specify the type of the key store to use. The default value, if this option is omitted, is that of the property @code{keystore.type} in the security properties file, which is obtained by invoking the static method call @code{getDefaultType()} in @code{java.security.KeyStore}.
+
+@anchor{storepass}
+@item -storepass @var{PASSWORD}
+Use this option to specify the password protecting the key store. If this option is omitted from the command line, you will be prompted to provide a password.
+
+@anchor{keystore}
+@item -keystore @var{URL}
+Use this option to specify the location of the key store to use. The default value is a file URL referencing the file named @file{.keystore} located in the path returned by the call to @code{java.lang.System#getProperty(String)} using @code{user.home} as argument.
+
+If a URL was specified, but was found to be malformed --e.g.@: missing protocol element-- the tool will attempt to use the URL value as a file-name (with absolute or relative path-name) of a key store --as if the protocol was @code{file:}.
+
+@anchor{provider}
+@item -provider @var{PROVIDER_CLASS_NAME}
+A fully qualified class name of a @i{Security Provider} to add to the current list of @i{Security Providers} already installed in the JVM in-use. If a provider class is specified with this option, and was successfully added to the runtime --i.e.@: it was not already installed-- then the tool will attempt to removed this @i{Security Provider} before exiting.
+
+@anchor{file}
+@item -file @var{FILE}
+Use this option to designate a file to use with a command. When specified with this option, the value is expected to be the fully qualified path of a file accessible by the File System. Depending on the command, the file may be used as input or as output. When this option is omitted from the command line, @code{STDIN} will be used instead, as the source of input, and @code{STDOUT} will be used instead as the output destination.
+
+@anchor{verbose}
+@item -v
+Unless specified otherwise, use this option to enable more verbose output.
+
+@end table
+@c man end
+
+@comment ----------------------------------------------------------------------
+
+@node Distinguished Names, Add/Update Commands, Common keytool Options, keytool Tool
+@comment node-name, next, previous, up
+@subsection X.500 Distinguished Names
+
+@anchor{dn}
+A @i{Distinguished Name} (or DN) MUST be supplied with some of the @code{COMMAND}s using a @code{-dname} option. The syntax of a valid value for this option MUST follow RFC-2253 specifications. Namely the following components (with their accepted meaning) will be recognized. Note that the component name is case-insensitive:
+
+@ftable @var
+@item CN
+The Common Name; e.g.@: @kbd{host.domain.com}
+@item OU
+The Organizational Unit; e.g.@: @kbd{IT Department}
+@item O
+The Organization Name; e.g.@: @kbd{The Sample Company}
+@item L
+The Locality Name; e.g.@: @kbd{Sydney}
+@item ST
+The State Name; e.g.@: @kbd{New South Wales}
+@item C
+The 2-letter Country identifier; e.g.@: @kbd{AU}
+@end ftable
+
+When specified with a @code{-dname} option, each pair of component/value will be separated from the other with a comma. Each component and value pair MUST be separated by an equal sign. For example, the following is a valid DN value:@*
+
+@format
+CN=host.domain.com, O=The Sample Company, L=Sydney, ST=NSW, C=AU
+@end format
+@*
+If the @i{Distinguished Name} is required, and no valid default value can be used, the tool will prompt you to enter the information through the console.
+
+@comment ----------------------------------------------------------------------
+
+@node Add/Update Commands, Export Commands, Distinguished Names, keytool Tool
+@comment node-name, next, previous, up
+@c man begin OPTIONS gkeytool
+@subsection Add/Update commands
+@c man end
+
+@menu
+* Command -genkey::            Generate private key and self-signed certificate
+* Command -import::            Import certificates and certificate replies
+* Command -selfcert::          Generate self-signed certificate
+* Command -cacert::            Import a CA Trusted Certificate
+* Command -identitydb::        Import JDK-1 style identities
+@end menu
+
+@comment ----------------------------------------------------------------------
+
+@node Command -genkey, Command -import, Add/Update Commands, Add/Update Commands
+@comment node-name, next, previous, up
+@c man begin OPTIONS gkeytool
+@subsubsection The @option{-genkey} command
+
+Use this command to generate a new key-pair (both private and public keys), and save these credentials in the key store as a @i{Key Entry}, associated with the designated (if was specified with the @option{-alias} option) or default (if the @option{-alias} option is omitted) @i{Alias}.
+
+The private key material will be protected with a user-defined password (see @option{-keypass} option). The public key on the other hand will be part of a self-signed X.509 certificate, which will form a 1-element chain and will be saved in the key store.
+
+@table @gcctabopt
+@item -alias @var{ALIAS}
+For more details @pxref{alias,, ALIAS}.
+
+@item -keyalg @var{ALGORITHM}
+For more details @pxref{keyalg,, ALGORITHM}.
+
+@item -keysize @var{KEY_SIZE}
+For more details @pxref{keysize,, KEY_SIZE}.
+
+@item -sigalg @var{ALGORITHM}
+The canonical name of the digital signature algorithm to use for signing certificates. If this option is omitted, a default value will be chosen based on the type of the key-pair; i.e., the algorithm that ends up being used by the -keyalg option. If the key-pair generation algorithm is @code{DSA}, the value for the signature algorithm will be @code{SHA1withDSA}. If on the other hand the key-pair generation algorithm is @code{RSA}, then the tool will use @code{MD5withRSA} as the signature algorithm.
+
+@item -dname @var{NAME}
+This a mandatory value for the command. If no value is specified --i.e.@: the @option{-dname} option is omitted-- the tool will prompt you to enter a @i{Distinguished Name} to use as both the @i{Owner} and @i{Issuer} of the generated self-signed certificate.
+
+For more details @pxref{dn,, X.500 DISTINGUISHED NAME}.
+
+@item -keypass @var{PASSWORD}
+Use this option to specify the password which the tool will use to protect the newly created @i{Key Entry}.
+
+If this option is omitted, you will be prompted to provide a password.
+
+@item -validity @var{DAY_COUNT}
+For more details @pxref{validity,, DAY_COUNT}.
+
+@item -storetype @var{STORE_TYPE}
+For more details @pxref{storetype,, STORE_TYPE}.
+
+@item -keystore @var{URL}
+For more details @pxref{keystore,, URL}.
+
+@item -storepass @var{PASSWORD}
+For more details @pxref{storepass,, PASSWORD}.
+
+@item -provider @var{PROVIDER_CLASS_NAME}
+For more details @pxref{provider,, PROVIDER_CLASS_NAME}.
+
+@item -v
+For more details @pxref{verbose}.
+
+@end table
+@c man end
+
+@comment ----------------------------------------------------------------------
+
+@node Command -import, Command -selfcert, Command -genkey, Add/Update Commands
+@comment node-name, next, previous, up
+@c man begin OPTIONS gkeytool
+@subsubsection The @option{-import} command
+
+Use this command to read an X.509 certificate, or a PKCS#7 @i{Certificate Reply} from a designated input source and incorporate the certificates into the key store.
+
+If the @i{Alias} does not already exist in the key store, the tool treats the certificate read from the input source as a new @i{Trusted Certificate}. It then attempts to discover a chain-of-trust, starting from that certificate and ending at another @i{Trusted Certificate}, already stored in the key store. If the @option{-trustcacerts} option is present, an additional key store, of type @code{JKS} named @file{cacerts}, and assumed to be present in @file{$@{JAVA_HOME@}/lib/security} will also be consulted if found --@code{$@{JAVA_HOME@}} refers to the location of an installed @i{Java Runtime Environment} (JRE). If no chain-of-trust can be established, and unless the @code{-noprompt} option has been specified, the certificate is printed to @code{STDOUT} and the user is prompted for a confirmation.
+
+If @i{Alias} exists in the key store, the tool will treat the certificate(s) read from the input source as a @i{Certificate Reply}, which can be a chain of certificates, that eventually would replace the chain of certificates associated with the @i{Key Entry} of that @i{Alias}. The substitution of the certificates only occurs if a chain-of-trust can be established between the bottom certificate of the chain read from the input file and the @i{Trusted Certificates} already present in the key store. Again, if the @option{-trustcacerts} option is specified, additional @i{Trusted Certificates} in the same @file{cacerts} key store will be considered. If no chain-of-trust can be established, the operation will abort.
+
+@table @gcctabopt
+@item -alias @var{ALIAS}
+For more details @pxref{alias,, ALIAS}.
+
+@item -file @var{FILE}
+For more details @pxref{file,, FILE}.
+
+@item -keypass @var{PASSWORD}
+Use this option to specify the password which the tool will use to protect the @i{Key Entry} associated with the designated @i{Alias}, when replacing this @i{Alias}' chain of certificates with that found in the certificate reply.
+
+If this option is omitted, and the chain-of-trust for the certificate reply has been established, the tool will first attempt to unlock the @i{Key Entry} using the same password protecting the key store. If this fails, you will then be prompted to provide a password.
+
+@item -noprompt
+Use this option to prevent the tool from prompting the user.
+
+@item -trustcacerts
+Use this option to indicate to the tool that a key store, of type @code{JKS}, named @file{cacerts}, and usually located in @file{lib/security} in an installed @i{Java Runtime Environment} should be considered when trying to establish chain-of-trusts.
+
+@item -storetype @var{STORE_TYPE}
+For more details @pxref{storetype,, STORE_TYPE}.
+
+@item -keystore @var{URL}
+For more details @pxref{keystore,, URL}.
+
+@item -storepass @var{PASSWORD}
+For more details @pxref{storepass,, PASSWORD}.
+
+@item -provider @var{PROVIDER_CLASS_NAME}
+For more details @pxref{provider,, PROVIDER_CLASS_NAME}.
+
+@item -v
+For more details @pxref{verbose}.
+
+@end table
+@c man end
+
+@comment ----------------------------------------------------------------------
+
+@node Command -selfcert, Command -cacert, Command -import, Add/Update Commands
+@comment node-name, next, previous, up
+@c man begin OPTIONS gkeytool
+@subsubsection The @option{-selfcert} command
+
+Use this command to generate a self-signed X.509 version 1 certificate. The newly generated certificate will form a chain of one element which will replace the previous chain associated with the designated @i{Alias} (if @option{-alias} option was specified), or the default @i{Alias} (if @option{-alias} option was omitted).
+
+@table @gcctabopt
+@item -alias @var{ALIAS}
+For more details @pxref{alias,, ALIAS}.
+
+@item -sigalg @var{ALGORITHM}
+The canonical name of the digital signature algorithm to use for signing the certificate. If this option is omitted, a default value will be chosen based on the type of the private key associated with the designated @i{Alias}. If the private key is a @code{DSA} one, the value for the signature algorithm will be @code{SHA1withDSA}. If on the other hand the private key is an @code{RSA} one, then the tool will use @code{MD5withRSA} as the signature algorithm.
+
+@item -dname @var{NAME}
+Use this option to specify the @i{Distinguished Name} of the newly generated self-signed certificate. If this option is omitted, the existing @i{Distinguished Name} of the base certificate in the chain associated with the designated @i{Alias} will be used instead.
+
+For more details @pxref{dn,, X.500 DISTINGUISHED NAME}.
+
+@item -validity @var{DAY_COUNT}
+For more details @pxref{validity,, DAY_COUNT}.
+
+@item -keypass @var{PASSWORD}
+Use this option to specify the password which the tool will use to unlock the @i{Key Entry} associated with the designated @i{Alias}.
+
+If this option is omitted, the tool will first attempt to unlock the @i{Key Entry} using the same password protecting the key store. If this fails, you will then be prompted to provide a password.
+
+@item -storetype @var{STORE_TYPE}
+For more details @pxref{storetype,, STORE_TYPE}.
+
+@item -keystore @var{URL}
+For more details @pxref{keystore,, URL}.
+
+@item -storepass @var{PASSWORD}
+For more details @pxref{storepass,, PASSWORD}.
+
+@item -provider @var{PROVIDER_CLASS_NAME}
+For more details @pxref{provider,, PROVIDER_CLASS_NAME}.
+
+@item -v
+For more details @pxref{verbose}.
+
+@end table
+@c man end
+
+@comment ----------------------------------------------------------------------
+
+@node Command -cacert, Command -identitydb, Command -selfcert, Add/Update Commands
+@comment node-name, next, previous, up
+@c man begin OPTIONS gkeytool
+@subsubsection The @option{-cacert} command
+
+Use this command to import, a CA certificate and add it to the key store as a @i{Trusted Certificate}. The @i{Alias} for this new entry will be constructed from the FILE's base-name after replacing hyphens and dots with underscores.
+
+This command is useful when used in a script that recursively visits a directory of CA certificates to populate a @code{cacerts.gkr} @i{Key Store} of trusted certificates which can then be used commands that specify the @option{-trustcacerts} option.
+
+@table @gcctabopt
+@item -file @var{FILE}
+For more details @pxref{file,, FILE}.
+
+@item -storetype @var{STORE_TYPE}
+For more details @pxref{storetype,, STORE_TYPE}.
+
+@item -keystore @var{URL}
+For more details @pxref{keystore,, URL}.
+
+@item -storepass @var{PASSWORD}
+For more details @pxref{storepass,, PASSWORD}.
+
+@item -provider @var{PROVIDER_CLASS_NAME}
+For more details @pxref{provider,, PROVIDER_CLASS_NAME}.
+
+@item -v
+For more details @pxref{verbose}.
+
+@end table
+@c man end
+
+@comment ----------------------------------------------------------------------
+
+@node Command -identitydb, , Command -cacert, Add/Update Commands
+@comment node-name, next, previous, up
+@c man begin OPTIONS gkeytool
+@subsubsection The @option{-identitydb} command
+
+@b{NOT IMPLEMENTED YET}.
+
+Use this command to import a JDK 1.1 style Identity Database.
+
+@table @gcctabopt
+@item -file @var{FILE}
+For more details @pxref{file,, FILE}.
+
+@item -storetype @var{STORE_TYPE}
+For more details @pxref{storetype,, STORE_TYPE}.
+
+@item -keystore @var{URL}
+For more details @pxref{keystore,, URL}.
+
+@item -storepass @var{PASSWORD}
+For more details @pxref{storepass,, PASSWORD}.
+
+@item -provider @var{PROVIDER_CLASS_NAME}
+For more details @pxref{provider,, PROVIDER_CLASS_NAME}.
+
+@item -v
+For more details @pxref{verbose}.
+
+@end table
+@c man end
+
+@comment ----------------------------------------------------------------------
+
+@node Export Commands, Display Commands, Add/Update Commands, keytool Tool
+@comment node-name, next, previous, up
+@c man begin OPTIONS gkeytool
+@subsection Export commands
+@c man end
+
+@menu
+* Command -certreq::           Generate Certificate Signing Requests (CSR)
+* Command -export::            Export a certificate in a Key Store
+@end menu
+
+@comment ----------------------------------------------------------------------
+
+@node Command -certreq, Command -export, Export Commands, Export Commands
+@comment node-name, next, previous, up
+@c man begin OPTIONS gkeytool
+@subsubsection The @option{-certreq} command
+
+Use this command to generate a PKCS#10 @i{Certificate Signing Request} (CSR) and write it to a designated output destination. The contents of the destination should look something like the following:
+
+@example
+-----BEGIN NEW CERTIFICATE REQUEST-----
+MI...QAwXzEUMBIGA1UEAwwLcnNuQGdudS5vcmcxGzAZBgNVBAoMElUg
+Q2...A0GA1UEBwwGU3lkbmV5MQwwCgYDVQQIDANOU1cxCzAJBgNVBACC
+...
+FC...IVwNVOfQLRX+O5kAhQ/a4RTZme2L8PnpvgRwrf7Eg8D6w==
+-----END NEW CERTIFICATE REQUEST-----
+@end example
+
+@b{IMPORTANT}: Some documentation (e.g.@: RSA examples) claims that the @code{Attributes} field, in the CSR is @code{OPTIONAL} while RFC-2986 implies the opposite. This implementation considers this field, by default, as @code{OPTIONAL}, unless the option @option{-attributes} is specified on the command line.
+
+@table @gcctabopt
+@item -alias @var{ALIAS}
+For more details @pxref{alias,, ALIAS}.
+
+@item -sigalg @var{ALGORITHM}
+The canonical name of the digital signature algorithm to use for signing the certificate. If this option is omitted, a default value will be chosen based on the type of the private key associated with the designated @i{Alias}. If the private key is a @code{DSA} one, the value for the signature algorithm will be @code{SHA1withDSA}. If on the other hand the private key is an @code{RSA} one, then the tool will use @code{MD5withRSA} as the signature algorithm.
+
+@item -file @var{FILE}
+For more details @pxref{file,, FILE}.
+
+@item -keypass @var{PASSWORD}
+Use this option to specify the password which the tool will use to unlock the @i{Key Entry} associated with the designated @i{Alias}.
+
+If this option is omitted, the tool will first attempt to unlock the @i{Key Entry} using the same password protecting the key store. If this fails, you will then be prompted to provide a password.
+
+@item -storetype @var{STORE_TYPE}
+For more details @pxref{storetype,, STORE_TYPE}.
+
+@item -keystore @var{URL}
+For more details @pxref{keystore,, URL}.
+
+@item -storepass @var{PASSWORD}
+For more details @pxref{storepass,, PASSWORD}.
+
+@item -provider @var{PROVIDER_CLASS_NAME}
+For more details @pxref{provider,, PROVIDER_CLASS_NAME}.
+
+@item -v
+For more details @pxref{verbose}.
+
+@item -attributes
+Use this option to force the tool to encode a @code{NULL} DER value in the CSR as the value of the @code{Attributes} field.
+
+@end table
+@c man end
+
+@comment ----------------------------------------------------------------------
+
+@node Command -export, , Command -certreq, Export Commands
+@comment node-name, next, previous, up
+@c man begin OPTIONS gkeytool
+@subsubsection The @option{-export} command
+
+Use this command to export a certificate stored in a key store to a designated output destination, either in binary format (if the @option{-v} option is specified), or in RFC-1421 compliant encoding (if the @option{-rfc} option is specified instead).
+
+@table @gcctabopt
+@item -alias @var{ALIAS}
+For more details @pxref{alias,, ALIAS}.
+
+@item -file @var{FILE}
+For more details @pxref{file,, FILE}.
+
+@item -storetype @var{STORE_TYPE}
+For more details @pxref{storetype,, STORE_TYPE}.
+
+@item -keystore @var{URL}
+For more details @pxref{keystore,, URL}.
+
+@item -storepass @var{PASSWORD}
+For more details @pxref{storepass,, PASSWORD}.
+
+@item -provider @var{PROVIDER_CLASS_NAME}
+For more details @pxref{provider,, PROVIDER_CLASS_NAME}.
+
+@item -rfc
+Use RFC-1421 specifications when encoding the output.
+
+@item -v
+Output the certificate in binary DER encoding. This is the default output format of the command if neither @option{-rfc} nor @code{-v} options were detected on the command line. If both this option and the @option{-rfc} option are detected on the command line, the tool will opt for the RFC-1421 style encoding.
+
+@end table
+@c man end
+
+@comment ----------------------------------------------------------------------
+
+@node Display Commands, Management Commands, Export Commands, keytool Tool
+@comment node-name, next, previous, up
+@c man begin OPTIONS gkeytool
+@subsection Display commands
+@c man end
+
+@menu
+* Command -list::              Display information about one or all Aliases
+* Command -printcert::         Print a certificate or a certificate fingerprint
+@end menu
+
+@comment ----------------------------------------------------------------------
+
+@node Command -list, Command -printcert, Display Commands, Display Commands
+@comment node-name, next, previous, up
+@c man begin OPTIONS gkeytool
+@subsubsection The @option{-list} command
+
+Use this command to print one or all of a key store entries to @code{STDOUT}. Usually this command will only print a @i{fingerprint} of the certificate, unless either the @option{-rfc} or the @option{-v} option is specified.
+
+@table @gcctabopt
+@item -alias @var{ALIAS}
+If this option is omitted, the tool will print ALL the entries found in the key store.
+
+For more details @pxref{alias,, ALIAS}.
+
+@item -storetype @var{STORE_TYPE}
+For more details @pxref{storetype,, STORE_TYPE}.
+
+@item -keystore @var{URL}
+For more details @pxref{keystore,, URL}.
+
+@item -storepass @var{PASSWORD}
+For more details @pxref{storepass,, PASSWORD}.
+
+@item -provider @var{PROVIDER_CLASS_NAME}
+For more details @pxref{provider,, PROVIDER_CLASS_NAME}.
+
+@item -rfc
+Use RFC-1421 specifications when encoding the output.
+
+@item -v
+Output the certificate in human-readable format. If both this option and the @option{-rfc} option are detected on the command line, the tool will opt for the human-readable form and will not abort the command.
+
+@end table
+@c man end
+
+@comment ----------------------------------------------------------------------
+
+@node Command -printcert, , Command -list, Display Commands
+@comment node-name, next, previous, up
+@c man begin OPTIONS gkeytool
+@subsubsection The @option{-printcert} command
+
+Use this command to read a certificate from a designated input source and print it to @code{STDOUT} in a human-readable form.
+
+@table @gcctabopt
+@item -file @var{FILE}
+For more details @pxref{file,, FILE}.
+
+@item -v
+For more details @pxref{verbose}.
+
+@end table
+@c man end
+
+@comment ----------------------------------------------------------------------
+
+@node Management Commands, , Display Commands, keytool Tool
+@comment node-name, next, previous, up
+@c man begin OPTIONS gkeytool
+@subsection Management commands
+@c man end
+
+@menu
+* Command -keyclone::          Clone a Key Entry in a Key Store
+* Command -storepasswd::       Change the password protecting a Key Store
+* Command -keypasswd::         Change the password protecting a Key Entry
+* Command -delete::            Remove an entry in a Key Store
+@end menu
+
+@comment ----------------------------------------------------------------------
+
+@node Command -keyclone, Command -storepasswd, Management Commands, Management Commands
+@comment node-name, next, previous, up
+@c man begin OPTIONS gkeytool
+@subsubsection The @option{-keyclone} command
+
+Use this command to clone an existing @i{Key Entry} and store it under a new (different) @i{Alias} protecting, its private key material with possibly a new password.
+
+@table @gcctabopt
+@item -alias @var{ALIAS}
+For more details @pxref{alias,, ALIAS}.
+
+@item -dest @var{ALIAS}
+Use this option to specify the new @i{Alias} which will be used to identify the cloned copy of the @i{Key Entry}.
+
+@item -keypass @var{PASSWORD}
+Use this option to specify the password which the tool will use to unlock the @i{Key Entry} associated with the designated @i{Alias}.
+
+If this option is omitted, the tool will first attempt to unlock the @i{Key Entry} using the same password protecting the key store. If this fails, you will then be prompted to provide a password.
+
+@item -new @var{PASSWORD}
+Use this option to specify the password protecting the private key material of the newly cloned copy of the @i{Key Entry}.
+
+@item -storetype @var{STORE_TYPE}
+For more details @pxref{storetype,, STORE_TYPE}.
+
+@item -keystore @var{URL}
+For more details @pxref{keystore,, URL}.
+
+@item -storepass @var{PASSWORD}
+For more details @pxref{storepass,, PASSWORD}.
+
+@item -provider @var{PROVIDER_CLASS_NAME}
+For more details @pxref{provider,, PROVIDER_CLASS_NAME}.
+
+@item -v
+For more details @pxref{verbose}.
+
+@end table
+@c man end
+
+@comment ----------------------------------------------------------------------
+
+@node Command -storepasswd, Command -keypasswd, Command -keyclone, Management Commands
+@comment node-name, next, previous, up
+@c man begin OPTIONS gkeytool
+@subsubsection The @option{-storepasswd} command
+
+Use this command to change the password protecting a key store.
+
+@table @gcctabopt
+@item -new @var{PASSWORD}
+The new, and different, password which will be used to protect the designated key store.
+
+@item -storetype @var{STORE_TYPE}
+For more details @pxref{storetype,, STORE_TYPE}.
+
+@item -keystore @var{URL}
+For more details @pxref{keystore,, URL}.
+
+@item -storepass @var{PASSWORD}
+For more details @pxref{storepass,, PASSWORD}.
+
+@item -provider @var{PROVIDER_CLASS_NAME}
+For more details @pxref{provider,, PROVIDER_CLASS_NAME}.
+
+@item -v
+For more details @pxref{verbose}.
+
+@end table
+@c man end
+
+@comment ----------------------------------------------------------------------
+
+@node Command -keypasswd, Command -delete, Command -storepasswd, Management Commands
+@comment node-name, next, previous, up
+@c man begin OPTIONS gkeytool
+@subsubsection The @option{-keypasswd} command
+
+Use this command to change the password protecting the private key material of a designated @i{Key Entry}.
+
+@table @gcctabopt
+@item -alias @var{ALIAS}
+For more details @pxref{alias,, ALIAS}.
+
+Use this option to specify the password which the tool will use to unlock the @i{Key Entry} associated with the designated @i{Alias}.
+
+If this option is omitted, the tool will first attempt to unlock the @i{Key Entry} using the same password protecting the key store. If this fails, you will then be prompted to provide a password.
+
+@item -new @var{PASSWORD}
+The new, and different, password which will be used to protect the private key material of the designated @i{Key Entry}.
+
+@item -storetype @var{STORE_TYPE}
+For more details @pxref{storetype,, STORE_TYPE}.
+
+@item -keystore @var{URL}
+For more details @pxref{keystore,, URL}.
+
+@item -storepass @var{PASSWORD}
+For more details @pxref{storepass,, PASSWORD}.
+
+@item -provider @var{PROVIDER_CLASS_NAME}
+For more details @pxref{provider,, PROVIDER_CLASS_NAME}.
+
+@item -v
+For more details @pxref{verbose}.
+
+@end table
+@c man end
+
+@comment ----------------------------------------------------------------------
+
+@node Command -delete, , Command -keypasswd, Management Commands
+@comment node-name, next, previous, up
+@c man begin OPTIONS gkeytool
+@subsubsection The @option{-delete} command
+
+Use this command to delete a designated key store entry.
+
+@table @gcctabopt
+@item -alias @var{ALIAS}
+For more details @pxref{alias,, ALIAS}.
+
+@item -storetype @var{STORE_TYPE}
+For more details @pxref{storetype,, STORE_TYPE}.
+
+@item -keystore @var{URL}
+For more details @pxref{keystore,, URL}.
+
+@item -storepass @var{PASSWORD}
+For more details @pxref{storepass,, PASSWORD}.
+
+@item -provider @var{PROVIDER_CLASS_NAME}
+For more details @pxref{provider,, PROVIDER_CLASS_NAME}.
+
+@item -v
+For more details @pxref{verbose}.
+
+@end table
+@c man end
+
+@comment ----------------------------------------------------------------------
+
+@node Other Tools, I18N Issues, Security Tools, Top
+@comment node-name, next, previous, up
+@chapter Other Tools
+
+This is a list of currently undocumented classpath tools: @b{jar},
+@b{javah}, @b{gcjh}, @b{native2ascii}, @b{orbd}, @b{serialver}, @b{rmid}, @b{rmiregistry}
+and @b{tnameserv}.
+
+@menu
+* jar Tool::                   Archive tool for Java archives
+* javah Tool::                 A java header compiler
+* gcjh Tool::                  A java header compiler (old version)
+* native2ascii Tool::          An encoding converter
+* orbd Tool::                  An object request broker daemon
+* serialver Tool::             A serial version command
+* rmid Tool::                  RMI activation daemon
+* rmiregistry Tool::           Remote object registry
+* tnameserv Tool::             Naming service
+* gjdoc Tool::                 A documentation generator
+@end menu
+
+@comment ----------------------------------------------------------------------
+
+@node jar Tool, javah Tool, , Other Tools
+@comment node-name, next, previous, up
+@section The @command{jar} Tool
+@c man title gjar - Archive tool for Java archives
+
+@c man begin DESCRIPTION gjar
+
+@command{gjar} is an implementation of Sun's jar utility that comes with
+the JDK.
+
+If any file is a directory then it is processed recursively.  The
+manifest file name and the archive file name needs to be specified in
+the same order the @option{-m} and @option{-f} flags are specified.
+
+@c man end
+
+@ignore
+@c man begin SYNOPSIS gjar
+gjar @option{-ctxui} [@var{OPTIONS}] @var{jar-file} [@option{-C} @var{DIR} @var{FILE}] @var{FILE}@dots{}
+@c man end
+@end ignore
+
+@c man begin OPTIONS gjar
+
+Operation mode:
+
+@table @gcctabopt
+@item -c
+Create new archive.
+
+@item -t
+List table of contents for archive.
+
+@item -x
+Extract named (or all) files from archive.
+
+@item -u
+Update existing archive.
+
+@item -i @var{FILE}
+Compute archive index.
+@end table
+
+Operation modifiers:
+
+@table @gcctabopt
+@item -f @var{FILE}
+Specify archive file name.
+
+@item -0
+Store only; use no ZIP compression.
+
+@item -v
+Generate verbose output on standard output.
+
+@item -M
+Do not create a manifest file for the entries.
+
+@item -m @var{manifest}
+Include manifest information from specified @var{manifest} file.
+@end table
+
+File name selection:
+
+@table @gcctabopt
+@item -C @var{DIR} @var{FILE}
+Change to the @var{DIR} and include the following @var{FILE}.
+
+@item -@@
+Read the names of the files to add to the archive from stdin.  This
+option is supported only in combination with @option{-c} or @option{-u}.
+Non standard option added in the GCC version.
+@end table
+
+Standard options:
+
+@table @gcctabopt
+@item -help
+Print help text, then exit.
+@item -version
+Print version number, then exit.
+@item -J@var{OPTION}
+Pass argument to the Java runtime.
+@end table
+
+@c man end
+
+@c man begin SEEALSO gjar
+java(1), @dots{}
+@c man end
+
+@comment ----------------------------------------------------------------------
+
+@node javah Tool, gcjh Tool, jar Tool, Other Tools
+@comment node-name, next, previous, up
+@section The @command{javah} Tool
+@c man title gjavah - generate header files from Java class files
+
+@c man begin DESCRIPTION gjavah
+
+The @command{gjavah} program is used to generate header files from class
+files.  It can generate both CNI and JNI header files, as well as stub
+implementation files which can be used as a basis for implementing the
+required native methods.
+
+@c man end
+
+@ignore
+@c man begin SYNOPSIS gjavah
+gjavah @dots{}
+@c man end
+@end ignore
+
+@c man begin OPTIONS gjavah
+
+@table @gcctabopt
+@item -d @var{DIR}
+Set output directory.
+
+@item -o @var{FILE}
+Set output file (only one of @option{-d} or @option{-o} may be used).
+
+@item -cmdfile @var{FILE}
+Read command file.
+
+@item -all @var{DIR}
+Operate on all class files under directory @var{DIR}.
+
+@item -stubs
+Emit stub implementation.
+
+@item -jni
+Emit JNI stubs or header (default).
+
+@item -cni
+Emit CNI stubs or header (default JNI).
+
+@item -verbose
+Set verbose mode.
+
+@item -force
+Output files should always be written.
+@end table
+
+Class path options:
+@table @gcctabopt
+@item -classpath @var{PATH}
+Set the class path.
+
+@item -I@var{DIR}
+Add directory to class path.
+
+@item -bootclasspath @var{PATH}
+Set the boot class path.
+
+@item -extdirs @var{PATH}
+Set the extension directory path.
+@end table
+
+Standard options:
+@table @gcctabopt
+@item -help
+Print help text, then exit.
+@item -version
+Print version number, then exit.
+@item -J@var{OPTION}
+Pass argument to the Java runtime.
+@end table
+@c man end
+
+@c man begin SEEALSO gjavah
+javac(1), @dots{}
+@c man end
+
+@comment ----------------------------------------------------------------------
+
+@node gcjh Tool, native2ascii Tool, javah Tool, Other Tools
+@comment node-name, next, previous, up
+@section The @command{gcjh} Tool
+@c man title gcjh - generate header files from Java class files
+
+@c man begin DESCRIPTION gcjh
+
+The @code{gcjh} program is used to generate header files from class
+files.  It can generate both CNI and JNI header files, as well as stub
+implementation files which can be used as a basis for implementing the
+required native methods.  It is similar to @code{javah} but has
+slightly different command line options, and defaults to CNI.
+
+@c man end
+
+@ignore
+@c man begin SYNOPSIS gcjh
+gcjh [@var{OPTIONS}]@dots{} @var{CLASS}@dots{}
+@c man end
+@end ignore
+
+@c man begin OPTIONS gcjh
+
+See @code{javah} for a full description; this page only lists the
+additional options provided by @code{gcjh}.
+
+CNI text options
+@table @gcctabopt
+@item -add @var{text}
+Insert @var{text} into class body.
+@item -append @var{text}
+Append @var{text} after class declaration.
+@item -friend @var{text}
+Insert @var{text} as a @code{friend} declaration.
+@item -prepend @var{text}
+Insert @var{text} before start of class.
+@end table
+
+Compatibility options (unused)
+@table @gcctabopt
+@item -td @var{DIR}
+@itemx -M
+@itemx -MM
+@itemx -MD
+@itemx -MMD
+Unused compatibility option.
+@end table
+
+
+Standard options:
+@table @gcctabopt
+@item -help
+Print help text, then exit.
+@item -version
+Print version number, then exit.
+@item -J@var{OPTION}
+Pass argument to the Java runtime.
+@end table
+@c man end
+
+@c man begin SEEALSO gcjh
+javac(1), javah(1), @dots{}
+@c man end
+
+@comment ----------------------------------------------------------------------
+
+@node native2ascii Tool, orbd Tool, gcjh Tool, Other Tools
+@comment node-name, next, previous, up
+@section The @command{native2ascii} Tool
+@c man title gnative2ascii - An encoding converter
+
+@c man begin DESCRIPTION gnative2ascii
+
+To be written @dots{}
+
+@c man end
+
+@ignore
+@c man begin SYNOPSIS gnative2ascii
+gnative2ascii [@var{OPTIONS}]@dots{} [@var{INPUTFILE} [@var{OUTPUTFILE}]]
+@c man end
+@end ignore
+
+@c man begin OPTIONS gnative2ascii
+
+@table @gcctabopt
+@item -encoding @var{NAME}
+Set the encoding to use.
+
+@item -reversed
+Convert from encoding to native.
+@end table
+
+Standard options:
+@table @gcctabopt
+@item -help
+Print help text, then exit.
+@item -version
+Print version number, then exit.
+@item -J@var{OPTION}
+Pass argument to the Java runtime.
+@end table
+
+@c man end
+
+@c man begin SEEALSO gnative2ascii
+javac(1), @dots{}
+@c man end
+
+@comment ----------------------------------------------------------------------
+
+@node orbd Tool, serialver Tool, native2ascii Tool, Other Tools
+@comment node-name, next, previous, up
+@section The @command{orbd} object request broker daemon
+@c man title gorbd - An object request broker daemon
+
+@c man begin DESCRIPTION gorbd
+
+To be written @dots{}
+
+@c man end
+
+@ignore
+@c man begin SYNOPSIS gorbd
+gorbd @dots{}
+@c man end
+@end ignore
+
+@c man begin OPTIONS gorbd
+
+@table @gcctabopt
+@item -ORBInitialPort @var{PORT}
+Port on which persistent naming service is to be started.
+
+@item -ior @var{FILE}
+File in which to store persistent naming service's IOR reference
+
+@item -directory @var{DIR}
+Directory in which to store persistent data.
+
+@item -restart
+Restart persistent naming service, clearing persistent naming
+database.
+@end table
+
+Standard options:
+@table @gcctabopt
+@item -help
+Print help text, then exit.
+@item -version
+Print version number, then exit.
+@item -J@var{OPTION}
+Pass argument to the Java runtime.
+@end table
+
+@c man end
+
+@c man begin SEEALSO gorbd
+java(1), @dots{}
+@c man end
+
+@comment ----------------------------------------------------------------------
+
+@node serialver Tool, rmid Tool, orbd Tool, Other Tools
+@comment node-name, next, previous, up
+@section The @command{serialver} version command
+@c man title gserialver version command
+
+@c man begin DESCRIPTION gserialver
+
+Print the serialVersionUID of the specified classes.
+
+@c man end
+
+@ignore
+@c man begin SYNOPSIS gserialver
+gserialver [@var{OPTIONS}]@dots{} @var{CLASS}@dots{}
+@c man end
+@end ignore
+
+@c man begin OPTIONS gserialver
+
+@table @gcctabopt
+@item -classpath @var{PATH}
+Class path to use to find classes.
+@end table
+
+Standard options:
+@table @gcctabopt
+@item -help
+Print help text, then exit.
+@item -version
+Print version number, then exit.
+@item -J@var{OPTION}
+Pass argument to the Java runtime.
+@end table
+
+@c man end
+
+@c man begin SEEALSO gserialver
+javac(1), @dots{}
+@c man end
+
+@comment ----------------------------------------------------------------------
+
+@node rmid Tool, rmiregistry Tool, serialver Tool, Other Tools
+@comment node-name, next, previous, up
+@section The @command{rmid} RMI activation system daemon
+@c man title grmid - RMI activation system daemon
+
+@c man begin DESCRIPTION grmid
+
+@command{rmiregistry} starts a remote object registry on the current
+host.  If no port number is specified, then port 1099 is used.
+
+@c man end
+
+@ignore
+@c man begin SYNOPSIS grmid
+grmid [@var{OPTIONS}]@dots{}
+@c man end
+@end ignore
+
+@c man begin OPTIONS grmid
+
+Activation process control:
+@table @gcctabopt
+@item -port @var{PORT}
+Port on which activation system is to be started.
+
+@item -restart
+Restart activation system, clearing persistent naming database, if
+any.
+
+@item -stop
+Stop activation system.
+@end table
+
+Persistence:
+@table @gcctabopt
+@item -persistent
+Make activation system persistent.
+
+@item -directory @var{DIR}
+Directory in which to store persistent data.
+@end table
+
+Debugging:
+@table @gcctabopt
+@item -verbose
+Log binding events to standard out.
+@end table
+
+Standard options:
+@table @gcctabopt
+@item -help
+Print help text, then exit.
+@item -version
+Print version number, then exit.
+@item -J@var{OPTION}
+Pass argument to the Java runtime.
+@end table
+
+@c man end
+
+@c man begin SEEALSO grmid
+java(1), @dots{}
+@c man end
+
+@comment ----------------------------------------------------------------------
+
+@node rmiregistry Tool, tnameserv Tool, rmid Tool, Other Tools
+@comment node-name, next, previous, up
+@section The @command{rmiregistry} Tool
+@c man title grmiregistry - Remote object registry
+
+@c man begin DESCRIPTION grmiregistry
+
+@command{grmiregistry} starts a remote object registry on the current
+host.  If no port number is specified, then port 1099 is used.
+
+@c man end
+
+@ignore
+@c man begin SYNOPSIS grmiregistry
+grmiregistry [@var{OPTIONS}]@dots{} @var{PORT}
+@c man end
+@end ignore
+
+@c man begin OPTIONS grmiregistry
+
+Registry process control:
+@table @gcctabopt
+@item -restart
+Restart RMI naming service, clearing persistent naming database, if
+any.
+
+@item -stop
+Stop RMI naming service.
+@end table
+
+Persistence:
+@table @gcctabopt
+@item -persistent
+Make RMI naming service persistent.
+
+@item -directory @var{DIR}
+Directory in which to store persistent data.
+@end table
+
+Debugging:
+@table @gcctabopt
+@item -verbose
+Log binding events to standard out.
+@end table
+
+Standard options:
+@table @gcctabopt
+@item -help
+Print help text, then exit.
+@item -version
+Print version number, then exit.
+@item -J@var{OPTION}
+Pass argument to the Java runtime.
+@end table
+
+@c man end
+
+@c man begin SEEALSO grmiregistry
+java(1), @dots{}
+@c man end
+
+@comment ----------------------------------------------------------------------
+
+@node tnameserv Tool, gjdoc Tool, rmiregistry Tool, Other Tools
+@comment node-name, next, previous, up
+@section The @command{tnameserv} Tool
+@c man title gtnameserv Naming service
+
+@c man begin DESCRIPTION gtnameserv
+
+To be written @dots{}
+
+@c man end
+
+@ignore
+@c man begin SYNOPSIS gtnameserv
+tnameserv [@var{OPTIONS}]
+@c man end
+@end ignore
+
+@c man begin OPTIONS gtnameserv
+
+@table @gcctabopt
+@item -ORBInitialPort @var{PORT}
+Port on which naming service is to be started.
+
+@item -ior @var{FILE}
+File in which to store naming service's IOR reference.
+@end table
+
+Standard options:
+@table @gcctabopt
+@item -help
+Print help text, then exit.
+@item -version
+Print version number, then exit.
+@item -J@var{OPTION}
+Pass argument to the Java runtime.
+@end table
+
+@c man end
+
+@c man begin SEEALSO gtnameserv
+java(1), @dots{}
+@c man end
+
+@comment ----------------------------------------------------------------------
+
+@ignore
+@c man begin SYNOPSIS gjdoc
+gjdoc [@option{-sourcepath }@var{pathlist}]
+      [@option{-all}] [@option{-subpackages }@var{pkg:pkg:@dots{}}] [@option{-exclude }@var{pkglist}]
+      [@option{-encoding }@var{charset}] [@option{-locale }@var{name}] [@option{-source }@var{release}]
+      [@option{-public}] [@option{-protected}] [@option{-package}] [@option{-private}] 
+      [@option{-doctitle }@var{text}] [@option{-header }@var{text}] [@option{-footer }@var{text}] [@option{-bottom }@var{text}]
+      [@option{-link }@var{url}] [@option{-linkoffline }@var{url} @var{path}] [@option{-noqualifier }@var{pkg:pkg:@dots{}}] 
+      [@option{-tagletpath }@var{pathlist}] [@option{-taglet }@var{className}] [@option{-tag }@var{tagspec}]
+      [@option{-use}] [@option{-linksource}] [@option{-splitindex}] [@option{-noindex}] [@option{-notree}] 
+      [@option{-version}] [@option{-author}] [@option{-nosince}] [@option{-addstylesheet }@var{file}]
+      [@option{-d }@var{targetdir}] 
+      [@var{packages}@dots{}] [@var{sourcefiles}@dots{}] [@@@var{cmdfile}]
+
+gjdoc [@option{-sourcepath }@var{pathlist}]
+      [@option{-all}] [@option{-subpackages }@var{pkg:pkg:@dots{}}] [@option{-exclude }@var{pkglist}]
+      [@option{-encoding }@var{charset}] [@option{-locale }@var{name}] [@option{-source }@var{release}]
+      [@option{-public}] [@option{-protected}] [@option{-package}] [@option{-private}] 
+      [@option{-docletpath }@var{pathlist}] [@option{-doclet }@var{className}]
+      [@var{packages}@dots{}] [@var{sourcefiles}@dots{}] [@@@var{cmdfile}]
+      [doclet options]
+
+gjdoc @option{--help}
+
+gjdoc @option{--version}
+
+Only the most useful options are listed here; see below for the
+remainder.
+@c man end
+@end ignore
+@c man begin SEEALSO gjdoc
+Info entry for @file{gjdoc}.
+@c man end
+@c man begin BUGS gjdoc
+Please report bugs to @w{@uref{http://savannah.gnu.org/bugs/?group=classpath}}.
+@c man end
+@c man begin AUTHOR gjdoc
+Julian Scheid
+@c man end
+
+@node gjdoc Tool, , tnameserv Tool, Other Tools
+@chapter Generating HTML Documentation
+@cindex Gjdoc command options
+@cindex command options
+@cindex options, Gjdoc command
+
+@c man begin DESCRIPTION gjdoc
+Gjdoc can be used in two ways: as a stand-alone documentation tool, or
+as a driver for a user-specified Doclet. @xref{Other Doclets}.
+
+In the default mode, Gjdoc will use the Standard Doclet
+@samp{HtmlDoclet} to generate a set of HTML pages.  The canonical
+usage is:
+
+@smallexample
+gjdoc -s src/java/ -all -d api-docs/
+@end smallexample
+
+Here, @samp{src/java/} is the root of your source code class
+hierarchy, @option{-all} means that all valid Java files found under
+this root directory should be processed, and @samp{api-docs/} is the
+directory where the generated documentation should be placed.
+
+To learn more about running Doclets other than the Standard Doclet,
+refer to the manual.  @xref{Invoking a Custom Doclet}.
+
+@menu
+* Invoking the Standard Doclet::   How to generate HTML documentation.
+* Invoking a Custom Doclet::       How to run third-party and other 
+                                   built-in Doclets.
+
+* Option Summary by Type::         Brief list of all options, grouped by type.
+* Gjdoc Option Summary::           List of all options accepted by Gjdoc.
+
+* Source Set Options::      Select the set of source codes to run Gjdoc on.
+* Source Format Options::   Specify the format of the source codes to document.
+
+* Interlinking Options::    Connection your documentation with other projects.
+* Output Control Options::  Specify the target directory and locale, and more.
+* Generation Options::       Select which pieces of information to generate.
+* Decoration Options::      Add or modify some titles, headers and footers or
+                              override/amend static resources like stylesheets.
+* Taglet Options::          Define your own javadoc @@tags
+
+* Virtual Machine Options::
+* Verbosity Options::
+* Doclet Options::
+
+* Other Doclets::                  Generating Other Output Types
+* Gjdoc Concepts::                 Advanced Concepts
+
+@end menu
+
+@c man end
+
+@comment ----------------------------------------------------------------------
+
+@node Invoking the Standard Doclet, Invoking a Custom Doclet, , gjdoc Tool
+@section Invoking the Standard Doclet
+@cindex Gjdoc command options
+@cindex command options
+@cindex options, Gjdoc command
+
+Running the Gjdoc Standard Doclet @samp{HtmlDoclet} is the default
+mode of operation for Gjdoc.  This section lists the command line
+options you can specify in this mode.  It doesn't distinguish between
+general Gjdoc options and options specific to the Standard Doclet.
+
+If you want to learn which options are accepted when Gjdoc is used as
+a doclet driver, @xref{Invoking a Custom Doclet}.
+
+@menu
+* Source Set Options::      Select the set of source codes to run Gjdoc on.
+* Source Format Options::   Specify the format of the source codes to document.
+
+* Output Control Options::  Specify the target directory and locale, and more.
+* Generation Options::       Select which pieces of information to generate.
+* Decoration Options::      Add or modify some titles, headers and footers or
+                              override/amend static resources like stylesheets.
+* Taglet Options::          Define your own javadoc @@tags
+
+* Virtual Machine Options::
+* Doclet Options::
+
+@end menu
+
+@c man begin OPTIONS gjdoc
+
+@node Option Summary by Type, Gjdoc Option Summary, Invoking a Custom Doclet, gjdoc Tool
+@section Option Summary by Type
+
+Here is a summary of all the options of both Gjdoc and the Standard
+Doclet, grouped by type.  Explanations are in the following sections.
+
+@table @emph
+@item Source Set Options
+@xref{Source Set Options,,Options For Specifying the Source Files To Operate on}.
+@gccoptlist{-sourcepath @var{pathlist}  -subpackages @var{pkglist}  -exclude @var{pkglist}}
+
+@item Source Format Options
+@xref{Source Format Options,,Options For Specifying the Source Format}.
+@gccoptlist{-source @var{release}  -encoding @var{encoding}  -breakiterator}
+
+@item Interlinking Options
+@xref{Interlinking Options,,Options For Specifying the Source Files To Operate on}.
+@gccoptlist{-link @var{url}  -linkoffline @var{url} @var{file}  -noqualifier @var{pkg:pkg:...}}
+
+@item Generation Options
+@xref{Generation Options,,Options Controlling What is Included in the Output}.
+@gccoptlist{-author  -licensetext  -use  -version  -splitindex  -noindex
+ -nodeprecated  -nodeprecatedlist  -nohelp  -nonavbar
+ -nosince  -notree  -public  -protected  -package  -private
+ -docfilessubdirs  -excludedocfilessubdir @var{dirname}
+ -linksource}
+
+@item Output Options
+@xref{Generation Options,,Options Controlling the Output}.
+@gccoptlist{-d  -locale @var{name}  -charset @var{charset}  -docencoding @var{charset}
+ -validhtml  -baseurl @var{url}}
+
+@item Decoration Options
+@gccoptlist{-windowtitle @var{text}  -doctitle @var{text}  -title @var{text}  
+ -header @var{text}  -footer @var{text}  -bottom @var{text}
+ -helpfile @var{file}  -stylesheetfile @var{file}  -addstylesheet @var{file}
+ -group @var{groupheading} @var{pkgpattern:pkgpattern:@dots{}}}
+
+@item Taglet Options
+@xref{Taglet Options,,Options For Specifying user-defined Taglets}.
+@gccoptlist{-tagletpath  -taglet @var{classname}  -tag @var{tagspec}}
+
+@item Doclet Options
+@xref{Doclet Options,,Options For Specifying the Doclet to use}.
+@gccoptlist{-docletpath  -doclet @var{classname}}
+
+@item Verbosity Options
+@xref{Verbosity Options,,Options Controlling Gjdoc Behavior}.
+@gccoptlist{-quiet  -verbose}
+
+@item Virtual Machine Options
+@xref{Virtual Machine Options,,Options Controlling Gjdoc Behavior}.
+@gccoptlist{-classpath  -bootclasspath  -J @var{vmopt}}
+
+@end table
+
+@menu
+* Virtual Machine Options::     Controlling the kind of output:
+                        an executable, object files, assembler files,
+                        or preprocessed source.
+@end menu
+
+@node Source Set Options, Source Format Options, Gjdoc Option Summary, gjdoc Tool
+@section Selecting which Source Files to Process
+
+@table @gcctabopt
+@item -s @var{pathlist}
+@item -sourcepath @var{pathlist}
+Look for source files in the specified directory or directories.
+
+@var{pathlist} should be one or more directory paths separated by your
+platform's path separator (usually @samp{:} or @samp{;}).
+
+If this option is not given, @command{gjdoc} will look for source
+files in the current directory.
+
+The directories specified should be root directories in terms of the
+Java package system.  For example, if you want to generate
+documentation for classes in package @samp{foo.bar}, you must specify
+the directory containing the top-level @samp{@file{foo}}
+sub-directory, not the directory @samp{@file{foo/bar/}} in which the
+Java source files reside.
+
+The short-hand alias @option{-s} is specific to @command{gjdoc} and
+not compatible to Sun @command{javadoc}.
+
+@item -all
+@emph{[EXPERIMENTAL]}
+Process all valid Java source files found in the directories listed in
+the source path and their sub-directories.
+
+This is an option specific to @command{gjdoc} and not compatible to
+Sun @command{javadoc}.
+
+@item -subpackages @var{pkg:pkg:@dots{}}
+Process the classes in the given Java packages and all sub-packages,
+recursively.  Note that multiple package names must be separated with
+colons instead of whitespace.
+
+@item -exclude @var{pkg:pkg:@dots{}}
+Do not process classes in the given Java packages and all
+sub-packages, recursively.  This option can be used in conjunction
+with @option{-all} or @option{-subpackages} in order to exclude
+individual packages or package sub-trees from the output.
+
+@item @var{packages}@dots{}
+Process all classes in the given Java packages.
+
+@item @var{sourcefiles}@dots{}
+Process the classes in the given Java source files.
+@end table
+
+@node Source Format Options, Interlinking Options, Source Set Options, gjdoc Tool
+@section Specifying the Format of Input Files
+
+@table @gcctabopt
+@item -source @var{release}
+Assume that the source files are targeted at the given release of the
+Java platform.
+
+@var{release} should be the version number of a Java platform release
+in the format MAJOR.MINOR, for example @samp{1.4}.
+
+This option is currently ignored except that an error is raised if a
+release number other than @samp{1.2}, @samp{1.3} or @samp{1.4} is
+specified.
+
+@item -encoding @var{charset}
+Assume that the source files are encoded using @var{charset}.
+
+Examples for @var{charset} are @samp{US-ASCII}, @samp{ISO-8859-1} or
+@samp{UTF-8}.
+
+The semantics of @var{charset} are identical to those of @samp{java.nio.charset.Charset.forName(String)}.
+
+@item -breakiterator
+Use the locale's java.text.BreakIterator instead of the internal
+first sentence detector.
+
+By default, @command{gjdoc} uses an internal algorithm to determine
+where a sentence ends. When this option is given, it will instead use
+the @samp{java.text.BreakIterator} instance for the locale given with
+@option{-locale} (or the default locale).
+
+This option should be specified when applying @command{gjdoc} to
+source code commented in a non-latin language for which the default
+first sentence detector does not work. For all other cases, the
+default (do not use BreakIterator) produces better results at the time
+of this writing.
+@end table
+
+@node Interlinking Options, Output Control Options, Source Format Options, gjdoc Tool
+@section Interlinking with other Documentation Sets
+
+@table @gcctabopt
+@item -link @var{url}
+
+Create hyperlinks to another documentation set.
+
+By default, @command{gjdoc} will only create hyperlinks to classes in
+the source set.  Use this option to additionally create hyperlinks to
+classes covered by the specified documentation set.
+
+@var{url} should be the root URL of the other documentation set. For
+example, to add hyperlinks to GNU Classpath, specify the following:
+
+@smallexample
+-link http://developer.classpath.org/doc/
+@end smallexample
+
+The @option{-link} option can be specified multiple times.
+
+Note that specifying the @option{-link} option will cause an HTTP
+access every time gjdoc is invoked. You can use @option{-linkoffline}
+instead to avoid this access.
+
+@item -linkoffline @var{url} @var{file}
+
+Create hyperlinks to another documentation set which is also present
+on the local file system.
+
+This option works exactly like @option{-link}, except that it accesses
+the local file system instead of the network for determining which
+classes are covered by the linked documentation set.
+
+When using @option{-linkoffline} the remote documentation set is not
+accessed at all, which can significantly speed up generation time
+depending on your network connection.  The generated hyperlinks to the
+documentation set however refer to the remote set, not to the local
+one, so that you can distribute the documentation without any further
+dependencies.
+
+The @option{-linkoffline} option can be specified multiple times.
+
+@item -noqualifier @var{pkg:pkg:@dots{}}
+
+Do not qualify names of classes in the given packages with their
+package name.
+
+By default, a class name is displayed unqualified only if the class is
+part of the source set or a linked documentation set, and qualified
+with the name of its containing package if it is not. You can use this
+option to force unqualified names for classes even if they are not
+part of the documentation set.
+
+For example, usually a reference to the String class is represented
+fully-qualified as @samp{java.lang.String} (unless you link to the
+appropriate documentation set using @option{-link}) because it isn't
+part of the documentation set.  You can specify @samp{-noqualifier
+java.lang} to render the same references just as @samp{String}.
+
+Note that for all unqualified class names, a tooltip is provided when
+you place your mouse pointer over it in the HTML documentation.
+
+@item -noqualifier @samp{all}
+Omit package name qualifier from all class names.
+
+Specify this option to omit package name qualifiers altogether,
+
+@end table
+
+@node Generation Options, Decoration Options, Output Control Options, gjdoc Tool
+@section Selecting which Information to Generate
+
+@table @gcctabopt
+@item -public
+Only include public members of public classes in the output.  By
+default, protected class members are included as well.
+
+@item -protected
+
+Include public or protected members of public classes in the output.
+This is the default.
+
+@item -package
+
+Include public, protected and package-private members of public and
+package-private classes.
+
+@item -private
+
+Include all classes and class members regardless of their access
+level.
+
+@item -splitindex
+Generate one index page per letter instead of a single, monolithic
+index page.
+
+By default, the index created by the Standard Doclet contains all
+entries on a single page.  This is fine for small documentation sets,
+but for large sets you should specify this option.
+
+@item -nosince
+Ignore @samp{@@since} tags in javadoc comments.
+
+By default, the generated output contains sections listing the version
+of your API since which the package, class or class member in question
+exists when this tag is encountered.  Specify this option to omit this
+information.
+
+@item -notree
+Do not generate any tree pages.
+
+By default, the generated output includes one inheritance tree per
+package, and - if the documentation set consists of multiple packages
+- a page with the full inheritance tree.  Specify this option to omit
+generation of these pages.
+
+@item -noindex
+Do not output the alphabetical index.
+
+By default, gjdoc generates an alphabetical index of all program
+elements in the documentation set (packages, classes, inner classes,
+constructors, methods, and fields).  Specify this option to omit this
+information.
+
+@item -nohelp
+Do not generate the help page.
+
+This option is currently ignored as the Standard Doclet doesn't
+provide a help page.
+
+@item -nodeprecated
+Do not output inline information about deprecated packages, classes or
+class members.
+
+By default, the Standard Doclet adds a highlighted paragraph with
+deprecation information to the description of each deprecated program
+element.  Specify this option to omit this information.
+
+@item -nodeprecatedlist
+Do not output the summary page for deprecated API elements.
+
+By default, the Standard Doclet generates a page listing all
+deprecated API elements along with a deprecation description which
+usually includes the reason for deprecation and possible
+alternatives.  Specify this option to omit this information.
+
+@item -nonavbar
+Do not output the navigation bar, header, and footer.
+
+By default, each output page is equipped with a top navigation bar
+(which may include a user-specified header) and a bottom navigation
+bar (which may include a user-specified footer).  Specify this option
+to omit this decoration.
+
+@item -nocomment
+
+Omit all documentation text from the generated files and output only
+declarations and program element relationships.
+
+This option is here for compatibility with @command{javadoc}.  If you
+plan on extracting information about your project via @command{gjdoc},
+you should consider using a different Doclet for your purposes
+instead, for example XmlDoclet.  You could also use the Doclet API
+directly by implementing a new Doclet.
+
+@item -linksource
+
+Generate a page with syntax-highlighted source code for each class.
+By default, this page is not generated.
+
+The source code can be accessed by clicking on the button labelled
+"Source" in the navigation bar, or by clicking on the name of a
+constructor, field, method, or inner class in the detail section of a
+class documentation page.
+
+@item -use
+
+Generate a page with cross-reference information. By default, this
+page is not generated.
+
+The cross-reference information can be accessed by clicking on the
+button labelled `Use' in the navigation bar.
+
+The `Use' page lists all classes/interfaces in the documentation set
+that extend/implement the class (type) in question; fields of the
+type; methods or constructors accepting a parameter of the type;
+methods returning the type; and methods or constructors throwing the
+type.
+
+@item -author
+Include author information in the output.
+
+When specified, author information as specified using the
+@samp{@@author} tag in javadoc comments is incorporated into the
+output. By default, @samp{@@author} tags are ignored.
+
+@item -version
+Include version information in the output.
+
+When specified, version information as specified using the
+@samp{@@version} tag in javadoc comments is incorporated into the
+output. By default, @samp{@@version} tags are ignored.
+
+@item -licensetext
+
+Assume that the first comment in each source file contains the license
+text, and add license information to the footer of each generated
+class page.
+
+This is an option specific to @command{gjdoc} and not compatible to
+Sun @command{javadoc}.
+
+This option is intended for use with free and open source projects
+where source code is typically prefixed with a boilerplate license
+comment, when there are legal reasons for including the license in the
+documentation.
+
+@item -docfilessubdirs
+
+Recursively copy all files in the @file{doc-files} sub-directory of each
+package directory.
+
+Usually, only the files in the @file{doc-files} sub-directory are copied
+without descending recursively.
+
+@xref{Adding Custom Resources}.
+
+@item -excludedocfilessubdir @var{name}:@var{name}:@dots{}
+
+Do not copy some directories directly under the @file{doc-files}
+sub-directories when descending recursively.
+
+The argument to this option should be a colon-separated list of
+directory names.
+
+This option only makes sense if @option{-docfilessubdirs} is also
+specified.  In this case, any sub-directory located directly beneath a
+@file{doc-files} directory is omitted if listed.
+
+@end table
+
+@node Taglet Options, Virtual Machine Options, Decoration Options, gjdoc Tool
+@section Custom Documentation Tags
+
+@table @gcctabopt
+@item -tagletpath @var{pathlist}
+Search @var{pathlist} when loading subsequent Taglet classes specified
+using @option{-taglet}.
+
+@var{pathlist} should be one or more paths to a directory or jar file,
+separated by your platform's path separator (usually @samp{:} or
+@samp{;}).
+
+@item -taglet @var{classname}
+Register a Taglet.
+
+@var{classname} should be the fully-qualified name of a Java class
+implementing @samp{com.sun.tools.doclets.Taglet}.
+
+The Taglet classes will be loaded from the classpath specified using
+@option{-tagletpath}, from the classpath specified using
+@option{-classpath} and from the default classpath.
+
+See the documentation of @samp{com.sun.tools.doclets.Taglet} for
+further information.
+
+Note that for simple tags, there is also @option{-tag}.
+
+@item -tag @var{tagspec}
+Register a generic Taglet.
+
+The format of @var{tagspec} must be @samp{<tagname>:<flags>:"<taghead>"}.
+
+@var{tagname} is the tag name to match, without the leading @@ sign. 
+
+@var{flags} is one or more of the following characters, where each
+character specifies a source code context in which the tag is to be
+recognized.
+
+@table @gcctabopt
+@item a  
+all contexts
+@item c  
+constructors
+@item f  
+fields
+@item m  
+methods
+@item o  
+overview
+@item p  
+packages
+@item t  
+types (classes, interfaces, exceptions, errors)
+@item X  
+special character which temporarily disables the
+Taglet altogether.
+@end table
+
+@var{taghead} is the string to display in the header of the section
+devoted to the tag in question.
+
+For example, to define a tag matching @samp{@@cvsid} which is to be
+accepted in overview, package and type pages and which is labelled
+with the header @samp{CVS ID}, you would specify:
+
+@smallexample
+-tag cvsid:tpo:"CVS ID"
+@end smallexample
+
+Let's say that a class javadoc comment contains
+
+@smallexample
+@@cvsid $Id: cp-tools.texinfo,v 1.7 2008/08/13 13:32:05 jsumali Exp $
+@end smallexample
+
+Then the HTML output will contain something like
+
+@smallexample
+CVS ID:
+  $Id: cp-tools.texinfo,v 1.7 2008/08/13 13:32:05 jsumali Exp $
+@end smallexample
+@end table
+
+@node Doclet Options, Other Doclets, Verbosity Options, gjdoc Tool
+@section Running Other Doclets
+
+@table @gcctabopt
+
+@item -docletpath @var{pathlist}
+Search @var{pathlist} when loading classes for the Doclet specified
+using @option{-doclet}.
+
+@var{pathlist} should be one or more paths to a directory or jar file,
+separated by your platform's path separator (usually @samp{:} or
+@samp{;}).
+
+@item -doclet @var{className}
+Run the specified doclet instead of the standard HtmlDoclet.
+
+@var{className} should be the fully-qualified name of a class which
+has a public default constructor and contain a method with the
+following signature:
+
+@smallexample
+   import com.sun.javadoc.RootDoc;
+   public static boolean start(RootDoc rootDoc) 
+@end smallexample
+
+The Doclet classes will be loaded from the classpath specified using
+@option{-docletpath}, from the classpath specified using
+@option{-classpath} and from the default classpath.
+
+The @samp{start} method should process the information exposed by the
+Doclet API via @samp{rootDoc} and return @samp{true} on success,
+@samp{false} on failure.
+
+If you are using a third-party doclet, refer to its documentation for
+further instructions.  Note that support for third-party doclets is
+experimental.  Please report any problems you encounter, or provide
+feedback when successfully running third-party applets.
+
+This option can be specified multiple times, in which case all doclets
+are executed with the same information tree exposed via the Doclet API
+for each Doclet run.
+
+@end table
+
+@node Decoration Options, Taglet Options, Generation Options, gjdoc Tool
+@section Adding Information to the Output
+
+@table @gcctabopt
+@item -windowtitle @var{text}
+Use @var{text} as the browser window title prefix.
+
+When specified, the browser window title for each page will be
+prefixed with @var{text} instead of the default string @samp{Generated
+API Documentation}.
+
+@var{text} should be plain text (it should not contain HTML tags).
+
+@item -doctitle @var{text}
+Set the header text of the overview page to @var{text}.
+
+@var{text} should be a short plain text string.
+
+When generating documentation for a single package, specifying this
+option forces generation of the overview page.
+
+@item -header @var{htmltext}
+
+Add @var{htmltext} to the right upper corner of every generated page.
+@var{htmltext} is usually set to the name of the project being
+documented.
+
+@item -footer @var{htmltext}
+
+Add @var{htmltext} to the right bottom corner of every generated page.
+@var{htmltext} is often set to the same value as for @option{-header}.
+
+@item -bottom @var{htmltext}
+
+Add @var{htmltext} to the very bottom of every generated page,
+spanning the whole width of the page.  When specified, @var{htmltext}
+usually consists of a copyright notice and/or links to other project
+pages.
+
+@item -addstylesheet @var{file}
+
+Augment the default CSS style sheets with the user-specified
+stylesheet @var{file}.
+
+The given stylesheet is simply loaded by each HTML page in addition to
+the default ones, as the last stylesheet.
+
+Note that the CSS cascading rules apply.  That is, your style
+properties will only be assigned if they have a higher cascading order
+than @command{gjdoc}'s default style.  One simple way to make sure
+that this is the case is to declare your overrides @samp{!important}.
+
+See @w{@uref{http://www.w3.org/TR/REC-CSS2/cascade.html#cascading-order}}.
+
+@item -group @var{heading} @var{pkgwildcard}:@var{pkgwildcard}:@dots{}
+
+Arrange the given packages in a separate group on the overview page.
+
+The first argument should be a short plain text which is used as the
+title of the package group.  The second argument should be a
+colon-separated list of package wildcards.  The group will consist of
+all packages in the documentation set whose name matches any of the
+given wildcards.
+
+There is only one wildcard character, @samp{*}, which matches both
+letters in package name components and the @samp{.} separating package
+name components.  For example, @samp{j*regex} would match package
+@samp{java.util.regex}.  A more useful example would be
+@samp{javax.swing*} to match @samp{javax.swing} and all of its
+sub-packages.
+
+This option can be given multiple times.  
+
+FIXME: Information about group nesting here.
+
+@smallexample
+gjdoc -group "Core Classes" 'java*' \
+      -group "Swing" 'javax.swing*' \
+      -group "XML APIs" 'javax.xml*' \
+      -group "Other Extensions" javax* \
+      @dots{}
+@end smallexample
+
+@item -overview @var{file}
+
+Add the XHTML body fragment from @var{file} to the overview page.
+
+@var{file} should contain an XHTML fragment with the HTML @samp{body}
+tag as the root node.  @xref{XHTML Fragments}.
+
+This option can be used to supply a description of the documentation
+set as a whole.
+
+When specified, the first sentence of the fragment will be put above
+the tables listing the documented packages, along with a link to the
+full copy of the fragment which is put below the tables.
+@xref{First Sentence Detector}.
+
+When generating documentation for a single package, specifying this
+option forces generation of the overview page.
+
+@item -stylesheetfile @var{file}
+
+Use the CSS stylesheet in @var{file} instead of the default CSS
+stylesheets.
+
+If you only want to override parts of the default stylesheets, use
+@option{-addstylesheet} instead.
+
+@item -title @var{text}
+
+@emph{Deprecated.} Use @option{-doctitle} @var{text} instead.
+
+@item -helpfile @var{file}
+
+This option is currently ignored.
+
+When implemented, it will use the XHTML fragment in @var{file} for the
+help page contents instead of the default help text.
+
+@end table
+
+@node Output Control Options, Generation Options, Interlinking Options, gjdoc Tool
+@section Controlling the Output.
+
+@table @gcctabopt
+@item -d @var{directory}
+Place all output files into @var{directory} (and
+sub-directories). @var{directory} will be created if it does not
+exist, including all non-existing parent directories and all required
+sub-directories.
+
+If not specified, output will be placed into the current directory.
+
+@item -locale @var{name}
+
+Use locale @var{name} instead of the default locale for all purposes.
+
+@var{name} should be a locale specifier in the form @samp{ll_CC[_VAR]}
+where @samp{ll} is a lowercase two-letter ISO-639 language code,
+@samp{CC} is an optional uppercase two-letter ISO-3166 country code,
+and @samp{VAR} is an optional variant code.  For example, @samp{en}
+specifies English, @samp{en_US} specifies US English, and
+@samp{en_US_WIN} specifies a deviant variant of the US English locale.
+
+Note that the semantics of this option correspond exactly to those of
+the constructors of class @samp{java.util.Locale}.
+
+This option currently only determines which Collator is being used for
+sorting output elements.  This means that the locale will only have an
+effect when you are using non-ASCII characters in identifiers.
+
+@item -charset @var{charset}
+
+@emph{Deprecated.} Override the specified encoding in output XHTML
+files with the one given by @samp{charset}.
+
+If this option is not given, the encoding specification in output
+XHTML is chosen to match the encoding used when writing the file (the
+encoding given with @option{-docencoding}, or your platform's default
+encoding).
+
+The semantics for @var{charset} are specified here:
+@w{@uref{http://www.w3.org/TR/2000/REC-xml-20001006#NT-EncName}}.  For
+all practical purposes, they are identical to those of the other
+options accepting charset parameters.
+
+This option is here for compatibility with @command{javadoc} and
+should be avoided.
+
+@item -docencoding @var{charset}
+
+Use the given charset encoding when writing output files instead of
+your platform's default encoding.
+
+Examples for @var{charset} are @samp{US-ASCII}, @samp{ISO-8859-1} or
+@samp{UTF-8}.
+
+The semantics of this option correspond exactly to those of the
+constructors of class @samp{java.util.Locale}.
+
+@item -validhtml
+
+Force generation of valid XHTML code.  This breaks compatibility to
+the traditional Javadoc tool to some extent.
+
+If this option is specified, anchor names will be mangled so that they
+are valid according to the XHTML 1.1 specification.  However, a
+documentation set generated with this option cannot be linked to
+properly using the traditional Javadoc tool.  It can be linked to just
+fine using Gjdoc, though.
+
+Without this option, anchor names for executable class members use the
+traditional format, for example: ``foo(String,int[])''.  This is
+compatible to the traditional Javadoc tool, but according to both the
+HTML 4.0 and XHTML 1.0 and 1.1 specifications, this format includes
+illegal characters.  Parentheses, square brackets, and the comma are
+not allowed in anchor names.
+
+@item -baseurl @var{url}
+
+Hardwire a page URL relative to @var{url} into each generated page.
+
+If you are generating documentation which will exclusively be
+available at a certain URL, you should use this option to specify this
+URL.
+
+This can help avoid certain redirect attacks used by spammers, and it
+can be helpful for certain web clients.
+
+@end table
+
+@node Verbosity Options, Doclet Options, Virtual Machine Options, gjdoc Tool
+@section Verbosity Options
+
+@table @gcctabopt
+@item -quiet
+Suppress all output except for warnings and error messages.
+
+@item -verbose
+Be very verbose about what @command{gjdoc} is doing.
+
+This option is currently ignored.
+
+@end table
+
+@node Virtual Machine Options, Verbosity Options, Taglet Options, gjdoc Tool
+@section Virtual Machine Options
+
+Sun's @command{javadoc} tool seems to be based on @command{javac} and
+as such it seems to operate on the VM level.  @command{gjdoc}, in
+contrast, is a pure Java application.
+
+Therefore, @command{gjdoc} can only fake, or simulate, the following
+VM-level options.
+
+@table @gcctabopt
+
+@item -classpath @var{pathlist}
+Set the Virtual Machine @samp{classpath} to @var{pathlist}.
+
+In most cases you should use @option{-docletpath} or
+@option{-tagletpath} instead of this option.
+
+@var{pathlist} should be one or more paths to a directory or jar file,
+separated by your platform's path separator (usually @samp{:} or
+@samp{;}).
+
+If this option is not intercepted at the wrapper level,
+@command{gjdoc} currently fakes it by calling
+@samp{System.setProperty("java.class.path", @var{pathlist});} and
+outputs a warning.
+
+@item -bootclasspath @var{pathlist}
+Set the Virtual Machine @samp{bootclasspath} to @var{pathlist}.
+
+If this option is not intercepted at the wrapper level,
+@command{gjdoc} outputs a warning.
+
+@item -J@var{vmopt}
+
+Pass an arbitrary parameter to the Virtual Machine @command{gjdoc}
+runs on.
+
+If this option is not intercepted at the wrapper level,
+@command{gjdoc} tries to emulate the option and outputs a warning.
+
+Currently, only the VM option @option{-D} for setting system
+properties is emulated.
+
+@end table
+
+@c man end
+
+@comment ----------------------------------------------------------------------
+
+@node Invoking a Custom Doclet, Option Summary by Type, Invoking the Standard Doclet, gjdoc Tool
+@section Invoking a Custom Doclet
+
+For invoking one of the other doclets shipping with @command{gjdoc} or
+a third-party doclet, the canonical usage is:
+
+@smallexample
+gjdoc -s src/java/ -all \
+  -docletpath /path/to/doclet.jar -doclet foo.BarDoclet \
+  (more Gjdoc core options and Doclet-specific options here)
+@end smallexample
+
+@samp{/path/to/doclet.jar} is a placeholder for a class path
+specifying where the Doclet classes and dependencies can be found and
+@samp{foo.BarDoclet} is the fully-qualified name of the Doclet's main
+class.
+
+@comment ----------------------------------------------------------------------
+
+@node Gjdoc Option Summary, Source Set Options, Option Summary by Type, gjdoc Tool
+@section Gjdoc Option Summary
+@cindex Gjdoc Options
+
+@comment ----------------------------------------------------------------------
+
+@node Other Doclets, Gjdoc Concepts, Doclet Options, gjdoc Tool
+@chapter Generating Other Output Types
+
+@menu
+* Built-in Doclets::
+* Third-party Doclets::
+@end menu
+
+@comment ----------------------------------------------------------------------
+
+@node Built-in Doclets, Third-party Doclets, , Other Doclets
+@section Using the Built-in Doclets
+@cindex Built-in Doclets
+
+@menu
+* Using XmlDoclet::
+* Using TexiDoclet::
+* Using IspellDoclet::
+* Using DebugDoclet::
+@end menu
+
+@comment ----------------------------------------------------------------------
+
+@node Using TexiDoclet, Using XmlDoclet, , Built-in Doclets
+@subsection TexiDoclet: Generating Info, PDF, and other formats
+@cindex TexiDoclet
+
+Missing.
+
+@comment ----------------------------------------------------------------------
+
+@node Using XmlDoclet, Using IspellDoclet, Using TexiDoclet, Built-in Doclets
+@subsection XmlDoclet: Generating XML Documentation
+@cindex HtmlDoclet
+
+Missing.
+
+@comment ----------------------------------------------------------------------
+
+@node Using IspellDoclet, Using DebugDoclet, Using XmlDoclet, Built-in Doclets
+@subsection IspellDoclet: Spell-checking Source Code
+@cindex IspellDoclet
+
+Missing.
+
+@comment ----------------------------------------------------------------------
+
+@node Using DebugDoclet, , Using IspellDoclet, Built-in Doclets
+@subsection DebugDoclet: Inspecting the Doclet API
+@cindex HtmlDoclet
+
+Missing.
+
+@comment ----------------------------------------------------------------------
+
+@node Third-party Doclets, , Built-in Doclets, Other Doclets
+@section Using Third-Party Doclets
+@cindex Third-party Doclets
+
+@menu
+* DocBook Doclet::
+* PDFDoclet::
+* JUnitDoclet::
+@end menu
+
+@comment ----------------------------------------------------------------------
+
+@node DocBook Doclet,PDFDoclet, ,Third-party Doclets
+@subsection DocBook Doclet
+@cindex DocBook Doclet
+
+Missing.
+
+@comment ----------------------------------------------------------------------
+
+@node PDFDoclet, JUnitDoclet, DocBook Doclet, Third-party Doclets
+@subsection PDFDoclet
+@cindex PDFDoclet
+
+Missing.
+
+@comment ----------------------------------------------------------------------
+
+@node JUnitDoclet, , PDFDoclet, Third-party Doclets
+@subsection JUnitDoclet
+@cindex JUnitDoclet
+
+Missing.
+
+@comment ----------------------------------------------------------------------
+
+@node Gjdoc Concepts, , Other Doclets, gjdoc Tool
+@chapter Advanced Concepts
+
+@menu
+* Writing Doclets::
+* Taglets::
+* XHTML Fragments::
+* First Sentence Detector::
+* Adding Custom Resources::
+@end menu
+
+@comment ----------------------------------------------------------------------
+
+@node Taglets, Writing Doclets, , Gjdoc Concepts
+@section Adding Custom Tags to the Documentation
+@cindex Taglet
+
+Missing.
+
+@comment ----------------------------------------------------------------------
+
+@node Writing Doclets, XHTML Fragments, Taglets, Gjdoc Concepts
+@section Writing Doclets
+@cindex Taglet
+
+If the various Doclets already available don't suit your needs, you
+can write a custom Doclet yourself.  
+
+@menu
+* Doclet Invocation Interface::
+* Using AbstractDoclet::
+* GNU Doclet SPI::
+@end menu
+
+@comment ----------------------------------------------------------------------
+
+@node Doclet Invocation Interface, Using AbstractDoclet, , Writing Doclets
+@subsection Implementing the Doclet Invocation Interface
+
+A Doclet is a class that contains a method with the following
+signature:
+
+@smallexample
+public static boolean start(RootDoc rootDoc);
+@end smallexample
+
+@var{rootDoc} is the root of an object hierarchy containing the
+information @command{gjdoc} extracted from the source files.  See the
+Doclet API for more details.
+
+@samp{start} should process all the information and return
+@samp{true} on success, @samp{false} on failure.
+
+For printing status information, the Doclet should use methods
+@samp{printNotice}, @samp{printWarning} and @samp{printError} instead
+of @samp{System.err}.  The Doclet can opt to use @samp{System.out} for
+redirectable output.
+
+@comment ----------------------------------------------------------------------
+
+@node Using AbstractDoclet, GNU Doclet SPI, Doclet Invocation Interface, Writing Doclets
+@subsection Deriving Your Doclet from AbstractDoclet
+@cindex AbstractDoclet
+
+You may want your Doclet to provide functionality similar to
+HtmlDoclet.  For example, you may want it to support Taglets, generate
+Index, Tree, and Uses pages, or show other cross-reference information
+like @samp{Overrides} and @samp{All Implementing Classes}.
+
+This information is not directly provided by the Doclet API, so your
+Doclet would normally have to assemble it itself.  For example, it
+would have to add the names of all program elements to a list and sort
+this list in order to create the Index page.
+
+If you want to provide this information or part of it, you should
+consider deriving your class from
+@samp{gnu.classpath.tools.doclets.AbstractDoclet}.  This class
+provides the following benefits:
+
+@itemize @bullet
+
+@item 
+Handles options @option{-tag}, @option{-taglet}, @option{-tagletpath}
+(Taglets)
+
+@item 
+Provides standard taglets for @@version, @@author, @@since, @@serial,
+@@deprecated, @@see, @@param, @@return and handles all related options
+(@option{-version}, @option{-author}, @option{-nosince},
+@option{-nodeprecated})
+
+@item 
+Handles option @option{-d} (destination directory)
+
+@item 
+Handles option @option{-noqualifier} (classes to omit qualifier for)
+
+@item 
+Handles options @option{-docfilessubdirs} and
+@option{-excludedocfilessubdir} (resource copying)
+
+@item 
+Can generate a full index or an index split by first letter
+
+@item 
+Can generate a full tree and package trees
+
+@item 
+Can generate cross-reference information
+
+@item 
+Can aggregate interface information (all superinterfaces, all
+subinterfaces, all implementing classes)
+
+@item 
+Provides convenient access to constructors, fields, methods, and inner
+classes sorted by name/signature instead of the default sort order.
+
+@item 
+Provides various other convenience methods
+
+@end itemize
+
+If you derive from @samp{AbstractDoclet}, there are a number of things
+you need to take care of:
+
+@itemize @bullet
+
+@item 
+
+@end itemize
+
+you should not implement the
+@samp{start(RootDoc)} method as it is already defined by
+@samp{AbstractDoclet} so that it can care about parsing the options.
+
+Instead, you implement method @samp{run()}, @samp{getOptions()} and
+the other abstract methods to define your Doclet's behavior.
+
+Note that all information provided by @samp{AbstractDoclet} is
+evaluated lazily.  That is, if your Doclet doesn't need to create an
+Index page, then @samp{AbstractDoclet} will not spend resources on
+creating the corresponding information.
+
+See the API documentation for
+@samp{gnu.classpath.tools.doclets.AbstractDoclet} for more details.
+
+You should be aware that if you base your Doclet on
+@samp{AbstractDoclet} then you have to bundle this and all related
+classes with your Doclet, with all implications such as possible
+licensing issues.  Otherwise, your Doclet will only be runnable on
+@samp{gjdoc} and not on other documentation systems.  Also note that
+@samp{AbstractDoclet} has not been extensively tested in environments
+other than @samp{gjdoc}.
+
+@comment ----------------------------------------------------------------------
+
+@node GNU Doclet SPI, , Using AbstractDoclet, Writing Doclets
+@subsection Preparing for the GNU Doclet Service Provider Interface
+@cindex GNU Doclet SPI, Service Provider, SPI
+
+In addition to the standard Doclet invocation interface described
+above, @command{gjdoc} also offers a Service Provider Interface
+conforming to the Java standard.  Adding support for this interface to
+your Doclet simplifies usage for @command{gjdoc} users because it
+makes your Doclet ``discoverable''.
+
+In order to provide the alternate interface, you have to add a class
+implementing @samp{gnu.classpath.tools.gjdoc.spi.DocletSpi} to your
+Doclet classes, and bundle all Doclet classes in a Jar file along with
+a file named
+@samp{META_INF/services/gnu.classpath.tools.gjdoc.spi.DocletSpi} which
+contains the name of your class implementing DocletSpi on a single
+line.
+
+Note that if your Doclet depends on third-party classes bundled in
+separate Jar files, you can link in these classes using the
+@samp{Class-path:} Manifest attribute of your Doclet Jar.
+
+Your Doclet can then be invoked in one of the following ways:
+@smallexample
+gjdoc -docletjar /path/to/doclet.jar
+gjdoc -docletpath /path/to/doclet.jar -docletname @var{docletname}
+gjdoc -docletname @var{docletname}
+@end smallexample
+
+Here, @var{docletname} is the name of your doclet as returned by
+@samp{DocletSpi.getDocletName()}.
+
+The last example will only work if your Doclet Jar is in
+@command{gjdoc}'s @file{doclets} directory or if it is on the
+classpath.
+
+@comment ----------------------------------------------------------------------
+
+@node XHTML Fragments, First Sentence Detector, Writing Doclets, Gjdoc Concepts
+@section Well-formed Documentation Fragments
+@cindex XHTML Fragments
+
+For many Doclets it is advantagous if the HTML code in the comments
+and HTML code passed via the command line is well-formed.  For
+example, HtmlDoclet outputs XHTML code, and XmlDoclet XML code, both
+of which results in invalid files if the user-specified HTML isn't
+wellformed.
+
+Unfortunately, comments were never required to contain well-formed
+HTML code, which means that every Doclet must deal with non-wellformed
+code as well.
+
+The @command{gjdoc} built-in Doclets deal with this problem by
+``fixing'' the HTML code - making sure that all tags are closed,
+attribute values are provided and quoted, tags are properly nested,
+etc.
+
+This approach works OK in most instances, but since it uses some crude
+heuristics it can sometimes produce undesirable result.
+
+Therefore, in order to make sure that your comments are always
+properly formatted, make sure they are well-formed as described in
+@w{@uref{http://www.w3.org/TR/xhtml1/#h-4.1, XHTML 1.0: Documents must
+be well-formed}}.
+
+In addition, you should use meaningful tags instead of text formatting
+tags to make your output look better in other output formats derived
+from your HTML code.  For example, you should use the <em> tag instead
+of <b> if you want to emphasize text.
+
+@comment ----------------------------------------------------------------------
+
+@node First Sentence Detector, Adding Custom Resources, XHTML Fragments, Gjdoc Concepts
+@section How Gjdoc Determines where the First Sentence Ends
+@cindex First Sentence Detector
+
+For a package, class or member summary, @command{gjdoc} only shows the
+first sentence of the documentation comment in question.  Because
+@command{gjdoc} is not human, it is not always obvious to
+@command{gjdoc} where the first sentence ends.
+
+You might be tempted to say that the first sentence ends at the first
+occurrence of a punctuation character like @samp{.} or
+@samp{!}. However, consider examples like this:
+@smallexample
+This work, by Thomas J. Shahan et al., is about the middle ages.
+@end smallexample
+
+As you can see, it is not trivial to determine the end of the
+sentence.
+
+@command{gjdoc} gives you the choice between two approaches.  By
+default it uses built-in heuristics which should be compatible to
+Sun's @command{javadoc} tool.  This approach works quiet well in most
+cases, at least for english comments.
+
+Alternatively, you can specify option @option{-breakiterator} in which
+case @command{gjdoc} will use
+@samp{java.text.BreakIterator.getSentenceInstance(@var{locale}).next()}
+to find the end of sentence, where @var{locale} is the locale
+specified by option @samp{-locale} or the default locale if none
+specified.
+
+@emph{NOT YET IMPLEMENTED:}
+
+@command{gjdoc} also allows you to explicitly delineate the first
+sentence by putting it in a @samp{<span>} tag with the CSS class
+@samp{first-sentence}.  For example:
+@smallexample
+/**
+ *  <span class="first-sentence">This. is. the. first. 
+ *  sentence.</span> This is the second sentence.
+ */
+@end smallexample
+
+Note that this will only work with @command{gjdoc}, but shouldn't hurt
+when using another documentation system since the @samp{<span>} tag
+usually doesn't show up in the output.
+
+@comment ----------------------------------------------------------------------
+
+@node Adding Custom Resources, , First Sentence Detector, Gjdoc Concepts
+@section Adding Images and Other Resources
+@cindex First Sentence Detector
+
+Sometimes you want to decorate your documentation with secondary
+resources such as images, SVG graphics, applets, and so on.  To do so,
+simply put the required files in a subdirectory 'doc-files' in the
+package directory corresponding to the documentation entry you want to
+decorate, and refer to it with the URL
+@samp{doc-files/@var{filename}}.
+
+For example, if you want to add an image to the description of class
+@samp{baz.FooBar}, create a directory @file{doc-files} in the
+directory @file{baz} containing @file{FooBar.java} and put your file,
+say @file{diagram.png}, into that directory.  Then, add the HTML code
+like this to a comment in @file{FooBar.java}:
+@smallexample
+<img src="doc-files/diagram.png" width="200" height="150"
+  alt="Foo Diagram"/>
+@end smallexample
+
+This works because the @file{doc-files} subdirectories will be copied
+to the target documentation directory every time you generate the
+documentation.  
+
+Note however that by default, the @file{doc-files} directory will not
+be copied deeply.  In other words, if you create subdirectories under
+@file{doc-files} they will not be copied and any resources located in
+these subdirectories will not be accessible in your generated
+documentation.  You can specify option @option{-docfilessubdirs} to
+remove this limitation.
+
+Sometimes you want to use option @option{-docfilessubdirs}, but there
+are certain directories which you don't want to be copied, for example
+because they contain source files for the resources in
+@file{doc-files}.  For cases like this, use
+@option{-excludedocfilessubdir} to specify directories to be omitted.
+
+@comment ----------------------------------------------------------------------
+
+@node I18N Issues, , Other Tools, Top
+@comment node-name, next, previous, up
+@chapter I18N Issues
+
+Some tools --@pxref{Security Tools}-- allow using other than the English language when prompting the User for input, and outputting messages. This chapter describes the elements used to offer this support and how they can be adapted for use with specific languages.
+
+@menu
+* Language Resources::         Where resources are located
+* Message Formats::            How messages are internationalized
+@end menu
+
+@comment ----------------------------------------------------------------------
+
+@node Language Resources, Message Formats, I18N Issues, I18N Issues
+@comment node-name, next, previous, up
+@section Language-specific resources
+
+The Tools use Java @code{ResourceBundle}s to store messages, and message templates they use at runtime to generate the message text itself, depending on the locale in use at the time.
+
+The @i{Resource Bundles} these tools use are essentially Java @i{Properties} files consisting of a set of @i{Name/Value} pairs. The @i{Name} is the @i{Property Name} and the @i{Value} is a substitution string that is used when the code references the associated @i{Name}. For example the following is a line in a @i{Resource Bundle} used by the @code{keytool} Tool:
+
+@example
+Command.23=A correct key password MUST be provided
+@end example
+
+When the tool needs to signal a mandatory but missing key password, it would reference the property named @code{Command.23} and the message "@kbd{A correct key password MUST be provided}" will be used instead. This indirect referencing of "resources" permits replacing, as late as possible, the English strings with strings in other languages, provided of course @i{Resource Bundles} in those languages are provided.
+
+For the GNU Classpath Tools described in this Guide, the @i{Resource Bundles} are files named @file{messages[_ll[_CC[_VV]]].properties} where:
+
+@ftable @var
+@item ll
+Is the 2-letter code for the Language,
+@item CC
+Is the 2-letter code for the Region, and
+@item VV
+Is the 2-letter code for the Variant of the language.
+@end ftable
+
+The complete list of language codes can be found at @uref{http://ftp.ics.uci.edu/pub/ietf/http/related/iso639.txt, Code for the representation of names of languages}. A similar list for the region codes can be found at @uref{http://userpage.chemie.fu-berlin.de/diverse/doc/ISO_3166.html, ISO 3166 Codes (Countries)}.
+
+The location of the @i{Resource Bundles} for the GNU Classpath Tools is specific to each tool. The next table shows where these files are found in a standard GNU Classpath distribution:
+
+@ftable @code
+@item jarsigner
+@file{gnu/classpath/tools/jarsigner}
+@item keytool
+@file{gnu/classpath/tools/keytool}
+@end ftable
+
+The collection of @i{Resource Bundles} in a location act as an inverted tree with a parent-child relationship. For example suppose in the @file{gnu/classpath/tools/keytool} there are 3 message bundles named:
+
+@enumerate
+@item @code{messages.properties}
+@item @code{messages_fr.properties}
+@item @code{messages_fr_FR.properties}
+@end enumerate
+
+In the above example, bundle #1 will act as the parent of bundle #2, which in turn will act as the parent for bundle #3. This ordering is used by the Java runtime to choose which file to load based on the set Locale. For example if the Locale is @code{fr_CH}, @code{messages_fr.properties} will be used because (a) @code{messages_fr_CH.properties} does not exist, but (b) @code{messages_fr.properties} is the parent for the required bundle, and it exists. As another example, suppose the Locale was set to @code{en_AU}; then the tool will end up using @code{messages.properties} because (a) @code{messages_en_AU.properties} does not exist, (b) @code{messages_en.properties} which is the parent for the required bundle does not exist, but (c) @code{messages.properties} exists and is the root of the hierarchy.
+
+You can see from the examples above that @file{messages.properties} is the safety net that the Java runtime falls back to when failing to find a specific bundle and its parent(s). This file is always provided with the Tool. In time, more localized versions will be included to cater for other languages.
+
+In the meantime, if you are willing to contribute localized versions of these resources, grab the @file{messages.properties} for a specific tool; translate it; save it with the appropriate language and region suffix and mail it to @code{classpath@@gnu.org}.
+
+@comment ----------------------------------------------------------------------
+
+@node Message Formats, , Language Resources, I18N Issues
+@comment node-name, next, previous, up
+@section Message formats
+
+If you open any of the @file{messages.properties} described in the previous section, you may see properties that look like so:
+
+@example
+Command.67=Issuer: @{0@}
+Command.68=Serial number: @{0,number@}
+Command.69=Valid from: @{0,date,full@} - @{0,time,full@}
+Command.70=\ \ \ \ \ until: @{0,date,full@} - @{0,time,full@}
+@end example
+
+These are @i{Message Formats} used by the tools to customize a text string that will then be used either as a prompt for User input or as output.
+
+If you are translating a @file{messages.properties} be careful not to alter text between curly braces.
+
+@comment ----------------------------------------------------------------------
+
+@bye
diff --git a/libjava/classpath/doc/cp-vmintegration.texinfo b/libjava/classpath/doc/cp-vmintegration.texinfo
new file mode 100644
index 000000000..0b2d78c84
--- /dev/null
+++ b/libjava/classpath/doc/cp-vmintegration.texinfo
@@ -0,0 +1,1999 @@
+\input texinfo @c -*-texinfo-*-
+
+@c %**start of header
+@setfilename cp-vmintegration.info
+@settitle GNU Classpath VM Integration Guide
+@c %**end of header
+
+@setchapternewpage off
+
+@ifinfo
+This file contains important information you will need to know if you
+are going to write an interface between GNU Classpath and a Virtual
+Machine.
+
+Copyright (C) 1998-2002, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
+
+@ifnotplaintext
+@dircategory GNU Libraries
+@direntry
+* VM Integration: (cp-vmintegration).  GNU Classpath VM Integration Guide
+@end direntry
+@end ifnotplaintext
+@end ifinfo
+
+@titlepage
+@title GNU Classpath VM Integration Guide
+@author John Keiser
+@author C. Brian Jones
+@author Mark Wielaard
+
+@page
+@vskip 0pt plus 1filll
+Copyright @copyright{} 1998-2002 Free Software Foundation, Inc.
+@sp 2
+Permission is granted to make and distribute verbatim copies of
+this document provided the copyright notice and this permission notice
+are preserved on all copies.
+
+Permission is granted to copy and distribute modified versions of this
+document under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions,
+except that this permission notice may be stated in a translation
+approved by the Free Software Foundation.
+
+@end titlepage
+
+@ifinfo
+@node Top, Introduction, (dir), (dir)
+@top GNU Classpath Hacker's Guide
+
+This file contains important information you will need to know if you
+are going to write an interface between GNU Classpath and a Virtual
+Machine.
+
+This document is incomplete, as we are still in alpha with the interface.
+
+@end ifinfo
+
+@menu
+* Introduction::                An introduction to the Classpath project
+* Initialization::              Initializing the classes
+* Classpath Hooks::             Hooks from Classpath to the VM
+* VM Hooks::                    Hooks from the underlying VM to Classpath
+* JNI Implementation::		Hooking the VM to jni.h
+* JVMTI Implementation::        Hooking the VM to jvmti.h
+* Miscellaneous VM Requirements::  
+@end menu
+
+@node Introduction, Initialization, Top, Top
+@comment node-name, next, previous, up
+@chapter Introduction
+
+The Classpath Project's ambition to be a 100% clean room implementation
+of the standard Java class libraries cannot be fulfilled without some
+level of integration with the Virtual Machine, the underlying machinery
+that actually runs Java.
+
+There are several VMs out there, here is a small list.
+
+@itemize @bullet
+@item @uref{http://www.hungry.com/old-hungry/products/japhar/,Japhar}
+Japhar was the first VM to use GNU Classpath.  Today you can see that
+sort of relationship in the source tree which denotes several Japhar
+specific files as a reference implementation of those pieces.  This VM
+has been primarily tested against Linux and lacks garbage collections, a
+JIT, and suffers recently from slow development.
+
+@item @uref{http://www.intel.com/research/mrl/orp/,Intel's Open Runtime Platform}
+Intel surprised us not long ago with the release of this rather advanced
+VM that uses GNU Classpath for a set of class libraries and works on
+Linux and Windows 2000.  As of June, 2004, it does not appear that ORP
+is under active development.
+
+@item @uref{http://www.sablevm.org/,SableVM}
+SableVM is a robust, extremely portable, efficient, and
+specifications-compliant Java Virtual Machine that aims to be easy to
+maintain and to extend. It features a state-of-the-art, efficient
+interpreter engine. Its source code is very accessible and easy to
+understand, and has many robustness features that have been the object
+of careful design.
+
+@item @uref{http://www.kaffe.org,Kaffe}
+Kaffe is an advanced VM and together with its own class libraries
+provides a Java 1.1 compatible environment.
+
+@item @uref{http://www.mozilla.org/projects/ef,Electrical Fire}
+The Electrical File VM continues to be listed as a Mozilla project
+though development has been somewhat quiet.  A number of concepts from
+EF were expected at one point to be rolled into Japhar, but that
+development has not occurred as of yet.
+
+@item @uref{http://latte.snu.ac.kr/,LaTTe}
+This VM project so far supports only Sun UltraSparc processors using the
+proprietary Solaris 2.5.1 or higher operating system.  LaTTe was derived
+from Kaffe but claims a number of improvements.
+
+@item @uref{http://gcc.gnu.org/java/,GNU Compiler for Java (GCJ)}
+This is a portable, optimizing, ahead-of-time compiler for the Java
+Programming Language. It can compile Java source code directly to native
+machine code, Java source code to Java bytecode (class files), and Java
+bytecode to native machine code. Compiled applications are linked with the
+GCJ runtime, libgcj which is based on the GNU Classpath code, which provides
+the core class libraries, a garbage collector, and a bytecode interpreter.
+libgcj can dynamically load and interpret class files, resulting in mixed
+compiled/interpreted applications.
+GCJ is part of the GNU Compiler Collection (@uref{http://gcc.gnu.org/,GCC}).
+On March 6 2000 the libgcj and GNU Classpath projects were officially merged
+and there is active work on merging all the classes between the projects.
+Licensed under GPL+exception, just as GNU Classpath is.
+
+@item @uref{http://kissme.sourceforge.net/,Kissme}
+This is a free Java Virtual Machine that is being developed on GNU/Linux
+and can run console Java applications.  Kissme also provides support for
+orthogonally persistent Java.
+@c I don't know what ``orthogonally persistent Java'' is, and I bet
+@c there are other people don't know either. -- Steve Augart, 4 June 2004
+
+@item @uref{http://jamvm.sourceforge.net/,JamVM}
+A simple, small bytecode interpreter that works out-of-the-box with
+pure GNU Classpath; it is emerging as the preferred platform for
+quickly testing a new build of GNU Classpath.  Licensed under the GPL.
+
+@item @uref{http://jikesrvm.sourceforge.net/,Jikes RVM}
+A free runtime environment for Java, written in Java.  Works
+out-of-the-box with pure GNU Classpath.  Features an optimizing JIT.
+Runs on the x86 and PowerPC architectures, on the AIX, Linux, and Mac
+OS/X operating systems.  Licensed under the CPL (Common Public
+License).  Extensively documented.  Actively developed as of June,
+2004.
+
+@end itemize
+
+In the past integration efforts were focused mainly on Japhar with an eye
+towards getting Electrical Fire to work.  Most information contained in
+this document is gleaned from these efforts. Recently more work has been
+done on getting gcj, orp and kissme to work out of the box with GNU Classpath
+but there is much to do before that becomes a reality.
+
+
+@node Initialization, Classpath Hooks, Introduction, Top
+@comment node-name, next, previous, up
+@chapter Initialization
+
+The order of initialization, as far as I can tell, doesn't matter just
+yet.  However, when we move to 1.2 support, it probably will matter, so
+we'll have a note in here at that time.
+
+The initialization order is currently documented in the
+@file{Runtime.java} source file.
+
+@node Classpath Hooks, VM Hooks, Initialization, Top
+@comment node-name, next, previous, up
+@chapter Classpath Hooks
+
+The primary method of interaction between Classpath and the VM is via
+the helper classes, which are named after the relevant core library
+class, but include an additional `VM' prefix.  The library classes from
+Classpath call out to these to get certain VM-specific dirty work done.
+A reference copy of each VM class exists.  The majority consist of a
+series of static methods, some of which are simply declared
+@code{native}, and some which provide a default implementation.  VMs may
+either use these as is, or create their own local variations.  When
+using the default implementations, the VM is responsible for
+implementing any of the code marked as @code{native} which corresponds
+to functionality they wish their VM to provide.  When using their own
+versions of the classes, VM implementors may choose to change the mix of
+native and non-native methods from that below, so as to best suit their
+implementation.
+
+@menu
+* java.lang::
+* gnu.classpath::
+* java.util::
+* java.io::
+* java.security::
+* java.net::
+* java.nio::
+* java.nio.channels::
+* gnu.java.nio::
+* java.lang.reflect::
+* gnu.java.lang::
+* gnu.java.lang.management::
+* java.lang.management::
+* Classpath Callbacks::
+@end menu
+
+@node java.lang, gnu.classpath, Classpath Hooks, Classpath Hooks
+@comment  node-name,  next,  previous,  up
+
+@section @code{java.lang}
+
+@code{java.lang} is the core Java package, being imported automatically by all
+classes.  It includes basic classes as @code{Object} and @code{String}.
+A VM must implement at least some parts of this package in order to
+become operable.
+
+@menu
+* java.lang.VMClass::
+* java.lang.VMObject::
+* java.lang.VMClassLoader::
+* java.lang.VMSystem::
+* java.lang.VMThrowable::
+* java.lang.VMCompiler::
+* java.lang.VMDouble::
+* java.lang.VMFloat::
+* java.lang.VMProcess::
+* java.lang.VMRuntime::
+* java.lang.VMString::
+* java.lang.VMThread::
+* java.lang.VMMath::
+@end menu
+
+@node java.lang.VMClass, java.lang.VMObject ,java.lang,java.lang
+@subsection @code{java.lang.VMClass}
+
+The core class, @code{java.lang.Class}, and the corresponding VM class,
+@code{java.lang.VMClass}, provide two main functions within GNU Classpath.
+
+@enumerate
+@item For basic VM operation, @code{java.lang.Class} provides the link between
+the Java-based representation of a class it embodies and the VM's own
+internal structure for a class.  @xref{VM Hooks}.
+
+@item As far as the user is concerned, the main function of
+@code{java.lang.Class} is as an entry point to the reflection
+facilities, and so it also provides this functionality, backed by the
+VM class.
+@end enumerate
+
+This VM class lists the following methods, organized by the version of the
+Java specification in which they occur.  All are @code{native}, unless
+otherwise specified, and pertain to reflection.  As a result, the VM only
+needs to implement these methods in order to provide reflection support,
+and then only to the degree required.
+
+@itemize @bullet
+@item 1.0
+@itemize @bullet
+@item @code{isInterface(Class)} -- This is simply a property test, and matches
+the presence of an appropriate flag within the class file.
+@item @code{getName(Class)} -- Returns the fully-qualified name of the class.
+@item @code{getSuperclass(Class)} -- Returns a @code{Class} instance which
+represents the superclass.  Again, the class file contains an element directly
+relating to this.  @code{null} is returned for primitives, interfaces and
+@code{Object}.
+@item @code{getInterfaces(Class)} -- Same as the above, but the implemented
+or extended interfaces rather than the superclass.  An empty array should
+be returned, rather than @code{null}.
+@item @code{getDeclaredClasses(Class,boolean)} -- Returns the internal classes
+this instance declares directly.  The flag determines whether or not the
+VM should filter out non-public classes.
+@item @code{getDeclaredFields(Class,boolean)} -- The same for fields.
+@item @code{getDeclaredMethods(Class,boolean)} -- And for methods.
+@item @code{getDeclaredConstructors(Class,boolean)} -- And constructors.
+@item @code{getClassLoader(Class)} -- Returns the @code{ClassLoader} instance
+which is responsible for the specified class.
+@item @code{forName(String, boolean, ClassLoader)} -- The VM should create a
+@code{Class} instance corresponding to the named class.  As noted in
+@ref{VM Hooks}, the internal content of the instance is the
+responsibility of the VM@.  The supplied class loader is recorded as that
+which loaded the class, and the boolean specifies whether or not to
+run the class initializer.
+@item @code{isArray(Class)} -- Another property test, corresponding to a
+class file flag.
+@item @code{initialize(Class)} -- The VM should initialize the class fully,
+if it has not already done so.
+@item @code{loadArrayClass(String,ClassLoader)} -- This is called if
+@code{forName} returns @code{null} and the string specifies an array class.
+The specified array class should be loaded with the supplied class loader.
+@item @code{throwException(Throwable)} -- The VM should throw the supplied
+checked exception, without declaring it.
+@end itemize
+@item 1.1
+@itemize @bullet
+@item @code{isInstance(Class,Object)} -- This is a reflection-based equivalent
+of the @code{instanceof} operator.
+@item @code{isAssignableFrom(Class,Class)} -- Mainly a shorthand for the above,
+removing the need to create an instance to test assignability.  
+@item @code{isPrimitive(Class)} -- Returns true if this class is simply
+a representation of one of the primitive types: @code{boolean}, @code{byte},
+@code{char}, @code{short}, @code{int}, @code{long}, @code{float},
+@code{double} and @code{void}.
+@item @code{getComponentType(Class)} -- Produces a @code{Class} instance which
+represents the type of the members of the array the class instance represents.
+Classes which don't represent an array type return @code{null}.
+@item @code{getModifiers(Class,boolean)} -- Returns an integer which encodes
+the class' modifiers, such as @code{public}.  Again, this relates to
+information stored in the class file.
+@item @code{getDeclaringClass(Class)} -- Returns the class that declared
+an inner or member class, or @code{null} if the instance refers to a top-level
+class.
+@end itemize
+@item 1.5
+@itemize @bullet
+@item @code{isSynthetic(Class)} -- Returns true if the flags for this class
+mark it as synthetic.
+@item @code{isAnnotation(Class)} -- Returns true if the flags for this class
+mark it as an annotation.
+@item @code{isEnum(Class)} -- Returns true if the flags for this class
+mark it as an enumeration.
+@item @code{getSimpleName(Class)} -- Returns the simple name of the class.
+A default implementation is provided, but a more efficient version may instead
+be provided by the VM.
+@item @code{getCanonicalName(Class)} -- Returns the canonical name of the
+class.  A default implementation is provided, but a more efficient
+version may instead be provided by the VM.
+@item @code{getEnclosingClass(Class)} -- Returns the immediately enclosing
+class (null for a top-level class).
+@item @code{getEnclosingConstructor(Class)} -- Returns the constructor
+which immediately encloses the supplied class.
+@item @code{getEnclosingMethod(Class)} -- Returns the method
+which immediately encloses the supplied class.
+@item @code{getClassSignature(Class)} -- Returns the generic signature of
+the class or null if there isn't one.
+@item @code{isAnonymousClass(Class)} -- Returns true if the class is an
+anonymous class.
+@item @code{isLocalClass(Class)} -- Returns true if the class is an
+local class.
+@item @code{isMemberClass(Class)} -- Returns true if the class is an
+member class.
+@end itemize
+@end itemize
+
+@node java.lang.VMObject, java.lang.VMClassLoader, java.lang.VMClass, java.lang
+@subsection @code{java.lang.VMObject}
+
+@code{VMObject} is the bridge between the low level @code{Object}
+facilities such as making a clone, getting the class of the object and
+the wait/notify semantics.  This is accomplished using the following
+@code{native} methods.
+
+@itemize @bullet
+@item @code{getClass(Object)} -- Returns the @code{Class} instance for the
+object.  @code{Class} objects are produced by the VM, as described in
+@ref{VM Hooks}.
+@item @code{clone(Cloneable)} -- The VM should produce a low-level clone of the
+specified object, creating a field-by-field shallow copy of the original.
+The only difference between the two is that the new object should still be
+@code{finalizable}, even if the original is not.
+@item @code{notify(Object)} -- The VM should choose one of the threads waiting
+for a lock on the specified object arbitrarily, and wake it.  If the current
+thread does not currently hold the lock on the object, then an
+@code{IllegalMonitorStateException} should be thrown.
+@item @code{notifyAll(Object)} -- Same as the above, but all threads are
+awakened.
+@item @code{wait(Object,long,int)} -- The VM should set the current thread
+into a waiting state, which persists until it receives a notify signal or the
+specified time (in milliseconds and nanoseconds) is exceeded.  The nanoseconds
+restriction may be ignored if such granularity is not available, and a
+@code{IllegalMonitorStateException} should be thrown if the current thread
+doesn't own the object.
+@end itemize
+
+@node java.lang.VMClassLoader, java.lang.VMSystem, java.lang.VMObject, java.lang
+@subsection @code{java.lang.VMClassLoader}
+@code{VMClassLoader} provides methods for defining and resolving core and
+primitive classes, as well as handling resources, packages and assertions.
+The class is a mixture of @code{native} methods and Java-based
+implementations, with some of the latter being @emph{stubs}.
+
+@itemize @bullet
+@item Native Methods
+@itemize @bullet
+@item @code{defineClass(ClassLoader,String,byte[],int,int,ProtectionDomain)}
+-- The VM should create a @code{Class} instance from the supplied byte array.
+@item @code{resolveClass(Class)} -- Resolve references to other classes in the
+supplied class.
+@item @code{loadClass(name,boolean)} -- Load a class using the bootstrap
+loader.
+@item @code{getPrimitiveClass(char)} -- The VM should provide a @code{Class}
+implementation for one of the primitive classes.  The supplied character
+matches the JNI code for the primitive class e.g.@: `B' for byte and
+`Z' for boolean.
+@end itemize
+@item Java Methods
+@itemize @bullet
+@item @code{getResource(String)} -- The default implementation calls
+@code{getResources} and returns the first element in the returned enumeration,
+or @code{null} if there are no elements.
+@item @code{getResources(String)} -- By default, this compiles a list of
+URLs via the boot class path.  Any matching files within a zip file are added,
+and directories on the boot class path are automatically converted to file
+URLs that refer to join the directory with the resource name (whether or not
+it actually exists).
+@item @code{getPackage(String)} -- Always returns null, which may be suitable
+if the VM does not wish to return a @code{Package} implementation. Otherwise,
+it may be necessary to make this a @code{native} method.
+@item @code{getPackages()} -- As with the last, a default stub implementation
+exists (returning an empty array) which may be replaced if support is
+required. 
+@item @code{defaultAssertionStatus()} -- A stub which can be implemented
+by VMs providing assertion support.  At present, it always returns @code{true}.
+@item @code{packageAssertionStatus()} -- Much the same status as the above.
+The method should return a map converting package names to boolean status
+values.  The stub implementation provides an empty map.
+@item @code{classAssertionStatus()} -- Same as the last, but for classes.
+@item @code{getSystemClassLoader()} -- The default calls @code{ClassLoader}
+to create a new auxiliary class loader with a system and extension class
+loader.  The VM may wish to replace it if it wishes to supply its own custom
+system class loader.
+@end itemize
+@end itemize
+@node java.lang.VMSystem, java.lang.VMThrowable, java.lang.VMClassLoader, java.lang
+@subsection @code{java.lang.VMSystem}
+@code{VMSystem} handles the default I/O streams, provides access to the
+system clock and environment variables and provides methods for
+@code{System.arraycopy} and the @code{identityHashCode} of an
+@code{Object}.  It consists of @code{native} methods, but the default
+implementation also provides some helper methods to simplify stream
+creation.  
+
+@itemize @bullet
+@item Native Methods
+@itemize @bullet
+@item @code{arraycopy(Object,int,Object,int,int)} -- The VM should copy
+a specified number of array objects from one array to another, with 
+appropriate checks for compatible typing, available elements and space.
+The VM should be able to perform this more efficiently using native code
+and direct memory manipulation than would have been achieved by using Java.
+@item @code{identityHashCode(Object)} -- This is the hashcode for
+@code{Object}, which relates to the actual location of the object in memory.
+@item @code{setIn(InputStream)} -- Set the system input stream.
+@item @code{setOut(PrintStream)} -- Set the system output stream.
+@item @code{setErr(PrintStream)} -- Set the system error stream.
+@item @code{currentTimeMillis()} -- Gets the system time in milliseconds.
+@item @code{getenv(String)} -- Returns the value of the specified environment
+variable.
+@item @code{getenv()} -- Returns a list of `name=value' pairs which correspond
+to the environment variables.
+@end itemize
+@item Java Methods
+@itemize @bullet
+@item @code{makeStandardInputStream()} -- Helps provide the functionality of
+@code{System.in} by wrapping the appropriate file descriptor in a
+buffered file input stream.  VMs may choose to create the stream from
+the descriptor differently rather than using this method.
+@item @code{makeStandardOutputStream()} -- Helps provide the functionality of
+@code{System.out} by wrapping the appropriate file descriptor in a buffered
+file output stream.  VMs may choose to create the stream from the descriptor
+differently rather than using this method.
+@item @code{makeStandardErrorStream()} -- Helps provide the functionality of
+@code{System.err} by wrapping the appropriate file descriptor in a buffered
+file output stream.  VMs may choose to create the stream from the descriptor
+differently rather than using this method.
+@end itemize
+@end itemize
+
+Classpath also provides native implementations of
+
+@itemize @bullet
+@item @code{setIn(InputStream)} 
+@item @code{setOut(PrintStream)} 
+@item @code{setErr(PrintStream)} 
+@item @code{currentTimeMillis()} 
+@item @code{getenv(String)}
+@end itemize
+
+making a VM implementation optional.
+
+@node java.lang.VMThrowable, java.lang.VMCompiler, java.lang.VMSystem, java.lang
+@subsection @code{java.lang.VMThrowable}
+@code{VMThrowable} is used to hold the VM state of a throwable, created either
+when a @code{Throwable} is created or the @code{fillInStackTrace()} method is
+called (i.e., when the actual stack trace is needed, as a lot of exceptions are
+never actually used).  The actual class has two @code{native} methods,
+one (@code{fillInStackTrace()}) being a method of the class used to obtain
+instances, and the other an instance method, @code{getStackTrace()}.
+@itemize @bullet
+@item @code{fillInStackTrace(Throwable)} -- The VM should return the current
+execution state of the @code{Throwable} in the form of a @code{VMThrowable}
+instance.  The VM may also return @code{null} if it does not support this
+functionality.
+@item @code{getStackTrace()} -- This is used to create a real
+@code{StackTraceElement} array for the exception, using the state data
+stored during creation of the instance.
+@end itemize
+
+@node java.lang.VMCompiler, java.lang.VMDouble, java.lang.VMThrowable, java.lang
+@subsection @code{java.lang.VMCompiler}
+
+@code{VMCompiler} provides an interface for VMs which wish to provide
+JIT compilation support.  The default implementation is simply a series
+of stubs. The property, @code{java.compiler}, should point to a library
+containing the function @code{java_lang_Compiler_start()} if such support
+is to be provided.
+
+@itemize @bullet
+@item @code{compileClass(Class)} -- Invoke the compiler to compile the specific
+class, returning @code{true} if successful.
+@item @code{compileClasses(String)} -- The compiler should compile the classes
+matching the specified string, again returning @code{true} on success.
+@item @code{command(Object)} -- The object represents a command given to the
+compiler, and is specific to the compiler implementation.
+@item @code{enable} -- Enable the operation of the compiler.
+@item @code{disable} -- Disable compiler operation.
+@end itemize
+
+@node java.lang.VMDouble, java.lang.VMFloat, java.lang.VMCompiler, java.lang
+@subsection @code{java.lang.VMDouble}
+
+@code{VMDouble} provides native support for the conversion and parsing
+of doubles.
+
+@itemize @bullet
+@item @code{doubleToRawLongBits(double)} -- Converts the double to the IEEE 754
+bit layout, preserving NaNs.
+@item @code{longBitsToDouble(long)} -- This is the inverse of the last method,
+preserving NaNs so that the output of one can be fed into the other without
+data loss.
+@item @code{toString(double,boolean)} -- Converts the double to a string,
+giving a shorter value if the flag @code{isFloat} is @code{true}, indicating
+that the conversion was requested by @code{java.lang.Float} rather than
+@code{java.lang.Double}.
+@item @code{initIDs} -- Used by JNI-based solutions to initialize the cache
+of the static field IDs.  The default @code{VMDouble} implementation has a
+static initializer which loads the JNI library and calls this method.
+@item @code{parseDouble} -- Turn the string into a usable double value.
+@end itemize
+
+Classpath provides native implementations of all these, making VM
+implementation optional.
+
+@node java.lang.VMFloat, java.lang.VMProcess, java.lang.VMDouble, java.lang
+@subsection @code{java.lang.VMFloat}
+
+@code{VMFloat} provides native support for the conversion of floats.
+
+@itemize @bullet
+@item @code{floatToRawIntBits(float)} -- Converts the float to the IEEE 754
+bit layout, preserving NaNs.
+@item @code{intBitsToFloat(int)} -- This is the inverse of the last method,
+preserving NaNs so that the output of one can be fed into the other without
+data loss.
+@end itemize
+
+Classpath provides native implementations of all these, making VM
+implementation optional.
+
+@node java.lang.VMProcess, java.lang.VMRuntime, java.lang.VMFloat, java.lang
+@subsection @code{java.lang.VMProcess}
+
+@code{VMProcess} handles the execution of external processes.  In the
+default implementation, threads are spawned and reaped by @code{ProcessThread}.
+A constructor creates a new @code{VMProcess}, which extends rather than
+complements @code{Process}, using an array of arguments, an array of
+environment variables and a working directory.  The instance maintains
+system input, output and error streams linked to the external process.
+Three @code{native} methods are used, and implementations are provided
+for all three by Classpath, making VM implementation optional.  These use
+the POSIX functions, @code{fork()}, @code{waitpid()} and @code{kill()}.
+
+@itemize @bullet
+@item @code{nativeSpawn(String[],String[],File,boolean)} -- The VM should
+create a new process which uses the specified command-line arguments,
+environment variables and working directory.  Unlike the other two
+methods, this method is linked to an instance, and must call
+@code{setProcessInfo()} with the results before returning.  The
+boolean argument maps to the @code{redirectErrorStream} property of
+@code{java.lang.ProcessBuilder}.  When true, the output and error streams
+are merged.
+@item @code{nativeReap()} -- This is called to perform a reap of any
+zombie processes, and should not block, instead returning a boolean as to
+whether reaping actually took place.
+@item @code{nativeKill(long)} -- The VM should terminate the specified PID.
+@end itemize
+
+@node java.lang.VMRuntime, java.lang.VMString, java.lang.VMProcess, java.lang
+@subsection @code{java.lang.VMRuntime}
+
+The @code{VMRuntime} class provides a series of native methods
+which divulge information about the runtime or invoke certain
+operations.  This includes retrieving the amount of available memory,
+and scheduling the garbage collector.  There are two exceptions: the
+@code{enableShutdownHooks} method, which allows the VM to put in its own
+shutdown hooks when @code{Runtime.addShutdownHook()} is first invoked,
+and @code{exec(String[],String[],File)} which spawns an external process.
+These are Java-based static methods instead.  The first is simply a stub by
+default, while the second simply links to the functionality of
+@code{VMProcess} (and should be changed if a different @code{Process}
+implementation is used).
+
+@itemize @bullet
+@item @code{availableProcessors()} -- Returns the number of processors 
+available to the VM.
+@item @code{freeMemory()} -- Returns the amount of memory the VM has available
+on the heap for allocating.
+@item @code{totalMemory()} -- Returns the size of the heap.
+@item @code{maxMemory()} -- Returns the maximum memory block the VM will
+attempt to allocate.  May be simply @code{Long.MAX_VALUE} (8 exabytes!)
+@item @code{gc()} -- Allows users to explicitly invoke the garbage collector.
+This is a suggestion to the VM, rather than a command, and the garbage
+collector should run anyway @emph{without} it being invoked.
+@item @code{runFinalization()} -- Like the above, but related to the
+finalilzation of objects rather than the garbage collector.
+@item @code{runFinalizationForExit()} -- Called immediately prior to VM
+shutdown in order to finalize all objects (including `live' ones)
+@item @code{traceInstructions(boolean)} -- This turns on and off the optional
+VM functionality of printing a trace of executed bytecode instructions.
+@item @code{traceMethodCalls(boolean)} -- This turns on and off the optional
+VM functionality of printing a trace of methods called.
+@item @code{runFinalizersOnExit(boolean)} -- A toggleable setting for
+running the finalization process at exit.
+@item @code{exit(int)} -- The VM should shutdown with the specified exit code.
+@item @code{nativeLoad(String,ClassLoader)} -- Attempts to load a file,
+returning an integer which is non-zero for success.  Nothing happens if the
+file has already been loaded.
+@item @code{mapLibraryName(String)} -- The VM should map the system-independent
+library name supplied to the platform-dependent equivalent (e.g.@: a @code{.so}
+or @code{.dll} file)
+@end itemize
+
+@node java.lang.VMString, java.lang.VMThread, java.lang.VMRuntime, java.lang
+@subsection @code{java.lang.VMString}
+@code{VMString} is responsible for handling interned strings.  If two strings
+are equal (using the @code{equals()} method), then the results of calling
+the @code{intern()} method on each of them makes them equal
+(using @code{==}).  Thus, the same string object is always returned by
+@code{intern} if the two strings are equal.  The default implementation
+is Java-based and implements @code{intern(String)} by maintaining a
+@code{WeakHashMap} which links the strings to their @code{WeakReference}.
+A new mapping is created for each new string being @code{intern}ed.  
+A VM may implement this differently by implementing this method,
+which is @code{static} and the only one in @code{VMString}.
+
+@node java.lang.VMThread, java.lang.VMMath, java.lang.VMString, java.lang
+@subsection @code{java.lang.VMThread}
+
+@code{VMThread} provides the link between Java's threads and the platform
+threading support.  A @code{VMThread} is created via a private constructor
+and linked to a @code{Thread} instance.  This occurs when the @code{Thread}
+instance is started by the static @code{create(Thread,long)} method (the second
+argument requests a certain stack size, usually zero).  The thread itself is
+executed via the @code{run()} method, which handles any problems with the
+running of the thread and its eventual death.
+
+@code{VMThread} provides the following accessors and mutators for accessing
+the thread state via @code{VMThread},
+
+@itemize @bullet
+@item @code{getName()}
+@item @code{setName(String)}
+@item @code{getPriority()}
+@item @code{setPriotity(int)}
+@item @code{isDaemon()}
+@end itemize
+
+all of which refer to the @code{Thread} instance. @code{setPriority(int)} also
+calls the appropriate native method.  @code{stop(Throwable)} similarly wraps
+a native method, merely adding in a check for the state of the thread.
+
+The default implementation also provides Java-based implementations of
+@code{join(long,int)}, @code{sleep(long,int)} and
+@code{holdsLock(Object)}.  @code{join} and @code{sleep} simply wait for
+the appropriate amount of time, with @code{join} additionally waiting
+for the thread instance to become @code{null}.  @code{holdsLock} simply
+checks if an object is locked by the current thread by trying to invoke
+the @code{notify} method, and catching the failing exception if this is
+not the case.
+
+The remainder of the class is a series of @code{native} methods, some of
+which are mandatory for VM implementation and others which provide optional
+or deprecated functionality.
+
+@itemize @bullet
+@item Mandatory Instance Methods
+@itemize @bullet
+@item @code{start(long)} -- The VM should create the native thread and start
+it running using the @code{run} method of the @code{VMThread} instance on
+which this method is called.
+@item @code{interrupt()} -- The VM should interrupt the running thread and
+throw an appropriate exception.
+@item @code{isInterrupted()} -- Checks the interrupted state of the thread.
+@item @code{suspend()} -- The thread should be suspended until resumed.
+@item @code{resume()} -- The thread should be resumed from its suspended state.
+This pair of methods are deprecated, due to the possibility of a deadlock
+occurring when a thread with locks is suspended.
+@item @code{nativeSetPriority(int)} -- Called by @code{setPriority}
+to allow the setting to flow down to the native thread.
+@item @code{nativeStop(Throwable)} -- The VM should stop the thread abnormally
+and throw the specified exception.  This is clearly deprecated, due to the
+ambiguous state an abruptly-stopped thread may leave.
+@item @code{getState()} -- Returns the VM's impression of the current state
+of the thread.  The applicable states are supplied by the @code{State}
+enumeration in @code{java.lang.Thread}.
+@end itemize
+@item Mandatory Class Methods
+@itemize @bullet
+@item @code{currentThread()} -- Return a reference to the thread currently
+being executed.
+@item @code{yield()} -- The VM should allow some other thread to run.
+The current thread maintains its locks even though it stops executing for
+the time being.
+@item @code{interrupted()} -- A shortcut to obtaining the interrupted state
+of the current thread.
+@end itemize
+@item Other Methods
+@itemize @bullet
+@item @code{countStackFrames()} -- Returns a count of the number of stack
+frames in the thread.  This depends on the deprecated method @code{suspend()}
+having returned true, and is thus deprecated as a result.
+@end itemize
+@end itemize
+
+@node java.lang.VMMath,, java.lang.VMThread, java.lang
+@subsection @code{java.lang.VMMath}
+
+The @code{VMMath} class provides a series of native methods
+for some of the mathematical functions present in @code{java.lang.Math}.
+Classpath provides a default implementation of these which maps the
+functions to those provided by @code{fdlibm}.  VM implementors are welcome
+to replace this with more efficient implementations, as long as the accuracy
+contract of these methods, specified in @code{java.lang.Math}, is maintained.
+
+@itemize @bullet
+@item 1.0
+@itemize @bullet
+@item @code{sin(double)} -- Returns the sine value for the given angle.
+@item @code{cos(double)} -- Returns the cosine value for the given angle.
+@item @code{tan(double)} -- Returns the tangent value for the given angle.
+@item @code{asin(double)} -- Returns the arc sine value for the given angle.
+@item @code{acos(double)} -- Returns the arc cosine value for the given angle.
+@item @code{atan(double)} -- Returns the arc tangent value for the given angle.
+@item @code{atan2(double,double)} -- Returns the arc tangent of the ratio of
+the two arguments.
+@item @code{exp(double)} -- Returns the exponent raised to the given power.
+@item @code{log(double)} -- Returns the natural logarithm for the given value.
+@item @code{sqrt(double)} -- Returns the square root of the value.
+@item @code{pow(double,double)} -- Returns x to the power of y.
+@item @code{IEEEremainder(double,double)} -- Returns the IEEE 754 remainder
+for the two values.
+@item @code{ceil(double)} -- Returns the nearest integer >= the value.
+@item @code{floor(double)} -- Returns the nearest integer <= the value.
+@item @code{rint(double)} -- Returns the nearest integer or the even one
+if the distance between the two is equal.
+@end itemize
+@item 1.5
+@itemize @bullet
+@item @code{cbrt(double)} -- Returns the cube root of the value.
+@item @code{cosh(double)} -- Returns the hyperbolic cosine value for the given
+angle.
+@item @code{expm1(double)} -- Returns the exponent of the value minus one.
+@item @code{hypot(double,double)} -- Returns the hypotenuse corresponding to
+x and y.
+@item @code{log10(double)} -- Returns the base 10 logarithm of the given value.
+@item @code{log1p(double)} -- Returns the natural logarithm of the value plus
+one.
+@item @code{sinh(double)} -- Returns the hyperbolic sine value for the given
+angle.
+@item @code{tanh(double)} -- Returns the hyperbolic tangent value for the given angle.
+@end itemize
+@end itemize
+
+@node gnu.classpath, java.util, java.lang, Classpath Hooks
+@section @code{gnu.classpath}
+
+The @code{gnu.classpath} package provides Classpath-specific functionality,
+primarily relating to the features in @code{java.lang}.  At present, this
+includes the context of a class (the stack) and the system properties.
+
+@menu
+* gnu.classpath.VMStackWalker::
+* gnu.classpath.VMSystemProperties::
+* gnu.classpath.Unsafe::
+@end menu
+
+@node gnu.classpath.VMStackWalker,gnu.classpath.VMSystemProperties,gnu.classpath,gnu.classpath
+@subsection @code{gnu.classpath.VMStackWalker}
+
+@code{VMStackWalker} provides access to the class context or stack.  The
+default implementation consists of a @code{native} @code{static} method,
+@code{getClassContext()}, which obtains the class context, and two helper
+methods which obtain the calling class (the 3rd element in the context array)
+and its class loader, respectively.
+
+@itemize @bullet
+@item @code{getClassContext()} -- The VM should return an array of
+@code{Class} objects, each of which relates to the method currently being
+executed at that point on the stack.  Thus, the first item (index 0) is the
+class that contains this method.
+@item @code{getCallingClass()} -- A Java-based helper method which returns
+the @code{Class} object which contains the method that called the method
+accessing @code{getCallingClass()}. 
+@item @code{getCallingClassLoader()} -- Like the last, but returning the class
+loader of the class.
+@end itemize
+
+@node gnu.classpath.VMSystemProperties,gnu.classpath.Unsafe,gnu.classpath.VMStackWalker,gnu.classpath
+@subsection @code{gnu.classpath.VMSystemProperties}
+
+@code{VMSystemProperties} allows the VM to hook into the property creation
+process, both before and after the system properties are added by GNU
+Classpath.  The default implementation assumes that the VM will add its
+properties first, by making the pre-initialisation method @code{native},
+and that the Classpath properties may then be altered by a Java-based
+post-initialisation method.
+
+As these methods are called as part of the bootstrap process, caution should
+be used as to what classes are used, and properties should only be set
+using @code{Properties.setProperty()}.  Specifically, I/O classes should be
+avoided at this early stage.
+
+@itemize @bullet
+@item @code{preInit(Properties)} -- Allows the VM to add properties
+@emph{before} the Classpath properties are added. The default implementation
+includes a full list of properties that @emph{must} be added by the VM, but
+additional VM-specific ones may also be added.  
+@item @code{postInit(Properties)} -- Same as the last, but called after the
+Classpath properties have been added.  The main purpose of this is to allow
+the VM to alter the properties added by GNU Classpath to suit it.
+@end itemize
+
+@node gnu.classpath.Unsafe,,gnu.classpath.VMSystemProperties,gnu.classpath
+@subsection @code{gnu.classpath.Unsafe}
+
+The @code{Unsafe} class provides access to some low-level unsafe operations
+as required by the addition of the java.util.concurrent classes.  These
+focus on direct memory access to the fields within the VM and providing
+atomic update methods.
+
+@itemize @bullet
+@item @code{objectFieldOffset(Field)} -- Provides the caller with the memory
+offset of a particular field.
+@item @code{compareAndSwap*(Object,long,*,*)} -- One of these methods is
+provided for each of int, long and Object (hence the *s).  The value of
+a field pointed to by the given Object and offset is compared with the
+first value and replaced with the second if they are the same.  The reason
+for this method is to make this change operation atomic.
+@item @code{put/get*(Object,long,*)} -- These are like the last set of
+methods, handling integers, longs and Objects, but the field is always
+changed on a put.  Different methods are provided for different semantics.
+Ordered variants perform a lazy put, in that the change does not
+immediately propogate to other threads, while the others provide
+volatile or 'normal' semantics.
+@item @code{arrayBaseOffset(Class)} and @code{arrayIndexScale(Class)} --
+These two methods allow an array class to be traversed by pointer
+arithmetic, by gaining the address of the first element and then
+scaling appropriately for the later ones.
+@item @code{park(boolean,long)} and @code{unpark(Thread)} -- These methods
+block and unblock threads respectively, with an optional timeout being
+provided for the blocking.  @code{unpark} is unsafe as the thread may have
+been destroyed by native code. 
+@end itemize
+
+@node java.util, java.io, gnu.classpath, Classpath Hooks
+@section java.util
+
+The @code{java.util} VM hooks provide links between the mix of functionality
+present in that package, which includes collections, date and time handling
+and parsing.  At present, there is only one hook, which connects GNU Classpath
+to the timezone information provided by the underlying platform.
+
+@menu
+* java.util.VMTimeZone::
+@end menu
+
+@node java.util.VMTimeZone,,java.util,java.util
+@subsection @code{java.util.VMTimeZone}
+
+@code{VMTimeZone} joins @code{TimeZone} to the platform timezone information
+via the static method, @code{getDefaultTimeZoneId()}.  The VM hook is
+expected to return a @code{TimeZone} instance that represents the current
+timezone in use by the platform.  The default implementation provides
+this functionality for POSIX or GNU-like systems, and VMs that want this
+functionality can keep this implementation and implement the native
+method, @code{getSystemTimeZoneId()}.  This method is only called when
+obtaining the timezone name from the @code{TZ} environment variable,
+@code{/etc/timezone} and @code{/etc/localtime} all fail.  This fallback
+mechanism also means that a system which doesn't provide the above three
+methods, but does provide a timezone in string form, can still use this
+implementation.
+
+@node java.io, java.security, java.util, Classpath Hooks
+@section java.io
+
+The @code{java.io} package is heavily reliant on access to the I/O facilities
+of the underlying platform.  As far as its VM hooks go, they provide two
+areas of functionality to GNU Classpath, these being
+
+@itemize @bullet
+@item File and directory queries and manipulation
+@item Serialization of objects
+@end itemize
+
+The first corresponds directly to most of the @code{File} class, while
+the latter underlies the functionality provided by the
+@code{ObjectInputStream} and @code{ObjectOutputStream}.  More low-level I/O
+is provided by @ref{java.nio}.
+
+@menu
+* java.io.VMFile::
+* java.io.VMObjectInputStream::
+* java.io.VMObjectStreamClass::
+@end menu
+
+@node java.io.VMFile,java.io.VMObjectInputStream,java.io,java.io
+@subsection @code{java.io.VMFile}
+
+@code{VMFile} allows GNU Classpath's @code{File} representations to
+probe and modify the file system using the native functions of the
+platform.  The default implementation (which consists of both a
+@code{VMFile} class and the native methods) is primarily UNIX-centric,
+working with POSIX functions and assuming case-sensitive filenames,
+without the restriction of the 8.3 format.  It consists mainly of
+@code{static} @code{native} methods, with a few Java helper methods.
+The native methods represent the file as a string containing its path,
+rather than using the object itself.
+
+@itemize @bullet
+@item Native Methods
+@itemize @bullet
+@item @code{lastModified(String)} -- The native method should return a
+@code{long} value that represents the last modified date of the file.
+@item @code{setReadOnly(String)} -- Sets the file's permissions to read only,
+in whichever way this is realised by the platform.
+@item @code{create(String)} -- Create the named file.
+@item @code{list(String)} -- The native method opens the named directory,
+reads the contents and returns them as a Java @code{String} array.
+@item @code{renameTo(String,String)} -- Renames the first file to the second.
+@item @code{length(String)} -- Returns a @code{long} value representing
+the file size.
+@item @code{exists(String)} -- Tests for the existence of the named file
+or directory.
+@item @code{delete(String)} -- Deletes the file or directory.
+@item @code{setLastModified(String,long)} -- Change the last modified time.
+@item @code{mkdir(String)} -- Creates the named directory.
+@item @code{isFile(String)} -- Tests that the named path references a file.
+@item @code{canWrite(String)} -- Tests that the file can be written to.
+This method is @code{synchronized}, so the object is locked during the check.
+@item @code{canRead(String)} -- Complement of the last method.
+@item @code{isDirectory(String)} -- Tests that the named path references
+a directory.
+@end itemize
+@item Java Helper Methods
+@itemize @bullet
+@item @code{canWriteDirectory(File)} -- Checks that the directory can be
+written to, by trying to create a temporary file in it.
+@item @code{listRoots()} -- Returns the root of a GNU filesystem, i.e.@: `/'
+in an array.
+@item @code{isHidden(String)} -- Checks whether the file starts with `.',
+which is how files are hidden on UNIX-style systems.
+@item @code{getName(String)} -- Pulls the actual filename from the end of
+the path, by breaking off the characters after the last occurrence of the
+platform's file separator.
+@item @code{getCanonicalForm(String)} -- This converts a UNIX path to
+its canonical form by removing the `.' and `..' sections that occur within.
+@end itemize
+@end itemize
+
+@node java.io.VMObjectInputStream,java.io.VMObjectStreamClass,java.io.VMFile,java.io
+@subsection @code{java.io.VMObjectInputStream}
+
+This class consists of two methods which provide functionality used in
+deserializing an object.  @code{currentClassLoader()} provides the first
+user-defined class loader from the class context
+(@xref{gnu.classpath.VMStackWalker},) via a @code{PrivilegedAction}.
+@code{allocateObject(Class,Class,Constructor)} is a @code{native} method
+(a reference implementation is provided) which creates an object but
+calls the constructor of another class, which is a superclass of the
+object's class.
+
+@node java.io.VMObjectStreamClass,,java.io.VMObjectInputStream,java.io
+@subsection @code{java.io.VMObjectStreamClass}
+
+@code{VMObjectStreamClass} is a series of @code{static} @code{native}
+methods that provide some of the groundwork for @code{ObjectStreamClass}
+and @code{ObjectStreamField}.  @code{hasClassInitializer(Class)} works
+with the former, and checks for the presence of a static initializer.
+The remaining methods are of the form @code{setXXXNative(Field,Object,XXX)}
+and support @code{ObjectStreamField}.  One exists for each of the main types
+(boolean, float, double, long, int, short, char, byte and object) and is used
+to set the specified field in the supplied instance to the given value.
+
+A default implementation is provided for all of them, so a VM implementation
+is optional.
+
+@node java.security, java.net, java.io, Classpath Hooks
+@section java.security
+
+The @code{java.security} package provides support for Java's security
+architecture.  
+
+@menu
+* java.security.VMAccessController::
+* java.security.VMSecureRandom::
+@end menu
+
+@node java.security.VMAccessController,java.security.VMSecureRandom,java.security,java.security
+@subsection @code{java.security.VMAccessController}
+
+The @code{AccessController} is used to perform privileged actions.  Its
+hook class, @code{VMAccessController}, maintains the
+@code{AccessControlContext} and the default implementation is purely
+Java-based.  The VM may choose to replace this with their own.
+The methods in the reference version are as follows:
+
+@itemize @bullet
+@item @code{pushContext(AccessControlContext)} -- Adds a new context to the
+stack for the current thread.  This is called before a privileged action
+takes place.
+@item @code{popContext()} -- Removes the top context from the stack.  This
+is performed after the privileged action takes place.
+@item @code{getContext()} -- Either derives a context based on the 
+@code{ProtectionDomain}s of the call stack (see the next method) or returns
+the top of the context stack.
+@item @code{getStack()} -- Provides access to the call stack as a pair of
+arrays of classes and method names.  The actual implementation returns
+an empty array, indicating that there are no permissions.
+@end itemize
+
+@node java.security.VMSecureRandom,,java.security.VMAccessController,java.security
+@subsection @code{java.security.VMSecureRandom}
+
+The @code{VMSecureRandom} class is used to provide access to
+cryptographically secure random numbers.  The default implementation
+of the class runs eight threads that increment counters in a tight
+loop, and XORs each counter to produce one byte of seed data. This is
+not very efficient, and is not guaranteed to be random (the thread
+scheduler is probably deterministic, after all). VM implementors
+should provide a version of this class, which implements the method
+@code{generateSeed(byte[],int,int)}, so that it fills the buffer using
+a random seed from a system facility, such as a system entropy
+gathering device or hardware random number generator.  The parameters
+are the usual set of buffer, offset and length and the method returns
+the number of bytes actually generated, which may be less than that
+requested.
+
+@node java.net, java.nio, java.security, Classpath Hooks
+@section java.net
+
+The @code{java.net} package is heavily reliant on access to the networking
+facilities of the underlying platform.  The VM hooks provide information
+about the available network interfaces, and access to lookup facilities
+for network addresses.
+
+@menu
+* java.net.VMInetAddress::
+* java.net.VMNetworkInterface::
+@end menu
+
+@node java.net.VMInetAddress,java.net.VMNetworkInterface,java.net,java.net
+@subsection @code{java.net.VMInetAddress}
+
+@code{VMInetAddress} is a series of @code{static} @code{native} methods
+which provide access to the platform's lookup facilities.  All the methods
+are implemented by GNU Classpath, making VM implementation optional, and
+are as follows:
+
+@itemize @bullet
+@item @code{getLocalHostname()} -- Wraps the @code{gethostname} function, and
+falls back on `localhost'.
+@item @code{lookupInaddrAny()} -- Returns the value of @code{INADDR_ANY}.
+@item @code{getHostByAddr(byte[])} -- Looks up the hostname based on an IP
+address.
+@item @code{getHostByName(String)} -- The reverse of the last method, it
+returns the IP addresses which the given host name resolves to.
+@end itemize
+
+@node java.net.VMNetworkInterface,,java.net.VMInetAddress,java.net
+@subsection @code{java.net.VMNetworkInterface}
+
+@code{VMNetworkInterface} currently consists of a single @code{static}
+@code{native} method, @code{getInterfaces()}, which retrieves the
+network interfaces available on the underlying platform as a @code{Vector}.
+The current GNU Classpath implementation is a native stub.
+
+@node java.nio, java.nio.channels, java.net, Classpath Hooks
+@section java.nio
+
+The @code{java.nio} package is part of the New I/O framework added in
+Java 1.4.  This splits I/O into the concepts of @emph{buffers},
+@emph{charsets}, @emph{channels} and @emph{selectors}, and
+@code{java.nio} defines the buffer classes.  As far as native and VM
+code is concerned, the new package needs support for low-level efficient
+buffer operations.
+
+@menu
+* java.nio.VMDirectByteBuffer::
+@end menu
+
+@node java.nio.VMDirectByteBuffer,,java.nio,java.nio
+@subsection @code{java.nio.VMDirectByteBuffer}
+
+A @code{ByteBuffer} maintains a buffer of bytes, and allows it to be
+manipulated using primitive operations such as @code{get}, @code{put},
+@code{allocate} and @code{free}.  A direct buffer avoids intermediate
+copying, and uses native data which shouldn't be manipulated by a
+garbage collector.  The VM class consists of @code{static} @code{native}
+methods, all of which are given default implementations by GNU
+Classpath.
+
+@itemize @bullet
+@item @code{init()} -- Creates an instance of an appropriate
+@code{gnu.classpath.RawData} class.  This class is not garbage
+collected, is created natively and is used in the other methods to reference
+the buffered data.
+@item @code{allocate(int)} -- Allocates the memory for the buffer using
+@code{malloc} and returns a reference to the @code{RawData} class.
+@item @code{free(RawData)} -- Frees the memory used by the buffer.
+@item @code{get(RawData,int)}  -- Returns the data at the specified index.
+@item @code{get(RawData,int,byte[],int,int)} -- Copies a section of the
+data into a byte array using @code{memcpy}.
+@item @code{put(RawData,int,byte)} -- Puts the given data in the buffer
+at the specified index.
+@item @code{adjustAddress(RawData,int)} -- Adjusts the pointer into the buffer.
+@item @code{shiftDown(RawData,int,int,int)} -- Moves the content of the buffer
+at an offset down to a new offset using @code{memmove}.
+@end itemize
+ 
+@node java.nio.channels, gnu.java.nio, java.nio, Classpath Hooks
+@section java.nio.channels
+
+Channels provide the data for the buffers with the New I/O packages.
+For example, a channel may wrap a file or a socket.  The VM hooks,
+at the moment, simply allow the channels to be accessed by @code{java.io}
+streams.
+
+@menu
+* java.nio.channels.VMChannels::
+@end menu
+
+@node java.nio.channels.VMChannels,,java.nio.channels,java.nio.channels
+@subsection @code{java.nio.channels.VMChannels}
+
+@code{VMChannels} provides the methods that create the channels or
+streams.  The default implementation is in pure Java and simply wraps
+the channels in standard I/O classes from @code{java.io}.
+
+@itemize @bullet
+@item @code{createStream(Class,Channel)} -- Creates a @code{FileChannel}
+which wraps an instance of the specified stream class, created by reflection.
+This method is private, and is used by the other two.
+@item @code{newInputStream(ReadableByteChannel)} -- Wraps the channel
+in a @code{FileInputStream}.
+@item @code{newOutputStream(WritableByteChannel)} -- Wraps the channel
+in a @code{FileOutputStream}.
+@end itemize
+
+@node gnu.java.nio, java.lang.reflect, java.nio.channels, Classpath Hooks
+@section gnu.java.nio
+
+The @code{gnu.java.nio} class provides Classpath implementations of the
+interfaces provided by @code{java.nio}.  The VM classes provide the native
+support necessary to implement @emph{pipes} and @emph{selectors}.
+
+@menu
+* gnu.java.nio.VMPipe::
+* gnu.java.nio.VMSelector::
+@end menu
+
+@node gnu.java.nio.VMPipe,gnu.java.nio.VMSelector,gnu.java.nio,gnu.java.nio
+@subsection @code{gnu.java.nio.VMPipe}
+
+@code{VMPipe} provides the native functionality for a uni-directional pipe
+between a source and a destination (sink) channel.  It consists of one 
+@code{static} @code{native} method, @code{init(PipeImpl,SelectorProvider)},
+the reference implementation of which is currently a native stub.  Ideally,
+this should initialise the pipe at the native level.
+
+@node gnu.java.nio.VMSelector,,gnu.java.nio.VMPipe,gnu.java.nio
+@subsection @code{gnu.java.nio.VMSelector}
+
+A @code{Selector} selects between multiple @code{SelectableChannel}s based
+on their readiness and a key set.  The VM hook for the Classpath implementation
+of this is @code{VMSelector}, and this allows the actual @code{select()}
+operation to be performed.  This is represented by the @code{static}
+@code{native} method, @code{select(int[],int[],int[],long)}, and a default
+implementation of this is provided.
+
+@node java.lang.reflect, gnu.java.lang, gnu.java.nio, Classpath Hooks
+@section @code{java.lang.reflect}
+@code{java.lang.reflect} provides the interface to Java's reflection
+facilities.  Via reflection, programmers can obtain type information about
+a particular instance at runtime or dynamically create new instances.
+
+@menu
+* java.lang.reflect.VMArray::
+@end menu
+
+@node java.lang.reflect.VMArray,,,java.lang.reflect
+@subsection @code{java.lang.reflect.VMArray}
+
+The @code{VMArray} class provides a hook, @code{createObjectArray},
+which the VM uses to generate a new non-primitive array of a
+particular class and size.  The default implementation simply passes
+the job down to the standard JNI function, @code{NewObjectArray}.
+
+@node gnu.java.lang, gnu.java.lang.management, java.lang.reflect, Classpath Hooks
+@section @code{gnu.java.lang}
+
+@code{gnu.java.lang} provides VM interfaces for the GNU
+implementations of features in java.lang.  Currently, this includes the
+implementation of instrumentation.
+
+@menu
+* gnu.java.lang.VMInstrumentationImpl::
+@end menu
+
+@node gnu.java.lang.VMInstrumentationImpl,,,gnu.java.lang
+@subsection @code{gnu.java.lang.VMInstrumentationImpl}
+
+The @code{gnu.java.lang.VMInstrumentationImpl} and
+@code{gnu.java.lang.InstrumentationImpl} classes provide an implementation of the
+@code{java.lang.instrument.Instrument} interface. 
+A @code{InstrumentationImpl} object should be created by the VM when agents
+are given in the command line (see the @code{java.lang.instrument} package
+documentation). The VM has to set the static field
+@code{VMClassLoader.instrumenter} to this object. The VM should implement the
+static native methods of the @code{VMInstrumentationImpl} class.
+
+@itemize @bullet
+@item @code{isRedefineClassesSupported()} -- Returns true if the JVM supports
+class redefinition.
+@item @code{redefineClasses()} -- Gives a set of classes with new bytecodes.
+The VM must redefine the classes by reading the new bytecodes.
+@item @code{getAllLoadedClass()} -- Returns an array of all loaded classes.
+@item @code{getInitiatedClass()} -- Returns an array of all classes loaded
+by a specific class loader.
+@item @code{getObjectSize()} -- Gives the size of an object.
+@end itemize
+
+Instrumentation allows to modify the bytecode of a class before it gets read
+by the VM@. In GNU Classpath, the @code{ClassLoader.defineClass} method calls
+the @code{VMClassLoader.defineClassWithTransformers} method which first checks
+if @code{VMClassLoader.instrumenter} is @code{null}. If it's the case, it
+directly calls @code{VMClassLoader.defineClass}. If it's not the case, the
+method calls at first the @code{InstrumentationImpl.callTransformers} method,
+which calls each transformer registered to the @code{InstrumentationImpl}
+object and returns a new bytecode array. Then, it calls the
+@code{VMClassLoader.defineClass} method with this new bytecode array.
+
+The second use of instrumentation is to redefine a class after it has been
+loaded by the VM@. This is done in the Java application by calling the
+@code{Instrumentation.redefineClasses} method of the standard interface on
+a @code{Instrumentation} object. The @code{InstrumentationImpl.redefineClasses}
+method calls the @code{VMInstrumentationImpl.redefineClasses} native method
+which must be implemented by the VM@. The implementation should call the
+@code{InstrumentationImpl.callTransformers} method.
+
+@node gnu.java.lang.management, java.lang.management, gnu.java.lang, Classpath Hooks
+@section @code{gnu.java.lang.management}
+
+@code{gnu.java.lang.management} provides the VM interfaces for the GNU
+implementations of the management beans.  
+
+@menu
+* gnu.java.lang.management.VMRuntimeMXBeanImpl::
+* gnu.java.lang.management.VMClassLoadingMXBeanImpl::
+* gnu.java.lang.management.VMThreadMXBeanImpl::
+* gnu.java.lang.management.VMMemoryMXBeanImpl::
+* gnu.java.lang.management.VMCompilationMXBeanImpl::
+* gnu.java.lang.management.VMMemoryPoolMXBeanImpl::
+* gnu.java.lang.management.VMMemoryManagerMXBeanImpl::
+* gnu.java.lang.management.VMGarbageCollectorMXBeanImpl::
+@end menu
+
+@node gnu.java.lang.management.VMRuntimeMXBeanImpl,gnu.java.lang.management.VMClassLoadingMXBeanImpl,,gnu.java.lang.management
+@subsection @code{gnu.java.lang.management.VMRuntimeMXBeanImpl}
+
+The @code{gnu.java.lang.management.RuntimeMXBeanImpl} provides an
+implementation of the @code{java.lang.management.RuntimeMXBean} interface,
+and is supported by VM functionality in the form of
+@code{gnu.java.lang.management.VMRuntimeMXBeanImpl}.  This provides a
+series of methods, which should be implemented by the virtual machine
+in order to provide the required information for the bean.  The VM
+methods are generally representative of information that is only
+available from the virtual machine, such as the command-line arguments
+it was given at startup.
+
+The methods are as follows:
+
+@itemize @bullet
+@item @code{(getInputArguments())} -- The VM should supply
+a @code{String} array containing each of the command-line
+arguments, excluding those that are directed at the
+@code{main()} method.  The reference implementation expects
+this to be a native method.
+@item @code{(getName())} -- The VM developer should choose
+an appropriate name for the virtual machine.  This name can
+be instance-specific e.g.@: it can include things like the
+process identifier or host name of the machine, which only
+apply to the current running instance.  Thus, the intention is
+that this name refers to the entity that the other information
+refers to, rather than the VM in general.  The reference
+implementation supplies a default concatenation of the VM
+name and version.
+@item @code{(getStartTime())} -- This should return the number
+of milliseconds at which the virtual machine was started.
+The uptime property of the bean is provided relative to this
+value.  Again, the reference implementation also expects
+this method to be native.
+@end itemize
+
+The virtual machine also needs to provide either the
+@code{sun.boot.class.path} or @code{java.boot.class.path}
+property in order to support the optional boot class path
+retrieval functionality.
+
+@node gnu.java.lang.management.VMClassLoadingMXBeanImpl,gnu.java.lang.management.VMThreadMXBeanImpl,gnu.java.lang.management.VMRuntimeMXBeanImpl,gnu.java.lang.management
+@subsection @code{gnu.java.lang.management.VMClassLoadingMXBeanImpl}
+
+The @code{gnu.java.lang.management.ClassLoadingMXBeanImpl} provides an
+implementation of the @code{java.lang.management.ClassLoadingMXBean} interface,
+and is supported by VM functionality in the form of
+@code{gnu.java.lang.management.VMClassLoadingMXBeanImpl}.  This provides a
+series of methods, which should be implemented by the virtual machine
+in order to provide the required information for the bean.  Implementing
+this bean requires the VM to monitor when classes are loaded and unloaded,
+and provide the option of verbose class loading output.
+
+The methods are as follows:
+
+@itemize @bullet
+@item @code{(getLoadedClassCount())} -- This should return
+the number of classes that are currently loaded by the VM.
+@item @code{(getUnloadedClassCount())} -- This should return
+the number of classes that have been loaded by the VM, but
+have since been unloaded.
+@item @code{(isVerbose())} -- This should return @code{true}
+or @code{false}, depending on whether verbose class loading
+output is turned or not, respectively.
+@item @code{(setVerbose(boolean))} -- This should allow the
+verbose class loading output to be turned on and off.
+@end itemize
+
+@node gnu.java.lang.management.VMThreadMXBeanImpl,gnu.java.lang.management.VMMemoryMXBeanImpl,gnu.java.lang.management.VMClassLoadingMXBeanImpl,gnu.java.lang.management
+@subsection @code{gnu.java.lang.management.VMThreadMXBeanImpl}
+
+The @code{gnu.java.lang.management.ThreadMXBeanImpl} provides an
+implementation of the @code{java.lang.management.ThreadMXBean} interface,
+and is supported by VM functionality in the form of
+@code{gnu.java.lang.management.VMThreadMXBeanImpl}.  This provides a
+series of methods, which should be implemented by the virtual machine
+in order to provide the required information for the bean.  Implementing
+this bean requires the VM to monitor thread-related statistics such as
+how often the blocked and waiting states have been entered, as well as
+additional optional support for time and contention monitoring.
+
+Optional support is determined by the following properties:
+
+@itemize @bullet
+@item @code{gnu.java.lang.management.CurrentThreadTimeSupport} --
+This property should be present if the VM supports monitoring the
+time used by the current thread.  If time monitoring for all threads
+is supported, this need not be provided.
+@item @code{gnu.java.lang.management.ThreadTimeSupport} --
+This property should be present if the VM supports monitoring the
+time used by all threads.
+@item @code{gnu.java.lang.management.ThreadContentionSupport} --
+This property should be present if the VM supports thread contention
+monitoring.
+@item @code{gnu.java.lang.management.MonitorUsageMonitoringSupport} --
+This property should be present if the VM supports the monitoring
+of object monitor usage.
+@item @code{gnu.java.lang.management.OwnableSynchronizerUsageMonitoringSupport} --
+This property should be present if the VM supports the monitoring
+of ownable synchronizer usage.
+@end itemize
+
+In addition, the property
+@code{gnu.java.lang.management.ThreadTimeInitallyEnabled} may be
+set to the @code{String} value, @code{"true"}, if time monitoring
+is enabled at startup.
+
+The methods are as follows:
+
+@itemize @bullet
+@item @code{(findDeadlockedThreads())} -- This should return
+an array of thread identifiers which match threads involved in
+deadlock cycles (where each thread is waiting to obtain a lock
+held by one of the others) on object monitors or ownable
+synchronizers.  This is specified as a native method in the
+reference implementation, and is optional.  It is only called
+when the VM supports ownable synchronizer monitoring.
+@item @code{(findMonitorDeadlockedThreads())} -- This should return
+an array of thread identifiers which match threads involved in
+deadlock cycles (where each thread is waiting to obtain a lock
+held by one of the others) on object monitors.  This is specified
+as a native method in the reference implementation.
+@item @code{(getAllThreads())} -- This should return an array of
+all live threads and set the @code{filled} variable to the number
+found.  A default implementation is provided.
+@item @code{(getAllThreadIds())} -- This should return an array of
+all live thread identifiers.  An implementation is provided against
+@code{getAllThreads()} by default.
+@item @code{(getCurrentThreadCpuTime())} -- This should return the
+approximate number of nanoseconds of CPU time the current thread
+has used.  This is an optional native method, which is used by VMs
+supporting time monitoring.
+@item @code{(getCurrentThreadUserTime())} -- This should return the
+approximate number of nanoseconds of user time the current thread
+has used.  This is an optional native method, which is used by VMs
+supporting time monitoring.
+@item @code{(getDaemonThreadCount())} -- This should return the number
+of live daemon threads.  A default implementation is provided, based
+on @code{getAllThreads()}.
+@item @code{(getLockInfo(ThreadInfo))} -- This is an optional native
+method called when the VM supports ownable synchronizer usage monitoring
+and the user has requested information for a particular thread.  The
+supplied @code{ThreadInfo} object should be filled out with an
+array of @code{LockInfo} objects, providing details on each lock. 
+@item @code{(getMonitorInfo(ThreadInfo))} -- This is an optional native
+method called when the VM supports object monitor usage monitoring
+and the user has requested information for a particular thread.  The
+supplied @code{ThreadInfo} object should be filled out with an
+array of @code{MonitorInfo} objects, providing details on each lock. 
+@item @code{(getPeakThreadCount())} -- The VM should maintain a record
+of the peak number of live threads, and return it when this method is
+called.  This is specified as a native method in the reference
+implementation.
+@item @code{(resetPeakThreadCount())} -- This should reset the record
+of the peak number of live threads to the current number of live
+threads.  This is specified as a native method in the reference
+implementation.
+@item @code{(getThreadCount())} -- This should return the number of
+live threads.  A default implementation is provided, based on
+@code{getAllThreads()}.
+@item @code{(getThreadCpuTime(long))} -- This should return the
+approximate number of nanoseconds of CPU time the specified thread
+has used.  This is an optional native method, which is used by VMs
+supporting time monitoring.
+@item @code{(getThreadUserTime(long))} -- This should return the
+approximate number of nanoseconds of CPU time the specified thread
+has used.  This is an optional native method, which is used by VMs
+supporting time monitoring.
+@item @code{(getThreadInfoForId(long, int))} -- This return an instance
+of @code{java.lang.management.ThreadInfo} for the specified thread.
+The class includes a private constructor which VMs should use to initialise
+it with the appropriate values for the thread.  The second argument
+given here specifies the depth of the stack trace supplied on construction
+of the instance.  Special values are 0 (return an empty array) and
+@code{Integer.MAX_VALUE} (return the maximum depth possible).  This
+is specified as a native method in the reference implementation.
+@item @code{(getTotalStartedThreadCount())} -- This should return the
+total number of threads that have been started by the VM, including ones
+that have died.  This is specified as a native method in the reference
+implementation.
+@end itemize
+
+@node gnu.java.lang.management.VMMemoryMXBeanImpl,gnu.java.lang.management.VMCompilationMXBeanImpl,gnu.java.lang.management.VMThreadMXBeanImpl,gnu.java.lang.management
+@subsection @code{gnu.java.lang.management.VMMemoryMXBeanImpl}
+
+The @code{gnu.java.lang.management.MemoryMXBeanImpl} provides an
+implementation of the @code{java.lang.management.MemoryMXBean} interface,
+and is supported by VM functionality in the form of
+@code{gnu.java.lang.management.VMMemoryMXBeanImpl}.  This provides a
+series of methods, which should be implemented by the virtual machine
+in order to provide the required information for the bean.  Implementing
+this bean requires the VM to monitor the levels of heap and non-heap
+memory, and provide the number of objects which are eligible for garbage
+collection.
+
+The methods are as follows:
+
+@itemize @bullet
+@item @code{(getHeapMemoryUsage())} -- This should return
+an instance of @code{java.lang.management.MemoryUsage} with
+values pertaining to the heap.  A default implementation is
+provided, based on @code{java.lang.Runtime}'s methods.
+@item @code{(getNonHeapMemoryUsage())} -- This should return
+an instance of @code{java.lang.management.MemoryUsage} with
+values pertaining to non-heap memory.
+@item @code{(getObjectPendingFinalizationCount())} -- Returns
+the number of objects which are no longer referenced, and which
+will thus be garbage collected on the next run of the garbage
+collector.
+@item @code{(isVerbose())} -- This should return @code{true}
+or @code{false}, depending on whether verbose memory management
+output is turned or not, respectively.
+@item @code{(setVerbose(boolean))} -- This should allow the
+verbose memory management output to be turned on and off.
+@end itemize
+
+@node gnu.java.lang.management.VMCompilationMXBeanImpl,gnu.java.lang.management.VMMemoryPoolMXBeanImpl,gnu.java.lang.management.VMMemoryMXBeanImpl,gnu.java.lang.management
+@subsection @code{gnu.java.lang.management.VMCompilationMXBeanImpl}
+
+The @code{gnu.java.lang.management.CompilationMXBeanImpl} provides an
+implementation of the optional @code{java.lang.management.CompilationMXBean}
+interface, and is supported by VM functionality in the form of
+@code{gnu.java.lang.management.VMCompilationMXBeanImpl}.  This provides a
+single method for returning the number of milliseconds the virtual
+machine's Just-In-Time (JIT) compiler has spent compiling.  Even if
+a JIT compiler is available and an instance of the bean supplied, this
+method is still optional.
+
+Optional support is determined by the following properties:
+
+@itemize @bullet
+@item @code{gnu.java.lang.compiler.name} -- This property should
+specify the name of the JIT compiler.  Classpath also uses this,
+within @code{java.lang.management.ManagementFactory}, to determine
+whether a bean should be created.  If this property is set to a
+non-null value, a bean will be created and its @code{getName()}
+method will return this value.
+@item @code{gnu.java.lang.management.CompilationTimeSupport} --
+This property should be present if the VM supports monitoring the
+time spent compiling.
+@end itemize
+
+Time support is implemented by the following method:
+
+@itemize @bullet
+@item @code{(getTotalCompilationTime())} -- This should return the
+number of milliseconds the JIT compiler has spent compiling.
+@end itemize
+
+@node gnu.java.lang.management.VMMemoryPoolMXBeanImpl,gnu.java.lang.management.VMMemoryManagerMXBeanImpl,gnu.java.lang.management.VMCompilationMXBeanImpl,gnu.java.lang.management
+@subsection @code{gnu.java.lang.management.VMMemoryPoolMXBeanImpl}
+
+The @code{gnu.java.lang.management.MemoryPoolMXBeanImpl} provides an
+implementation of the optional @code{java.lang.management.MemoryPoolMXBean}
+interface, and is supported by VM functionality in the form of
+@code{gnu.java.lang.management.VMMemoryPoolMXBeanImpl}.  Providing
+this interface requires implementing a number of methods for each supported
+pool.  These return statistics on memory usage, and, optionally, allows
+monitoring of when memory usage exceeds a preset threshold.
+
+Optional support is determined by the following properties:
+
+@itemize @bullet
+@item @code{gnu.java.lang.management.CollectionUsageThresholdSupport} --
+This property should be present if the VM supports setting a collection
+usage threshold and monitoring when it is matched or exceeded.  Collection
+usage thresholds are related to the remaining memory usage following a
+garbage collection cycle.
+@item @code{gnu.java.lang.management.UsageThresholdSupport} --
+This property should be present if the VM supports setting a 
+usage threshold and monitoring when it is matched or exceeded.  
+@end itemize
+
+The methods are as follows (all take a pool name as their
+first parameter):
+
+@itemize @bullet
+@item @code{(getCollectionUsage(String))} -- Returns a
+@code{java.lang.management.MemoryUsage} object, containing the
+memory usage statistics following a garbage collection cycle
+for the specified pool.  This may also return @code{null} if
+the pool isn't an appropriate pool for this particular task.
+@item @code{(getCollectionUsageThreshold(String))} -- Returns
+the pool's collection usage threshold, if supported.
+@item @code{(getCollectionUsageThresholdCount(String))} -- Returns
+the number of times the specified pool has matched or exceeded
+its collection usage threshold, if supported.
+@item @code{(getMemoryManagerNames(String))} -- Returns a list
+of names of memory managers which manage the specified pool.
+@item @code{(getPeakUsage(String))} -- Returns a
+@code{java.lang.management.MemoryUsage} object for the peak
+usage level of the specified pool.
+@item @code{(getType(String))} -- Returns a string containing
+either @code{"HEAP"} or @code{"NON_HEAP"} which indicates the type of
+memory used by the specified pool.
+@item @code{(getUsage(String))} -- Returns a
+@code{java.lang.management.MemoryUsage} object for the current
+usage level of the specified pool.
+@item @code{(getUsageThreshold(String))} -- Returns
+the pool's usage threshold, if supported.
+@item @code{(getUsageThresholdCount(String))} -- Returns
+the number of times the specified pool has matched or exceeded
+its usage threshold, if supported.
+@item @code{(isValid(String))} -- Returns true if the pool
+is still in use by the virtual machine.
+@item @code{(resetPeakUsage(String))} -- Resets the peak usage
+levels to the current usage levels for the specified pool.
+@item @code{(setCollectionUsageThreshold(String, long))} -- Sets
+the pool's collection usage threshold, if supported.
+@item @code{(setUsageThreshold(String, long))} -- Sets
+the pool's usage threshold, if supported.
+@end itemize
+
+@node gnu.java.lang.management.VMMemoryManagerMXBeanImpl,gnu.java.lang.management.VMGarbageCollectorMXBeanImpl,gnu.java.lang.management.VMMemoryPoolMXBeanImpl,gnu.java.lang.management
+@subsection @code{gnu.java.lang.management.VMMemoryManagerMXBeanImpl}
+
+The @code{gnu.java.lang.management.MemoryManagerMXBeanImpl} provides an
+implementation of the optional @code{java.lang.management.MemoryManagerMXBean}
+interface, and is supported by VM functionality in the form of
+@code{gnu.java.lang.management.VMMemoryManagerMXBeanImpl}.  Providing
+this interface requires implementing two methods (each takes the name
+of the manager as the first argument):
+
+@itemize @bullet
+@item @code{(getMemoryPoolNames(String))} -- Returns a list of the
+memory pools that the manager maintains.  A default implementation
+which scans the results of @code{getMemoryManagerNames()} for each
+pool is provided.
+@item @code{(isValid(String))} -- Returns true if the specified
+manager is still valid, i.e., it is still in use by the virtual machine.
+@end itemize
+
+@node gnu.java.lang.management.VMGarbageCollectorMXBeanImpl,,gnu.java.lang.management.VMMemoryManagerMXBeanImpl,gnu.java.lang.management
+@subsection @code{gnu.java.lang.management.VMGarbageCollectorMXBeanImpl}
+
+The @code{gnu.java.lang.management.GarbageCollectorMXBeanImpl} provides an
+implementation of the optional @code{java.lang.management.GarbageCollectorMXBean}
+interface, and is supported by VM functionality in the form of
+@code{gnu.java.lang.management.VMGarbageCollectorMXBeanImpl}.  Providing
+this interface requires implementing two methods (each takes the name
+of the garbage collector as the first argument):
+
+@itemize @bullet
+@item @code{(getCollectionCount(String))} -- Returns the number of
+times the specified garbage collector has run.
+@item @code{(getCollectionTime(String))} -- Returns the accumulated
+number of milliseconds for which the garbage collector has run.
+@end itemize
+
+Note that each garbage collector is also a memory manager, and so an
+implementation of the @code{gnu.java.lang.management.VMMemoryManagerMXBeanImpl}
+methods for its name should also be provided.
+
+@node java.lang.management, Classpath Callbacks, gnu.java.lang.management, Classpath Hooks
+@section @code{java.lang.management}
+
+@code{gnu.java.lang.management} provides the VM interfaces for the GNU
+implementations of the management beans.  
+
+@menu
+* java.lang.management.VMManagementFactory::
+@end menu
+
+@node java.lang.management.VMManagementFactory,,,java.lang.management
+@subsection @code{java.lang.management.VMManagementFactory}
+
+This VM interface provides the names of the memory pools, memory managers
+and garbage collectors for use by the @code{java.lang.management.ManagementFactory}
+in creating lists of appropriate beans for these types of managed object.
+
+The methods are as follows:
+
+@itemize @bullet
+@item @code{(getMemoryPoolNames())} -- Returns a list of the names
+of the current memory pools in use by the virtual machine.
+@item @code{(getMemoryManagerNames())} -- Returns a list of the names
+of the current memory managers in use by the virtual machine.  This
+should not include those that are also garbage collectors.
+@item @code{(getGarbageCollectorNames())} -- Returns a list of the names
+of the current garbage collectors in use by the virtual machine.
+@end itemize
+
+@node Classpath Callbacks, , java.lang.management, Classpath Hooks
+Some of the classes you implement for the VM will need to call back to
+package-private methods in Classpath:
+
+@itemize @bullet
+@item @code{java.lang.ThreadGroup.addThread(Thread)}
+Call this method from @code{Thread} when a new @code{Thread} is created, to add it to
+the group.
+
+@item @code{java.lang.ThreadGroup.removeThread(Thread)}
+Call this method from @code{Thread} when a @code{Thread} is stopped or destroyed.
+
+@item @code{gnu.java.lang.management.MemoryMXBeanImpl.fireThresholdExceededNotification(String, long, long, long, long)}
+If the monitoring of memory usage thresholds is supported, this method
+should be called when the normal usage of a memory pool crosses the
+threshold, in order to emit a notification.  Another notification
+should not be emitted until there is an intermittent period where the
+usage is again below the threshold.  The parameters are the memory
+pool name, the usage levels (init, used, committed and max) and the
+number of times the threshold has been crossed.
+
+@item @code{gnu.java.lang.management.MemoryMXBeanImpl.fireCollectionThresholdExceededNotification(String, long, long, long, long)}
+If the monitoring of memory usage thresholds is supported, this method
+should be called when the usage of a memory pool after a garbage
+collection cycle crosses the threshold, in order to emit a
+notification.  Another notification should not be emitted until there
+is an intermittent period where the usage is again below the
+threshold.  The parameters are the memory pool name, the usage levels
+(init, used, committed and max) and the number of times the threshold
+has been crossed.
+
+@end itemize
+
+@node VM Hooks, JNI Implementation, Classpath Hooks, Top
+@comment node-name, next, previous, up
+@chapter VM Hooks
+
+VMs need to do some dirty work; there are some things in the VM that
+unfortunately are dependent on the internal structure of various
+classes.  This is a guide to all of the things the VM itself needs to
+know about classes.
+
+Some of the core classes, while being implemented by GNU Classpath,
+provide space for state (in the form of a @code{vmdata} object) to be
+stored by the VM, and can not be constructed normally.
+
+@itemize @bullet
+@item java.lang.Class
+@item java.lang.ClassLoader
+@end itemize
+
+The default implementations of some VM classes also follow this methodology,
+when it is intended that most VMs will keep the default.
+
+@itemize @bullet
+@item java.lang.VMThread
+@item java.lang.VMThrowable
+@end itemize
+
+Several core classes must be completely implemented by the VM for Classpath to
+work, although reference implementations are provided.  These classes are:
+
+@itemize @bullet
+@item java.lang.reflect.Constructor
+@item java.lang.reflect.Method
+@item java.lang.reflect.Field
+@end itemize
+
+The following issues are of note;
+
+@itemize @bullet
+@item @code{java.lang.Class} @*
+The GNU Classpath implementation of @code{java.lang.Class} provides an
+object for storing the internal state of the class maintained by the VM.
+This is the only known place where this matters.  The class is
+constructed with this data by the VM@.  Some VMs do not create the
+@code{Class} object at the point where the class is defined; instead,
+they wait until a @code{Class} object is actually used.
+
+@item Array Classes @*
+When you are creating an array class, you should set the
+@code{ClassLoader} of the array class to the @code{ClassLoader} of its
+component type.  Whenever you add a class to a @code{ClassLoader}, you
+need to notify the @code{ClassLoader} and add the new @code{Class} to
+its internal cache of classes.  To do this, call
+@code{ClassLoader.addVMCreatedClass(Class)}.  @emph{Note: this is
+written in anticipation of 1.2 support and does not apply just yet.}
+
+@item Primordial Class Loader @*
+When the primordial class loader loads a class, it needs to tell
+Classpath what it has done in order for security stuff to work right.
+To do this, call the static method
+@code{ClassLoader.newPrimordialClass(Class)}.
+
+Even the first few core classes need to do this; in order to do it,
+simply call this method @emph{after} the initial class loading has been
+done.  No harm will come, as long as you follow the guidelines in the
+@pxref{Initialization} section.
+
+@emph{Note: this is written in anticipation of 1.2 support and does not
+apply just yet.}
+
+@item Top-level Exception Handler @*
+Exceptions take care of themselves in Classpath; all you need to do in
+the top-level exception handler is call @code{Throwable.printStackTrace()}.
+
+@item Security and Traces @*
+There will eventually be a feature in the 1.2 security that keeps the
+@code{AccessController} from having to evaluate @emph{all} of the
+@code{ProtectionDomain}s every time a security check is made.  I think a common
+case is a single method doing a lot of things that require security
+checks.  However, I don't want to bog down the method stack too much, so
+this feature of the VM will have the @code{AccessController} for a thread
+calling out to the VM to tell it how high it was on the stack when it
+made the last security request.  Every time the stack goes lower than
+that number, the VM will decrement the number.  The @code{AccessController}
+will remember what the accumulated protection status was at every stack
+level (an @code{AccessControlContext}) and use that aggregated information to
+do the check.  I am not sure, however, whether the savings are
+substantial enough to outweigh the integer check and set after every
+method call.  I will investigate.
+
+@item Threading @*
+I figured I'd put this here because a VM guy might be wondering about it.
+We implement @code{ThreadGroup}, but that class is almost entirely
+VM-independent.  The root @code{ThreadGroup}, a static field called
+@code{ThreadGroup.root}, should be initialized by Classpath, but if you wish to
+reinitialize it yourself, there should be no harm.
+
+@end itemize
+
+@node JNI Implementation, JVMTI Implementation, VM Hooks, Top
+@comment  node-name,  next,  previous,  up
+@chapter JNI Implementation
+
+Classpath comes with its own implementation of @file{jni.h}.  This
+file can be customized by the VM in a few ways, by defining macros
+that affect the interpretation of the file.  These macros are all
+intended for use by a VM which uses GNU Classpath and which wants to
+use a single copy of @file{jni.h} for both internal and external use.
+
+@itemize @bullet
+@item _CLASSPATH_VM_JNI_TYPES_DEFINED
+Some VMs like to define JNI ``object'' types in a special way.  If
+this macro is defined, the Classpath @file{jni.h} will avoid defining
+these types.  By default, these types are defined in @file{jni.h}.
+The full list of types and macros treated this way is: @samp{jobject},
+@samp{jclass}, @samp{jstring}, @samp{jthrowable}, @samp{jweak},
+@samp{jarray}, @samp{jobjectArray}, @samp{jbyteArray},
+@samp{jshortArray}, @samp{jintArray}, @samp{jlongArray},
+@samp{jbooleanArray}, @samp{jcharArray}, @samp{jfloatArray},
+@samp{jdoubleArray}, @samp{JNIEnv}, @samp{JavaVM}, @samp{JNI_TRUE}
+(macro), @samp{JNI_FALSE} (macro).
+
+@item _CLASSPATH_VM_INTERNAL_TYPES_DEFINED
+If the VM has its own definitions for @samp{jfieldID} and
+@samp{jmethodID}, then it should define this macro.  Otherwise,
+@file{jni.h} will provide definitions for these types.
+
+@item _CLASSPATH_JNIIMPEXP
+Three functions -- @samp{JNI_GetDefaultJavaVMInitArgs},
+@samp{JNI_CreateJavaVM}, and @samp{JNI_GetCreatedJavaVMs} -- must be
+marked as @samp{JNIIMPORT} when seen by user code, but most likely
+should be marked as @samp{JNIEXPORT} when defined in the VM
+implementation.  This macro can be defined to one or the other by the
+VM as appropriate.  If this macro is not defined, it defaults to
+@samp{JNIIMPORT}.
+
+@item _CLASSPATH_JNIENV_CONTENTS
+A VM can add fields to the @samp{JNIEnv} structure by defining this to
+be a sequence of field declarations.
+
+@end itemize
+
+@node JVMTI Implementation, Miscellaneous VM Requirements, JNI Implementation, Top
+@comment node-name, next, previous, up
+@chapter JVMTI Implementation
+
+Classpath comes with its own implementation of @file{jvmti.h}.  This
+file can be customized by the VM in a few ways by defining macros that
+affect the interpretation of the file.  These macros are all intended
+for use for use by a VM which uses GNU Classpath and which wants to
+use a single copy of @file{jvmti.h} for both internal and external use.
+
+@itemize @bullet
+@item _CLASSPATH_VM_JVMTI_TYPES_DEFINED
+Some VMs like to define JVMTI ``object'' types in a special way.  If
+this macro is defined, the Classpath @file{jvmti.h} will avoid defining
+these types.  By default these types are defined in @file{jvmti.h}.  
+The full list of types and macros treated this way is: @samp{jthread},
+@samp{jthreadGroup}, @samp{jlocation}, and @samp{jrawMonitorID}.  By
+default @samp{jrawMonitorID} is defined as an opaque pointer which
+must be defined by the VM.
+
+@item _CLASSPATH_JVMTIENV_CONTENTS
+A VM can add fields to the @samp{jvmtiEnv} structure by defining this
+to be a sequence of field declarations.
+
+@end itemize
+
+@node Miscellaneous VM Requirements,  , JVMTI Implementation, Top
+@comment  node-name,  next,  previous,  up
+@chapter Miscellaneous VM Requirements
+
+Classpath places a few requirements on the VM that uses it.
+
+@menu
+* JNI Version::                 
+* VM Threading Model::          
+* Boot Library Path Property::
+@end menu
+
+@node JNI Version, VM Threading Model, Miscellaneous VM Requirements, Miscellaneous VM Requirements
+@comment  node-name,  next,  previous,  up
+@section JNI Version
+
+Classpath currently uses only JNI 1.1, except for one JNI 1.2 function
+in the JNI Invocation API: GetEnv().  And GetEnv() is only used in the
+now deprecated ``portable native sync'' code.
+
+A future direction will probably be to require that all VMs provide
+JNI 1.2.  If this poses problems, please raise them on the classpath
+mailing list. 
+
+@node VM Threading Model, Boot Library Path Property, JNI Version, Miscellaneous VM Requirements
+@comment  node-name,  next,  previous,  up
+@section VM Threading Model
+
+VM authors can implement a number of different threading models. When
+native code is also threaded there is the potential for one threading
+model to deadlock the other. The
+@uref{http://java.sun.com/docs/books/jni/html/other.html#29406,Java
+Native Interface Programmer's Guide and Specification} suggests
+consulting VM documentation in such situations. Classpath uses
+existing libraries, for example the AWT peers can use the GTK+
+graphics library. As these libraries assume a different threading
+model, there is the potential for the native code to deadlock a VM.
+
+The different threading models available to a VM author are:
+@enumerate
+@item
+@i{Native threads}: Map a Java thread to an underlying operating system
+thread (normally a POSIX compatible pthread). This approach reduces
+the potential for deadlock as there is only one thread scheduling
+mechanism.
+@item
+@i{Green threads 1}: Green threads are threads scheduled by the VM,
+typically by switching swapping registers. In early VMs green threads
+were seen as advantageous as they didn't require the operating system
+to reschedule, save and swap all of a threads registers. The green
+thread 1 model switches thread on an externally created event, such as
+a timer interrupt. An example of a VM using this approach is Kaffe
+configured with its jthreads model.
+@item
+@i{Green threads 2}: The essential difference with this model is to
+not switch threads on an event, but at fixed points in the code being
+executed by the VM@. Points chosen could be backward branches (loops)
+or method calls. This approach can be advantageous to nonconservative
+garbage collectors, as non-running threads would be at known points
+and can have fixed register maps. It can also reduce the number of
+registers it is necessary to swap when switching threads.
+@item
+@i{M:N threading}: a flaw to green threading is that it is unable to
+use multiple processors. @i{M}:@i{N} threading fixes this problem by
+running groups of green threads on multiple underlying native
+threads. An example of a VM using this approach is the Jikes RVM,
+which uses @i{M}:@i{N} threading combined with the green thread 2
+model.
+@end enumerate
+
+An example of the problem of mixing threading models is:
+@itemize @bullet
+@item
+A Java thread calls a native method. The native method acquires a lock.
+@item
+The native method calls back into the VM.
+@item
+An event triggers the VM to reschedule the currently running thread.
+@item
+A new VM thread, executing on the same underlying native thread, calls
+a native method.
+@item
+The native method tries to acquire the lock already acquired earlier. As
+the lock is busy the thread waits and allows the operating system to
+reschedule native threads.
+@item
+The operating system reschedules the VM thread again, but the lock is
+still busy and in some threading models will remain busy forever
+(the VM is deadlocked).
+@end itemize
+
+VMs that don't use the underlying operating system thread scheduling
+mechanism need to avoid deadlock. One now deprecated approach was to
+build Classpath and VMs on top of a wrapper thread library (aka
+portable native sync). The wrapper thread library used was GLIB's
+@dfn{gthreads}. This approach has been deprecated because:
+@enumerate
+@item
+The wrapper library is only in use by some native libraries. For
+example, GTK+ uses the gthread library but QT does not.
+@item
+The wrapper library can't be in use prior to the VM starting as the VM
+must replace the wrapper libraries functions with its own. This
+prevents the VM from running as a plugin in an application that
+already uses the wrapper library.
+@end enumerate
+
+An alternative approach is for the VM to detect deadlocked native code
+and swap Java threads off of that native thread. The VM can't,
+however, swap two blocked native threads that are potentially
+deadlocking each other on a lock. The lock will be associated with the
+native thread. To prevent this from happening the VM must hijack
+functions that operate on locks. This is done by redefining the lock
+functions inside the VM and configuring the linker so that it uses the
+VMs symbol in preference to that of the external thread support
+library. The VM's lock function can then reschedule Java threads if it
+must wait for the lock.
+
+@node Boot Library Path Property,  , VM Threading Model, Miscellaneous VM Requirements
+@comment  node-name,  next,  previous,  up
+@section Boot Library Path Property
+
+As of GNU Classpath 0.15 a system property named @code{gnu.classpath.boot.library.path}
+can be set by the VM to specify the directories which contain GNU Classpath's native
+libraries. Usually this value is given at configuration time and is then hardcoded
+in the VM@. However for development purposes it is handy to switch to another installation
+by overriding the properties' value on the command line.
+
+A VM that does not support this feature can simply ignore the property.
+
+For compatibility reasons we suggest to set the default value of @code{java.library.path}
+to the value of the @code{LD_LIBRARY_PATH} environment if it exists on your platform.
+
+@bye
+
+
+
diff --git a/libjava/classpath/doc/gappletviewer.1 b/libjava/classpath/doc/gappletviewer.1
new file mode 100644
index 000000000..9c4b10ec8
--- /dev/null
+++ b/libjava/classpath/doc/gappletviewer.1
@@ -0,0 +1,240 @@
+.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings.  \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
+.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
+.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
+.\" nothing in troff, for use with C<>.
+.tr \(*W-
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+.    ds -- \(*W-
+.    ds PI pi
+.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
+.    ds L" ""
+.    ds R" ""
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds -- \|\(em\|
+.    ds PI \(*p
+.    ds L" ``
+.    ds R" ''
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.ie \nF \{\
+.    de IX
+.    tm Index:\\$1\t\\n%\t"\\$2"
+..
+.    nr % 0
+.    rr F
+.\}
+.el \{\
+.    de IX
+..
+.\}
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
+.    \" fudge factors for nroff and troff
+.if n \{\
+.    ds #H 0
+.    ds #V .8m
+.    ds #F .3m
+.    ds #[ \f1
+.    ds #] \fP
+.\}
+.if t \{\
+.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+.    ds #V .6m
+.    ds #F 0
+.    ds #[ \&
+.    ds #] \&
+.\}
+.    \" simple accents for nroff and troff
+.if n \{\
+.    ds ' \&
+.    ds ` \&
+.    ds ^ \&
+.    ds , \&
+.    ds ~ ~
+.    ds /
+.\}
+.if t \{\
+.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+.    \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+.    \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+.    \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+.    ds : e
+.    ds 8 ss
+.    ds o a
+.    ds d- d\h'-1'\(ga
+.    ds D- D\h'-1'\(hy
+.    ds th \o'bp'
+.    ds Th \o'LP'
+.    ds ae ae
+.    ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "GAPPLETVIEWER 1"
+.TH GAPPLETVIEWER 1 "2013-04-12" "0.99-pre" "GNU"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH "NAME"
+gappletviewer \- Load and runs an applet
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+appletviewer [\fI\s-1OPTION\s0\fR]... \fI\s-1URL\s0\fR...
+.PP
+appletviewer [\fI\s-1OPTION\s0\fR]... \fB\-code\fR \fI\s-1CODE\s0\fR
+.PP
+appletviewer [\fI\s-1OPTION\s0\fR]... \fB\-plugin\fR \fI\s-1INPUT\s0\fR,\fI\s-1OUTPUT\s0\fR
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+The \fBappletviewer\fR tool loads and runs an applet.
+.PP
+Use the first form to test applets specified by tag.  The \s-1URL\s0 should
+resolve to an \s-1HTML\s0 document from which the \fBappletviewer\fR will
+extract applet tags.  The \s-1APPLET\s0, \s-1EMBED\s0 and \s-1OBJECT\s0 tags are supported.
+If a given document contains multiple applet tags, all the applets
+will be loaded, with each applet appearing in its own window.
+Likewise, when multiple URLs are specified, each applet tag instance
+is given its own window.  If a given document contains no recognized
+tags the \fBappletviewer\fR does nothing.
+.PP
+.Vb 1
+\&        appletviewer http://www.gnu.org/software/classpath/
+.Ve
+.PP
+Use the second form to test an applet in development.  This form
+allows applet tag attributes to be supplied on the command line.  Only
+one applet may be specified using the \fB\-code\fR option.  The
+\&\fB\-code\fR option overrides the \s-1URL\s0 form \*(-- any URLs specified will
+be ignored.
+.PP
+.Vb 1
+\&        appletviewer \-code Test.class \-param datafile,data.txt
+.Ve
+.PP
+\&\fBgcjwebplugin\fR uses the third form to communicate with the
+\&\fBappletviewer\fR through named pipes.
+.SH "OPTIONS"
+.IX Header "OPTIONS"
+\&\s-1URL\s0 \s-1OPTIONS\s0
+.IP "\fB\-debug\fR" 4
+.IX Item "-debug"
+This option is not yet implemented but is provided for compatibility.
+.IP "\fB\-encoding\fR \fI\s-1CHARSET\s0\fR" 4
+.IX Item "-encoding CHARSET"
+Use this option to specify an alternate character encoding for the
+specified \s-1HTML\s0 page.
+.PP
+\&\s-1APPLET\s0 \s-1TAG\s0 \s-1OPTIONS\s0
+.IP "\fB\-code\fR \fI\s-1CODE\s0\fR" 4
+.IX Item "-code CODE"
+Use the \fB\-code\fR option to specify the value of the applet tag
+\&\fI\s-1CODE\s0\fR attribute.
+.IP "\fB\-codebase\fR \fI\s-1CODEBASE\s0\fR" 4
+.IX Item "-codebase CODEBASE"
+Use the \fB\-codebase\fR option to specify the value of the applet tag
+\&\fI\s-1CODEBASE\s0\fR attribute.
+.IP "\fB\-archive\fR \fI\s-1ARCHIVE\s0\fR" 4
+.IX Item "-archive ARCHIVE"
+Use the \fB\-archive\fR option to specify the value of the applet tag
+\&\fI\s-1ARCHIVE\s0\fR attribute.
+.IP "\fB\-width\fR \fI\s-1WIDTH\s0\fR" 4
+.IX Item "-width WIDTH"
+Use the \fB\-width\fR option to specify the value of the applet tag
+\&\fI\s-1WIDTH\s0\fR attribute.
+.IP "\fB\-height\fR \fI\s-1HEIGHT\s0\fR" 4
+.IX Item "-height HEIGHT"
+Use the \fB\-height\fR option to specify the value of the applet tag
+\&\fI\s-1HEIGHT\s0\fR attribute.
+.IP "\fB\-param\fR \fI\s-1NAME\s0\fR\fB,\fR\fI\s-1VALUE\s0\fR" 4
+.IX Item "-param NAME,VALUE"
+Use the \fB\-param\fR option to specify values for the \fI\s-1NAME\s0\fR
+and \fI\s-1VALUE\s0\fR attributes of an applet \s-1PARAM\s0 tag.
+.PP
+\&\s-1PLUGIN\s0 \s-1OPTION\s0
+.IP "\fB\-plugin\fR \fI\s-1INPUT\s0\fR\fB,\fR\fI\s-1OUTPUT\s0\fR" 4
+.IX Item "-plugin INPUT,OUTPUT"
+\&\fBgcjwebplugin\fR uses the \fB\-plugin\fR option to specify the
+named pipe the \fBappletviewer\fR should use for receiving commands
+(\fI\s-1INPUT\s0\fR) and the one it should use for sending commands to
+\&\fBgcjwebplugin\fR (\fI\s-1OUTPUT\s0\fR).
+.PP
+\&\s-1DEBUGGING\s0 \s-1OPTION\s0
+.IP "\fB\-verbose\fR" 4
+.IX Item "-verbose"
+Use the \fB\-verbose\fR option to have the \fBappletviewer\fR print
+debugging messages.
+.PP
+\&\s-1STANDARD\s0 \s-1OPTIONS\s0
+.IP "\fB\-help\fR" 4
+.IX Item "-help"
+Use the \fB\-help\fR option to have the \fBappletviewer\fR print a
+usage message, then exit.
+.IP "\fB\-version\fR" 4
+.IX Item "-version"
+Use the \fB\-version\fR option to have the \fBappletviewer\fR print
+its version, then exit.
+.IP "\fB\-J\fR\fI\s-1OPTION\s0\fR" 4
+.IX Item "-JOPTION"
+Use the \fB\-J\fR option to pass \fI\s-1OPTION\s0\fR to the virtual machine that
+will run the \fBappletviewer\fR.  Unlike other options, there must
+not be a space between the \fB\-J\fR and \fI\s-1OPTION\s0\fR.
+.SH "BUGS"
+.IX Header "BUGS"
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+.SH "AUTHOR"
+.IX Header "AUTHOR"
diff --git a/libjava/classpath/doc/gjar.1 b/libjava/classpath/doc/gjar.1
new file mode 100644
index 000000000..c82051c5e
--- /dev/null
+++ b/libjava/classpath/doc/gjar.1
@@ -0,0 +1,207 @@
+.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings.  \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
+.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
+.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
+.\" nothing in troff, for use with C<>.
+.tr \(*W-
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+.    ds -- \(*W-
+.    ds PI pi
+.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
+.    ds L" ""
+.    ds R" ""
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds -- \|\(em\|
+.    ds PI \(*p
+.    ds L" ``
+.    ds R" ''
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.ie \nF \{\
+.    de IX
+.    tm Index:\\$1\t\\n%\t"\\$2"
+..
+.    nr % 0
+.    rr F
+.\}
+.el \{\
+.    de IX
+..
+.\}
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
+.    \" fudge factors for nroff and troff
+.if n \{\
+.    ds #H 0
+.    ds #V .8m
+.    ds #F .3m
+.    ds #[ \f1
+.    ds #] \fP
+.\}
+.if t \{\
+.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+.    ds #V .6m
+.    ds #F 0
+.    ds #[ \&
+.    ds #] \&
+.\}
+.    \" simple accents for nroff and troff
+.if n \{\
+.    ds ' \&
+.    ds ` \&
+.    ds ^ \&
+.    ds , \&
+.    ds ~ ~
+.    ds /
+.\}
+.if t \{\
+.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+.    \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+.    \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+.    \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+.    ds : e
+.    ds 8 ss
+.    ds o a
+.    ds d- d\h'-1'\(ga
+.    ds D- D\h'-1'\(hy
+.    ds th \o'bp'
+.    ds Th \o'LP'
+.    ds ae ae
+.    ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "GJAR 1"
+.TH GJAR 1 "2013-04-12" "0.99-pre" "GNU"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH "NAME"
+gjar \- \- Archive tool for Java archives
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+gjar \fB\-ctxui\fR [\fI\s-1OPTIONS\s0\fR] \fIjar-file\fR [\fB\-C\fR \fI\s-1DIR\s0\fR \fI\s-1FILE\s0\fR] \fI\s-1FILE\s0\fR...
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+\&\fBgjar\fR is an implementation of Sun's jar utility that comes with
+the \s-1JDK\s0.
+.PP
+If any file is a directory then it is processed recursively.  The
+manifest file name and the archive file name needs to be specified in
+the same order the \fB\-m\fR and \fB\-f\fR flags are specified.
+.SH "OPTIONS"
+.IX Header "OPTIONS"
+Operation mode:
+.IP "\fB\-c\fR" 4
+.IX Item "-c"
+Create new archive.
+.IP "\fB\-t\fR" 4
+.IX Item "-t"
+List table of contents for archive.
+.IP "\fB\-x\fR" 4
+.IX Item "-x"
+Extract named (or all) files from archive.
+.IP "\fB\-u\fR" 4
+.IX Item "-u"
+Update existing archive.
+.IP "\fB\-i\fR \fI\s-1FILE\s0\fR" 4
+.IX Item "-i FILE"
+Compute archive index.
+.PP
+Operation modifiers:
+.IP "\fB\-f\fR \fI\s-1FILE\s0\fR" 4
+.IX Item "-f FILE"
+Specify archive file name.
+.IP "\fB\-0\fR" 4
+.IX Item "-0"
+Store only; use no \s-1ZIP\s0 compression.
+.IP "\fB\-v\fR" 4
+.IX Item "-v"
+Generate verbose output on standard output.
+.IP "\fB\-M\fR" 4
+.IX Item "-M"
+Do not create a manifest file for the entries.
+.IP "\fB\-m\fR \fImanifest\fR" 4
+.IX Item "-m manifest"
+Include manifest information from specified \fImanifest\fR file.
+.PP
+File name selection:
+.IP "\fB\-C\fR \fI\s-1DIR\s0\fR\fB \fR\fI\s-1FILE\s0\fR" 4
+.IX Item "-C DIR FILE"
+Change to the \fI\s-1DIR\s0\fR and include the following \fI\s-1FILE\s0\fR.
+.IP "\fB\-@\fR" 4
+.IX Item "-@"
+Read the names of the files to add to the archive from stdin.  This
+option is supported only in combination with \fB\-c\fR or \fB\-u\fR.
+Non standard option added in the \s-1GCC\s0 version.
+.PP
+Standard options:
+.IP "\fB\-help\fR" 4
+.IX Item "-help"
+Print help text, then exit.
+.IP "\fB\-version\fR" 4
+.IX Item "-version"
+Print version number, then exit.
+.IP "\fB\-J\fR\fI\s-1OPTION\s0\fR" 4
+.IX Item "-JOPTION"
+Pass argument to the Java runtime.
+.SH "BUGS"
+.IX Header "BUGS"
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fIjava\fR\|(1), ...
+.SH "AUTHOR"
+.IX Header "AUTHOR"
diff --git a/libjava/classpath/doc/gjarsigner.1 b/libjava/classpath/doc/gjarsigner.1
new file mode 100644
index 000000000..74c57306f
--- /dev/null
+++ b/libjava/classpath/doc/gjarsigner.1
@@ -0,0 +1,212 @@
+.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings.  \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
+.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
+.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
+.\" nothing in troff, for use with C<>.
+.tr \(*W-
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+.    ds -- \(*W-
+.    ds PI pi
+.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
+.    ds L" ""
+.    ds R" ""
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds -- \|\(em\|
+.    ds PI \(*p
+.    ds L" ``
+.    ds R" ''
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.ie \nF \{\
+.    de IX
+.    tm Index:\\$1\t\\n%\t"\\$2"
+..
+.    nr % 0
+.    rr F
+.\}
+.el \{\
+.    de IX
+..
+.\}
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
+.    \" fudge factors for nroff and troff
+.if n \{\
+.    ds #H 0
+.    ds #V .8m
+.    ds #F .3m
+.    ds #[ \f1
+.    ds #] \fP
+.\}
+.if t \{\
+.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+.    ds #V .6m
+.    ds #F 0
+.    ds #[ \&
+.    ds #] \&
+.\}
+.    \" simple accents for nroff and troff
+.if n \{\
+.    ds ' \&
+.    ds ` \&
+.    ds ^ \&
+.    ds , \&
+.    ds ~ ~
+.    ds /
+.\}
+.if t \{\
+.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+.    \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+.    \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+.    \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+.    ds : e
+.    ds 8 ss
+.    ds o a
+.    ds d- d\h'-1'\(ga
+.    ds D- D\h'-1'\(hy
+.    ds th \o'bp'
+.    ds Th \o'LP'
+.    ds ae ae
+.    ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "GJARSIGNER 1"
+.TH GJARSIGNER 1 "2013-04-12" "0.99-pre" "GNU"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH "NAME"
+gjarsigner \- Java ARchive (JAR) file signing and verification tool
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+jarsigner [\fI\s-1OPTION\s0\fR]... \fI\s-1FILE\s0\fR \fI\s-1ALIAS\s0\fR
+.PP
+jarsigner \fB\-verify\fR [\fI\s-1OPTION\s0\fR]... \fI\s-1FILE\s0\fR
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+When the first form is used, the tool signs the designated \s-1JAR\s0 file. The second form, on the other hand, is used to verify a previously signed \s-1JAR\s0 file.
+.PP
+\&\fI\s-1FILE\s0\fR is the .JAR file to process; i.e., to sign if the first syntax form is used, or to verify if the second syntax form is used instead.
+.PP
+\&\fI\s-1ALIAS\s0\fR must be a known \fIAlias\fR of a \fIKey Entry\fR in the designated \fIKey Store\fR. The private key material associated with this \fIAlias\fR is then used for signing the designated .JAR file.
+.SH "OPTIONS"
+.IX Header "OPTIONS"
+\fICommon options\fR
+.IX Subsection "Common options"
+.PP
+The following options may be used when the tool is used for either signing, or verifying, a .JAR file.
+.IP "\fB\-verbose\fR" 4
+.IX Item "-verbose"
+Use this option to force the tool to generate more verbose messages, during its processing.
+.IP "\fB\-internalsf\fR" 4
+.IX Item "-internalsf"
+When present, the tool will include \-\-which otherwise it does not\*(-- the \f(CW\*(C`.SF\*(C'\fR file in the \f(CW\*(C`.DSA\*(C'\fR generated file.
+.IP "\fB\-sectionsonly\fR" 4
+.IX Item "-sectionsonly"
+When present, the tool will include in the \f(CW\*(C`.SF\*(C'\fR generated file \-\-which otherwise it does not\*(-- a header containing a hash of the whole manifest file.  When that header is included, the tool can quickly check, during verification, if the hash (in the header) matches or not the manifest file.
+.IP "\fB\-provider \s-1PROVIDER_CLASS_NAME\s0\fR" 4
+.IX Item "-provider PROVIDER_CLASS_NAME"
+A fully qualified class name of a \fISecurity Provider\fR to add to the current list of \fISecurity Providers\fR already installed in the \s-1JVM\s0 in-use. If a provider class is specified with this option, and was successfully added to the runtime \-\-i.e. it was not already installed\*(-- then the tool will attempt to remove this \fISecurity Provider\fR before exiting.
+.IP "\fB\-help\fR" 4
+.IX Item "-help"
+Prints a help text similar to this one.
+.PP
+\fISigning options\fR
+.IX Subsection "Signing options"
+.PP
+The following options may be specified when using the tool for signing purposes.
+.IP "\fB\-keystore\fR \fI\s-1URL\s0\fR" 4
+.IX Item "-keystore URL"
+Use this option to specify the location of the key store to use. The default value is a file \s-1URL\s0 referencing the file named \fI.keystore\fR located in the path returned by the call to \f(CW\*(C`java.lang.System#getProperty(String)\*(C'\fR using \f(CW\*(C`user.home\*(C'\fR as argument.
+.Sp
+If a \s-1URL\s0 was specified, but was found to be malformed \-\-e.g. missing protocol element\*(-- the tool will attempt to use the \s-1URL\s0 value as a file-name (with absolute or relative path-name) of a key store \-\-as if the protocol was \f(CW\*(C`file:\*(C'\fR.
+.IP "\fB\-storetype\fR \fI\s-1STORE_TYPE\s0\fR" 4
+.IX Item "-storetype STORE_TYPE"
+Use this option to specify the type of the key store to use. The default value, if this option is omitted, is that of the property \f(CW\*(C`keystore.type\*(C'\fR in the security properties file, which is obtained by invoking the static method call \f(CW\*(C`getDefaultType()\*(C'\fR in \f(CW\*(C`java.security.KeyStore\*(C'\fR.
+.IP "\fB\-storepass\fR \fI\s-1PASSWORD\s0\fR" 4
+.IX Item "-storepass PASSWORD"
+Use this option to specify the password which will be used to unlock the key store. If this option is missing, the User will be prompted to provide a password.
+.IP "\fB\-keypass\fR \fI\s-1PASSWORD\s0\fR" 4
+.IX Item "-keypass PASSWORD"
+Use this option to specify the password which the tool will use to unlock the \fIKey Entry\fR associated with the designated \fIAlias\fR.
+.Sp
+If this option is omitted, the tool will first attempt to unlock the \fIKey Entry\fR using the same password protecting the key store. If this fails, you will then be prompted to provide a password.
+.IP "\fB\-sigfile\fR \fI\s-1NAME\s0\fR" 4
+.IX Item "-sigfile NAME"
+Use this option to designate a literal that will be used to construct file names for both the \f(CW\*(C`.SF\*(C'\fR and \f(CW\*(C`.DSA\*(C'\fR signature files. These files  will be generated, by the tool, and placed in the \fIMETA-INF\fR directory of the signed \s-1JAR\s0.  Permissible characters for \fI\s-1NAME\s0\fR must be in the range \*(L"a\-zA\-Z0\-9_\-\*(R".  All characters will be converted to upper-case ones.
+.Sp
+If this option is missing, the first eight characters of the \fI\s-1ALIAS\s0\fR argument will be used. When this is the case, any character in \fI\s-1ALIAS\s0\fR that is outside the permissible range of characters will be replaced by an underscore.
+.IP "\fB\-signedjar\fR \fI\s-1FILE\s0\fR" 4
+.IX Item "-signedjar FILE"
+Use this option to specify the file name of the signed \s-1JAR\s0. If this option is omitted, then the signed \s-1JAR\s0 will be named the same as \fI\s-1FILE\s0\fR; i.e., the input \s-1JAR\s0 file will be replaced with the signed copy.
+.PP
+\fIVerification options\fR
+.IX Subsection "Verification options"
+.PP
+The following options may be specified when using the tool for verification purposes.
+.IP "\fB\-verify\fR" 4
+.IX Item "-verify"
+Use this option to indicate that the tool is to be used for verification purposes.
+.IP "\fB\-certs\fR" 4
+.IX Item "-certs"
+This option is used in conjunction with the \fB\-verbose\fR option. When present, along with the \fB\-verbose\fR option, the tool will print more detailed information about the certificates of the signer(s) being processed.
+.SH "BUGS"
+.IX Header "BUGS"
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+.SH "AUTHOR"
+.IX Header "AUTHOR"
diff --git a/libjava/classpath/doc/gjavah.1 b/libjava/classpath/doc/gjavah.1
new file mode 100644
index 000000000..5e844883a
--- /dev/null
+++ b/libjava/classpath/doc/gjavah.1
@@ -0,0 +1,203 @@
+.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings.  \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
+.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
+.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
+.\" nothing in troff, for use with C<>.
+.tr \(*W-
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+.    ds -- \(*W-
+.    ds PI pi
+.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
+.    ds L" ""
+.    ds R" ""
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds -- \|\(em\|
+.    ds PI \(*p
+.    ds L" ``
+.    ds R" ''
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.ie \nF \{\
+.    de IX
+.    tm Index:\\$1\t\\n%\t"\\$2"
+..
+.    nr % 0
+.    rr F
+.\}
+.el \{\
+.    de IX
+..
+.\}
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
+.    \" fudge factors for nroff and troff
+.if n \{\
+.    ds #H 0
+.    ds #V .8m
+.    ds #F .3m
+.    ds #[ \f1
+.    ds #] \fP
+.\}
+.if t \{\
+.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+.    ds #V .6m
+.    ds #F 0
+.    ds #[ \&
+.    ds #] \&
+.\}
+.    \" simple accents for nroff and troff
+.if n \{\
+.    ds ' \&
+.    ds ` \&
+.    ds ^ \&
+.    ds , \&
+.    ds ~ ~
+.    ds /
+.\}
+.if t \{\
+.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+.    \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+.    \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+.    \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+.    ds : e
+.    ds 8 ss
+.    ds o a
+.    ds d- d\h'-1'\(ga
+.    ds D- D\h'-1'\(hy
+.    ds th \o'bp'
+.    ds Th \o'LP'
+.    ds ae ae
+.    ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "GJAVAH 1"
+.TH GJAVAH 1 "2013-04-12" "0.99-pre" "GNU"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH "NAME"
+gjavah \- \- generate header files from Java class files
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+gjavah ...
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+The \fBgjavah\fR program is used to generate header files from class
+files.  It can generate both \s-1CNI\s0 and \s-1JNI\s0 header files, as well as stub
+implementation files which can be used as a basis for implementing the
+required native methods.
+.SH "OPTIONS"
+.IX Header "OPTIONS"
+.IP "\fB\-d\fR \fI\s-1DIR\s0\fR" 4
+.IX Item "-d DIR"
+Set output directory.
+.IP "\fB\-o\fR \fI\s-1FILE\s0\fR" 4
+.IX Item "-o FILE"
+Set output file (only one of \fB\-d\fR or \fB\-o\fR may be used).
+.IP "\fB\-cmdfile\fR \fI\s-1FILE\s0\fR" 4
+.IX Item "-cmdfile FILE"
+Read command file.
+.IP "\fB\-all\fR \fI\s-1DIR\s0\fR" 4
+.IX Item "-all DIR"
+Operate on all class files under directory \fI\s-1DIR\s0\fR.
+.IP "\fB\-stubs\fR" 4
+.IX Item "-stubs"
+Emit stub implementation.
+.IP "\fB\-jni\fR" 4
+.IX Item "-jni"
+Emit \s-1JNI\s0 stubs or header (default).
+.IP "\fB\-cni\fR" 4
+.IX Item "-cni"
+Emit \s-1CNI\s0 stubs or header (default \s-1JNI\s0).
+.IP "\fB\-verbose\fR" 4
+.IX Item "-verbose"
+Set verbose mode.
+.IP "\fB\-force\fR" 4
+.IX Item "-force"
+Output files should always be written.
+.PP
+Class path options:
+.IP "\fB\-classpath\fR \fI\s-1PATH\s0\fR" 4
+.IX Item "-classpath PATH"
+Set the class path.
+.IP "\fB\-I\fR\fI\s-1DIR\s0\fR" 4
+.IX Item "-IDIR"
+Add directory to class path.
+.IP "\fB\-bootclasspath\fR \fI\s-1PATH\s0\fR" 4
+.IX Item "-bootclasspath PATH"
+Set the boot class path.
+.IP "\fB\-extdirs\fR \fI\s-1PATH\s0\fR" 4
+.IX Item "-extdirs PATH"
+Set the extension directory path.
+.PP
+Standard options:
+.IP "\fB\-help\fR" 4
+.IX Item "-help"
+Print help text, then exit.
+.IP "\fB\-version\fR" 4
+.IX Item "-version"
+Print version number, then exit.
+.IP "\fB\-J\fR\fI\s-1OPTION\s0\fR" 4
+.IX Item "-JOPTION"
+Pass argument to the Java runtime.
+.SH "BUGS"
+.IX Header "BUGS"
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fIjavac\fR\|(1), ...
+.SH "AUTHOR"
+.IX Header "AUTHOR"
diff --git a/libjava/classpath/doc/gjdoc.1 b/libjava/classpath/doc/gjdoc.1
new file mode 100644
index 000000000..90862d653
--- /dev/null
+++ b/libjava/classpath/doc/gjdoc.1
@@ -0,0 +1,906 @@
+.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings.  \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
+.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
+.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
+.\" nothing in troff, for use with C<>.
+.tr \(*W-
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+.    ds -- \(*W-
+.    ds PI pi
+.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
+.    ds L" ""
+.    ds R" ""
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds -- \|\(em\|
+.    ds PI \(*p
+.    ds L" ``
+.    ds R" ''
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.ie \nF \{\
+.    de IX
+.    tm Index:\\$1\t\\n%\t"\\$2"
+..
+.    nr % 0
+.    rr F
+.\}
+.el \{\
+.    de IX
+..
+.\}
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
+.    \" fudge factors for nroff and troff
+.if n \{\
+.    ds #H 0
+.    ds #V .8m
+.    ds #F .3m
+.    ds #[ \f1
+.    ds #] \fP
+.\}
+.if t \{\
+.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+.    ds #V .6m
+.    ds #F 0
+.    ds #[ \&
+.    ds #] \&
+.\}
+.    \" simple accents for nroff and troff
+.if n \{\
+.    ds ' \&
+.    ds ` \&
+.    ds ^ \&
+.    ds , \&
+.    ds ~ ~
+.    ds /
+.\}
+.if t \{\
+.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+.    \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+.    \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+.    \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+.    ds : e
+.    ds 8 ss
+.    ds o a
+.    ds d- d\h'-1'\(ga
+.    ds D- D\h'-1'\(hy
+.    ds th \o'bp'
+.    ds Th \o'LP'
+.    ds ae ae
+.    ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "GJDOC 1"
+.TH GJDOC 1 "2013-04-12" "0.99-pre" "GNU"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH "NAME"
+cp\-tools \- GNU Classpath Tools Guide
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+gjdoc [\fB\-sourcepath\fR \fIpathlist\fR]
+      [\fB\-all\fR] [\fB\-subpackages\fR \fIpkg:pkg:...\fR] [\fB\-exclude\fR \fIpkglist\fR]
+      [\fB\-encoding\fR \fIcharset\fR] [\fB\-locale\fR \fIname\fR] [\fB\-source\fR \fIrelease\fR]
+      [\fB\-public\fR] [\fB\-protected\fR] [\fB\-package\fR] [\fB\-private\fR] 
+      [\fB\-doctitle\fR \fItext\fR] [\fB\-header\fR \fItext\fR] [\fB\-footer\fR \fItext\fR] [\fB\-bottom\fR \fItext\fR]
+      [\fB\-link\fR \fIurl\fR] [\fB\-linkoffline\fR \fIurl\fR \fIpath\fR] [\fB\-noqualifier\fR \fIpkg:pkg:...\fR] 
+      [\fB\-tagletpath\fR \fIpathlist\fR] [\fB\-taglet\fR \fIclassName\fR] [\fB\-tag\fR \fItagspec\fR]
+      [\fB\-use\fR] [\fB\-linksource\fR] [\fB\-splitindex\fR] [\fB\-noindex\fR] [\fB\-notree\fR] 
+      [\fB\-version\fR] [\fB\-author\fR] [\fB\-nosince\fR] [\fB\-addstylesheet\fR \fIfile\fR]
+      [\fB\-d\fR \fItargetdir\fR] 
+      [\fIpackages\fR...] [\fIsourcefiles\fR...] [@\fIcmdfile\fR]
+.PP
+gjdoc [\fB\-sourcepath\fR \fIpathlist\fR]
+      [\fB\-all\fR] [\fB\-subpackages\fR \fIpkg:pkg:...\fR] [\fB\-exclude\fR \fIpkglist\fR]
+      [\fB\-encoding\fR \fIcharset\fR] [\fB\-locale\fR \fIname\fR] [\fB\-source\fR \fIrelease\fR]
+      [\fB\-public\fR] [\fB\-protected\fR] [\fB\-package\fR] [\fB\-private\fR] 
+      [\fB\-docletpath\fR \fIpathlist\fR] [\fB\-doclet\fR \fIclassName\fR]
+      [\fIpackages\fR...] [\fIsourcefiles\fR...] [@\fIcmdfile\fR]
+      [doclet options]
+.PP
+gjdoc \fB\-\-help\fR
+.PP
+gjdoc \fB\-\-version\fR
+.PP
+Only the most useful options are listed here; see below for the
+remainder.
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+Gjdoc can be used in two ways: as a stand-alone documentation tool, or
+as a driver for a user-specified Doclet.
+.PP
+In the default mode, Gjdoc will use the Standard Doclet
+\&\fBHtmlDoclet\fR to generate a set of \s-1HTML\s0 pages.  The canonical
+usage is:
+.PP
+.Vb 1
+\&        gjdoc \-s src/java/ \-all \-d api\-docs/
+.Ve
+.PP
+Here, \fBsrc/java/\fR is the root of your source code class
+hierarchy, \fB\-all\fR means that all valid Java files found under
+this root directory should be processed, and \fBapi\-docs/\fR is the
+directory where the generated documentation should be placed.
+.PP
+To learn more about running Doclets other than the Standard Doclet,
+refer to the manual.
+.SH "OPTIONS"
+.IX Header "OPTIONS"
+.SS "Option Summary by Type"
+.IX Subsection "Option Summary by Type"
+Here is a summary of all the options of both Gjdoc and the Standard
+Doclet, grouped by type.  Explanations are in the following sections.
+.IP "\fISource Set Options\fR" 4
+.IX Item "Source Set Options"
+\&\fB\-sourcepath\fR \fIpathlist\fR  \fB\-subpackages\fR \fIpkglist\fR  \fB\-exclude\fR \fIpkglist\fR
+.IP "\fISource Format Options\fR" 4
+.IX Item "Source Format Options"
+\&\fB\-source\fR \fIrelease\fR  \fB\-encoding\fR \fIencoding\fR  \fB\-breakiterator\fR
+.IP "\fIInterlinking Options\fR" 4
+.IX Item "Interlinking Options"
+\&\fB\-link\fR \fIurl\fR  \fB\-linkoffline\fR \fIurl\fR\fB \fR\fIfile\fR  \fB\-noqualifier\fR \fIpkg:pkg:...\fR
+.IP "\fIGeneration Options\fR" 4
+.IX Item "Generation Options"
+\&\fB\-author  \-licensetext  \-use  \-version  \-splitindex  \-noindex
+ \-nodeprecated  \-nodeprecatedlist  \-nohelp  \-nonavbar
+ \-nosince  \-notree  \-public  \-protected  \-package  \-private
+ \-docfilessubdirs  \-excludedocfilessubdir\fR \fIdirname\fR
+ \fB\-linksource\fR
+.IP "\fIOutput Options\fR" 4
+.IX Item "Output Options"
+\&\fB\-d  \-locale\fR \fIname\fR  \fB\-charset\fR \fIcharset\fR  \fB\-docencoding\fR \fIcharset\fR
+ \fB\-validhtml  \-baseurl\fR \fIurl\fR
+.IP "\fIDecoration Options\fR" 4
+.IX Item "Decoration Options"
+\&\fB\-windowtitle\fR \fItext\fR  \fB\-doctitle\fR \fItext\fR  \fB\-title\fR \fItext\fR  
+ \fB\-header\fR \fItext\fR  \fB\-footer\fR \fItext\fR  \fB\-bottom\fR \fItext\fR
+ \fB\-helpfile\fR \fIfile\fR  \fB\-stylesheetfile\fR \fIfile\fR  \fB\-addstylesheet\fR \fIfile\fR
+ \fB\-group\fR \fIgroupheading\fR\fB \fR\fIpkgpattern:pkgpattern:...\fR
+.IP "\fITaglet Options\fR" 4
+.IX Item "Taglet Options"
+\&\fB\-tagletpath  \-taglet\fR \fIclassname\fR  \fB\-tag\fR \fItagspec\fR
+.IP "\fIDoclet Options\fR" 4
+.IX Item "Doclet Options"
+\&\fB\-docletpath  \-doclet\fR \fIclassname\fR
+.IP "\fIVerbosity Options\fR" 4
+.IX Item "Verbosity Options"
+\&\fB\-quiet  \-verbose\fR
+.IP "\fIVirtual Machine Options\fR" 4
+.IX Item "Virtual Machine Options"
+\&\fB\-classpath  \-bootclasspath  \-J\fR \fIvmopt\fR
+.SS "Selecting which Source Files to Process"
+.IX Subsection "Selecting which Source Files to Process"
+.IP "\fB\-s\fR \fIpathlist\fR" 4
+.IX Item "-s pathlist"
+.PD 0
+.IP "\fB\-sourcepath\fR \fIpathlist\fR" 4
+.IX Item "-sourcepath pathlist"
+.PD
+Look for source files in the specified directory or directories.
+.Sp
+\&\fIpathlist\fR should be one or more directory paths separated by your
+platform's path separator (usually \fB:\fR or \fB;\fR).
+.Sp
+If this option is not given, \fBgjdoc\fR will look for source
+files in the current directory.
+.Sp
+The directories specified should be root directories in terms of the
+Java package system.  For example, if you want to generate
+documentation for classes in package \fBfoo.bar\fR, you must specify
+the directory containing the top-level \fB\f(BIfoo\fB\fR
+sub-directory, not the directory \fB\f(BIfoo/bar/\fB\fR in which the
+Java source files reside.
+.Sp
+The short-hand alias \fB\-s\fR is specific to \fBgjdoc\fR and
+not compatible to Sun \fBjavadoc\fR.
+.IP "\fB\-all\fR" 4
+.IX Item "-all"
+\&\fI[\s-1EXPERIMENTAL\s0]\fR
+Process all valid Java source files found in the directories listed in
+the source path and their sub-directories.
+.Sp
+This is an option specific to \fBgjdoc\fR and not compatible to
+Sun \fBjavadoc\fR.
+.IP "\fB\-subpackages\fR \fIpkg:pkg:...\fR" 4
+.IX Item "-subpackages pkg:pkg:..."
+Process the classes in the given Java packages and all sub-packages,
+recursively.  Note that multiple package names must be separated with
+colons instead of whitespace.
+.IP "\fB\-exclude\fR \fIpkg:pkg:...\fR" 4
+.IX Item "-exclude pkg:pkg:..."
+Do not process classes in the given Java packages and all
+sub-packages, recursively.  This option can be used in conjunction
+with \fB\-all\fR or \fB\-subpackages\fR in order to exclude
+individual packages or package sub-trees from the output.
+.IP "\fIpackages\fR\fB...\fR" 4
+.IX Item "packages..."
+Process all classes in the given Java packages.
+.IP "\fIsourcefiles\fR\fB...\fR" 4
+.IX Item "sourcefiles..."
+Process the classes in the given Java source files.
+.SS "Specifying the Format of Input Files"
+.IX Subsection "Specifying the Format of Input Files"
+.IP "\fB\-source\fR \fIrelease\fR" 4
+.IX Item "-source release"
+Assume that the source files are targeted at the given release of the
+Java platform.
+.Sp
+\&\fIrelease\fR should be the version number of a Java platform release
+in the format \s-1MAJOR\s0.MINOR, for example \fB1.4\fR.
+.Sp
+This option is currently ignored except that an error is raised if a
+release number other than \fB1.2\fR, \fB1.3\fR or \fB1.4\fR is
+specified.
+.IP "\fB\-encoding\fR \fIcharset\fR" 4
+.IX Item "-encoding charset"
+Assume that the source files are encoded using \fIcharset\fR.
+.Sp
+Examples for \fIcharset\fR are \fBUS-ASCII\fR, \fB\s-1ISO\-8859\-1\s0\fR or
+\&\fB\s-1UTF\-8\s0\fR.
+.Sp
+The semantics of \fIcharset\fR are identical to those of \fBjava.nio.charset.Charset.forName(String)\fR.
+.IP "\fB\-breakiterator\fR" 4
+.IX Item "-breakiterator"
+Use the locale's java.text.BreakIterator instead of the internal
+first sentence detector.
+.Sp
+By default, \fBgjdoc\fR uses an internal algorithm to determine
+where a sentence ends. When this option is given, it will instead use
+the \fBjava.text.BreakIterator\fR instance for the locale given with
+\&\fB\-locale\fR (or the default locale).
+.Sp
+This option should be specified when applying \fBgjdoc\fR to
+source code commented in a non-latin language for which the default
+first sentence detector does not work. For all other cases, the
+default (do not use BreakIterator) produces better results at the time
+of this writing.
+.SS "Interlinking with other Documentation Sets"
+.IX Subsection "Interlinking with other Documentation Sets"
+.IP "\fB\-link\fR \fIurl\fR" 4
+.IX Item "-link url"
+Create hyperlinks to another documentation set.
+.Sp
+By default, \fBgjdoc\fR will only create hyperlinks to classes in
+the source set.  Use this option to additionally create hyperlinks to
+classes covered by the specified documentation set.
+.Sp
+\&\fIurl\fR should be the root \s-1URL\s0 of the other documentation set. For
+example, to add hyperlinks to \s-1GNU\s0 Classpath, specify the following:
+.Sp
+.Vb 1
+\&        \-link http://developer.classpath.org/doc/
+.Ve
+.Sp
+The \fB\-link\fR option can be specified multiple times.
+.Sp
+Note that specifying the \fB\-link\fR option will cause an \s-1HTTP\s0
+access every time gjdoc is invoked. You can use \fB\-linkoffline\fR
+instead to avoid this access.
+.IP "\fB\-linkoffline\fR \fIurl\fR\fB \fR\fIfile\fR" 4
+.IX Item "-linkoffline url file"
+Create hyperlinks to another documentation set which is also present
+on the local file system.
+.Sp
+This option works exactly like \fB\-link\fR, except that it accesses
+the local file system instead of the network for determining which
+classes are covered by the linked documentation set.
+.Sp
+When using \fB\-linkoffline\fR the remote documentation set is not
+accessed at all, which can significantly speed up generation time
+depending on your network connection.  The generated hyperlinks to the
+documentation set however refer to the remote set, not to the local
+one, so that you can distribute the documentation without any further
+dependencies.
+.Sp
+The \fB\-linkoffline\fR option can be specified multiple times.
+.IP "\fB\-noqualifier\fR \fIpkg:pkg:...\fR" 4
+.IX Item "-noqualifier pkg:pkg:..."
+Do not qualify names of classes in the given packages with their
+package name.
+.Sp
+By default, a class name is displayed unqualified only if the class is
+part of the source set or a linked documentation set, and qualified
+with the name of its containing package if it is not. You can use this
+option to force unqualified names for classes even if they are not
+part of the documentation set.
+.Sp
+For example, usually a reference to the String class is represented
+fully-qualified as \fBjava.lang.String\fR (unless you link to the
+appropriate documentation set using \fB\-link\fR) because it isn't
+part of the documentation set.  You can specify \fB\-noqualifier
+java.lang\fR to render the same references just as \fBString\fR.
+.Sp
+Note that for all unqualified class names, a tooltip is provided when
+you place your mouse pointer over it in the \s-1HTML\s0 documentation.
+.IP "\fB\-noqualifier\fR \fBall\fR" 4
+.IX Item "-noqualifier all"
+Omit package name qualifier from all class names.
+.Sp
+Specify this option to omit package name qualifiers altogether,
+.SS "Selecting which Information to Generate"
+.IX Subsection "Selecting which Information to Generate"
+.IP "\fB\-public\fR" 4
+.IX Item "-public"
+Only include public members of public classes in the output.  By
+default, protected class members are included as well.
+.IP "\fB\-protected\fR" 4
+.IX Item "-protected"
+Include public or protected members of public classes in the output.
+This is the default.
+.IP "\fB\-package\fR" 4
+.IX Item "-package"
+Include public, protected and package-private members of public and
+package-private classes.
+.IP "\fB\-private\fR" 4
+.IX Item "-private"
+Include all classes and class members regardless of their access
+level.
+.IP "\fB\-splitindex\fR" 4
+.IX Item "-splitindex"
+Generate one index page per letter instead of a single, monolithic
+index page.
+.Sp
+By default, the index created by the Standard Doclet contains all
+entries on a single page.  This is fine for small documentation sets,
+but for large sets you should specify this option.
+.IP "\fB\-nosince\fR" 4
+.IX Item "-nosince"
+Ignore \fB\f(CB@since\fB\fR tags in javadoc comments.
+.Sp
+By default, the generated output contains sections listing the version
+of your \s-1API\s0 since which the package, class or class member in question
+exists when this tag is encountered.  Specify this option to omit this
+information.
+.IP "\fB\-notree\fR" 4
+.IX Item "-notree"
+Do not generate any tree pages.
+.Sp
+By default, the generated output includes one inheritance tree per
+package, and \- if the documentation set consists of multiple packages
+\&\- a page with the full inheritance tree.  Specify this option to omit
+generation of these pages.
+.IP "\fB\-noindex\fR" 4
+.IX Item "-noindex"
+Do not output the alphabetical index.
+.Sp
+By default, gjdoc generates an alphabetical index of all program
+elements in the documentation set (packages, classes, inner classes,
+constructors, methods, and fields).  Specify this option to omit this
+information.
+.IP "\fB\-nohelp\fR" 4
+.IX Item "-nohelp"
+Do not generate the help page.
+.Sp
+This option is currently ignored as the Standard Doclet doesn't
+provide a help page.
+.IP "\fB\-nodeprecated\fR" 4
+.IX Item "-nodeprecated"
+Do not output inline information about deprecated packages, classes or
+class members.
+.Sp
+By default, the Standard Doclet adds a highlighted paragraph with
+deprecation information to the description of each deprecated program
+element.  Specify this option to omit this information.
+.IP "\fB\-nodeprecatedlist\fR" 4
+.IX Item "-nodeprecatedlist"
+Do not output the summary page for deprecated \s-1API\s0 elements.
+.Sp
+By default, the Standard Doclet generates a page listing all
+deprecated \s-1API\s0 elements along with a deprecation description which
+usually includes the reason for deprecation and possible
+alternatives.  Specify this option to omit this information.
+.IP "\fB\-nonavbar\fR" 4
+.IX Item "-nonavbar"
+Do not output the navigation bar, header, and footer.
+.Sp
+By default, each output page is equipped with a top navigation bar
+(which may include a user-specified header) and a bottom navigation
+bar (which may include a user-specified footer).  Specify this option
+to omit this decoration.
+.IP "\fB\-nocomment\fR" 4
+.IX Item "-nocomment"
+Omit all documentation text from the generated files and output only
+declarations and program element relationships.
+.Sp
+This option is here for compatibility with \fBjavadoc\fR.  If you
+plan on extracting information about your project via \fBgjdoc\fR,
+you should consider using a different Doclet for your purposes
+instead, for example XmlDoclet.  You could also use the Doclet \s-1API\s0
+directly by implementing a new Doclet.
+.IP "\fB\-linksource\fR" 4
+.IX Item "-linksource"
+Generate a page with syntax-highlighted source code for each class.
+By default, this page is not generated.
+.Sp
+The source code can be accessed by clicking on the button labelled
+\&\*(L"Source\*(R" in the navigation bar, or by clicking on the name of a
+constructor, field, method, or inner class in the detail section of a
+class documentation page.
+.IP "\fB\-use\fR" 4
+.IX Item "-use"
+Generate a page with cross-reference information. By default, this
+page is not generated.
+.Sp
+The cross-reference information can be accessed by clicking on the
+button labelled `Use' in the navigation bar.
+.Sp
+The `Use' page lists all classes/interfaces in the documentation set
+that extend/implement the class (type) in question; fields of the
+type; methods or constructors accepting a parameter of the type;
+methods returning the type; and methods or constructors throwing the
+type.
+.IP "\fB\-author\fR" 4
+.IX Item "-author"
+Include author information in the output.
+.Sp
+When specified, author information as specified using the
+\&\fB\f(CB@author\fB\fR tag in javadoc comments is incorporated into the
+output. By default, \fB\f(CB@author\fB\fR tags are ignored.
+.IP "\fB\-version\fR" 4
+.IX Item "-version"
+Include version information in the output.
+.Sp
+When specified, version information as specified using the
+\&\fB\f(CB@version\fB\fR tag in javadoc comments is incorporated into the
+output. By default, \fB\f(CB@version\fB\fR tags are ignored.
+.IP "\fB\-licensetext\fR" 4
+.IX Item "-licensetext"
+Assume that the first comment in each source file contains the license
+text, and add license information to the footer of each generated
+class page.
+.Sp
+This is an option specific to \fBgjdoc\fR and not compatible to
+Sun \fBjavadoc\fR.
+.Sp
+This option is intended for use with free and open source projects
+where source code is typically prefixed with a boilerplate license
+comment, when there are legal reasons for including the license in the
+documentation.
+.IP "\fB\-docfilessubdirs\fR" 4
+.IX Item "-docfilessubdirs"
+Recursively copy all files in the \fIdoc-files\fR sub-directory of each
+package directory.
+.Sp
+Usually, only the files in the \fIdoc-files\fR sub-directory are copied
+without descending recursively.
+.IP "\fB\-excludedocfilessubdir\fR \fIname\fR\fB:\fR\fIname\fR\fB:...\fR" 4
+.IX Item "-excludedocfilessubdir name:name:..."
+Do not copy some directories directly under the \fIdoc-files\fR
+sub-directories when descending recursively.
+.Sp
+The argument to this option should be a colon-separated list of
+directory names.
+.Sp
+This option only makes sense if \fB\-docfilessubdirs\fR is also
+specified.  In this case, any sub-directory located directly beneath a
+\&\fIdoc-files\fR directory is omitted if listed.
+.SS "Custom Documentation Tags"
+.IX Subsection "Custom Documentation Tags"
+.IP "\fB\-tagletpath\fR \fIpathlist\fR" 4
+.IX Item "-tagletpath pathlist"
+Search \fIpathlist\fR when loading subsequent Taglet classes specified
+using \fB\-taglet\fR.
+.Sp
+\&\fIpathlist\fR should be one or more paths to a directory or jar file,
+separated by your platform's path separator (usually \fB:\fR or
+\&\fB;\fR).
+.IP "\fB\-taglet\fR \fIclassname\fR" 4
+.IX Item "-taglet classname"
+Register a Taglet.
+.Sp
+\&\fIclassname\fR should be the fully-qualified name of a Java class
+implementing \fBcom.sun.tools.doclets.Taglet\fR.
+.Sp
+The Taglet classes will be loaded from the classpath specified using
+\&\fB\-tagletpath\fR, from the classpath specified using
+\&\fB\-classpath\fR and from the default classpath.
+.Sp
+See the documentation of \fBcom.sun.tools.doclets.Taglet\fR for
+further information.
+.Sp
+Note that for simple tags, there is also \fB\-tag\fR.
+.IP "\fB\-tag\fR \fItagspec\fR" 4
+.IX Item "-tag tagspec"
+Register a generic Taglet.
+.Sp
+The format of \fItagspec\fR must be \fB<tagname>:<flags>:\*(L"<taghead>\*(R"\fR.
+.Sp
+\&\fItagname\fR is the tag name to match, without the leading @ sign.
+.Sp
+\&\fIflags\fR is one or more of the following characters, where each
+character specifies a source code context in which the tag is to be
+recognized.
+.RS 4
+.IP "\fBa\fR" 4
+.IX Item "a"
+all contexts
+.IP "\fBc\fR" 4
+.IX Item "c"
+constructors
+.IP "\fBf\fR" 4
+.IX Item "f"
+fields
+.IP "\fBm\fR" 4
+.IX Item "m"
+methods
+.IP "\fBo\fR" 4
+.IX Item "o"
+overview
+.IP "\fBp\fR" 4
+.IX Item "p"
+packages
+.IP "\fBt\fR" 4
+.IX Item "t"
+types (classes, interfaces, exceptions, errors)
+.IP "\fBX\fR" 4
+.IX Item "X"
+special character which temporarily disables the
+Taglet altogether.
+.RE
+.RS 4
+.Sp
+\&\fItaghead\fR is the string to display in the header of the section
+devoted to the tag in question.
+.Sp
+For example, to define a tag matching \fB\f(CB@cvsid\fB\fR which is to be
+accepted in overview, package and type pages and which is labelled
+with the header \fB\s-1CVS\s0 \s-1ID\s0\fR, you would specify:
+.Sp
+.Vb 1
+\&        \-tag cvsid:tpo:"CVS ID"
+.Ve
+.Sp
+Let's say that a class javadoc comment contains
+.Sp
+.Vb 1
+\&        @cvsid $Id: cp\-tools.texinfo,v 1.7 2008/08/13 13:32:05 jsumali Exp $
+.Ve
+.Sp
+Then the \s-1HTML\s0 output will contain something like
+.Sp
+.Vb 2
+\&        CVS ID:
+\&          $Id: cp\-tools.texinfo,v 1.7 2008/08/13 13:32:05 jsumali Exp $
+.Ve
+.RE
+.SS "Running Other Doclets"
+.IX Subsection "Running Other Doclets"
+.IP "\fB\-docletpath\fR \fIpathlist\fR" 4
+.IX Item "-docletpath pathlist"
+Search \fIpathlist\fR when loading classes for the Doclet specified
+using \fB\-doclet\fR.
+.Sp
+\&\fIpathlist\fR should be one or more paths to a directory or jar file,
+separated by your platform's path separator (usually \fB:\fR or
+\&\fB;\fR).
+.IP "\fB\-doclet\fR \fIclassName\fR" 4
+.IX Item "-doclet className"
+Run the specified doclet instead of the standard HtmlDoclet.
+.Sp
+\&\fIclassName\fR should be the fully-qualified name of a class which
+has a public default constructor and contain a method with the
+following signature:
+.Sp
+.Vb 2
+\&           import com.sun.javadoc.RootDoc;
+\&           public static boolean start(RootDoc rootDoc)
+.Ve
+.Sp
+The Doclet classes will be loaded from the classpath specified using
+\&\fB\-docletpath\fR, from the classpath specified using
+\&\fB\-classpath\fR and from the default classpath.
+.Sp
+The \fBstart\fR method should process the information exposed by the
+Doclet \s-1API\s0 via \fBrootDoc\fR and return \fBtrue\fR on success,
+\&\fBfalse\fR on failure.
+.Sp
+If you are using a third-party doclet, refer to its documentation for
+further instructions.  Note that support for third-party doclets is
+experimental.  Please report any problems you encounter, or provide
+feedback when successfully running third-party applets.
+.Sp
+This option can be specified multiple times, in which case all doclets
+are executed with the same information tree exposed via the Doclet \s-1API\s0
+for each Doclet run.
+.SS "Adding Information to the Output"
+.IX Subsection "Adding Information to the Output"
+.IP "\fB\-windowtitle\fR \fItext\fR" 4
+.IX Item "-windowtitle text"
+Use \fItext\fR as the browser window title prefix.
+.Sp
+When specified, the browser window title for each page will be
+prefixed with \fItext\fR instead of the default string \fBGenerated
+\&\s-1API\s0 Documentation\fR.
+.Sp
+\&\fItext\fR should be plain text (it should not contain \s-1HTML\s0 tags).
+.IP "\fB\-doctitle\fR \fItext\fR" 4
+.IX Item "-doctitle text"
+Set the header text of the overview page to \fItext\fR.
+.Sp
+\&\fItext\fR should be a short plain text string.
+.Sp
+When generating documentation for a single package, specifying this
+option forces generation of the overview page.
+.IP "\fB\-header\fR \fIhtmltext\fR" 4
+.IX Item "-header htmltext"
+Add \fIhtmltext\fR to the right upper corner of every generated page.
+\&\fIhtmltext\fR is usually set to the name of the project being
+documented.
+.IP "\fB\-footer\fR \fIhtmltext\fR" 4
+.IX Item "-footer htmltext"
+Add \fIhtmltext\fR to the right bottom corner of every generated page.
+\&\fIhtmltext\fR is often set to the same value as for \fB\-header\fR.
+.IP "\fB\-bottom\fR \fIhtmltext\fR" 4
+.IX Item "-bottom htmltext"
+Add \fIhtmltext\fR to the very bottom of every generated page,
+spanning the whole width of the page.  When specified, \fIhtmltext\fR
+usually consists of a copyright notice and/or links to other project
+pages.
+.IP "\fB\-addstylesheet\fR \fIfile\fR" 4
+.IX Item "-addstylesheet file"
+Augment the default \s-1CSS\s0 style sheets with the user-specified
+stylesheet \fIfile\fR.
+.Sp
+The given stylesheet is simply loaded by each \s-1HTML\s0 page in addition to
+the default ones, as the last stylesheet.
+.Sp
+Note that the \s-1CSS\s0 cascading rules apply.  That is, your style
+properties will only be assigned if they have a higher cascading order
+than \fBgjdoc\fR's default style.  One simple way to make sure
+that this is the case is to declare your overrides \fB!important\fR.
+.Sp
+See <\fBhttp://www.w3.org/TR/REC\-CSS2/cascade.html#cascading\-order\fR>.
+.IP "\fB\-group\fR \fIheading\fR\fB \fR\fIpkgwildcard\fR\fB:\fR\fIpkgwildcard\fR\fB:...\fR" 4
+.IX Item "-group heading pkgwildcard:pkgwildcard:..."
+Arrange the given packages in a separate group on the overview page.
+.Sp
+The first argument should be a short plain text which is used as the
+title of the package group.  The second argument should be a
+colon-separated list of package wildcards.  The group will consist of
+all packages in the documentation set whose name matches any of the
+given wildcards.
+.Sp
+There is only one wildcard character, \fB*\fR, which matches both
+letters in package name components and the \fB.\fR separating package
+name components.  For example, \fBj*regex\fR would match package
+\&\fBjava.util.regex\fR.  A more useful example would be
+\&\fBjavax.swing*\fR to match \fBjavax.swing\fR and all of its
+sub-packages.
+.Sp
+This option can be given multiple times.
+.Sp
+\&\s-1FIXME:\s0 Information about group nesting here.
+.Sp
+.Vb 5
+\&        gjdoc \-group "Core Classes" \*(Aqjava*\*(Aq \e
+\&              \-group "Swing" \*(Aqjavax.swing*\*(Aq \e
+\&              \-group "XML APIs" \*(Aqjavax.xml*\*(Aq \e
+\&              \-group "Other Extensions" javax* \e
+\&              ...
+.Ve
+.IP "\fB\-overview\fR \fIfile\fR" 4
+.IX Item "-overview file"
+Add the \s-1XHTML\s0 body fragment from \fIfile\fR to the overview page.
+.Sp
+\&\fIfile\fR should contain an \s-1XHTML\s0 fragment with the \s-1HTML\s0 \fBbody\fR
+tag as the root node.
+.Sp
+This option can be used to supply a description of the documentation
+set as a whole.
+.Sp
+When specified, the first sentence of the fragment will be put above
+the tables listing the documented packages, along with a link to the
+full copy of the fragment which is put below the tables.
+.Sp
+When generating documentation for a single package, specifying this
+option forces generation of the overview page.
+.IP "\fB\-stylesheetfile\fR \fIfile\fR" 4
+.IX Item "-stylesheetfile file"
+Use the \s-1CSS\s0 stylesheet in \fIfile\fR instead of the default \s-1CSS\s0
+stylesheets.
+.Sp
+If you only want to override parts of the default stylesheets, use
+\&\fB\-addstylesheet\fR instead.
+.IP "\fB\-title\fR \fItext\fR" 4
+.IX Item "-title text"
+\&\fIDeprecated.\fR Use \fB\-doctitle\fR \fItext\fR instead.
+.IP "\fB\-helpfile\fR \fIfile\fR" 4
+.IX Item "-helpfile file"
+This option is currently ignored.
+.Sp
+When implemented, it will use the \s-1XHTML\s0 fragment in \fIfile\fR for the
+help page contents instead of the default help text.
+.SS "Controlling the Output."
+.IX Subsection "Controlling the Output."
+.IP "\fB\-d\fR \fIdirectory\fR" 4
+.IX Item "-d directory"
+Place all output files into \fIdirectory\fR (and
+sub-directories). \fIdirectory\fR will be created if it does not
+exist, including all non-existing parent directories and all required
+sub-directories.
+.Sp
+If not specified, output will be placed into the current directory.
+.IP "\fB\-locale\fR \fIname\fR" 4
+.IX Item "-locale name"
+Use locale \fIname\fR instead of the default locale for all purposes.
+.Sp
+\&\fIname\fR should be a locale specifier in the form \fBll_CC[_VAR]\fR
+where \fBll\fR is a lowercase two-letter \s-1ISO\-639\s0 language code,
+\&\fB\s-1CC\s0\fR is an optional uppercase two-letter \s-1ISO\-3166\s0 country code,
+and \fB\s-1VAR\s0\fR is an optional variant code.  For example, \fBen\fR
+specifies English, \fBen_US\fR specifies \s-1US\s0 English, and
+\&\fBen_US_WIN\fR specifies a deviant variant of the \s-1US\s0 English locale.
+.Sp
+Note that the semantics of this option correspond exactly to those of
+the constructors of class \fBjava.util.Locale\fR.
+.Sp
+This option currently only determines which Collator is being used for
+sorting output elements.  This means that the locale will only have an
+effect when you are using non-ASCII characters in identifiers.
+.IP "\fB\-charset\fR \fIcharset\fR" 4
+.IX Item "-charset charset"
+\&\fIDeprecated.\fR Override the specified encoding in output \s-1XHTML\s0
+files with the one given by \fBcharset\fR.
+.Sp
+If this option is not given, the encoding specification in output
+\&\s-1XHTML\s0 is chosen to match the encoding used when writing the file (the
+encoding given with \fB\-docencoding\fR, or your platform's default
+encoding).
+.Sp
+The semantics for \fIcharset\fR are specified here:
+<\fBhttp://www.w3.org/TR/2000/REC\-xml\-20001006#NT\-EncName\fR>.  For
+all practical purposes, they are identical to those of the other
+options accepting charset parameters.
+.Sp
+This option is here for compatibility with \fBjavadoc\fR and
+should be avoided.
+.IP "\fB\-docencoding\fR \fIcharset\fR" 4
+.IX Item "-docencoding charset"
+Use the given charset encoding when writing output files instead of
+your platform's default encoding.
+.Sp
+Examples for \fIcharset\fR are \fBUS-ASCII\fR, \fB\s-1ISO\-8859\-1\s0\fR or
+\&\fB\s-1UTF\-8\s0\fR.
+.Sp
+The semantics of this option correspond exactly to those of the
+constructors of class \fBjava.util.Locale\fR.
+.IP "\fB\-validhtml\fR" 4
+.IX Item "-validhtml"
+Force generation of valid \s-1XHTML\s0 code.  This breaks compatibility to
+the traditional Javadoc tool to some extent.
+.Sp
+If this option is specified, anchor names will be mangled so that they
+are valid according to the \s-1XHTML\s0 1.1 specification.  However, a
+documentation set generated with this option cannot be linked to
+properly using the traditional Javadoc tool.  It can be linked to just
+fine using Gjdoc, though.
+.Sp
+Without this option, anchor names for executable class members use the
+traditional format, for example: \*(L"foo(String,int[])\*(R".  This is
+compatible to the traditional Javadoc tool, but according to both the
+\&\s-1HTML\s0 4.0 and \s-1XHTML\s0 1.0 and 1.1 specifications, this format includes
+illegal characters.  Parentheses, square brackets, and the comma are
+not allowed in anchor names.
+.IP "\fB\-baseurl\fR \fIurl\fR" 4
+.IX Item "-baseurl url"
+Hardwire a page \s-1URL\s0 relative to \fIurl\fR into each generated page.
+.Sp
+If you are generating documentation which will exclusively be
+available at a certain \s-1URL\s0, you should use this option to specify this
+\&\s-1URL\s0.
+.Sp
+This can help avoid certain redirect attacks used by spammers, and it
+can be helpful for certain web clients.
+.SS "Verbosity Options"
+.IX Subsection "Verbosity Options"
+.IP "\fB\-quiet\fR" 4
+.IX Item "-quiet"
+Suppress all output except for warnings and error messages.
+.IP "\fB\-verbose\fR" 4
+.IX Item "-verbose"
+Be very verbose about what \fBgjdoc\fR is doing.
+.Sp
+This option is currently ignored.
+.SS "Virtual Machine Options"
+.IX Subsection "Virtual Machine Options"
+Sun's \fBjavadoc\fR tool seems to be based on \fBjavac\fR and
+as such it seems to operate on the \s-1VM\s0 level.  \fBgjdoc\fR, in
+contrast, is a pure Java application.
+.PP
+Therefore, \fBgjdoc\fR can only fake, or simulate, the following
+VM-level options.
+.IP "\fB\-classpath\fR \fIpathlist\fR" 4
+.IX Item "-classpath pathlist"
+Set the Virtual Machine \fBclasspath\fR to \fIpathlist\fR.
+.Sp
+In most cases you should use \fB\-docletpath\fR or
+\&\fB\-tagletpath\fR instead of this option.
+.Sp
+\&\fIpathlist\fR should be one or more paths to a directory or jar file,
+separated by your platform's path separator (usually \fB:\fR or
+\&\fB;\fR).
+.Sp
+If this option is not intercepted at the wrapper level,
+\&\fBgjdoc\fR currently fakes it by calling
+\&\fBSystem.setProperty(\*(L"java.class.path\*(R",\fR \fIpathlist\fR\fB);\fR and
+outputs a warning.
+.IP "\fB\-bootclasspath\fR \fIpathlist\fR" 4
+.IX Item "-bootclasspath pathlist"
+Set the Virtual Machine \fBbootclasspath\fR to \fIpathlist\fR.
+.Sp
+If this option is not intercepted at the wrapper level,
+\&\fBgjdoc\fR outputs a warning.
+.IP "\fB\-J\fR\fIvmopt\fR" 4
+.IX Item "-Jvmopt"
+Pass an arbitrary parameter to the Virtual Machine \fBgjdoc\fR
+runs on.
+.Sp
+If this option is not intercepted at the wrapper level,
+\&\fBgjdoc\fR tries to emulate the option and outputs a warning.
+.Sp
+Currently, only the \s-1VM\s0 option \fB\-D\fR for setting system
+properties is emulated.
+.SH "BUGS"
+.IX Header "BUGS"
+Please report bugs to <\fBhttp://savannah.gnu.org/bugs/?group=classpath\fR>.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+Info entry for \fIgjdoc\fR.
+.SH "AUTHOR"
+.IX Header "AUTHOR"
+Julian Scheid
diff --git a/libjava/classpath/doc/gkeytool.1 b/libjava/classpath/doc/gkeytool.1
new file mode 100644
index 000000000..219d9b7dd
--- /dev/null
+++ b/libjava/classpath/doc/gkeytool.1
@@ -0,0 +1,688 @@
+.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings.  \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
+.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
+.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
+.\" nothing in troff, for use with C<>.
+.tr \(*W-
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+.    ds -- \(*W-
+.    ds PI pi
+.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
+.    ds L" ""
+.    ds R" ""
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds -- \|\(em\|
+.    ds PI \(*p
+.    ds L" ``
+.    ds R" ''
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.ie \nF \{\
+.    de IX
+.    tm Index:\\$1\t\\n%\t"\\$2"
+..
+.    nr % 0
+.    rr F
+.\}
+.el \{\
+.    de IX
+..
+.\}
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
+.    \" fudge factors for nroff and troff
+.if n \{\
+.    ds #H 0
+.    ds #V .8m
+.    ds #F .3m
+.    ds #[ \f1
+.    ds #] \fP
+.\}
+.if t \{\
+.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+.    ds #V .6m
+.    ds #F 0
+.    ds #[ \&
+.    ds #] \&
+.\}
+.    \" simple accents for nroff and troff
+.if n \{\
+.    ds ' \&
+.    ds ` \&
+.    ds ^ \&
+.    ds , \&
+.    ds ~ ~
+.    ds /
+.\}
+.if t \{\
+.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+.    \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+.    \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+.    \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+.    ds : e
+.    ds 8 ss
+.    ds o a
+.    ds d- d\h'-1'\(ga
+.    ds D- D\h'-1'\(hy
+.    ds th \o'bp'
+.    ds Th \o'LP'
+.    ds ae ae
+.    ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "GKEYTOOL 1"
+.TH GKEYTOOL 1 "2013-04-12" "0.99-pre" "GNU"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH "NAME"
+gkeytool \- Manage private keys and public certificates
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+keytool [\fI\s-1COMMAND\s0\fR] ...
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+Cryptographic credentials, in a Java environment, are usually stored in a \fIKey Store\fR. The Java \s-1SDK\s0 specifies a \fIKey Store\fR as a persistent container of two types of objects: \fIKey Entries\fR and \fITrusted Certificates\fR. The security tool \fBkeytool\fR is a Java-based application for managing those types of objects.
+.PP
+A \fIKey Entry\fR represents the private key part of a key-pair used in Public-Key Cryptography, and a signed X.509 certificate which authenticates the public key part for a known entity; i.e. the owner of the key-pair. The X.509 certificate itself contains the public key part of the key-pair.
+.PP
+A \fITrusted Certificate\fR is a signed X.509 certificate issued by a trusted entity. The \fITrust\fR in this context is relative to the User of the \fBkeytool\fR. In other words, the existence of a \fITrusted Certificate\fR in the \fIKey Store\fR processed by a \fBkeytool\fR command implies that the User trusts the \fIIssuer\fR of that \fITrusted Certificate\fR to also sign, and hence authenticates, other \fISubjects\fR the tool may process.
+.PP
+\&\fITrusted Certificates\fR are important because they allow the tool to mechanically construct \fIChains of Trust\fR starting from one of the \fITrusted Certificates\fR in a \fIKey Store\fR and ending with a certificate whose \fIIssuer\fR is potentially unknown. A valid chain is an ordered list, starting with a \fITrusted Certificate\fR (also called the \fIanchor\fR), ending with the target certificate, and satisfying the condition that the \fISubject\fR of certificate \f(CW\*(C`#i\*(C'\fR is the \fIIssuer\fR of certificate \f(CW\*(C`#i + 1\*(C'\fR.
+.PP
+The \fBkeytool\fR is invoked from the command line as follows:
+.PP
+.Vb 1
+\&        keytool [COMMAND] ...
+.Ve
+.PP
+Multiple \fI\s-1COMMAND\s0\fRs may be specified at once, each complete with its own options. \fBkeytool\fR will parse all the arguments, before processing, and executing, each \f(CW\*(C`COMMAND\*(C'\fR. If an exception occurs while executing one \fI\s-1COMMAND\s0\fR \fBkeytool\fR will abort. Note however that because the implementation of the tool uses code to parse command line options that also supports GNU-style options, you have to separate each command group with a double-hyphen; e.g
+.PP
+.Vb 1
+\&        keytool \-list \-\- \-printcert \-alias mykey
+.Ve
+.SH "OPTIONS"
+.IX Header "OPTIONS"
+.IP "\- Add/Update commands" 4
+.IX Item "- Add/Update commands"
+.RS 4
+.PD 0
+.IP "\fB\-genkey [\fR\fI\s-1OPTION\s0\fR\fB]...\fR" 4
+.IX Item "-genkey [OPTION]..."
+.PD
+Generate a new \fIKey Entry\fR, eventually creating a new key store.
+.IP "\fB\-import [\fR\fI\s-1OPTION\s0\fR\fB]...\fR" 4
+.IX Item "-import [OPTION]..."
+Add, to a key store, \fIKey Entries\fR (private keys and certificate chains authenticating the public keys) and \fITrusted Certificates\fR (3rd party certificates which can be used as \fITrust Anchors\fR when building chains-of-trust).
+.IP "\fB\-selfcert [\fR\fI\s-1OPTION\s0\fR\fB]...\fR" 4
+.IX Item "-selfcert [OPTION]..."
+Generate a new self-signed \fITrusted Certificate\fR.
+.IP "\fB\-cacert [\fR\fI\s-1OPTION\s0\fR\fB]...\fR" 4
+.IX Item "-cacert [OPTION]..."
+Import a \s-1CA\s0 \fITrusted Certificate\fR.
+.IP "\fB\-identitydb [\fR\fI\s-1OPTION\s0\fR\fB]...\fR" 4
+.IX Item "-identitydb [OPTION]..."
+\&\fB\s-1NOT\s0 \s-1IMPLEMENTED\s0 \s-1YET\s0\fR.Import a \s-1JDK\s0 1.1 style Identity Database.
+.RE
+.RS 4
+.RE
+.IP "\- Export commands" 4
+.IX Item "- Export commands"
+.RS 4
+.PD 0
+.IP "\fB\-certreq [\fR\fI\s-1OPTION\s0\fR\fB]...\fR" 4
+.IX Item "-certreq [OPTION]..."
+.PD
+Issue a \fICertificate Signing Request\fR (\s-1CSR\s0) which can be then sent to a \fICertification Authority\fR (\s-1CA\s0) to issue a certificate signed (by the \s-1CA\s0) and authenticating the \fISubject\fR of the request.
+.IP "\fB\-export [\fR\fI\s-1OPTION\s0\fR\fB]...\fR" 4
+.IX Item "-export [OPTION]..."
+Export a certificate from a key store.
+.RE
+.RS 4
+.RE
+.IP "\- Display commands" 4
+.IX Item "- Display commands"
+.RS 4
+.PD 0
+.IP "\fB\-list [\fR\fI\s-1OPTION\s0\fR\fB]...\fR" 4
+.IX Item "-list [OPTION]..."
+.PD
+Print one or all certificates in a key store to \f(CW\*(C`STDOUT\*(C'\fR.
+.IP "\fB\-printcert [\fR\fI\s-1OPTION\s0\fR\fB]...\fR" 4
+.IX Item "-printcert [OPTION]..."
+Print a human-readable form of a certificate, in a designated file, to \f(CW\*(C`STDOUT\*(C'\fR.
+.RE
+.RS 4
+.RE
+.IP "\- Management commands" 4
+.IX Item "- Management commands"
+.RS 4
+.PD 0
+.IP "\fB\-keyclone [\fR\fI\s-1OPTION\s0\fR\fB]...\fR" 4
+.IX Item "-keyclone [OPTION]..."
+.PD
+Clone a \fIKey Entry\fR in a key store.
+.IP "\fB\-storepasswd [\fR\fI\s-1OPTION\s0\fR\fB]...\fR" 4
+.IX Item "-storepasswd [OPTION]..."
+Change the password protecting a key store.
+.IP "\fB\-keypasswd [\fR\fI\s-1OPTION\s0\fR\fB]...\fR" 4
+.IX Item "-keypasswd [OPTION]..."
+Change the password protecting a \fIKey Entry\fR in a key store.
+.IP "\fB\-delete [\fR\fI\s-1OPTION\s0\fR\fB]...\fR" 4
+.IX Item "-delete [OPTION]..."
+Delete a \fIKey Entry\fR or a \fITrusted Certificate\fR from a key store.
+.RE
+.RS 4
+.RE
+.PP
+\fICommon options\fR
+.IX Subsection "Common options"
+.PP
+The following \fB\s-1OPTION\s0\fRs are used in more than one \fB\s-1COMMAND\s0\fR. They are described here to reduce redundancy.
+.IP "\fB\-alias\fR \fIAlias\fR" 4
+.IX Item "-alias Alias"
+Every entry, be it a \fIKey Entry\fR or a \fITrusted Certificate\fR, in a key store is uniquely identified by a user-defined \fIAlias\fR string. Use this option to specify the \fIAlias\fR to use when referring to an entry in the key store. Unless specified otherwise, a default value of \f(CW\*(C`mykey\*(C'\fR shall be used when this option is omitted from the command line.
+.IP "\fB\-keyalg\fR \fI\s-1ALGORITHM\s0\fR" 4
+.IX Item "-keyalg ALGORITHM"
+Use this option to specify the canonical name of the key-pair generation algorithm. The default value for this option is \f(CW\*(C`DSS\*(C'\fR (a synonym for the Digital Signature Algorithm also known as \s-1DSA\s0).
+.IP "\fB\-keysize\fR \fI\s-1SIZE\s0\fR" 4
+.IX Item "-keysize SIZE"
+Use this option to specify the number of bits of the shared modulus (for both the public and private keys) to use when generating new keys. A default value of \f(CW1024\fR will be used if this option is omitted from the command line.
+.IP "\fB\-validity\fR \fI\s-1DAY_COUNT\s0\fR" 4
+.IX Item "-validity DAY_COUNT"
+Use this option to specify the number of days a newly generated certificate will be valid for. The default value is \f(CW90\fR (days) if this option is omitted from the command line.
+.IP "\fB\-storetype\fR \fI\s-1STORE_TYPE\s0\fR" 4
+.IX Item "-storetype STORE_TYPE"
+Use this option to specify the type of the key store to use. The default value, if this option is omitted, is that of the property \f(CW\*(C`keystore.type\*(C'\fR in the security properties file, which is obtained by invoking the static method call \f(CW\*(C`getDefaultType()\*(C'\fR in \f(CW\*(C`java.security.KeyStore\*(C'\fR.
+.IP "\fB\-storepass\fR \fI\s-1PASSWORD\s0\fR" 4
+.IX Item "-storepass PASSWORD"
+Use this option to specify the password protecting the key store. If this option is omitted from the command line, you will be prompted to provide a password.
+.IP "\fB\-keystore\fR \fI\s-1URL\s0\fR" 4
+.IX Item "-keystore URL"
+Use this option to specify the location of the key store to use. The default value is a file \s-1URL\s0 referencing the file named \fI.keystore\fR located in the path returned by the call to \f(CW\*(C`java.lang.System#getProperty(String)\*(C'\fR using \f(CW\*(C`user.home\*(C'\fR as argument.
+.Sp
+If a \s-1URL\s0 was specified, but was found to be malformed \-\-e.g. missing protocol element\*(-- the tool will attempt to use the \s-1URL\s0 value as a file-name (with absolute or relative path-name) of a key store \-\-as if the protocol was \f(CW\*(C`file:\*(C'\fR.
+.IP "\fB\-provider\fR \fI\s-1PROVIDER_CLASS_NAME\s0\fR" 4
+.IX Item "-provider PROVIDER_CLASS_NAME"
+A fully qualified class name of a \fISecurity Provider\fR to add to the current list of \fISecurity Providers\fR already installed in the \s-1JVM\s0 in-use. If a provider class is specified with this option, and was successfully added to the runtime \-\-i.e. it was not already installed\*(-- then the tool will attempt to removed this \fISecurity Provider\fR before exiting.
+.IP "\fB\-file\fR \fI\s-1FILE\s0\fR" 4
+.IX Item "-file FILE"
+Use this option to designate a file to use with a command. When specified with this option, the value is expected to be the fully qualified path of a file accessible by the File System. Depending on the command, the file may be used as input or as output. When this option is omitted from the command line, \f(CW\*(C`STDIN\*(C'\fR will be used instead, as the source of input, and \f(CW\*(C`STDOUT\*(C'\fR will be used instead as the output destination.
+.IP "\fB\-v\fR" 4
+.IX Item "-v"
+Unless specified otherwise, use this option to enable more verbose output.
+.PP
+\fIAdd/Update commands\fR
+.IX Subsection "Add/Update commands"
+.PP
+The \fB\-genkey\fR command
+.IX Subsection "The -genkey command"
+.PP
+Use this command to generate a new key-pair (both private and public keys), and save these credentials in the key store as a \fIKey Entry\fR, associated with the designated (if was specified with the \fB\-alias\fR option) or default (if the \fB\-alias\fR option is omitted) \fIAlias\fR.
+.PP
+The private key material will be protected with a user-defined password (see \fB\-keypass\fR option). The public key on the other hand will be part of a self-signed X.509 certificate, which will form a 1\-element chain and will be saved in the key store.
+.IP "\fB\-alias\fR \fI\s-1ALIAS\s0\fR" 4
+.IX Item "-alias ALIAS"
+See \fICommon Options\fR for more details.
+.IP "\fB\-keyalg\fR \fI\s-1ALGORITHM\s0\fR" 4
+.IX Item "-keyalg ALGORITHM"
+See \fICommon Options\fR for more details.
+.IP "\fB\-keysize\fR \fI\s-1KEY_SIZE\s0\fR" 4
+.IX Item "-keysize KEY_SIZE"
+See \fICommon Options\fR for more details.
+.IP "\fB\-sigalg\fR \fI\s-1ALGORITHM\s0\fR" 4
+.IX Item "-sigalg ALGORITHM"
+The canonical name of the digital signature algorithm to use for signing certificates. If this option is omitted, a default value will be chosen based on the type of the key-pair; i.e., the algorithm that ends up being used by the \-keyalg option. If the key-pair generation algorithm is \f(CW\*(C`DSA\*(C'\fR, the value for the signature algorithm will be \f(CW\*(C`SHA1withDSA\*(C'\fR. If on the other hand the key-pair generation algorithm is \f(CW\*(C`RSA\*(C'\fR, then the tool will use \f(CW\*(C`MD5withRSA\*(C'\fR as the signature algorithm.
+.IP "\fB\-dname\fR \fI\s-1NAME\s0\fR" 4
+.IX Item "-dname NAME"
+This a mandatory value for the command. If no value is specified \-\-i.e. the \fB\-dname\fR option is omitted\*(-- the tool will prompt you to enter a \fIDistinguished Name\fR to use as both the \fIOwner\fR and \fIIssuer\fR of the generated self-signed certificate.
+.Sp
+See \fICommon Options\fR for more details.
+.IP "\fB\-keypass\fR \fI\s-1PASSWORD\s0\fR" 4
+.IX Item "-keypass PASSWORD"
+Use this option to specify the password which the tool will use to protect the newly created \fIKey Entry\fR.
+.Sp
+If this option is omitted, you will be prompted to provide a password.
+.IP "\fB\-validity\fR \fI\s-1DAY_COUNT\s0\fR" 4
+.IX Item "-validity DAY_COUNT"
+See \fICommon Options\fR for more details.
+.IP "\fB\-storetype\fR \fI\s-1STORE_TYPE\s0\fR" 4
+.IX Item "-storetype STORE_TYPE"
+See \fICommon Options\fR for more details.
+.IP "\fB\-keystore\fR \fI\s-1URL\s0\fR" 4
+.IX Item "-keystore URL"
+See \fICommon Options\fR for more details.
+.IP "\fB\-storepass\fR \fI\s-1PASSWORD\s0\fR" 4
+.IX Item "-storepass PASSWORD"
+See \fICommon Options\fR for more details.
+.IP "\fB\-provider\fR \fI\s-1PROVIDER_CLASS_NAME\s0\fR" 4
+.IX Item "-provider PROVIDER_CLASS_NAME"
+See \fICommon Options\fR for more details.
+.IP "\fB\-v\fR" 4
+.IX Item "-v"
+See \fICommon Options\fR for more details.
+.PP
+The \fB\-import\fR command
+.IX Subsection "The -import command"
+.PP
+Use this command to read an X.509 certificate, or a PKCS#7 \fICertificate Reply\fR from a designated input source and incorporate the certificates into the key store.
+.PP
+If the \fIAlias\fR does not already exist in the key store, the tool treats the certificate read from the input source as a new \fITrusted Certificate\fR. It then attempts to discover a chain-of-trust, starting from that certificate and ending at another \fITrusted Certificate\fR, already stored in the key store. If the \fB\-trustcacerts\fR option is present, an additional key store, of type \f(CW\*(C`JKS\*(C'\fR named \fIcacerts\fR, and assumed to be present in \fI${\s-1JAVA_HOME\s0}/lib/security\fR will also be consulted if found \-\-\f(CW\*(C`${JAVA_HOME}\*(C'\fR refers to the location of an installed \fIJava Runtime Environment\fR (\s-1JRE\s0). If no chain-of-trust can be established, and unless the \f(CW\*(C`\-noprompt\*(C'\fR option has been specified, the certificate is printed to \f(CW\*(C`STDOUT\*(C'\fR and the user is prompted for a confirmation.
+.PP
+If \fIAlias\fR exists in the key store, the tool will treat the certificate(s) read from the input source as a \fICertificate Reply\fR, which can be a chain of certificates, that eventually would replace the chain of certificates associated with the \fIKey Entry\fR of that \fIAlias\fR. The substitution of the certificates only occurs if a chain-of-trust can be established between the bottom certificate of the chain read from the input file and the \fITrusted Certificates\fR already present in the key store. Again, if the \fB\-trustcacerts\fR option is specified, additional \fITrusted Certificates\fR in the same \fIcacerts\fR key store will be considered. If no chain-of-trust can be established, the operation will abort.
+.IP "\fB\-alias\fR \fI\s-1ALIAS\s0\fR" 4
+.IX Item "-alias ALIAS"
+See \fICommon Options\fR for more details.
+.IP "\fB\-file\fR \fI\s-1FILE\s0\fR" 4
+.IX Item "-file FILE"
+See \fICommon Options\fR for more details.
+.IP "\fB\-keypass\fR \fI\s-1PASSWORD\s0\fR" 4
+.IX Item "-keypass PASSWORD"
+Use this option to specify the password which the tool will use to protect the \fIKey Entry\fR associated with the designated \fIAlias\fR, when replacing this \fIAlias\fR' chain of certificates with that found in the certificate reply.
+.Sp
+If this option is omitted, and the chain-of-trust for the certificate reply has been established, the tool will first attempt to unlock the \fIKey Entry\fR using the same password protecting the key store. If this fails, you will then be prompted to provide a password.
+.IP "\fB\-noprompt\fR" 4
+.IX Item "-noprompt"
+Use this option to prevent the tool from prompting the user.
+.IP "\fB\-trustcacerts\fR" 4
+.IX Item "-trustcacerts"
+Use this option to indicate to the tool that a key store, of type \f(CW\*(C`JKS\*(C'\fR, named \fIcacerts\fR, and usually located in \fIlib/security\fR in an installed \fIJava Runtime Environment\fR should be considered when trying to establish chain-of-trusts.
+.IP "\fB\-storetype\fR \fI\s-1STORE_TYPE\s0\fR" 4
+.IX Item "-storetype STORE_TYPE"
+See \fICommon Options\fR for more details.
+.IP "\fB\-keystore\fR \fI\s-1URL\s0\fR" 4
+.IX Item "-keystore URL"
+See \fICommon Options\fR for more details.
+.IP "\fB\-storepass\fR \fI\s-1PASSWORD\s0\fR" 4
+.IX Item "-storepass PASSWORD"
+See \fICommon Options\fR for more details.
+.IP "\fB\-provider\fR \fI\s-1PROVIDER_CLASS_NAME\s0\fR" 4
+.IX Item "-provider PROVIDER_CLASS_NAME"
+See \fICommon Options\fR for more details.
+.IP "\fB\-v\fR" 4
+.IX Item "-v"
+See \fICommon Options\fR for more details.
+.PP
+The \fB\-selfcert\fR command
+.IX Subsection "The -selfcert command"
+.PP
+Use this command to generate a self-signed X.509 version 1 certificate. The newly generated certificate will form a chain of one element which will replace the previous chain associated with the designated \fIAlias\fR (if \fB\-alias\fR option was specified), or the default \fIAlias\fR (if \fB\-alias\fR option was omitted).
+.IP "\fB\-alias\fR \fI\s-1ALIAS\s0\fR" 4
+.IX Item "-alias ALIAS"
+See \fICommon Options\fR for more details.
+.IP "\fB\-sigalg\fR \fI\s-1ALGORITHM\s0\fR" 4
+.IX Item "-sigalg ALGORITHM"
+The canonical name of the digital signature algorithm to use for signing the certificate. If this option is omitted, a default value will be chosen based on the type of the private key associated with the designated \fIAlias\fR. If the private key is a \f(CW\*(C`DSA\*(C'\fR one, the value for the signature algorithm will be \f(CW\*(C`SHA1withDSA\*(C'\fR. If on the other hand the private key is an \f(CW\*(C`RSA\*(C'\fR one, then the tool will use \f(CW\*(C`MD5withRSA\*(C'\fR as the signature algorithm.
+.IP "\fB\-dname\fR \fI\s-1NAME\s0\fR" 4
+.IX Item "-dname NAME"
+Use this option to specify the \fIDistinguished Name\fR of the newly generated self-signed certificate. If this option is omitted, the existing \fIDistinguished Name\fR of the base certificate in the chain associated with the designated \fIAlias\fR will be used instead.
+.Sp
+See \fICommon Options\fR for more details.
+.IP "\fB\-validity\fR \fI\s-1DAY_COUNT\s0\fR" 4
+.IX Item "-validity DAY_COUNT"
+See \fICommon Options\fR for more details.
+.IP "\fB\-keypass\fR \fI\s-1PASSWORD\s0\fR" 4
+.IX Item "-keypass PASSWORD"
+Use this option to specify the password which the tool will use to unlock the \fIKey Entry\fR associated with the designated \fIAlias\fR.
+.Sp
+If this option is omitted, the tool will first attempt to unlock the \fIKey Entry\fR using the same password protecting the key store. If this fails, you will then be prompted to provide a password.
+.IP "\fB\-storetype\fR \fI\s-1STORE_TYPE\s0\fR" 4
+.IX Item "-storetype STORE_TYPE"
+See \fICommon Options\fR for more details.
+.IP "\fB\-keystore\fR \fI\s-1URL\s0\fR" 4
+.IX Item "-keystore URL"
+See \fICommon Options\fR for more details.
+.IP "\fB\-storepass\fR \fI\s-1PASSWORD\s0\fR" 4
+.IX Item "-storepass PASSWORD"
+See \fICommon Options\fR for more details.
+.IP "\fB\-provider\fR \fI\s-1PROVIDER_CLASS_NAME\s0\fR" 4
+.IX Item "-provider PROVIDER_CLASS_NAME"
+See \fICommon Options\fR for more details.
+.IP "\fB\-v\fR" 4
+.IX Item "-v"
+See \fICommon Options\fR for more details.
+.PP
+The \fB\-cacert\fR command
+.IX Subsection "The -cacert command"
+.PP
+Use this command to import, a \s-1CA\s0 certificate and add it to the key store as a \fITrusted Certificate\fR. The \fIAlias\fR for this new entry will be constructed from the \s-1FILE\s0's base-name after replacing hyphens and dots with underscores.
+.PP
+This command is useful when used in a script that recursively visits a directory of \s-1CA\s0 certificates to populate a \f(CW\*(C`cacerts.gkr\*(C'\fR \fIKey Store\fR of trusted certificates which can then be used commands that specify the \fB\-trustcacerts\fR option.
+.IP "\fB\-file\fR \fI\s-1FILE\s0\fR" 4
+.IX Item "-file FILE"
+See \fICommon Options\fR for more details.
+.IP "\fB\-storetype\fR \fI\s-1STORE_TYPE\s0\fR" 4
+.IX Item "-storetype STORE_TYPE"
+See \fICommon Options\fR for more details.
+.IP "\fB\-keystore\fR \fI\s-1URL\s0\fR" 4
+.IX Item "-keystore URL"
+See \fICommon Options\fR for more details.
+.IP "\fB\-storepass\fR \fI\s-1PASSWORD\s0\fR" 4
+.IX Item "-storepass PASSWORD"
+See \fICommon Options\fR for more details.
+.IP "\fB\-provider\fR \fI\s-1PROVIDER_CLASS_NAME\s0\fR" 4
+.IX Item "-provider PROVIDER_CLASS_NAME"
+See \fICommon Options\fR for more details.
+.IP "\fB\-v\fR" 4
+.IX Item "-v"
+See \fICommon Options\fR for more details.
+.PP
+The \fB\-identitydb\fR command
+.IX Subsection "The -identitydb command"
+.PP
+\&\fB\s-1NOT\s0 \s-1IMPLEMENTED\s0 \s-1YET\s0\fR.
+.PP
+Use this command to import a \s-1JDK\s0 1.1 style Identity Database.
+.IP "\fB\-file\fR \fI\s-1FILE\s0\fR" 4
+.IX Item "-file FILE"
+See \fICommon Options\fR for more details.
+.IP "\fB\-storetype\fR \fI\s-1STORE_TYPE\s0\fR" 4
+.IX Item "-storetype STORE_TYPE"
+See \fICommon Options\fR for more details.
+.IP "\fB\-keystore\fR \fI\s-1URL\s0\fR" 4
+.IX Item "-keystore URL"
+See \fICommon Options\fR for more details.
+.IP "\fB\-storepass\fR \fI\s-1PASSWORD\s0\fR" 4
+.IX Item "-storepass PASSWORD"
+See \fICommon Options\fR for more details.
+.IP "\fB\-provider\fR \fI\s-1PROVIDER_CLASS_NAME\s0\fR" 4
+.IX Item "-provider PROVIDER_CLASS_NAME"
+See \fICommon Options\fR for more details.
+.IP "\fB\-v\fR" 4
+.IX Item "-v"
+See \fICommon Options\fR for more details.
+.PP
+\fIExport commands\fR
+.IX Subsection "Export commands"
+.PP
+The \fB\-certreq\fR command
+.IX Subsection "The -certreq command"
+.PP
+Use this command to generate a PKCS#10 \fICertificate Signing Request\fR (\s-1CSR\s0) and write it to a designated output destination. The contents of the destination should look something like the following:
+.PP
+.Vb 6
+\&        \-\-\-\-\-BEGIN NEW CERTIFICATE REQUEST\-\-\-\-\-
+\&        MI...QAwXzEUMBIGA1UEAwwLcnNuQGdudS5vcmcxGzAZBgNVBAoMElUg
+\&        Q2...A0GA1UEBwwGU3lkbmV5MQwwCgYDVQQIDANOU1cxCzAJBgNVBACC
+\&        ...
+\&        FC...IVwNVOfQLRX+O5kAhQ/a4RTZme2L8PnpvgRwrf7Eg8D6w==
+\&        \-\-\-\-\-END NEW CERTIFICATE REQUEST\-\-\-\-\-
+.Ve
+.PP
+\&\fB\s-1IMPORTANT\s0\fR: Some documentation (e.g. \s-1RSA\s0 examples) claims that the \f(CW\*(C`Attributes\*(C'\fR field, in the \s-1CSR\s0 is \f(CW\*(C`OPTIONAL\*(C'\fR while \s-1RFC\-2986\s0 implies the opposite. This implementation considers this field, by default, as \f(CW\*(C`OPTIONAL\*(C'\fR, unless the option \fB\-attributes\fR is specified on the command line.
+.IP "\fB\-alias\fR \fI\s-1ALIAS\s0\fR" 4
+.IX Item "-alias ALIAS"
+See \fICommon Options\fR for more details.
+.IP "\fB\-sigalg\fR \fI\s-1ALGORITHM\s0\fR" 4
+.IX Item "-sigalg ALGORITHM"
+The canonical name of the digital signature algorithm to use for signing the certificate. If this option is omitted, a default value will be chosen based on the type of the private key associated with the designated \fIAlias\fR. If the private key is a \f(CW\*(C`DSA\*(C'\fR one, the value for the signature algorithm will be \f(CW\*(C`SHA1withDSA\*(C'\fR. If on the other hand the private key is an \f(CW\*(C`RSA\*(C'\fR one, then the tool will use \f(CW\*(C`MD5withRSA\*(C'\fR as the signature algorithm.
+.IP "\fB\-file\fR \fI\s-1FILE\s0\fR" 4
+.IX Item "-file FILE"
+See \fICommon Options\fR for more details.
+.IP "\fB\-keypass\fR \fI\s-1PASSWORD\s0\fR" 4
+.IX Item "-keypass PASSWORD"
+Use this option to specify the password which the tool will use to unlock the \fIKey Entry\fR associated with the designated \fIAlias\fR.
+.Sp
+If this option is omitted, the tool will first attempt to unlock the \fIKey Entry\fR using the same password protecting the key store. If this fails, you will then be prompted to provide a password.
+.IP "\fB\-storetype\fR \fI\s-1STORE_TYPE\s0\fR" 4
+.IX Item "-storetype STORE_TYPE"
+See \fICommon Options\fR for more details.
+.IP "\fB\-keystore\fR \fI\s-1URL\s0\fR" 4
+.IX Item "-keystore URL"
+See \fICommon Options\fR for more details.
+.IP "\fB\-storepass\fR \fI\s-1PASSWORD\s0\fR" 4
+.IX Item "-storepass PASSWORD"
+See \fICommon Options\fR for more details.
+.IP "\fB\-provider\fR \fI\s-1PROVIDER_CLASS_NAME\s0\fR" 4
+.IX Item "-provider PROVIDER_CLASS_NAME"
+See \fICommon Options\fR for more details.
+.IP "\fB\-v\fR" 4
+.IX Item "-v"
+See \fICommon Options\fR for more details.
+.IP "\fB\-attributes\fR" 4
+.IX Item "-attributes"
+Use this option to force the tool to encode a \f(CW\*(C`NULL\*(C'\fR \s-1DER\s0 value in the \s-1CSR\s0 as the value of the \f(CW\*(C`Attributes\*(C'\fR field.
+.PP
+The \fB\-export\fR command
+.IX Subsection "The -export command"
+.PP
+Use this command to export a certificate stored in a key store to a designated output destination, either in binary format (if the \fB\-v\fR option is specified), or in \s-1RFC\-1421\s0 compliant encoding (if the \fB\-rfc\fR option is specified instead).
+.IP "\fB\-alias\fR \fI\s-1ALIAS\s0\fR" 4
+.IX Item "-alias ALIAS"
+See \fICommon Options\fR for more details.
+.IP "\fB\-file\fR \fI\s-1FILE\s0\fR" 4
+.IX Item "-file FILE"
+See \fICommon Options\fR for more details.
+.IP "\fB\-storetype\fR \fI\s-1STORE_TYPE\s0\fR" 4
+.IX Item "-storetype STORE_TYPE"
+See \fICommon Options\fR for more details.
+.IP "\fB\-keystore\fR \fI\s-1URL\s0\fR" 4
+.IX Item "-keystore URL"
+See \fICommon Options\fR for more details.
+.IP "\fB\-storepass\fR \fI\s-1PASSWORD\s0\fR" 4
+.IX Item "-storepass PASSWORD"
+See \fICommon Options\fR for more details.
+.IP "\fB\-provider\fR \fI\s-1PROVIDER_CLASS_NAME\s0\fR" 4
+.IX Item "-provider PROVIDER_CLASS_NAME"
+See \fICommon Options\fR for more details.
+.IP "\fB\-rfc\fR" 4
+.IX Item "-rfc"
+Use \s-1RFC\-1421\s0 specifications when encoding the output.
+.IP "\fB\-v\fR" 4
+.IX Item "-v"
+Output the certificate in binary \s-1DER\s0 encoding. This is the default output format of the command if neither \fB\-rfc\fR nor \f(CW\*(C`\-v\*(C'\fR options were detected on the command line. If both this option and the \fB\-rfc\fR option are detected on the command line, the tool will opt for the \s-1RFC\-1421\s0 style encoding.
+.PP
+\fIDisplay commands\fR
+.IX Subsection "Display commands"
+.PP
+The \fB\-list\fR command
+.IX Subsection "The -list command"
+.PP
+Use this command to print one or all of a key store entries to \f(CW\*(C`STDOUT\*(C'\fR. Usually this command will only print a \fIfingerprint\fR of the certificate, unless either the \fB\-rfc\fR or the \fB\-v\fR option is specified.
+.IP "\fB\-alias\fR \fI\s-1ALIAS\s0\fR" 4
+.IX Item "-alias ALIAS"
+If this option is omitted, the tool will print \s-1ALL\s0 the entries found in the key store.
+.Sp
+See \fICommon Options\fR for more details.
+.IP "\fB\-storetype\fR \fI\s-1STORE_TYPE\s0\fR" 4
+.IX Item "-storetype STORE_TYPE"
+See \fICommon Options\fR for more details.
+.IP "\fB\-keystore\fR \fI\s-1URL\s0\fR" 4
+.IX Item "-keystore URL"
+See \fICommon Options\fR for more details.
+.IP "\fB\-storepass\fR \fI\s-1PASSWORD\s0\fR" 4
+.IX Item "-storepass PASSWORD"
+See \fICommon Options\fR for more details.
+.IP "\fB\-provider\fR \fI\s-1PROVIDER_CLASS_NAME\s0\fR" 4
+.IX Item "-provider PROVIDER_CLASS_NAME"
+See \fICommon Options\fR for more details.
+.IP "\fB\-rfc\fR" 4
+.IX Item "-rfc"
+Use \s-1RFC\-1421\s0 specifications when encoding the output.
+.IP "\fB\-v\fR" 4
+.IX Item "-v"
+Output the certificate in human-readable format. If both this option and the \fB\-rfc\fR option are detected on the command line, the tool will opt for the human-readable form and will not abort the command.
+.PP
+The \fB\-printcert\fR command
+.IX Subsection "The -printcert command"
+.PP
+Use this command to read a certificate from a designated input source and print it to \f(CW\*(C`STDOUT\*(C'\fR in a human-readable form.
+.IP "\fB\-file\fR \fI\s-1FILE\s0\fR" 4
+.IX Item "-file FILE"
+See \fICommon Options\fR for more details.
+.IP "\fB\-v\fR" 4
+.IX Item "-v"
+See \fICommon Options\fR for more details.
+.PP
+\fIManagement commands\fR
+.IX Subsection "Management commands"
+.PP
+The \fB\-keyclone\fR command
+.IX Subsection "The -keyclone command"
+.PP
+Use this command to clone an existing \fIKey Entry\fR and store it under a new (different) \fIAlias\fR protecting, its private key material with possibly a new password.
+.IP "\fB\-alias\fR \fI\s-1ALIAS\s0\fR" 4
+.IX Item "-alias ALIAS"
+See \fICommon Options\fR for more details.
+.IP "\fB\-dest\fR \fI\s-1ALIAS\s0\fR" 4
+.IX Item "-dest ALIAS"
+Use this option to specify the new \fIAlias\fR which will be used to identify the cloned copy of the \fIKey Entry\fR.
+.IP "\fB\-keypass\fR \fI\s-1PASSWORD\s0\fR" 4
+.IX Item "-keypass PASSWORD"
+Use this option to specify the password which the tool will use to unlock the \fIKey Entry\fR associated with the designated \fIAlias\fR.
+.Sp
+If this option is omitted, the tool will first attempt to unlock the \fIKey Entry\fR using the same password protecting the key store. If this fails, you will then be prompted to provide a password.
+.IP "\fB\-new\fR \fI\s-1PASSWORD\s0\fR" 4
+.IX Item "-new PASSWORD"
+Use this option to specify the password protecting the private key material of the newly cloned copy of the \fIKey Entry\fR.
+.IP "\fB\-storetype\fR \fI\s-1STORE_TYPE\s0\fR" 4
+.IX Item "-storetype STORE_TYPE"
+See \fICommon Options\fR for more details.
+.IP "\fB\-keystore\fR \fI\s-1URL\s0\fR" 4
+.IX Item "-keystore URL"
+See \fICommon Options\fR for more details.
+.IP "\fB\-storepass\fR \fI\s-1PASSWORD\s0\fR" 4
+.IX Item "-storepass PASSWORD"
+See \fICommon Options\fR for more details.
+.IP "\fB\-provider\fR \fI\s-1PROVIDER_CLASS_NAME\s0\fR" 4
+.IX Item "-provider PROVIDER_CLASS_NAME"
+See \fICommon Options\fR for more details.
+.IP "\fB\-v\fR" 4
+.IX Item "-v"
+See \fICommon Options\fR for more details.
+.PP
+The \fB\-storepasswd\fR command
+.IX Subsection "The -storepasswd command"
+.PP
+Use this command to change the password protecting a key store.
+.IP "\fB\-new\fR \fI\s-1PASSWORD\s0\fR" 4
+.IX Item "-new PASSWORD"
+The new, and different, password which will be used to protect the designated key store.
+.IP "\fB\-storetype\fR \fI\s-1STORE_TYPE\s0\fR" 4
+.IX Item "-storetype STORE_TYPE"
+See \fICommon Options\fR for more details.
+.IP "\fB\-keystore\fR \fI\s-1URL\s0\fR" 4
+.IX Item "-keystore URL"
+See \fICommon Options\fR for more details.
+.IP "\fB\-storepass\fR \fI\s-1PASSWORD\s0\fR" 4
+.IX Item "-storepass PASSWORD"
+See \fICommon Options\fR for more details.
+.IP "\fB\-provider\fR \fI\s-1PROVIDER_CLASS_NAME\s0\fR" 4
+.IX Item "-provider PROVIDER_CLASS_NAME"
+See \fICommon Options\fR for more details.
+.IP "\fB\-v\fR" 4
+.IX Item "-v"
+See \fICommon Options\fR for more details.
+.PP
+The \fB\-keypasswd\fR command
+.IX Subsection "The -keypasswd command"
+.PP
+Use this command to change the password protecting the private key material of a designated \fIKey Entry\fR.
+.IP "\fB\-alias\fR \fI\s-1ALIAS\s0\fR" 4
+.IX Item "-alias ALIAS"
+See \fICommon Options\fR for more details.
+.Sp
+Use this option to specify the password which the tool will use to unlock the \fIKey Entry\fR associated with the designated \fIAlias\fR.
+.Sp
+If this option is omitted, the tool will first attempt to unlock the \fIKey Entry\fR using the same password protecting the key store. If this fails, you will then be prompted to provide a password.
+.IP "\fB\-new\fR \fI\s-1PASSWORD\s0\fR" 4
+.IX Item "-new PASSWORD"
+The new, and different, password which will be used to protect the private key material of the designated \fIKey Entry\fR.
+.IP "\fB\-storetype\fR \fI\s-1STORE_TYPE\s0\fR" 4
+.IX Item "-storetype STORE_TYPE"
+See \fICommon Options\fR for more details.
+.IP "\fB\-keystore\fR \fI\s-1URL\s0\fR" 4
+.IX Item "-keystore URL"
+See \fICommon Options\fR for more details.
+.IP "\fB\-storepass\fR \fI\s-1PASSWORD\s0\fR" 4
+.IX Item "-storepass PASSWORD"
+See \fICommon Options\fR for more details.
+.IP "\fB\-provider\fR \fI\s-1PROVIDER_CLASS_NAME\s0\fR" 4
+.IX Item "-provider PROVIDER_CLASS_NAME"
+See \fICommon Options\fR for more details.
+.IP "\fB\-v\fR" 4
+.IX Item "-v"
+See \fICommon Options\fR for more details.
+.PP
+The \fB\-delete\fR command
+.IX Subsection "The -delete command"
+.PP
+Use this command to delete a designated key store entry.
+.IP "\fB\-alias\fR \fI\s-1ALIAS\s0\fR" 4
+.IX Item "-alias ALIAS"
+See \fICommon Options\fR for more details.
+.IP "\fB\-storetype\fR \fI\s-1STORE_TYPE\s0\fR" 4
+.IX Item "-storetype STORE_TYPE"
+See \fICommon Options\fR for more details.
+.IP "\fB\-keystore\fR \fI\s-1URL\s0\fR" 4
+.IX Item "-keystore URL"
+See \fICommon Options\fR for more details.
+.IP "\fB\-storepass\fR \fI\s-1PASSWORD\s0\fR" 4
+.IX Item "-storepass PASSWORD"
+See \fICommon Options\fR for more details.
+.IP "\fB\-provider\fR \fI\s-1PROVIDER_CLASS_NAME\s0\fR" 4
+.IX Item "-provider PROVIDER_CLASS_NAME"
+See \fICommon Options\fR for more details.
+.IP "\fB\-v\fR" 4
+.IX Item "-v"
+See \fICommon Options\fR for more details.
+.SH "BUGS"
+.IX Header "BUGS"
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+.SH "AUTHOR"
+.IX Header "AUTHOR"
diff --git a/libjava/classpath/doc/gnative2ascii.1 b/libjava/classpath/doc/gnative2ascii.1
new file mode 100644
index 000000000..e89fdbb26
--- /dev/null
+++ b/libjava/classpath/doc/gnative2ascii.1
@@ -0,0 +1,165 @@
+.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings.  \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
+.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
+.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
+.\" nothing in troff, for use with C<>.
+.tr \(*W-
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+.    ds -- \(*W-
+.    ds PI pi
+.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
+.    ds L" ""
+.    ds R" ""
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds -- \|\(em\|
+.    ds PI \(*p
+.    ds L" ``
+.    ds R" ''
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.ie \nF \{\
+.    de IX
+.    tm Index:\\$1\t\\n%\t"\\$2"
+..
+.    nr % 0
+.    rr F
+.\}
+.el \{\
+.    de IX
+..
+.\}
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
+.    \" fudge factors for nroff and troff
+.if n \{\
+.    ds #H 0
+.    ds #V .8m
+.    ds #F .3m
+.    ds #[ \f1
+.    ds #] \fP
+.\}
+.if t \{\
+.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+.    ds #V .6m
+.    ds #F 0
+.    ds #[ \&
+.    ds #] \&
+.\}
+.    \" simple accents for nroff and troff
+.if n \{\
+.    ds ' \&
+.    ds ` \&
+.    ds ^ \&
+.    ds , \&
+.    ds ~ ~
+.    ds /
+.\}
+.if t \{\
+.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+.    \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+.    \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+.    \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+.    ds : e
+.    ds 8 ss
+.    ds o a
+.    ds d- d\h'-1'\(ga
+.    ds D- D\h'-1'\(hy
+.    ds th \o'bp'
+.    ds Th \o'LP'
+.    ds ae ae
+.    ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "GNATIVE2ASCII 1"
+.TH GNATIVE2ASCII 1 "2013-04-12" "0.99-pre" "GNU"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH "NAME"
+gnative2ascii \- \- An encoding converter
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+gnative2ascii [\fI\s-1OPTIONS\s0\fR]... [\fI\s-1INPUTFILE\s0\fR [\fI\s-1OUTPUTFILE\s0\fR]]
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+To be written ...
+.SH "OPTIONS"
+.IX Header "OPTIONS"
+.IP "\fB\-encoding\fR \fI\s-1NAME\s0\fR" 4
+.IX Item "-encoding NAME"
+Set the encoding to use.
+.IP "\fB\-reversed\fR" 4
+.IX Item "-reversed"
+Convert from encoding to native.
+.PP
+Standard options:
+.IP "\fB\-help\fR" 4
+.IX Item "-help"
+Print help text, then exit.
+.IP "\fB\-version\fR" 4
+.IX Item "-version"
+Print version number, then exit.
+.IP "\fB\-J\fR\fI\s-1OPTION\s0\fR" 4
+.IX Item "-JOPTION"
+Pass argument to the Java runtime.
+.SH "BUGS"
+.IX Header "BUGS"
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fIjavac\fR\|(1), ...
+.SH "AUTHOR"
+.IX Header "AUTHOR"
diff --git a/libjava/classpath/doc/gorbd.1 b/libjava/classpath/doc/gorbd.1
new file mode 100644
index 000000000..b54d6943e
--- /dev/null
+++ b/libjava/classpath/doc/gorbd.1
@@ -0,0 +1,172 @@
+.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings.  \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
+.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
+.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
+.\" nothing in troff, for use with C<>.
+.tr \(*W-
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+.    ds -- \(*W-
+.    ds PI pi
+.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
+.    ds L" ""
+.    ds R" ""
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds -- \|\(em\|
+.    ds PI \(*p
+.    ds L" ``
+.    ds R" ''
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.ie \nF \{\
+.    de IX
+.    tm Index:\\$1\t\\n%\t"\\$2"
+..
+.    nr % 0
+.    rr F
+.\}
+.el \{\
+.    de IX
+..
+.\}
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
+.    \" fudge factors for nroff and troff
+.if n \{\
+.    ds #H 0
+.    ds #V .8m
+.    ds #F .3m
+.    ds #[ \f1
+.    ds #] \fP
+.\}
+.if t \{\
+.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+.    ds #V .6m
+.    ds #F 0
+.    ds #[ \&
+.    ds #] \&
+.\}
+.    \" simple accents for nroff and troff
+.if n \{\
+.    ds ' \&
+.    ds ` \&
+.    ds ^ \&
+.    ds , \&
+.    ds ~ ~
+.    ds /
+.\}
+.if t \{\
+.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+.    \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+.    \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+.    \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+.    ds : e
+.    ds 8 ss
+.    ds o a
+.    ds d- d\h'-1'\(ga
+.    ds D- D\h'-1'\(hy
+.    ds th \o'bp'
+.    ds Th \o'LP'
+.    ds ae ae
+.    ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "GORBD 1"
+.TH GORBD 1 "2013-04-12" "0.99-pre" "GNU"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH "NAME"
+gorbd \- \- An object request broker daemon
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+gorbd ...
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+To be written ...
+.SH "OPTIONS"
+.IX Header "OPTIONS"
+.IP "\fB\-ORBInitialPort\fR \fI\s-1PORT\s0\fR" 4
+.IX Item "-ORBInitialPort PORT"
+Port on which persistent naming service is to be started.
+.IP "\fB\-ior\fR \fI\s-1FILE\s0\fR" 4
+.IX Item "-ior FILE"
+File in which to store persistent naming service's \s-1IOR\s0 reference
+.IP "\fB\-directory\fR \fI\s-1DIR\s0\fR" 4
+.IX Item "-directory DIR"
+Directory in which to store persistent data.
+.IP "\fB\-restart\fR" 4
+.IX Item "-restart"
+Restart persistent naming service, clearing persistent naming
+database.
+.PP
+Standard options:
+.IP "\fB\-help\fR" 4
+.IX Item "-help"
+Print help text, then exit.
+.IP "\fB\-version\fR" 4
+.IX Item "-version"
+Print version number, then exit.
+.IP "\fB\-J\fR\fI\s-1OPTION\s0\fR" 4
+.IX Item "-JOPTION"
+Pass argument to the Java runtime.
+.SH "BUGS"
+.IX Header "BUGS"
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fIjava\fR\|(1), ...
+.SH "AUTHOR"
+.IX Header "AUTHOR"
diff --git a/libjava/classpath/doc/grmid.1 b/libjava/classpath/doc/grmid.1
new file mode 100644
index 000000000..3d135cff0
--- /dev/null
+++ b/libjava/classpath/doc/grmid.1
@@ -0,0 +1,184 @@
+.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings.  \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
+.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
+.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
+.\" nothing in troff, for use with C<>.
+.tr \(*W-
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+.    ds -- \(*W-
+.    ds PI pi
+.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
+.    ds L" ""
+.    ds R" ""
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds -- \|\(em\|
+.    ds PI \(*p
+.    ds L" ``
+.    ds R" ''
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.ie \nF \{\
+.    de IX
+.    tm Index:\\$1\t\\n%\t"\\$2"
+..
+.    nr % 0
+.    rr F
+.\}
+.el \{\
+.    de IX
+..
+.\}
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
+.    \" fudge factors for nroff and troff
+.if n \{\
+.    ds #H 0
+.    ds #V .8m
+.    ds #F .3m
+.    ds #[ \f1
+.    ds #] \fP
+.\}
+.if t \{\
+.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+.    ds #V .6m
+.    ds #F 0
+.    ds #[ \&
+.    ds #] \&
+.\}
+.    \" simple accents for nroff and troff
+.if n \{\
+.    ds ' \&
+.    ds ` \&
+.    ds ^ \&
+.    ds , \&
+.    ds ~ ~
+.    ds /
+.\}
+.if t \{\
+.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+.    \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+.    \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+.    \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+.    ds : e
+.    ds 8 ss
+.    ds o a
+.    ds d- d\h'-1'\(ga
+.    ds D- D\h'-1'\(hy
+.    ds th \o'bp'
+.    ds Th \o'LP'
+.    ds ae ae
+.    ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "GRMID 1"
+.TH GRMID 1 "2013-04-12" "0.99-pre" "GNU"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH "NAME"
+grmid \- \- RMI activation system daemon
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+grmid [\fI\s-1OPTIONS\s0\fR]...
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+\&\fBrmiregistry\fR starts a remote object registry on the current
+host.  If no port number is specified, then port 1099 is used.
+.SH "OPTIONS"
+.IX Header "OPTIONS"
+Activation process control:
+.IP "\fB\-port\fR \fI\s-1PORT\s0\fR" 4
+.IX Item "-port PORT"
+Port on which activation system is to be started.
+.IP "\fB\-restart\fR" 4
+.IX Item "-restart"
+Restart activation system, clearing persistent naming database, if
+any.
+.IP "\fB\-stop\fR" 4
+.IX Item "-stop"
+Stop activation system.
+.PP
+Persistence:
+.IP "\fB\-persistent\fR" 4
+.IX Item "-persistent"
+Make activation system persistent.
+.IP "\fB\-directory\fR \fI\s-1DIR\s0\fR" 4
+.IX Item "-directory DIR"
+Directory in which to store persistent data.
+.PP
+Debugging:
+.IP "\fB\-verbose\fR" 4
+.IX Item "-verbose"
+Log binding events to standard out.
+.PP
+Standard options:
+.IP "\fB\-help\fR" 4
+.IX Item "-help"
+Print help text, then exit.
+.IP "\fB\-version\fR" 4
+.IX Item "-version"
+Print version number, then exit.
+.IP "\fB\-J\fR\fI\s-1OPTION\s0\fR" 4
+.IX Item "-JOPTION"
+Pass argument to the Java runtime.
+.SH "BUGS"
+.IX Header "BUGS"
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fIjava\fR\|(1), ...
+.SH "AUTHOR"
+.IX Header "AUTHOR"
diff --git a/libjava/classpath/doc/grmiregistry.1 b/libjava/classpath/doc/grmiregistry.1
new file mode 100644
index 000000000..b830c9429
--- /dev/null
+++ b/libjava/classpath/doc/grmiregistry.1
@@ -0,0 +1,181 @@
+.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings.  \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
+.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
+.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
+.\" nothing in troff, for use with C<>.
+.tr \(*W-
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+.    ds -- \(*W-
+.    ds PI pi
+.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
+.    ds L" ""
+.    ds R" ""
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds -- \|\(em\|
+.    ds PI \(*p
+.    ds L" ``
+.    ds R" ''
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.ie \nF \{\
+.    de IX
+.    tm Index:\\$1\t\\n%\t"\\$2"
+..
+.    nr % 0
+.    rr F
+.\}
+.el \{\
+.    de IX
+..
+.\}
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
+.    \" fudge factors for nroff and troff
+.if n \{\
+.    ds #H 0
+.    ds #V .8m
+.    ds #F .3m
+.    ds #[ \f1
+.    ds #] \fP
+.\}
+.if t \{\
+.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+.    ds #V .6m
+.    ds #F 0
+.    ds #[ \&
+.    ds #] \&
+.\}
+.    \" simple accents for nroff and troff
+.if n \{\
+.    ds ' \&
+.    ds ` \&
+.    ds ^ \&
+.    ds , \&
+.    ds ~ ~
+.    ds /
+.\}
+.if t \{\
+.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+.    \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+.    \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+.    \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+.    ds : e
+.    ds 8 ss
+.    ds o a
+.    ds d- d\h'-1'\(ga
+.    ds D- D\h'-1'\(hy
+.    ds th \o'bp'
+.    ds Th \o'LP'
+.    ds ae ae
+.    ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "GRMIREGISTRY 1"
+.TH GRMIREGISTRY 1 "2013-04-12" "0.99-pre" "GNU"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH "NAME"
+grmiregistry \- \- Remote object registry
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+grmiregistry [\fI\s-1OPTIONS\s0\fR]... \fI\s-1PORT\s0\fR
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+\&\fBgrmiregistry\fR starts a remote object registry on the current
+host.  If no port number is specified, then port 1099 is used.
+.SH "OPTIONS"
+.IX Header "OPTIONS"
+Registry process control:
+.IP "\fB\-restart\fR" 4
+.IX Item "-restart"
+Restart \s-1RMI\s0 naming service, clearing persistent naming database, if
+any.
+.IP "\fB\-stop\fR" 4
+.IX Item "-stop"
+Stop \s-1RMI\s0 naming service.
+.PP
+Persistence:
+.IP "\fB\-persistent\fR" 4
+.IX Item "-persistent"
+Make \s-1RMI\s0 naming service persistent.
+.IP "\fB\-directory\fR \fI\s-1DIR\s0\fR" 4
+.IX Item "-directory DIR"
+Directory in which to store persistent data.
+.PP
+Debugging:
+.IP "\fB\-verbose\fR" 4
+.IX Item "-verbose"
+Log binding events to standard out.
+.PP
+Standard options:
+.IP "\fB\-help\fR" 4
+.IX Item "-help"
+Print help text, then exit.
+.IP "\fB\-version\fR" 4
+.IX Item "-version"
+Print version number, then exit.
+.IP "\fB\-J\fR\fI\s-1OPTION\s0\fR" 4
+.IX Item "-JOPTION"
+Pass argument to the Java runtime.
+.SH "BUGS"
+.IX Header "BUGS"
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fIjava\fR\|(1), ...
+.SH "AUTHOR"
+.IX Header "AUTHOR"
diff --git a/libjava/classpath/doc/gserialver.1 b/libjava/classpath/doc/gserialver.1
new file mode 100644
index 000000000..23326e1f5
--- /dev/null
+++ b/libjava/classpath/doc/gserialver.1
@@ -0,0 +1,162 @@
+.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings.  \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
+.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
+.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
+.\" nothing in troff, for use with C<>.
+.tr \(*W-
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+.    ds -- \(*W-
+.    ds PI pi
+.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
+.    ds L" ""
+.    ds R" ""
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds -- \|\(em\|
+.    ds PI \(*p
+.    ds L" ``
+.    ds R" ''
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.ie \nF \{\
+.    de IX
+.    tm Index:\\$1\t\\n%\t"\\$2"
+..
+.    nr % 0
+.    rr F
+.\}
+.el \{\
+.    de IX
+..
+.\}
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
+.    \" fudge factors for nroff and troff
+.if n \{\
+.    ds #H 0
+.    ds #V .8m
+.    ds #F .3m
+.    ds #[ \f1
+.    ds #] \fP
+.\}
+.if t \{\
+.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+.    ds #V .6m
+.    ds #F 0
+.    ds #[ \&
+.    ds #] \&
+.\}
+.    \" simple accents for nroff and troff
+.if n \{\
+.    ds ' \&
+.    ds ` \&
+.    ds ^ \&
+.    ds , \&
+.    ds ~ ~
+.    ds /
+.\}
+.if t \{\
+.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+.    \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+.    \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+.    \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+.    ds : e
+.    ds 8 ss
+.    ds o a
+.    ds d- d\h'-1'\(ga
+.    ds D- D\h'-1'\(hy
+.    ds th \o'bp'
+.    ds Th \o'LP'
+.    ds ae ae
+.    ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "GSERIALVER 1"
+.TH GSERIALVER 1 "2013-04-12" "0.99-pre" "GNU"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH "NAME"
+gserialver \- version command
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+gserialver [\fI\s-1OPTIONS\s0\fR]... \fI\s-1CLASS\s0\fR...
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+Print the serialVersionUID of the specified classes.
+.SH "OPTIONS"
+.IX Header "OPTIONS"
+.IP "\fB\-classpath\fR \fI\s-1PATH\s0\fR" 4
+.IX Item "-classpath PATH"
+Class path to use to find classes.
+.PP
+Standard options:
+.IP "\fB\-help\fR" 4
+.IX Item "-help"
+Print help text, then exit.
+.IP "\fB\-version\fR" 4
+.IX Item "-version"
+Print version number, then exit.
+.IP "\fB\-J\fR\fI\s-1OPTION\s0\fR" 4
+.IX Item "-JOPTION"
+Pass argument to the Java runtime.
+.SH "BUGS"
+.IX Header "BUGS"
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fIjavac\fR\|(1), ...
+.SH "AUTHOR"
+.IX Header "AUTHOR"
diff --git a/libjava/classpath/doc/gtnameserv.1 b/libjava/classpath/doc/gtnameserv.1
new file mode 100644
index 000000000..f7d821a71
--- /dev/null
+++ b/libjava/classpath/doc/gtnameserv.1
@@ -0,0 +1,165 @@
+.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings.  \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
+.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
+.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
+.\" nothing in troff, for use with C<>.
+.tr \(*W-
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+.    ds -- \(*W-
+.    ds PI pi
+.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
+.    ds L" ""
+.    ds R" ""
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds -- \|\(em\|
+.    ds PI \(*p
+.    ds L" ``
+.    ds R" ''
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.ie \nF \{\
+.    de IX
+.    tm Index:\\$1\t\\n%\t"\\$2"
+..
+.    nr % 0
+.    rr F
+.\}
+.el \{\
+.    de IX
+..
+.\}
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
+.    \" fudge factors for nroff and troff
+.if n \{\
+.    ds #H 0
+.    ds #V .8m
+.    ds #F .3m
+.    ds #[ \f1
+.    ds #] \fP
+.\}
+.if t \{\
+.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+.    ds #V .6m
+.    ds #F 0
+.    ds #[ \&
+.    ds #] \&
+.\}
+.    \" simple accents for nroff and troff
+.if n \{\
+.    ds ' \&
+.    ds ` \&
+.    ds ^ \&
+.    ds , \&
+.    ds ~ ~
+.    ds /
+.\}
+.if t \{\
+.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+.    \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+.    \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+.    \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+.    ds : e
+.    ds 8 ss
+.    ds o a
+.    ds d- d\h'-1'\(ga
+.    ds D- D\h'-1'\(hy
+.    ds th \o'bp'
+.    ds Th \o'LP'
+.    ds ae ae
+.    ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "GTNAMESERV 1"
+.TH GTNAMESERV 1 "2013-04-12" "0.99-pre" "GNU"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH "NAME"
+gtnameserv \- Naming service
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+tnameserv [\fI\s-1OPTIONS\s0\fR]
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+To be written ...
+.SH "OPTIONS"
+.IX Header "OPTIONS"
+.IP "\fB\-ORBInitialPort\fR \fI\s-1PORT\s0\fR" 4
+.IX Item "-ORBInitialPort PORT"
+Port on which naming service is to be started.
+.IP "\fB\-ior\fR \fI\s-1FILE\s0\fR" 4
+.IX Item "-ior FILE"
+File in which to store naming service's \s-1IOR\s0 reference.
+.PP
+Standard options:
+.IP "\fB\-help\fR" 4
+.IX Item "-help"
+Print help text, then exit.
+.IP "\fB\-version\fR" 4
+.IX Item "-version"
+Print version number, then exit.
+.IP "\fB\-J\fR\fI\s-1OPTION\s0\fR" 4
+.IX Item "-JOPTION"
+Pass argument to the Java runtime.
+.SH "BUGS"
+.IX Header "BUGS"
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fIjava\fR\|(1), ...
+.SH "AUTHOR"
+.IX Header "AUTHOR"
diff --git a/libjava/classpath/doc/texi2pod.pl b/libjava/classpath/doc/texi2pod.pl
new file mode 100755
index 000000000..e7b983bd2
--- /dev/null
+++ b/libjava/classpath/doc/texi2pod.pl
@@ -0,0 +1,478 @@
+#! /usr/bin/perl -w
+
+#   Copyright (C) 1999, 2000, 2001, 2003 Free Software Foundation, Inc.
+
+# This file is part of GCC.
+
+# GCC 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, or (at your option)
+# any later version.
+
+# GCC 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 GCC; see the file COPYING.  If not, write to
+# the Free Software Foundation, 51 Franklin Street, Fifth Floor,
+# Boston MA 02110-1301, USA.
+
+# This does trivial (and I mean _trivial_) conversion of Texinfo
+# markup to Perl POD format.  It's intended to be used to extract
+# something suitable for a manpage from a Texinfo document.
+
+$output = 0;
+$skipping = 0;
+%sects = ();
+$section = "";
+@icstack = ();
+@endwstack = ();
+@skstack = ();
+@instack = ();
+$shift = "";
+%defs = ();
+$fnno = 1;
+$inf = "";
+$ibase = "";
+@ipath = ();
+
+while ($_ = shift) {
+    if (/^-D(.*)$/) {
+	if ($1 ne "") {
+	    $flag = $1;
+	} else {
+	    $flag = shift;
+	}
+	$value = "";
+	($flag, $value) = ($flag =~ /^([^=]+)(?:=(.+))?/);
+	die "no flag specified for -D\n"
+	    unless $flag ne "";
+	die "flags may only contain letters, digits, hyphens, dashes and underscores\n"
+	    unless $flag =~ /^[a-zA-Z0-9_-]+$/;
+	$defs{$flag} = $value;
+    } elsif (/^-I(.*)$/) {
+	if ($1 ne "") {
+	    $flag = $1;
+	} else {
+	    $flag = shift;
+	}
+        push (@ipath, $flag);
+    } elsif (/^-/) {
+	usage();
+    } else {
+	$in = $_, next unless defined $in;
+	$out = $_, next unless defined $out;
+	usage();
+    }
+}
+
+if (defined $in) {
+    $inf = gensym();
+    open($inf, "<$in") or die "opening \"$in\": $!\n";
+    $ibase = $1 if $in =~ m|^(.+)/[^/]+$|;
+} else {
+    $inf = \*STDIN;
+}
+
+if (defined $out) {
+    open(STDOUT, ">$out") or die "opening \"$out\": $!\n";
+}
+
+while(defined $inf) {
+while(<$inf>) {
+    # Certain commands are discarded without further processing.
+    /^\@(?:
+	 [a-z]+index		# @*index: useful only in complete manual
+	 |need			# @need: useful only in printed manual
+	 |(?:end\s+)?group	# @group .. @end group: ditto
+	 |page			# @page: ditto
+	 |node			# @node: useful only in .info file
+	 |(?:end\s+)?ifnottex   # @ifnottex .. @end ifnottex: use contents
+	)\b/x and next;
+
+    chomp;
+
+    # Look for filename and title markers.
+    /^\@setfilename\s+([^.]+)/ and $fn = $1, next;
+    /^\@settitle\s+([^.]+)/ and $tl = postprocess($1), next;
+
+    # Identify a man title but keep only the one we are interested in.
+    /^\@c\s+man\s+title\s+([A-Za-z0-9-]+)\s+(.+)/ and do {
+	if (exists $defs{$1}) {
+	    $fn = $1;
+	    $tl = postprocess($2);
+	}
+	next;
+    };
+
+    # Look for blocks surrounded by @c man begin SECTION ... @c man end.
+    # This really oughta be @ifman ... @end ifman and the like, but such
+    # would require rev'ing all other Texinfo translators.
+    /^\@c\s+man\s+begin\s+([A-Z]+)\s+([A-Za-z0-9-]+)/ and do {
+	$output = 1 if exists $defs{$2};
+        $sect = $1;
+	next;
+    };
+    /^\@c\s+man\s+begin\s+([A-Z]+)/ and $sect = $1, $output = 1, next;
+    /^\@c\s+man\s+end/ and do {
+	$sects{$sect} = "" unless exists $sects{$sect};
+	$sects{$sect} .= postprocess($section);
+	$section = "";
+	$output = 0;
+	next;
+    };
+
+    # handle variables
+    /^\@set\s+([a-zA-Z0-9_-]+)\s*(.*)$/ and do {
+	$defs{$1} = $2;
+	next;
+    };
+    /^\@clear\s+([a-zA-Z0-9_-]+)/ and do {
+	delete $defs{$1};
+	next;
+    };
+
+    next unless $output;
+
+    # Discard comments.  (Can't do it above, because then we'd never see
+    # @c man lines.)
+    /^\@c\b/ and next;
+
+    # End-block handler goes up here because it needs to operate even
+    # if we are skipping.
+    /^\@end\s+([a-z]+)/ and do {
+	# Ignore @end foo, where foo is not an operation which may
+	# cause us to skip, if we are presently skipping.
+	my $ended = $1;
+	next if $skipping && $ended !~ /^(?:ifset|ifclear|ignore|menu|iftex|copying)$/;
+
+	die "\@end $ended without \@$ended at line $.\n" unless defined $endw;
+	die "\@$endw ended by \@end $ended at line $.\n" unless $ended eq $endw;
+
+	$endw = pop @endwstack;
+
+	if ($ended =~ /^(?:ifset|ifclear|ignore|menu|iftex)$/) {
+	    $skipping = pop @skstack;
+	    next;
+	} elsif ($ended =~ /^(?:example|smallexample|display)$/) {
+	    $shift = "";
+	    $_ = "";	# need a paragraph break
+	} elsif ($ended =~ /^(?:itemize|enumerate|[fv]?table)$/) {
+	    $_ = "\n=back\n";
+	    $ic = pop @icstack;
+	} elsif ($ended eq "multitable") {
+	    $_ = "\n=back\n";
+	} else {
+	    die "unknown command \@end $ended at line $.\n";
+	}
+    };
+
+    # We must handle commands which can cause skipping even while we
+    # are skipping, otherwise we will not process nested conditionals
+    # correctly.
+    /^\@ifset\s+([a-zA-Z0-9_-]+)/ and do {
+	push @endwstack, $endw;
+	push @skstack, $skipping;
+	$endw = "ifset";
+	$skipping = 1 unless exists $defs{$1};
+	next;
+    };
+
+    /^\@ifclear\s+([a-zA-Z0-9_-]+)/ and do {
+	push @endwstack, $endw;
+	push @skstack, $skipping;
+	$endw = "ifclear";
+	$skipping = 1 if exists $defs{$1};
+	next;
+    };
+
+    /^\@(ignore|menu|iftex|copying)\b/ and do {
+	push @endwstack, $endw;
+	push @skstack, $skipping;
+	$endw = $1;
+	$skipping = 1;
+	next;
+    };
+
+    next if $skipping;
+
+    # Character entities.  First the ones that can be replaced by raw text
+    # or discarded outright:
+    s/\@copyright\{\}/(c)/g;
+    s/\@dots\{\}/.../g;
+    s/\@enddots\{\}/..../g;
+    s/\@([.!? ])/$1/g;
+    s/\@[:-]//g;
+    s/\@bullet(?:\{\})?/*/g;
+    s/\@TeX\{\}/TeX/g;
+    s/\@pounds\{\}/\#/g;
+    s/\@minus(?:\{\})?/-/g;
+    s/\\,/,/g;
+
+    # Now the ones that have to be replaced by special escapes
+    # (which will be turned back into text by unmunge())
+    s/&/&amp;/g;
+    s/\@\{/&lbrace;/g;
+    s/\@\}/&rbrace;/g;
+    s/\@\@/&at;/g;
+
+    # Inside a verbatim block, handle @var specially.
+    if ($shift ne "") {
+	s/\@var\{([^\}]*)\}/<$1>/g;
+    }
+
+    # POD doesn't interpret E<> inside a verbatim block.
+    if ($shift eq "") {
+	s/</&lt;/g;
+	s/>/&gt;/g;
+    } else {
+	s/</&LT;/g;
+	s/>/&GT;/g;
+    }
+
+    # Single line command handlers.
+
+    /^\@include\s+(.+)$/ and do {
+	push @instack, $inf;
+	$inf = gensym();
+	$file = postprocess($1);
+
+	# Try cwd and $ibase, then explicit -I paths.
+	$done = 0;
+	foreach $path ("", $ibase, @ipath) {
+	    $mypath = $file;
+	    $mypath = $path . "/" . $mypath if ($path ne "");
+	    open($inf, "<" . $mypath) and ($done = 1, last);
+	}
+	die "cannot find $file" if !$done;
+	next;
+    };
+
+    /^\@(?:section|unnumbered|unnumberedsec|center)\s+(.+)$/
+	and $_ = "\n=head2 $1\n";
+    /^\@subsection\s+(.+)$/
+	and $_ = "\n=head3 $1\n";
+    /^\@subsubsection\s+(.+)$/
+	and $_ = "\n=head4 $1\n";
+
+    # Block command handlers:
+    /^\@itemize(?:\s+(\@[a-z]+|\*|-))?/ and do {
+	push @endwstack, $endw;
+	push @icstack, $ic;
+	if (defined $1) {
+	    $ic = $1;
+	} else {
+	    $ic = '@bullet';
+	}
+	$_ = "\n=over 4\n";
+	$endw = "itemize";
+    };
+
+    /^\@enumerate(?:\s+([a-zA-Z0-9]+))?/ and do {
+	push @endwstack, $endw;
+	push @icstack, $ic;
+	if (defined $1) {
+	    $ic = $1 . ".";
+	} else {
+	    $ic = "1.";
+	}
+	$_ = "\n=over 4\n";
+	$endw = "enumerate";
+    };
+
+    /^\@multitable\s.*/ and do {
+	push @endwstack, $endw;
+	$endw = "multitable";
+	$_ = "\n=over 4\n";
+    };
+
+    /^\@([fv]?table)\s+(\@[a-z]+)/ and do {
+	push @endwstack, $endw;
+	push @icstack, $ic;
+	$endw = $1;
+	$ic = $2;
+	$ic =~ s/\@(?:samp|strong|key|gcctabopt|env)/B/;
+	$ic =~ s/\@(?:code|kbd)/C/;
+	$ic =~ s/\@(?:dfn|var|emph|cite|i)/I/;
+	$ic =~ s/\@(?:file)/F/;
+	$_ = "\n=over 4\n";
+    };
+
+    /^\@((?:small)?example|display)/ and do {
+	push @endwstack, $endw;
+	$endw = $1;
+	$shift = "\t";
+	$_ = "";	# need a paragraph break
+    };
+
+    /^\@item\s+(.*\S)\s*$/ and $endw eq "multitable" and do {
+	@columns = ();
+	for $column (split (/\s*\@tab\s*/, $1)) {
+	    # @strong{...} is used a @headitem work-alike
+	    $column =~ s/^\@strong{(.*)}$/$1/;
+	    push @columns, $column;
+	}
+	$_ = "\n=item ".join (" : ", @columns)."\n";
+    };
+
+    /^\@itemx?\s*(.+)?$/ and do {
+	if (defined $1) {
+	    # Entity escapes prevent munging by the <> processing below.
+	    $_ = "\n=item $ic\&LT;$1\&GT;\n";
+	} else {
+	    $_ = "\n=item $ic\n";
+	    $ic =~ y/A-Ya-y/B-Zb-z/;
+	    $ic =~ s/(\d+)/$1 + 1/eg;
+	}
+    };
+
+    $section .= $shift.$_."\n";
+}
+# End of current file.
+close($inf);
+$inf = pop @instack;
+}
+
+die "No filename or title\n" unless defined $fn && defined $tl;
+
+$sects{NAME} = "$fn \- $tl\n";
+$sects{FOOTNOTES} .= "=back\n" if exists $sects{FOOTNOTES};
+
+for $sect (qw(NAME SYNOPSIS DESCRIPTION OPTIONS ENVIRONMENT FILES
+	      BUGS NOTES FOOTNOTES SEEALSO AUTHOR COPYRIGHT)) {
+    if(exists $sects{$sect}) {
+	$head = $sect;
+	$head =~ s/SEEALSO/SEE ALSO/;
+	print "=head1 $head\n\n";
+	print scalar unmunge ($sects{$sect});
+	print "\n";
+    }
+}
+
+sub usage
+{
+    die "usage: $0 [-D toggle...] [infile [outfile]]\n";
+}
+
+sub postprocess
+{
+    local $_ = $_[0];
+
+    # @value{foo} is replaced by whatever 'foo' is defined as.
+    while (m/(\@value\{([a-zA-Z0-9_-]+)\})/g) {
+	if (! exists $defs{$2}) {
+	    print STDERR "Option $2 not defined\n";
+	    s/\Q$1\E//;
+	} else {
+	    $value = $defs{$2};
+	    s/\Q$1\E/$value/;
+	}
+    }
+
+    # Formatting commands.
+    # Temporary escape for @r.
+    s/\@r\{([^\}]*)\}/R<$1>/g;
+    s/\@(?:dfn|var|emph|cite|i)\{([^\}]*)\}/I<$1>/g;
+    s/\@(?:code|kbd)\{([^\}]*)\}/C<$1>/g;
+    s/\@(?:gccoptlist|samp|strong|key|option|env|command|b)\{([^\}]*)\}/B<$1>/g;
+    s/\@sc\{([^\}]*)\}/\U$1/g;
+    s/\@file\{([^\}]*)\}/F<$1>/g;
+    s/\@w\{([^\}]*)\}/S<$1>/g;
+    s/\@(?:dmn|math)\{([^\}]*)\}/$1/g;
+
+    # keep references of the form @ref{...}, print them bold
+    s/\@(?:ref)\{([^\}]*)\}/B<$1>/g;
+
+    # Change double single quotes to double quotes.
+    s/''/"/g;
+    s/``/"/g;
+
+    # Cross references are thrown away, as are @noindent and @refill.
+    # (@noindent is impossible in .pod, and @refill is unnecessary.)
+    # @* is also impossible in .pod; we discard it and any newline that
+    # follows it.  Similarly, our macro @gol must be discarded.
+
+    s/\(?\@xref\{(?:[^\}]*)\}(?:[^.<]|(?:<[^<>]*>))*\.\)?//g;
+    s/\s+\(\@pxref\{(?:[^\}]*)\}\)//g;
+    s/;\s+\@pxref\{(?:[^\}]*)\}//g;
+    s/\@noindent\s*//g;
+    s/\@refill//g;
+    s/\@gol//g;
+    s/\@\*\s*\n?//g;
+
+    # Anchors are thrown away
+    s/\@anchor\{(?:[^\}]*)\}//g;
+
+    # @uref can take one, two, or three arguments, with different
+    # semantics each time.  @url and @email are just like @uref with
+    # one argument, for our purposes.
+    s/\@(?:uref|url|email)\{([^\},]*)\}/&lt;B<$1>&gt;/g;
+    s/\@uref\{([^\},]*),([^\},]*)\}/$2 (C<$1>)/g;
+    s/\@uref\{([^\},]*),([^\},]*),([^\},]*)\}/$3/g;
+
+    # Un-escape <> at this point.
+    s/&LT;/</g;
+    s/&GT;/>/g;
+
+    # Now un-nest all B<>, I<>, R<>.  Theoretically we could have
+    # indefinitely deep nesting; in practice, one level suffices.
+    1 while s/([BIR])<([^<>]*)([BIR])<([^<>]*)>/$1<$2>$3<$4>$1</g;
+
+    # Replace R<...> with bare ...; eliminate empty markup, B<>;
+    # shift white space at the ends of [BI]<...> expressions outside
+    # the expression.
+    s/R<([^<>]*)>/$1/g;
+    s/[BI]<>//g;
+    s/([BI])<(\s+)([^>]+)>/$2$1<$3>/g;
+    s/([BI])<([^>]+?)(\s+)>/$1<$2>$3/g;
+
+    # Extract footnotes.  This has to be done after all other
+    # processing because otherwise the regexp will choke on formatting
+    # inside @footnote.
+    while (/\@footnote/g) {
+	s/\@footnote\{([^\}]+)\}/[$fnno]/;
+	add_footnote($1, $fnno);
+	$fnno++;
+    }
+
+    return $_;
+}
+
+sub unmunge
+{
+    # Replace escaped symbols with their equivalents.
+    local $_ = $_[0];
+
+    s/&lt;/E<lt>/g;
+    s/&gt;/E<gt>/g;
+    s/&lbrace;/\{/g;
+    s/&rbrace;/\}/g;
+    s/&at;/\@/g;
+    s/&amp;/&/g;
+    return $_;
+}
+
+sub add_footnote
+{
+    unless (exists $sects{FOOTNOTES}) {
+	$sects{FOOTNOTES} = "\n=over 4\n\n";
+    }
+
+    $sects{FOOTNOTES} .= "=item $fnno.\n\n"; $fnno++;
+    $sects{FOOTNOTES} .= $_[0];
+    $sects{FOOTNOTES} .= "\n\n";
+}
+
+# stolen from Symbol.pm
+{
+    my $genseq = 0;
+    sub gensym
+    {
+	my $name = "GEN" . $genseq++;
+	my $ref = \*{$name};
+	delete $::{$name};
+	return $ref;
+    }
+}
diff --git a/libjava/classpath/doc/texinfo.tex b/libjava/classpath/doc/texinfo.tex
new file mode 100644
index 000000000..91408263b
--- /dev/null
+++ b/libjava/classpath/doc/texinfo.tex
@@ -0,0 +1,9291 @@
+% texinfo.tex -- TeX macros to handle Texinfo files.
+% 
+% Load plain if necessary, i.e., if running under initex.
+\expandafter\ifx\csname fmtname\endcsname\relax\input plain\fi
+%
+\def\texinfoversion{2009-08-14.15}
+%
+% Copyright 1985, 1986, 1988, 1990, 1991, 1992, 1993, 1994, 1995,
+% 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006,
+% 2007, 2008, 2009 Free Software Foundation, Inc.
+%
+% This texinfo.tex file 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 3 of the
+% License, or (at your option) any later version.
+%
+% This texinfo.tex file 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, see <http://www.gnu.org/licenses/>.
+%
+% As a special exception, when this file is read by TeX when processing
+% a Texinfo source document, you may use the result without
+% restriction.  (This has been our intent since Texinfo was invented.)
+%
+% Please try the latest version of texinfo.tex before submitting bug
+% reports; you can get the latest version from:
+%   http://www.gnu.org/software/texinfo/ (the Texinfo home page), or
+%   ftp://tug.org/tex/texinfo.tex
+%     (and all CTAN mirrors, see http://www.ctan.org).
+% The texinfo.tex in any given distribution could well be out
+% of date, so if that's what you're using, please check.
+%
+% Send bug reports to bug-texinfo@gnu.org.  Please include including a
+% complete document in each bug report with which we can reproduce the
+% problem.  Patches are, of course, greatly appreciated.
+%
+% To process a Texinfo manual with TeX, it's most reliable to use the
+% texi2dvi shell script that comes with the distribution.  For a simple
+% manual foo.texi, however, you can get away with this:
+%   tex foo.texi
+%   texindex foo.??
+%   tex foo.texi
+%   tex foo.texi
+%   dvips foo.dvi -o  # or whatever; this makes foo.ps.
+% The extra TeX runs get the cross-reference information correct.
+% Sometimes one run after texindex suffices, and sometimes you need more
+% than two; texi2dvi does it as many times as necessary.
+%
+% It is possible to adapt texinfo.tex for other languages, to some
+% extent.  You can get the existing language-specific files from the
+% full Texinfo distribution.
+%
+% The GNU Texinfo home page is http://www.gnu.org/software/texinfo.
+
+
+\message{Loading texinfo [version \texinfoversion]:}
+
+% If in a .fmt file, print the version number
+% and turn on active characters that we couldn't do earlier because
+% they might have appeared in the input file name.
+\everyjob{\message{[Texinfo version \texinfoversion]}%
+  \catcode`+=\active \catcode`\_=\active}
+
+
+\chardef\other=12
+
+% We never want plain's \outer definition of \+ in Texinfo.
+% For @tex, we can use \tabalign.
+\let\+ = \relax
+
+% Save some plain tex macros whose names we will redefine.
+\let\ptexb=\b
+\let\ptexbullet=\bullet
+\let\ptexc=\c
+\let\ptexcomma=\,
+\let\ptexdot=\.
+\let\ptexdots=\dots
+\let\ptexend=\end
+\let\ptexequiv=\equiv
+\let\ptexexclam=\!
+\let\ptexfootnote=\footnote
+\let\ptexgtr=>
+\let\ptexhat=^
+\let\ptexi=\i
+\let\ptexindent=\indent
+\let\ptexinsert=\insert
+\let\ptexlbrace=\{
+\let\ptexless=<
+\let\ptexnewwrite\newwrite
+\let\ptexnoindent=\noindent
+\let\ptexplus=+
+\let\ptexrbrace=\}
+\let\ptexslash=\/
+\let\ptexstar=\*
+\let\ptext=\t
+\let\ptextop=\top
+{\catcode`\'=\active
+\global\let\ptexquoteright'}% Math-mode def from plain.tex.
+\let\ptexraggedright=\raggedright
+
+% If this character appears in an error message or help string, it
+% starts a new line in the output.
+\newlinechar = `^^J
+
+% Use TeX 3.0's \inputlineno to get the line number, for better error
+% messages, but if we're using an old version of TeX, don't do anything.
+%
+\ifx\inputlineno\thisisundefined
+  \let\linenumber = \empty % Pre-3.0.
+\else
+  \def\linenumber{l.\the\inputlineno:\space}
+\fi
+
+% Set up fixed words for English if not already set.
+\ifx\putwordAppendix\undefined  \gdef\putwordAppendix{Appendix}\fi
+\ifx\putwordChapter\undefined   \gdef\putwordChapter{Chapter}\fi
+\ifx\putwordfile\undefined      \gdef\putwordfile{file}\fi
+\ifx\putwordin\undefined        \gdef\putwordin{in}\fi
+\ifx\putwordIndexIsEmpty\undefined     \gdef\putwordIndexIsEmpty{(Index is empty)}\fi
+\ifx\putwordIndexNonexistent\undefined \gdef\putwordIndexNonexistent{(Index is nonexistent)}\fi
+\ifx\putwordInfo\undefined      \gdef\putwordInfo{Info}\fi
+\ifx\putwordInstanceVariableof\undefined \gdef\putwordInstanceVariableof{Instance Variable of}\fi
+\ifx\putwordMethodon\undefined  \gdef\putwordMethodon{Method on}\fi
+\ifx\putwordNoTitle\undefined   \gdef\putwordNoTitle{No Title}\fi
+\ifx\putwordof\undefined        \gdef\putwordof{of}\fi
+\ifx\putwordon\undefined        \gdef\putwordon{on}\fi
+\ifx\putwordpage\undefined      \gdef\putwordpage{page}\fi
+\ifx\putwordsection\undefined   \gdef\putwordsection{section}\fi
+\ifx\putwordSection\undefined   \gdef\putwordSection{Section}\fi
+\ifx\putwordsee\undefined       \gdef\putwordsee{see}\fi
+\ifx\putwordSee\undefined       \gdef\putwordSee{See}\fi
+\ifx\putwordShortTOC\undefined  \gdef\putwordShortTOC{Short Contents}\fi
+\ifx\putwordTOC\undefined       \gdef\putwordTOC{Table of Contents}\fi
+%
+\ifx\putwordMJan\undefined \gdef\putwordMJan{January}\fi
+\ifx\putwordMFeb\undefined \gdef\putwordMFeb{February}\fi
+\ifx\putwordMMar\undefined \gdef\putwordMMar{March}\fi
+\ifx\putwordMApr\undefined \gdef\putwordMApr{April}\fi
+\ifx\putwordMMay\undefined \gdef\putwordMMay{May}\fi
+\ifx\putwordMJun\undefined \gdef\putwordMJun{June}\fi
+\ifx\putwordMJul\undefined \gdef\putwordMJul{July}\fi
+\ifx\putwordMAug\undefined \gdef\putwordMAug{August}\fi
+\ifx\putwordMSep\undefined \gdef\putwordMSep{September}\fi
+\ifx\putwordMOct\undefined \gdef\putwordMOct{October}\fi
+\ifx\putwordMNov\undefined \gdef\putwordMNov{November}\fi
+\ifx\putwordMDec\undefined \gdef\putwordMDec{December}\fi
+%
+\ifx\putwordDefmac\undefined    \gdef\putwordDefmac{Macro}\fi
+\ifx\putwordDefspec\undefined   \gdef\putwordDefspec{Special Form}\fi
+\ifx\putwordDefvar\undefined    \gdef\putwordDefvar{Variable}\fi
+\ifx\putwordDefopt\undefined    \gdef\putwordDefopt{User Option}\fi
+\ifx\putwordDeffunc\undefined   \gdef\putwordDeffunc{Function}\fi
+
+% Since the category of space is not known, we have to be careful.
+\chardef\spacecat = 10
+\def\spaceisspace{\catcode`\ =\spacecat}
+
+% sometimes characters are active, so we need control sequences.
+\chardef\colonChar = `\:
+\chardef\commaChar = `\,
+\chardef\dashChar  = `\-
+\chardef\dotChar   = `\.
+\chardef\exclamChar= `\!
+\chardef\lquoteChar= `\`
+\chardef\questChar = `\?
+\chardef\rquoteChar= `\'
+\chardef\semiChar  = `\;
+\chardef\underChar = `\_
+
+% Ignore a token.
+%
+\def\gobble#1{}
+
+% The following is used inside several \edef's.
+\def\makecsname#1{\expandafter\noexpand\csname#1\endcsname}
+
+% Hyphenation fixes.
+\hyphenation{
+  Flor-i-da Ghost-script Ghost-view Mac-OS Post-Script
+  ap-pen-dix bit-map bit-maps
+  data-base data-bases eshell fall-ing half-way long-est man-u-script
+  man-u-scripts mini-buf-fer mini-buf-fers over-view par-a-digm
+  par-a-digms rath-er rec-tan-gu-lar ro-bot-ics se-vere-ly set-up spa-ces
+  spell-ing spell-ings
+  stand-alone strong-est time-stamp time-stamps which-ever white-space
+  wide-spread wrap-around
+}
+
+% Margin to add to right of even pages, to left of odd pages.
+\newdimen\bindingoffset
+\newdimen\normaloffset
+\newdimen\pagewidth \newdimen\pageheight
+
+% For a final copy, take out the rectangles
+% that mark overfull boxes (in case you have decided
+% that the text looks ok even though it passes the margin).
+%
+\def\finalout{\overfullrule=0pt}
+
+% @| inserts a changebar to the left of the current line.  It should
+% surround any changed text.  This approach does *not* work if the
+% change spans more than two lines of output.  To handle that, we would
+% have adopt a much more difficult approach (putting marks into the main
+% vertical list for the beginning and end of each change).
+%
+\def\|{%
+  % \vadjust can only be used in horizontal mode.
+  \leavevmode
+  %
+  % Append this vertical mode material after the current line in the output.
+  \vadjust{%
+    % We want to insert a rule with the height and depth of the current
+    % leading; that is exactly what \strutbox is supposed to record.
+    \vskip-\baselineskip
+    %
+    % \vadjust-items are inserted at the left edge of the type.  So
+    % the \llap here moves out into the left-hand margin.
+    \llap{%
+      %
+      % For a thicker or thinner bar, change the `1pt'.
+      \vrule height\baselineskip width1pt
+      %
+      % This is the space between the bar and the text.
+      \hskip 12pt
+    }%
+  }%
+}
+
+% Sometimes it is convenient to have everything in the transcript file
+% and nothing on the terminal.  We don't just call \tracingall here,
+% since that produces some useless output on the terminal.  We also make
+% some effort to order the tracing commands to reduce output in the log
+% file; cf. trace.sty in LaTeX.
+%
+\def\gloggingall{\begingroup \globaldefs = 1 \loggingall \endgroup}%
+\def\loggingall{%
+  \tracingstats2
+  \tracingpages1
+  \tracinglostchars2  % 2 gives us more in etex
+  \tracingparagraphs1
+  \tracingoutput1
+  \tracingmacros2
+  \tracingrestores1
+  \showboxbreadth\maxdimen \showboxdepth\maxdimen
+  \ifx\eTeXversion\undefined\else % etex gives us more logging
+    \tracingscantokens1
+    \tracingifs1
+    \tracinggroups1
+    \tracingnesting2
+    \tracingassigns1
+  \fi
+  \tracingcommands3  % 3 gives us more in etex
+  \errorcontextlines16
+}%
+
+% add check for \lastpenalty to plain's definitions.  If the last thing
+% we did was a \nobreak, we don't want to insert more space.
+%
+\def\smallbreak{\ifnum\lastpenalty<10000\par\ifdim\lastskip<\smallskipamount
+  \removelastskip\penalty-50\smallskip\fi\fi}
+\def\medbreak{\ifnum\lastpenalty<10000\par\ifdim\lastskip<\medskipamount
+  \removelastskip\penalty-100\medskip\fi\fi}
+\def\bigbreak{\ifnum\lastpenalty<10000\par\ifdim\lastskip<\bigskipamount
+  \removelastskip\penalty-200\bigskip\fi\fi}
+
+% For @cropmarks command.
+% Do @cropmarks to get crop marks.
+%
+\newif\ifcropmarks
+\let\cropmarks = \cropmarkstrue
+%
+% Dimensions to add cropmarks at corners.
+% Added by P. A. MacKay, 12 Nov. 1986
+%
+\newdimen\outerhsize \newdimen\outervsize % set by the paper size routines
+\newdimen\cornerlong  \cornerlong=1pc
+\newdimen\cornerthick \cornerthick=.3pt
+\newdimen\topandbottommargin \topandbottommargin=.75in
+
+% Output a mark which sets \thischapter, \thissection and \thiscolor.
+% We dump everything together because we only have one kind of mark.
+% This works because we only use \botmark / \topmark, not \firstmark.
+%
+% A mark contains a subexpression of the \ifcase ... \fi construct.
+% \get*marks macros below extract the needed part using \ifcase.
+%
+% Another complication is to let the user choose whether \thischapter
+% (\thissection) refers to the chapter (section) in effect at the top
+% of a page, or that at the bottom of a page.  The solution is
+% described on page 260 of The TeXbook.  It involves outputting two
+% marks for the sectioning macros, one before the section break, and
+% one after.  I won't pretend I can describe this better than DEK...
+\def\domark{%
+  \toks0=\expandafter{\lastchapterdefs}%
+  \toks2=\expandafter{\lastsectiondefs}%
+  \toks4=\expandafter{\prevchapterdefs}%
+  \toks6=\expandafter{\prevsectiondefs}%
+  \toks8=\expandafter{\lastcolordefs}%
+  \mark{%
+                   \the\toks0 \the\toks2
+      \noexpand\or \the\toks4 \the\toks6
+    \noexpand\else \the\toks8
+  }%
+}
+% \topmark doesn't work for the very first chapter (after the title
+% page or the contents), so we use \firstmark there -- this gets us
+% the mark with the chapter defs, unless the user sneaks in, e.g.,
+% @setcolor (or @url, or @link, etc.) between @contents and the very
+% first @chapter.
+\def\gettopheadingmarks{%
+  \ifcase0\topmark\fi
+  \ifx\thischapter\empty \ifcase0\firstmark\fi \fi
+}
+\def\getbottomheadingmarks{\ifcase1\botmark\fi}
+\def\getcolormarks{\ifcase2\topmark\fi}
+
+% Avoid "undefined control sequence" errors.
+\def\lastchapterdefs{}
+\def\lastsectiondefs{}
+\def\prevchapterdefs{}
+\def\prevsectiondefs{}
+\def\lastcolordefs{}
+
+% Main output routine.
+\chardef\PAGE = 255
+\output = {\onepageout{\pagecontents\PAGE}}
+
+\newbox\headlinebox
+\newbox\footlinebox
+
+% \onepageout takes a vbox as an argument.  Note that \pagecontents
+% does insertions, but you have to call it yourself.
+\def\onepageout#1{%
+  \ifcropmarks \hoffset=0pt \else \hoffset=\normaloffset \fi
+  %
+  \ifodd\pageno  \advance\hoffset by \bindingoffset
+  \else \advance\hoffset by -\bindingoffset\fi
+  %
+  % Do this outside of the \shipout so @code etc. will be expanded in
+  % the headline as they should be, not taken literally (outputting ''code).
+  \ifodd\pageno \getoddheadingmarks \else \getevenheadingmarks \fi
+  \setbox\headlinebox = \vbox{\let\hsize=\pagewidth \makeheadline}%
+  \ifodd\pageno \getoddfootingmarks \else \getevenfootingmarks \fi
+  \setbox\footlinebox = \vbox{\let\hsize=\pagewidth \makefootline}%
+  %
+  {%
+    % Have to do this stuff outside the \shipout because we want it to
+    % take effect in \write's, yet the group defined by the \vbox ends
+    % before the \shipout runs.
+    %
+    \indexdummies         % don't expand commands in the output.
+    \normalturnoffactive  % \ in index entries must not stay \, e.g., if
+               % the page break happens to be in the middle of an example.
+               % We don't want .vr (or whatever) entries like this:
+               % \entry{{\tt \indexbackslash }acronym}{32}{\code {\acronym}}
+               % "\acronym" won't work when it's read back in;
+               % it needs to be
+               % {\code {{\tt \backslashcurfont }acronym}
+    \shipout\vbox{%
+      % Do this early so pdf references go to the beginning of the page.
+      \ifpdfmakepagedest \pdfdest name{\the\pageno} xyz\fi
+      %
+      \ifcropmarks \vbox to \outervsize\bgroup
+        \hsize = \outerhsize
+        \vskip-\topandbottommargin
+        \vtop to0pt{%
+          \line{\ewtop\hfil\ewtop}%
+          \nointerlineskip
+          \line{%
+            \vbox{\moveleft\cornerthick\nstop}%
+            \hfill
+            \vbox{\moveright\cornerthick\nstop}%
+          }%
+          \vss}%
+        \vskip\topandbottommargin
+        \line\bgroup
+          \hfil % center the page within the outer (page) hsize.
+          \ifodd\pageno\hskip\bindingoffset\fi
+          \vbox\bgroup
+      \fi
+      %
+      \unvbox\headlinebox
+      \pagebody{#1}%
+      \ifdim\ht\footlinebox > 0pt
+        % Only leave this space if the footline is nonempty.
+        % (We lessened \vsize for it in \oddfootingyyy.)
+        % The \baselineskip=24pt in plain's \makefootline has no effect.
+        \vskip 24pt
+        \unvbox\footlinebox
+      \fi
+      %
+      \ifcropmarks
+          \egroup % end of \vbox\bgroup
+        \hfil\egroup % end of (centering) \line\bgroup
+        \vskip\topandbottommargin plus1fill minus1fill
+        \boxmaxdepth = \cornerthick
+        \vbox to0pt{\vss
+          \line{%
+            \vbox{\moveleft\cornerthick\nsbot}%
+            \hfill
+            \vbox{\moveright\cornerthick\nsbot}%
+          }%
+          \nointerlineskip
+          \line{\ewbot\hfil\ewbot}%
+        }%
+      \egroup % \vbox from first cropmarks clause
+      \fi
+    }% end of \shipout\vbox
+  }% end of group with \indexdummies
+  \advancepageno
+  \ifnum\outputpenalty>-20000 \else\dosupereject\fi
+}
+
+\newinsert\margin \dimen\margin=\maxdimen
+
+\def\pagebody#1{\vbox to\pageheight{\boxmaxdepth=\maxdepth #1}}
+{\catcode`\@ =11
+\gdef\pagecontents#1{\ifvoid\topins\else\unvbox\topins\fi
+% marginal hacks, juha@viisa.uucp (Juha Takala)
+\ifvoid\margin\else % marginal info is present
+  \rlap{\kern\hsize\vbox to\z@{\kern1pt\box\margin \vss}}\fi
+\dimen@=\dp#1\relax \unvbox#1\relax
+\ifvoid\footins\else\vskip\skip\footins\footnoterule \unvbox\footins\fi
+\ifr@ggedbottom \kern-\dimen@ \vfil \fi}
+}
+
+% Here are the rules for the cropmarks.  Note that they are
+% offset so that the space between them is truly \outerhsize or \outervsize
+% (P. A. MacKay, 12 November, 1986)
+%
+\def\ewtop{\vrule height\cornerthick depth0pt width\cornerlong}
+\def\nstop{\vbox
+  {\hrule height\cornerthick depth\cornerlong width\cornerthick}}
+\def\ewbot{\vrule height0pt depth\cornerthick width\cornerlong}
+\def\nsbot{\vbox
+  {\hrule height\cornerlong depth\cornerthick width\cornerthick}}
+
+% Parse an argument, then pass it to #1.  The argument is the rest of
+% the input line (except we remove a trailing comment).  #1 should be a
+% macro which expects an ordinary undelimited TeX argument.
+%
+\def\parsearg{\parseargusing{}}
+\def\parseargusing#1#2{%
+  \def\argtorun{#2}%
+  \begingroup
+    \obeylines
+    \spaceisspace
+    #1%
+    \parseargline\empty% Insert the \empty token, see \finishparsearg below.
+}
+
+{\obeylines %
+  \gdef\parseargline#1^^M{%
+    \endgroup % End of the group started in \parsearg.
+    \argremovecomment #1\comment\ArgTerm%
+  }%
+}
+
+% First remove any @comment, then any @c comment.
+\def\argremovecomment#1\comment#2\ArgTerm{\argremovec #1\c\ArgTerm}
+\def\argremovec#1\c#2\ArgTerm{\argcheckspaces#1\^^M\ArgTerm}
+
+% Each occurrence of `\^^M' or `<space>\^^M' is replaced by a single space.
+%
+% \argremovec might leave us with trailing space, e.g.,
+%    @end itemize  @c foo
+% This space token undergoes the same procedure and is eventually removed
+% by \finishparsearg.
+%
+\def\argcheckspaces#1\^^M{\argcheckspacesX#1\^^M \^^M}
+\def\argcheckspacesX#1 \^^M{\argcheckspacesY#1\^^M}
+\def\argcheckspacesY#1\^^M#2\^^M#3\ArgTerm{%
+  \def\temp{#3}%
+  \ifx\temp\empty
+    % Do not use \next, perhaps the caller of \parsearg uses it; reuse \temp:
+    \let\temp\finishparsearg
+  \else
+    \let\temp\argcheckspaces
+  \fi
+  % Put the space token in:
+  \temp#1 #3\ArgTerm
+}
+
+% If a _delimited_ argument is enclosed in braces, they get stripped; so
+% to get _exactly_ the rest of the line, we had to prevent such situation.
+% We prepended an \empty token at the very beginning and we expand it now,
+% just before passing the control to \argtorun.
+% (Similarly, we have to think about #3 of \argcheckspacesY above: it is
+% either the null string, or it ends with \^^M---thus there is no danger
+% that a pair of braces would be stripped.
+%
+% But first, we have to remove the trailing space token.
+%
+\def\finishparsearg#1 \ArgTerm{\expandafter\argtorun\expandafter{#1}}
+
+% \parseargdef\foo{...}
+%	is roughly equivalent to
+% \def\foo{\parsearg\Xfoo}
+% \def\Xfoo#1{...}
+%
+% Actually, I use \csname\string\foo\endcsname, ie. \\foo, as it is my
+% favourite TeX trick.  --kasal, 16nov03
+
+\def\parseargdef#1{%
+  \expandafter \doparseargdef \csname\string#1\endcsname #1%
+}
+\def\doparseargdef#1#2{%
+  \def#2{\parsearg#1}%
+  \def#1##1%
+}
+
+% Several utility definitions with active space:
+{
+  \obeyspaces
+  \gdef\obeyedspace{ }
+
+  % Make each space character in the input produce a normal interword
+  % space in the output.  Don't allow a line break at this space, as this
+  % is used only in environments like @example, where each line of input
+  % should produce a line of output anyway.
+  %
+  \gdef\sepspaces{\obeyspaces\let =\tie}
+
+  % If an index command is used in an @example environment, any spaces
+  % therein should become regular spaces in the raw index file, not the
+  % expansion of \tie (\leavevmode \penalty \@M \ ).
+  \gdef\unsepspaces{\let =\space}
+}
+
+
+\def\flushcr{\ifx\par\lisppar \def\next##1{}\else \let\next=\relax \fi \next}
+
+% Define the framework for environments in texinfo.tex.  It's used like this:
+%
+%   \envdef\foo{...}
+%   \def\Efoo{...}
+%
+% It's the responsibility of \envdef to insert \begingroup before the
+% actual body; @end closes the group after calling \Efoo.  \envdef also
+% defines \thisenv, so the current environment is known; @end checks
+% whether the environment name matches.  The \checkenv macro can also be
+% used to check whether the current environment is the one expected.
+%
+% Non-false conditionals (@iftex, @ifset) don't fit into this, so they
+% are not treated as environments; they don't open a group.  (The
+% implementation of @end takes care not to call \endgroup in this
+% special case.)
+
+
+% At run-time, environments start with this:
+\def\startenvironment#1{\begingroup\def\thisenv{#1}}
+% initialize
+\let\thisenv\empty
+
+% ... but they get defined via ``\envdef\foo{...}'':
+\long\def\envdef#1#2{\def#1{\startenvironment#1#2}}
+\def\envparseargdef#1#2{\parseargdef#1{\startenvironment#1#2}}
+
+% Check whether we're in the right environment:
+\def\checkenv#1{%
+  \def\temp{#1}%
+  \ifx\thisenv\temp
+  \else
+    \badenverr
+  \fi
+}
+
+% Environment mismatch, #1 expected:
+\def\badenverr{%
+  \errhelp = \EMsimple
+  \errmessage{This command can appear only \inenvironment\temp,
+    not \inenvironment\thisenv}%
+}
+\def\inenvironment#1{%
+  \ifx#1\empty
+    out of any environment%
+  \else
+    in environment \expandafter\string#1%
+  \fi
+}
+
+% @end foo executes the definition of \Efoo.
+% But first, it executes a specialized version of \checkenv
+%
+\parseargdef\end{%
+  \if 1\csname iscond.#1\endcsname
+  \else
+    % The general wording of \badenverr may not be ideal, but... --kasal, 06nov03
+    \expandafter\checkenv\csname#1\endcsname
+    \csname E#1\endcsname
+    \endgroup
+  \fi
+}
+
+\newhelp\EMsimple{Press RETURN to continue.}
+
+
+%% Simple single-character @ commands
+
+% @@ prints an @
+% Kludge this until the fonts are right (grr).
+\def\@{{\tt\char64}}
+
+% This is turned off because it was never documented
+% and you can use @w{...} around a quote to suppress ligatures.
+%% Define @` and @' to be the same as ` and '
+%% but suppressing ligatures.
+%\def\`{{`}}
+%\def\'{{'}}
+
+% Used to generate quoted braces.
+\def\mylbrace {{\tt\char123}}
+\def\myrbrace {{\tt\char125}}
+\let\{=\mylbrace
+\let\}=\myrbrace
+\begingroup
+  % Definitions to produce \{ and \} commands for indices,
+  % and @{ and @} for the aux/toc files.
+  \catcode`\{ = \other \catcode`\} = \other
+  \catcode`\[ = 1 \catcode`\] = 2
+  \catcode`\! = 0 \catcode`\\ = \other
+  !gdef!lbracecmd[\{]%
+  !gdef!rbracecmd[\}]%
+  !gdef!lbraceatcmd[@{]%
+  !gdef!rbraceatcmd[@}]%
+!endgroup
+
+% @comma{} to avoid , parsing problems.
+\let\comma = ,
+
+% Accents: @, @dotaccent @ringaccent @ubaraccent @udotaccent
+% Others are defined by plain TeX: @` @' @" @^ @~ @= @u @v @H.
+\let\, = \c
+\let\dotaccent = \.
+\def\ringaccent#1{{\accent23 #1}}
+\let\tieaccent = \t
+\let\ubaraccent = \b
+\let\udotaccent = \d
+
+% Other special characters: @questiondown @exclamdown @ordf @ordm
+% Plain TeX defines: @AA @AE @O @OE @L (plus lowercase versions) @ss.
+\def\questiondown{?`}
+\def\exclamdown{!`}
+\def\ordf{\leavevmode\raise1ex\hbox{\selectfonts\lllsize \underbar{a}}}
+\def\ordm{\leavevmode\raise1ex\hbox{\selectfonts\lllsize \underbar{o}}}
+
+% Dotless i and dotless j, used for accents.
+\def\imacro{i}
+\def\jmacro{j}
+\def\dotless#1{%
+  \def\temp{#1}%
+  \ifx\temp\imacro \ifmmode\imath \else\ptexi \fi
+  \else\ifx\temp\jmacro \ifmmode\jmath \else\j \fi
+  \else \errmessage{@dotless can be used only with i or j}%
+  \fi\fi
+}
+
+% The \TeX{} logo, as in plain, but resetting the spacing so that a
+% period following counts as ending a sentence.  (Idea found in latex.)
+%
+\edef\TeX{\TeX \spacefactor=1000 }
+
+% @LaTeX{} logo.  Not quite the same results as the definition in
+% latex.ltx, since we use a different font for the raised A; it's most
+% convenient for us to use an explicitly smaller font, rather than using
+% the \scriptstyle font (since we don't reset \scriptstyle and
+% \scriptscriptstyle).
+%
+\def\LaTeX{%
+  L\kern-.36em
+  {\setbox0=\hbox{T}%
+   \vbox to \ht0{\hbox{\selectfonts\lllsize A}\vss}}%
+  \kern-.15em
+  \TeX
+}
+
+% Be sure we're in horizontal mode when doing a tie, since we make space
+% equivalent to this in @example-like environments. Otherwise, a space
+% at the beginning of a line will start with \penalty -- and
+% since \penalty is valid in vertical mode, we'd end up putting the
+% penalty on the vertical list instead of in the new paragraph.
+{\catcode`@ = 11
+ % Avoid using \@M directly, because that causes trouble
+ % if the definition is written into an index file.
+ \global\let\tiepenalty = \@M
+ \gdef\tie{\leavevmode\penalty\tiepenalty\ }
+}
+
+% @: forces normal size whitespace following.
+\def\:{\spacefactor=1000 }
+
+% @* forces a line break.
+\def\*{\hfil\break\hbox{}\ignorespaces}
+
+% @/ allows a line break.
+\let\/=\allowbreak
+
+% @. is an end-of-sentence period.
+\def\.{.\spacefactor=\endofsentencespacefactor\space}
+
+% @! is an end-of-sentence bang.
+\def\!{!\spacefactor=\endofsentencespacefactor\space}
+
+% @? is an end-of-sentence query.
+\def\?{?\spacefactor=\endofsentencespacefactor\space}
+
+% @frenchspacing on|off  says whether to put extra space after punctuation.
+%
+\def\onword{on}
+\def\offword{off}
+%
+\parseargdef\frenchspacing{%
+  \def\temp{#1}%
+  \ifx\temp\onword \plainfrenchspacing
+  \else\ifx\temp\offword \plainnonfrenchspacing
+  \else
+    \errhelp = \EMsimple
+    \errmessage{Unknown @frenchspacing option `\temp', must be on/off}%
+  \fi\fi
+}
+
+% @w prevents a word break.  Without the \leavevmode, @w at the
+% beginning of a paragraph, when TeX is still in vertical mode, would
+% produce a whole line of output instead of starting the paragraph.
+\def\w#1{\leavevmode\hbox{#1}}
+
+% @group ... @end group forces ... to be all on one page, by enclosing
+% it in a TeX vbox.  We use \vtop instead of \vbox to construct the box
+% to keep its height that of a normal line.  According to the rules for
+% \topskip (p.114 of the TeXbook), the glue inserted is
+% max (\topskip - \ht (first item), 0).  If that height is large,
+% therefore, no glue is inserted, and the space between the headline and
+% the text is small, which looks bad.
+%
+% Another complication is that the group might be very large.  This can
+% cause the glue on the previous page to be unduly stretched, because it
+% does not have much material.  In this case, it's better to add an
+% explicit \vfill so that the extra space is at the bottom.  The
+% threshold for doing this is if the group is more than \vfilllimit
+% percent of a page (\vfilllimit can be changed inside of @tex).
+%
+\newbox\groupbox
+\def\vfilllimit{0.7}
+%
+\envdef\group{%
+  \ifnum\catcode`\^^M=\active \else
+    \errhelp = \groupinvalidhelp
+    \errmessage{@group invalid in context where filling is enabled}%
+  \fi
+  \startsavinginserts
+  %
+  \setbox\groupbox = \vtop\bgroup
+    % Do @comment since we are called inside an environment such as
+    % @example, where each end-of-line in the input causes an
+    % end-of-line in the output.  We don't want the end-of-line after
+    % the `@group' to put extra space in the output.  Since @group
+    % should appear on a line by itself (according to the Texinfo
+    % manual), we don't worry about eating any user text.
+    \comment
+}
+%
+% The \vtop produces a box with normal height and large depth; thus, TeX puts
+% \baselineskip glue before it, and (when the next line of text is done)
+% \lineskip glue after it.  Thus, space below is not quite equal to space
+% above.  But it's pretty close.
+\def\Egroup{%
+    % To get correct interline space between the last line of the group
+    % and the first line afterwards, we have to propagate \prevdepth.
+    \endgraf % Not \par, as it may have been set to \lisppar.
+    \global\dimen1 = \prevdepth
+  \egroup           % End the \vtop.
+  % \dimen0 is the vertical size of the group's box.
+  \dimen0 = \ht\groupbox  \advance\dimen0 by \dp\groupbox
+  % \dimen2 is how much space is left on the page (more or less).
+  \dimen2 = \pageheight   \advance\dimen2 by -\pagetotal
+  % if the group doesn't fit on the current page, and it's a big big
+  % group, force a page break.
+  \ifdim \dimen0 > \dimen2
+    \ifdim \pagetotal < \vfilllimit\pageheight
+      \page
+    \fi
+  \fi
+  \box\groupbox
+  \prevdepth = \dimen1
+  \checkinserts
+}
+%
+% TeX puts in an \escapechar (i.e., `@') at the beginning of the help
+% message, so this ends up printing `@group can only ...'.
+%
+\newhelp\groupinvalidhelp{%
+group can only be used in environments such as @example,^^J%
+where each line of input produces a line of output.}
+
+% @need space-in-mils
+% forces a page break if there is not space-in-mils remaining.
+
+\newdimen\mil  \mil=0.001in
+
+% Old definition--didn't work.
+%\parseargdef\need{\par %
+%% This method tries to make TeX break the page naturally
+%% if the depth of the box does not fit.
+%{\baselineskip=0pt%
+%\vtop to #1\mil{\vfil}\kern -#1\mil\nobreak
+%\prevdepth=-1000pt
+%}}
+
+\parseargdef\need{%
+  % Ensure vertical mode, so we don't make a big box in the middle of a
+  % paragraph.
+  \par
+  %
+  % If the @need value is less than one line space, it's useless.
+  \dimen0 = #1\mil
+  \dimen2 = \ht\strutbox
+  \advance\dimen2 by \dp\strutbox
+  \ifdim\dimen0 > \dimen2
+    %
+    % Do a \strut just to make the height of this box be normal, so the
+    % normal leading is inserted relative to the preceding line.
+    % And a page break here is fine.
+    \vtop to #1\mil{\strut\vfil}%
+    %
+    % TeX does not even consider page breaks if a penalty added to the
+    % main vertical list is 10000 or more.  But in order to see if the
+    % empty box we just added fits on the page, we must make it consider
+    % page breaks.  On the other hand, we don't want to actually break the
+    % page after the empty box.  So we use a penalty of 9999.
+    %
+    % There is an extremely small chance that TeX will actually break the
+    % page at this \penalty, if there are no other feasible breakpoints in
+    % sight.  (If the user is using lots of big @group commands, which
+    % almost-but-not-quite fill up a page, TeX will have a hard time doing
+    % good page breaking, for example.)  However, I could not construct an
+    % example where a page broke at this \penalty; if it happens in a real
+    % document, then we can reconsider our strategy.
+    \penalty9999
+    %
+    % Back up by the size of the box, whether we did a page break or not.
+    \kern -#1\mil
+    %
+    % Do not allow a page break right after this kern.
+    \nobreak
+  \fi
+}
+
+% @br   forces paragraph break (and is undocumented).
+
+\let\br = \par
+
+% @page forces the start of a new page.
+%
+\def\page{\par\vfill\supereject}
+
+% @exdent text....
+% outputs text on separate line in roman font, starting at standard page margin
+
+% This records the amount of indent in the innermost environment.
+% That's how much \exdent should take out.
+\newskip\exdentamount
+
+% This defn is used inside fill environments such as @defun.
+\parseargdef\exdent{\hfil\break\hbox{\kern -\exdentamount{\rm#1}}\hfil\break}
+
+% This defn is used inside nofill environments such as @example.
+\parseargdef\nofillexdent{{\advance \leftskip by -\exdentamount
+  \leftline{\hskip\leftskip{\rm#1}}}}
+
+% @inmargin{WHICH}{TEXT} puts TEXT in the WHICH margin next to the current
+% paragraph.  For more general purposes, use the \margin insertion
+% class.  WHICH is `l' or `r'.
+%
+\newskip\inmarginspacing \inmarginspacing=1cm
+\def\strutdepth{\dp\strutbox}
+%
+\def\doinmargin#1#2{\strut\vadjust{%
+  \nobreak
+  \kern-\strutdepth
+  \vtop to \strutdepth{%
+    \baselineskip=\strutdepth
+    \vss
+    % if you have multiple lines of stuff to put here, you'll need to
+    % make the vbox yourself of the appropriate size.
+    \ifx#1l%
+      \llap{\ignorespaces #2\hskip\inmarginspacing}%
+    \else
+      \rlap{\hskip\hsize \hskip\inmarginspacing \ignorespaces #2}%
+    \fi
+    \null
+  }%
+}}
+\def\inleftmargin{\doinmargin l}
+\def\inrightmargin{\doinmargin r}
+%
+% @inmargin{TEXT [, RIGHT-TEXT]}
+% (if RIGHT-TEXT is given, use TEXT for left page, RIGHT-TEXT for right;
+% else use TEXT for both).
+%
+\def\inmargin#1{\parseinmargin #1,,\finish}
+\def\parseinmargin#1,#2,#3\finish{% not perfect, but better than nothing.
+  \setbox0 = \hbox{\ignorespaces #2}%
+  \ifdim\wd0 > 0pt
+    \def\lefttext{#1}%  have both texts
+    \def\righttext{#2}%
+  \else
+    \def\lefttext{#1}%  have only one text
+    \def\righttext{#1}%
+  \fi
+  %
+  \ifodd\pageno
+    \def\temp{\inrightmargin\righttext}% odd page -> outside is right margin
+  \else
+    \def\temp{\inleftmargin\lefttext}%
+  \fi
+  \temp
+}
+
+% @include FILE -- \input text of FILE.
+%
+\def\include{\parseargusing\filenamecatcodes\includezzz}
+\def\includezzz#1{%
+  \pushthisfilestack
+  \def\thisfile{#1}%
+  {%
+    \makevalueexpandable  % we want to expand any @value in FILE.
+    \turnoffactive        % and allow special characters in the expansion
+    \indexnofonts         % Allow `@@' and other weird things in file names.
+    \edef\temp{\noexpand\input #1 }%
+    %
+    % This trickery is to read FILE outside of a group, in case it makes
+    % definitions, etc.
+    \expandafter
+  }\temp
+  \popthisfilestack
+}
+\def\filenamecatcodes{%
+  \catcode`\\=\other
+  \catcode`~=\other
+  \catcode`^=\other
+  \catcode`_=\other
+  \catcode`|=\other
+  \catcode`<=\other
+  \catcode`>=\other
+  \catcode`+=\other
+  \catcode`-=\other
+  \catcode`\`=\other
+  \catcode`\'=\other
+}
+
+\def\pushthisfilestack{%
+  \expandafter\pushthisfilestackX\popthisfilestack\StackTerm
+}
+\def\pushthisfilestackX{%
+  \expandafter\pushthisfilestackY\thisfile\StackTerm
+}
+\def\pushthisfilestackY #1\StackTerm #2\StackTerm {%
+  \gdef\popthisfilestack{\gdef\thisfile{#1}\gdef\popthisfilestack{#2}}%
+}
+
+\def\popthisfilestack{\errthisfilestackempty}
+\def\errthisfilestackempty{\errmessage{Internal error:
+  the stack of filenames is empty.}}
+
+\def\thisfile{}
+
+% @center line
+% outputs that line, centered.
+%
+\parseargdef\center{%
+  \ifhmode
+    \let\next\centerH
+  \else
+    \let\next\centerV
+  \fi
+  \next{\hfil \ignorespaces#1\unskip \hfil}%
+}
+\def\centerH#1{%
+  {%
+    \hfil\break
+    \advance\hsize by -\leftskip
+    \advance\hsize by -\rightskip
+    \line{#1}%
+    \break
+  }%
+}
+\def\centerV#1{\line{\kern\leftskip #1\kern\rightskip}}
+
+% @sp n   outputs n lines of vertical space
+
+\parseargdef\sp{\vskip #1\baselineskip}
+
+% @comment ...line which is ignored...
+% @c is the same as @comment
+% @ignore ... @end ignore  is another way to write a comment
+
+\def\comment{\begingroup \catcode`\^^M=\other%
+\catcode`\@=\other \catcode`\{=\other \catcode`\}=\other%
+\commentxxx}
+{\catcode`\^^M=\other \gdef\commentxxx#1^^M{\endgroup}}
+
+\let\c=\comment
+
+% @paragraphindent NCHARS
+% We'll use ems for NCHARS, close enough.
+% NCHARS can also be the word `asis' or `none'.
+% We cannot feasibly implement @paragraphindent asis, though.
+%
+\def\asisword{asis} % no translation, these are keywords
+\def\noneword{none}
+%
+\parseargdef\paragraphindent{%
+  \def\temp{#1}%
+  \ifx\temp\asisword
+  \else
+    \ifx\temp\noneword
+      \defaultparindent = 0pt
+    \else
+      \defaultparindent = #1em
+    \fi
+  \fi
+  \parindent = \defaultparindent
+}
+
+% @exampleindent NCHARS
+% We'll use ems for NCHARS like @paragraphindent.
+% It seems @exampleindent asis isn't necessary, but
+% I preserve it to make it similar to @paragraphindent.
+\parseargdef\exampleindent{%
+  \def\temp{#1}%
+  \ifx\temp\asisword
+  \else
+    \ifx\temp\noneword
+      \lispnarrowing = 0pt
+    \else
+      \lispnarrowing = #1em
+    \fi
+  \fi
+}
+
+% @firstparagraphindent WORD
+% If WORD is `none', then suppress indentation of the first paragraph
+% after a section heading.  If WORD is `insert', then do indent at such
+% paragraphs.
+%
+% The paragraph indentation is suppressed or not by calling
+% \suppressfirstparagraphindent, which the sectioning commands do.
+% We switch the definition of this back and forth according to WORD.
+% By default, we suppress indentation.
+%
+\def\suppressfirstparagraphindent{\dosuppressfirstparagraphindent}
+\def\insertword{insert}
+%
+\parseargdef\firstparagraphindent{%
+  \def\temp{#1}%
+  \ifx\temp\noneword
+    \let\suppressfirstparagraphindent = \dosuppressfirstparagraphindent
+  \else\ifx\temp\insertword
+    \let\suppressfirstparagraphindent = \relax
+  \else
+    \errhelp = \EMsimple
+    \errmessage{Unknown @firstparagraphindent option `\temp'}%
+  \fi\fi
+}
+
+% Here is how we actually suppress indentation.  Redefine \everypar to
+% \kern backwards by \parindent, and then reset itself to empty.
+%
+% We also make \indent itself not actually do anything until the next
+% paragraph.
+%
+\gdef\dosuppressfirstparagraphindent{%
+  \gdef\indent{%
+    \restorefirstparagraphindent
+    \indent
+  }%
+  \gdef\noindent{%
+    \restorefirstparagraphindent
+    \noindent
+  }%
+  \global\everypar = {%
+    \kern -\parindent
+    \restorefirstparagraphindent
+  }%
+}
+
+\gdef\restorefirstparagraphindent{%
+  \global \let \indent = \ptexindent
+  \global \let \noindent = \ptexnoindent
+  \global \everypar = {}%
+}
+
+
+% @asis just yields its argument.  Used with @table, for example.
+%
+\def\asis#1{#1}
+
+% @math outputs its argument in math mode.
+%
+% One complication: _ usually means subscripts, but it could also mean
+% an actual _ character, as in @math{@var{some_variable} + 1}.  So make
+% _ active, and distinguish by seeing if the current family is \slfam,
+% which is what @var uses.
+{
+  \catcode`\_ = \active
+  \gdef\mathunderscore{%
+    \catcode`\_=\active
+    \def_{\ifnum\fam=\slfam \_\else\sb\fi}%
+  }
+}
+% Another complication: we want \\ (and @\) to output a \ character.
+% FYI, plain.tex uses \\ as a temporary control sequence (why?), but
+% this is not advertised and we don't care.  Texinfo does not
+% otherwise define @\.
+%
+% The \mathchar is class=0=ordinary, family=7=ttfam, position=5C=\.
+\def\mathbackslash{\ifnum\fam=\ttfam \mathchar"075C \else\backslash \fi}
+%
+\def\math{%
+  \tex
+  \mathunderscore
+  \let\\ = \mathbackslash
+  \mathactive
+  % make the texinfo accent commands work in math mode
+  \let\"=\ddot
+  \let\'=\acute
+  \let\==\bar
+  \let\^=\hat
+  \let\`=\grave
+  \let\u=\breve
+  \let\v=\check
+  \let\~=\tilde
+  \let\dotaccent=\dot
+  $\finishmath
+}
+\def\finishmath#1{#1$\endgroup}  % Close the group opened by \tex.
+
+% Some active characters (such as <) are spaced differently in math.
+% We have to reset their definitions in case the @math was an argument
+% to a command which sets the catcodes (such as @item or @section).
+%
+{
+  \catcode`^ = \active
+  \catcode`< = \active
+  \catcode`> = \active
+  \catcode`+ = \active
+  \catcode`' = \active
+  \gdef\mathactive{%
+    \let^ = \ptexhat
+    \let< = \ptexless
+    \let> = \ptexgtr
+    \let+ = \ptexplus
+    \let' = \ptexquoteright
+  }
+}
+
+% Some math mode symbols.
+\def\bullet{$\ptexbullet$}
+\def\geq{\ifmmode \ge\else $\ge$\fi}
+\def\leq{\ifmmode \le\else $\le$\fi}
+\def\minus{\ifmmode -\else $-$\fi}
+
+% @dots{} outputs an ellipsis using the current font.
+% We do .5em per period so that it has the same spacing in the cm
+% typewriter fonts as three actual period characters; on the other hand,
+% in other typewriter fonts three periods are wider than 1.5em.  So do
+% whichever is larger.
+%
+\def\dots{%
+  \leavevmode
+  \setbox0=\hbox{...}% get width of three periods
+  \ifdim\wd0 > 1.5em
+    \dimen0 = \wd0
+  \else
+    \dimen0 = 1.5em
+  \fi
+  \hbox to \dimen0{%
+    \hskip 0pt plus.25fil
+    .\hskip 0pt plus1fil
+    .\hskip 0pt plus1fil
+    .\hskip 0pt plus.5fil
+  }%
+}
+
+% @enddots{} is an end-of-sentence ellipsis.
+%
+\def\enddots{%
+  \dots
+  \spacefactor=\endofsentencespacefactor
+}
+
+% @comma{} is so commas can be inserted into text without messing up
+% Texinfo's parsing.
+%
+\let\comma = ,
+
+% @refill is a no-op.
+\let\refill=\relax
+
+% If working on a large document in chapters, it is convenient to
+% be able to disable indexing, cross-referencing, and contents, for test runs.
+% This is done with @novalidate (before @setfilename).
+%
+\newif\iflinks \linkstrue % by default we want the aux files.
+\let\novalidate = \linksfalse
+
+% @setfilename is done at the beginning of every texinfo file.
+% So open here the files we need to have open while reading the input.
+% This makes it possible to make a .fmt file for texinfo.
+\def\setfilename{%
+   \fixbackslash  % Turn off hack to swallow `\input texinfo'.
+   \iflinks
+     \tryauxfile
+     % Open the new aux file.  TeX will close it automatically at exit.
+     \immediate\openout\auxfile=\jobname.aux
+   \fi % \openindices needs to do some work in any case.
+   \openindices
+   \let\setfilename=\comment % Ignore extra @setfilename cmds.
+   %
+   % If texinfo.cnf is present on the system, read it.
+   % Useful for site-wide @afourpaper, etc.
+   \openin 1 texinfo.cnf
+   \ifeof 1 \else \input texinfo.cnf \fi
+   \closein 1
+   %
+   \comment % Ignore the actual filename.
+}
+
+% Called from \setfilename.
+%
+\def\openindices{%
+  \newindex{cp}%
+  \newcodeindex{fn}%
+  \newcodeindex{vr}%
+  \newcodeindex{tp}%
+  \newcodeindex{ky}%
+  \newcodeindex{pg}%
+}
+
+% @bye.
+\outer\def\bye{\pagealignmacro\tracingstats=1\ptexend}
+
+
+\message{pdf,}
+% adobe `portable' document format
+\newcount\tempnum
+\newcount\lnkcount
+\newtoks\filename
+\newcount\filenamelength
+\newcount\pgn
+\newtoks\toksA
+\newtoks\toksB
+\newtoks\toksC
+\newtoks\toksD
+\newbox\boxA
+\newcount\countA
+\newif\ifpdf
+\newif\ifpdfmakepagedest
+
+% when pdftex is run in dvi mode, \pdfoutput is defined (so \pdfoutput=1
+% can be set).  So we test for \relax and 0 as well as \undefined,
+% borrowed from ifpdf.sty.
+\ifx\pdfoutput\undefined
+\else
+  \ifx\pdfoutput\relax
+  \else
+    \ifcase\pdfoutput
+    \else
+      \pdftrue
+    \fi
+  \fi
+\fi
+
+% PDF uses PostScript string constants for the names of xref targets,
+% for display in the outlines, and in other places.  Thus, we have to
+% double any backslashes.  Otherwise, a name like "\node" will be
+% interpreted as a newline (\n), followed by o, d, e.  Not good.
+% http://www.ntg.nl/pipermail/ntg-pdftex/2004-July/000654.html
+% (and related messages, the final outcome is that it is up to the TeX
+% user to double the backslashes and otherwise make the string valid, so
+% that's what we do).
+
+% double active backslashes.
+%
+{\catcode`\@=0 \catcode`\\=\active
+ @gdef@activebackslashdouble{%
+   @catcode`@\=@active
+   @let\=@doublebackslash}
+}
+
+% To handle parens, we must adopt a different approach, since parens are
+% not active characters.  hyperref.dtx (which has the same problem as
+% us) handles it with this amazing macro to replace tokens, with minor
+% changes for Texinfo.  It is included here under the GPL by permission
+% from the author, Heiko Oberdiek.
+%
+% #1 is the tokens to replace.
+% #2 is the replacement.
+% #3 is the control sequence with the string.
+%
+\def\HyPsdSubst#1#2#3{%
+  \def\HyPsdReplace##1#1##2\END{%
+    ##1%
+    \ifx\\##2\\%
+    \else
+      #2%
+      \HyReturnAfterFi{%
+        \HyPsdReplace##2\END
+      }%
+    \fi
+  }%
+  \xdef#3{\expandafter\HyPsdReplace#3#1\END}%
+}
+\long\def\HyReturnAfterFi#1\fi{\fi#1}
+
+% #1 is a control sequence in which to do the replacements.
+\def\backslashparens#1{%
+  \xdef#1{#1}% redefine it as its expansion; the definition is simply
+             % \lastnode when called from \setref -> \pdfmkdest.
+  \HyPsdSubst{(}{\realbackslash(}{#1}%
+  \HyPsdSubst{)}{\realbackslash)}{#1}%
+}
+
+\newhelp\nopdfimagehelp{Texinfo supports .png, .jpg, .jpeg, and .pdf images
+with PDF output, and none of those formats could be found.  (.eps cannot
+be supported due to the design of the PDF format; use regular TeX (DVI
+output) for that.)}
+
+\ifpdf
+  %
+  % Color manipulation macros based on pdfcolor.tex,
+  % except using rgb instead of cmyk; the latter is said to render as a
+  % very dark gray on-screen and a very dark halftone in print, instead
+  % of actual black.
+  \def\rgbDarkRed{0.50 0.09 0.12}
+  \def\rgbBlack{0 0 0}
+  %
+  % k sets the color for filling (usual text, etc.);
+  % K sets the color for stroking (thin rules, e.g., normal _'s).
+  \def\pdfsetcolor#1{\pdfliteral{#1 rg  #1 RG}}
+  %
+  % Set color, and create a mark which defines \thiscolor accordingly,
+  % so that \makeheadline knows which color to restore.
+  \def\setcolor#1{%
+    \xdef\lastcolordefs{\gdef\noexpand\thiscolor{#1}}%
+    \domark
+    \pdfsetcolor{#1}%
+  }
+  %
+  \def\maincolor{\rgbBlack}
+  \pdfsetcolor{\maincolor}
+  \edef\thiscolor{\maincolor}
+  \def\lastcolordefs{}
+  %
+  \def\makefootline{%
+    \baselineskip24pt
+    \line{\pdfsetcolor{\maincolor}\the\footline}%
+  }
+  %
+  \def\makeheadline{%
+    \vbox to 0pt{%
+      \vskip-22.5pt
+      \line{%
+        \vbox to8.5pt{}%
+        % Extract \thiscolor definition from the marks.
+        \getcolormarks
+        % Typeset the headline with \maincolor, then restore the color.
+        \pdfsetcolor{\maincolor}\the\headline\pdfsetcolor{\thiscolor}%
+      }%
+      \vss
+    }%
+    \nointerlineskip
+  }
+  %
+  %
+  \pdfcatalog{/PageMode /UseOutlines}
+  %
+  % #1 is image name, #2 width (might be empty/whitespace), #3 height (ditto).
+  \def\dopdfimage#1#2#3{%
+    \def\imagewidth{#2}\setbox0 = \hbox{\ignorespaces #2}%
+    \def\imageheight{#3}\setbox2 = \hbox{\ignorespaces #3}%
+    %
+    % pdftex (and the PDF format) support .png, .jpg, .pdf (among
+    % others).  Let's try in that order.
+    \let\pdfimgext=\empty
+    \begingroup
+      \openin 1 #1.png \ifeof 1
+        \openin 1 #1.jpg \ifeof 1
+          \openin 1 #1.jpeg \ifeof 1
+            \openin 1 #1.JPG \ifeof 1
+              \openin 1 #1.pdf \ifeof 1
+                \openin 1 #1.PDF \ifeof 1
+                  \errhelp = \nopdfimagehelp
+                  \errmessage{Could not find image file #1 for pdf}%
+                \else \gdef\pdfimgext{PDF}%
+                \fi
+              \else \gdef\pdfimgext{pdf}%
+              \fi
+            \else \gdef\pdfimgext{JPG}%
+            \fi
+          \else \gdef\pdfimgext{jpeg}%
+          \fi
+        \else \gdef\pdfimgext{jpg}%
+        \fi
+      \else \gdef\pdfimgext{png}%
+      \fi
+      \closein 1
+    \endgroup
+    %
+    % without \immediate, ancient pdftex seg faults when the same image is
+    % included twice.  (Version 3.14159-pre-1.0-unofficial-20010704.)
+    \ifnum\pdftexversion < 14
+      \immediate\pdfimage
+    \else
+      \immediate\pdfximage
+    \fi
+      \ifdim \wd0 >0pt width \imagewidth \fi
+      \ifdim \wd2 >0pt height \imageheight \fi
+      \ifnum\pdftexversion<13
+         #1.\pdfimgext
+       \else
+         {#1.\pdfimgext}%
+       \fi
+    \ifnum\pdftexversion < 14 \else
+      \pdfrefximage \pdflastximage
+    \fi}
+  %
+  \def\pdfmkdest#1{{%
+    % We have to set dummies so commands such as @code, and characters
+    % such as \, aren't expanded when present in a section title.
+    \indexnofonts
+    \turnoffactive
+    \activebackslashdouble
+    \makevalueexpandable
+    \def\pdfdestname{#1}%
+    \backslashparens\pdfdestname
+    \safewhatsit{\pdfdest name{\pdfdestname} xyz}%
+  }}
+  %
+  % used to mark target names; must be expandable.
+  \def\pdfmkpgn#1{#1}
+  %
+  % by default, use a color that is dark enough to print on paper as
+  % nearly black, but still distinguishable for online viewing.
+  \def\urlcolor{\rgbDarkRed}
+  \def\linkcolor{\rgbDarkRed}
+  \def\endlink{\setcolor{\maincolor}\pdfendlink}
+  %
+  % Adding outlines to PDF; macros for calculating structure of outlines
+  % come from Petr Olsak
+  \def\expnumber#1{\expandafter\ifx\csname#1\endcsname\relax 0%
+    \else \csname#1\endcsname \fi}
+  \def\advancenumber#1{\tempnum=\expnumber{#1}\relax
+    \advance\tempnum by 1
+    \expandafter\xdef\csname#1\endcsname{\the\tempnum}}
+  %
+  % #1 is the section text, which is what will be displayed in the
+  % outline by the pdf viewer.  #2 is the pdf expression for the number
+  % of subentries (or empty, for subsubsections).  #3 is the node text,
+  % which might be empty if this toc entry had no corresponding node.
+  % #4 is the page number
+  %
+  \def\dopdfoutline#1#2#3#4{%
+    % Generate a link to the node text if that exists; else, use the
+    % page number.  We could generate a destination for the section
+    % text in the case where a section has no node, but it doesn't
+    % seem worth the trouble, since most documents are normally structured.
+    \def\pdfoutlinedest{#3}%
+    \ifx\pdfoutlinedest\empty
+      \def\pdfoutlinedest{#4}%
+    \else
+      % Doubled backslashes in the name.
+      {\activebackslashdouble \xdef\pdfoutlinedest{#3}%
+       \backslashparens\pdfoutlinedest}%
+    \fi
+    %
+    % Also double the backslashes in the display string.
+    {\activebackslashdouble \xdef\pdfoutlinetext{#1}%
+     \backslashparens\pdfoutlinetext}%
+    %
+    \pdfoutline goto name{\pdfmkpgn{\pdfoutlinedest}}#2{\pdfoutlinetext}%
+  }
+  %
+  \def\pdfmakeoutlines{%
+    \begingroup
+      % Thanh's hack / proper braces in bookmarks
+      \edef\mylbrace{\iftrue \string{\else}\fi}\let\{=\mylbrace
+      \edef\myrbrace{\iffalse{\else\string}\fi}\let\}=\myrbrace
+      %
+      % Read toc silently, to get counts of subentries for \pdfoutline.
+      \def\numchapentry##1##2##3##4{%
+	\def\thischapnum{##2}%
+	\def\thissecnum{0}%
+	\def\thissubsecnum{0}%
+      }%
+      \def\numsecentry##1##2##3##4{%
+	\advancenumber{chap\thischapnum}%
+	\def\thissecnum{##2}%
+	\def\thissubsecnum{0}%
+      }%
+      \def\numsubsecentry##1##2##3##4{%
+	\advancenumber{sec\thissecnum}%
+	\def\thissubsecnum{##2}%
+      }%
+      \def\numsubsubsecentry##1##2##3##4{%
+	\advancenumber{subsec\thissubsecnum}%
+      }%
+      \def\thischapnum{0}%
+      \def\thissecnum{0}%
+      \def\thissubsecnum{0}%
+      %
+      % use \def rather than \let here because we redefine \chapentry et
+      % al. a second time, below.
+      \def\appentry{\numchapentry}%
+      \def\appsecentry{\numsecentry}%
+      \def\appsubsecentry{\numsubsecentry}%
+      \def\appsubsubsecentry{\numsubsubsecentry}%
+      \def\unnchapentry{\numchapentry}%
+      \def\unnsecentry{\numsecentry}%
+      \def\unnsubsecentry{\numsubsecentry}%
+      \def\unnsubsubsecentry{\numsubsubsecentry}%
+      \readdatafile{toc}%
+      %
+      % Read toc second time, this time actually producing the outlines.
+      % The `-' means take the \expnumber as the absolute number of
+      % subentries, which we calculated on our first read of the .toc above.
+      %
+      % We use the node names as the destinations.
+      \def\numchapentry##1##2##3##4{%
+        \dopdfoutline{##1}{count-\expnumber{chap##2}}{##3}{##4}}%
+      \def\numsecentry##1##2##3##4{%
+        \dopdfoutline{##1}{count-\expnumber{sec##2}}{##3}{##4}}%
+      \def\numsubsecentry##1##2##3##4{%
+        \dopdfoutline{##1}{count-\expnumber{subsec##2}}{##3}{##4}}%
+      \def\numsubsubsecentry##1##2##3##4{% count is always zero
+        \dopdfoutline{##1}{}{##3}{##4}}%
+      %
+      % PDF outlines are displayed using system fonts, instead of
+      % document fonts.  Therefore we cannot use special characters,
+      % since the encoding is unknown.  For example, the eogonek from
+      % Latin 2 (0xea) gets translated to a | character.  Info from
+      % Staszek Wawrykiewicz, 19 Jan 2004 04:09:24 +0100.
+      %
+      % xx to do this right, we have to translate 8-bit characters to
+      % their "best" equivalent, based on the @documentencoding.  Right
+      % now, I guess we'll just let the pdf reader have its way.
+      \indexnofonts
+      \setupdatafile
+      \catcode`\\=\active \otherbackslash
+      \input \tocreadfilename
+    \endgroup
+  }
+  %
+  \def\skipspaces#1{\def\PP{#1}\def\D{|}%
+    \ifx\PP\D\let\nextsp\relax
+    \else\let\nextsp\skipspaces
+      \ifx\p\space\else\addtokens{\filename}{\PP}%
+        \advance\filenamelength by 1
+      \fi
+    \fi
+    \nextsp}
+  \def\getfilename#1{\filenamelength=0\expandafter\skipspaces#1|\relax}
+  \ifnum\pdftexversion < 14
+    \let \startlink \pdfannotlink
+  \else
+    \let \startlink \pdfstartlink
+  \fi
+  % make a live url in pdf output.
+  \def\pdfurl#1{%
+    \begingroup
+      % it seems we really need yet another set of dummies; have not
+      % tried to figure out what each command should do in the context
+      % of @url.  for now, just make @/ a no-op, that's the only one
+      % people have actually reported a problem with.
+      %
+      \normalturnoffactive
+      \def\@{@}%
+      \let\/=\empty
+      \makevalueexpandable
+      % do we want to go so far as to use \indexnofonts instead of just
+      % special-casing \var here?
+      \def\var##1{##1}%
+      %
+      \leavevmode\setcolor{\urlcolor}%
+      \startlink attr{/Border [0 0 0]}%
+        user{/Subtype /Link /A << /S /URI /URI (#1) >>}%
+    \endgroup}
+  \def\pdfgettoks#1.{\setbox\boxA=\hbox{\toksA={#1.}\toksB={}\maketoks}}
+  \def\addtokens#1#2{\edef\addtoks{\noexpand#1={\the#1#2}}\addtoks}
+  \def\adn#1{\addtokens{\toksC}{#1}\global\countA=1\let\next=\maketoks}
+  \def\poptoks#1#2|ENDTOKS|{\let\first=#1\toksD={#1}\toksA={#2}}
+  \def\maketoks{%
+    \expandafter\poptoks\the\toksA|ENDTOKS|\relax
+    \ifx\first0\adn0
+    \else\ifx\first1\adn1 \else\ifx\first2\adn2 \else\ifx\first3\adn3
+    \else\ifx\first4\adn4 \else\ifx\first5\adn5 \else\ifx\first6\adn6
+    \else\ifx\first7\adn7 \else\ifx\first8\adn8 \else\ifx\first9\adn9
+    \else
+      \ifnum0=\countA\else\makelink\fi
+      \ifx\first.\let\next=\done\else
+        \let\next=\maketoks
+        \addtokens{\toksB}{\the\toksD}
+        \ifx\first,\addtokens{\toksB}{\space}\fi
+      \fi
+    \fi\fi\fi\fi\fi\fi\fi\fi\fi\fi
+    \next}
+  \def\makelink{\addtokens{\toksB}%
+    {\noexpand\pdflink{\the\toksC}}\toksC={}\global\countA=0}
+  \def\pdflink#1{%
+    \startlink attr{/Border [0 0 0]} goto name{\pdfmkpgn{#1}}
+    \setcolor{\linkcolor}#1\endlink}
+  \def\done{\edef\st{\global\noexpand\toksA={\the\toksB}}\st}
+\else
+  % non-pdf mode
+  \let\pdfmkdest = \gobble
+  \let\pdfurl = \gobble
+  \let\endlink = \relax
+  \let\setcolor = \gobble
+  \let\pdfsetcolor = \gobble
+  \let\pdfmakeoutlines = \relax
+\fi  % \ifx\pdfoutput
+
+
+\message{fonts,}
+
+% Change the current font style to #1, remembering it in \curfontstyle.
+% For now, we do not accumulate font styles: @b{@i{foo}} prints foo in
+% italics, not bold italics.
+%
+\def\setfontstyle#1{%
+  \def\curfontstyle{#1}% not as a control sequence, because we are \edef'd.
+  \csname ten#1\endcsname  % change the current font
+}
+
+% Select #1 fonts with the current style.
+%
+\def\selectfonts#1{\csname #1fonts\endcsname \csname\curfontstyle\endcsname}
+
+\def\rm{\fam=0 \setfontstyle{rm}}
+\def\it{\fam=\itfam \setfontstyle{it}}
+\def\sl{\fam=\slfam \setfontstyle{sl}}
+\def\bf{\fam=\bffam \setfontstyle{bf}}\def\bfstylename{bf}
+\def\tt{\fam=\ttfam \setfontstyle{tt}}
+
+% Unfortunately, we have to override this for titles and the like, since
+% in those cases "rm" is bold.  Sigh.
+\def\rmisbold{\rm\def\curfontstyle{bf}}
+
+% Texinfo sort of supports the sans serif font style, which plain TeX does not.
+% So we set up a \sf.
+\newfam\sffam
+\def\sf{\fam=\sffam \setfontstyle{sf}}
+\let\li = \sf % Sometimes we call it \li, not \sf.
+
+% We don't need math for this font style.
+\def\ttsl{\setfontstyle{ttsl}}
+
+
+% Default leading.
+\newdimen\textleading  \textleading = 13.2pt
+
+% Set the baselineskip to #1, and the lineskip and strut size
+% correspondingly.  There is no deep meaning behind these magic numbers
+% used as factors; they just match (closely enough) what Knuth defined.
+%
+\def\lineskipfactor{.08333}
+\def\strutheightpercent{.70833}
+\def\strutdepthpercent {.29167}
+%
+% can get a sort of poor man's double spacing by redefining this.
+\def\baselinefactor{1}
+%
+\def\setleading#1{%
+  \dimen0 = #1\relax
+  \normalbaselineskip = \baselinefactor\dimen0
+  \normallineskip = \lineskipfactor\normalbaselineskip
+  \normalbaselines
+  \setbox\strutbox =\hbox{%
+    \vrule width0pt height\strutheightpercent\baselineskip
+                    depth \strutdepthpercent \baselineskip
+  }%
+}
+
+% PDF CMaps.  See also LaTeX's t1.cmap.
+%
+% do nothing with this by default.
+\expandafter\let\csname cmapOT1\endcsname\gobble
+\expandafter\let\csname cmapOT1IT\endcsname\gobble
+\expandafter\let\csname cmapOT1TT\endcsname\gobble
+
+% if we are producing pdf, and we have \pdffontattr, then define cmaps.
+% (\pdffontattr was introduced many years ago, but people still run
+% older pdftex's; it's easy to conditionalize, so we do.)
+\ifpdf \ifx\pdffontattr\undefined \else
+  \begingroup
+    \catcode`\^^M=\active \def^^M{^^J}% Output line endings as the ^^J char.
+    \catcode`\%=12 \immediate\pdfobj stream {%!PS-Adobe-3.0 Resource-CMap
+%%DocumentNeededResources: ProcSet (CIDInit)
+%%IncludeResource: ProcSet (CIDInit)
+%%BeginResource: CMap (TeX-OT1-0)
+%%Title: (TeX-OT1-0 TeX OT1 0)
+%%Version: 1.000
+%%EndComments
+/CIDInit /ProcSet findresource begin
+12 dict begin
+begincmap
+/CIDSystemInfo
+<< /Registry (TeX)
+/Ordering (OT1)
+/Supplement 0
+>> def
+/CMapName /TeX-OT1-0 def
+/CMapType 2 def
+1 begincodespacerange
+<00> <7F>
+endcodespacerange
+8 beginbfrange
+<00> <01> <0393>
+<09> <0A> <03A8>
+<23> <26> <0023>
+<28> <3B> <0028>
+<3F> <5B> <003F>
+<5D> <5E> <005D>
+<61> <7A> <0061>
+<7B> <7C> <2013>
+endbfrange
+40 beginbfchar
+<02> <0398>
+<03> <039B>
+<04> <039E>
+<05> <03A0>
+<06> <03A3>
+<07> <03D2>
+<08> <03A6>
+<0B> <00660066>
+<0C> <00660069>
+<0D> <0066006C>
+<0E> <006600660069>
+<0F> <00660066006C>
+<10> <0131>
+<11> <0237>
+<12> <0060>
+<13> <00B4>
+<14> <02C7>
+<15> <02D8>
+<16> <00AF>
+<17> <02DA>
+<18> <00B8>
+<19> <00DF>
+<1A> <00E6>
+<1B> <0153>
+<1C> <00F8>
+<1D> <00C6>
+<1E> <0152>
+<1F> <00D8>
+<21> <0021>
+<22> <201D>
+<27> <2019>
+<3C> <00A1>
+<3D> <003D>
+<3E> <00BF>
+<5C> <201C>
+<5F> <02D9>
+<60> <2018>
+<7D> <02DD>
+<7E> <007E>
+<7F> <00A8>
+endbfchar
+endcmap
+CMapName currentdict /CMap defineresource pop
+end
+end
+%%EndResource
+%%EOF
+    }\endgroup
+  \expandafter\edef\csname cmapOT1\endcsname#1{%
+    \pdffontattr#1{/ToUnicode \the\pdflastobj\space 0 R}%
+  }%
+%
+% \cmapOT1IT
+  \begingroup
+    \catcode`\^^M=\active \def^^M{^^J}% Output line endings as the ^^J char.
+    \catcode`\%=12 \immediate\pdfobj stream {%!PS-Adobe-3.0 Resource-CMap
+%%DocumentNeededResources: ProcSet (CIDInit)
+%%IncludeResource: ProcSet (CIDInit)
+%%BeginResource: CMap (TeX-OT1IT-0)
+%%Title: (TeX-OT1IT-0 TeX OT1IT 0)
+%%Version: 1.000
+%%EndComments
+/CIDInit /ProcSet findresource begin
+12 dict begin
+begincmap
+/CIDSystemInfo
+<< /Registry (TeX)
+/Ordering (OT1IT)
+/Supplement 0
+>> def
+/CMapName /TeX-OT1IT-0 def
+/CMapType 2 def
+1 begincodespacerange
+<00> <7F>
+endcodespacerange
+8 beginbfrange
+<00> <01> <0393>
+<09> <0A> <03A8>
+<25> <26> <0025>
+<28> <3B> <0028>
+<3F> <5B> <003F>
+<5D> <5E> <005D>
+<61> <7A> <0061>
+<7B> <7C> <2013>
+endbfrange
+42 beginbfchar
+<02> <0398>
+<03> <039B>
+<04> <039E>
+<05> <03A0>
+<06> <03A3>
+<07> <03D2>
+<08> <03A6>
+<0B> <00660066>
+<0C> <00660069>
+<0D> <0066006C>
+<0E> <006600660069>
+<0F> <00660066006C>
+<10> <0131>
+<11> <0237>
+<12> <0060>
+<13> <00B4>
+<14> <02C7>
+<15> <02D8>
+<16> <00AF>
+<17> <02DA>
+<18> <00B8>
+<19> <00DF>
+<1A> <00E6>
+<1B> <0153>
+<1C> <00F8>
+<1D> <00C6>
+<1E> <0152>
+<1F> <00D8>
+<21> <0021>
+<22> <201D>
+<23> <0023>
+<24> <00A3>
+<27> <2019>
+<3C> <00A1>
+<3D> <003D>
+<3E> <00BF>
+<5C> <201C>
+<5F> <02D9>
+<60> <2018>
+<7D> <02DD>
+<7E> <007E>
+<7F> <00A8>
+endbfchar
+endcmap
+CMapName currentdict /CMap defineresource pop
+end
+end
+%%EndResource
+%%EOF
+    }\endgroup
+  \expandafter\edef\csname cmapOT1IT\endcsname#1{%
+    \pdffontattr#1{/ToUnicode \the\pdflastobj\space 0 R}%
+  }%
+%
+% \cmapOT1TT
+  \begingroup
+    \catcode`\^^M=\active \def^^M{^^J}% Output line endings as the ^^J char.
+    \catcode`\%=12 \immediate\pdfobj stream {%!PS-Adobe-3.0 Resource-CMap
+%%DocumentNeededResources: ProcSet (CIDInit)
+%%IncludeResource: ProcSet (CIDInit)
+%%BeginResource: CMap (TeX-OT1TT-0)
+%%Title: (TeX-OT1TT-0 TeX OT1TT 0)
+%%Version: 1.000
+%%EndComments
+/CIDInit /ProcSet findresource begin
+12 dict begin
+begincmap
+/CIDSystemInfo
+<< /Registry (TeX)
+/Ordering (OT1TT)
+/Supplement 0
+>> def
+/CMapName /TeX-OT1TT-0 def
+/CMapType 2 def
+1 begincodespacerange
+<00> <7F>
+endcodespacerange
+5 beginbfrange
+<00> <01> <0393>
+<09> <0A> <03A8>
+<21> <26> <0021>
+<28> <5F> <0028>
+<61> <7E> <0061>
+endbfrange
+32 beginbfchar
+<02> <0398>
+<03> <039B>
+<04> <039E>
+<05> <03A0>
+<06> <03A3>
+<07> <03D2>
+<08> <03A6>
+<0B> <2191>
+<0C> <2193>
+<0D> <0027>
+<0E> <00A1>
+<0F> <00BF>
+<10> <0131>
+<11> <0237>
+<12> <0060>
+<13> <00B4>
+<14> <02C7>
+<15> <02D8>
+<16> <00AF>
+<17> <02DA>
+<18> <00B8>
+<19> <00DF>
+<1A> <00E6>
+<1B> <0153>
+<1C> <00F8>
+<1D> <00C6>
+<1E> <0152>
+<1F> <00D8>
+<20> <2423>
+<27> <2019>
+<60> <2018>
+<7F> <00A8>
+endbfchar
+endcmap
+CMapName currentdict /CMap defineresource pop
+end
+end
+%%EndResource
+%%EOF
+    }\endgroup
+  \expandafter\edef\csname cmapOT1TT\endcsname#1{%
+    \pdffontattr#1{/ToUnicode \the\pdflastobj\space 0 R}%
+  }%
+\fi\fi
+
+
+% Set the font macro #1 to the font named #2, adding on the
+% specified font prefix (normally `cm').
+% #3 is the font's design size, #4 is a scale factor, #5 is the CMap
+% encoding (currently only OT1, OT1IT and OT1TT are allowed, pass
+% empty to omit).
+\def\setfont#1#2#3#4#5{%
+  \font#1=\fontprefix#2#3 scaled #4
+  \csname cmap#5\endcsname#1%
+}
+% This is what gets called when #5 of \setfont is empty.
+\let\cmap\gobble
+% emacs-page end of cmaps
+
+% Use cm as the default font prefix.
+% To specify the font prefix, you must define \fontprefix
+% before you read in texinfo.tex.
+\ifx\fontprefix\undefined
+\def\fontprefix{cm}
+\fi
+% Support font families that don't use the same naming scheme as CM.
+\def\rmshape{r}
+\def\rmbshape{bx}               %where the normal face is bold
+\def\bfshape{b}
+\def\bxshape{bx}
+\def\ttshape{tt}
+\def\ttbshape{tt}
+\def\ttslshape{sltt}
+\def\itshape{ti}
+\def\itbshape{bxti}
+\def\slshape{sl}
+\def\slbshape{bxsl}
+\def\sfshape{ss}
+\def\sfbshape{ss}
+\def\scshape{csc}
+\def\scbshape{csc}
+
+% Definitions for a main text size of 11pt.  This is the default in
+% Texinfo.
+%
+\def\definetextfontsizexi{%
+% Text fonts (11.2pt, magstep1).
+\def\textnominalsize{11pt}
+\edef\mainmagstep{\magstephalf}
+\setfont\textrm\rmshape{10}{\mainmagstep}{OT1}
+\setfont\texttt\ttshape{10}{\mainmagstep}{OT1TT}
+\setfont\textbf\bfshape{10}{\mainmagstep}{OT1}
+\setfont\textit\itshape{10}{\mainmagstep}{OT1IT}
+\setfont\textsl\slshape{10}{\mainmagstep}{OT1}
+\setfont\textsf\sfshape{10}{\mainmagstep}{OT1}
+\setfont\textsc\scshape{10}{\mainmagstep}{OT1}
+\setfont\textttsl\ttslshape{10}{\mainmagstep}{OT1TT}
+\font\texti=cmmi10 scaled \mainmagstep
+\font\textsy=cmsy10 scaled \mainmagstep
+\def\textecsize{1095}
+
+% A few fonts for @defun names and args.
+\setfont\defbf\bfshape{10}{\magstep1}{OT1}
+\setfont\deftt\ttshape{10}{\magstep1}{OT1TT}
+\setfont\defttsl\ttslshape{10}{\magstep1}{OT1TT}
+\def\df{\let\tentt=\deftt \let\tenbf = \defbf \let\tenttsl=\defttsl \bf}
+
+% Fonts for indices, footnotes, small examples (9pt).
+\def\smallnominalsize{9pt}
+\setfont\smallrm\rmshape{9}{1000}{OT1}
+\setfont\smalltt\ttshape{9}{1000}{OT1TT}
+\setfont\smallbf\bfshape{10}{900}{OT1}
+\setfont\smallit\itshape{9}{1000}{OT1IT}
+\setfont\smallsl\slshape{9}{1000}{OT1}
+\setfont\smallsf\sfshape{9}{1000}{OT1}
+\setfont\smallsc\scshape{10}{900}{OT1}
+\setfont\smallttsl\ttslshape{10}{900}{OT1TT}
+\font\smalli=cmmi9
+\font\smallsy=cmsy9
+\def\smallecsize{0900}
+
+% Fonts for small examples (8pt).
+\def\smallernominalsize{8pt}
+\setfont\smallerrm\rmshape{8}{1000}{OT1}
+\setfont\smallertt\ttshape{8}{1000}{OT1TT}
+\setfont\smallerbf\bfshape{10}{800}{OT1}
+\setfont\smallerit\itshape{8}{1000}{OT1IT}
+\setfont\smallersl\slshape{8}{1000}{OT1}
+\setfont\smallersf\sfshape{8}{1000}{OT1}
+\setfont\smallersc\scshape{10}{800}{OT1}
+\setfont\smallerttsl\ttslshape{10}{800}{OT1TT}
+\font\smalleri=cmmi8
+\font\smallersy=cmsy8
+\def\smallerecsize{0800}
+
+% Fonts for title page (20.4pt):
+\def\titlenominalsize{20pt}
+\setfont\titlerm\rmbshape{12}{\magstep3}{OT1}
+\setfont\titleit\itbshape{10}{\magstep4}{OT1IT}
+\setfont\titlesl\slbshape{10}{\magstep4}{OT1}
+\setfont\titlett\ttbshape{12}{\magstep3}{OT1TT}
+\setfont\titlettsl\ttslshape{10}{\magstep4}{OT1TT}
+\setfont\titlesf\sfbshape{17}{\magstep1}{OT1}
+\let\titlebf=\titlerm
+\setfont\titlesc\scbshape{10}{\magstep4}{OT1}
+\font\titlei=cmmi12 scaled \magstep3
+\font\titlesy=cmsy10 scaled \magstep4
+\def\titleecsize{2074}
+
+% Chapter (and unnumbered) fonts (17.28pt).
+\def\chapnominalsize{17pt}
+\setfont\chaprm\rmbshape{12}{\magstep2}{OT1}
+\setfont\chapit\itbshape{10}{\magstep3}{OT1IT}
+\setfont\chapsl\slbshape{10}{\magstep3}{OT1}
+\setfont\chaptt\ttbshape{12}{\magstep2}{OT1TT}
+\setfont\chapttsl\ttslshape{10}{\magstep3}{OT1TT}
+\setfont\chapsf\sfbshape{17}{1000}{OT1}
+\let\chapbf=\chaprm
+\setfont\chapsc\scbshape{10}{\magstep3}{OT1}
+\font\chapi=cmmi12 scaled \magstep2
+\font\chapsy=cmsy10 scaled \magstep3
+\def\chapecsize{1728}
+
+% Section fonts (14.4pt).
+\def\secnominalsize{14pt}
+\setfont\secrm\rmbshape{12}{\magstep1}{OT1}
+\setfont\secit\itbshape{10}{\magstep2}{OT1IT}
+\setfont\secsl\slbshape{10}{\magstep2}{OT1}
+\setfont\sectt\ttbshape{12}{\magstep1}{OT1TT}
+\setfont\secttsl\ttslshape{10}{\magstep2}{OT1TT}
+\setfont\secsf\sfbshape{12}{\magstep1}{OT1}
+\let\secbf\secrm
+\setfont\secsc\scbshape{10}{\magstep2}{OT1}
+\font\seci=cmmi12 scaled \magstep1
+\font\secsy=cmsy10 scaled \magstep2
+\def\sececsize{1440}
+
+% Subsection fonts (13.15pt).
+\def\ssecnominalsize{13pt}
+\setfont\ssecrm\rmbshape{12}{\magstephalf}{OT1}
+\setfont\ssecit\itbshape{10}{1315}{OT1IT}
+\setfont\ssecsl\slbshape{10}{1315}{OT1}
+\setfont\ssectt\ttbshape{12}{\magstephalf}{OT1TT}
+\setfont\ssecttsl\ttslshape{10}{1315}{OT1TT}
+\setfont\ssecsf\sfbshape{12}{\magstephalf}{OT1}
+\let\ssecbf\ssecrm
+\setfont\ssecsc\scbshape{10}{1315}{OT1}
+\font\sseci=cmmi12 scaled \magstephalf
+\font\ssecsy=cmsy10 scaled 1315
+\def\ssececsize{1200}
+
+% Reduced fonts for @acro in text (10pt).
+\def\reducednominalsize{10pt}
+\setfont\reducedrm\rmshape{10}{1000}{OT1}
+\setfont\reducedtt\ttshape{10}{1000}{OT1TT}
+\setfont\reducedbf\bfshape{10}{1000}{OT1}
+\setfont\reducedit\itshape{10}{1000}{OT1IT}
+\setfont\reducedsl\slshape{10}{1000}{OT1}
+\setfont\reducedsf\sfshape{10}{1000}{OT1}
+\setfont\reducedsc\scshape{10}{1000}{OT1}
+\setfont\reducedttsl\ttslshape{10}{1000}{OT1TT}
+\font\reducedi=cmmi10
+\font\reducedsy=cmsy10
+\def\reducedecsize{1000}
+
+% reset the current fonts
+\textfonts
+\rm
+} % end of 11pt text font size definitions
+
+
+% Definitions to make the main text be 10pt Computer Modern, with
+% section, chapter, etc., sizes following suit.  This is for the GNU
+% Press printing of the Emacs 22 manual.  Maybe other manuals in the
+% future.  Used with @smallbook, which sets the leading to 12pt.
+%
+\def\definetextfontsizex{%
+% Text fonts (10pt).
+\def\textnominalsize{10pt}
+\edef\mainmagstep{1000}
+\setfont\textrm\rmshape{10}{\mainmagstep}{OT1}
+\setfont\texttt\ttshape{10}{\mainmagstep}{OT1TT}
+\setfont\textbf\bfshape{10}{\mainmagstep}{OT1}
+\setfont\textit\itshape{10}{\mainmagstep}{OT1IT}
+\setfont\textsl\slshape{10}{\mainmagstep}{OT1}
+\setfont\textsf\sfshape{10}{\mainmagstep}{OT1}
+\setfont\textsc\scshape{10}{\mainmagstep}{OT1}
+\setfont\textttsl\ttslshape{10}{\mainmagstep}{OT1TT}
+\font\texti=cmmi10 scaled \mainmagstep
+\font\textsy=cmsy10 scaled \mainmagstep
+\def\textecsize{1000}
+
+% A few fonts for @defun names and args.
+\setfont\defbf\bfshape{10}{\magstephalf}{OT1}
+\setfont\deftt\ttshape{10}{\magstephalf}{OT1TT}
+\setfont\defttsl\ttslshape{10}{\magstephalf}{OT1TT}
+\def\df{\let\tentt=\deftt \let\tenbf = \defbf \let\tenttsl=\defttsl \bf}
+
+% Fonts for indices, footnotes, small examples (9pt).
+\def\smallnominalsize{9pt}
+\setfont\smallrm\rmshape{9}{1000}{OT1}
+\setfont\smalltt\ttshape{9}{1000}{OT1TT}
+\setfont\smallbf\bfshape{10}{900}{OT1}
+\setfont\smallit\itshape{9}{1000}{OT1IT}
+\setfont\smallsl\slshape{9}{1000}{OT1}
+\setfont\smallsf\sfshape{9}{1000}{OT1}
+\setfont\smallsc\scshape{10}{900}{OT1}
+\setfont\smallttsl\ttslshape{10}{900}{OT1TT}
+\font\smalli=cmmi9
+\font\smallsy=cmsy9
+\def\smallecsize{0900}
+
+% Fonts for small examples (8pt).
+\def\smallernominalsize{8pt}
+\setfont\smallerrm\rmshape{8}{1000}{OT1}
+\setfont\smallertt\ttshape{8}{1000}{OT1TT}
+\setfont\smallerbf\bfshape{10}{800}{OT1}
+\setfont\smallerit\itshape{8}{1000}{OT1IT}
+\setfont\smallersl\slshape{8}{1000}{OT1}
+\setfont\smallersf\sfshape{8}{1000}{OT1}
+\setfont\smallersc\scshape{10}{800}{OT1}
+\setfont\smallerttsl\ttslshape{10}{800}{OT1TT}
+\font\smalleri=cmmi8
+\font\smallersy=cmsy8
+\def\smallerecsize{0800}
+
+% Fonts for title page (20.4pt):
+\def\titlenominalsize{20pt}
+\setfont\titlerm\rmbshape{12}{\magstep3}{OT1}
+\setfont\titleit\itbshape{10}{\magstep4}{OT1IT}
+\setfont\titlesl\slbshape{10}{\magstep4}{OT1}
+\setfont\titlett\ttbshape{12}{\magstep3}{OT1TT}
+\setfont\titlettsl\ttslshape{10}{\magstep4}{OT1TT}
+\setfont\titlesf\sfbshape{17}{\magstep1}{OT1}
+\let\titlebf=\titlerm
+\setfont\titlesc\scbshape{10}{\magstep4}{OT1}
+\font\titlei=cmmi12 scaled \magstep3
+\font\titlesy=cmsy10 scaled \magstep4
+\def\titleecsize{2074}
+
+% Chapter fonts (14.4pt).
+\def\chapnominalsize{14pt}
+\setfont\chaprm\rmbshape{12}{\magstep1}{OT1}
+\setfont\chapit\itbshape{10}{\magstep2}{OT1IT}
+\setfont\chapsl\slbshape{10}{\magstep2}{OT1}
+\setfont\chaptt\ttbshape{12}{\magstep1}{OT1TT}
+\setfont\chapttsl\ttslshape{10}{\magstep2}{OT1TT}
+\setfont\chapsf\sfbshape{12}{\magstep1}{OT1}
+\let\chapbf\chaprm
+\setfont\chapsc\scbshape{10}{\magstep2}{OT1}
+\font\chapi=cmmi12 scaled \magstep1
+\font\chapsy=cmsy10 scaled \magstep2
+\def\chapecsize{1440}
+
+% Section fonts (12pt).
+\def\secnominalsize{12pt}
+\setfont\secrm\rmbshape{12}{1000}{OT1}
+\setfont\secit\itbshape{10}{\magstep1}{OT1IT}
+\setfont\secsl\slbshape{10}{\magstep1}{OT1}
+\setfont\sectt\ttbshape{12}{1000}{OT1TT}
+\setfont\secttsl\ttslshape{10}{\magstep1}{OT1TT}
+\setfont\secsf\sfbshape{12}{1000}{OT1}
+\let\secbf\secrm
+\setfont\secsc\scbshape{10}{\magstep1}{OT1}
+\font\seci=cmmi12
+\font\secsy=cmsy10 scaled \magstep1
+\def\sececsize{1200}
+
+% Subsection fonts (10pt).
+\def\ssecnominalsize{10pt}
+\setfont\ssecrm\rmbshape{10}{1000}{OT1}
+\setfont\ssecit\itbshape{10}{1000}{OT1IT}
+\setfont\ssecsl\slbshape{10}{1000}{OT1}
+\setfont\ssectt\ttbshape{10}{1000}{OT1TT}
+\setfont\ssecttsl\ttslshape{10}{1000}{OT1TT}
+\setfont\ssecsf\sfbshape{10}{1000}{OT1}
+\let\ssecbf\ssecrm
+\setfont\ssecsc\scbshape{10}{1000}{OT1}
+\font\sseci=cmmi10
+\font\ssecsy=cmsy10
+\def\ssececsize{1000}
+
+% Reduced fonts for @acro in text (9pt).
+\def\reducednominalsize{9pt}
+\setfont\reducedrm\rmshape{9}{1000}{OT1}
+\setfont\reducedtt\ttshape{9}{1000}{OT1TT}
+\setfont\reducedbf\bfshape{10}{900}{OT1}
+\setfont\reducedit\itshape{9}{1000}{OT1IT}
+\setfont\reducedsl\slshape{9}{1000}{OT1}
+\setfont\reducedsf\sfshape{9}{1000}{OT1}
+\setfont\reducedsc\scshape{10}{900}{OT1}
+\setfont\reducedttsl\ttslshape{10}{900}{OT1TT}
+\font\reducedi=cmmi9
+\font\reducedsy=cmsy9
+\def\reducedecsize{0900}
+
+% reduce space between paragraphs
+\divide\parskip by 2
+
+% reset the current fonts
+\textfonts
+\rm
+} % end of 10pt text font size definitions
+
+
+% We provide the user-level command
+%   @fonttextsize 10
+% (or 11) to redefine the text font size.  pt is assumed.
+%
+\def\xword{10}
+\def\xiword{11}
+%
+\parseargdef\fonttextsize{%
+  \def\textsizearg{#1}%
+  \wlog{doing @fonttextsize \textsizearg}%
+  %
+  % Set \globaldefs so that documents can use this inside @tex, since
+  % makeinfo 4.8 does not support it, but we need it nonetheless.
+  %
+ \begingroup \globaldefs=1
+  \ifx\textsizearg\xword \definetextfontsizex
+  \else \ifx\textsizearg\xiword \definetextfontsizexi
+  \else
+    \errhelp=\EMsimple
+    \errmessage{@fonttextsize only supports `10' or `11', not `\textsizearg'}
+  \fi\fi
+ \endgroup
+}
+
+
+% In order for the font changes to affect most math symbols and letters,
+% we have to define the \textfont of the standard families.  Since
+% texinfo doesn't allow for producing subscripts and superscripts except
+% in the main text, we don't bother to reset \scriptfont and
+% \scriptscriptfont (which would also require loading a lot more fonts).
+%
+\def\resetmathfonts{%
+  \textfont0=\tenrm \textfont1=\teni \textfont2=\tensy
+  \textfont\itfam=\tenit \textfont\slfam=\tensl \textfont\bffam=\tenbf
+  \textfont\ttfam=\tentt \textfont\sffam=\tensf
+}
+
+% The font-changing commands redefine the meanings of \tenSTYLE, instead
+% of just \STYLE.  We do this because \STYLE needs to also set the
+% current \fam for math mode.  Our \STYLE (e.g., \rm) commands hardwire
+% \tenSTYLE to set the current font.
+%
+% Each font-changing command also sets the names \lsize (one size lower)
+% and \lllsize (three sizes lower).  These relative commands are used in
+% the LaTeX logo and acronyms.
+%
+% This all needs generalizing, badly.
+%
+\def\textfonts{%
+  \let\tenrm=\textrm \let\tenit=\textit \let\tensl=\textsl
+  \let\tenbf=\textbf \let\tentt=\texttt \let\smallcaps=\textsc
+  \let\tensf=\textsf \let\teni=\texti \let\tensy=\textsy
+  \let\tenttsl=\textttsl
+  \def\curfontsize{text}%
+  \def\lsize{reduced}\def\lllsize{smaller}%
+  \resetmathfonts \setleading{\textleading}}
+\def\titlefonts{%
+  \let\tenrm=\titlerm \let\tenit=\titleit \let\tensl=\titlesl
+  \let\tenbf=\titlebf \let\tentt=\titlett \let\smallcaps=\titlesc
+  \let\tensf=\titlesf \let\teni=\titlei \let\tensy=\titlesy
+  \let\tenttsl=\titlettsl
+  \def\curfontsize{title}%
+  \def\lsize{chap}\def\lllsize{subsec}%
+  \resetmathfonts \setleading{25pt}}
+\def\titlefont#1{{\titlefonts\rmisbold #1}}
+\def\chapfonts{%
+  \let\tenrm=\chaprm \let\tenit=\chapit \let\tensl=\chapsl
+  \let\tenbf=\chapbf \let\tentt=\chaptt \let\smallcaps=\chapsc
+  \let\tensf=\chapsf \let\teni=\chapi \let\tensy=\chapsy
+  \let\tenttsl=\chapttsl
+  \def\curfontsize{chap}%
+  \def\lsize{sec}\def\lllsize{text}%
+  \resetmathfonts \setleading{19pt}}
+\def\secfonts{%
+  \let\tenrm=\secrm \let\tenit=\secit \let\tensl=\secsl
+  \let\tenbf=\secbf \let\tentt=\sectt \let\smallcaps=\secsc
+  \let\tensf=\secsf \let\teni=\seci \let\tensy=\secsy
+  \let\tenttsl=\secttsl
+  \def\curfontsize{sec}%
+  \def\lsize{subsec}\def\lllsize{reduced}%
+  \resetmathfonts \setleading{16pt}}
+\def\subsecfonts{%
+  \let\tenrm=\ssecrm \let\tenit=\ssecit \let\tensl=\ssecsl
+  \let\tenbf=\ssecbf \let\tentt=\ssectt \let\smallcaps=\ssecsc
+  \let\tensf=\ssecsf \let\teni=\sseci \let\tensy=\ssecsy
+  \let\tenttsl=\ssecttsl
+  \def\curfontsize{ssec}%
+  \def\lsize{text}\def\lllsize{small}%
+  \resetmathfonts \setleading{15pt}}
+\let\subsubsecfonts = \subsecfonts
+\def\reducedfonts{%
+  \let\tenrm=\reducedrm \let\tenit=\reducedit \let\tensl=\reducedsl
+  \let\tenbf=\reducedbf \let\tentt=\reducedtt \let\reducedcaps=\reducedsc
+  \let\tensf=\reducedsf \let\teni=\reducedi \let\tensy=\reducedsy
+  \let\tenttsl=\reducedttsl
+  \def\curfontsize{reduced}%
+  \def\lsize{small}\def\lllsize{smaller}%
+  \resetmathfonts \setleading{10.5pt}}
+\def\smallfonts{%
+  \let\tenrm=\smallrm \let\tenit=\smallit \let\tensl=\smallsl
+  \let\tenbf=\smallbf \let\tentt=\smalltt \let\smallcaps=\smallsc
+  \let\tensf=\smallsf \let\teni=\smalli \let\tensy=\smallsy
+  \let\tenttsl=\smallttsl
+  \def\curfontsize{small}%
+  \def\lsize{smaller}\def\lllsize{smaller}%
+  \resetmathfonts \setleading{10.5pt}}
+\def\smallerfonts{%
+  \let\tenrm=\smallerrm \let\tenit=\smallerit \let\tensl=\smallersl
+  \let\tenbf=\smallerbf \let\tentt=\smallertt \let\smallcaps=\smallersc
+  \let\tensf=\smallersf \let\teni=\smalleri \let\tensy=\smallersy
+  \let\tenttsl=\smallerttsl
+  \def\curfontsize{smaller}%
+  \def\lsize{smaller}\def\lllsize{smaller}%
+  \resetmathfonts \setleading{9.5pt}}
+
+% Fonts for short table of contents.
+\setfont\shortcontrm\rmshape{12}{1000}{OT1}
+\setfont\shortcontbf\bfshape{10}{\magstep1}{OT1}  % no cmb12
+\setfont\shortcontsl\slshape{12}{1000}{OT1}
+\setfont\shortconttt\ttshape{12}{1000}{OT1TT}
+
+% Define these just so they can be easily changed for other fonts.
+\def\angleleft{$\langle$}
+\def\angleright{$\rangle$}
+
+% Set the fonts to use with the @small... environments.
+\let\smallexamplefonts = \smallfonts
+
+% About \smallexamplefonts.  If we use \smallfonts (9pt), @smallexample
+% can fit this many characters:
+%   8.5x11=86   smallbook=72  a4=90  a5=69
+% If we use \scriptfonts (8pt), then we can fit this many characters:
+%   8.5x11=90+  smallbook=80  a4=90+  a5=77
+% For me, subjectively, the few extra characters that fit aren't worth
+% the additional smallness of 8pt.  So I'm making the default 9pt.
+%
+% By the way, for comparison, here's what fits with @example (10pt):
+%   8.5x11=71  smallbook=60  a4=75  a5=58
+% --karl, 24jan03.
+
+% Set up the default fonts, so we can use them for creating boxes.
+%
+\definetextfontsizexi
+
+
+\message{markup,}
+
+% Check if we are currently using a typewriter font.  Since all the
+% Computer Modern typewriter fonts have zero interword stretch (and
+% shrink), and it is reasonable to expect all typewriter fonts to have
+% this property, we can check that font parameter.
+%
+\def\ifmonospace{\ifdim\fontdimen3\font=0pt }
+
+% Markup style infrastructure.  \defmarkupstylesetup\INITMACRO will
+% define and register \INITMACRO to be called on markup style changes.
+% \INITMACRO can check \currentmarkupstyle for the innermost
+% style and the set of \ifmarkupSTYLE switches for all styles
+% currently in effect.
+\newif\ifmarkupvar
+\newif\ifmarkupsamp
+\newif\ifmarkupkey
+%\newif\ifmarkupfile % @file == @samp.
+%\newif\ifmarkupoption % @option == @samp.
+\newif\ifmarkupcode
+\newif\ifmarkupkbd
+%\newif\ifmarkupenv % @env == @code.
+%\newif\ifmarkupcommand % @command == @code.
+\newif\ifmarkuptex % @tex (and part of @math, for now).
+\newif\ifmarkupexample
+\newif\ifmarkupverb
+\newif\ifmarkupverbatim
+
+\let\currentmarkupstyle\empty
+
+\def\setupmarkupstyle#1{%
+  \csname markup#1true\endcsname
+  \def\currentmarkupstyle{#1}%
+  \markupstylesetup
+}
+
+\let\markupstylesetup\empty
+
+\def\defmarkupstylesetup#1{%
+  \expandafter\def\expandafter\markupstylesetup
+    \expandafter{\markupstylesetup #1}%
+  \def#1%
+}
+
+% Markup style setup for left and right quotes.
+\defmarkupstylesetup\markupsetuplq{%
+  \expandafter\let\expandafter \temp \csname markupsetuplq\currentmarkupstyle\endcsname
+  \ifx\temp\relax \markupsetuplqdefault \else \temp \fi
+}
+
+\defmarkupstylesetup\markupsetuprq{%
+  \expandafter\let\expandafter \temp \csname markupsetuprq\currentmarkupstyle\endcsname
+  \ifx\temp\relax \markupsetuprqdefault \else \temp \fi
+}
+
+{
+\catcode`\'=\active
+\catcode`\`=\active
+
+\gdef\markupsetuplqdefault{\let`\lq}
+\gdef\markupsetuprqdefault{\let'\rq}
+
+\gdef\markupsetcodequoteleft{\let`\codequoteleft}
+\gdef\markupsetcodequoteright{\let'\codequoteright}
+
+\gdef\markupsetnoligaturesquoteleft{\let`\noligaturesquoteleft}
+}
+
+\let\markupsetuplqcode \markupsetcodequoteleft
+\let\markupsetuprqcode \markupsetcodequoteright
+\let\markupsetuplqexample \markupsetcodequoteleft
+\let\markupsetuprqexample \markupsetcodequoteright
+\let\markupsetuplqverb \markupsetcodequoteleft
+\let\markupsetuprqverb \markupsetcodequoteright
+\let\markupsetuplqverbatim \markupsetcodequoteleft
+\let\markupsetuprqverbatim \markupsetcodequoteright
+
+\let\markupsetuplqsamp \markupsetnoligaturesquoteleft
+\let\markupsetuplqkbd \markupsetnoligaturesquoteleft
+
+% Allow an option to not replace quotes with a regular directed right
+% quote/apostrophe (char 0x27), but instead use the undirected quote
+% from cmtt (char 0x0d).  The undirected quote is ugly, so don't make it
+% the default, but it works for pasting with more pdf viewers (at least
+% evince), the lilypond developers report.  xpdf does work with the
+% regular 0x27.
+%
+\def\codequoteright{%
+  \expandafter\ifx\csname SETtxicodequoteundirected\endcsname\relax
+    \expandafter\ifx\csname SETcodequoteundirected\endcsname\relax
+      '%
+    \else \char'15 \fi
+  \else \char'15 \fi
+}
+%
+% and a similar option for the left quote char vs. a grave accent.
+% Modern fonts display ASCII 0x60 as a grave accent, so some people like
+% the code environments to do likewise.
+%
+\def\codequoteleft{%
+  \expandafter\ifx\csname SETtxicodequotebacktick\endcsname\relax
+    \expandafter\ifx\csname SETcodequotebacktick\endcsname\relax
+      % [Knuth] pp. 380,381,391
+      % \relax disables Spanish ligatures ?` and !` of \tt font.
+      \relax`%
+    \else \char'22 \fi
+  \else \char'22 \fi
+}
+
+% [Knuth] pp. 380,381,391, disable Spanish ligatures ?` and !` of \tt font.
+\def\noligaturesquoteleft{\relax\lq}
+
+% Count depth in font-changes, for error checks
+\newcount\fontdepth \fontdepth=0
+
+%% Add scribe-like font environments, plus @l for inline lisp (usually sans
+%% serif) and @ii for TeX italic
+
+% \smartitalic{ARG} outputs arg in italics, followed by an italic correction
+% unless the following character is such as not to need one.
+\def\smartitalicx{\ifx\next,\else\ifx\next-\else\ifx\next.\else
+                    \ptexslash\fi\fi\fi}
+\def\smartslanted#1{{\ifusingtt\ttsl\sl #1}\futurelet\next\smartitalicx}
+\def\smartitalic#1{{\ifusingtt\ttsl\it #1}\futurelet\next\smartitalicx}
+
+% like \smartslanted except unconditionally uses \ttsl.
+% @var is set to this for defun arguments.
+\def\ttslanted#1{{\ttsl #1}\futurelet\next\smartitalicx}
+
+% @cite is like \smartslanted except unconditionally use \sl.  We never want
+% ttsl for book titles, do we?
+\def\cite#1{{\sl #1}\futurelet\next\smartitalicx}
+
+\let\i=\smartitalic
+\let\slanted=\smartslanted
+\def\var#1{{\setupmarkupstyle{var}\smartslanted{#1}}}
+\let\dfn=\smartslanted
+\let\emph=\smartitalic
+
+% Explicit font changes: @r, @sc, undocumented @ii.
+\def\r#1{{\rm #1}}              % roman font
+\def\sc#1{{\smallcaps#1}}       % smallcaps font
+\def\ii#1{{\it #1}}             % italic font
+
+% @b, explicit bold.  Also @strong.
+\def\b#1{{\bf #1}}
+\let\strong=\b
+
+% @sansserif, explicit sans.
+\def\sansserif#1{{\sf #1}}
+
+% We can't just use \exhyphenpenalty, because that only has effect at
+% the end of a paragraph.  Restore normal hyphenation at the end of the
+% group within which \nohyphenation is presumably called.
+%
+\def\nohyphenation{\hyphenchar\font = -1  \aftergroup\restorehyphenation}
+\def\restorehyphenation{\hyphenchar\font = `- }
+
+% Set sfcode to normal for the chars that usually have another value.
+% Can't use plain's \frenchspacing because it uses the `\x notation, and
+% sometimes \x has an active definition that messes things up.
+%
+\catcode`@=11
+  \def\plainfrenchspacing{%
+    \sfcode\dotChar  =\@m \sfcode\questChar=\@m \sfcode\exclamChar=\@m
+    \sfcode\colonChar=\@m \sfcode\semiChar =\@m \sfcode\commaChar =\@m
+    \def\endofsentencespacefactor{1000}% for @. and friends
+  }
+  \def\plainnonfrenchspacing{%
+    \sfcode`\.3000\sfcode`\?3000\sfcode`\!3000
+    \sfcode`\:2000\sfcode`\;1500\sfcode`\,1250
+    \def\endofsentencespacefactor{3000}% for @. and friends
+  }
+\catcode`@=\other
+\def\endofsentencespacefactor{3000}% default
+
+% @t, explicit typewriter.
+\def\t#1{%
+  {\tt \rawbackslash \plainfrenchspacing #1}%
+  \null
+}
+
+% @samp.
+\def\samp#1{{\setupmarkupstyle{samp}\lq\tclose{#1}\rq\null}}
+
+% definition of @key that produces a lozenge.  Doesn't adjust to text size.
+%\setfont\keyrm\rmshape{8}{1000}{OT1}
+%\font\keysy=cmsy9
+%\def\key#1{{\keyrm\textfont2=\keysy \leavevmode\hbox{%
+%  \raise0.4pt\hbox{\angleleft}\kern-.08em\vtop{%
+%    \vbox{\hrule\kern-0.4pt
+%     \hbox{\raise0.4pt\hbox{\vphantom{\angleleft}}#1}}%
+%    \kern-0.4pt\hrule}%
+%  \kern-.06em\raise0.4pt\hbox{\angleright}}}}
+
+% definition of @key with no lozenge.  If the current font is already
+% monospace, don't change it; that way, we respect @kbdinputstyle.  But
+% if it isn't monospace, then use \tt.
+%
+\def\key#1{{\setupmarkupstyle{key}%
+  \nohyphenation
+  \ifmonospace\else\tt\fi
+  #1}\null}
+
+% ctrl is no longer a Texinfo command.
+\def\ctrl #1{{\tt \rawbackslash \hat}#1}
+
+% @file, @option are the same as @samp.
+\let\file=\samp
+\let\option=\samp
+
+% @code is a modification of @t,
+% which makes spaces the same size as normal in the surrounding text.
+\def\tclose#1{%
+  {%
+    % Change normal interword space to be same as for the current font.
+    \spaceskip = \fontdimen2\font
+    %
+    % Switch to typewriter.
+    \tt
+    %
+    % But `\ ' produces the large typewriter interword space.
+    \def\ {{\spaceskip = 0pt{} }}%
+    %
+    % Turn off hyphenation.
+    \nohyphenation
+    %
+    \rawbackslash
+    \plainfrenchspacing
+    #1%
+  }%
+  \null
+}
+
+% We *must* turn on hyphenation at `-' and `_' in @code.
+% Otherwise, it is too hard to avoid overfull hboxes
+% in the Emacs manual, the Library manual, etc.
+
+% Unfortunately, TeX uses one parameter (\hyphenchar) to control
+% both hyphenation at - and hyphenation within words.
+% We must therefore turn them both off (\tclose does that)
+% and arrange explicitly to hyphenate at a dash.
+%  -- rms.
+{
+  \catcode`\-=\active \catcode`\_=\active
+  \catcode`\'=\active \catcode`\`=\active
+  \global\let'=\rq \global\let`=\lq  % default definitions
+  %
+  \global\def\code{\begingroup
+    \setupmarkupstyle{code}%
+    % The following should really be moved into \setupmarkupstyle handlers.
+    \catcode\dashChar=\active  \catcode\underChar=\active
+    \ifallowcodebreaks
+     \let-\codedash
+     \let_\codeunder
+    \else
+     \let-\realdash
+     \let_\realunder
+    \fi
+    \codex
+  }
+}
+
+\def\realdash{-}
+\def\codedash{-\discretionary{}{}{}}
+\def\codeunder{%
+  % this is all so @math{@code{var_name}+1} can work.  In math mode, _
+  % is "active" (mathcode"8000) and \normalunderscore (or \char95, etc.)
+  % will therefore expand the active definition of _, which is us
+  % (inside @code that is), therefore an endless loop.
+  \ifusingtt{\ifmmode
+               \mathchar"075F % class 0=ordinary, family 7=ttfam, pos 0x5F=_.
+             \else\normalunderscore \fi
+             \discretionary{}{}{}}%
+            {\_}%
+}
+\def\codex #1{\tclose{#1}\endgroup}
+
+% An additional complication: the above will allow breaks after, e.g.,
+% each of the four underscores in __typeof__.  This is undesirable in
+% some manuals, especially if they don't have long identifiers in
+% general.  @allowcodebreaks provides a way to control this.
+%
+\newif\ifallowcodebreaks  \allowcodebreakstrue
+
+\def\keywordtrue{true}
+\def\keywordfalse{false}
+
+\parseargdef\allowcodebreaks{%
+  \def\txiarg{#1}%
+  \ifx\txiarg\keywordtrue
+    \allowcodebreakstrue
+  \else\ifx\txiarg\keywordfalse
+    \allowcodebreaksfalse
+  \else
+    \errhelp = \EMsimple
+    \errmessage{Unknown @allowcodebreaks option `\txiarg'}%
+  \fi\fi
+}
+
+% @kbd is like @code, except that if the argument is just one @key command,
+% then @kbd has no effect.
+\def\kbd#1{{\setupmarkupstyle{kbd}\def\look{#1}\expandafter\kbdfoo\look??\par}}
+
+% @kbdinputstyle -- arg is `distinct' (@kbd uses slanted tty font always),
+%   `example' (@kbd uses ttsl only inside of @example and friends),
+%   or `code' (@kbd uses normal tty font always).
+\parseargdef\kbdinputstyle{%
+  \def\txiarg{#1}%
+  \ifx\txiarg\worddistinct
+    \gdef\kbdexamplefont{\ttsl}\gdef\kbdfont{\ttsl}%
+  \else\ifx\txiarg\wordexample
+    \gdef\kbdexamplefont{\ttsl}\gdef\kbdfont{\tt}%
+  \else\ifx\txiarg\wordcode
+    \gdef\kbdexamplefont{\tt}\gdef\kbdfont{\tt}%
+  \else
+    \errhelp = \EMsimple
+    \errmessage{Unknown @kbdinputstyle option `\txiarg'}%
+  \fi\fi\fi
+}
+\def\worddistinct{distinct}
+\def\wordexample{example}
+\def\wordcode{code}
+
+% Default is `distinct'.
+\kbdinputstyle distinct
+
+\def\xkey{\key}
+\def\kbdfoo#1#2#3\par{\def\one{#1}\def\three{#3}\def\threex{??}%
+\ifx\one\xkey\ifx\threex\three \key{#2}%
+\else{\tclose{\kbdfont\setupmarkupstyle{kbd}\look}}\fi
+\else{\tclose{\kbdfont\setupmarkupstyle{kbd}\look}}\fi}
+
+% For @indicateurl, @env, @command quotes seem unnecessary, so use \code.
+\let\indicateurl=\code
+\let\env=\code
+\let\command=\code
+
+% @clicksequence{File @click{} Open ...}
+\def\clicksequence#1{\begingroup #1\endgroup}
+
+% @clickstyle @arrow   (by default)
+\parseargdef\clickstyle{\def\click{#1}}
+\def\click{\arrow}
+
+% @uref (abbreviation for `urlref') takes an optional (comma-separated)
+% second argument specifying the text to display and an optional third
+% arg as text to display instead of (rather than in addition to) the url
+% itself.  First (mandatory) arg is the url.  Perhaps eventually put in
+% a hypertex \special here.
+%
+\def\uref#1{\douref #1,,,\finish}
+\def\douref#1,#2,#3,#4\finish{\begingroup
+  \unsepspaces
+  \pdfurl{#1}%
+  \setbox0 = \hbox{\ignorespaces #3}%
+  \ifdim\wd0 > 0pt
+    \unhbox0 % third arg given, show only that
+  \else
+    \setbox0 = \hbox{\ignorespaces #2}%
+    \ifdim\wd0 > 0pt
+      \ifpdf
+        \unhbox0             % PDF: 2nd arg given, show only it
+      \else
+        \unhbox0\ (\code{#1})% DVI: 2nd arg given, show both it and url
+      \fi
+    \else
+      \code{#1}% only url given, so show it
+    \fi
+  \fi
+  \endlink
+\endgroup}
+
+% @url synonym for @uref, since that's how everyone uses it.
+%
+\let\url=\uref
+
+% rms does not like angle brackets --karl, 17may97.
+% So now @email is just like @uref, unless we are pdf.
+%
+%\def\email#1{\angleleft{\tt #1}\angleright}
+\ifpdf
+  \def\email#1{\doemail#1,,\finish}
+  \def\doemail#1,#2,#3\finish{\begingroup
+    \unsepspaces
+    \pdfurl{mailto:#1}%
+    \setbox0 = \hbox{\ignorespaces #2}%
+    \ifdim\wd0>0pt\unhbox0\else\code{#1}\fi
+    \endlink
+  \endgroup}
+\else
+  \let\email=\uref
+\fi
+
+% Typeset a dimension, e.g., `in' or `pt'.  The only reason for the
+% argument is to make the input look right: @dmn{pt} instead of @dmn{}pt.
+%
+\def\dmn#1{\thinspace #1}
+
+% @l was never documented to mean ``switch to the Lisp font'',
+% and it is not used as such in any manual I can find.  We need it for
+% Polish suppressed-l.  --karl, 22sep96.
+%\def\l#1{{\li #1}\null}
+
+% @acronym for "FBI", "NATO", and the like.
+% We print this one point size smaller, since it's intended for
+% all-uppercase.
+%
+\def\acronym#1{\doacronym #1,,\finish}
+\def\doacronym#1,#2,#3\finish{%
+  {\selectfonts\lsize #1}%
+  \def\temp{#2}%
+  \ifx\temp\empty \else
+    \space ({\unsepspaces \ignorespaces \temp \unskip})%
+  \fi
+}
+
+% @abbr for "Comput. J." and the like.
+% No font change, but don't do end-of-sentence spacing.
+%
+\def\abbr#1{\doabbr #1,,\finish}
+\def\doabbr#1,#2,#3\finish{%
+  {\plainfrenchspacing #1}%
+  \def\temp{#2}%
+  \ifx\temp\empty \else
+    \space ({\unsepspaces \ignorespaces \temp \unskip})%
+  \fi
+}
+
+
+\message{glyphs,}
+
+% @point{}, @result{}, @expansion{}, @print{}, @equiv{}.
+%
+% Since these characters are used in examples, they should be an even number of
+% \tt widths. Each \tt character is 1en, so two makes it 1em.
+%
+\def\point{$\star$}
+\def\arrow{\leavevmode\raise.05ex\hbox to 1em{\hfil$\rightarrow$\hfil}}
+\def\result{\leavevmode\raise.05ex\hbox to 1em{\hfil$\Rightarrow$\hfil}}
+\def\expansion{\leavevmode\hbox to 1em{\hfil$\mapsto$\hfil}}
+\def\print{\leavevmode\lower.1ex\hbox to 1em{\hfil$\dashv$\hfil}}
+\def\equiv{\leavevmode\hbox to 1em{\hfil$\ptexequiv$\hfil}}
+
+% The @error{} command.
+% Adapted from the TeXbook's \boxit.
+%
+\newbox\errorbox
+%
+{\tentt \global\dimen0 = 3em}% Width of the box.
+\dimen2 = .55pt % Thickness of rules
+% The text. (`r' is open on the right, `e' somewhat less so on the left.)
+\setbox0 = \hbox{\kern-.75pt \reducedsf error\kern-1.5pt}
+%
+\setbox\errorbox=\hbox to \dimen0{\hfil
+   \hsize = \dimen0 \advance\hsize by -5.8pt % Space to left+right.
+   \advance\hsize by -2\dimen2 % Rules.
+   \vbox{%
+      \hrule height\dimen2
+      \hbox{\vrule width\dimen2 \kern3pt          % Space to left of text.
+         \vtop{\kern2.4pt \box0 \kern2.4pt}% Space above/below.
+         \kern3pt\vrule width\dimen2}% Space to right.
+      \hrule height\dimen2}
+    \hfil}
+%
+\def\error{\leavevmode\lower.7ex\copy\errorbox}
+
+% @pounds{} is a sterling sign, which Knuth put in the CM italic font.
+%
+\def\pounds{{\it\$}}
+
+% @euro{} comes from a separate font, depending on the current style.
+% We use the free feym* fonts from the eurosym package by Henrik
+% Theiling, which support regular, slanted, bold and bold slanted (and
+% "outlined" (blackboard board, sort of) versions, which we don't need).
+% It is available from http://www.ctan.org/tex-archive/fonts/eurosym.
+%
+% Although only regular is the truly official Euro symbol, we ignore
+% that.  The Euro is designed to be slightly taller than the regular
+% font height.
+%
+% feymr - regular
+% feymo - slanted
+% feybr - bold
+% feybo - bold slanted
+%
+% There is no good (free) typewriter version, to my knowledge.
+% A feymr10 euro is ~7.3pt wide, while a normal cmtt10 char is ~5.25pt wide.
+% Hmm.
+%
+% Also doesn't work in math.  Do we need to do math with euro symbols?
+% Hope not.
+%
+%
+\def\euro{{\eurofont e}}
+\def\eurofont{%
+  % We set the font at each command, rather than predefining it in
+  % \textfonts and the other font-switching commands, so that
+  % installations which never need the symbol don't have to have the
+  % font installed.
+  %
+  % There is only one designed size (nominal 10pt), so we always scale
+  % that to the current nominal size.
+  %
+  % By the way, simply using "at 1em" works for cmr10 and the like, but
+  % does not work for cmbx10 and other extended/shrunken fonts.
+  %
+  \def\eurosize{\csname\curfontsize nominalsize\endcsname}%
+  %
+  \ifx\curfontstyle\bfstylename
+    % bold:
+    \font\thiseurofont = \ifusingit{feybo10}{feybr10} at \eurosize
+  \else
+    % regular:
+    \font\thiseurofont = \ifusingit{feymo10}{feymr10} at \eurosize
+  \fi
+  \thiseurofont
+}
+
+% Glyphs from the EC fonts.  We don't use \let for the aliases, because
+% sometimes we redefine the original macro, and the alias should reflect
+% the redefinition.
+%
+% Use LaTeX names for the Icelandic letters.
+\def\DH{{\ecfont \char"D0}} % Eth
+\def\dh{{\ecfont \char"F0}} % eth
+\def\TH{{\ecfont \char"DE}} % Thorn
+\def\th{{\ecfont \char"FE}} % thorn
+%
+\def\guillemetleft{{\ecfont \char"13}}
+\def\guillemotleft{\guillemetleft}
+\def\guillemetright{{\ecfont \char"14}}
+\def\guillemotright{\guillemetright}
+\def\guilsinglleft{{\ecfont \char"0E}}
+\def\guilsinglright{{\ecfont \char"0F}}
+\def\quotedblbase{{\ecfont \char"12}}
+\def\quotesinglbase{{\ecfont \char"0D}}
+%
+% This positioning is not perfect (see the ogonek LaTeX package), but
+% we have the precomposed glyphs for the most common cases.  We put the
+% tests to use those glyphs in the single \ogonek macro so we have fewer
+% dummy definitions to worry about for index entries, etc.
+%
+% ogonek is also used with other letters in Lithuanian (IOU), but using
+% the precomposed glyphs for those is not so easy since they aren't in
+% the same EC font.
+\def\ogonek#1{{%
+  \def\temp{#1}%
+  \ifx\temp\macrocharA\Aogonek
+  \else\ifx\temp\macrochara\aogonek
+  \else\ifx\temp\macrocharE\Eogonek
+  \else\ifx\temp\macrochare\eogonek
+  \else
+    \ecfont \setbox0=\hbox{#1}%
+    \ifdim\ht0=1ex\accent"0C #1%
+    \else\ooalign{\unhbox0\crcr\hidewidth\char"0C \hidewidth}%
+    \fi
+  \fi\fi\fi\fi
+  }%
+}
+\def\Aogonek{{\ecfont \char"81}}\def\macrocharA{A}
+\def\aogonek{{\ecfont \char"A1}}\def\macrochara{a}
+\def\Eogonek{{\ecfont \char"86}}\def\macrocharE{E}
+\def\eogonek{{\ecfont \char"A6}}\def\macrochare{e}
+%
+% Use the ec* fonts (cm-super in outline format) for non-CM glyphs.
+\def\ecfont{%
+  % We can't distinguish serif/sans and italic/slanted, but this
+  % is used for crude hacks anyway (like adding French and German
+  % quotes to documents typeset with CM, where we lose kerning), so
+  % hopefully nobody will notice/care.
+  \edef\ecsize{\csname\curfontsize ecsize\endcsname}%
+  \edef\nominalsize{\csname\curfontsize nominalsize\endcsname}%
+  \ifx\curfontstyle\bfstylename
+    % bold:
+    \font\thisecfont = ecb\ifusingit{i}{x}\ecsize \space at \nominalsize
+  \else
+    % regular:
+    \font\thisecfont = ec\ifusingit{ti}{rm}\ecsize \space at \nominalsize
+  \fi
+  \thisecfont
+}
+
+% @registeredsymbol - R in a circle.  The font for the R should really
+% be smaller yet, but lllsize is the best we can do for now.
+% Adapted from the plain.tex definition of \copyright.
+%
+\def\registeredsymbol{%
+  $^{{\ooalign{\hfil\raise.07ex\hbox{\selectfonts\lllsize R}%
+               \hfil\crcr\Orb}}%
+    }$%
+}
+
+% @textdegree - the normal degrees sign.
+%
+\def\textdegree{$^\circ$}
+
+% Laurent Siebenmann reports \Orb undefined with:
+%  Textures 1.7.7 (preloaded format=plain 93.10.14)  (68K)  16 APR 2004 02:38
+% so we'll define it if necessary.
+%
+\ifx\Orb\undefined
+\def\Orb{\mathhexbox20D}
+\fi
+
+% Quotes.
+\chardef\quotedblleft="5C
+\chardef\quotedblright=`\"
+\chardef\quoteleft=`\`
+\chardef\quoteright=`\'
+
+
+\message{page headings,}
+
+\newskip\titlepagetopglue \titlepagetopglue = 1.5in
+\newskip\titlepagebottomglue \titlepagebottomglue = 2pc
+
+% First the title page.  Must do @settitle before @titlepage.
+\newif\ifseenauthor
+\newif\iffinishedtitlepage
+
+% Do an implicit @contents or @shortcontents after @end titlepage if the
+% user says @setcontentsaftertitlepage or @setshortcontentsaftertitlepage.
+%
+\newif\ifsetcontentsaftertitlepage
+ \let\setcontentsaftertitlepage = \setcontentsaftertitlepagetrue
+\newif\ifsetshortcontentsaftertitlepage
+ \let\setshortcontentsaftertitlepage = \setshortcontentsaftertitlepagetrue
+
+\parseargdef\shorttitlepage{\begingroup\hbox{}\vskip 1.5in \chaprm \centerline{#1}%
+        \endgroup\page\hbox{}\page}
+
+\envdef\titlepage{%
+  % Open one extra group, as we want to close it in the middle of \Etitlepage.
+  \begingroup
+    \parindent=0pt \textfonts
+    % Leave some space at the very top of the page.
+    \vglue\titlepagetopglue
+    % No rule at page bottom unless we print one at the top with @title.
+    \finishedtitlepagetrue
+    %
+    % Most title ``pages'' are actually two pages long, with space
+    % at the top of the second.  We don't want the ragged left on the second.
+    \let\oldpage = \page
+    \def\page{%
+      \iffinishedtitlepage\else
+	 \finishtitlepage
+      \fi
+      \let\page = \oldpage
+      \page
+      \null
+    }%
+}
+
+\def\Etitlepage{%
+    \iffinishedtitlepage\else
+	\finishtitlepage
+    \fi
+    % It is important to do the page break before ending the group,
+    % because the headline and footline are only empty inside the group.
+    % If we use the new definition of \page, we always get a blank page
+    % after the title page, which we certainly don't want.
+    \oldpage
+  \endgroup
+  %
+  % Need this before the \...aftertitlepage checks so that if they are
+  % in effect the toc pages will come out with page numbers.
+  \HEADINGSon
+  %
+  % If they want short, they certainly want long too.
+  \ifsetshortcontentsaftertitlepage
+    \shortcontents
+    \contents
+    \global\let\shortcontents = \relax
+    \global\let\contents = \relax
+  \fi
+  %
+  \ifsetcontentsaftertitlepage
+    \contents
+    \global\let\contents = \relax
+    \global\let\shortcontents = \relax
+  \fi
+}
+
+\def\finishtitlepage{%
+  \vskip4pt \hrule height 2pt width \hsize
+  \vskip\titlepagebottomglue
+  \finishedtitlepagetrue
+}
+
+%%% Macros to be used within @titlepage:
+
+\let\subtitlerm=\tenrm
+\def\subtitlefont{\subtitlerm \normalbaselineskip = 13pt \normalbaselines}
+
+\parseargdef\title{%
+  \checkenv\titlepage
+  \leftline{\titlefonts\rmisbold #1}
+  % print a rule at the page bottom also.
+  \finishedtitlepagefalse
+  \vskip4pt \hrule height 4pt width \hsize \vskip4pt
+}
+
+\parseargdef\subtitle{%
+  \checkenv\titlepage
+  {\subtitlefont \rightline{#1}}%
+}
+
+% @author should come last, but may come many times.
+% It can also be used inside @quotation.
+%
+\parseargdef\author{%
+  \def\temp{\quotation}%
+  \ifx\thisenv\temp
+    \def\quotationauthor{#1}% printed in \Equotation.
+  \else
+    \checkenv\titlepage
+    \ifseenauthor\else \vskip 0pt plus 1filll \seenauthortrue \fi
+    {\secfonts\rmisbold \leftline{#1}}%
+  \fi
+}
+
+
+%%% Set up page headings and footings.
+
+\let\thispage=\folio
+
+\newtoks\evenheadline    % headline on even pages
+\newtoks\oddheadline     % headline on odd pages
+\newtoks\evenfootline    % footline on even pages
+\newtoks\oddfootline     % footline on odd pages
+
+% Now make TeX use those variables
+\headline={{\textfonts\rm \ifodd\pageno \the\oddheadline
+                            \else \the\evenheadline \fi}}
+\footline={{\textfonts\rm \ifodd\pageno \the\oddfootline
+                            \else \the\evenfootline \fi}\HEADINGShook}
+\let\HEADINGShook=\relax
+
+% Commands to set those variables.
+% For example, this is what  @headings on  does
+% @evenheading @thistitle|@thispage|@thischapter
+% @oddheading @thischapter|@thispage|@thistitle
+% @evenfooting @thisfile||
+% @oddfooting ||@thisfile
+
+
+\def\evenheading{\parsearg\evenheadingxxx}
+\def\evenheadingxxx #1{\evenheadingyyy #1\|\|\|\|\finish}
+\def\evenheadingyyy #1\|#2\|#3\|#4\finish{%
+\global\evenheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}}}
+
+\def\oddheading{\parsearg\oddheadingxxx}
+\def\oddheadingxxx #1{\oddheadingyyy #1\|\|\|\|\finish}
+\def\oddheadingyyy #1\|#2\|#3\|#4\finish{%
+\global\oddheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}}}
+
+\parseargdef\everyheading{\oddheadingxxx{#1}\evenheadingxxx{#1}}%
+
+\def\evenfooting{\parsearg\evenfootingxxx}
+\def\evenfootingxxx #1{\evenfootingyyy #1\|\|\|\|\finish}
+\def\evenfootingyyy #1\|#2\|#3\|#4\finish{%
+\global\evenfootline={\rlap{\centerline{#2}}\line{#1\hfil#3}}}
+
+\def\oddfooting{\parsearg\oddfootingxxx}
+\def\oddfootingxxx #1{\oddfootingyyy #1\|\|\|\|\finish}
+\def\oddfootingyyy #1\|#2\|#3\|#4\finish{%
+  \global\oddfootline = {\rlap{\centerline{#2}}\line{#1\hfil#3}}%
+  %
+  % Leave some space for the footline.  Hopefully ok to assume
+  % @evenfooting will not be used by itself.
+  \global\advance\pageheight by -12pt
+  \global\advance\vsize by -12pt
+}
+
+\parseargdef\everyfooting{\oddfootingxxx{#1}\evenfootingxxx{#1}}
+
+% @evenheadingmarks top     \thischapter <- chapter at the top of a page
+% @evenheadingmarks bottom  \thischapter <- chapter at the bottom of a page
+%
+% The same set of arguments for:
+%
+% @oddheadingmarks
+% @evenfootingmarks
+% @oddfootingmarks
+% @everyheadingmarks
+% @everyfootingmarks
+
+\def\evenheadingmarks{\headingmarks{even}{heading}}
+\def\oddheadingmarks{\headingmarks{odd}{heading}}
+\def\evenfootingmarks{\headingmarks{even}{footing}}
+\def\oddfootingmarks{\headingmarks{odd}{footing}}
+\def\everyheadingmarks#1 {\headingmarks{even}{heading}{#1}
+                          \headingmarks{odd}{heading}{#1} }
+\def\everyfootingmarks#1 {\headingmarks{even}{footing}{#1}
+                          \headingmarks{odd}{footing}{#1} }
+% #1 = even/odd, #2 = heading/footing, #3 = top/bottom.
+\def\headingmarks#1#2#3 {%
+  \expandafter\let\expandafter\temp \csname get#3headingmarks\endcsname
+  \global\expandafter\let\csname get#1#2marks\endcsname \temp
+}
+
+\everyheadingmarks bottom
+\everyfootingmarks bottom
+
+% @headings double      turns headings on for double-sided printing.
+% @headings single      turns headings on for single-sided printing.
+% @headings off         turns them off.
+% @headings on          same as @headings double, retained for compatibility.
+% @headings after       turns on double-sided headings after this page.
+% @headings doubleafter turns on double-sided headings after this page.
+% @headings singleafter turns on single-sided headings after this page.
+% By default, they are off at the start of a document,
+% and turned `on' after @end titlepage.
+
+\def\headings #1 {\csname HEADINGS#1\endcsname}
+
+\def\HEADINGSoff{%
+\global\evenheadline={\hfil} \global\evenfootline={\hfil}
+\global\oddheadline={\hfil} \global\oddfootline={\hfil}}
+\HEADINGSoff
+% When we turn headings on, set the page number to 1.
+% For double-sided printing, put current file name in lower left corner,
+% chapter name on inside top of right hand pages, document
+% title on inside top of left hand pages, and page numbers on outside top
+% edge of all pages.
+\def\HEADINGSdouble{%
+\global\pageno=1
+\global\evenfootline={\hfil}
+\global\oddfootline={\hfil}
+\global\evenheadline={\line{\folio\hfil\thistitle}}
+\global\oddheadline={\line{\thischapter\hfil\folio}}
+\global\let\contentsalignmacro = \chapoddpage
+}
+\let\contentsalignmacro = \chappager
+
+% For single-sided printing, chapter title goes across top left of page,
+% page number on top right.
+\def\HEADINGSsingle{%
+\global\pageno=1
+\global\evenfootline={\hfil}
+\global\oddfootline={\hfil}
+\global\evenheadline={\line{\thischapter\hfil\folio}}
+\global\oddheadline={\line{\thischapter\hfil\folio}}
+\global\let\contentsalignmacro = \chappager
+}
+\def\HEADINGSon{\HEADINGSdouble}
+
+\def\HEADINGSafter{\let\HEADINGShook=\HEADINGSdoublex}
+\let\HEADINGSdoubleafter=\HEADINGSafter
+\def\HEADINGSdoublex{%
+\global\evenfootline={\hfil}
+\global\oddfootline={\hfil}
+\global\evenheadline={\line{\folio\hfil\thistitle}}
+\global\oddheadline={\line{\thischapter\hfil\folio}}
+\global\let\contentsalignmacro = \chapoddpage
+}
+
+\def\HEADINGSsingleafter{\let\HEADINGShook=\HEADINGSsinglex}
+\def\HEADINGSsinglex{%
+\global\evenfootline={\hfil}
+\global\oddfootline={\hfil}
+\global\evenheadline={\line{\thischapter\hfil\folio}}
+\global\oddheadline={\line{\thischapter\hfil\folio}}
+\global\let\contentsalignmacro = \chappager
+}
+
+% Subroutines used in generating headings
+% This produces Day Month Year style of output.
+% Only define if not already defined, in case a txi-??.tex file has set
+% up a different format (e.g., txi-cs.tex does this).
+\ifx\today\undefined
+\def\today{%
+  \number\day\space
+  \ifcase\month
+  \or\putwordMJan\or\putwordMFeb\or\putwordMMar\or\putwordMApr
+  \or\putwordMMay\or\putwordMJun\or\putwordMJul\or\putwordMAug
+  \or\putwordMSep\or\putwordMOct\or\putwordMNov\or\putwordMDec
+  \fi
+  \space\number\year}
+\fi
+
+% @settitle line...  specifies the title of the document, for headings.
+% It generates no output of its own.
+\def\thistitle{\putwordNoTitle}
+\def\settitle{\parsearg{\gdef\thistitle}}
+
+
+\message{tables,}
+% Tables -- @table, @ftable, @vtable, @item(x).
+
+% default indentation of table text
+\newdimen\tableindent \tableindent=.8in
+% default indentation of @itemize and @enumerate text
+\newdimen\itemindent  \itemindent=.3in
+% margin between end of table item and start of table text.
+\newdimen\itemmargin  \itemmargin=.1in
+
+% used internally for \itemindent minus \itemmargin
+\newdimen\itemmax
+
+% Note @table, @ftable, and @vtable define @item, @itemx, etc., with
+% these defs.
+% They also define \itemindex
+% to index the item name in whatever manner is desired (perhaps none).
+
+\newif\ifitemxneedsnegativevskip
+
+\def\itemxpar{\par\ifitemxneedsnegativevskip\nobreak\vskip-\parskip\nobreak\fi}
+
+\def\internalBitem{\smallbreak \parsearg\itemzzz}
+\def\internalBitemx{\itemxpar \parsearg\itemzzz}
+
+\def\itemzzz #1{\begingroup %
+  \advance\hsize by -\rightskip
+  \advance\hsize by -\tableindent
+  \setbox0=\hbox{\itemindicate{#1}}%
+  \itemindex{#1}%
+  \nobreak % This prevents a break before @itemx.
+  %
+  % If the item text does not fit in the space we have, put it on a line
+  % by itself, and do not allow a page break either before or after that
+  % line.  We do not start a paragraph here because then if the next
+  % command is, e.g., @kindex, the whatsit would get put into the
+  % horizontal list on a line by itself, resulting in extra blank space.
+  \ifdim \wd0>\itemmax
+    %
+    % Make this a paragraph so we get the \parskip glue and wrapping,
+    % but leave it ragged-right.
+    \begingroup
+      \advance\leftskip by-\tableindent
+      \advance\hsize by\tableindent
+      \advance\rightskip by0pt plus1fil
+      \leavevmode\unhbox0\par
+    \endgroup
+    %
+    % We're going to be starting a paragraph, but we don't want the
+    % \parskip glue -- logically it's part of the @item we just started.
+    \nobreak \vskip-\parskip
+    %
+    % Stop a page break at the \parskip glue coming up.  However, if
+    % what follows is an environment such as @example, there will be no
+    % \parskip glue; then the negative vskip we just inserted would
+    % cause the example and the item to crash together.  So we use this
+    % bizarre value of 10001 as a signal to \aboveenvbreak to insert
+    % \parskip glue after all.  Section titles are handled this way also.
+    %
+    \penalty 10001
+    \endgroup
+    \itemxneedsnegativevskipfalse
+  \else
+    % The item text fits into the space.  Start a paragraph, so that the
+    % following text (if any) will end up on the same line.
+    \noindent
+    % Do this with kerns and \unhbox so that if there is a footnote in
+    % the item text, it can migrate to the main vertical list and
+    % eventually be printed.
+    \nobreak\kern-\tableindent
+    \dimen0 = \itemmax  \advance\dimen0 by \itemmargin \advance\dimen0 by -\wd0
+    \unhbox0
+    \nobreak\kern\dimen0
+    \endgroup
+    \itemxneedsnegativevskiptrue
+  \fi
+}
+
+\def\item{\errmessage{@item while not in a list environment}}
+\def\itemx{\errmessage{@itemx while not in a list environment}}
+
+% @table, @ftable, @vtable.
+\envdef\table{%
+  \let\itemindex\gobble
+  \tablecheck{table}%
+}
+\envdef\ftable{%
+  \def\itemindex ##1{\doind {fn}{\code{##1}}}%
+  \tablecheck{ftable}%
+}
+\envdef\vtable{%
+  \def\itemindex ##1{\doind {vr}{\code{##1}}}%
+  \tablecheck{vtable}%
+}
+\def\tablecheck#1{%
+  \ifnum \the\catcode`\^^M=\active
+    \endgroup
+    \errmessage{This command won't work in this context; perhaps the problem is
+      that we are \inenvironment\thisenv}%
+    \def\next{\doignore{#1}}%
+  \else
+    \let\next\tablex
+  \fi
+  \next
+}
+\def\tablex#1{%
+  \def\itemindicate{#1}%
+  \parsearg\tabley
+}
+\def\tabley#1{%
+  {%
+    \makevalueexpandable
+    \edef\temp{\noexpand\tablez #1\space\space\space}%
+    \expandafter
+  }\temp \endtablez
+}
+\def\tablez #1 #2 #3 #4\endtablez{%
+  \aboveenvbreak
+  \ifnum 0#1>0 \advance \leftskip by #1\mil \fi
+  \ifnum 0#2>0 \tableindent=#2\mil \fi
+  \ifnum 0#3>0 \advance \rightskip by #3\mil \fi
+  \itemmax=\tableindent
+  \advance \itemmax by -\itemmargin
+  \advance \leftskip by \tableindent
+  \exdentamount=\tableindent
+  \parindent = 0pt
+  \parskip = \smallskipamount
+  \ifdim \parskip=0pt \parskip=2pt \fi
+  \let\item = \internalBitem
+  \let\itemx = \internalBitemx
+}
+\def\Etable{\endgraf\afterenvbreak}
+\let\Eftable\Etable
+\let\Evtable\Etable
+\let\Eitemize\Etable
+\let\Eenumerate\Etable
+
+% This is the counter used by @enumerate, which is really @itemize
+
+\newcount \itemno
+
+\envdef\itemize{\parsearg\doitemize}
+
+\def\doitemize#1{%
+  \aboveenvbreak
+  \itemmax=\itemindent
+  \advance\itemmax by -\itemmargin
+  \advance\leftskip by \itemindent
+  \exdentamount=\itemindent
+  \parindent=0pt
+  \parskip=\smallskipamount
+  \ifdim\parskip=0pt \parskip=2pt \fi
+  %
+  % Try typesetting the item mark that if the document erroneously says
+  % something like @itemize @samp (intending @table), there's an error
+  % right away at the @itemize.  It's not the best error message in the
+  % world, but it's better than leaving it to the @item.  This means if
+  % the user wants an empty mark, they have to say @w{} not just @w.
+  \def\itemcontents{#1}%
+  \setbox0 = \hbox{\itemcontents}%
+  %
+  % @itemize with no arg is equivalent to @itemize @bullet.
+  \ifx\itemcontents\empty\def\itemcontents{\bullet}\fi
+  %
+  \let\item=\itemizeitem
+}
+
+% Definition of @item while inside @itemize and @enumerate.
+%
+\def\itemizeitem{%
+  \advance\itemno by 1  % for enumerations
+  {\let\par=\endgraf \smallbreak}% reasonable place to break
+  {%
+   % If the document has an @itemize directly after a section title, a
+   % \nobreak will be last on the list, and \sectionheading will have
+   % done a \vskip-\parskip.  In that case, we don't want to zero
+   % parskip, or the item text will crash with the heading.  On the
+   % other hand, when there is normal text preceding the item (as there
+   % usually is), we do want to zero parskip, or there would be too much
+   % space.  In that case, we won't have a \nobreak before.  At least
+   % that's the theory.
+   \ifnum\lastpenalty<10000 \parskip=0in \fi
+   \noindent
+   \hbox to 0pt{\hss \itemcontents \kern\itemmargin}%
+   %
+   \vadjust{\penalty 1200}}% not good to break after first line of item.
+  \flushcr
+}
+
+% \splitoff TOKENS\endmark defines \first to be the first token in
+% TOKENS, and \rest to be the remainder.
+%
+\def\splitoff#1#2\endmark{\def\first{#1}\def\rest{#2}}%
+
+% Allow an optional argument of an uppercase letter, lowercase letter,
+% or number, to specify the first label in the enumerated list.  No
+% argument is the same as `1'.
+%
+\envparseargdef\enumerate{\enumeratey #1  \endenumeratey}
+\def\enumeratey #1 #2\endenumeratey{%
+  % If we were given no argument, pretend we were given `1'.
+  \def\thearg{#1}%
+  \ifx\thearg\empty \def\thearg{1}\fi
+  %
+  % Detect if the argument is a single token.  If so, it might be a
+  % letter.  Otherwise, the only valid thing it can be is a number.
+  % (We will always have one token, because of the test we just made.
+  % This is a good thing, since \splitoff doesn't work given nothing at
+  % all -- the first parameter is undelimited.)
+  \expandafter\splitoff\thearg\endmark
+  \ifx\rest\empty
+    % Only one token in the argument.  It could still be anything.
+    % A ``lowercase letter'' is one whose \lccode is nonzero.
+    % An ``uppercase letter'' is one whose \lccode is both nonzero, and
+    %   not equal to itself.
+    % Otherwise, we assume it's a number.
+    %
+    % We need the \relax at the end of the \ifnum lines to stop TeX from
+    % continuing to look for a <number>.
+    %
+    \ifnum\lccode\expandafter`\thearg=0\relax
+      \numericenumerate % a number (we hope)
+    \else
+      % It's a letter.
+      \ifnum\lccode\expandafter`\thearg=\expandafter`\thearg\relax
+        \lowercaseenumerate % lowercase letter
+      \else
+        \uppercaseenumerate % uppercase letter
+      \fi
+    \fi
+  \else
+    % Multiple tokens in the argument.  We hope it's a number.
+    \numericenumerate
+  \fi
+}
+
+% An @enumerate whose labels are integers.  The starting integer is
+% given in \thearg.
+%
+\def\numericenumerate{%
+  \itemno = \thearg
+  \startenumeration{\the\itemno}%
+}
+
+% The starting (lowercase) letter is in \thearg.
+\def\lowercaseenumerate{%
+  \itemno = \expandafter`\thearg
+  \startenumeration{%
+    % Be sure we're not beyond the end of the alphabet.
+    \ifnum\itemno=0
+      \errmessage{No more lowercase letters in @enumerate; get a bigger
+                  alphabet}%
+    \fi
+    \char\lccode\itemno
+  }%
+}
+
+% The starting (uppercase) letter is in \thearg.
+\def\uppercaseenumerate{%
+  \itemno = \expandafter`\thearg
+  \startenumeration{%
+    % Be sure we're not beyond the end of the alphabet.
+    \ifnum\itemno=0
+      \errmessage{No more uppercase letters in @enumerate; get a bigger
+                  alphabet}
+    \fi
+    \char\uccode\itemno
+  }%
+}
+
+% Call \doitemize, adding a period to the first argument and supplying the
+% common last two arguments.  Also subtract one from the initial value in
+% \itemno, since @item increments \itemno.
+%
+\def\startenumeration#1{%
+  \advance\itemno by -1
+  \doitemize{#1.}\flushcr
+}
+
+% @alphaenumerate and @capsenumerate are abbreviations for giving an arg
+% to @enumerate.
+%
+\def\alphaenumerate{\enumerate{a}}
+\def\capsenumerate{\enumerate{A}}
+\def\Ealphaenumerate{\Eenumerate}
+\def\Ecapsenumerate{\Eenumerate}
+
+
+% @multitable macros
+% Amy Hendrickson, 8/18/94, 3/6/96
+%
+% @multitable ... @end multitable will make as many columns as desired.
+% Contents of each column will wrap at width given in preamble.  Width
+% can be specified either with sample text given in a template line,
+% or in percent of \hsize, the current width of text on page.
+
+% Table can continue over pages but will only break between lines.
+
+% To make preamble:
+%
+% Either define widths of columns in terms of percent of \hsize:
+%   @multitable @columnfractions .25 .3 .45
+%   @item ...
+%
+%   Numbers following @columnfractions are the percent of the total
+%   current hsize to be used for each column. You may use as many
+%   columns as desired.
+
+
+% Or use a template:
+%   @multitable {Column 1 template} {Column 2 template} {Column 3 template}
+%   @item ...
+%   using the widest term desired in each column.
+
+% Each new table line starts with @item, each subsequent new column
+% starts with @tab. Empty columns may be produced by supplying @tab's
+% with nothing between them for as many times as empty columns are needed,
+% ie, @tab@tab@tab will produce two empty columns.
+
+% @item, @tab do not need to be on their own lines, but it will not hurt
+% if they are.
+
+% Sample multitable:
+
+%   @multitable {Column 1 template} {Column 2 template} {Column 3 template}
+%   @item first col stuff @tab second col stuff @tab third col
+%   @item
+%   first col stuff
+%   @tab
+%   second col stuff
+%   @tab
+%   third col
+%   @item first col stuff @tab second col stuff
+%   @tab Many paragraphs of text may be used in any column.
+%
+%         They will wrap at the width determined by the template.
+%   @item@tab@tab This will be in third column.
+%   @end multitable
+
+% Default dimensions may be reset by user.
+% @multitableparskip is vertical space between paragraphs in table.
+% @multitableparindent is paragraph indent in table.
+% @multitablecolmargin is horizontal space to be left between columns.
+% @multitablelinespace is space to leave between table items, baseline
+%                                                            to baseline.
+%   0pt means it depends on current normal line spacing.
+%
+\newskip\multitableparskip
+\newskip\multitableparindent
+\newdimen\multitablecolspace
+\newskip\multitablelinespace
+\multitableparskip=0pt
+\multitableparindent=6pt
+\multitablecolspace=12pt
+\multitablelinespace=0pt
+
+% Macros used to set up halign preamble:
+%
+\let\endsetuptable\relax
+\def\xendsetuptable{\endsetuptable}
+\let\columnfractions\relax
+\def\xcolumnfractions{\columnfractions}
+\newif\ifsetpercent
+
+% #1 is the @columnfraction, usually a decimal number like .5, but might
+% be just 1.  We just use it, whatever it is.
+%
+\def\pickupwholefraction#1 {%
+  \global\advance\colcount by 1
+  \expandafter\xdef\csname col\the\colcount\endcsname{#1\hsize}%
+  \setuptable
+}
+
+\newcount\colcount
+\def\setuptable#1{%
+  \def\firstarg{#1}%
+  \ifx\firstarg\xendsetuptable
+    \let\go = \relax
+  \else
+    \ifx\firstarg\xcolumnfractions
+      \global\setpercenttrue
+    \else
+      \ifsetpercent
+         \let\go\pickupwholefraction
+      \else
+         \global\advance\colcount by 1
+         \setbox0=\hbox{#1\unskip\space}% Add a normal word space as a
+                   % separator; typically that is always in the input, anyway.
+         \expandafter\xdef\csname col\the\colcount\endcsname{\the\wd0}%
+      \fi
+    \fi
+    \ifx\go\pickupwholefraction
+      % Put the argument back for the \pickupwholefraction call, so
+      % we'll always have a period there to be parsed.
+      \def\go{\pickupwholefraction#1}%
+    \else
+      \let\go = \setuptable
+    \fi%
+  \fi
+  \go
+}
+
+% multitable-only commands.
+%
+% @headitem starts a heading row, which we typeset in bold.
+% Assignments have to be global since we are inside the implicit group
+% of an alignment entry.  \everycr resets \everytab so we don't have to
+% undo it ourselves.
+\def\headitemfont{\b}% for people to use in the template row; not changeable
+\def\headitem{%
+  \checkenv\multitable
+  \crcr
+  \global\everytab={\bf}% can't use \headitemfont since the parsing differs
+  \the\everytab % for the first item
+}%
+%
+% A \tab used to include \hskip1sp.  But then the space in a template
+% line is not enough.  That is bad.  So let's go back to just `&' until
+% we again encounter the problem the 1sp was intended to solve.
+%					--karl, nathan@acm.org, 20apr99.
+\def\tab{\checkenv\multitable &\the\everytab}%
+
+% @multitable ... @end multitable definitions:
+%
+\newtoks\everytab  % insert after every tab.
+%
+\envdef\multitable{%
+  \vskip\parskip
+  \startsavinginserts
+  %
+  % @item within a multitable starts a normal row.
+  % We use \def instead of \let so that if one of the multitable entries
+  % contains an @itemize, we don't choke on the \item (seen as \crcr aka
+  % \endtemplate) expanding \doitemize.
+  \def\item{\crcr}%
+  %
+  \tolerance=9500
+  \hbadness=9500
+  \setmultitablespacing
+  \parskip=\multitableparskip
+  \parindent=\multitableparindent
+  \overfullrule=0pt
+  \global\colcount=0
+  %
+  \everycr = {%
+    \noalign{%
+      \global\everytab={}%
+      \global\colcount=0 % Reset the column counter.
+      % Check for saved footnotes, etc.
+      \checkinserts
+      % Keeps underfull box messages off when table breaks over pages.
+      %\filbreak
+	% Maybe so, but it also creates really weird page breaks when the
+	% table breaks over pages. Wouldn't \vfil be better?  Wait until the
+	% problem manifests itself, so it can be fixed for real --karl.
+    }%
+  }%
+  %
+  \parsearg\domultitable
+}
+\def\domultitable#1{%
+  % To parse everything between @multitable and @item:
+  \setuptable#1 \endsetuptable
+  %
+  % This preamble sets up a generic column definition, which will
+  % be used as many times as user calls for columns.
+  % \vtop will set a single line and will also let text wrap and
+  % continue for many paragraphs if desired.
+  \halign\bgroup &%
+    \global\advance\colcount by 1
+    \multistrut
+    \vtop{%
+      % Use the current \colcount to find the correct column width:
+      \hsize=\expandafter\csname col\the\colcount\endcsname
+      %
+      % In order to keep entries from bumping into each other
+      % we will add a \leftskip of \multitablecolspace to all columns after
+      % the first one.
+      %
+      % If a template has been used, we will add \multitablecolspace
+      % to the width of each template entry.
+      %
+      % If the user has set preamble in terms of percent of \hsize we will
+      % use that dimension as the width of the column, and the \leftskip
+      % will keep entries from bumping into each other.  Table will start at
+      % left margin and final column will justify at right margin.
+      %
+      % Make sure we don't inherit \rightskip from the outer environment.
+      \rightskip=0pt
+      \ifnum\colcount=1
+	% The first column will be indented with the surrounding text.
+	\advance\hsize by\leftskip
+      \else
+	\ifsetpercent \else
+	  % If user has not set preamble in terms of percent of \hsize
+	  % we will advance \hsize by \multitablecolspace.
+	  \advance\hsize by \multitablecolspace
+	\fi
+       % In either case we will make \leftskip=\multitablecolspace:
+      \leftskip=\multitablecolspace
+      \fi
+      % Ignoring space at the beginning and end avoids an occasional spurious
+      % blank line, when TeX decides to break the line at the space before the
+      % box from the multistrut, so the strut ends up on a line by itself.
+      % For example:
+      % @multitable @columnfractions .11 .89
+      % @item @code{#}
+      % @tab Legal holiday which is valid in major parts of the whole country.
+      % Is automatically provided with highlighting sequences respectively
+      % marking characters.
+      \noindent\ignorespaces##\unskip\multistrut
+    }\cr
+}
+\def\Emultitable{%
+  \crcr
+  \egroup % end the \halign
+  \global\setpercentfalse
+}
+
+\def\setmultitablespacing{%
+  \def\multistrut{\strut}% just use the standard line spacing
+  %
+  % Compute \multitablelinespace (if not defined by user) for use in
+  % \multitableparskip calculation.  We used define \multistrut based on
+  % this, but (ironically) that caused the spacing to be off.
+  % See bug-texinfo report from Werner Lemberg, 31 Oct 2004 12:52:20 +0100.
+\ifdim\multitablelinespace=0pt
+\setbox0=\vbox{X}\global\multitablelinespace=\the\baselineskip
+\global\advance\multitablelinespace by-\ht0
+\fi
+%% Test to see if parskip is larger than space between lines of
+%% table. If not, do nothing.
+%%        If so, set to same dimension as multitablelinespace.
+\ifdim\multitableparskip>\multitablelinespace
+\global\multitableparskip=\multitablelinespace
+\global\advance\multitableparskip-7pt %% to keep parskip somewhat smaller
+                                      %% than skip between lines in the table.
+\fi%
+\ifdim\multitableparskip=0pt
+\global\multitableparskip=\multitablelinespace
+\global\advance\multitableparskip-7pt %% to keep parskip somewhat smaller
+                                      %% than skip between lines in the table.
+\fi}
+
+
+\message{conditionals,}
+
+% @iftex, @ifnotdocbook, @ifnothtml, @ifnotinfo, @ifnotplaintext,
+% @ifnotxml always succeed.  They currently do nothing; we don't
+% attempt to check whether the conditionals are properly nested.  But we
+% have to remember that they are conditionals, so that @end doesn't
+% attempt to close an environment group.
+%
+\def\makecond#1{%
+  \expandafter\let\csname #1\endcsname = \relax
+  \expandafter\let\csname iscond.#1\endcsname = 1
+}
+\makecond{iftex}
+\makecond{ifnotdocbook}
+\makecond{ifnothtml}
+\makecond{ifnotinfo}
+\makecond{ifnotplaintext}
+\makecond{ifnotxml}
+
+% Ignore @ignore, @ifhtml, @ifinfo, and the like.
+%
+\def\direntry{\doignore{direntry}}
+\def\documentdescription{\doignore{documentdescription}}
+\def\docbook{\doignore{docbook}}
+\def\html{\doignore{html}}
+\def\ifdocbook{\doignore{ifdocbook}}
+\def\ifhtml{\doignore{ifhtml}}
+\def\ifinfo{\doignore{ifinfo}}
+\def\ifnottex{\doignore{ifnottex}}
+\def\ifplaintext{\doignore{ifplaintext}}
+\def\ifxml{\doignore{ifxml}}
+\def\ignore{\doignore{ignore}}
+\def\menu{\doignore{menu}}
+\def\xml{\doignore{xml}}
+
+% Ignore text until a line `@end #1', keeping track of nested conditionals.
+%
+% A count to remember the depth of nesting.
+\newcount\doignorecount
+
+\def\doignore#1{\begingroup
+  % Scan in ``verbatim'' mode:
+  \obeylines
+  \catcode`\@ = \other
+  \catcode`\{ = \other
+  \catcode`\} = \other
+  %
+  % Make sure that spaces turn into tokens that match what \doignoretext wants.
+  \spaceisspace
+  %
+  % Count number of #1's that we've seen.
+  \doignorecount = 0
+  %
+  % Swallow text until we reach the matching `@end #1'.
+  \dodoignore{#1}%
+}
+
+{ \catcode`_=11 % We want to use \_STOP_ which cannot appear in texinfo source.
+  \obeylines %
+  %
+  \gdef\dodoignore#1{%
+    % #1 contains the command name as a string, e.g., `ifinfo'.
+    %
+    % Define a command to find the next `@end #1'.
+    \long\def\doignoretext##1^^M@end #1{%
+      \doignoretextyyy##1^^M@#1\_STOP_}%
+    %
+    % And this command to find another #1 command, at the beginning of a
+    % line.  (Otherwise, we would consider a line `@c @ifset', for
+    % example, to count as an @ifset for nesting.)
+    \long\def\doignoretextyyy##1^^M@#1##2\_STOP_{\doignoreyyy{##2}\_STOP_}%
+    %
+    % And now expand that command.
+    \doignoretext ^^M%
+  }%
+}
+
+\def\doignoreyyy#1{%
+  \def\temp{#1}%
+  \ifx\temp\empty			% Nothing found.
+    \let\next\doignoretextzzz
+  \else					% Found a nested condition, ...
+    \advance\doignorecount by 1
+    \let\next\doignoretextyyy		% ..., look for another.
+    % If we're here, #1 ends with ^^M\ifinfo (for example).
+  \fi
+  \next #1% the token \_STOP_ is present just after this macro.
+}
+
+% We have to swallow the remaining "\_STOP_".
+%
+\def\doignoretextzzz#1{%
+  \ifnum\doignorecount = 0	% We have just found the outermost @end.
+    \let\next\enddoignore
+  \else				% Still inside a nested condition.
+    \advance\doignorecount by -1
+    \let\next\doignoretext      % Look for the next @end.
+  \fi
+  \next
+}
+
+% Finish off ignored text.
+{ \obeylines%
+  % Ignore anything after the last `@end #1'; this matters in verbatim
+  % environments, where otherwise the newline after an ignored conditional
+  % would result in a blank line in the output.
+  \gdef\enddoignore#1^^M{\endgroup\ignorespaces}%
+}
+
+
+% @set VAR sets the variable VAR to an empty value.
+% @set VAR REST-OF-LINE sets VAR to the value REST-OF-LINE.
+%
+% Since we want to separate VAR from REST-OF-LINE (which might be
+% empty), we can't just use \parsearg; we have to insert a space of our
+% own to delimit the rest of the line, and then take it out again if we
+% didn't need it.
+% We rely on the fact that \parsearg sets \catcode`\ =10.
+%
+\parseargdef\set{\setyyy#1 \endsetyyy}
+\def\setyyy#1 #2\endsetyyy{%
+  {%
+    \makevalueexpandable
+    \def\temp{#2}%
+    \edef\next{\gdef\makecsname{SET#1}}%
+    \ifx\temp\empty
+      \next{}%
+    \else
+      \setzzz#2\endsetzzz
+    \fi
+  }%
+}
+% Remove the trailing space \setxxx inserted.
+\def\setzzz#1 \endsetzzz{\next{#1}}
+
+% @clear VAR clears (i.e., unsets) the variable VAR.
+%
+\parseargdef\clear{%
+  {%
+    \makevalueexpandable
+    \global\expandafter\let\csname SET#1\endcsname=\relax
+  }%
+}
+
+% @value{foo} gets the text saved in variable foo.
+\def\value{\begingroup\makevalueexpandable\valuexxx}
+\def\valuexxx#1{\expandablevalue{#1}\endgroup}
+{
+  \catcode`\- = \active \catcode`\_ = \active
+  %
+  \gdef\makevalueexpandable{%
+    \let\value = \expandablevalue
+    % We don't want these characters active, ...
+    \catcode`\-=\other \catcode`\_=\other
+    % ..., but we might end up with active ones in the argument if
+    % we're called from @code, as @code{@value{foo-bar_}}, though.
+    % So \let them to their normal equivalents.
+    \let-\realdash \let_\normalunderscore
+  }
+}
+
+% We have this subroutine so that we can handle at least some @value's
+% properly in indexes (we call \makevalueexpandable in \indexdummies).
+% The command has to be fully expandable (if the variable is set), since
+% the result winds up in the index file.  This means that if the
+% variable's value contains other Texinfo commands, it's almost certain
+% it will fail (although perhaps we could fix that with sufficient work
+% to do a one-level expansion on the result, instead of complete).
+%
+\def\expandablevalue#1{%
+  \expandafter\ifx\csname SET#1\endcsname\relax
+    {[No value for ``#1'']}%
+    \message{Variable `#1', used in @value, is not set.}%
+  \else
+    \csname SET#1\endcsname
+  \fi
+}
+
+% @ifset VAR ... @end ifset reads the `...' iff VAR has been defined
+% with @set.
+%
+% To get special treatment of `@end ifset,' call \makeond and the redefine.
+%
+\makecond{ifset}
+\def\ifset{\parsearg{\doifset{\let\next=\ifsetfail}}}
+\def\doifset#1#2{%
+  {%
+    \makevalueexpandable
+    \let\next=\empty
+    \expandafter\ifx\csname SET#2\endcsname\relax
+      #1% If not set, redefine \next.
+    \fi
+    \expandafter
+  }\next
+}
+\def\ifsetfail{\doignore{ifset}}
+
+% @ifclear VAR ... @end ifclear reads the `...' iff VAR has never been
+% defined with @set, or has been undefined with @clear.
+%
+% The `\else' inside the `\doifset' parameter is a trick to reuse the
+% above code: if the variable is not set, do nothing, if it is set,
+% then redefine \next to \ifclearfail.
+%
+\makecond{ifclear}
+\def\ifclear{\parsearg{\doifset{\else \let\next=\ifclearfail}}}
+\def\ifclearfail{\doignore{ifclear}}
+
+% @dircategory CATEGORY  -- specify a category of the dir file
+% which this file should belong to.  Ignore this in TeX.
+\let\dircategory=\comment
+
+% @defininfoenclose.
+\let\definfoenclose=\comment
+
+
+\message{indexing,}
+% Index generation facilities
+
+% Define \newwrite to be identical to plain tex's \newwrite
+% except not \outer, so it can be used within macros and \if's.
+\edef\newwrite{\makecsname{ptexnewwrite}}
+
+% \newindex {foo} defines an index named foo.
+% It automatically defines \fooindex such that
+% \fooindex ...rest of line... puts an entry in the index foo.
+% It also defines \fooindfile to be the number of the output channel for
+% the file that accumulates this index.  The file's extension is foo.
+% The name of an index should be no more than 2 characters long
+% for the sake of vms.
+%
+\def\newindex#1{%
+  \iflinks
+    \expandafter\newwrite \csname#1indfile\endcsname
+    \openout \csname#1indfile\endcsname \jobname.#1 % Open the file
+  \fi
+  \expandafter\xdef\csname#1index\endcsname{%     % Define @#1index
+    \noexpand\doindex{#1}}
+}
+
+% @defindex foo  ==  \newindex{foo}
+%
+\def\defindex{\parsearg\newindex}
+
+% Define @defcodeindex, like @defindex except put all entries in @code.
+%
+\def\defcodeindex{\parsearg\newcodeindex}
+%
+\def\newcodeindex#1{%
+  \iflinks
+    \expandafter\newwrite \csname#1indfile\endcsname
+    \openout \csname#1indfile\endcsname \jobname.#1
+  \fi
+  \expandafter\xdef\csname#1index\endcsname{%
+    \noexpand\docodeindex{#1}}%
+}
+
+
+% @synindex foo bar    makes index foo feed into index bar.
+% Do this instead of @defindex foo if you don't want it as a separate index.
+%
+% @syncodeindex foo bar   similar, but put all entries made for index foo
+% inside @code.
+%
+\def\synindex#1 #2 {\dosynindex\doindex{#1}{#2}}
+\def\syncodeindex#1 #2 {\dosynindex\docodeindex{#1}{#2}}
+
+% #1 is \doindex or \docodeindex, #2 the index getting redefined (foo),
+% #3 the target index (bar).
+\def\dosynindex#1#2#3{%
+  % Only do \closeout if we haven't already done it, else we'll end up
+  % closing the target index.
+  \expandafter \ifx\csname donesynindex#2\endcsname \relax
+    % The \closeout helps reduce unnecessary open files; the limit on the
+    % Acorn RISC OS is a mere 16 files.
+    \expandafter\closeout\csname#2indfile\endcsname
+    \expandafter\let\csname donesynindex#2\endcsname = 1
+  \fi
+  % redefine \fooindfile:
+  \expandafter\let\expandafter\temp\expandafter=\csname#3indfile\endcsname
+  \expandafter\let\csname#2indfile\endcsname=\temp
+  % redefine \fooindex:
+  \expandafter\xdef\csname#2index\endcsname{\noexpand#1{#3}}%
+}
+
+% Define \doindex, the driver for all \fooindex macros.
+% Argument #1 is generated by the calling \fooindex macro,
+%  and it is "foo", the name of the index.
+
+% \doindex just uses \parsearg; it calls \doind for the actual work.
+% This is because \doind is more useful to call from other macros.
+
+% There is also \dosubind {index}{topic}{subtopic}
+% which makes an entry in a two-level index such as the operation index.
+
+\def\doindex#1{\edef\indexname{#1}\parsearg\singleindexer}
+\def\singleindexer #1{\doind{\indexname}{#1}}
+
+% like the previous two, but they put @code around the argument.
+\def\docodeindex#1{\edef\indexname{#1}\parsearg\singlecodeindexer}
+\def\singlecodeindexer #1{\doind{\indexname}{\code{#1}}}
+
+% Take care of Texinfo commands that can appear in an index entry.
+% Since there are some commands we want to expand, and others we don't,
+% we have to laboriously prevent expansion for those that we don't.
+%
+\def\indexdummies{%
+  \escapechar = `\\     % use backslash in output files.
+  \def\@{@}% change to @@ when we switch to @ as escape char in index files.
+  \def\ {\realbackslash\space }%
+  %
+  % Need these in case \tex is in effect and \{ is a \delimiter again.
+  % But can't use \lbracecmd and \rbracecmd because texindex assumes
+  % braces and backslashes are used only as delimiters.
+  \let\{ = \mylbrace
+  \let\} = \myrbrace
+  %
+  % I don't entirely understand this, but when an index entry is
+  % generated from a macro call, the \endinput which \scanmacro inserts
+  % causes processing to be prematurely terminated.  This is,
+  % apparently, because \indexsorttmp is fully expanded, and \endinput
+  % is an expandable command.  The redefinition below makes \endinput
+  % disappear altogether for that purpose -- although logging shows that
+  % processing continues to some further point.  On the other hand, it
+  % seems \endinput does not hurt in the printed index arg, since that
+  % is still getting written without apparent harm.
+  %
+  % Sample source (mac-idx3.tex, reported by Graham Percival to
+  % help-texinfo, 22may06):
+  % @macro funindex {WORD}
+  % @findex xyz
+  % @end macro
+  % ...
+  % @funindex commtest
+  %
+  % The above is not enough to reproduce the bug, but it gives the flavor.
+  %
+  % Sample whatsit resulting:
+  % .@write3{\entry{xyz}{@folio }{@code {xyz@endinput }}}
+  %
+  % So:
+  \let\endinput = \empty
+  %
+  % Do the redefinitions.
+  \commondummies
+}
+
+% For the aux and toc files, @ is the escape character.  So we want to
+% redefine everything using @ as the escape character (instead of
+% \realbackslash, still used for index files).  When everything uses @,
+% this will be simpler.
+%
+\def\atdummies{%
+  \def\@{@@}%
+  \def\ {@ }%
+  \let\{ = \lbraceatcmd
+  \let\} = \rbraceatcmd
+  %
+  % Do the redefinitions.
+  \commondummies
+  \otherbackslash
+}
+
+% Called from \indexdummies and \atdummies.
+%
+\def\commondummies{%
+  %
+  % \definedummyword defines \#1 as \string\#1\space, thus effectively
+  % preventing its expansion.  This is used only for control% words,
+  % not control letters, because the \space would be incorrect for
+  % control characters, but is needed to separate the control word
+  % from whatever follows.
+  %
+  % For control letters, we have \definedummyletter, which omits the
+  % space.
+  %
+  % These can be used both for control words that take an argument and
+  % those that do not.  If it is followed by {arg} in the input, then
+  % that will dutifully get written to the index (or wherever).
+  %
+  \def\definedummyword  ##1{\def##1{\string##1\space}}%
+  \def\definedummyletter##1{\def##1{\string##1}}%
+  \let\definedummyaccent\definedummyletter
+  %
+  \commondummiesnofonts
+  %
+  \definedummyletter\_%
+  %
+  % Non-English letters.
+  \definedummyword\AA
+  \definedummyword\AE
+  \definedummyword\DH
+  \definedummyword\L
+  \definedummyword\O
+  \definedummyword\OE
+  \definedummyword\TH
+  \definedummyword\aa
+  \definedummyword\ae
+  \definedummyword\dh
+  \definedummyword\exclamdown
+  \definedummyword\l
+  \definedummyword\o
+  \definedummyword\oe
+  \definedummyword\ordf
+  \definedummyword\ordm
+  \definedummyword\questiondown
+  \definedummyword\ss
+  \definedummyword\th
+  %
+  % Although these internal commands shouldn't show up, sometimes they do.
+  \definedummyword\bf
+  \definedummyword\gtr
+  \definedummyword\hat
+  \definedummyword\less
+  \definedummyword\sf
+  \definedummyword\sl
+  \definedummyword\tclose
+  \definedummyword\tt
+  %
+  \definedummyword\LaTeX
+  \definedummyword\TeX
+  %
+  % Assorted special characters.
+  \definedummyword\bullet
+  \definedummyword\comma
+  \definedummyword\copyright
+  \definedummyword\registeredsymbol
+  \definedummyword\dots
+  \definedummyword\enddots
+  \definedummyword\equiv
+  \definedummyword\error
+  \definedummyword\euro
+  \definedummyword\guillemetleft
+  \definedummyword\guillemetright
+  \definedummyword\guilsinglleft
+  \definedummyword\guilsinglright
+  \definedummyword\expansion
+  \definedummyword\minus
+  \definedummyword\ogonek
+  \definedummyword\pounds
+  \definedummyword\point
+  \definedummyword\print
+  \definedummyword\quotedblbase
+  \definedummyword\quotedblleft
+  \definedummyword\quotedblright
+  \definedummyword\quoteleft
+  \definedummyword\quoteright
+  \definedummyword\quotesinglbase
+  \definedummyword\result
+  \definedummyword\textdegree
+  %
+  % We want to disable all macros so that they are not expanded by \write.
+  \macrolist
+  %
+  \normalturnoffactive
+  %
+  % Handle some cases of @value -- where it does not contain any
+  % (non-fully-expandable) commands.
+  \makevalueexpandable
+}
+
+% \commondummiesnofonts: common to \commondummies and \indexnofonts.
+%
+\def\commondummiesnofonts{%
+  % Control letters and accents.
+  \definedummyletter\!%
+  \definedummyaccent\"%
+  \definedummyaccent\'%
+  \definedummyletter\*%
+  \definedummyaccent\,%
+  \definedummyletter\.%
+  \definedummyletter\/%
+  \definedummyletter\:%
+  \definedummyaccent\=%
+  \definedummyletter\?%
+  \definedummyaccent\^%
+  \definedummyaccent\`%
+  \definedummyaccent\~%
+  \definedummyword\u
+  \definedummyword\v
+  \definedummyword\H
+  \definedummyword\dotaccent
+  \definedummyword\ogonek
+  \definedummyword\ringaccent
+  \definedummyword\tieaccent
+  \definedummyword\ubaraccent
+  \definedummyword\udotaccent
+  \definedummyword\dotless
+  %
+  % Texinfo font commands.
+  \definedummyword\b
+  \definedummyword\i
+  \definedummyword\r
+  \definedummyword\sc
+  \definedummyword\t
+  %
+  % Commands that take arguments.
+  \definedummyword\acronym
+  \definedummyword\cite
+  \definedummyword\code
+  \definedummyword\command
+  \definedummyword\dfn
+  \definedummyword\email
+  \definedummyword\emph
+  \definedummyword\env
+  \definedummyword\file
+  \definedummyword\kbd
+  \definedummyword\key
+  \definedummyword\math
+  \definedummyword\option
+  \definedummyword\pxref
+  \definedummyword\ref
+  \definedummyword\samp
+  \definedummyword\strong
+  \definedummyword\tie
+  \definedummyword\uref
+  \definedummyword\url
+  \definedummyword\var
+  \definedummyword\verb
+  \definedummyword\w
+  \definedummyword\xref
+}
+
+% \indexnofonts is used when outputting the strings to sort the index
+% by, and when constructing control sequence names.  It eliminates all
+% control sequences and just writes whatever the best ASCII sort string
+% would be for a given command (usually its argument).
+%
+\def\indexnofonts{%
+  % Accent commands should become @asis.
+  \def\definedummyaccent##1{\let##1\asis}%
+  % We can just ignore other control letters.
+  \def\definedummyletter##1{\let##1\empty}%
+  % Hopefully, all control words can become @asis.
+  \let\definedummyword\definedummyaccent
+  %
+  \commondummiesnofonts
+  %
+  % Don't no-op \tt, since it isn't a user-level command
+  % and is used in the definitions of the active chars like <, >, |, etc.
+  % Likewise with the other plain tex font commands.
+  %\let\tt=\asis
+  %
+  \def\ { }%
+  \def\@{@}%
+  % how to handle braces?
+  \def\_{\normalunderscore}%
+  %
+  % Non-English letters.
+  \def\AA{AA}%
+  \def\AE{AE}%
+  \def\DH{DZZ}%
+  \def\L{L}%
+  \def\OE{OE}%
+  \def\O{O}%
+  \def\TH{ZZZ}%
+  \def\aa{aa}%
+  \def\ae{ae}%
+  \def\dh{dzz}%
+  \def\exclamdown{!}%
+  \def\l{l}%
+  \def\oe{oe}%
+  \def\ordf{a}%
+  \def\ordm{o}%
+  \def\o{o}%
+  \def\questiondown{?}%
+  \def\ss{ss}%
+  \def\th{zzz}%
+  %
+  \def\LaTeX{LaTeX}%
+  \def\TeX{TeX}%
+  %
+  % Assorted special characters.
+  % (The following {} will end up in the sort string, but that's ok.)
+  \def\bullet{bullet}%
+  \def\comma{,}%
+  \def\copyright{copyright}%
+  \def\dots{...}%
+  \def\enddots{...}%
+  \def\equiv{==}%
+  \def\error{error}%
+  \def\euro{euro}%
+  \def\expansion{==>}%
+  \def\guillemetleft{<<}%
+  \def\guillemetright{>>}%
+  \def\guilsinglleft{<}%
+  \def\guilsinglright{>}%
+  \def\minus{-}%
+  \def\point{.}%
+  \def\pounds{pounds}%
+  \def\print{-|}%
+  \def\quotedblbase{"}%
+  \def\quotedblleft{"}%
+  \def\quotedblright{"}%
+  \def\quoteleft{`}%
+  \def\quoteright{'}%
+  \def\quotesinglbase{,}%
+  \def\registeredsymbol{R}%
+  \def\result{=>}%
+  \def\textdegree{o}%
+  %
+  % We need to get rid of all macros, leaving only the arguments (if present).
+  % Of course this is not nearly correct, but it is the best we can do for now.
+  % makeinfo does not expand macros in the argument to @deffn, which ends up
+  % writing an index entry, and texindex isn't prepared for an index sort entry
+  % that starts with \.
+  %
+  % Since macro invocations are followed by braces, we can just redefine them
+  % to take a single TeX argument.  The case of a macro invocation that
+  % goes to end-of-line is not handled.
+  %
+  \macrolist
+}
+
+\let\indexbackslash=0  %overridden during \printindex.
+\let\SETmarginindex=\relax % put index entries in margin (undocumented)?
+
+% Most index entries go through here, but \dosubind is the general case.
+% #1 is the index name, #2 is the entry text.
+\def\doind#1#2{\dosubind{#1}{#2}{}}
+
+% Workhorse for all \fooindexes.
+% #1 is name of index, #2 is stuff to put there, #3 is subentry --
+% empty if called from \doind, as we usually are (the main exception
+% is with most defuns, which call us directly).
+%
+\def\dosubind#1#2#3{%
+  \iflinks
+  {%
+    % Store the main index entry text (including the third arg).
+    \toks0 = {#2}%
+    % If third arg is present, precede it with a space.
+    \def\thirdarg{#3}%
+    \ifx\thirdarg\empty \else
+      \toks0 = \expandafter{\the\toks0 \space #3}%
+    \fi
+    %
+    \edef\writeto{\csname#1indfile\endcsname}%
+    %
+    \safewhatsit\dosubindwrite
+  }%
+  \fi
+}
+
+% Write the entry in \toks0 to the index file:
+%
+\def\dosubindwrite{%
+  % Put the index entry in the margin if desired.
+  \ifx\SETmarginindex\relax\else
+    \insert\margin{\hbox{\vrule height8pt depth3pt width0pt \the\toks0}}%
+  \fi
+  %
+  % Remember, we are within a group.
+  \indexdummies % Must do this here, since \bf, etc expand at this stage
+  \def\backslashcurfont{\indexbackslash}% \indexbackslash isn't defined now
+      % so it will be output as is; and it will print as backslash.
+  %
+  % Process the index entry with all font commands turned off, to
+  % get the string to sort by.
+  {\indexnofonts
+   \edef\temp{\the\toks0}% need full expansion
+   \xdef\indexsorttmp{\temp}%
+  }%
+  %
+  % Set up the complete index entry, with both the sort key and
+  % the original text, including any font commands.  We write
+  % three arguments to \entry to the .?? file (four in the
+  % subentry case), texindex reduces to two when writing the .??s
+  % sorted result.
+  \edef\temp{%
+    \write\writeto{%
+      \string\entry{\indexsorttmp}{\noexpand\folio}{\the\toks0}}%
+  }%
+  \temp
+}
+
+% Take care of unwanted page breaks/skips around a whatsit:
+%
+% If a skip is the last thing on the list now, preserve it
+% by backing up by \lastskip, doing the \write, then inserting
+% the skip again.  Otherwise, the whatsit generated by the
+% \write or \pdfdest will make \lastskip zero.  The result is that
+% sequences like this:
+% @end defun
+% @tindex whatever
+% @defun ...
+% will have extra space inserted, because the \medbreak in the
+% start of the @defun won't see the skip inserted by the @end of
+% the previous defun.
+%
+% But don't do any of this if we're not in vertical mode.  We
+% don't want to do a \vskip and prematurely end a paragraph.
+%
+% Avoid page breaks due to these extra skips, too.
+%
+% But wait, there is a catch there:
+% We'll have to check whether \lastskip is zero skip.  \ifdim is not
+% sufficient for this purpose, as it ignores stretch and shrink parts
+% of the skip.  The only way seems to be to check the textual
+% representation of the skip.
+%
+% The following is almost like \def\zeroskipmacro{0.0pt} except that
+% the ``p'' and ``t'' characters have catcode \other, not 11 (letter).
+%
+\edef\zeroskipmacro{\expandafter\the\csname z@skip\endcsname}
+%
+\newskip\whatsitskip
+\newcount\whatsitpenalty
+%
+% ..., ready, GO:
+%
+\def\safewhatsit#1{%
+\ifhmode
+  #1%
+\else
+  % \lastskip and \lastpenalty cannot both be nonzero simultaneously.
+  \whatsitskip = \lastskip
+  \edef\lastskipmacro{\the\lastskip}%
+  \whatsitpenalty = \lastpenalty
+  %
+  % If \lastskip is nonzero, that means the last item was a
+  % skip.  And since a skip is discardable, that means this
+  % -\whatsitskip glue we're inserting is preceded by a
+  % non-discardable item, therefore it is not a potential
+  % breakpoint, therefore no \nobreak needed.
+  \ifx\lastskipmacro\zeroskipmacro
+  \else
+    \vskip-\whatsitskip
+  \fi
+  %
+  #1%
+  %
+  \ifx\lastskipmacro\zeroskipmacro
+    % If \lastskip was zero, perhaps the last item was a penalty, and
+    % perhaps it was >=10000, e.g., a \nobreak.  In that case, we want
+    % to re-insert the same penalty (values >10000 are used for various
+    % signals); since we just inserted a non-discardable item, any
+    % following glue (such as a \parskip) would be a breakpoint.  For example:
+    %
+    %   @deffn deffn-whatever
+    %   @vindex index-whatever
+    %   Description.
+    % would allow a break between the index-whatever whatsit
+    % and the "Description." paragraph.
+    \ifnum\whatsitpenalty>9999 \penalty\whatsitpenalty \fi
+  \else
+    % On the other hand, if we had a nonzero \lastskip,
+    % this make-up glue would be preceded by a non-discardable item
+    % (the whatsit from the \write), so we must insert a \nobreak.
+    \nobreak\vskip\whatsitskip
+  \fi
+\fi
+}
+
+% The index entry written in the file actually looks like
+%  \entry {sortstring}{page}{topic}
+% or
+%  \entry {sortstring}{page}{topic}{subtopic}
+% The texindex program reads in these files and writes files
+% containing these kinds of lines:
+%  \initial {c}
+%     before the first topic whose initial is c
+%  \entry {topic}{pagelist}
+%     for a topic that is used without subtopics
+%  \primary {topic}
+%     for the beginning of a topic that is used with subtopics
+%  \secondary {subtopic}{pagelist}
+%     for each subtopic.
+
+% Define the user-accessible indexing commands
+% @findex, @vindex, @kindex, @cindex.
+
+\def\findex {\fnindex}
+\def\kindex {\kyindex}
+\def\cindex {\cpindex}
+\def\vindex {\vrindex}
+\def\tindex {\tpindex}
+\def\pindex {\pgindex}
+
+\def\cindexsub {\begingroup\obeylines\cindexsub}
+{\obeylines %
+\gdef\cindexsub "#1" #2^^M{\endgroup %
+\dosubind{cp}{#2}{#1}}}
+
+% Define the macros used in formatting output of the sorted index material.
+
+% @printindex causes a particular index (the ??s file) to get printed.
+% It does not print any chapter heading (usually an @unnumbered).
+%
+\parseargdef\printindex{\begingroup
+  \dobreak \chapheadingskip{10000}%
+  %
+  \smallfonts \rm
+  \tolerance = 9500
+  \plainfrenchspacing
+  \everypar = {}% don't want the \kern\-parindent from indentation suppression.
+  %
+  % See if the index file exists and is nonempty.
+  % Change catcode of @ here so that if the index file contains
+  % \initial {@}
+  % as its first line, TeX doesn't complain about mismatched braces
+  % (because it thinks @} is a control sequence).
+  \catcode`\@ = 11
+  \openin 1 \jobname.#1s
+  \ifeof 1
+    % \enddoublecolumns gets confused if there is no text in the index,
+    % and it loses the chapter title and the aux file entries for the
+    % index.  The easiest way to prevent this problem is to make sure
+    % there is some text.
+    \putwordIndexNonexistent
+  \else
+    %
+    % If the index file exists but is empty, then \openin leaves \ifeof
+    % false.  We have to make TeX try to read something from the file, so
+    % it can discover if there is anything in it.
+    \read 1 to \temp
+    \ifeof 1
+      \putwordIndexIsEmpty
+    \else
+      % Index files are almost Texinfo source, but we use \ as the escape
+      % character.  It would be better to use @, but that's too big a change
+      % to make right now.
+      \def\indexbackslash{\backslashcurfont}%
+      \catcode`\\ = 0
+      \escapechar = `\\
+      \begindoublecolumns
+      \input \jobname.#1s
+      \enddoublecolumns
+    \fi
+  \fi
+  \closein 1
+\endgroup}
+
+% These macros are used by the sorted index file itself.
+% Change them to control the appearance of the index.
+
+\def\initial#1{{%
+  % Some minor font changes for the special characters.
+  \let\tentt=\sectt \let\tt=\sectt \let\sf=\sectt
+  %
+  % Remove any glue we may have, we'll be inserting our own.
+  \removelastskip
+  %
+  % We like breaks before the index initials, so insert a bonus.
+  \nobreak
+  \vskip 0pt plus 3\baselineskip
+  \penalty 0
+  \vskip 0pt plus -3\baselineskip
+  %
+  % Typeset the initial.  Making this add up to a whole number of
+  % baselineskips increases the chance of the dots lining up from column
+  % to column.  It still won't often be perfect, because of the stretch
+  % we need before each entry, but it's better.
+  %
+  % No shrink because it confuses \balancecolumns.
+  \vskip 1.67\baselineskip plus .5\baselineskip
+  \leftline{\secbf #1}%
+  % Do our best not to break after the initial.
+  \nobreak
+  \vskip .33\baselineskip plus .1\baselineskip
+}}
+
+% \entry typesets a paragraph consisting of the text (#1), dot leaders, and
+% then page number (#2) flushed to the right margin.  It is used for index
+% and table of contents entries.  The paragraph is indented by \leftskip.
+%
+% A straightforward implementation would start like this:
+%	\def\entry#1#2{...
+% But this freezes the catcodes in the argument, and can cause problems to
+% @code, which sets - active.  This problem was fixed by a kludge---
+% ``-'' was active throughout whole index, but this isn't really right.
+%
+% The right solution is to prevent \entry from swallowing the whole text.
+%                                 --kasal, 21nov03
+\def\entry{%
+  \begingroup
+    %
+    % Start a new paragraph if necessary, so our assignments below can't
+    % affect previous text.
+    \par
+    %
+    % Do not fill out the last line with white space.
+    \parfillskip = 0in
+    %
+    % No extra space above this paragraph.
+    \parskip = 0in
+    %
+    % Do not prefer a separate line ending with a hyphen to fewer lines.
+    \finalhyphendemerits = 0
+    %
+    % \hangindent is only relevant when the entry text and page number
+    % don't both fit on one line.  In that case, bob suggests starting the
+    % dots pretty far over on the line.  Unfortunately, a large
+    % indentation looks wrong when the entry text itself is broken across
+    % lines.  So we use a small indentation and put up with long leaders.
+    %
+    % \hangafter is reset to 1 (which is the value we want) at the start
+    % of each paragraph, so we need not do anything with that.
+    \hangindent = 2em
+    %
+    % When the entry text needs to be broken, just fill out the first line
+    % with blank space.
+    \rightskip = 0pt plus1fil
+    %
+    % A bit of stretch before each entry for the benefit of balancing
+    % columns.
+    \vskip 0pt plus1pt
+    %
+    % Swallow the left brace of the text (first parameter):
+    \afterassignment\doentry
+    \let\temp =
+}
+\def\doentry{%
+    \bgroup % Instead of the swallowed brace.
+      \noindent
+      \aftergroup\finishentry
+      % And now comes the text of the entry.
+}
+\def\finishentry#1{%
+    % #1 is the page number.
+    %
+    % The following is kludged to not output a line of dots in the index if
+    % there are no page numbers.  The next person who breaks this will be
+    % cursed by a Unix daemon.
+    \setbox\boxA = \hbox{#1}%
+    \ifdim\wd\boxA = 0pt
+      \ %
+    \else
+      %
+      % If we must, put the page number on a line of its own, and fill out
+      % this line with blank space.  (The \hfil is overwhelmed with the
+      % fill leaders glue in \indexdotfill if the page number does fit.)
+      \hfil\penalty50
+      \null\nobreak\indexdotfill % Have leaders before the page number.
+      %
+      % The `\ ' here is removed by the implicit \unskip that TeX does as
+      % part of (the primitive) \par.  Without it, a spurious underfull
+      % \hbox ensues.
+      \ifpdf
+	\pdfgettoks#1.%
+	\ \the\toksA
+      \else
+	\ #1%
+      \fi
+    \fi
+    \par
+  \endgroup
+}
+
+% Like plain.tex's \dotfill, except uses up at least 1 em.
+\def\indexdotfill{\cleaders
+  \hbox{$\mathsurround=0pt \mkern1.5mu.\mkern1.5mu$}\hskip 1em plus 1fill}
+
+\def\primary #1{\line{#1\hfil}}
+
+\newskip\secondaryindent \secondaryindent=0.5cm
+\def\secondary#1#2{{%
+  \parfillskip=0in
+  \parskip=0in
+  \hangindent=1in
+  \hangafter=1
+  \noindent\hskip\secondaryindent\hbox{#1}\indexdotfill
+  \ifpdf
+    \pdfgettoks#2.\ \the\toksA % The page number ends the paragraph.
+  \else
+    #2
+  \fi
+  \par
+}}
+
+% Define two-column mode, which we use to typeset indexes.
+% Adapted from the TeXbook, page 416, which is to say,
+% the manmac.tex format used to print the TeXbook itself.
+\catcode`\@=11
+
+\newbox\partialpage
+\newdimen\doublecolumnhsize
+
+\def\begindoublecolumns{\begingroup % ended by \enddoublecolumns
+  % Grab any single-column material above us.
+  \output = {%
+    %
+    % Here is a possibility not foreseen in manmac: if we accumulate a
+    % whole lot of material, we might end up calling this \output
+    % routine twice in a row (see the doublecol-lose test, which is
+    % essentially a couple of indexes with @setchapternewpage off).  In
+    % that case we just ship out what is in \partialpage with the normal
+    % output routine.  Generally, \partialpage will be empty when this
+    % runs and this will be a no-op.  See the indexspread.tex test case.
+    \ifvoid\partialpage \else
+      \onepageout{\pagecontents\partialpage}%
+    \fi
+    %
+    \global\setbox\partialpage = \vbox{%
+      % Unvbox the main output page.
+      \unvbox\PAGE
+      \kern-\topskip \kern\baselineskip
+    }%
+  }%
+  \eject % run that output routine to set \partialpage
+  %
+  % Use the double-column output routine for subsequent pages.
+  \output = {\doublecolumnout}%
+  %
+  % Change the page size parameters.  We could do this once outside this
+  % routine, in each of @smallbook, @afourpaper, and the default 8.5x11
+  % format, but then we repeat the same computation.  Repeating a couple
+  % of assignments once per index is clearly meaningless for the
+  % execution time, so we may as well do it in one place.
+  %
+  % First we halve the line length, less a little for the gutter between
+  % the columns.  We compute the gutter based on the line length, so it
+  % changes automatically with the paper format.  The magic constant
+  % below is chosen so that the gutter has the same value (well, +-<1pt)
+  % as it did when we hard-coded it.
+  %
+  % We put the result in a separate register, \doublecolumhsize, so we
+  % can restore it in \pagesofar, after \hsize itself has (potentially)
+  % been clobbered.
+  %
+  \doublecolumnhsize = \hsize
+    \advance\doublecolumnhsize by -.04154\hsize
+    \divide\doublecolumnhsize by 2
+  \hsize = \doublecolumnhsize
+  %
+  % Double the \vsize as well.  (We don't need a separate register here,
+  % since nobody clobbers \vsize.)
+  \vsize = 2\vsize
+}
+
+% The double-column output routine for all double-column pages except
+% the last.
+%
+\def\doublecolumnout{%
+  \splittopskip=\topskip \splitmaxdepth=\maxdepth
+  % Get the available space for the double columns -- the normal
+  % (undoubled) page height minus any material left over from the
+  % previous page.
+  \dimen@ = \vsize
+  \divide\dimen@ by 2
+  \advance\dimen@ by -\ht\partialpage
+  %
+  % box0 will be the left-hand column, box2 the right.
+  \setbox0=\vsplit255 to\dimen@ \setbox2=\vsplit255 to\dimen@
+  \onepageout\pagesofar
+  \unvbox255
+  \penalty\outputpenalty
+}
+%
+% Re-output the contents of the output page -- any previous material,
+% followed by the two boxes we just split, in box0 and box2.
+\def\pagesofar{%
+  \unvbox\partialpage
+  %
+  \hsize = \doublecolumnhsize
+  \wd0=\hsize \wd2=\hsize
+  \hbox to\pagewidth{\box0\hfil\box2}%
+}
+%
+% All done with double columns.
+\def\enddoublecolumns{%
+  % The following penalty ensures that the page builder is exercised
+  % _before_ we change the output routine.  This is necessary in the
+  % following situation:
+  %
+  % The last section of the index consists only of a single entry.
+  % Before this section, \pagetotal is less than \pagegoal, so no
+  % break occurs before the last section starts.  However, the last
+  % section, consisting of \initial and the single \entry, does not
+  % fit on the page and has to be broken off.  Without the following
+  % penalty the page builder will not be exercised until \eject
+  % below, and by that time we'll already have changed the output
+  % routine to the \balancecolumns version, so the next-to-last
+  % double-column page will be processed with \balancecolumns, which
+  % is wrong:  The two columns will go to the main vertical list, with
+  % the broken-off section in the recent contributions.  As soon as
+  % the output routine finishes, TeX starts reconsidering the page
+  % break.  The two columns and the broken-off section both fit on the
+  % page, because the two columns now take up only half of the page
+  % goal.  When TeX sees \eject from below which follows the final
+  % section, it invokes the new output routine that we've set after
+  % \balancecolumns below; \onepageout will try to fit the two columns
+  % and the final section into the vbox of \pageheight (see
+  % \pagebody), causing an overfull box.
+  %
+  % Note that glue won't work here, because glue does not exercise the
+  % page builder, unlike penalties (see The TeXbook, pp. 280-281).
+  \penalty0
+  %
+  \output = {%
+    % Split the last of the double-column material.  Leave it on the
+    % current page, no automatic page break.
+    \balancecolumns
+    %
+    % If we end up splitting too much material for the current page,
+    % though, there will be another page break right after this \output
+    % invocation ends.  Having called \balancecolumns once, we do not
+    % want to call it again.  Therefore, reset \output to its normal
+    % definition right away.  (We hope \balancecolumns will never be
+    % called on to balance too much material, but if it is, this makes
+    % the output somewhat more palatable.)
+    \global\output = {\onepageout{\pagecontents\PAGE}}%
+  }%
+  \eject
+  \endgroup % started in \begindoublecolumns
+  %
+  % \pagegoal was set to the doubled \vsize above, since we restarted
+  % the current page.  We're now back to normal single-column
+  % typesetting, so reset \pagegoal to the normal \vsize (after the
+  % \endgroup where \vsize got restored).
+  \pagegoal = \vsize
+}
+%
+% Called at the end of the double column material.
+\def\balancecolumns{%
+  \setbox0 = \vbox{\unvbox255}% like \box255 but more efficient, see p.120.
+  \dimen@ = \ht0
+  \advance\dimen@ by \topskip
+  \advance\dimen@ by-\baselineskip
+  \divide\dimen@ by 2 % target to split to
+  %debug\message{final 2-column material height=\the\ht0, target=\the\dimen@.}%
+  \splittopskip = \topskip
+  % Loop until we get a decent breakpoint.
+  {%
+    \vbadness = 10000
+    \loop
+      \global\setbox3 = \copy0
+      \global\setbox1 = \vsplit3 to \dimen@
+    \ifdim\ht3>\dimen@
+      \global\advance\dimen@ by 1pt
+    \repeat
+  }%
+  %debug\message{split to \the\dimen@, column heights: \the\ht1, \the\ht3.}%
+  \setbox0=\vbox to\dimen@{\unvbox1}%
+  \setbox2=\vbox to\dimen@{\unvbox3}%
+  %
+  \pagesofar
+}
+\catcode`\@ = \other
+
+
+\message{sectioning,}
+% Chapters, sections, etc.
+
+% \unnumberedno is an oxymoron, of course.  But we count the unnumbered
+% sections so that we can refer to them unambiguously in the pdf
+% outlines by their "section number".  We avoid collisions with chapter
+% numbers by starting them at 10000.  (If a document ever has 10000
+% chapters, we're in trouble anyway, I'm sure.)
+\newcount\unnumberedno \unnumberedno = 10000
+\newcount\chapno
+\newcount\secno        \secno=0
+\newcount\subsecno     \subsecno=0
+\newcount\subsubsecno  \subsubsecno=0
+
+% This counter is funny since it counts through charcodes of letters A, B, ...
+\newcount\appendixno  \appendixno = `\@
+%
+% \def\appendixletter{\char\the\appendixno}
+% We do the following ugly conditional instead of the above simple
+% construct for the sake of pdftex, which needs the actual
+% letter in the expansion, not just typeset.
+%
+\def\appendixletter{%
+  \ifnum\appendixno=`A A%
+  \else\ifnum\appendixno=`B B%
+  \else\ifnum\appendixno=`C C%
+  \else\ifnum\appendixno=`D D%
+  \else\ifnum\appendixno=`E E%
+  \else\ifnum\appendixno=`F F%
+  \else\ifnum\appendixno=`G G%
+  \else\ifnum\appendixno=`H H%
+  \else\ifnum\appendixno=`I I%
+  \else\ifnum\appendixno=`J J%
+  \else\ifnum\appendixno=`K K%
+  \else\ifnum\appendixno=`L L%
+  \else\ifnum\appendixno=`M M%
+  \else\ifnum\appendixno=`N N%
+  \else\ifnum\appendixno=`O O%
+  \else\ifnum\appendixno=`P P%
+  \else\ifnum\appendixno=`Q Q%
+  \else\ifnum\appendixno=`R R%
+  \else\ifnum\appendixno=`S S%
+  \else\ifnum\appendixno=`T T%
+  \else\ifnum\appendixno=`U U%
+  \else\ifnum\appendixno=`V V%
+  \else\ifnum\appendixno=`W W%
+  \else\ifnum\appendixno=`X X%
+  \else\ifnum\appendixno=`Y Y%
+  \else\ifnum\appendixno=`Z Z%
+  % The \the is necessary, despite appearances, because \appendixletter is
+  % expanded while writing the .toc file.  \char\appendixno is not
+  % expandable, thus it is written literally, thus all appendixes come out
+  % with the same letter (or @) in the toc without it.
+  \else\char\the\appendixno
+  \fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi
+  \fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi}
+
+% Each @chapter defines these (using marks) as the number+name, number
+% and name of the chapter.  Page headings and footings can use
+% these.  @section does likewise.
+\def\thischapter{}
+\def\thischapternum{}
+\def\thischaptername{}
+\def\thissection{}
+\def\thissectionnum{}
+\def\thissectionname{}
+
+\newcount\absseclevel % used to calculate proper heading level
+\newcount\secbase\secbase=0 % @raisesections/@lowersections modify this count
+
+% @raisesections: treat @section as chapter, @subsection as section, etc.
+\def\raisesections{\global\advance\secbase by -1}
+\let\up=\raisesections % original BFox name
+
+% @lowersections: treat @chapter as section, @section as subsection, etc.
+\def\lowersections{\global\advance\secbase by 1}
+\let\down=\lowersections % original BFox name
+
+% we only have subsub.
+\chardef\maxseclevel = 3
+%
+% A numbered section within an unnumbered changes to unnumbered too.
+% To achive this, remember the "biggest" unnum. sec. we are currently in:
+\chardef\unmlevel = \maxseclevel
+%
+% Trace whether the current chapter is an appendix or not:
+% \chapheadtype is "N" or "A", unnumbered chapters are ignored.
+\def\chapheadtype{N}
+
+% Choose a heading macro
+% #1 is heading type
+% #2 is heading level
+% #3 is text for heading
+\def\genhead#1#2#3{%
+  % Compute the abs. sec. level:
+  \absseclevel=#2
+  \advance\absseclevel by \secbase
+  % Make sure \absseclevel doesn't fall outside the range:
+  \ifnum \absseclevel < 0
+    \absseclevel = 0
+  \else
+    \ifnum \absseclevel > 3
+      \absseclevel = 3
+    \fi
+  \fi
+  % The heading type:
+  \def\headtype{#1}%
+  \if \headtype U%
+    \ifnum \absseclevel < \unmlevel
+      \chardef\unmlevel = \absseclevel
+    \fi
+  \else
+    % Check for appendix sections:
+    \ifnum \absseclevel = 0
+      \edef\chapheadtype{\headtype}%
+    \else
+      \if \headtype A\if \chapheadtype N%
+	\errmessage{@appendix... within a non-appendix chapter}%
+      \fi\fi
+    \fi
+    % Check for numbered within unnumbered:
+    \ifnum \absseclevel > \unmlevel
+      \def\headtype{U}%
+    \else
+      \chardef\unmlevel = 3
+    \fi
+  \fi
+  % Now print the heading:
+  \if \headtype U%
+    \ifcase\absseclevel
+	\unnumberedzzz{#3}%
+    \or \unnumberedseczzz{#3}%
+    \or \unnumberedsubseczzz{#3}%
+    \or \unnumberedsubsubseczzz{#3}%
+    \fi
+  \else
+    \if \headtype A%
+      \ifcase\absseclevel
+	  \appendixzzz{#3}%
+      \or \appendixsectionzzz{#3}%
+      \or \appendixsubseczzz{#3}%
+      \or \appendixsubsubseczzz{#3}%
+      \fi
+    \else
+      \ifcase\absseclevel
+	  \chapterzzz{#3}%
+      \or \seczzz{#3}%
+      \or \numberedsubseczzz{#3}%
+      \or \numberedsubsubseczzz{#3}%
+      \fi
+    \fi
+  \fi
+  \suppressfirstparagraphindent
+}
+
+% an interface:
+\def\numhead{\genhead N}
+\def\apphead{\genhead A}
+\def\unnmhead{\genhead U}
+
+% @chapter, @appendix, @unnumbered.  Increment top-level counter, reset
+% all lower-level sectioning counters to zero.
+%
+% Also set \chaplevelprefix, which we prepend to @float sequence numbers
+% (e.g., figures), q.v.  By default (before any chapter), that is empty.
+\let\chaplevelprefix = \empty
+%
+\outer\parseargdef\chapter{\numhead0{#1}} % normally numhead0 calls chapterzzz
+\def\chapterzzz#1{%
+  % section resetting is \global in case the chapter is in a group, such
+  % as an @include file.
+  \global\secno=0 \global\subsecno=0 \global\subsubsecno=0
+    \global\advance\chapno by 1
+  %
+  % Used for \float.
+  \gdef\chaplevelprefix{\the\chapno.}%
+  \resetallfloatnos
+  %
+  % \putwordChapter can contain complex things in translations.
+  \toks0=\expandafter{\putwordChapter}%
+  \message{\the\toks0 \space \the\chapno}%
+  %
+  % Write the actual heading.
+  \chapmacro{#1}{Ynumbered}{\the\chapno}%
+  %
+  % So @section and the like are numbered underneath this chapter.
+  \global\let\section = \numberedsec
+  \global\let\subsection = \numberedsubsec
+  \global\let\subsubsection = \numberedsubsubsec
+}
+
+\outer\parseargdef\appendix{\apphead0{#1}} % normally calls appendixzzz
+%
+\def\appendixzzz#1{%
+  \global\secno=0 \global\subsecno=0 \global\subsubsecno=0
+    \global\advance\appendixno by 1
+  \gdef\chaplevelprefix{\appendixletter.}%
+  \resetallfloatnos
+  %
+  % \putwordAppendix can contain complex things in translations.
+  \toks0=\expandafter{\putwordAppendix}%
+  \message{\the\toks0 \space \appendixletter}%
+  %
+  \chapmacro{#1}{Yappendix}{\appendixletter}%
+  %
+  \global\let\section = \appendixsec
+  \global\let\subsection = \appendixsubsec
+  \global\let\subsubsection = \appendixsubsubsec
+}
+
+\outer\parseargdef\unnumbered{\unnmhead0{#1}} % normally unnmhead0 calls unnumberedzzz
+\def\unnumberedzzz#1{%
+  \global\secno=0 \global\subsecno=0 \global\subsubsecno=0
+    \global\advance\unnumberedno by 1
+  %
+  % Since an unnumbered has no number, no prefix for figures.
+  \global\let\chaplevelprefix = \empty
+  \resetallfloatnos
+  %
+  % This used to be simply \message{#1}, but TeX fully expands the
+  % argument to \message.  Therefore, if #1 contained @-commands, TeX
+  % expanded them.  For example, in `@unnumbered The @cite{Book}', TeX
+  % expanded @cite (which turns out to cause errors because \cite is meant
+  % to be executed, not expanded).
+  %
+  % Anyway, we don't want the fully-expanded definition of @cite to appear
+  % as a result of the \message, we just want `@cite' itself.  We use
+  % \the<toks register> to achieve this: TeX expands \the<toks> only once,
+  % simply yielding the contents of <toks register>.  (We also do this for
+  % the toc entries.)
+  \toks0 = {#1}%
+  \message{(\the\toks0)}%
+  %
+  \chapmacro{#1}{Ynothing}{\the\unnumberedno}%
+  %
+  \global\let\section = \unnumberedsec
+  \global\let\subsection = \unnumberedsubsec
+  \global\let\subsubsection = \unnumberedsubsubsec
+}
+
+% @centerchap is like @unnumbered, but the heading is centered.
+\outer\parseargdef\centerchap{%
+  % Well, we could do the following in a group, but that would break
+  % an assumption that \chapmacro is called at the outermost level.
+  % Thus we are safer this way:		--kasal, 24feb04
+  \let\centerparametersmaybe = \centerparameters
+  \unnmhead0{#1}%
+  \let\centerparametersmaybe = \relax
+}
+
+% @top is like @unnumbered.
+\let\top\unnumbered
+
+% Sections.
+\outer\parseargdef\numberedsec{\numhead1{#1}} % normally calls seczzz
+\def\seczzz#1{%
+  \global\subsecno=0 \global\subsubsecno=0  \global\advance\secno by 1
+  \sectionheading{#1}{sec}{Ynumbered}{\the\chapno.\the\secno}%
+}
+
+\outer\parseargdef\appendixsection{\apphead1{#1}} % normally calls appendixsectionzzz
+\def\appendixsectionzzz#1{%
+  \global\subsecno=0 \global\subsubsecno=0  \global\advance\secno by 1
+  \sectionheading{#1}{sec}{Yappendix}{\appendixletter.\the\secno}%
+}
+\let\appendixsec\appendixsection
+
+\outer\parseargdef\unnumberedsec{\unnmhead1{#1}} % normally calls unnumberedseczzz
+\def\unnumberedseczzz#1{%
+  \global\subsecno=0 \global\subsubsecno=0  \global\advance\secno by 1
+  \sectionheading{#1}{sec}{Ynothing}{\the\unnumberedno.\the\secno}%
+}
+
+% Subsections.
+\outer\parseargdef\numberedsubsec{\numhead2{#1}} % normally calls numberedsubseczzz
+\def\numberedsubseczzz#1{%
+  \global\subsubsecno=0  \global\advance\subsecno by 1
+  \sectionheading{#1}{subsec}{Ynumbered}{\the\chapno.\the\secno.\the\subsecno}%
+}
+
+\outer\parseargdef\appendixsubsec{\apphead2{#1}} % normally calls appendixsubseczzz
+\def\appendixsubseczzz#1{%
+  \global\subsubsecno=0  \global\advance\subsecno by 1
+  \sectionheading{#1}{subsec}{Yappendix}%
+                 {\appendixletter.\the\secno.\the\subsecno}%
+}
+
+\outer\parseargdef\unnumberedsubsec{\unnmhead2{#1}} %normally calls unnumberedsubseczzz
+\def\unnumberedsubseczzz#1{%
+  \global\subsubsecno=0  \global\advance\subsecno by 1
+  \sectionheading{#1}{subsec}{Ynothing}%
+                 {\the\unnumberedno.\the\secno.\the\subsecno}%
+}
+
+% Subsubsections.
+\outer\parseargdef\numberedsubsubsec{\numhead3{#1}} % normally numberedsubsubseczzz
+\def\numberedsubsubseczzz#1{%
+  \global\advance\subsubsecno by 1
+  \sectionheading{#1}{subsubsec}{Ynumbered}%
+                 {\the\chapno.\the\secno.\the\subsecno.\the\subsubsecno}%
+}
+
+\outer\parseargdef\appendixsubsubsec{\apphead3{#1}} % normally appendixsubsubseczzz
+\def\appendixsubsubseczzz#1{%
+  \global\advance\subsubsecno by 1
+  \sectionheading{#1}{subsubsec}{Yappendix}%
+                 {\appendixletter.\the\secno.\the\subsecno.\the\subsubsecno}%
+}
+
+\outer\parseargdef\unnumberedsubsubsec{\unnmhead3{#1}} %normally unnumberedsubsubseczzz
+\def\unnumberedsubsubseczzz#1{%
+  \global\advance\subsubsecno by 1
+  \sectionheading{#1}{subsubsec}{Ynothing}%
+                 {\the\unnumberedno.\the\secno.\the\subsecno.\the\subsubsecno}%
+}
+
+% These macros control what the section commands do, according
+% to what kind of chapter we are in (ordinary, appendix, or unnumbered).
+% Define them by default for a numbered chapter.
+\let\section = \numberedsec
+\let\subsection = \numberedsubsec
+\let\subsubsection = \numberedsubsubsec
+
+% Define @majorheading, @heading and @subheading
+
+% NOTE on use of \vbox for chapter headings, section headings, and such:
+%       1) We use \vbox rather than the earlier \line to permit
+%          overlong headings to fold.
+%       2) \hyphenpenalty is set to 10000 because hyphenation in a
+%          heading is obnoxious; this forbids it.
+%       3) Likewise, headings look best if no \parindent is used, and
+%          if justification is not attempted.  Hence \raggedright.
+
+\def\majorheading{%
+  {\advance\chapheadingskip by 10pt \chapbreak }%
+  \parsearg\chapheadingzzz
+}
+
+\def\chapheading{\chapbreak \parsearg\chapheadingzzz}
+\def\chapheadingzzz#1{%
+  {\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000
+                    \parindent=0pt\ptexraggedright
+                    \rmisbold #1\hfill}}%
+  \bigskip \par\penalty 200\relax
+  \suppressfirstparagraphindent
+}
+
+% @heading, @subheading, @subsubheading.
+\parseargdef\heading{\sectionheading{#1}{sec}{Yomitfromtoc}{}
+  \suppressfirstparagraphindent}
+\parseargdef\subheading{\sectionheading{#1}{subsec}{Yomitfromtoc}{}
+  \suppressfirstparagraphindent}
+\parseargdef\subsubheading{\sectionheading{#1}{subsubsec}{Yomitfromtoc}{}
+  \suppressfirstparagraphindent}
+
+% These macros generate a chapter, section, etc. heading only
+% (including whitespace, linebreaking, etc. around it),
+% given all the information in convenient, parsed form.
+
+%%% Args are the skip and penalty (usually negative)
+\def\dobreak#1#2{\par\ifdim\lastskip<#1\removelastskip\penalty#2\vskip#1\fi}
+
+%%% Define plain chapter starts, and page on/off switching for it
+% Parameter controlling skip before chapter headings (if needed)
+
+\newskip\chapheadingskip
+
+\def\chapbreak{\dobreak \chapheadingskip {-4000}}
+\def\chappager{\par\vfill\supereject}
+% Because \domark is called before \chapoddpage, the filler page will
+% get the headings for the next chapter, which is wrong.  But we don't
+% care -- we just disable all headings on the filler page.
+\def\chapoddpage{%
+  \chappager
+  \ifodd\pageno \else
+    \begingroup
+      \evenheadline={\hfil}\evenfootline={\hfil}%
+      \oddheadline={\hfil}\oddfootline={\hfil}%
+      \hbox to 0pt{}%
+      \chappager
+    \endgroup
+  \fi
+}
+
+\def\setchapternewpage #1 {\csname CHAPPAG#1\endcsname}
+
+\def\CHAPPAGoff{%
+\global\let\contentsalignmacro = \chappager
+\global\let\pchapsepmacro=\chapbreak
+\global\let\pagealignmacro=\chappager}
+
+\def\CHAPPAGon{%
+\global\let\contentsalignmacro = \chappager
+\global\let\pchapsepmacro=\chappager
+\global\let\pagealignmacro=\chappager
+\global\def\HEADINGSon{\HEADINGSsingle}}
+
+\def\CHAPPAGodd{%
+\global\let\contentsalignmacro = \chapoddpage
+\global\let\pchapsepmacro=\chapoddpage
+\global\let\pagealignmacro=\chapoddpage
+\global\def\HEADINGSon{\HEADINGSdouble}}
+
+\CHAPPAGon
+
+% Chapter opening.
+%
+% #1 is the text, #2 is the section type (Ynumbered, Ynothing,
+% Yappendix, Yomitfromtoc), #3 the chapter number.
+%
+% To test against our argument.
+\def\Ynothingkeyword{Ynothing}
+\def\Yomitfromtockeyword{Yomitfromtoc}
+\def\Yappendixkeyword{Yappendix}
+%
+\def\chapmacro#1#2#3{%
+  % Insert the first mark before the heading break (see notes for \domark).
+  \let\prevchapterdefs=\lastchapterdefs
+  \let\prevsectiondefs=\lastsectiondefs
+  \gdef\lastsectiondefs{\gdef\thissectionname{}\gdef\thissectionnum{}%
+                        \gdef\thissection{}}%
+  %
+  \def\temptype{#2}%
+  \ifx\temptype\Ynothingkeyword
+    \gdef\lastchapterdefs{\gdef\thischaptername{#1}\gdef\thischapternum{}%
+                          \gdef\thischapter{\thischaptername}}%
+  \else\ifx\temptype\Yomitfromtockeyword
+    \gdef\lastchapterdefs{\gdef\thischaptername{#1}\gdef\thischapternum{}%
+                          \gdef\thischapter{}}%
+  \else\ifx\temptype\Yappendixkeyword
+    \toks0={#1}%
+    \xdef\lastchapterdefs{%
+      \gdef\noexpand\thischaptername{\the\toks0}%
+      \gdef\noexpand\thischapternum{\appendixletter}%
+      % \noexpand\putwordAppendix avoids expanding indigestible
+      % commands in some of the translations.
+      \gdef\noexpand\thischapter{\noexpand\putwordAppendix{}
+                                 \noexpand\thischapternum:
+                                 \noexpand\thischaptername}%
+    }%
+  \else
+    \toks0={#1}%
+    \xdef\lastchapterdefs{%
+      \gdef\noexpand\thischaptername{\the\toks0}%
+      \gdef\noexpand\thischapternum{\the\chapno}%
+      % \noexpand\putwordChapter avoids expanding indigestible
+      % commands in some of the translations.
+      \gdef\noexpand\thischapter{\noexpand\putwordChapter{}
+                                 \noexpand\thischapternum:
+                                 \noexpand\thischaptername}%
+    }%
+  \fi\fi\fi
+  %
+  % Output the mark.  Pass it through \safewhatsit, to take care of
+  % the preceding space.
+  \safewhatsit\domark
+  %
+  % Insert the chapter heading break.
+  \pchapsepmacro
+  %
+  % Now the second mark, after the heading break.  No break points
+  % between here and the heading.
+  \let\prevchapterdefs=\lastchapterdefs
+  \let\prevsectiondefs=\lastsectiondefs
+  \domark
+  %
+  {%
+    \chapfonts \rmisbold
+    %
+    % Have to define \lastsection before calling \donoderef, because the
+    % xref code eventually uses it.  On the other hand, it has to be called
+    % after \pchapsepmacro, or the headline will change too soon.
+    \gdef\lastsection{#1}%
+    %
+    % Only insert the separating space if we have a chapter/appendix
+    % number, and don't print the unnumbered ``number''.
+    \ifx\temptype\Ynothingkeyword
+      \setbox0 = \hbox{}%
+      \def\toctype{unnchap}%
+    \else\ifx\temptype\Yomitfromtockeyword
+      \setbox0 = \hbox{}% contents like unnumbered, but no toc entry
+      \def\toctype{omit}%
+    \else\ifx\temptype\Yappendixkeyword
+      \setbox0 = \hbox{\putwordAppendix{} #3\enspace}%
+      \def\toctype{app}%
+    \else
+      \setbox0 = \hbox{#3\enspace}%
+      \def\toctype{numchap}%
+    \fi\fi\fi
+    %
+    % Write the toc entry for this chapter.  Must come before the
+    % \donoderef, because we include the current node name in the toc
+    % entry, and \donoderef resets it to empty.
+    \writetocentry{\toctype}{#1}{#3}%
+    %
+    % For pdftex, we have to write out the node definition (aka, make
+    % the pdfdest) after any page break, but before the actual text has
+    % been typeset.  If the destination for the pdf outline is after the
+    % text, then jumping from the outline may wind up with the text not
+    % being visible, for instance under high magnification.
+    \donoderef{#2}%
+    %
+    % Typeset the actual heading.
+    \nobreak % Avoid page breaks at the interline glue.
+    \vbox{\hyphenpenalty=10000 \tolerance=5000 \parindent=0pt \ptexraggedright
+          \hangindent=\wd0 \centerparametersmaybe
+          \unhbox0 #1\par}%
+  }%
+  \nobreak\bigskip % no page break after a chapter title
+  \nobreak
+}
+
+% @centerchap -- centered and unnumbered.
+\let\centerparametersmaybe = \relax
+\def\centerparameters{%
+  \advance\rightskip by 3\rightskip
+  \leftskip = \rightskip
+  \parfillskip = 0pt
+}
+
+
+% I don't think this chapter style is supported any more, so I'm not
+% updating it with the new noderef stuff.  We'll see.  --karl, 11aug03.
+%
+\def\setchapterstyle #1 {\csname CHAPF#1\endcsname}
+%
+\def\unnchfopen #1{%
+\chapoddpage {\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000
+                       \parindent=0pt\ptexraggedright
+                       \rmisbold #1\hfill}}\bigskip \par\nobreak
+}
+\def\chfopen #1#2{\chapoddpage {\chapfonts
+\vbox to 3in{\vfil \hbox to\hsize{\hfil #2} \hbox to\hsize{\hfil #1} \vfil}}%
+\par\penalty 5000 %
+}
+\def\centerchfopen #1{%
+\chapoddpage {\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000
+                       \parindent=0pt
+                       \hfill {\rmisbold #1}\hfill}}\bigskip \par\nobreak
+}
+\def\CHAPFopen{%
+  \global\let\chapmacro=\chfopen
+  \global\let\centerchapmacro=\centerchfopen}
+
+
+% Section titles.  These macros combine the section number parts and
+% call the generic \sectionheading to do the printing.
+%
+\newskip\secheadingskip
+\def\secheadingbreak{\dobreak \secheadingskip{-1000}}
+
+% Subsection titles.
+\newskip\subsecheadingskip
+\def\subsecheadingbreak{\dobreak \subsecheadingskip{-500}}
+
+% Subsubsection titles.
+\def\subsubsecheadingskip{\subsecheadingskip}
+\def\subsubsecheadingbreak{\subsecheadingbreak}
+
+
+% Print any size, any type, section title.
+%
+% #1 is the text, #2 is the section level (sec/subsec/subsubsec), #3 is
+% the section type for xrefs (Ynumbered, Ynothing, Yappendix), #4 is the
+% section number.
+%
+\def\seckeyword{sec}
+%
+\def\sectionheading#1#2#3#4{%
+  {%
+    % Switch to the right set of fonts.
+    \csname #2fonts\endcsname \rmisbold
+    %
+    \def\sectionlevel{#2}%
+    \def\temptype{#3}%
+    %
+    % Insert first mark before the heading break (see notes for \domark).
+    \let\prevsectiondefs=\lastsectiondefs
+    \ifx\temptype\Ynothingkeyword
+      \ifx\sectionlevel\seckeyword
+        \gdef\lastsectiondefs{\gdef\thissectionname{#1}\gdef\thissectionnum{}%
+                              \gdef\thissection{\thissectionname}}%
+      \fi
+    \else\ifx\temptype\Yomitfromtockeyword
+      % Don't redefine \thissection.
+    \else\ifx\temptype\Yappendixkeyword
+      \ifx\sectionlevel\seckeyword
+        \toks0={#1}%
+        \xdef\lastsectiondefs{%
+          \gdef\noexpand\thissectionname{\the\toks0}%
+          \gdef\noexpand\thissectionnum{#4}%
+          % \noexpand\putwordSection avoids expanding indigestible
+          % commands in some of the translations.
+          \gdef\noexpand\thissection{\noexpand\putwordSection{}
+                                     \noexpand\thissectionnum:
+                                     \noexpand\thissectionname}%
+        }%
+      \fi
+    \else
+      \ifx\sectionlevel\seckeyword
+        \toks0={#1}%
+        \xdef\lastsectiondefs{%
+          \gdef\noexpand\thissectionname{\the\toks0}%
+          \gdef\noexpand\thissectionnum{#4}%
+          % \noexpand\putwordSection avoids expanding indigestible
+          % commands in some of the translations.
+          \gdef\noexpand\thissection{\noexpand\putwordSection{}
+                                     \noexpand\thissectionnum:
+                                     \noexpand\thissectionname}%
+        }%
+      \fi
+    \fi\fi\fi
+    %
+    % Go into vertical mode.  Usually we'll already be there, but we
+    % don't want the following whatsit to end up in a preceding paragraph
+    % if the document didn't happen to have a blank line.
+    \par
+    %
+    % Output the mark.  Pass it through \safewhatsit, to take care of
+    % the preceding space.
+    \safewhatsit\domark
+    %
+    % Insert space above the heading.
+    \csname #2headingbreak\endcsname
+    %
+    % Now the second mark, after the heading break.  No break points
+    % between here and the heading.
+    \let\prevsectiondefs=\lastsectiondefs
+    \domark
+    %
+    % Only insert the space after the number if we have a section number.
+    \ifx\temptype\Ynothingkeyword
+      \setbox0 = \hbox{}%
+      \def\toctype{unn}%
+      \gdef\lastsection{#1}%
+    \else\ifx\temptype\Yomitfromtockeyword
+      % for @headings -- no section number, don't include in toc,
+      % and don't redefine \lastsection.
+      \setbox0 = \hbox{}%
+      \def\toctype{omit}%
+      \let\sectionlevel=\empty
+    \else\ifx\temptype\Yappendixkeyword
+      \setbox0 = \hbox{#4\enspace}%
+      \def\toctype{app}%
+      \gdef\lastsection{#1}%
+    \else
+      \setbox0 = \hbox{#4\enspace}%
+      \def\toctype{num}%
+      \gdef\lastsection{#1}%
+    \fi\fi\fi
+    %
+    % Write the toc entry (before \donoderef).  See comments in \chapmacro.
+    \writetocentry{\toctype\sectionlevel}{#1}{#4}%
+    %
+    % Write the node reference (= pdf destination for pdftex).
+    % Again, see comments in \chapmacro.
+    \donoderef{#3}%
+    %
+    % Interline glue will be inserted when the vbox is completed.
+    % That glue will be a valid breakpoint for the page, since it'll be
+    % preceded by a whatsit (usually from the \donoderef, or from the
+    % \writetocentry if there was no node).  We don't want to allow that
+    % break, since then the whatsits could end up on page n while the
+    % section is on page n+1, thus toc/etc. are wrong.  Debian bug 276000.
+    \nobreak
+    %
+    % Output the actual section heading.
+    \vbox{\hyphenpenalty=10000 \tolerance=5000 \parindent=0pt \ptexraggedright
+          \hangindent=\wd0  % zero if no section number
+          \unhbox0 #1}%
+  }%
+  % Add extra space after the heading -- half of whatever came above it.
+  % Don't allow stretch, though.
+  \kern .5 \csname #2headingskip\endcsname
+  %
+  % Do not let the kern be a potential breakpoint, as it would be if it
+  % was followed by glue.
+  \nobreak
+  %
+  % We'll almost certainly start a paragraph next, so don't let that
+  % glue accumulate.  (Not a breakpoint because it's preceded by a
+  % discardable item.)
+  \vskip-\parskip
+  %
+  % This is purely so the last item on the list is a known \penalty >
+  % 10000.  This is so \startdefun can avoid allowing breakpoints after
+  % section headings.  Otherwise, it would insert a valid breakpoint between:
+  %
+  %   @section sec-whatever
+  %   @deffn def-whatever
+  \penalty 10001
+}
+
+
+\message{toc,}
+% Table of contents.
+\newwrite\tocfile
+
+% Write an entry to the toc file, opening it if necessary.
+% Called from @chapter, etc.
+%
+% Example usage: \writetocentry{sec}{Section Name}{\the\chapno.\the\secno}
+% We append the current node name (if any) and page number as additional
+% arguments for the \{chap,sec,...}entry macros which will eventually
+% read this.  The node name is used in the pdf outlines as the
+% destination to jump to.
+%
+% We open the .toc file for writing here instead of at @setfilename (or
+% any other fixed time) so that @contents can be anywhere in the document.
+% But if #1 is `omit', then we don't do anything.  This is used for the
+% table of contents chapter openings themselves.
+%
+\newif\iftocfileopened
+\def\omitkeyword{omit}%
+%
+\def\writetocentry#1#2#3{%
+  \edef\writetoctype{#1}%
+  \ifx\writetoctype\omitkeyword \else
+    \iftocfileopened\else
+      \immediate\openout\tocfile = \jobname.toc
+      \global\tocfileopenedtrue
+    \fi
+    %
+    \iflinks
+      {\atdummies
+       \edef\temp{%
+         \write\tocfile{@#1entry{#2}{#3}{\lastnode}{\noexpand\folio}}}%
+       \temp
+      }%
+    \fi
+  \fi
+  %
+  % Tell \shipout to create a pdf destination on each page, if we're
+  % writing pdf.  These are used in the table of contents.  We can't
+  % just write one on every page because the title pages are numbered
+  % 1 and 2 (the page numbers aren't printed), and so are the first
+  % two pages of the document.  Thus, we'd have two destinations named
+  % `1', and two named `2'.
+  \ifpdf \global\pdfmakepagedesttrue \fi
+}
+
+
+% These characters do not print properly in the Computer Modern roman
+% fonts, so we must take special care.  This is more or less redundant
+% with the Texinfo input format setup at the end of this file.
+%
+\def\activecatcodes{%
+  \catcode`\"=\active
+  \catcode`\$=\active
+  \catcode`\<=\active
+  \catcode`\>=\active
+  \catcode`\\=\active
+  \catcode`\^=\active
+  \catcode`\_=\active
+  \catcode`\|=\active
+  \catcode`\~=\active
+}
+
+
+% Read the toc file, which is essentially Texinfo input.
+\def\readtocfile{%
+  \setupdatafile
+  \activecatcodes
+  \input \tocreadfilename
+}
+
+\newskip\contentsrightmargin \contentsrightmargin=1in
+\newcount\savepageno
+\newcount\lastnegativepageno \lastnegativepageno = -1
+
+% Prepare to read what we've written to \tocfile.
+%
+\def\startcontents#1{%
+  % If @setchapternewpage on, and @headings double, the contents should
+  % start on an odd page, unlike chapters.  Thus, we maintain
+  % \contentsalignmacro in parallel with \pagealignmacro.
+  % From: Torbjorn Granlund <tege@matematik.su.se>
+  \contentsalignmacro
+  \immediate\closeout\tocfile
+  %
+  % Don't need to put `Contents' or `Short Contents' in the headline.
+  % It is abundantly clear what they are.
+  \chapmacro{#1}{Yomitfromtoc}{}%
+  %
+  \savepageno = \pageno
+  \begingroup                  % Set up to handle contents files properly.
+    \raggedbottom              % Worry more about breakpoints than the bottom.
+    \advance\hsize by -\contentsrightmargin % Don't use the full line length.
+    %
+    % Roman numerals for page numbers.
+    \ifnum \pageno>0 \global\pageno = \lastnegativepageno \fi
+}
+
+% redefined for the two-volume lispref.  We always output on
+% \jobname.toc even if this is redefined.
+%
+\def\tocreadfilename{\jobname.toc}
+
+% Normal (long) toc.
+%
+\def\contents{%
+  \startcontents{\putwordTOC}%
+    \openin 1 \tocreadfilename\space
+    \ifeof 1 \else
+      \readtocfile
+    \fi
+    \vfill \eject
+    \contentsalignmacro % in case @setchapternewpage odd is in effect
+    \ifeof 1 \else
+      \pdfmakeoutlines
+    \fi
+    \closein 1
+  \endgroup
+  \lastnegativepageno = \pageno
+  \global\pageno = \savepageno
+}
+
+% And just the chapters.
+\def\summarycontents{%
+  \startcontents{\putwordShortTOC}%
+    %
+    \let\numchapentry = \shortchapentry
+    \let\appentry = \shortchapentry
+    \let\unnchapentry = \shortunnchapentry
+    % We want a true roman here for the page numbers.
+    \secfonts
+    \let\rm=\shortcontrm \let\bf=\shortcontbf
+    \let\sl=\shortcontsl \let\tt=\shortconttt
+    \rm
+    \hyphenpenalty = 10000
+    \advance\baselineskip by 1pt % Open it up a little.
+    \def\numsecentry##1##2##3##4{}
+    \let\appsecentry = \numsecentry
+    \let\unnsecentry = \numsecentry
+    \let\numsubsecentry = \numsecentry
+    \let\appsubsecentry = \numsecentry
+    \let\unnsubsecentry = \numsecentry
+    \let\numsubsubsecentry = \numsecentry
+    \let\appsubsubsecentry = \numsecentry
+    \let\unnsubsubsecentry = \numsecentry
+    \openin 1 \tocreadfilename\space
+    \ifeof 1 \else
+      \readtocfile
+    \fi
+    \closein 1
+    \vfill \eject
+    \contentsalignmacro % in case @setchapternewpage odd is in effect
+  \endgroup
+  \lastnegativepageno = \pageno
+  \global\pageno = \savepageno
+}
+\let\shortcontents = \summarycontents
+
+% Typeset the label for a chapter or appendix for the short contents.
+% The arg is, e.g., `A' for an appendix, or `3' for a chapter.
+%
+\def\shortchaplabel#1{%
+  % This space should be enough, since a single number is .5em, and the
+  % widest letter (M) is 1em, at least in the Computer Modern fonts.
+  % But use \hss just in case.
+  % (This space doesn't include the extra space that gets added after
+  % the label; that gets put in by \shortchapentry above.)
+  %
+  % We'd like to right-justify chapter numbers, but that looks strange
+  % with appendix letters.  And right-justifying numbers and
+  % left-justifying letters looks strange when there is less than 10
+  % chapters.  Have to read the whole toc once to know how many chapters
+  % there are before deciding ...
+  \hbox to 1em{#1\hss}%
+}
+
+% These macros generate individual entries in the table of contents.
+% The first argument is the chapter or section name.
+% The last argument is the page number.
+% The arguments in between are the chapter number, section number, ...
+
+% Chapters, in the main contents.
+\def\numchapentry#1#2#3#4{\dochapentry{#2\labelspace#1}{#4}}
+%
+% Chapters, in the short toc.
+% See comments in \dochapentry re vbox and related settings.
+\def\shortchapentry#1#2#3#4{%
+  \tocentry{\shortchaplabel{#2}\labelspace #1}{\doshortpageno\bgroup#4\egroup}%
+}
+
+% Appendices, in the main contents.
+% Need the word Appendix, and a fixed-size box.
+%
+\def\appendixbox#1{%
+  % We use M since it's probably the widest letter.
+  \setbox0 = \hbox{\putwordAppendix{} M}%
+  \hbox to \wd0{\putwordAppendix{} #1\hss}}
+%
+\def\appentry#1#2#3#4{\dochapentry{\appendixbox{#2}\labelspace#1}{#4}}
+
+% Unnumbered chapters.
+\def\unnchapentry#1#2#3#4{\dochapentry{#1}{#4}}
+\def\shortunnchapentry#1#2#3#4{\tocentry{#1}{\doshortpageno\bgroup#4\egroup}}
+
+% Sections.
+\def\numsecentry#1#2#3#4{\dosecentry{#2\labelspace#1}{#4}}
+\let\appsecentry=\numsecentry
+\def\unnsecentry#1#2#3#4{\dosecentry{#1}{#4}}
+
+% Subsections.
+\def\numsubsecentry#1#2#3#4{\dosubsecentry{#2\labelspace#1}{#4}}
+\let\appsubsecentry=\numsubsecentry
+\def\unnsubsecentry#1#2#3#4{\dosubsecentry{#1}{#4}}
+
+% And subsubsections.
+\def\numsubsubsecentry#1#2#3#4{\dosubsubsecentry{#2\labelspace#1}{#4}}
+\let\appsubsubsecentry=\numsubsubsecentry
+\def\unnsubsubsecentry#1#2#3#4{\dosubsubsecentry{#1}{#4}}
+
+% This parameter controls the indentation of the various levels.
+% Same as \defaultparindent.
+\newdimen\tocindent \tocindent = 15pt
+
+% Now for the actual typesetting. In all these, #1 is the text and #2 is the
+% page number.
+%
+% If the toc has to be broken over pages, we want it to be at chapters
+% if at all possible; hence the \penalty.
+\def\dochapentry#1#2{%
+   \penalty-300 \vskip1\baselineskip plus.33\baselineskip minus.25\baselineskip
+   \begingroup
+     \chapentryfonts
+     \tocentry{#1}{\dopageno\bgroup#2\egroup}%
+   \endgroup
+   \nobreak\vskip .25\baselineskip plus.1\baselineskip
+}
+
+\def\dosecentry#1#2{\begingroup
+  \secentryfonts \leftskip=\tocindent
+  \tocentry{#1}{\dopageno\bgroup#2\egroup}%
+\endgroup}
+
+\def\dosubsecentry#1#2{\begingroup
+  \subsecentryfonts \leftskip=2\tocindent
+  \tocentry{#1}{\dopageno\bgroup#2\egroup}%
+\endgroup}
+
+\def\dosubsubsecentry#1#2{\begingroup
+  \subsubsecentryfonts \leftskip=3\tocindent
+  \tocentry{#1}{\dopageno\bgroup#2\egroup}%
+\endgroup}
+
+% We use the same \entry macro as for the index entries.
+\let\tocentry = \entry
+
+% Space between chapter (or whatever) number and the title.
+\def\labelspace{\hskip1em \relax}
+
+\def\dopageno#1{{\rm #1}}
+\def\doshortpageno#1{{\rm #1}}
+
+\def\chapentryfonts{\secfonts \rm}
+\def\secentryfonts{\textfonts}
+\def\subsecentryfonts{\textfonts}
+\def\subsubsecentryfonts{\textfonts}
+
+
+\message{environments,}
+% @foo ... @end foo.
+
+% @tex ... @end tex    escapes into raw Tex temporarily.
+% One exception: @ is still an escape character, so that @end tex works.
+% But \@ or @@ will get a plain tex @ character.
+
+\envdef\tex{%
+  \setupmarkupstyle{tex}%
+  \catcode `\\=0 \catcode `\{=1 \catcode `\}=2
+  \catcode `\$=3 \catcode `\&=4 \catcode `\#=6
+  \catcode `\^=7 \catcode `\_=8 \catcode `\~=\active \let~=\tie
+  \catcode `\%=14
+  \catcode `\+=\other
+  \catcode `\"=\other
+  \catcode `\|=\other
+  \catcode `\<=\other
+  \catcode `\>=\other
+  \catcode`\`=\other
+  \catcode`\'=\other
+  \escapechar=`\\
+  %
+  \let\b=\ptexb
+  \let\bullet=\ptexbullet
+  \let\c=\ptexc
+  \let\,=\ptexcomma
+  \let\.=\ptexdot
+  \let\dots=\ptexdots
+  \let\equiv=\ptexequiv
+  \let\!=\ptexexclam
+  \let\i=\ptexi
+  \let\indent=\ptexindent
+  \let\noindent=\ptexnoindent
+  \let\{=\ptexlbrace
+  \let\+=\tabalign
+  \let\}=\ptexrbrace
+  \let\/=\ptexslash
+  \let\*=\ptexstar
+  \let\t=\ptext
+  \expandafter \let\csname top\endcsname=\ptextop  % outer
+  \let\frenchspacing=\plainfrenchspacing
+  %
+  \def\endldots{\mathinner{\ldots\ldots\ldots\ldots}}%
+  \def\enddots{\relax\ifmmode\endldots\else$\mathsurround=0pt \endldots\,$\fi}%
+  \def\@{@}%
+}
+% There is no need to define \Etex.
+
+% Define @lisp ... @end lisp.
+% @lisp environment forms a group so it can rebind things,
+% including the definition of @end lisp (which normally is erroneous).
+
+% Amount to narrow the margins by for @lisp.
+\newskip\lispnarrowing \lispnarrowing=0.4in
+
+% This is the definition that ^^M gets inside @lisp, @example, and other
+% such environments.  \null is better than a space, since it doesn't
+% have any width.
+\def\lisppar{\null\endgraf}
+
+% This space is always present above and below environments.
+\newskip\envskipamount \envskipamount = 0pt
+
+% Make spacing and below environment symmetrical.  We use \parskip here
+% to help in doing that, since in @example-like environments \parskip
+% is reset to zero; thus the \afterenvbreak inserts no space -- but the
+% start of the next paragraph will insert \parskip.
+%
+\def\aboveenvbreak{{%
+  % =10000 instead of <10000 because of a special case in \itemzzz and
+  % \sectionheading, q.v.
+  \ifnum \lastpenalty=10000 \else
+    \advance\envskipamount by \parskip
+    \endgraf
+    \ifdim\lastskip<\envskipamount
+      \removelastskip
+      % it's not a good place to break if the last penalty was \nobreak
+      % or better ...
+      \ifnum\lastpenalty<10000 \penalty-50 \fi
+      \vskip\envskipamount
+    \fi
+  \fi
+}}
+
+\let\afterenvbreak = \aboveenvbreak
+
+% \nonarrowing is a flag.  If "set", @lisp etc don't narrow margins; it will
+% also clear it, so that its embedded environments do the narrowing again.
+\let\nonarrowing=\relax
+
+% @cartouche ... @end cartouche: draw rectangle w/rounded corners around
+% environment contents.
+\font\circle=lcircle10
+\newdimen\circthick
+\newdimen\cartouter\newdimen\cartinner
+\newskip\normbskip\newskip\normpskip\newskip\normlskip
+\circthick=\fontdimen8\circle
+%
+\def\ctl{{\circle\char'013\hskip -6pt}}% 6pt from pl file: 1/2charwidth
+\def\ctr{{\hskip 6pt\circle\char'010}}
+\def\cbl{{\circle\char'012\hskip -6pt}}
+\def\cbr{{\hskip 6pt\circle\char'011}}
+\def\carttop{\hbox to \cartouter{\hskip\lskip
+        \ctl\leaders\hrule height\circthick\hfil\ctr
+        \hskip\rskip}}
+\def\cartbot{\hbox to \cartouter{\hskip\lskip
+        \cbl\leaders\hrule height\circthick\hfil\cbr
+        \hskip\rskip}}
+%
+\newskip\lskip\newskip\rskip
+
+\envdef\cartouche{%
+  \ifhmode\par\fi  % can't be in the midst of a paragraph.
+  \startsavinginserts
+  \lskip=\leftskip \rskip=\rightskip
+  \leftskip=0pt\rightskip=0pt % we want these *outside*.
+  \cartinner=\hsize \advance\cartinner by-\lskip
+  \advance\cartinner by-\rskip
+  \cartouter=\hsize
+  \advance\cartouter by 18.4pt	% allow for 3pt kerns on either
+				% side, and for 6pt waste from
+				% each corner char, and rule thickness
+  \normbskip=\baselineskip \normpskip=\parskip \normlskip=\lineskip
+  % Flag to tell @lisp, etc., not to narrow margin.
+  \let\nonarrowing = t%
+  \vbox\bgroup
+      \baselineskip=0pt\parskip=0pt\lineskip=0pt
+      \carttop
+      \hbox\bgroup
+	  \hskip\lskip
+	  \vrule\kern3pt
+	  \vbox\bgroup
+	      \kern3pt
+	      \hsize=\cartinner
+	      \baselineskip=\normbskip
+	      \lineskip=\normlskip
+	      \parskip=\normpskip
+	      \vskip -\parskip
+	      \comment % For explanation, see the end of \def\group.
+}
+\def\Ecartouche{%
+              \ifhmode\par\fi
+	      \kern3pt
+	  \egroup
+	  \kern3pt\vrule
+	  \hskip\rskip
+      \egroup
+      \cartbot
+  \egroup
+  \checkinserts
+}
+
+
+% This macro is called at the beginning of all the @example variants,
+% inside a group.
+\newdimen\nonfillparindent
+\def\nonfillstart{%
+  \aboveenvbreak
+  \hfuzz = 12pt % Don't be fussy
+  \sepspaces % Make spaces be word-separators rather than space tokens.
+  \let\par = \lisppar % don't ignore blank lines
+  \obeylines % each line of input is a line of output
+  \parskip = 0pt
+  % Turn off paragraph indentation but redefine \indent to emulate
+  % the normal \indent.
+  \nonfillparindent=\parindent
+  \parindent = 0pt
+  \let\indent\nonfillindent
+  %
+  \emergencystretch = 0pt % don't try to avoid overfull boxes
+  \ifx\nonarrowing\relax
+    \advance \leftskip by \lispnarrowing
+    \exdentamount=\lispnarrowing
+  \else
+    \let\nonarrowing = \relax
+  \fi
+  \let\exdent=\nofillexdent
+}
+
+\begingroup
+\obeyspaces
+% We want to swallow spaces (but not other tokens) after the fake
+% @indent in our nonfill-environments, where spaces are normally
+% active and set to @tie, resulting in them not being ignored after
+% @indent.
+\gdef\nonfillindent{\futurelet\temp\nonfillindentcheck}%
+\gdef\nonfillindentcheck{%
+\ifx\temp %
+\expandafter\nonfillindentgobble%
+\else%
+\leavevmode\nonfillindentbox%
+\fi%
+}%
+\endgroup
+\def\nonfillindentgobble#1{\nonfillindent}
+\def\nonfillindentbox{\hbox to \nonfillparindent{\hss}}
+
+% If you want all examples etc. small: @set dispenvsize small.
+% If you want even small examples the full size: @set dispenvsize nosmall.
+% This affects the following displayed environments:
+%    @example, @display, @format, @lisp
+%
+\def\smallword{small}
+\def\nosmallword{nosmall}
+\let\SETdispenvsize\relax
+\def\setnormaldispenv{%
+  \ifx\SETdispenvsize\smallword
+    % end paragraph for sake of leading, in case document has no blank
+    % line.  This is redundant with what happens in \aboveenvbreak, but
+    % we need to do it before changing the fonts, and it's inconvenient
+    % to change the fonts afterward.
+    \ifnum \lastpenalty=10000 \else \endgraf \fi
+    \smallexamplefonts \rm
+  \fi
+}
+\def\setsmalldispenv{%
+  \ifx\SETdispenvsize\nosmallword
+  \else
+    \ifnum \lastpenalty=10000 \else \endgraf \fi
+    \smallexamplefonts \rm
+  \fi
+}
+
+% We often define two environments, @foo and @smallfoo.
+% Let's do it by one command:
+\def\makedispenv #1#2{
+  \expandafter\envdef\csname#1\endcsname {\setnormaldispenv #2}
+  \expandafter\envdef\csname small#1\endcsname {\setsmalldispenv #2}
+  \expandafter\let\csname E#1\endcsname \afterenvbreak
+  \expandafter\let\csname Esmall#1\endcsname \afterenvbreak
+}
+
+% Define two synonyms:
+\def\maketwodispenvs #1#2#3{
+  \makedispenv{#1}{#3}
+  \makedispenv{#2}{#3}
+}
+
+% @lisp: indented, narrowed, typewriter font; @example: same as @lisp.
+%
+% @smallexample and @smalllisp: use smaller fonts.
+% Originally contributed by Pavel@xerox.
+%
+\maketwodispenvs {lisp}{example}{%
+  \nonfillstart
+  \tt\setupmarkupstyle{example}%
+  \let\kbdfont = \kbdexamplefont % Allow @kbd to do something special.
+  \gobble       % eat return
+}
+% @display/@smalldisplay: same as @lisp except keep current font.
+%
+\makedispenv {display}{%
+  \nonfillstart
+  \gobble
+}
+
+% @format/@smallformat: same as @display except don't narrow margins.
+%
+\makedispenv{format}{%
+  \let\nonarrowing = t%
+  \nonfillstart
+  \gobble
+}
+
+% @flushleft: same as @format, but doesn't obey \SETdispenvsize.
+\envdef\flushleft{%
+  \let\nonarrowing = t%
+  \nonfillstart
+  \gobble
+}
+\let\Eflushleft = \afterenvbreak
+
+% @flushright.
+%
+\envdef\flushright{%
+  \let\nonarrowing = t%
+  \nonfillstart
+  \advance\leftskip by 0pt plus 1fill
+  \gobble
+}
+\let\Eflushright = \afterenvbreak
+
+
+% @raggedright does more-or-less normal line breaking but no right
+% justification.  From plain.tex.
+\envdef\raggedright{%
+  \rightskip0pt plus2em \spaceskip.3333em \xspaceskip.5em\relax
+}
+\let\Eraggedright\par
+
+\envdef\raggedleft{%
+  \parindent=0pt \leftskip0pt plus2em
+  \spaceskip.3333em \xspaceskip.5em \parfillskip=0pt
+  \hbadness=10000 % Last line will usually be underfull, so turn off
+                  % badness reporting.
+}
+\let\Eraggedleft\par
+
+\envdef\raggedcenter{%
+  \parindent=0pt \rightskip0pt plus1em \leftskip0pt plus1em
+  \spaceskip.3333em \xspaceskip.5em \parfillskip=0pt
+  \hbadness=10000 % Last line will usually be underfull, so turn off
+                  % badness reporting.
+}
+\let\Eraggedcenter\par
+
+
+% @quotation does normal linebreaking (hence we can't use \nonfillstart)
+% and narrows the margins.  We keep \parskip nonzero in general, since
+% we're doing normal filling.  So, when using \aboveenvbreak and
+% \afterenvbreak, temporarily make \parskip 0.
+%
+\def\quotationstart{%
+  {\parskip=0pt \aboveenvbreak}% because \aboveenvbreak inserts \parskip
+  \parindent=0pt
+  %
+  % @cartouche defines \nonarrowing to inhibit narrowing at next level down.
+  \ifx\nonarrowing\relax
+    \advance\leftskip by \lispnarrowing
+    \advance\rightskip by \lispnarrowing
+    \exdentamount = \lispnarrowing
+  \else
+    \let\nonarrowing = \relax
+  \fi
+  \parsearg\quotationlabel
+}
+
+\envdef\quotation{%
+  \setnormaldispenv
+  \quotationstart
+}
+
+\envdef\smallquotation{%
+  \setsmalldispenv
+  \quotationstart
+}
+\let\Esmallquotation = \Equotation
+
+% We have retained a nonzero parskip for the environment, since we're
+% doing normal filling.
+%
+\def\Equotation{%
+  \par
+  \ifx\quotationauthor\undefined\else
+    % indent a bit.
+    \leftline{\kern 2\leftskip \sl ---\quotationauthor}%
+  \fi
+  {\parskip=0pt \afterenvbreak}%
+}
+
+% If we're given an argument, typeset it in bold with a colon after.
+\def\quotationlabel#1{%
+  \def\temp{#1}%
+  \ifx\temp\empty \else
+    {\bf #1: }%
+  \fi
+}
+
+
+% LaTeX-like @verbatim...@end verbatim and @verb{<char>...<char>}
+% If we want to allow any <char> as delimiter,
+% we need the curly braces so that makeinfo sees the @verb command, eg:
+% `@verbx...x' would look like the '@verbx' command.  --janneke@gnu.org
+%
+% [Knuth]: Donald Ervin Knuth, 1996.  The TeXbook.
+%
+% [Knuth] p.344; only we need to do the other characters Texinfo sets
+% active too.  Otherwise, they get lost as the first character on a
+% verbatim line.
+\def\dospecials{%
+  \do\ \do\\\do\{\do\}\do\$\do\&%
+  \do\#\do\^\do\^^K\do\_\do\^^A\do\%\do\~%
+  \do\<\do\>\do\|\do\@\do+\do\"%
+  % Don't do the quotes -- if we do, @set txicodequoteundirected and
+  % @set txicodequotebacktick will not have effect on @verb and
+  % @verbatim, and ?` and !` ligatures won't get disabled.
+  %\do\`\do\'%
+}
+%
+% [Knuth] p. 380
+\def\uncatcodespecials{%
+  \def\do##1{\catcode`##1=\other}\dospecials}
+%
+% Setup for the @verb command.
+%
+% Eight spaces for a tab
+\begingroup
+  \catcode`\^^I=\active
+  \gdef\tabeightspaces{\catcode`\^^I=\active\def^^I{\ \ \ \ \ \ \ \ }}
+\endgroup
+%
+\def\setupverb{%
+  \tt  % easiest (and conventionally used) font for verbatim
+  \def\par{\leavevmode\endgraf}%
+  \setupmarkupstyle{verb}%
+  \tabeightspaces
+  % Respect line breaks,
+  % print special symbols as themselves, and
+  % make each space count
+  % must do in this order:
+  \obeylines \uncatcodespecials \sepspaces
+}
+
+% Setup for the @verbatim environment
+%
+% Real tab expansion
+\newdimen\tabw \setbox0=\hbox{\tt\space} \tabw=8\wd0 % tab amount
+%
+\def\starttabbox{\setbox0=\hbox\bgroup}
+%
+\begingroup
+  \catcode`\^^I=\active
+  \gdef\tabexpand{%
+    \catcode`\^^I=\active
+    \def^^I{\leavevmode\egroup
+      \dimen0=\wd0 % the width so far, or since the previous tab
+      \divide\dimen0 by\tabw
+      \multiply\dimen0 by\tabw % compute previous multiple of \tabw
+      \advance\dimen0 by\tabw  % advance to next multiple of \tabw
+      \wd0=\dimen0 \box0 \starttabbox
+    }%
+  }
+\endgroup
+
+% start the verbatim environment.
+\def\setupverbatim{%
+  \let\nonarrowing = t%
+  \nonfillstart
+  % Easiest (and conventionally used) font for verbatim
+  \tt
+  \def\par{\leavevmode\egroup\box0\endgraf}%
+  \tabexpand
+  \setupmarkupstyle{verbatim}%
+  % Respect line breaks,
+  % print special symbols as themselves, and
+  % make each space count
+  % must do in this order:
+  \obeylines \uncatcodespecials \sepspaces
+  \everypar{\starttabbox}%
+}
+
+% Do the @verb magic: verbatim text is quoted by unique
+% delimiter characters.  Before first delimiter expect a
+% right brace, after last delimiter expect closing brace:
+%
+%    \def\doverb'{'<char>#1<char>'}'{#1}
+%
+% [Knuth] p. 382; only eat outer {}
+\begingroup
+  \catcode`[=1\catcode`]=2\catcode`\{=\other\catcode`\}=\other
+  \gdef\doverb{#1[\def\next##1#1}[##1\endgroup]\next]
+\endgroup
+%
+\def\verb{\begingroup\setupverb\doverb}
+%
+%
+% Do the @verbatim magic: define the macro \doverbatim so that
+% the (first) argument ends when '@end verbatim' is reached, ie:
+%
+%     \def\doverbatim#1@end verbatim{#1}
+%
+% For Texinfo it's a lot easier than for LaTeX,
+% because texinfo's \verbatim doesn't stop at '\end{verbatim}':
+% we need not redefine '\', '{' and '}'.
+%
+% Inspired by LaTeX's verbatim command set [latex.ltx]
+%
+\begingroup
+  \catcode`\ =\active
+  \obeylines %
+  % ignore everything up to the first ^^M, that's the newline at the end
+  % of the @verbatim input line itself.  Otherwise we get an extra blank
+  % line in the output.
+  \xdef\doverbatim#1^^M#2@end verbatim{#2\noexpand\end\gobble verbatim}%
+  % We really want {...\end verbatim} in the body of the macro, but
+  % without the active space; thus we have to use \xdef and \gobble.
+\endgroup
+%
+\envdef\verbatim{%
+    \setupverbatim\doverbatim
+}
+\let\Everbatim = \afterenvbreak
+
+
+% @verbatiminclude FILE - insert text of file in verbatim environment.
+%
+\def\verbatiminclude{\parseargusing\filenamecatcodes\doverbatiminclude}
+%
+\def\doverbatiminclude#1{%
+  {%
+    \makevalueexpandable
+    \setupverbatim
+    \indexnofonts       % Allow `@@' and other weird things in file names.
+    \input #1
+    \afterenvbreak
+  }%
+}
+
+% @copying ... @end copying.
+% Save the text away for @insertcopying later.
+%
+% We save the uninterpreted tokens, rather than creating a box.
+% Saving the text in a box would be much easier, but then all the
+% typesetting commands (@smallbook, font changes, etc.) have to be done
+% beforehand -- and a) we want @copying to be done first in the source
+% file; b) letting users define the frontmatter in as flexible order as
+% possible is very desirable.
+%
+\def\copying{\checkenv{}\begingroup\scanargctxt\docopying}
+\def\docopying#1@end copying{\endgroup\def\copyingtext{#1}}
+%
+\def\insertcopying{%
+  \begingroup
+    \parindent = 0pt  % paragraph indentation looks wrong on title page
+    \scanexp\copyingtext
+  \endgroup
+}
+
+
+\message{defuns,}
+% @defun etc.
+
+\newskip\defbodyindent \defbodyindent=.4in
+\newskip\defargsindent \defargsindent=50pt
+\newskip\deflastargmargin \deflastargmargin=18pt
+\newcount\defunpenalty
+
+% Start the processing of @deffn:
+\def\startdefun{%
+  \ifnum\lastpenalty<10000
+    \medbreak
+    \defunpenalty=10003 % Will keep this @deffn together with the
+                        % following @def command, see below.
+  \else
+    % If there are two @def commands in a row, we'll have a \nobreak,
+    % which is there to keep the function description together with its
+    % header.  But if there's nothing but headers, we need to allow a
+    % break somewhere.  Check specifically for penalty 10002, inserted
+    % by \printdefunline, instead of 10000, since the sectioning
+    % commands also insert a nobreak penalty, and we don't want to allow
+    % a break between a section heading and a defun.
+    %
+    % As a minor refinement, we avoid "club" headers by signalling
+    % with penalty of 10003 after the very first @deffn in the
+    % sequence (see above), and penalty of 10002 after any following
+    % @def command.
+    \ifnum\lastpenalty=10002 \penalty2000 \else \defunpenalty=10002 \fi
+    %
+    % Similarly, after a section heading, do not allow a break.
+    % But do insert the glue.
+    \medskip  % preceded by discardable penalty, so not a breakpoint
+  \fi
+  %
+  \parindent=0in
+  \advance\leftskip by \defbodyindent
+  \exdentamount=\defbodyindent
+}
+
+\def\dodefunx#1{%
+  % First, check whether we are in the right environment:
+  \checkenv#1%
+  %
+  % As above, allow line break if we have multiple x headers in a row.
+  % It's not a great place, though.
+  \ifnum\lastpenalty=10002 \penalty3000 \else \defunpenalty=10002 \fi
+  %
+  % And now, it's time to reuse the body of the original defun:
+  \expandafter\gobbledefun#1%
+}
+\def\gobbledefun#1\startdefun{}
+
+% \printdefunline \deffnheader{text}
+%
+\def\printdefunline#1#2{%
+  \begingroup
+    % call \deffnheader:
+    #1#2 \endheader
+    % common ending:
+    \interlinepenalty = 10000
+    \advance\rightskip by 0pt plus 1fil
+    \endgraf
+    \nobreak\vskip -\parskip
+    \penalty\defunpenalty  % signal to \startdefun and \dodefunx
+    % Some of the @defun-type tags do not enable magic parentheses,
+    % rendering the following check redundant.  But we don't optimize.
+    \checkparencounts
+  \endgroup
+}
+
+\def\Edefun{\endgraf\medbreak}
+
+% \makedefun{deffn} creates \deffn, \deffnx and \Edeffn;
+% the only thing remaining is to define \deffnheader.
+%
+\def\makedefun#1{%
+  \expandafter\let\csname E#1\endcsname = \Edefun
+  \edef\temp{\noexpand\domakedefun
+    \makecsname{#1}\makecsname{#1x}\makecsname{#1header}}%
+  \temp
+}
+
+% \domakedefun \deffn \deffnx \deffnheader
+%
+% Define \deffn and \deffnx, without parameters.
+% \deffnheader has to be defined explicitly.
+%
+\def\domakedefun#1#2#3{%
+  \envdef#1{%
+    \startdefun
+    \parseargusing\activeparens{\printdefunline#3}%
+  }%
+  \def#2{\dodefunx#1}%
+  \def#3%
+}
+
+%%% Untyped functions:
+
+% @deffn category name args
+\makedefun{deffn}{\deffngeneral{}}
+
+% @deffn category class name args
+\makedefun{defop}#1 {\defopon{#1\ \putwordon}}
+
+% \defopon {category on}class name args
+\def\defopon#1#2 {\deffngeneral{\putwordon\ \code{#2}}{#1\ \code{#2}} }
+
+% \deffngeneral {subind}category name args
+%
+\def\deffngeneral#1#2 #3 #4\endheader{%
+  % Remember that \dosubind{fn}{foo}{} is equivalent to \doind{fn}{foo}.
+  \dosubind{fn}{\code{#3}}{#1}%
+  \defname{#2}{}{#3}\magicamp\defunargs{#4\unskip}%
+}
+
+%%% Typed functions:
+
+% @deftypefn category type name args
+\makedefun{deftypefn}{\deftypefngeneral{}}
+
+% @deftypeop category class type name args
+\makedefun{deftypeop}#1 {\deftypeopon{#1\ \putwordon}}
+
+% \deftypeopon {category on}class type name args
+\def\deftypeopon#1#2 {\deftypefngeneral{\putwordon\ \code{#2}}{#1\ \code{#2}} }
+
+% \deftypefngeneral {subind}category type name args
+%
+\def\deftypefngeneral#1#2 #3 #4 #5\endheader{%
+  \dosubind{fn}{\code{#4}}{#1}%
+  \defname{#2}{#3}{#4}\defunargs{#5\unskip}%
+}
+
+%%% Typed variables:
+
+% @deftypevr category type var args
+\makedefun{deftypevr}{\deftypecvgeneral{}}
+
+% @deftypecv category class type var args
+\makedefun{deftypecv}#1 {\deftypecvof{#1\ \putwordof}}
+
+% \deftypecvof {category of}class type var args
+\def\deftypecvof#1#2 {\deftypecvgeneral{\putwordof\ \code{#2}}{#1\ \code{#2}} }
+
+% \deftypecvgeneral {subind}category type var args
+%
+\def\deftypecvgeneral#1#2 #3 #4 #5\endheader{%
+  \dosubind{vr}{\code{#4}}{#1}%
+  \defname{#2}{#3}{#4}\defunargs{#5\unskip}%
+}
+
+%%% Untyped variables:
+
+% @defvr category var args
+\makedefun{defvr}#1 {\deftypevrheader{#1} {} }
+
+% @defcv category class var args
+\makedefun{defcv}#1 {\defcvof{#1\ \putwordof}}
+
+% \defcvof {category of}class var args
+\def\defcvof#1#2 {\deftypecvof{#1}#2 {} }
+
+%%% Type:
+% @deftp category name args
+\makedefun{deftp}#1 #2 #3\endheader{%
+  \doind{tp}{\code{#2}}%
+  \defname{#1}{}{#2}\defunargs{#3\unskip}%
+}
+
+% Remaining @defun-like shortcuts:
+\makedefun{defun}{\deffnheader{\putwordDeffunc} }
+\makedefun{defmac}{\deffnheader{\putwordDefmac} }
+\makedefun{defspec}{\deffnheader{\putwordDefspec} }
+\makedefun{deftypefun}{\deftypefnheader{\putwordDeffunc} }
+\makedefun{defvar}{\defvrheader{\putwordDefvar} }
+\makedefun{defopt}{\defvrheader{\putwordDefopt} }
+\makedefun{deftypevar}{\deftypevrheader{\putwordDefvar} }
+\makedefun{defmethod}{\defopon\putwordMethodon}
+\makedefun{deftypemethod}{\deftypeopon\putwordMethodon}
+\makedefun{defivar}{\defcvof\putwordInstanceVariableof}
+\makedefun{deftypeivar}{\deftypecvof\putwordInstanceVariableof}
+
+% \defname, which formats the name of the @def (not the args).
+% #1 is the category, such as "Function".
+% #2 is the return type, if any.
+% #3 is the function name.
+%
+% We are followed by (but not passed) the arguments, if any.
+%
+\def\defname#1#2#3{%
+  % Get the values of \leftskip and \rightskip as they were outside the @def...
+  \advance\leftskip by -\defbodyindent
+  %
+  % How we'll format the type name.  Putting it in brackets helps
+  % distinguish it from the body text that may end up on the next line
+  % just below it.
+  \def\temp{#1}%
+  \setbox0=\hbox{\kern\deflastargmargin \ifx\temp\empty\else [\rm\temp]\fi}
+  %
+  % Figure out line sizes for the paragraph shape.
+  % The first line needs space for \box0; but if \rightskip is nonzero,
+  % we need only space for the part of \box0 which exceeds it:
+  \dimen0=\hsize  \advance\dimen0 by -\wd0  \advance\dimen0 by \rightskip
+  % The continuations:
+  \dimen2=\hsize  \advance\dimen2 by -\defargsindent
+  % (plain.tex says that \dimen1 should be used only as global.)
+  \parshape 2 0in \dimen0 \defargsindent \dimen2
+  %
+  % Put the type name to the right margin.
+  \noindent
+  \hbox to 0pt{%
+    \hfil\box0 \kern-\hsize
+    % \hsize has to be shortened this way:
+    \kern\leftskip
+    % Intentionally do not respect \rightskip, since we need the space.
+  }%
+  %
+  % Allow all lines to be underfull without complaint:
+  \tolerance=10000 \hbadness=10000
+  \exdentamount=\defbodyindent
+  {%
+    % defun fonts. We use typewriter by default (used to be bold) because:
+    % . we're printing identifiers, they should be in tt in principle.
+    % . in languages with many accents, such as Czech or French, it's
+    %   common to leave accents off identifiers.  The result looks ok in
+    %   tt, but exceedingly strange in rm.
+    % . we don't want -- and --- to be treated as ligatures.
+    % . this still does not fix the ?` and !` ligatures, but so far no
+    %   one has made identifiers using them :).
+    \df \tt
+    \def\temp{#2}% return value type
+    \ifx\temp\empty\else \tclose{\temp} \fi
+    #3% output function name
+  }%
+  {\rm\enskip}% hskip 0.5 em of \tenrm
+  %
+  \boldbrax
+  % arguments will be output next, if any.
+}
+
+% Print arguments in slanted roman (not ttsl), inconsistently with using
+% tt for the name.  This is because literal text is sometimes needed in
+% the argument list (groff manual), and ttsl and tt are not very
+% distinguishable.  Prevent hyphenation at `-' chars.
+%
+\def\defunargs#1{%
+  % use sl by default (not ttsl),
+  % tt for the names.
+  \df \sl \hyphenchar\font=0
+  %
+  % On the other hand, if an argument has two dashes (for instance), we
+  % want a way to get ttsl.  Let's try @var for that.
+  \def\var##1{{\setupmarkupstyle{var}\ttslanted{##1}}}%
+  #1%
+  \sl\hyphenchar\font=45
+}
+
+% We want ()&[] to print specially on the defun line.
+%
+\def\activeparens{%
+  \catcode`\(=\active \catcode`\)=\active
+  \catcode`\[=\active \catcode`\]=\active
+  \catcode`\&=\active
+}
+
+% Make control sequences which act like normal parenthesis chars.
+\let\lparen = ( \let\rparen = )
+
+% Be sure that we always have a definition for `(', etc.  For example,
+% if the fn name has parens in it, \boldbrax will not be in effect yet,
+% so TeX would otherwise complain about undefined control sequence.
+{
+  \activeparens
+  \global\let(=\lparen \global\let)=\rparen
+  \global\let[=\lbrack \global\let]=\rbrack
+  \global\let& = \&
+
+  \gdef\boldbrax{\let(=\opnr\let)=\clnr\let[=\lbrb\let]=\rbrb}
+  \gdef\magicamp{\let&=\amprm}
+}
+
+\newcount\parencount
+
+% If we encounter &foo, then turn on ()-hacking afterwards
+\newif\ifampseen
+\def\amprm#1 {\ampseentrue{\bf\&#1 }}
+
+\def\parenfont{%
+  \ifampseen
+    % At the first level, print parens in roman,
+    % otherwise use the default font.
+    \ifnum \parencount=1 \rm \fi
+  \else
+    % The \sf parens (in \boldbrax) actually are a little bolder than
+    % the contained text.  This is especially needed for [ and ] .
+    \sf
+  \fi
+}
+\def\infirstlevel#1{%
+  \ifampseen
+    \ifnum\parencount=1
+      #1%
+    \fi
+  \fi
+}
+\def\bfafterword#1 {#1 \bf}
+
+\def\opnr{%
+  \global\advance\parencount by 1
+  {\parenfont(}%
+  \infirstlevel \bfafterword
+}
+\def\clnr{%
+  {\parenfont)}%
+  \infirstlevel \sl
+  \global\advance\parencount by -1
+}
+
+\newcount\brackcount
+\def\lbrb{%
+  \global\advance\brackcount by 1
+  {\bf[}%
+}
+\def\rbrb{%
+  {\bf]}%
+  \global\advance\brackcount by -1
+}
+
+\def\checkparencounts{%
+  \ifnum\parencount=0 \else \badparencount \fi
+  \ifnum\brackcount=0 \else \badbrackcount \fi
+}
+% these should not use \errmessage; the glibc manual, at least, actually
+% has such constructs (when documenting function pointers).
+\def\badparencount{%
+  \message{Warning: unbalanced parentheses in @def...}%
+  \global\parencount=0
+}
+\def\badbrackcount{%
+  \message{Warning: unbalanced square brackets in @def...}%
+  \global\brackcount=0
+}
+
+
+\message{macros,}
+% @macro.
+
+% To do this right we need a feature of e-TeX, \scantokens,
+% which we arrange to emulate with a temporary file in ordinary TeX.
+\ifx\eTeXversion\undefined
+  \newwrite\macscribble
+  \def\scantokens#1{%
+    \toks0={#1}%
+    \immediate\openout\macscribble=\jobname.tmp
+    \immediate\write\macscribble{\the\toks0}%
+    \immediate\closeout\macscribble
+    \input \jobname.tmp
+  }
+\fi
+
+\def\scanmacro#1{%
+  \begingroup
+    \newlinechar`\^^M
+    \let\xeatspaces\eatspaces
+    % Undo catcode changes of \startcontents and \doprintindex
+    % When called from @insertcopying or (short)caption, we need active
+    % backslash to get it printed correctly.  Previously, we had
+    % \catcode`\\=\other instead.  We'll see whether a problem appears
+    % with macro expansion.				--kasal, 19aug04
+    \catcode`\@=0 \catcode`\\=\active \escapechar=`\@
+    % ... and \example
+    \spaceisspace
+    %
+    % Append \endinput to make sure that TeX does not see the ending newline.
+    % I've verified that it is necessary both for e-TeX and for ordinary TeX
+    %							--kasal, 29nov03
+    \scantokens{#1\endinput}%
+  \endgroup
+}
+
+\def\scanexp#1{%
+  \edef\temp{\noexpand\scanmacro{#1}}%
+  \temp
+}
+
+\newcount\paramno   % Count of parameters
+\newtoks\macname    % Macro name
+\newif\ifrecursive  % Is it recursive?
+
+% List of all defined macros in the form
+%    \definedummyword\macro1\definedummyword\macro2...
+% Currently is also contains all @aliases; the list can be split
+% if there is a need.
+\def\macrolist{}
+
+% Add the macro to \macrolist
+\def\addtomacrolist#1{\expandafter \addtomacrolistxxx \csname#1\endcsname}
+\def\addtomacrolistxxx#1{%
+     \toks0 = \expandafter{\macrolist\definedummyword#1}%
+     \xdef\macrolist{\the\toks0}%
+}
+
+% Utility routines.
+% This does \let #1 = #2, with \csnames; that is,
+%   \let \csname#1\endcsname = \csname#2\endcsname
+% (except of course we have to play expansion games).
+%
+\def\cslet#1#2{%
+  \expandafter\let
+  \csname#1\expandafter\endcsname
+  \csname#2\endcsname
+}
+
+% Trim leading and trailing spaces off a string.
+% Concepts from aro-bend problem 15 (see CTAN).
+{\catcode`\@=11
+\gdef\eatspaces #1{\expandafter\trim@\expandafter{#1 }}
+\gdef\trim@ #1{\trim@@ @#1 @ #1 @ @@}
+\gdef\trim@@ #1@ #2@ #3@@{\trim@@@\empty #2 @}
+\def\unbrace#1{#1}
+\unbrace{\gdef\trim@@@ #1 } #2@{#1}
+}
+
+% Trim a single trailing ^^M off a string.
+{\catcode`\^^M=\other \catcode`\Q=3%
+\gdef\eatcr #1{\eatcra #1Q^^MQ}%
+\gdef\eatcra#1^^MQ{\eatcrb#1Q}%
+\gdef\eatcrb#1Q#2Q{#1}%
+}
+
+% Macro bodies are absorbed as an argument in a context where
+% all characters are catcode 10, 11 or 12, except \ which is active
+% (as in normal texinfo). It is necessary to change the definition of \.
+
+% Non-ASCII encodings make 8-bit characters active, so un-activate
+% them to avoid their expansion.  Must do this non-globally, to
+% confine the change to the current group.
+
+% It's necessary to have hard CRs when the macro is executed. This is
+% done by  making ^^M (\endlinechar) catcode 12 when reading the macro
+% body, and then making it the \newlinechar in \scanmacro.
+
+\def\scanctxt{%
+  \catcode`\"=\other
+  \catcode`\+=\other
+  \catcode`\<=\other
+  \catcode`\>=\other
+  \catcode`\@=\other
+  \catcode`\^=\other
+  \catcode`\_=\other
+  \catcode`\|=\other
+  \catcode`\~=\other
+  \ifx\declaredencoding\ascii \else \setnonasciicharscatcodenonglobal\other \fi
+}
+
+\def\scanargctxt{%
+  \scanctxt
+  \catcode`\\=\other
+  \catcode`\^^M=\other
+}
+
+\def\macrobodyctxt{%
+  \scanctxt
+  \catcode`\{=\other
+  \catcode`\}=\other
+  \catcode`\^^M=\other
+  \usembodybackslash
+}
+
+\def\macroargctxt{%
+  \scanctxt
+  \catcode`\\=\other
+}
+
+% \mbodybackslash is the definition of \ in @macro bodies.
+% It maps \foo\ => \csname macarg.foo\endcsname => #N
+% where N is the macro parameter number.
+% We define \csname macarg.\endcsname to be \realbackslash, so
+% \\ in macro replacement text gets you a backslash.
+
+{\catcode`@=0 @catcode`@\=@active
+ @gdef@usembodybackslash{@let\=@mbodybackslash}
+ @gdef@mbodybackslash#1\{@csname macarg.#1@endcsname}
+}
+\expandafter\def\csname macarg.\endcsname{\realbackslash}
+
+\def\macro{\recursivefalse\parsearg\macroxxx}
+\def\rmacro{\recursivetrue\parsearg\macroxxx}
+
+\def\macroxxx#1{%
+  \getargs{#1}%           now \macname is the macname and \argl the arglist
+  \ifx\argl\empty       % no arguments
+     \paramno=0%
+  \else
+     \expandafter\parsemargdef \argl;%
+  \fi
+  \if1\csname ismacro.\the\macname\endcsname
+     \message{Warning: redefining \the\macname}%
+  \else
+     \expandafter\ifx\csname \the\macname\endcsname \relax
+     \else \errmessage{Macro name \the\macname\space already defined}\fi
+     \global\cslet{macsave.\the\macname}{\the\macname}%
+     \global\expandafter\let\csname ismacro.\the\macname\endcsname=1%
+     \addtomacrolist{\the\macname}%
+  \fi
+  \begingroup \macrobodyctxt
+  \ifrecursive \expandafter\parsermacbody
+  \else \expandafter\parsemacbody
+  \fi}
+
+\parseargdef\unmacro{%
+  \if1\csname ismacro.#1\endcsname
+    \global\cslet{#1}{macsave.#1}%
+    \global\expandafter\let \csname ismacro.#1\endcsname=0%
+    % Remove the macro name from \macrolist:
+    \begingroup
+      \expandafter\let\csname#1\endcsname \relax
+      \let\definedummyword\unmacrodo
+      \xdef\macrolist{\macrolist}%
+    \endgroup
+  \else
+    \errmessage{Macro #1 not defined}%
+  \fi
+}
+
+% Called by \do from \dounmacro on each macro.  The idea is to omit any
+% macro definitions that have been changed to \relax.
+%
+\def\unmacrodo#1{%
+  \ifx #1\relax
+    % remove this
+  \else
+    \noexpand\definedummyword \noexpand#1%
+  \fi
+}
+
+% This makes use of the obscure feature that if the last token of a
+% <parameter list> is #, then the preceding argument is delimited by
+% an opening brace, and that opening brace is not consumed.
+\def\getargs#1{\getargsxxx#1{}}
+\def\getargsxxx#1#{\getmacname #1 \relax\getmacargs}
+\def\getmacname #1 #2\relax{\macname={#1}}
+\def\getmacargs#1{\def\argl{#1}}
+
+% Parse the optional {params} list.  Set up \paramno and \paramlist
+% so \defmacro knows what to do.  Define \macarg.blah for each blah
+% in the params list, to be ##N where N is the position in that list.
+% That gets used by \mbodybackslash (above).
+
+% We need to get `macro parameter char #' into several definitions.
+% The technique used is stolen from LaTeX:  let \hash be something
+% unexpandable, insert that wherever you need a #, and then redefine
+% it to # just before using the token list produced.
+%
+% The same technique is used to protect \eatspaces till just before
+% the macro is used.
+
+\def\parsemargdef#1;{\paramno=0\def\paramlist{}%
+        \let\hash\relax\let\xeatspaces\relax\parsemargdefxxx#1,;,}
+\def\parsemargdefxxx#1,{%
+  \if#1;\let\next=\relax
+  \else \let\next=\parsemargdefxxx
+    \advance\paramno by 1%
+    \expandafter\edef\csname macarg.\eatspaces{#1}\endcsname
+        {\xeatspaces{\hash\the\paramno}}%
+    \edef\paramlist{\paramlist\hash\the\paramno,}%
+  \fi\next}
+
+% These two commands read recursive and nonrecursive macro bodies.
+% (They're different since rec and nonrec macros end differently.)
+
+\long\def\parsemacbody#1@end macro%
+{\xdef\temp{\eatcr{#1}}\endgroup\defmacro}%
+\long\def\parsermacbody#1@end rmacro%
+{\xdef\temp{\eatcr{#1}}\endgroup\defmacro}%
+
+% This defines the macro itself. There are six cases: recursive and
+% nonrecursive macros of zero, one, and many arguments.
+% Much magic with \expandafter here.
+% \xdef is used so that macro definitions will survive the file
+% they're defined in; @include reads the file inside a group.
+\def\defmacro{%
+  \let\hash=##% convert placeholders to macro parameter chars
+  \ifrecursive
+    \ifcase\paramno
+    % 0
+      \expandafter\xdef\csname\the\macname\endcsname{%
+        \noexpand\scanmacro{\temp}}%
+    \or % 1
+      \expandafter\xdef\csname\the\macname\endcsname{%
+         \bgroup\noexpand\macroargctxt
+         \noexpand\braceorline
+         \expandafter\noexpand\csname\the\macname xxx\endcsname}%
+      \expandafter\xdef\csname\the\macname xxx\endcsname##1{%
+         \egroup\noexpand\scanmacro{\temp}}%
+    \else % many
+      \expandafter\xdef\csname\the\macname\endcsname{%
+         \bgroup\noexpand\macroargctxt
+         \noexpand\csname\the\macname xx\endcsname}%
+      \expandafter\xdef\csname\the\macname xx\endcsname##1{%
+          \expandafter\noexpand\csname\the\macname xxx\endcsname ##1,}%
+      \expandafter\expandafter
+      \expandafter\xdef
+      \expandafter\expandafter
+        \csname\the\macname xxx\endcsname
+          \paramlist{\egroup\noexpand\scanmacro{\temp}}%
+    \fi
+  \else
+    \ifcase\paramno
+    % 0
+      \expandafter\xdef\csname\the\macname\endcsname{%
+        \noexpand\norecurse{\the\macname}%
+        \noexpand\scanmacro{\temp}\egroup}%
+    \or % 1
+      \expandafter\xdef\csname\the\macname\endcsname{%
+         \bgroup\noexpand\macroargctxt
+         \noexpand\braceorline
+         \expandafter\noexpand\csname\the\macname xxx\endcsname}%
+      \expandafter\xdef\csname\the\macname xxx\endcsname##1{%
+        \egroup
+        \noexpand\norecurse{\the\macname}%
+        \noexpand\scanmacro{\temp}\egroup}%
+    \else % many
+      \expandafter\xdef\csname\the\macname\endcsname{%
+         \bgroup\noexpand\macroargctxt
+         \expandafter\noexpand\csname\the\macname xx\endcsname}%
+      \expandafter\xdef\csname\the\macname xx\endcsname##1{%
+          \expandafter\noexpand\csname\the\macname xxx\endcsname ##1,}%
+      \expandafter\expandafter
+      \expandafter\xdef
+      \expandafter\expandafter
+      \csname\the\macname xxx\endcsname
+      \paramlist{%
+          \egroup
+          \noexpand\norecurse{\the\macname}%
+          \noexpand\scanmacro{\temp}\egroup}%
+    \fi
+  \fi}
+
+\def\norecurse#1{\bgroup\cslet{#1}{macsave.#1}}
+
+% \braceorline decides whether the next nonwhitespace character is a
+% {.  If so it reads up to the closing }, if not, it reads the whole
+% line.  Whatever was read is then fed to the next control sequence
+% as an argument (by \parsebrace or \parsearg)
+\def\braceorline#1{\let\macnamexxx=#1\futurelet\nchar\braceorlinexxx}
+\def\braceorlinexxx{%
+  \ifx\nchar\bgroup\else
+    \expandafter\parsearg
+  \fi \macnamexxx}
+
+
+% @alias.
+% We need some trickery to remove the optional spaces around the equal
+% sign.  Just make them active and then expand them all to nothing.
+\def\alias{\parseargusing\obeyspaces\aliasxxx}
+\def\aliasxxx #1{\aliasyyy#1\relax}
+\def\aliasyyy #1=#2\relax{%
+  {%
+    \expandafter\let\obeyedspace=\empty
+    \addtomacrolist{#1}%
+    \xdef\next{\global\let\makecsname{#1}=\makecsname{#2}}%
+  }%
+  \next
+}
+
+
+\message{cross references,}
+
+\newwrite\auxfile
+\newif\ifhavexrefs    % True if xref values are known.
+\newif\ifwarnedxrefs  % True if we warned once that they aren't known.
+
+% @inforef is relatively simple.
+\def\inforef #1{\inforefzzz #1,,,,**}
+\def\inforefzzz #1,#2,#3,#4**{\putwordSee{} \putwordInfo{} \putwordfile{} \file{\ignorespaces #3{}},
+  node \samp{\ignorespaces#1{}}}
+
+% @node's only job in TeX is to define \lastnode, which is used in
+% cross-references.  The @node line might or might not have commas, and
+% might or might not have spaces before the first comma, like:
+% @node foo , bar , ...
+% We don't want such trailing spaces in the node name.
+%
+\parseargdef\node{\checkenv{}\donode #1 ,\finishnodeparse}
+%
+% also remove a trailing comma, in case of something like this:
+% @node Help-Cross,  ,  , Cross-refs
+\def\donode#1 ,#2\finishnodeparse{\dodonode #1,\finishnodeparse}
+\def\dodonode#1,#2\finishnodeparse{\gdef\lastnode{#1}}
+
+\let\nwnode=\node
+\let\lastnode=\empty
+
+% Write a cross-reference definition for the current node.  #1 is the
+% type (Ynumbered, Yappendix, Ynothing).
+%
+\def\donoderef#1{%
+  \ifx\lastnode\empty\else
+    \setref{\lastnode}{#1}%
+    \global\let\lastnode=\empty
+  \fi
+}
+
+% @anchor{NAME} -- define xref target at arbitrary point.
+%
+\newcount\savesfregister
+%
+\def\savesf{\relax \ifhmode \savesfregister=\spacefactor \fi}
+\def\restoresf{\relax \ifhmode \spacefactor=\savesfregister \fi}
+\def\anchor#1{\savesf \setref{#1}{Ynothing}\restoresf \ignorespaces}
+
+% \setref{NAME}{SNT} defines a cross-reference point NAME (a node or an
+% anchor), which consists of three parts:
+% 1) NAME-title - the current sectioning name taken from \lastsection,
+%                 or the anchor name.
+% 2) NAME-snt   - section number and type, passed as the SNT arg, or
+%                 empty for anchors.
+% 3) NAME-pg    - the page number.
+%
+% This is called from \donoderef, \anchor, and \dofloat.  In the case of
+% floats, there is an additional part, which is not written here:
+% 4) NAME-lof   - the text as it should appear in a @listoffloats.
+%
+\def\setref#1#2{%
+  \pdfmkdest{#1}%
+  \iflinks
+    {%
+      \atdummies  % preserve commands, but don't expand them
+      \edef\writexrdef##1##2{%
+	\write\auxfile{@xrdef{#1-% #1 of \setref, expanded by the \edef
+	  ##1}{##2}}% these are parameters of \writexrdef
+      }%
+      \toks0 = \expandafter{\lastsection}%
+      \immediate \writexrdef{title}{\the\toks0 }%
+      \immediate \writexrdef{snt}{\csname #2\endcsname}% \Ynumbered etc.
+      \safewhatsit{\writexrdef{pg}{\folio}}% will be written later, during \shipout
+    }%
+  \fi
+}
+
+% @xref, @pxref, and @ref generate cross-references.  For \xrefX, #1 is
+% the node name, #2 the name of the Info cross-reference, #3 the printed
+% node name, #4 the name of the Info file, #5 the name of the printed
+% manual.  All but the node name can be omitted.
+%
+\def\pxref#1{\putwordsee{} \xrefX[#1,,,,,,,]}
+\def\xref#1{\putwordSee{} \xrefX[#1,,,,,,,]}
+\def\ref#1{\xrefX[#1,,,,,,,]}
+\def\xrefX[#1,#2,#3,#4,#5,#6]{\begingroup
+  \unsepspaces
+  \def\printedmanual{\ignorespaces #5}%
+  \def\printedrefname{\ignorespaces #3}%
+  \setbox1=\hbox{\printedmanual\unskip}%
+  \setbox0=\hbox{\printedrefname\unskip}%
+  \ifdim \wd0 = 0pt
+    % No printed node name was explicitly given.
+    \expandafter\ifx\csname SETxref-automatic-section-title\endcsname\relax
+      % Use the node name inside the square brackets.
+      \def\printedrefname{\ignorespaces #1}%
+    \else
+      % Use the actual chapter/section title appear inside
+      % the square brackets.  Use the real section title if we have it.
+      \ifdim \wd1 > 0pt
+        % It is in another manual, so we don't have it.
+        \def\printedrefname{\ignorespaces #1}%
+      \else
+        \ifhavexrefs
+          % We know the real title if we have the xref values.
+          \def\printedrefname{\refx{#1-title}{}}%
+        \else
+          % Otherwise just copy the Info node name.
+          \def\printedrefname{\ignorespaces #1}%
+        \fi%
+      \fi
+    \fi
+  \fi
+  %
+  % Make link in pdf output.
+  \ifpdf
+    {\indexnofonts
+     \turnoffactive
+     % This expands tokens, so do it after making catcode changes, so _
+     % etc. don't get their TeX definitions.
+     \getfilename{#4}%
+     %
+     % See comments at \activebackslashdouble.
+     {\activebackslashdouble \xdef\pdfxrefdest{#1}%
+      \backslashparens\pdfxrefdest}%
+     %
+     \leavevmode
+     \startlink attr{/Border [0 0 0]}%
+     \ifnum\filenamelength>0
+       goto file{\the\filename.pdf} name{\pdfxrefdest}%
+     \else
+       goto name{\pdfmkpgn{\pdfxrefdest}}%
+     \fi
+    }%
+    \setcolor{\linkcolor}%
+  \fi
+  %
+  % Float references are printed completely differently: "Figure 1.2"
+  % instead of "[somenode], p.3".  We distinguish them by the
+  % LABEL-title being set to a magic string.
+  {%
+    % Have to otherify everything special to allow the \csname to
+    % include an _ in the xref name, etc.
+    \indexnofonts
+    \turnoffactive
+    \expandafter\global\expandafter\let\expandafter\Xthisreftitle
+      \csname XR#1-title\endcsname
+  }%
+  \iffloat\Xthisreftitle
+    % If the user specified the print name (third arg) to the ref,
+    % print it instead of our usual "Figure 1.2".
+    \ifdim\wd0 = 0pt
+      \refx{#1-snt}{}%
+    \else
+      \printedrefname
+    \fi
+    %
+    % if the user also gave the printed manual name (fifth arg), append
+    % "in MANUALNAME".
+    \ifdim \wd1 > 0pt
+      \space \putwordin{} \cite{\printedmanual}%
+    \fi
+  \else
+    % node/anchor (non-float) references.
+    %
+    % If we use \unhbox0 and \unhbox1 to print the node names, TeX does not
+    % insert empty discretionaries after hyphens, which means that it will
+    % not find a line break at a hyphen in a node names.  Since some manuals
+    % are best written with fairly long node names, containing hyphens, this
+    % is a loss.  Therefore, we give the text of the node name again, so it
+    % is as if TeX is seeing it for the first time.
+    \ifdim \wd1 > 0pt
+      \putwordSection{} ``\printedrefname'' \putwordin{} \cite{\printedmanual}%
+    \else
+      % _ (for example) has to be the character _ for the purposes of the
+      % control sequence corresponding to the node, but it has to expand
+      % into the usual \leavevmode...\vrule stuff for purposes of
+      % printing. So we \turnoffactive for the \refx-snt, back on for the
+      % printing, back off for the \refx-pg.
+      {\turnoffactive
+       % Only output a following space if the -snt ref is nonempty; for
+       % @unnumbered and @anchor, it won't be.
+       \setbox2 = \hbox{\ignorespaces \refx{#1-snt}{}}%
+       \ifdim \wd2 > 0pt \refx{#1-snt}\space\fi
+      }%
+      % output the `[mynode]' via a macro so it can be overridden.
+      \xrefprintnodename\printedrefname
+      %
+      % But we always want a comma and a space:
+      ,\space
+      %
+      % output the `page 3'.
+      \turnoffactive \putwordpage\tie\refx{#1-pg}{}%
+    \fi
+  \fi
+  \endlink
+\endgroup}
+
+% This macro is called from \xrefX for the `[nodename]' part of xref
+% output.  It's a separate macro only so it can be changed more easily,
+% since square brackets don't work well in some documents.  Particularly
+% one that Bob is working on :).
+%
+\def\xrefprintnodename#1{[#1]}
+
+% Things referred to by \setref.
+%
+\def\Ynothing{}
+\def\Yomitfromtoc{}
+\def\Ynumbered{%
+  \ifnum\secno=0
+    \putwordChapter@tie \the\chapno
+  \else \ifnum\subsecno=0
+    \putwordSection@tie \the\chapno.\the\secno
+  \else \ifnum\subsubsecno=0
+    \putwordSection@tie \the\chapno.\the\secno.\the\subsecno
+  \else
+    \putwordSection@tie \the\chapno.\the\secno.\the\subsecno.\the\subsubsecno
+  \fi\fi\fi
+}
+\def\Yappendix{%
+  \ifnum\secno=0
+     \putwordAppendix@tie @char\the\appendixno{}%
+  \else \ifnum\subsecno=0
+     \putwordSection@tie @char\the\appendixno.\the\secno
+  \else \ifnum\subsubsecno=0
+    \putwordSection@tie @char\the\appendixno.\the\secno.\the\subsecno
+  \else
+    \putwordSection@tie
+      @char\the\appendixno.\the\secno.\the\subsecno.\the\subsubsecno
+  \fi\fi\fi
+}
+
+% Define \refx{NAME}{SUFFIX} to reference a cross-reference string named NAME.
+% If its value is nonempty, SUFFIX is output afterward.
+%
+\def\refx#1#2{%
+  {%
+    \indexnofonts
+    \otherbackslash
+    \expandafter\global\expandafter\let\expandafter\thisrefX
+      \csname XR#1\endcsname
+  }%
+  \ifx\thisrefX\relax
+    % If not defined, say something at least.
+    \angleleft un\-de\-fined\angleright
+    \iflinks
+      \ifhavexrefs
+        \message{\linenumber Undefined cross reference `#1'.}%
+      \else
+        \ifwarnedxrefs\else
+          \global\warnedxrefstrue
+          \message{Cross reference values unknown; you must run TeX again.}%
+        \fi
+      \fi
+    \fi
+  \else
+    % It's defined, so just use it.
+    \thisrefX
+  \fi
+  #2% Output the suffix in any case.
+}
+
+% This is the macro invoked by entries in the aux file.  Usually it's
+% just a \def (we prepend XR to the control sequence name to avoid
+% collisions).  But if this is a float type, we have more work to do.
+%
+\def\xrdef#1#2{%
+  {% The node name might contain 8-bit characters, which in our current
+   % implementation are changed to commands like @'e.  Don't let these
+   % mess up the control sequence name.
+    \indexnofonts
+    \turnoffactive
+    \xdef\safexrefname{#1}%
+  }%
+  %
+  \expandafter\gdef\csname XR\safexrefname\endcsname{#2}% remember this xref
+  %
+  % Was that xref control sequence that we just defined for a float?
+  \expandafter\iffloat\csname XR\safexrefname\endcsname
+    % it was a float, and we have the (safe) float type in \iffloattype.
+    \expandafter\let\expandafter\floatlist
+      \csname floatlist\iffloattype\endcsname
+    %
+    % Is this the first time we've seen this float type?
+    \expandafter\ifx\floatlist\relax
+      \toks0 = {\do}% yes, so just \do
+    \else
+      % had it before, so preserve previous elements in list.
+      \toks0 = \expandafter{\floatlist\do}%
+    \fi
+    %
+    % Remember this xref in the control sequence \floatlistFLOATTYPE,
+    % for later use in \listoffloats.
+    \expandafter\xdef\csname floatlist\iffloattype\endcsname{\the\toks0
+      {\safexrefname}}%
+  \fi
+}
+
+% Read the last existing aux file, if any.  No error if none exists.
+%
+\def\tryauxfile{%
+  \openin 1 \jobname.aux
+  \ifeof 1 \else
+    \readdatafile{aux}%
+    \global\havexrefstrue
+  \fi
+  \closein 1
+}
+
+\def\setupdatafile{%
+  \catcode`\^^@=\other
+  \catcode`\^^A=\other
+  \catcode`\^^B=\other
+  \catcode`\^^C=\other
+  \catcode`\^^D=\other
+  \catcode`\^^E=\other
+  \catcode`\^^F=\other
+  \catcode`\^^G=\other
+  \catcode`\^^H=\other
+  \catcode`\^^K=\other
+  \catcode`\^^L=\other
+  \catcode`\^^N=\other
+  \catcode`\^^P=\other
+  \catcode`\^^Q=\other
+  \catcode`\^^R=\other
+  \catcode`\^^S=\other
+  \catcode`\^^T=\other
+  \catcode`\^^U=\other
+  \catcode`\^^V=\other
+  \catcode`\^^W=\other
+  \catcode`\^^X=\other
+  \catcode`\^^Z=\other
+  \catcode`\^^[=\other
+  \catcode`\^^\=\other
+  \catcode`\^^]=\other
+  \catcode`\^^^=\other
+  \catcode`\^^_=\other
+  % It was suggested to set the catcode of ^ to 7, which would allow ^^e4 etc.
+  % in xref tags, i.e., node names.  But since ^^e4 notation isn't
+  % supported in the main text, it doesn't seem desirable.  Furthermore,
+  % that is not enough: for node names that actually contain a ^
+  % character, we would end up writing a line like this: 'xrdef {'hat
+  % b-title}{'hat b} and \xrdef does a \csname...\endcsname on the first
+  % argument, and \hat is not an expandable control sequence.  It could
+  % all be worked out, but why?  Either we support ^^ or we don't.
+  %
+  % The other change necessary for this was to define \auxhat:
+  % \def\auxhat{\def^{'hat }}% extra space so ok if followed by letter
+  % and then to call \auxhat in \setq.
+  %
+  \catcode`\^=\other
+  %
+  % Special characters.  Should be turned off anyway, but...
+  \catcode`\~=\other
+  \catcode`\[=\other
+  \catcode`\]=\other
+  \catcode`\"=\other
+  \catcode`\_=\other
+  \catcode`\|=\other
+  \catcode`\<=\other
+  \catcode`\>=\other
+  \catcode`\$=\other
+  \catcode`\#=\other
+  \catcode`\&=\other
+  \catcode`\%=\other
+  \catcode`+=\other % avoid \+ for paranoia even though we've turned it off
+  %
+  % This is to support \ in node names and titles, since the \
+  % characters end up in a \csname.  It's easier than
+  % leaving it active and making its active definition an actual \
+  % character.  What I don't understand is why it works in the *value*
+  % of the xrdef.  Seems like it should be a catcode12 \, and that
+  % should not typeset properly.  But it works, so I'm moving on for
+  % now.  --karl, 15jan04.
+  \catcode`\\=\other
+  %
+  % Make the characters 128-255 be printing characters.
+  {%
+    \count1=128
+    \def\loop{%
+      \catcode\count1=\other
+      \advance\count1 by 1
+      \ifnum \count1<256 \loop \fi
+    }%
+  }%
+  %
+  % @ is our escape character in .aux files, and we need braces.
+  \catcode`\{=1
+  \catcode`\}=2
+  \catcode`\@=0
+}
+
+\def\readdatafile#1{%
+\begingroup
+  \setupdatafile
+  \input\jobname.#1
+\endgroup}
+
+
+\message{insertions,}
+% including footnotes.
+
+\newcount \footnoteno
+
+% The trailing space in the following definition for supereject is
+% vital for proper filling; pages come out unaligned when you do a
+% pagealignmacro call if that space before the closing brace is
+% removed. (Generally, numeric constants should always be followed by a
+% space to prevent strange expansion errors.)
+\def\supereject{\par\penalty -20000\footnoteno =0 }
+
+% @footnotestyle is meaningful for info output only.
+\let\footnotestyle=\comment
+
+{\catcode `\@=11
+%
+% Auto-number footnotes.  Otherwise like plain.
+\gdef\footnote{%
+  \let\indent=\ptexindent
+  \let\noindent=\ptexnoindent
+  \global\advance\footnoteno by \@ne
+  \edef\thisfootno{$^{\the\footnoteno}$}%
+  %
+  % In case the footnote comes at the end of a sentence, preserve the
+  % extra spacing after we do the footnote number.
+  \let\@sf\empty
+  \ifhmode\edef\@sf{\spacefactor\the\spacefactor}\ptexslash\fi
+  %
+  % Remove inadvertent blank space before typesetting the footnote number.
+  \unskip
+  \thisfootno\@sf
+  \dofootnote
+}%
+
+% Don't bother with the trickery in plain.tex to not require the
+% footnote text as a parameter.  Our footnotes don't need to be so general.
+%
+% Oh yes, they do; otherwise, @ifset (and anything else that uses
+% \parseargline) fails inside footnotes because the tokens are fixed when
+% the footnote is read.  --karl, 16nov96.
+%
+\gdef\dofootnote{%
+  \insert\footins\bgroup
+  % We want to typeset this text as a normal paragraph, even if the
+  % footnote reference occurs in (for example) a display environment.
+  % So reset some parameters.
+  \hsize=\pagewidth
+  \interlinepenalty\interfootnotelinepenalty
+  \splittopskip\ht\strutbox % top baseline for broken footnotes
+  \splitmaxdepth\dp\strutbox
+  \floatingpenalty\@MM
+  \leftskip\z@skip
+  \rightskip\z@skip
+  \spaceskip\z@skip
+  \xspaceskip\z@skip
+  \parindent\defaultparindent
+  %
+  \smallfonts \rm
+  %
+  % Because we use hanging indentation in footnotes, a @noindent appears
+  % to exdent this text, so make it be a no-op.  makeinfo does not use
+  % hanging indentation so @noindent can still be needed within footnote
+  % text after an @example or the like (not that this is good style).
+  \let\noindent = \relax
+  %
+  % Hang the footnote text off the number.  Use \everypar in case the
+  % footnote extends for more than one paragraph.
+  \everypar = {\hang}%
+  \textindent{\thisfootno}%
+  %
+  % Don't crash into the line above the footnote text.  Since this
+  % expands into a box, it must come within the paragraph, lest it
+  % provide a place where TeX can split the footnote.
+  \footstrut
+  \futurelet\next\fo@t
+}
+}%end \catcode `\@=11
+
+% In case a @footnote appears in a vbox, save the footnote text and create
+% the real \insert just after the vbox finished.  Otherwise, the insertion
+% would be lost.
+% Similarly, if a @footnote appears inside an alignment, save the footnote
+% text to a box and make the \insert when a row of the table is finished.
+% And the same can be done for other insert classes.  --kasal, 16nov03.
+
+% Replace the \insert primitive by a cheating macro.
+% Deeper inside, just make sure that the saved insertions are not spilled
+% out prematurely.
+%
+\def\startsavinginserts{%
+  \ifx \insert\ptexinsert
+    \let\insert\saveinsert
+  \else
+    \let\checkinserts\relax
+  \fi
+}
+
+% This \insert replacement works for both \insert\footins{foo} and
+% \insert\footins\bgroup foo\egroup, but it doesn't work for \insert27{foo}.
+%
+\def\saveinsert#1{%
+  \edef\next{\noexpand\savetobox \makeSAVEname#1}%
+  \afterassignment\next
+  % swallow the left brace
+  \let\temp =
+}
+\def\makeSAVEname#1{\makecsname{SAVE\expandafter\gobble\string#1}}
+\def\savetobox#1{\global\setbox#1 = \vbox\bgroup \unvbox#1}
+
+\def\checksaveins#1{\ifvoid#1\else \placesaveins#1\fi}
+
+\def\placesaveins#1{%
+  \ptexinsert \csname\expandafter\gobblesave\string#1\endcsname
+    {\box#1}%
+}
+
+% eat @SAVE -- beware, all of them have catcode \other:
+{
+  \def\dospecials{\do S\do A\do V\do E} \uncatcodespecials  %  ;-)
+  \gdef\gobblesave @SAVE{}
+}
+
+% initialization:
+\def\newsaveins #1{%
+  \edef\next{\noexpand\newsaveinsX \makeSAVEname#1}%
+  \next
+}
+\def\newsaveinsX #1{%
+  \csname newbox\endcsname #1%
+  \expandafter\def\expandafter\checkinserts\expandafter{\checkinserts
+    \checksaveins #1}%
+}
+
+% initialize:
+\let\checkinserts\empty
+\newsaveins\footins
+\newsaveins\margin
+
+
+% @image.  We use the macros from epsf.tex to support this.
+% If epsf.tex is not installed and @image is used, we complain.
+%
+% Check for and read epsf.tex up front.  If we read it only at @image
+% time, we might be inside a group, and then its definitions would get
+% undone and the next image would fail.
+\openin 1 = epsf.tex
+\ifeof 1 \else
+  % Do not bother showing banner with epsf.tex v2.7k (available in
+  % doc/epsf.tex and on ctan).
+  \def\epsfannounce{\toks0 = }%
+  \input epsf.tex
+\fi
+\closein 1
+%
+% We will only complain once about lack of epsf.tex.
+\newif\ifwarnednoepsf
+\newhelp\noepsfhelp{epsf.tex must be installed for images to
+  work.  It is also included in the Texinfo distribution, or you can get
+  it from ftp://tug.org/tex/epsf.tex.}
+%
+\def\image#1{%
+  \ifx\epsfbox\undefined
+    \ifwarnednoepsf \else
+      \errhelp = \noepsfhelp
+      \errmessage{epsf.tex not found, images will be ignored}%
+      \global\warnednoepsftrue
+    \fi
+  \else
+    \imagexxx #1,,,,,\finish
+  \fi
+}
+%
+% Arguments to @image:
+% #1 is (mandatory) image filename; we tack on .eps extension.
+% #2 is (optional) width, #3 is (optional) height.
+% #4 is (ignored optional) html alt text.
+% #5 is (ignored optional) extension.
+% #6 is just the usual extra ignored arg for parsing this stuff.
+\newif\ifimagevmode
+\def\imagexxx#1,#2,#3,#4,#5,#6\finish{\begingroup
+  \catcode`\^^M = 5     % in case we're inside an example
+  \normalturnoffactive  % allow _ et al. in names
+  % If the image is by itself, center it.
+  \ifvmode
+    \imagevmodetrue
+    \nobreak\medskip
+    % Usually we'll have text after the image which will insert
+    % \parskip glue, so insert it here too to equalize the space
+    % above and below.
+    \nobreak\vskip\parskip
+    \nobreak
+  \fi
+  %
+  % Leave vertical mode so that indentation from an enclosing
+  % environment such as @quotation is respected.  On the other hand, if
+  % it's at the top level, we don't want the normal paragraph indentation.
+  \noindent
+  %
+  % Output the image.
+  \ifpdf
+    \dopdfimage{#1}{#2}{#3}%
+  \else
+    % \epsfbox itself resets \epsf?size at each figure.
+    \setbox0 = \hbox{\ignorespaces #2}\ifdim\wd0 > 0pt \epsfxsize=#2\relax \fi
+    \setbox0 = \hbox{\ignorespaces #3}\ifdim\wd0 > 0pt \epsfysize=#3\relax \fi
+    \epsfbox{#1.eps}%
+  \fi
+  %
+  \ifimagevmode \medskip \fi  % space after the standalone image
+\endgroup}
+
+
+% @float FLOATTYPE,LABEL,LOC ... @end float for displayed figures, tables,
+% etc.  We don't actually implement floating yet, we always include the
+% float "here".  But it seemed the best name for the future.
+%
+\envparseargdef\float{\eatcommaspace\eatcommaspace\dofloat#1, , ,\finish}
+
+% There may be a space before second and/or third parameter; delete it.
+\def\eatcommaspace#1, {#1,}
+
+% #1 is the optional FLOATTYPE, the text label for this float, typically
+% "Figure", "Table", "Example", etc.  Can't contain commas.  If omitted,
+% this float will not be numbered and cannot be referred to.
+%
+% #2 is the optional xref label.  Also must be present for the float to
+% be referable.
+%
+% #3 is the optional positioning argument; for now, it is ignored.  It
+% will somehow specify the positions allowed to float to (here, top, bottom).
+%
+% We keep a separate counter for each FLOATTYPE, which we reset at each
+% chapter-level command.
+\let\resetallfloatnos=\empty
+%
+\def\dofloat#1,#2,#3,#4\finish{%
+  \let\thiscaption=\empty
+  \let\thisshortcaption=\empty
+  %
+  % don't lose footnotes inside @float.
+  %
+  % BEWARE: when the floats start float, we have to issue warning whenever an
+  % insert appears inside a float which could possibly float. --kasal, 26may04
+  %
+  \startsavinginserts
+  %
+  % We can't be used inside a paragraph.
+  \par
+  %
+  \vtop\bgroup
+    \def\floattype{#1}%
+    \def\floatlabel{#2}%
+    \def\floatloc{#3}% we do nothing with this yet.
+    %
+    \ifx\floattype\empty
+      \let\safefloattype=\empty
+    \else
+      {%
+        % the floattype might have accents or other special characters,
+        % but we need to use it in a control sequence name.
+        \indexnofonts
+        \turnoffactive
+        \xdef\safefloattype{\floattype}%
+      }%
+    \fi
+    %
+    % If label is given but no type, we handle that as the empty type.
+    \ifx\floatlabel\empty \else
+      % We want each FLOATTYPE to be numbered separately (Figure 1,
+      % Table 1, Figure 2, ...).  (And if no label, no number.)
+      %
+      \expandafter\getfloatno\csname\safefloattype floatno\endcsname
+      \global\advance\floatno by 1
+      %
+      {%
+        % This magic value for \lastsection is output by \setref as the
+        % XREFLABEL-title value.  \xrefX uses it to distinguish float
+        % labels (which have a completely different output format) from
+        % node and anchor labels.  And \xrdef uses it to construct the
+        % lists of floats.
+        %
+        \edef\lastsection{\floatmagic=\safefloattype}%
+        \setref{\floatlabel}{Yfloat}%
+      }%
+    \fi
+    %
+    % start with \parskip glue, I guess.
+    \vskip\parskip
+    %
+    % Don't suppress indentation if a float happens to start a section.
+    \restorefirstparagraphindent
+}
+
+% we have these possibilities:
+% @float Foo,lbl & @caption{Cap}: Foo 1.1: Cap
+% @float Foo,lbl & no caption:    Foo 1.1
+% @float Foo & @caption{Cap}:     Foo: Cap
+% @float Foo & no caption:        Foo
+% @float ,lbl & Caption{Cap}:     1.1: Cap
+% @float ,lbl & no caption:       1.1
+% @float & @caption{Cap}:         Cap
+% @float & no caption:
+%
+\def\Efloat{%
+    \let\floatident = \empty
+    %
+    % In all cases, if we have a float type, it comes first.
+    \ifx\floattype\empty \else \def\floatident{\floattype}\fi
+    %
+    % If we have an xref label, the number comes next.
+    \ifx\floatlabel\empty \else
+      \ifx\floattype\empty \else % if also had float type, need tie first.
+        \appendtomacro\floatident{\tie}%
+      \fi
+      % the number.
+      \appendtomacro\floatident{\chaplevelprefix\the\floatno}%
+    \fi
+    %
+    % Start the printed caption with what we've constructed in
+    % \floatident, but keep it separate; we need \floatident again.
+    \let\captionline = \floatident
+    %
+    \ifx\thiscaption\empty \else
+      \ifx\floatident\empty \else
+	\appendtomacro\captionline{: }% had ident, so need a colon between
+      \fi
+      %
+      % caption text.
+      \appendtomacro\captionline{\scanexp\thiscaption}%
+    \fi
+    %
+    % If we have anything to print, print it, with space before.
+    % Eventually this needs to become an \insert.
+    \ifx\captionline\empty \else
+      \vskip.5\parskip
+      \captionline
+      %
+      % Space below caption.
+      \vskip\parskip
+    \fi
+    %
+    % If have an xref label, write the list of floats info.  Do this
+    % after the caption, to avoid chance of it being a breakpoint.
+    \ifx\floatlabel\empty \else
+      % Write the text that goes in the lof to the aux file as
+      % \floatlabel-lof.  Besides \floatident, we include the short
+      % caption if specified, else the full caption if specified, else nothing.
+      {%
+        \atdummies
+        %
+        % since we read the caption text in the macro world, where ^^M
+        % is turned into a normal character, we have to scan it back, so
+        % we don't write the literal three characters "^^M" into the aux file.
+	\scanexp{%
+	  \xdef\noexpand\gtemp{%
+	    \ifx\thisshortcaption\empty
+	      \thiscaption
+	    \else
+	      \thisshortcaption
+	    \fi
+	  }%
+	}%
+        \immediate\write\auxfile{@xrdef{\floatlabel-lof}{\floatident
+	  \ifx\gtemp\empty \else : \gtemp \fi}}%
+      }%
+    \fi
+  \egroup  % end of \vtop
+  %
+  % place the captured inserts
+  %
+  % BEWARE: when the floats start floating, we have to issue warning
+  % whenever an insert appears inside a float which could possibly
+  % float. --kasal, 26may04
+  %
+  \checkinserts
+}
+
+% Append the tokens #2 to the definition of macro #1, not expanding either.
+%
+\def\appendtomacro#1#2{%
+  \expandafter\def\expandafter#1\expandafter{#1#2}%
+}
+
+% @caption, @shortcaption
+%
+\def\caption{\docaption\thiscaption}
+\def\shortcaption{\docaption\thisshortcaption}
+\def\docaption{\checkenv\float \bgroup\scanargctxt\defcaption}
+\def\defcaption#1#2{\egroup \def#1{#2}}
+
+% The parameter is the control sequence identifying the counter we are
+% going to use.  Create it if it doesn't exist and assign it to \floatno.
+\def\getfloatno#1{%
+  \ifx#1\relax
+      % Haven't seen this figure type before.
+      \csname newcount\endcsname #1%
+      %
+      % Remember to reset this floatno at the next chap.
+      \expandafter\gdef\expandafter\resetallfloatnos
+        \expandafter{\resetallfloatnos #1=0 }%
+  \fi
+  \let\floatno#1%
+}
+
+% \setref calls this to get the XREFLABEL-snt value.  We want an @xref
+% to the FLOATLABEL to expand to "Figure 3.1".  We call \setref when we
+% first read the @float command.
+%
+\def\Yfloat{\floattype@tie \chaplevelprefix\the\floatno}%
+
+% Magic string used for the XREFLABEL-title value, so \xrefX can
+% distinguish floats from other xref types.
+\def\floatmagic{!!float!!}
+
+% #1 is the control sequence we are passed; we expand into a conditional
+% which is true if #1 represents a float ref.  That is, the magic
+% \lastsection value which we \setref above.
+%
+\def\iffloat#1{\expandafter\doiffloat#1==\finish}
+%
+% #1 is (maybe) the \floatmagic string.  If so, #2 will be the
+% (safe) float type for this float.  We set \iffloattype to #2.
+%
+\def\doiffloat#1=#2=#3\finish{%
+  \def\temp{#1}%
+  \def\iffloattype{#2}%
+  \ifx\temp\floatmagic
+}
+
+% @listoffloats FLOATTYPE - print a list of floats like a table of contents.
+%
+\parseargdef\listoffloats{%
+  \def\floattype{#1}% floattype
+  {%
+    % the floattype might have accents or other special characters,
+    % but we need to use it in a control sequence name.
+    \indexnofonts
+    \turnoffactive
+    \xdef\safefloattype{\floattype}%
+  }%
+  %
+  % \xrdef saves the floats as a \do-list in \floatlistSAFEFLOATTYPE.
+  \expandafter\ifx\csname floatlist\safefloattype\endcsname \relax
+    \ifhavexrefs
+      % if the user said @listoffloats foo but never @float foo.
+      \message{\linenumber No `\safefloattype' floats to list.}%
+    \fi
+  \else
+    \begingroup
+      \leftskip=\tocindent  % indent these entries like a toc
+      \let\do=\listoffloatsdo
+      \csname floatlist\safefloattype\endcsname
+    \endgroup
+  \fi
+}
+
+% This is called on each entry in a list of floats.  We're passed the
+% xref label, in the form LABEL-title, which is how we save it in the
+% aux file.  We strip off the -title and look up \XRLABEL-lof, which
+% has the text we're supposed to typeset here.
+%
+% Figures without xref labels will not be included in the list (since
+% they won't appear in the aux file).
+%
+\def\listoffloatsdo#1{\listoffloatsdoentry#1\finish}
+\def\listoffloatsdoentry#1-title\finish{{%
+  % Can't fully expand XR#1-lof because it can contain anything.  Just
+  % pass the control sequence.  On the other hand, XR#1-pg is just the
+  % page number, and we want to fully expand that so we can get a link
+  % in pdf output.
+  \toksA = \expandafter{\csname XR#1-lof\endcsname}%
+  %
+  % use the same \entry macro we use to generate the TOC and index.
+  \edef\writeentry{\noexpand\entry{\the\toksA}{\csname XR#1-pg\endcsname}}%
+  \writeentry
+}}
+
+
+\message{localization,}
+
+% For single-language documents, @documentlanguage is usually given very
+% early, just after @documentencoding.  Single argument is the language
+% (de) or locale (de_DE) abbreviation.
+%
+{
+  \catcode`\_ = \active
+  \globaldefs=1
+\parseargdef\documentlanguage{\begingroup
+  \let_=\normalunderscore  % normal _ character for filenames
+  \tex % read txi-??.tex file in plain TeX.
+    % Read the file by the name they passed if it exists.
+    \openin 1 txi-#1.tex
+    \ifeof 1
+      \documentlanguagetrywithoutunderscore{#1_\finish}%
+    \else
+      \globaldefs = 1  % everything in the txi-LL files needs to persist
+      \input txi-#1.tex
+    \fi
+    \closein 1
+  \endgroup % end raw TeX
+\endgroup}
+%
+% If they passed de_DE, and txi-de_DE.tex doesn't exist,
+% try txi-de.tex.
+%
+\gdef\documentlanguagetrywithoutunderscore#1_#2\finish{%
+  \openin 1 txi-#1.tex
+  \ifeof 1
+    \errhelp = \nolanghelp
+    \errmessage{Cannot read language file txi-#1.tex}%
+  \else
+    \globaldefs = 1  % everything in the txi-LL files needs to persist
+    \input txi-#1.tex
+  \fi
+  \closein 1
+}
+}% end of special _ catcode
+%
+\newhelp\nolanghelp{The given language definition file cannot be found or
+is empty.  Maybe you need to install it?  Putting it in the current
+directory should work if nowhere else does.}
+
+% This macro is called from txi-??.tex files; the first argument is the
+% \language name to set (without the "\lang@" prefix), the second and
+% third args are \{left,right}hyphenmin.
+%
+% The language names to pass are determined when the format is built.
+% See the etex.log file created at that time, e.g.,
+% /usr/local/texlive/2008/texmf-var/web2c/pdftex/etex.log.
+%
+% With TeX Live 2008, etex now includes hyphenation patterns for all
+% available languages.  This means we can support hyphenation in
+% Texinfo, at least to some extent.  (This still doesn't solve the
+% accented characters problem.)
+%
+\catcode`@=11
+\def\txisetlanguage#1#2#3{%
+  % do not set the language if the name is undefined in the current TeX.
+  \expandafter\ifx\csname lang@#1\endcsname \relax
+    \message{no patterns for #1}%
+  \else
+    \global\language = \csname lang@#1\endcsname
+  \fi
+  % but there is no harm in adjusting the hyphenmin values regardless.
+  \global\lefthyphenmin = #2\relax
+  \global\righthyphenmin = #3\relax
+}
+
+% Helpers for encodings.
+% Set the catcode of characters 128 through 255 to the specified number.
+%
+\def\setnonasciicharscatcode#1{%
+   \count255=128
+   \loop\ifnum\count255<256
+      \global\catcode\count255=#1\relax
+      \advance\count255 by 1
+   \repeat
+}
+
+\def\setnonasciicharscatcodenonglobal#1{%
+   \count255=128
+   \loop\ifnum\count255<256
+      \catcode\count255=#1\relax
+      \advance\count255 by 1
+   \repeat
+}
+
+% @documentencoding sets the definition of non-ASCII characters
+% according to the specified encoding.
+%
+\parseargdef\documentencoding{%
+  % Encoding being declared for the document.
+  \def\declaredencoding{\csname #1.enc\endcsname}%
+  %
+  % Supported encodings: names converted to tokens in order to be able
+  % to compare them with \ifx.
+  \def\ascii{\csname US-ASCII.enc\endcsname}%
+  \def\latnine{\csname ISO-8859-15.enc\endcsname}%
+  \def\latone{\csname ISO-8859-1.enc\endcsname}%
+  \def\lattwo{\csname ISO-8859-2.enc\endcsname}%
+  \def\utfeight{\csname UTF-8.enc\endcsname}%
+  %
+  \ifx \declaredencoding \ascii
+     \asciichardefs
+  %
+  \else \ifx \declaredencoding \lattwo
+     \setnonasciicharscatcode\active
+     \lattwochardefs
+  %
+  \else \ifx \declaredencoding \latone
+     \setnonasciicharscatcode\active
+     \latonechardefs
+  %
+  \else \ifx \declaredencoding \latnine
+     \setnonasciicharscatcode\active
+     \latninechardefs
+  %
+  \else \ifx \declaredencoding \utfeight
+     \setnonasciicharscatcode\active
+     \utfeightchardefs
+  %
+  \else
+    \message{Unknown document encoding #1, ignoring.}%
+  %
+  \fi % utfeight
+  \fi % latnine
+  \fi % latone
+  \fi % lattwo
+  \fi % ascii
+}
+
+% A message to be logged when using a character that isn't available
+% the default font encoding (OT1).
+%
+\def\missingcharmsg#1{\message{Character missing in OT1 encoding: #1.}}
+
+% Take account of \c (plain) vs. \, (Texinfo) difference.
+\def\cedilla#1{\ifx\c\ptexc\c{#1}\else\,{#1}\fi}
+
+% First, make active non-ASCII characters in order for them to be
+% correctly categorized when TeX reads the replacement text of
+% macros containing the character definitions.
+\setnonasciicharscatcode\active
+%
+% Latin1 (ISO-8859-1) character definitions.
+\def\latonechardefs{%
+  \gdef^^a0{~}
+  \gdef^^a1{\exclamdown}
+  \gdef^^a2{\missingcharmsg{CENT SIGN}}
+  \gdef^^a3{{\pounds}}
+  \gdef^^a4{\missingcharmsg{CURRENCY SIGN}}
+  \gdef^^a5{\missingcharmsg{YEN SIGN}}
+  \gdef^^a6{\missingcharmsg{BROKEN BAR}}
+  \gdef^^a7{\S}
+  \gdef^^a8{\"{}}
+  \gdef^^a9{\copyright}
+  \gdef^^aa{\ordf}
+  \gdef^^ab{\guillemetleft}
+  \gdef^^ac{$\lnot$}
+  \gdef^^ad{\-}
+  \gdef^^ae{\registeredsymbol}
+  \gdef^^af{\={}}
+  %
+  \gdef^^b0{\textdegree}
+  \gdef^^b1{$\pm$}
+  \gdef^^b2{$^2$}
+  \gdef^^b3{$^3$}
+  \gdef^^b4{\'{}}
+  \gdef^^b5{$\mu$}
+  \gdef^^b6{\P}
+  %
+  \gdef^^b7{$^.$}
+  \gdef^^b8{\cedilla\ }
+  \gdef^^b9{$^1$}
+  \gdef^^ba{\ordm}
+  %
+  \gdef^^bb{\guilletright}
+  \gdef^^bc{$1\over4$}
+  \gdef^^bd{$1\over2$}
+  \gdef^^be{$3\over4$}
+  \gdef^^bf{\questiondown}
+  %
+  \gdef^^c0{\`A}
+  \gdef^^c1{\'A}
+  \gdef^^c2{\^A}
+  \gdef^^c3{\~A}
+  \gdef^^c4{\"A}
+  \gdef^^c5{\ringaccent A}
+  \gdef^^c6{\AE}
+  \gdef^^c7{\cedilla C}
+  \gdef^^c8{\`E}
+  \gdef^^c9{\'E}
+  \gdef^^ca{\^E}
+  \gdef^^cb{\"E}
+  \gdef^^cc{\`I}
+  \gdef^^cd{\'I}
+  \gdef^^ce{\^I}
+  \gdef^^cf{\"I}
+  %
+  \gdef^^d0{\DH}
+  \gdef^^d1{\~N}
+  \gdef^^d2{\`O}
+  \gdef^^d3{\'O}
+  \gdef^^d4{\^O}
+  \gdef^^d5{\~O}
+  \gdef^^d6{\"O}
+  \gdef^^d7{$\times$}
+  \gdef^^d8{\O}
+  \gdef^^d9{\`U}
+  \gdef^^da{\'U}
+  \gdef^^db{\^U}
+  \gdef^^dc{\"U}
+  \gdef^^dd{\'Y}
+  \gdef^^de{\TH}
+  \gdef^^df{\ss}
+  %
+  \gdef^^e0{\`a}
+  \gdef^^e1{\'a}
+  \gdef^^e2{\^a}
+  \gdef^^e3{\~a}
+  \gdef^^e4{\"a}
+  \gdef^^e5{\ringaccent a}
+  \gdef^^e6{\ae}
+  \gdef^^e7{\cedilla c}
+  \gdef^^e8{\`e}
+  \gdef^^e9{\'e}
+  \gdef^^ea{\^e}
+  \gdef^^eb{\"e}
+  \gdef^^ec{\`{\dotless i}}
+  \gdef^^ed{\'{\dotless i}}
+  \gdef^^ee{\^{\dotless i}}
+  \gdef^^ef{\"{\dotless i}}
+  %
+  \gdef^^f0{\dh}
+  \gdef^^f1{\~n}
+  \gdef^^f2{\`o}
+  \gdef^^f3{\'o}
+  \gdef^^f4{\^o}
+  \gdef^^f5{\~o}
+  \gdef^^f6{\"o}
+  \gdef^^f7{$\div$}
+  \gdef^^f8{\o}
+  \gdef^^f9{\`u}
+  \gdef^^fa{\'u}
+  \gdef^^fb{\^u}
+  \gdef^^fc{\"u}
+  \gdef^^fd{\'y}
+  \gdef^^fe{\th}
+  \gdef^^ff{\"y}
+}
+
+% Latin9 (ISO-8859-15) encoding character definitions.
+\def\latninechardefs{%
+  % Encoding is almost identical to Latin1.
+  \latonechardefs
+  %
+  \gdef^^a4{\euro}
+  \gdef^^a6{\v S}
+  \gdef^^a8{\v s}
+  \gdef^^b4{\v Z}
+  \gdef^^b8{\v z}
+  \gdef^^bc{\OE}
+  \gdef^^bd{\oe}
+  \gdef^^be{\"Y}
+}
+
+% Latin2 (ISO-8859-2) character definitions.
+\def\lattwochardefs{%
+  \gdef^^a0{~}
+  \gdef^^a1{\ogonek{A}}
+  \gdef^^a2{\u{}}
+  \gdef^^a3{\L}
+  \gdef^^a4{\missingcharmsg{CURRENCY SIGN}}
+  \gdef^^a5{\v L}
+  \gdef^^a6{\'S}
+  \gdef^^a7{\S}
+  \gdef^^a8{\"{}}
+  \gdef^^a9{\v S}
+  \gdef^^aa{\cedilla S}
+  \gdef^^ab{\v T}
+  \gdef^^ac{\'Z}
+  \gdef^^ad{\-}
+  \gdef^^ae{\v Z}
+  \gdef^^af{\dotaccent Z}
+  %
+  \gdef^^b0{\textdegree}
+  \gdef^^b1{\ogonek{a}}
+  \gdef^^b2{\ogonek{ }}
+  \gdef^^b3{\l}
+  \gdef^^b4{\'{}}
+  \gdef^^b5{\v l}
+  \gdef^^b6{\'s}
+  \gdef^^b7{\v{}}
+  \gdef^^b8{\cedilla\ }
+  \gdef^^b9{\v s}
+  \gdef^^ba{\cedilla s}
+  \gdef^^bb{\v t}
+  \gdef^^bc{\'z}
+  \gdef^^bd{\H{}}
+  \gdef^^be{\v z}
+  \gdef^^bf{\dotaccent z}
+  %
+  \gdef^^c0{\'R}
+  \gdef^^c1{\'A}
+  \gdef^^c2{\^A}
+  \gdef^^c3{\u A}
+  \gdef^^c4{\"A}
+  \gdef^^c5{\'L}
+  \gdef^^c6{\'C}
+  \gdef^^c7{\cedilla C}
+  \gdef^^c8{\v C}
+  \gdef^^c9{\'E}
+  \gdef^^ca{\ogonek{E}}
+  \gdef^^cb{\"E}
+  \gdef^^cc{\v E}
+  \gdef^^cd{\'I}
+  \gdef^^ce{\^I}
+  \gdef^^cf{\v D}
+  %
+  \gdef^^d0{\DH}
+  \gdef^^d1{\'N}
+  \gdef^^d2{\v N}
+  \gdef^^d3{\'O}
+  \gdef^^d4{\^O}
+  \gdef^^d5{\H O}
+  \gdef^^d6{\"O}
+  \gdef^^d7{$\times$}
+  \gdef^^d8{\v R}
+  \gdef^^d9{\ringaccent U}
+  \gdef^^da{\'U}
+  \gdef^^db{\H U}
+  \gdef^^dc{\"U}
+  \gdef^^dd{\'Y}
+  \gdef^^de{\cedilla T}
+  \gdef^^df{\ss}
+  %
+  \gdef^^e0{\'r}
+  \gdef^^e1{\'a}
+  \gdef^^e2{\^a}
+  \gdef^^e3{\u a}
+  \gdef^^e4{\"a}
+  \gdef^^e5{\'l}
+  \gdef^^e6{\'c}
+  \gdef^^e7{\cedilla c}
+  \gdef^^e8{\v c}
+  \gdef^^e9{\'e}
+  \gdef^^ea{\ogonek{e}}
+  \gdef^^eb{\"e}
+  \gdef^^ec{\v e}
+  \gdef^^ed{\'\i}
+  \gdef^^ee{\^\i}
+  \gdef^^ef{\v d}
+  %
+  \gdef^^f0{\dh}
+  \gdef^^f1{\'n}
+  \gdef^^f2{\v n}
+  \gdef^^f3{\'o}
+  \gdef^^f4{\^o}
+  \gdef^^f5{\H o}
+  \gdef^^f6{\"o}
+  \gdef^^f7{$\div$}
+  \gdef^^f8{\v r}
+  \gdef^^f9{\ringaccent u}
+  \gdef^^fa{\'u}
+  \gdef^^fb{\H u}
+  \gdef^^fc{\"u}
+  \gdef^^fd{\'y}
+  \gdef^^fe{\cedilla t}
+  \gdef^^ff{\dotaccent{}}
+}
+
+% UTF-8 character definitions.
+%
+% This code to support UTF-8 is based on LaTeX's utf8.def, with some
+% changes for Texinfo conventions.  It is included here under the GPL by
+% permission from Frank Mittelbach and the LaTeX team.
+%
+\newcount\countUTFx
+\newcount\countUTFy
+\newcount\countUTFz
+
+\gdef\UTFviiiTwoOctets#1#2{\expandafter
+   \UTFviiiDefined\csname u8:#1\string #2\endcsname}
+%
+\gdef\UTFviiiThreeOctets#1#2#3{\expandafter
+   \UTFviiiDefined\csname u8:#1\string #2\string #3\endcsname}
+%
+\gdef\UTFviiiFourOctets#1#2#3#4{\expandafter
+   \UTFviiiDefined\csname u8:#1\string #2\string #3\string #4\endcsname}
+
+\gdef\UTFviiiDefined#1{%
+  \ifx #1\relax
+    \message{\linenumber Unicode char \string #1 not defined for Texinfo}%
+  \else
+    \expandafter #1%
+  \fi
+}
+
+\begingroup
+  \catcode`\~13
+  \catcode`\"12
+
+  \def\UTFviiiLoop{%
+    \global\catcode\countUTFx\active
+    \uccode`\~\countUTFx
+    \uppercase\expandafter{\UTFviiiTmp}%
+    \advance\countUTFx by 1
+    \ifnum\countUTFx < \countUTFy
+      \expandafter\UTFviiiLoop
+    \fi}
+
+  \countUTFx = "C2
+  \countUTFy = "E0
+  \def\UTFviiiTmp{%
+    \xdef~{\noexpand\UTFviiiTwoOctets\string~}}
+  \UTFviiiLoop
+
+  \countUTFx = "E0
+  \countUTFy = "F0
+  \def\UTFviiiTmp{%
+    \xdef~{\noexpand\UTFviiiThreeOctets\string~}}
+  \UTFviiiLoop
+
+  \countUTFx = "F0
+  \countUTFy = "F4
+  \def\UTFviiiTmp{%
+    \xdef~{\noexpand\UTFviiiFourOctets\string~}}
+  \UTFviiiLoop
+\endgroup
+
+\begingroup
+  \catcode`\"=12
+  \catcode`\<=12
+  \catcode`\.=12
+  \catcode`\,=12
+  \catcode`\;=12
+  \catcode`\!=12
+  \catcode`\~=13
+
+  \gdef\DeclareUnicodeCharacter#1#2{%
+    \countUTFz = "#1\relax
+    \wlog{\space\space defining Unicode char U+#1 (decimal \the\countUTFz)}%
+    \begingroup
+      \parseXMLCharref
+      \def\UTFviiiTwoOctets##1##2{%
+        \csname u8:##1\string ##2\endcsname}%
+      \def\UTFviiiThreeOctets##1##2##3{%
+        \csname u8:##1\string ##2\string ##3\endcsname}%
+      \def\UTFviiiFourOctets##1##2##3##4{%
+        \csname u8:##1\string ##2\string ##3\string ##4\endcsname}%
+      \expandafter\expandafter\expandafter\expandafter
+       \expandafter\expandafter\expandafter
+       \gdef\UTFviiiTmp{#2}%
+    \endgroup}
+
+  \gdef\parseXMLCharref{%
+    \ifnum\countUTFz < "A0\relax
+      \errhelp = \EMsimple
+      \errmessage{Cannot define Unicode char value < 00A0}%
+    \else\ifnum\countUTFz < "800\relax
+      \parseUTFviiiA,%
+      \parseUTFviiiB C\UTFviiiTwoOctets.,%
+    \else\ifnum\countUTFz < "10000\relax
+      \parseUTFviiiA;%
+      \parseUTFviiiA,%
+      \parseUTFviiiB E\UTFviiiThreeOctets.{,;}%
+    \else
+      \parseUTFviiiA;%
+      \parseUTFviiiA,%
+      \parseUTFviiiA!%
+      \parseUTFviiiB F\UTFviiiFourOctets.{!,;}%
+    \fi\fi\fi
+  }
+
+  \gdef\parseUTFviiiA#1{%
+    \countUTFx = \countUTFz
+    \divide\countUTFz by 64
+    \countUTFy = \countUTFz
+    \multiply\countUTFz by 64
+    \advance\countUTFx by -\countUTFz
+    \advance\countUTFx by 128
+    \uccode `#1\countUTFx
+    \countUTFz = \countUTFy}
+
+  \gdef\parseUTFviiiB#1#2#3#4{%
+    \advance\countUTFz by "#10\relax
+    \uccode `#3\countUTFz
+    \uppercase{\gdef\UTFviiiTmp{#2#3#4}}}
+\endgroup
+
+\def\utfeightchardefs{%
+  \DeclareUnicodeCharacter{00A0}{\tie}
+  \DeclareUnicodeCharacter{00A1}{\exclamdown}
+  \DeclareUnicodeCharacter{00A3}{\pounds}
+  \DeclareUnicodeCharacter{00A8}{\"{ }}
+  \DeclareUnicodeCharacter{00A9}{\copyright}
+  \DeclareUnicodeCharacter{00AA}{\ordf}
+  \DeclareUnicodeCharacter{00AB}{\guillemetleft}
+  \DeclareUnicodeCharacter{00AD}{\-}
+  \DeclareUnicodeCharacter{00AE}{\registeredsymbol}
+  \DeclareUnicodeCharacter{00AF}{\={ }}
+
+  \DeclareUnicodeCharacter{00B0}{\ringaccent{ }}
+  \DeclareUnicodeCharacter{00B4}{\'{ }}
+  \DeclareUnicodeCharacter{00B8}{\cedilla{ }}
+  \DeclareUnicodeCharacter{00BA}{\ordm}
+  \DeclareUnicodeCharacter{00BB}{\guillemetright}
+  \DeclareUnicodeCharacter{00BF}{\questiondown}
+
+  \DeclareUnicodeCharacter{00C0}{\`A}
+  \DeclareUnicodeCharacter{00C1}{\'A}
+  \DeclareUnicodeCharacter{00C2}{\^A}
+  \DeclareUnicodeCharacter{00C3}{\~A}
+  \DeclareUnicodeCharacter{00C4}{\"A}
+  \DeclareUnicodeCharacter{00C5}{\AA}
+  \DeclareUnicodeCharacter{00C6}{\AE}
+  \DeclareUnicodeCharacter{00C7}{\cedilla{C}}
+  \DeclareUnicodeCharacter{00C8}{\`E}
+  \DeclareUnicodeCharacter{00C9}{\'E}
+  \DeclareUnicodeCharacter{00CA}{\^E}
+  \DeclareUnicodeCharacter{00CB}{\"E}
+  \DeclareUnicodeCharacter{00CC}{\`I}
+  \DeclareUnicodeCharacter{00CD}{\'I}
+  \DeclareUnicodeCharacter{00CE}{\^I}
+  \DeclareUnicodeCharacter{00CF}{\"I}
+
+  \DeclareUnicodeCharacter{00D0}{\DH}
+  \DeclareUnicodeCharacter{00D1}{\~N}
+  \DeclareUnicodeCharacter{00D2}{\`O}
+  \DeclareUnicodeCharacter{00D3}{\'O}
+  \DeclareUnicodeCharacter{00D4}{\^O}
+  \DeclareUnicodeCharacter{00D5}{\~O}
+  \DeclareUnicodeCharacter{00D6}{\"O}
+  \DeclareUnicodeCharacter{00D8}{\O}
+  \DeclareUnicodeCharacter{00D9}{\`U}
+  \DeclareUnicodeCharacter{00DA}{\'U}
+  \DeclareUnicodeCharacter{00DB}{\^U}
+  \DeclareUnicodeCharacter{00DC}{\"U}
+  \DeclareUnicodeCharacter{00DD}{\'Y}
+  \DeclareUnicodeCharacter{00DE}{\TH}
+  \DeclareUnicodeCharacter{00DF}{\ss}
+
+  \DeclareUnicodeCharacter{00E0}{\`a}
+  \DeclareUnicodeCharacter{00E1}{\'a}
+  \DeclareUnicodeCharacter{00E2}{\^a}
+  \DeclareUnicodeCharacter{00E3}{\~a}
+  \DeclareUnicodeCharacter{00E4}{\"a}
+  \DeclareUnicodeCharacter{00E5}{\aa}
+  \DeclareUnicodeCharacter{00E6}{\ae}
+  \DeclareUnicodeCharacter{00E7}{\cedilla{c}}
+  \DeclareUnicodeCharacter{00E8}{\`e}
+  \DeclareUnicodeCharacter{00E9}{\'e}
+  \DeclareUnicodeCharacter{00EA}{\^e}
+  \DeclareUnicodeCharacter{00EB}{\"e}
+  \DeclareUnicodeCharacter{00EC}{\`{\dotless{i}}}
+  \DeclareUnicodeCharacter{00ED}{\'{\dotless{i}}}
+  \DeclareUnicodeCharacter{00EE}{\^{\dotless{i}}}
+  \DeclareUnicodeCharacter{00EF}{\"{\dotless{i}}}
+
+  \DeclareUnicodeCharacter{00F0}{\dh}
+  \DeclareUnicodeCharacter{00F1}{\~n}
+  \DeclareUnicodeCharacter{00F2}{\`o}
+  \DeclareUnicodeCharacter{00F3}{\'o}
+  \DeclareUnicodeCharacter{00F4}{\^o}
+  \DeclareUnicodeCharacter{00F5}{\~o}
+  \DeclareUnicodeCharacter{00F6}{\"o}
+  \DeclareUnicodeCharacter{00F8}{\o}
+  \DeclareUnicodeCharacter{00F9}{\`u}
+  \DeclareUnicodeCharacter{00FA}{\'u}
+  \DeclareUnicodeCharacter{00FB}{\^u}
+  \DeclareUnicodeCharacter{00FC}{\"u}
+  \DeclareUnicodeCharacter{00FD}{\'y}
+  \DeclareUnicodeCharacter{00FE}{\th}
+  \DeclareUnicodeCharacter{00FF}{\"y}
+
+  \DeclareUnicodeCharacter{0100}{\=A}
+  \DeclareUnicodeCharacter{0101}{\=a}
+  \DeclareUnicodeCharacter{0102}{\u{A}}
+  \DeclareUnicodeCharacter{0103}{\u{a}}
+  \DeclareUnicodeCharacter{0104}{\ogonek{A}}
+  \DeclareUnicodeCharacter{0105}{\ogonek{a}}
+  \DeclareUnicodeCharacter{0106}{\'C}
+  \DeclareUnicodeCharacter{0107}{\'c}
+  \DeclareUnicodeCharacter{0108}{\^C}
+  \DeclareUnicodeCharacter{0109}{\^c}
+  \DeclareUnicodeCharacter{0118}{\ogonek{E}}
+  \DeclareUnicodeCharacter{0119}{\ogonek{e}}
+  \DeclareUnicodeCharacter{010A}{\dotaccent{C}}
+  \DeclareUnicodeCharacter{010B}{\dotaccent{c}}
+  \DeclareUnicodeCharacter{010C}{\v{C}}
+  \DeclareUnicodeCharacter{010D}{\v{c}}
+  \DeclareUnicodeCharacter{010E}{\v{D}}
+
+  \DeclareUnicodeCharacter{0112}{\=E}
+  \DeclareUnicodeCharacter{0113}{\=e}
+  \DeclareUnicodeCharacter{0114}{\u{E}}
+  \DeclareUnicodeCharacter{0115}{\u{e}}
+  \DeclareUnicodeCharacter{0116}{\dotaccent{E}}
+  \DeclareUnicodeCharacter{0117}{\dotaccent{e}}
+  \DeclareUnicodeCharacter{011A}{\v{E}}
+  \DeclareUnicodeCharacter{011B}{\v{e}}
+  \DeclareUnicodeCharacter{011C}{\^G}
+  \DeclareUnicodeCharacter{011D}{\^g}
+  \DeclareUnicodeCharacter{011E}{\u{G}}
+  \DeclareUnicodeCharacter{011F}{\u{g}}
+
+  \DeclareUnicodeCharacter{0120}{\dotaccent{G}}
+  \DeclareUnicodeCharacter{0121}{\dotaccent{g}}
+  \DeclareUnicodeCharacter{0124}{\^H}
+  \DeclareUnicodeCharacter{0125}{\^h}
+  \DeclareUnicodeCharacter{0128}{\~I}
+  \DeclareUnicodeCharacter{0129}{\~{\dotless{i}}}
+  \DeclareUnicodeCharacter{012A}{\=I}
+  \DeclareUnicodeCharacter{012B}{\={\dotless{i}}}
+  \DeclareUnicodeCharacter{012C}{\u{I}}
+  \DeclareUnicodeCharacter{012D}{\u{\dotless{i}}}
+
+  \DeclareUnicodeCharacter{0130}{\dotaccent{I}}
+  \DeclareUnicodeCharacter{0131}{\dotless{i}}
+  \DeclareUnicodeCharacter{0132}{IJ}
+  \DeclareUnicodeCharacter{0133}{ij}
+  \DeclareUnicodeCharacter{0134}{\^J}
+  \DeclareUnicodeCharacter{0135}{\^{\dotless{j}}}
+  \DeclareUnicodeCharacter{0139}{\'L}
+  \DeclareUnicodeCharacter{013A}{\'l}
+
+  \DeclareUnicodeCharacter{0141}{\L}
+  \DeclareUnicodeCharacter{0142}{\l}
+  \DeclareUnicodeCharacter{0143}{\'N}
+  \DeclareUnicodeCharacter{0144}{\'n}
+  \DeclareUnicodeCharacter{0147}{\v{N}}
+  \DeclareUnicodeCharacter{0148}{\v{n}}
+  \DeclareUnicodeCharacter{014C}{\=O}
+  \DeclareUnicodeCharacter{014D}{\=o}
+  \DeclareUnicodeCharacter{014E}{\u{O}}
+  \DeclareUnicodeCharacter{014F}{\u{o}}
+
+  \DeclareUnicodeCharacter{0150}{\H{O}}
+  \DeclareUnicodeCharacter{0151}{\H{o}}
+  \DeclareUnicodeCharacter{0152}{\OE}
+  \DeclareUnicodeCharacter{0153}{\oe}
+  \DeclareUnicodeCharacter{0154}{\'R}
+  \DeclareUnicodeCharacter{0155}{\'r}
+  \DeclareUnicodeCharacter{0158}{\v{R}}
+  \DeclareUnicodeCharacter{0159}{\v{r}}
+  \DeclareUnicodeCharacter{015A}{\'S}
+  \DeclareUnicodeCharacter{015B}{\'s}
+  \DeclareUnicodeCharacter{015C}{\^S}
+  \DeclareUnicodeCharacter{015D}{\^s}
+  \DeclareUnicodeCharacter{015E}{\cedilla{S}}
+  \DeclareUnicodeCharacter{015F}{\cedilla{s}}
+
+  \DeclareUnicodeCharacter{0160}{\v{S}}
+  \DeclareUnicodeCharacter{0161}{\v{s}}
+  \DeclareUnicodeCharacter{0162}{\cedilla{t}}
+  \DeclareUnicodeCharacter{0163}{\cedilla{T}}
+  \DeclareUnicodeCharacter{0164}{\v{T}}
+
+  \DeclareUnicodeCharacter{0168}{\~U}
+  \DeclareUnicodeCharacter{0169}{\~u}
+  \DeclareUnicodeCharacter{016A}{\=U}
+  \DeclareUnicodeCharacter{016B}{\=u}
+  \DeclareUnicodeCharacter{016C}{\u{U}}
+  \DeclareUnicodeCharacter{016D}{\u{u}}
+  \DeclareUnicodeCharacter{016E}{\ringaccent{U}}
+  \DeclareUnicodeCharacter{016F}{\ringaccent{u}}
+
+  \DeclareUnicodeCharacter{0170}{\H{U}}
+  \DeclareUnicodeCharacter{0171}{\H{u}}
+  \DeclareUnicodeCharacter{0174}{\^W}
+  \DeclareUnicodeCharacter{0175}{\^w}
+  \DeclareUnicodeCharacter{0176}{\^Y}
+  \DeclareUnicodeCharacter{0177}{\^y}
+  \DeclareUnicodeCharacter{0178}{\"Y}
+  \DeclareUnicodeCharacter{0179}{\'Z}
+  \DeclareUnicodeCharacter{017A}{\'z}
+  \DeclareUnicodeCharacter{017B}{\dotaccent{Z}}
+  \DeclareUnicodeCharacter{017C}{\dotaccent{z}}
+  \DeclareUnicodeCharacter{017D}{\v{Z}}
+  \DeclareUnicodeCharacter{017E}{\v{z}}
+
+  \DeclareUnicodeCharacter{01C4}{D\v{Z}}
+  \DeclareUnicodeCharacter{01C5}{D\v{z}}
+  \DeclareUnicodeCharacter{01C6}{d\v{z}}
+  \DeclareUnicodeCharacter{01C7}{LJ}
+  \DeclareUnicodeCharacter{01C8}{Lj}
+  \DeclareUnicodeCharacter{01C9}{lj}
+  \DeclareUnicodeCharacter{01CA}{NJ}
+  \DeclareUnicodeCharacter{01CB}{Nj}
+  \DeclareUnicodeCharacter{01CC}{nj}
+  \DeclareUnicodeCharacter{01CD}{\v{A}}
+  \DeclareUnicodeCharacter{01CE}{\v{a}}
+  \DeclareUnicodeCharacter{01CF}{\v{I}}
+
+  \DeclareUnicodeCharacter{01D0}{\v{\dotless{i}}}
+  \DeclareUnicodeCharacter{01D1}{\v{O}}
+  \DeclareUnicodeCharacter{01D2}{\v{o}}
+  \DeclareUnicodeCharacter{01D3}{\v{U}}
+  \DeclareUnicodeCharacter{01D4}{\v{u}}
+
+  \DeclareUnicodeCharacter{01E2}{\={\AE}}
+  \DeclareUnicodeCharacter{01E3}{\={\ae}}
+  \DeclareUnicodeCharacter{01E6}{\v{G}}
+  \DeclareUnicodeCharacter{01E7}{\v{g}}
+  \DeclareUnicodeCharacter{01E8}{\v{K}}
+  \DeclareUnicodeCharacter{01E9}{\v{k}}
+
+  \DeclareUnicodeCharacter{01F0}{\v{\dotless{j}}}
+  \DeclareUnicodeCharacter{01F1}{DZ}
+  \DeclareUnicodeCharacter{01F2}{Dz}
+  \DeclareUnicodeCharacter{01F3}{dz}
+  \DeclareUnicodeCharacter{01F4}{\'G}
+  \DeclareUnicodeCharacter{01F5}{\'g}
+  \DeclareUnicodeCharacter{01F8}{\`N}
+  \DeclareUnicodeCharacter{01F9}{\`n}
+  \DeclareUnicodeCharacter{01FC}{\'{\AE}}
+  \DeclareUnicodeCharacter{01FD}{\'{\ae}}
+  \DeclareUnicodeCharacter{01FE}{\'{\O}}
+  \DeclareUnicodeCharacter{01FF}{\'{\o}}
+
+  \DeclareUnicodeCharacter{021E}{\v{H}}
+  \DeclareUnicodeCharacter{021F}{\v{h}}
+
+  \DeclareUnicodeCharacter{0226}{\dotaccent{A}}
+  \DeclareUnicodeCharacter{0227}{\dotaccent{a}}
+  \DeclareUnicodeCharacter{0228}{\cedilla{E}}
+  \DeclareUnicodeCharacter{0229}{\cedilla{e}}
+  \DeclareUnicodeCharacter{022E}{\dotaccent{O}}
+  \DeclareUnicodeCharacter{022F}{\dotaccent{o}}
+
+  \DeclareUnicodeCharacter{0232}{\=Y}
+  \DeclareUnicodeCharacter{0233}{\=y}
+  \DeclareUnicodeCharacter{0237}{\dotless{j}}
+
+  \DeclareUnicodeCharacter{02DB}{\ogonek{ }}
+
+  \DeclareUnicodeCharacter{1E02}{\dotaccent{B}}
+  \DeclareUnicodeCharacter{1E03}{\dotaccent{b}}
+  \DeclareUnicodeCharacter{1E04}{\udotaccent{B}}
+  \DeclareUnicodeCharacter{1E05}{\udotaccent{b}}
+  \DeclareUnicodeCharacter{1E06}{\ubaraccent{B}}
+  \DeclareUnicodeCharacter{1E07}{\ubaraccent{b}}
+  \DeclareUnicodeCharacter{1E0A}{\dotaccent{D}}
+  \DeclareUnicodeCharacter{1E0B}{\dotaccent{d}}
+  \DeclareUnicodeCharacter{1E0C}{\udotaccent{D}}
+  \DeclareUnicodeCharacter{1E0D}{\udotaccent{d}}
+  \DeclareUnicodeCharacter{1E0E}{\ubaraccent{D}}
+  \DeclareUnicodeCharacter{1E0F}{\ubaraccent{d}}
+
+  \DeclareUnicodeCharacter{1E1E}{\dotaccent{F}}
+  \DeclareUnicodeCharacter{1E1F}{\dotaccent{f}}
+
+  \DeclareUnicodeCharacter{1E20}{\=G}
+  \DeclareUnicodeCharacter{1E21}{\=g}
+  \DeclareUnicodeCharacter{1E22}{\dotaccent{H}}
+  \DeclareUnicodeCharacter{1E23}{\dotaccent{h}}
+  \DeclareUnicodeCharacter{1E24}{\udotaccent{H}}
+  \DeclareUnicodeCharacter{1E25}{\udotaccent{h}}
+  \DeclareUnicodeCharacter{1E26}{\"H}
+  \DeclareUnicodeCharacter{1E27}{\"h}
+
+  \DeclareUnicodeCharacter{1E30}{\'K}
+  \DeclareUnicodeCharacter{1E31}{\'k}
+  \DeclareUnicodeCharacter{1E32}{\udotaccent{K}}
+  \DeclareUnicodeCharacter{1E33}{\udotaccent{k}}
+  \DeclareUnicodeCharacter{1E34}{\ubaraccent{K}}
+  \DeclareUnicodeCharacter{1E35}{\ubaraccent{k}}
+  \DeclareUnicodeCharacter{1E36}{\udotaccent{L}}
+  \DeclareUnicodeCharacter{1E37}{\udotaccent{l}}
+  \DeclareUnicodeCharacter{1E3A}{\ubaraccent{L}}
+  \DeclareUnicodeCharacter{1E3B}{\ubaraccent{l}}
+  \DeclareUnicodeCharacter{1E3E}{\'M}
+  \DeclareUnicodeCharacter{1E3F}{\'m}
+
+  \DeclareUnicodeCharacter{1E40}{\dotaccent{M}}
+  \DeclareUnicodeCharacter{1E41}{\dotaccent{m}}
+  \DeclareUnicodeCharacter{1E42}{\udotaccent{M}}
+  \DeclareUnicodeCharacter{1E43}{\udotaccent{m}}
+  \DeclareUnicodeCharacter{1E44}{\dotaccent{N}}
+  \DeclareUnicodeCharacter{1E45}{\dotaccent{n}}
+  \DeclareUnicodeCharacter{1E46}{\udotaccent{N}}
+  \DeclareUnicodeCharacter{1E47}{\udotaccent{n}}
+  \DeclareUnicodeCharacter{1E48}{\ubaraccent{N}}
+  \DeclareUnicodeCharacter{1E49}{\ubaraccent{n}}
+
+  \DeclareUnicodeCharacter{1E54}{\'P}
+  \DeclareUnicodeCharacter{1E55}{\'p}
+  \DeclareUnicodeCharacter{1E56}{\dotaccent{P}}
+  \DeclareUnicodeCharacter{1E57}{\dotaccent{p}}
+  \DeclareUnicodeCharacter{1E58}{\dotaccent{R}}
+  \DeclareUnicodeCharacter{1E59}{\dotaccent{r}}
+  \DeclareUnicodeCharacter{1E5A}{\udotaccent{R}}
+  \DeclareUnicodeCharacter{1E5B}{\udotaccent{r}}
+  \DeclareUnicodeCharacter{1E5E}{\ubaraccent{R}}
+  \DeclareUnicodeCharacter{1E5F}{\ubaraccent{r}}
+
+  \DeclareUnicodeCharacter{1E60}{\dotaccent{S}}
+  \DeclareUnicodeCharacter{1E61}{\dotaccent{s}}
+  \DeclareUnicodeCharacter{1E62}{\udotaccent{S}}
+  \DeclareUnicodeCharacter{1E63}{\udotaccent{s}}
+  \DeclareUnicodeCharacter{1E6A}{\dotaccent{T}}
+  \DeclareUnicodeCharacter{1E6B}{\dotaccent{t}}
+  \DeclareUnicodeCharacter{1E6C}{\udotaccent{T}}
+  \DeclareUnicodeCharacter{1E6D}{\udotaccent{t}}
+  \DeclareUnicodeCharacter{1E6E}{\ubaraccent{T}}
+  \DeclareUnicodeCharacter{1E6F}{\ubaraccent{t}}
+
+  \DeclareUnicodeCharacter{1E7C}{\~V}
+  \DeclareUnicodeCharacter{1E7D}{\~v}
+  \DeclareUnicodeCharacter{1E7E}{\udotaccent{V}}
+  \DeclareUnicodeCharacter{1E7F}{\udotaccent{v}}
+
+  \DeclareUnicodeCharacter{1E80}{\`W}
+  \DeclareUnicodeCharacter{1E81}{\`w}
+  \DeclareUnicodeCharacter{1E82}{\'W}
+  \DeclareUnicodeCharacter{1E83}{\'w}
+  \DeclareUnicodeCharacter{1E84}{\"W}
+  \DeclareUnicodeCharacter{1E85}{\"w}
+  \DeclareUnicodeCharacter{1E86}{\dotaccent{W}}
+  \DeclareUnicodeCharacter{1E87}{\dotaccent{w}}
+  \DeclareUnicodeCharacter{1E88}{\udotaccent{W}}
+  \DeclareUnicodeCharacter{1E89}{\udotaccent{w}}
+  \DeclareUnicodeCharacter{1E8A}{\dotaccent{X}}
+  \DeclareUnicodeCharacter{1E8B}{\dotaccent{x}}
+  \DeclareUnicodeCharacter{1E8C}{\"X}
+  \DeclareUnicodeCharacter{1E8D}{\"x}
+  \DeclareUnicodeCharacter{1E8E}{\dotaccent{Y}}
+  \DeclareUnicodeCharacter{1E8F}{\dotaccent{y}}
+
+  \DeclareUnicodeCharacter{1E90}{\^Z}
+  \DeclareUnicodeCharacter{1E91}{\^z}
+  \DeclareUnicodeCharacter{1E92}{\udotaccent{Z}}
+  \DeclareUnicodeCharacter{1E93}{\udotaccent{z}}
+  \DeclareUnicodeCharacter{1E94}{\ubaraccent{Z}}
+  \DeclareUnicodeCharacter{1E95}{\ubaraccent{z}}
+  \DeclareUnicodeCharacter{1E96}{\ubaraccent{h}}
+  \DeclareUnicodeCharacter{1E97}{\"t}
+  \DeclareUnicodeCharacter{1E98}{\ringaccent{w}}
+  \DeclareUnicodeCharacter{1E99}{\ringaccent{y}}
+
+  \DeclareUnicodeCharacter{1EA0}{\udotaccent{A}}
+  \DeclareUnicodeCharacter{1EA1}{\udotaccent{a}}
+
+  \DeclareUnicodeCharacter{1EB8}{\udotaccent{E}}
+  \DeclareUnicodeCharacter{1EB9}{\udotaccent{e}}
+  \DeclareUnicodeCharacter{1EBC}{\~E}
+  \DeclareUnicodeCharacter{1EBD}{\~e}
+
+  \DeclareUnicodeCharacter{1ECA}{\udotaccent{I}}
+  \DeclareUnicodeCharacter{1ECB}{\udotaccent{i}}
+  \DeclareUnicodeCharacter{1ECC}{\udotaccent{O}}
+  \DeclareUnicodeCharacter{1ECD}{\udotaccent{o}}
+
+  \DeclareUnicodeCharacter{1EE4}{\udotaccent{U}}
+  \DeclareUnicodeCharacter{1EE5}{\udotaccent{u}}
+
+  \DeclareUnicodeCharacter{1EF2}{\`Y}
+  \DeclareUnicodeCharacter{1EF3}{\`y}
+  \DeclareUnicodeCharacter{1EF4}{\udotaccent{Y}}
+
+  \DeclareUnicodeCharacter{1EF8}{\~Y}
+  \DeclareUnicodeCharacter{1EF9}{\~y}
+
+  \DeclareUnicodeCharacter{2013}{--}
+  \DeclareUnicodeCharacter{2014}{---}
+  \DeclareUnicodeCharacter{2018}{\quoteleft}
+  \DeclareUnicodeCharacter{2019}{\quoteright}
+  \DeclareUnicodeCharacter{201A}{\quotesinglbase}
+  \DeclareUnicodeCharacter{201C}{\quotedblleft}
+  \DeclareUnicodeCharacter{201D}{\quotedblright}
+  \DeclareUnicodeCharacter{201E}{\quotedblbase}
+  \DeclareUnicodeCharacter{2022}{\bullet}
+  \DeclareUnicodeCharacter{2026}{\dots}
+  \DeclareUnicodeCharacter{2039}{\guilsinglleft}
+  \DeclareUnicodeCharacter{203A}{\guilsinglright}
+  \DeclareUnicodeCharacter{20AC}{\euro}
+
+  \DeclareUnicodeCharacter{2192}{\expansion}
+  \DeclareUnicodeCharacter{21D2}{\result}
+
+  \DeclareUnicodeCharacter{2212}{\minus}
+  \DeclareUnicodeCharacter{2217}{\point}
+  \DeclareUnicodeCharacter{2261}{\equiv}
+}% end of \utfeightchardefs
+
+
+% US-ASCII character definitions.
+\def\asciichardefs{% nothing need be done
+   \relax
+}
+
+% Make non-ASCII characters printable again for compatibility with
+% existing Texinfo documents that may use them, even without declaring a
+% document encoding.
+%
+\setnonasciicharscatcode \other
+
+
+\message{formatting,}
+
+\newdimen\defaultparindent \defaultparindent = 15pt
+
+\chapheadingskip = 15pt plus 4pt minus 2pt
+\secheadingskip = 12pt plus 3pt minus 2pt
+\subsecheadingskip = 9pt plus 2pt minus 2pt
+
+% Prevent underfull vbox error messages.
+\vbadness = 10000
+
+% Don't be so finicky about underfull hboxes, either.
+\hbadness = 2000
+
+% Following George Bush, get rid of widows and orphans.
+\widowpenalty=10000
+\clubpenalty=10000
+
+% Use TeX 3.0's \emergencystretch to help line breaking, but if we're
+% using an old version of TeX, don't do anything.  We want the amount of
+% stretch added to depend on the line length, hence the dependence on
+% \hsize.  We call this whenever the paper size is set.
+%
+\def\setemergencystretch{%
+  \ifx\emergencystretch\thisisundefined
+    % Allow us to assign to \emergencystretch anyway.
+    \def\emergencystretch{\dimen0}%
+  \else
+    \emergencystretch = .15\hsize
+  \fi
+}
+
+% Parameters in order: 1) textheight; 2) textwidth;
+% 3) voffset; 4) hoffset; 5) binding offset; 6) topskip;
+% 7) physical page height; 8) physical page width.
+%
+% We also call \setleading{\textleading}, so the caller should define
+% \textleading.  The caller should also set \parskip.
+%
+\def\internalpagesizes#1#2#3#4#5#6#7#8{%
+  \voffset = #3\relax
+  \topskip = #6\relax
+  \splittopskip = \topskip
+  %
+  \vsize = #1\relax
+  \advance\vsize by \topskip
+  \outervsize = \vsize
+  \advance\outervsize by 2\topandbottommargin
+  \pageheight = \vsize
+  %
+  \hsize = #2\relax
+  \outerhsize = \hsize
+  \advance\outerhsize by 0.5in
+  \pagewidth = \hsize
+  %
+  \normaloffset = #4\relax
+  \bindingoffset = #5\relax
+  %
+  \ifpdf
+    \pdfpageheight #7\relax
+    \pdfpagewidth #8\relax
+    % if we don't reset these, they will remain at "1 true in" of
+    % whatever layout pdftex was dumped with.
+    \pdfhorigin = 1 true in
+    \pdfvorigin = 1 true in
+  \fi
+  %
+  \setleading{\textleading}
+  %
+  \parindent = \defaultparindent
+  \setemergencystretch
+}
+
+% @letterpaper (the default).
+\def\letterpaper{{\globaldefs = 1
+  \parskip = 3pt plus 2pt minus 1pt
+  \textleading = 13.2pt
+  %
+  % If page is nothing but text, make it come out even.
+  \internalpagesizes{607.2pt}{6in}% that's 46 lines
+                    {\voffset}{.25in}%
+                    {\bindingoffset}{36pt}%
+                    {11in}{8.5in}%
+}}
+
+% Use @smallbook to reset parameters for 7x9.25 trim size.
+\def\smallbook{{\globaldefs = 1
+  \parskip = 2pt plus 1pt
+  \textleading = 12pt
+  %
+  \internalpagesizes{7.5in}{5in}%
+                    {-.2in}{0in}%
+                    {\bindingoffset}{16pt}%
+                    {9.25in}{7in}%
+  %
+  \lispnarrowing = 0.3in
+  \tolerance = 700
+  \hfuzz = 1pt
+  \contentsrightmargin = 0pt
+  \defbodyindent = .5cm
+}}
+
+% Use @smallerbook to reset parameters for 6x9 trim size.
+% (Just testing, parameters still in flux.)
+\def\smallerbook{{\globaldefs = 1
+  \parskip = 1.5pt plus 1pt
+  \textleading = 12pt
+  %
+  \internalpagesizes{7.4in}{4.8in}%
+                    {-.2in}{-.4in}%
+                    {0pt}{14pt}%
+                    {9in}{6in}%
+  %
+  \lispnarrowing = 0.25in
+  \tolerance = 700
+  \hfuzz = 1pt
+  \contentsrightmargin = 0pt
+  \defbodyindent = .4cm
+}}
+
+% Use @afourpaper to print on European A4 paper.
+\def\afourpaper{{\globaldefs = 1
+  \parskip = 3pt plus 2pt minus 1pt
+  \textleading = 13.2pt
+  %
+  % Double-side printing via postscript on Laserjet 4050
+  % prints double-sided nicely when \bindingoffset=10mm and \hoffset=-6mm.
+  % To change the settings for a different printer or situation, adjust
+  % \normaloffset until the front-side and back-side texts align.  Then
+  % do the same for \bindingoffset.  You can set these for testing in
+  % your texinfo source file like this:
+  % @tex
+  % \global\normaloffset = -6mm
+  % \global\bindingoffset = 10mm
+  % @end tex
+  \internalpagesizes{673.2pt}{160mm}% that's 51 lines
+                    {\voffset}{\hoffset}%
+                    {\bindingoffset}{44pt}%
+                    {297mm}{210mm}%
+  %
+  \tolerance = 700
+  \hfuzz = 1pt
+  \contentsrightmargin = 0pt
+  \defbodyindent = 5mm
+}}
+
+% Use @afivepaper to print on European A5 paper.
+% From romildo@urano.iceb.ufop.br, 2 July 2000.
+% He also recommends making @example and @lisp be small.
+\def\afivepaper{{\globaldefs = 1
+  \parskip = 2pt plus 1pt minus 0.1pt
+  \textleading = 12.5pt
+  %
+  \internalpagesizes{160mm}{120mm}%
+                    {\voffset}{\hoffset}%
+                    {\bindingoffset}{8pt}%
+                    {210mm}{148mm}%
+  %
+  \lispnarrowing = 0.2in
+  \tolerance = 800
+  \hfuzz = 1.2pt
+  \contentsrightmargin = 0pt
+  \defbodyindent = 2mm
+  \tableindent = 12mm
+}}
+
+% A specific text layout, 24x15cm overall, intended for A4 paper.
+\def\afourlatex{{\globaldefs = 1
+  \afourpaper
+  \internalpagesizes{237mm}{150mm}%
+                    {\voffset}{4.6mm}%
+                    {\bindingoffset}{7mm}%
+                    {297mm}{210mm}%
+  %
+  % Must explicitly reset to 0 because we call \afourpaper.
+  \globaldefs = 0
+}}
+
+% Use @afourwide to print on A4 paper in landscape format.
+\def\afourwide{{\globaldefs = 1
+  \afourpaper
+  \internalpagesizes{241mm}{165mm}%
+                    {\voffset}{-2.95mm}%
+                    {\bindingoffset}{7mm}%
+                    {297mm}{210mm}%
+  \globaldefs = 0
+}}
+
+% @pagesizes TEXTHEIGHT[,TEXTWIDTH]
+% Perhaps we should allow setting the margins, \topskip, \parskip,
+% and/or leading, also. Or perhaps we should compute them somehow.
+%
+\parseargdef\pagesizes{\pagesizesyyy #1,,\finish}
+\def\pagesizesyyy#1,#2,#3\finish{{%
+  \setbox0 = \hbox{\ignorespaces #2}\ifdim\wd0 > 0pt \hsize=#2\relax \fi
+  \globaldefs = 1
+  %
+  \parskip = 3pt plus 2pt minus 1pt
+  \setleading{\textleading}%
+  %
+  \dimen0 = #1\relax
+  \advance\dimen0 by \voffset
+  %
+  \dimen2 = \hsize
+  \advance\dimen2 by \normaloffset
+  %
+  \internalpagesizes{#1}{\hsize}%
+                    {\voffset}{\normaloffset}%
+                    {\bindingoffset}{44pt}%
+                    {\dimen0}{\dimen2}%
+}}
+
+% Set default to letter.
+%
+\letterpaper
+
+
+\message{and turning on texinfo input format.}
+
+% DEL is a comment character, in case @c does not suffice.
+\catcode`\^^? = 14
+
+% Define macros to output various characters with catcode for normal text.
+\catcode`\"=\other
+\catcode`\~=\other
+\catcode`\^=\other
+\catcode`\_=\other
+\catcode`\|=\other
+\catcode`\<=\other
+\catcode`\>=\other
+\catcode`\+=\other
+\catcode`\$=\other
+\def\normaldoublequote{"}
+\def\normaltilde{~}
+\def\normalcaret{^}
+\def\normalunderscore{_}
+\def\normalverticalbar{|}
+\def\normalless{<}
+\def\normalgreater{>}
+\def\normalplus{+}
+\def\normaldollar{$}%$ font-lock fix
+
+% This macro is used to make a character print one way in \tt
+% (where it can probably be output as-is), and another way in other fonts,
+% where something hairier probably needs to be done.
+%
+% #1 is what to print if we are indeed using \tt; #2 is what to print
+% otherwise.  Since all the Computer Modern typewriter fonts have zero
+% interword stretch (and shrink), and it is reasonable to expect all
+% typewriter fonts to have this, we can check that font parameter.
+%
+\def\ifusingtt#1#2{\ifdim \fontdimen3\font=0pt #1\else #2\fi}
+
+% Same as above, but check for italic font.  Actually this also catches
+% non-italic slanted fonts since it is impossible to distinguish them from
+% italic fonts.  But since this is only used by $ and it uses \sl anyway
+% this is not a problem.
+\def\ifusingit#1#2{\ifdim \fontdimen1\font>0pt #1\else #2\fi}
+
+% Turn off all special characters except @
+% (and those which the user can use as if they were ordinary).
+% Most of these we simply print from the \tt font, but for some, we can
+% use math or other variants that look better in normal text.
+
+\catcode`\"=\active
+\def\activedoublequote{{\tt\char34}}
+\let"=\activedoublequote
+\catcode`\~=\active
+\def~{{\tt\char126}}
+\chardef\hat=`\^
+\catcode`\^=\active
+\def^{{\tt \hat}}
+
+\catcode`\_=\active
+\def_{\ifusingtt\normalunderscore\_}
+\let\realunder=_
+% Subroutine for the previous macro.
+\def\_{\leavevmode \kern.07em \vbox{\hrule width.3em height.1ex}\kern .07em }
+
+\catcode`\|=\active
+\def|{{\tt\char124}}
+\chardef \less=`\<
+\catcode`\<=\active
+\def<{{\tt \less}}
+\chardef \gtr=`\>
+\catcode`\>=\active
+\def>{{\tt \gtr}}
+\catcode`\+=\active
+\def+{{\tt \char 43}}
+\catcode`\$=\active
+\def${\ifusingit{{\sl\$}}\normaldollar}%$ font-lock fix
+
+% If a .fmt file is being used, characters that might appear in a file
+% name cannot be active until we have parsed the command line.
+% So turn them off again, and have \everyjob (or @setfilename) turn them on.
+% \otherifyactive is called near the end of this file.
+\def\otherifyactive{\catcode`+=\other \catcode`\_=\other}
+
+% Used sometimes to turn off (effectively) the active characters even after
+% parsing them.
+\def\turnoffactive{%
+  \normalturnoffactive
+  \otherbackslash
+}
+
+\catcode`\@=0
+
+% \backslashcurfont outputs one backslash character in current font,
+% as in \char`\\.
+\global\chardef\backslashcurfont=`\\
+\global\let\rawbackslashxx=\backslashcurfont  % let existing .??s files work
+
+% \realbackslash is an actual character `\' with catcode other, and
+% \doublebackslash is two of them (for the pdf outlines).
+{\catcode`\\=\other @gdef@realbackslash{\} @gdef@doublebackslash{\\}}
+
+% In texinfo, backslash is an active character; it prints the backslash
+% in fixed width font.
+\catcode`\\=\active
+@def@normalbackslash{{@tt@backslashcurfont}}
+% On startup, @fixbackslash assigns:
+%  @let \ = @normalbackslash
+
+% \rawbackslash defines an active \ to do \backslashcurfont.
+% \otherbackslash defines an active \ to be a literal `\' character with
+% catcode other.
+@gdef@rawbackslash{@let\=@backslashcurfont}
+@gdef@otherbackslash{@let\=@realbackslash}
+
+% Same as @turnoffactive except outputs \ as {\tt\char`\\} instead of
+% the literal character `\'.
+%
+@def@normalturnoffactive{%
+  @let\=@normalbackslash
+  @let"=@normaldoublequote
+  @let~=@normaltilde
+  @let^=@normalcaret
+  @let_=@normalunderscore
+  @let|=@normalverticalbar
+  @let<=@normalless
+  @let>=@normalgreater
+  @let+=@normalplus
+  @let$=@normaldollar %$ font-lock fix
+  @markupsetuplqdefault
+  @markupsetuprqdefault
+  @unsepspaces
+}
+
+% Make _ and + \other characters, temporarily.
+% This is canceled by @fixbackslash.
+@otherifyactive
+
+% If a .fmt file is being used, we don't want the `\input texinfo' to show up.
+% That is what \eatinput is for; after that, the `\' should revert to printing
+% a backslash.
+%
+@gdef@eatinput input texinfo{@fixbackslash}
+@global@let\ = @eatinput
+
+% On the other hand, perhaps the file did not have a `\input texinfo'. Then
+% the first `\' in the file would cause an error. This macro tries to fix
+% that, assuming it is called before the first `\' could plausibly occur.
+% Also turn back on active characters that might appear in the input
+% file name, in case not using a pre-dumped format.
+%
+@gdef@fixbackslash{%
+  @ifx\@eatinput @let\ = @normalbackslash @fi
+  @catcode`+=@active
+  @catcode`@_=@active
+}
+
+% Say @foo, not \foo, in error messages.
+@escapechar = `@@
+
+% These look ok in all fonts, so just make them not special.
+@catcode`@& = @other
+@catcode`@# = @other
+@catcode`@% = @other
+
+@c Finally, make ` and ' active, so that txicodequoteundirected and
+@c txicodequotebacktick work right in, e.g., @w{@code{`foo'}}.  If we
+@c don't make ` and ' active, @code will not get them as active chars.
+@c Do this last of all since we use ` in the previous @catcode assignments.
+@catcode`@'=@active
+@catcode`@`=@active
+@markupsetuplqdefault
+@markupsetuprqdefault
+
+@c Local variables:
+@c eval: (add-hook 'write-file-hooks 'time-stamp)
+@c page-delimiter: "^\\\\message"
+@c time-stamp-start: "def\\\\texinfoversion{"
+@c time-stamp-format: "%:y-%02m-%02d.%02H"
+@c time-stamp-end: "}"
+@c End:
+
+@c vim:sw=2:
+
+@ignore
+   arch-tag: e1b36e32-c96e-4135-a41a-0b2efa2ea115
+@end ignore