diff options
| author | Joshua Sumali <jsumali@redhat.com> | 2008-05-27 19:25:27 +0000 |
|---|---|---|
| committer | Joshua Sumali <jsumali@redhat.com> | 2008-05-27 19:25:27 +0000 |
| commit | b982843cf69bc9e8bfa4aa26beffd2c71f7282f6 (patch) | |
| tree | be1f2467b9d6c9be2b85c75c3c81bf601365b69d /doc | |
| parent | 295c1e3a4c0a05d30e874beacdf528437098e25d (diff) | |
| download | classpath-b982843cf69bc9e8bfa4aa26beffd2c71f7282f6.tar.gz | |
2008-05-27 Joshua Sumali <jsumali@redhat.com>
* configure.ac: Add support for Antlr. This is used for building gjdoc.
Also generate tools/gjdoc wrapper with gjdoc.in.
* doc/gjdoc.texi: New file.
* doc/invoke.texi: New file.
* doc/Makefile.am: Generate gjdoc documentation.
* m4/ac_prog_antlr.m4: New file.
* m4/ac_prog_java.m4: New file.
* m4/ac_prog_java_works.m4: New file.
* tools/Makefile.am: Build gjdoc as part of tools.
* tools/com/sun/tools/javadoc/Main.java,
* tools/gjdoc.in,
* tools/gnu/classpath/tools/doclets/AbstractDoclet.java,
* tools/gnu/classpath/tools/doclets/.cvsignore,
* tools/gnu/classpath/tools/doclets/debugdoclet/.cvsignore,
* tools/gnu/classpath/tools/doclets/debugdoclet/DebugDoclet.java,
* tools/gnu/classpath/tools/doclets/DocletConfigurationException.java,
* tools/gnu/classpath/tools/doclets/DocletOptionColonSeparated.java,
* tools/gnu/classpath/tools/doclets/DocletOptionFile.java,
* tools/gnu/classpath/tools/doclets/DocletOptionFlag.java,
* tools/gnu/classpath/tools/doclets/DocletOption.java,
* tools/gnu/classpath/tools/doclets/DocletOptionPackageWildcard.java,
* tools/gnu/classpath/tools/doclets/DocletOptionString.java,
* tools/gnu/classpath/tools/doclets/htmldoclet/CssClass.java,
* tools/gnu/classpath/tools/doclets/htmldoclet/.cvsignore,
* tools/gnu/classpath/tools/doclets/htmldoclet/ExternalDocSet.java,
* tools/gnu/classpath/tools/doclets/htmldoclet/HtmlDoclet.java,
* tools/gnu/classpath/tools/doclets/htmldoclet/HtmlPage.java,
* tools/gnu/classpath/tools/doclets/htmldoclet/HtmlTagletContext.java,
* tools/gnu/classpath/tools/doclets/InlineTagRenderer.java,
* tools/gnu/classpath/tools/doclets/InvalidPackageWildcardException.java,
* tools/gnu/classpath/tools/doclets/PackageGroup.java,
* tools/gnu/classpath/tools/doclets/PackageMatcher.java,
* tools/gnu/classpath/tools/doclets/StandardTaglet.java,
* tools/gnu/classpath/tools/doclets/TagletPrinter.java,
* tools/gnu/classpath/tools/doclets/xmldoclet/.cvsignore,
* tools/gnu/classpath/tools/doclets/xmldoclet/doctranslet/.cvsignore,
* tools/gnu/classpath/tools/doclets/xmldoclet/doctranslet/DocTransletConfigurationException.java,
* tools/gnu/classpath/tools/doclets/xmldoclet/doctranslet/DocTransletException.java,
* tools/gnu/classpath/tools/doclets/xmldoclet/doctranslet/DocTranslet.java,
* tools/gnu/classpath/tools/doclets/xmldoclet/doctranslet/DocTransletOptions.java,
* tools/gnu/classpath/tools/doclets/xmldoclet/doctranslet/JarClassLoader.java,
* tools/gnu/classpath/tools/doclets/xmldoclet/doctranslet/OutputFileInfo.java,
* tools/gnu/classpath/tools/doclets/xmldoclet/doctranslet/package.html,
* tools/gnu/classpath/tools/doclets/xmldoclet/Driver1_4.java,
* tools/gnu/classpath/tools/doclets/xmldoclet/Driver.java,
* tools/gnu/classpath/tools/doclets/xmldoclet/HtmlRepairer.java,
* tools/gnu/classpath/tools/doclets/xmldoclet/TargetContext.java,
* tools/gnu/classpath/tools/FileSystemClassLoader.java,
* tools/gnu/classpath/tools/gjdoc/AbstractTagImpl.java,
* tools/gnu/classpath/tools/gjdoc/ArrayCharacterIterator.java,
* tools/gnu/classpath/tools/gjdoc/ClassDocImpl.java,
* tools/gnu/classpath/tools/gjdoc/ClassDocProxy.java,
* tools/gnu/classpath/tools/gjdoc/ClassDocReflectedImpl.java,
* tools/gnu/classpath/tools/gjdoc/ConstructorDocImpl.java,
* tools/gnu/classpath/tools/gjdoc/.cvsignore,
* tools/gnu/classpath/tools/gjdoc/Debug.java,
* tools/gnu/classpath/tools/gjdoc/DirectoryTree.java,
* tools/gnu/classpath/tools/gjdoc/DocImpl.java,
* tools/gnu/classpath/tools/gjdoc/ErrorReporter.java,
* tools/gnu/classpath/tools/gjdoc/ExecutableMemberDocImpl.java,
* tools/gnu/classpath/tools/gjdoc/expr/AdditionExpression.java,
* tools/gnu/classpath/tools/gjdoc/expr/AndExpression.java,
* tools/gnu/classpath/tools/gjdoc/expr/BinaryBitwiseExpression.java,
* tools/gnu/classpath/tools/gjdoc/expr/BinaryComputationExpression.java,
* tools/gnu/classpath/tools/gjdoc/expr/BinaryEqualityExpression.java,
* tools/gnu/classpath/tools/gjdoc/expr/BinaryExpression.java,
* tools/gnu/classpath/tools/gjdoc/expr/BinaryLogicalExpression.java,
* tools/gnu/classpath/tools/gjdoc/expr/BinaryRelationExpression.java,
* tools/gnu/classpath/tools/gjdoc/expr/BinaryShiftExpression.java,
* tools/gnu/classpath/tools/gjdoc/expr/BitShiftRightExpression.java,
* tools/gnu/classpath/tools/gjdoc/expr/CircularExpressionException.java,
* tools/gnu/classpath/tools/gjdoc/expr/ConditionalExpression.java,
* tools/gnu/classpath/tools/gjdoc/expr/ConstantBoolean.java,
* tools/gnu/classpath/tools/gjdoc/expr/ConstantByte.java,
* tools/gnu/classpath/tools/gjdoc/expr/ConstantChar.java,
* tools/gnu/classpath/tools/gjdoc/expr/ConstantDouble.java,
* tools/gnu/classpath/tools/gjdoc/expr/ConstantExpression.java,
* tools/gnu/classpath/tools/gjdoc/expr/ConstantFloat.java,
* tools/gnu/classpath/tools/gjdoc/expr/ConstantInteger.java,
* tools/gnu/classpath/tools/gjdoc/expr/ConstantLong.java,
* tools/gnu/classpath/tools/gjdoc/expr/ConstantNull.java,
* tools/gnu/classpath/tools/gjdoc/expr/ConstantShort.java,
* tools/gnu/classpath/tools/gjdoc/expr/ConstantString.java,
* tools/gnu/classpath/tools/gjdoc/expr/Context.java,
* tools/gnu/classpath/tools/gjdoc/expr/.cvsignore,
* tools/gnu/classpath/tools/gjdoc/expr/DivisionExpression.java,
* tools/gnu/classpath/tools/gjdoc/expr/EqualExpression.java,
* tools/gnu/classpath/tools/gjdoc/expr/EvaluatorEnvironment.java,
* tools/gnu/classpath/tools/gjdoc/expr/Evaluator.java,
* tools/gnu/classpath/tools/gjdoc/expr/ExclusiveOrExpression.java,
* tools/gnu/classpath/tools/gjdoc/expr/Expression.java,
* tools/gnu/classpath/tools/gjdoc/expr/GreaterThanExpression.java,
* tools/gnu/classpath/tools/gjdoc/expr/GreaterThanOrEqualExpression.java,
* tools/gnu/classpath/tools/gjdoc/expr/IdentifierExpression.java,
* tools/gnu/classpath/tools/gjdoc/expr/IllegalExpressionException.java,
* tools/gnu/classpath/tools/gjdoc/expr/InclusiveOrExpression.java,
* tools/gnu/classpath/tools/gjdoc/expr/java-expression.g,
* tools/gnu/classpath/tools/gjdoc/expr/LessThanExpression.java,
* tools/gnu/classpath/tools/gjdoc/expr/LessThanOrEqualExpression.java,
* tools/gnu/classpath/tools/gjdoc/expr/LogicalAndExpression.java,
* tools/gnu/classpath/tools/gjdoc/expr/LogicalNotExpression.java,
* tools/gnu/classpath/tools/gjdoc/expr/LogicalOrExpression.java,
* tools/gnu/classpath/tools/gjdoc/expr/ModuloExpression.java,
* tools/gnu/classpath/tools/gjdoc/expr/MultiplicationExpression.java,
* tools/gnu/classpath/tools/gjdoc/expr/NegateExpression.java,
* tools/gnu/classpath/tools/gjdoc/expr/NotEqualExpression.java,
* tools/gnu/classpath/tools/gjdoc/expr/NotExpression.java,
* tools/gnu/classpath/tools/gjdoc/expr/ShiftLeftExpression.java,
* tools/gnu/classpath/tools/gjdoc/expr/ShiftRightExpression.java,
* tools/gnu/classpath/tools/gjdoc/expr/SubtractionExpression.java,
* tools/gnu/classpath/tools/gjdoc/expr/TypeCastExpression.java,
* tools/gnu/classpath/tools/gjdoc/expr/Type.java,
* tools/gnu/classpath/tools/gjdoc/expr/UnaryExpression.java,
* tools/gnu/classpath/tools/gjdoc/expr/UnknownIdentifierException.java,
* tools/gnu/classpath/tools/gjdoc/FieldDocImpl.java,
* tools/gnu/classpath/tools/gjdoc/GjdocPackageDoc.java,
* tools/gnu/classpath/tools/gjdoc/GjdocRootDoc.java,
* tools/gnu/classpath/tools/gjdoc/InheritDocTagImpl.java,
* tools/gnu/classpath/tools/gjdoc/JavadocWrapper.java,
* tools/gnu/classpath/tools/gjdoc/LinkTagImpl.java,
* tools/gnu/classpath/tools/gjdoc/Main.java,
* tools/gnu/classpath/tools/gjdoc/MemberDocImpl.java,
* tools/gnu/classpath/tools/gjdoc/MethodDocImpl.java,
* tools/gnu/classpath/tools/gjdoc/PackageDocImpl.java,
* tools/gnu/classpath/tools/gjdoc/ParameterImpl.java,
* tools/gnu/classpath/tools/gjdoc/ParamTagImpl.java,
* tools/gnu/classpath/tools/gjdoc/ParseException.java,
* tools/gnu/classpath/tools/gjdoc/Parser.java,
* tools/gnu/classpath/tools/gjdoc/ProgramElementDocImpl.java,
* tools/gnu/classpath/tools/gjdoc/RootDocImpl.java,
* tools/gnu/classpath/tools/gjdoc/SeeTagImpl.java,
* tools/gnu/classpath/tools/gjdoc/SerialFieldTagImpl.java,
* tools/gnu/classpath/tools/gjdoc/SourcePositionImpl.java,
* tools/gnu/classpath/tools/gjdoc/TagContainer.java,
* tools/gnu/classpath/tools/gjdoc/TagImpl.java,
* tools/gnu/classpath/tools/gjdoc/TemporaryStore.java,
* tools/gnu/classpath/tools/gjdoc/TextTagImpl.java,
* tools/gnu/classpath/tools/gjdoc/ThrowsTagImpl.java,
* tools/gnu/classpath/tools/gjdoc/TimerDoclet.java,
* tools/gnu/classpath/tools/gjdoc/Timer.java,
* tools/gnu/classpath/tools/gjdoc/TypeImpl.java,
* tools/gnu/classpath/tools/gjdoc/TypeVariableImpl.java,
* tools/gnu/classpath/tools/gjdoc/ValueTagImpl.java,
* tools/gnu/classpath/tools/gjdoc/WritableType.java,
* tools/gnu/classpath/tools/IOToolkit.java,
* tools/gnu/classpath/tools/java2xhtml/.cvsignore,
* tools/gnu/classpath/tools/java2xhtml/Java2xhtml.java,
* tools/gnu/classpath/tools/MalformedInputEvent.java,
* tools/gnu/classpath/tools/MalformedInputListener.java,
* tools/gnu/classpath/tools/NotifyingInputStreamReader.java,
* tools/gnu/classpath/tools/StringToolkit.java,
* tools/gnu/classpath/tools/taglets/AuthorTaglet.java,
* tools/gnu/classpath/tools/taglets/CodeTaglet.java,
* tools/gnu/classpath/tools/taglets/CopyrightTaglet.java,
* tools/gnu/classpath/tools/taglets/.cvsignore,
* tools/gnu/classpath/tools/taglets/DeprecatedTaglet.java,
* tools/gnu/classpath/tools/taglets/GenericTaglet.java,
* tools/gnu/classpath/tools/taglets/GnuExtendedTaglet.java,
* tools/gnu/classpath/tools/taglets/SinceTaglet.java,
* tools/gnu/classpath/tools/taglets/TagletContext.java,
* tools/gnu/classpath/tools/taglets/ValueTaglet.java,
* tools/gnu/classpath/tools/taglets/VersionTaglet.java,
* tools/resource/gnu/classpath/tools/gjdoc/doctranslets/gjdoc_common.xsl,
* tools/resource/gnu/classpath/tools/gjdoc/doctranslets/html/about.xsl,
* tools/resource/gnu/classpath/tools/gjdoc/doctranslets/html/allclasses.xsl,
* tools/resource/gnu/classpath/tools/gjdoc/doctranslets/html/allpackages.xsl,
* tools/resource/gnu/classpath/tools/gjdoc/doctranslets/html/alphaindex_chunked.xsl,
* tools/resource/gnu/classpath/tools/gjdoc/doctranslets/html/alphaindex.xsl,
* tools/resource/gnu/classpath/tools/gjdoc/doctranslets/html/classdoc-source.xsl,
* tools/resource/gnu/classpath/tools/gjdoc/doctranslets/html/classdoc-uses.xsl,
* tools/resource/gnu/classpath/tools/gjdoc/doctranslets/html/classdoc.xsl,
* tools/resource/gnu/classpath/tools/gjdoc/doctranslets/html/deprecated.xsl,
* tools/resource/gnu/classpath/tools/gjdoc/doctranslets/html/descriptor.xsl,
* tools/resource/gnu/classpath/tools/gjdoc/doctranslets/html/doctranslet.xsl,
* tools/resource/gnu/classpath/tools/gjdoc/doctranslets/html/fulltree.xsl,
* tools/resource/gnu/classpath/tools/gjdoc/doctranslets/html/gjdoc.xsl,
* tools/resource/gnu/classpath/tools/gjdoc/doctranslets/html/help.xsl,
* tools/resource/gnu/classpath/tools/gjdoc/doctranslets/html/html_common.xsl,
* tools/resource/gnu/classpath/tools/gjdoc/doctranslets/html/index_noframes.xsl,
* tools/resource/gnu/classpath/tools/gjdoc/doctranslets/html/index.xsl,
* tools/resource/gnu/classpath/tools/gjdoc/doctranslets/html/packageclasses.xsl,
* tools/resource/gnu/classpath/tools/gjdoc/doctranslets/html/packagedoc.xsl,
* tools/resource/gnu/classpath/tools/gjdoc/doctranslets/html/res/default_help_en.html,
* tools/resource/gnu/classpath/tools/gjdoc/doctranslets/html/res/gjdochtml-clean.css,
* tools/resource/gnu/classpath/tools/gjdoc/doctranslets/html/res/gjdochtml.css,
* tools/resource/gnu/classpath/tools/gjdoc/doctranslets/html/res/gjdochtml-fixed.css,
* tools/resource/gnu/classpath/tools/gjdoc/doctranslets/html/res/gjdochtml-sclara.css,
* tools/resource/gnu/classpath/tools/gjdoc/doctranslets/html/res/gjdoc.js,
* tools/resource/gnu/classpath/tools/gjdoc/doctranslets/html/serialized.xsl,
* tools/resource/gnu/classpath/tools/gjdoc/dtd/dbcentx.mod,
* tools/resource/gnu/classpath/tools/gjdoc/dtd/ent/iso-amsa.ent,
* tools/resource/gnu/classpath/tools/gjdoc/dtd/ent/iso-amsb.ent,
* tools/resource/gnu/classpath/tools/gjdoc/dtd/ent/iso-amsc.ent,
* tools/resource/gnu/classpath/tools/gjdoc/dtd/ent/iso-amsn.ent,
* tools/resource/gnu/classpath/tools/gjdoc/dtd/ent/iso-amso.ent,
* tools/resource/gnu/classpath/tools/gjdoc/dtd/ent/iso-amsr.ent,
* tools/resource/gnu/classpath/tools/gjdoc/dtd/ent/iso-box.ent,
* tools/resource/gnu/classpath/tools/gjdoc/dtd/ent/iso-cyr1.ent,
* tools/resource/gnu/classpath/tools/gjdoc/dtd/ent/iso-cyr2.ent,
* tools/resource/gnu/classpath/tools/gjdoc/dtd/ent/iso-dia.ent,
* tools/resource/gnu/classpath/tools/gjdoc/dtd/ent/iso-grk1.ent,
* tools/resource/gnu/classpath/tools/gjdoc/dtd/ent/iso-grk2.ent,
* tools/resource/gnu/classpath/tools/gjdoc/dtd/ent/iso-grk3.ent,
* tools/resource/gnu/classpath/tools/gjdoc/dtd/ent/iso-grk4.ent,
* tools/resource/gnu/classpath/tools/gjdoc/dtd/ent/iso-lat1.ent,
* tools/resource/gnu/classpath/tools/gjdoc/dtd/ent/iso-lat2.ent,
* tools/resource/gnu/classpath/tools/gjdoc/dtd/ent/iso-num.ent,
* tools/resource/gnu/classpath/tools/gjdoc/dtd/ent/iso-pub.ent,
* tools/resource/gnu/classpath/tools/gjdoc/dtd/ent/iso-tech.ent,
* tools/resource/gnu/classpath/tools/gjdoc/dtd/gjdoc-alphaindex.dtd,
* tools/resource/gnu/classpath/tools/gjdoc/dtd/gjdoc.dtd,
* tools/resource/gnu/classpath/tools/gjdoc/htmldoclet/gjdochtml-clean-color1.css,
* tools/resource/gnu/classpath/tools/gjdoc/htmldoclet/gjdochtml-clean-layout.css,
* tools/resource/gnu/classpath/tools/gjdoc/htmldoclet/gjdochtml-vanilla.css,
* tools/resource/gnu/classpath/tools/gjdoc/htmldoclet/gjdoc.js,
* tools/resource/gnu/classpath/tools/gjdoc/htmldoclet/help.xhtml,
* tools/resource/gnu/classpath/tools/gjdoc/htmldoclet/HtmlDoclet.properties,
* tools/resource/gnu/classpath/tools/gjdoc/htmldoclet/xhtml11-target10.dtd,
* tools/resource/gnu/classpath/tools/gjdoc/java.lang-classes-1.2.txt,
* tools/resource/gnu/classpath/tools/gjdoc/java.lang-classes-1.3.txt,
* tools/resource/gnu/classpath/tools/gjdoc/java.lang-classes-1.4.txt,
* tools/resource/gnu/classpath/tools/gjdoc/java.lang-classes-1.5.txt,
* tools/resource/gnu/classpath/tools/gjdoc/rng/gjdoc-classdoc.rng,
* tools/resource/gnu/classpath/tools/gjdoc/rng/gjdoc-common.rng,
* tools/resource/gnu/classpath/tools/gjdoc/rng/gjdoc-index.rng,
* tools/resource/gnu/classpath/tools/gjdoc/version.properties,
* tools/resource/gnu/classpath/tools/gjdoc/version.properties.in:
New files, taken from gjdoc source tree.
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Makefile.am | 8 | ||||
| -rw-r--r-- | doc/gjdoc.texi | 210 | ||||
| -rw-r--r-- | doc/invoke.texi | 1428 |
3 files changed, 1644 insertions, 2 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am index e2d1db706..f61af6d2c 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -25,7 +25,8 @@ TOOLS_MANFILES = \ grmid.1 \ grmiregistry.1 \ gserialver.1 \ - gtnameserv.1 + gtnameserv.1 \ + gjdoc.1 POD2MAN = pod2man --center="GNU" --release="$(VERSION)" TEXI2POD = perl $(srcdir)/texi2pod.pl @@ -39,7 +40,7 @@ STAMP = echo timestamp > .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 + gserialver.pod gtnameserv.pod gcjh.pod gjdoc.pod gappletviewer.pod: $(srcdir)/cp-tools.texinfo -$(TEXI2POD) -D gappletviewer < $< > $@ @@ -81,5 +82,8 @@ gserialver.pod: $(srcdir)/cp-tools.texinfo gtnameserv.pod: $(srcdir)/cp-tools.texinfo -$(TEXI2POD) -D gtnameserv < $< > $@ +gjdoc.pod: $(srcdir)/invoke.texi + -$(TEXI2POD) -D gjdoc < $< > $@ + CLEANFILES = $(TOOLS_MANFILES) diff --git a/doc/gjdoc.texi b/doc/gjdoc.texi new file mode 100644 index 000000000..bf3ad4a11 --- /dev/null +++ b/doc/gjdoc.texi @@ -0,0 +1,210 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename gjdoc.info +@c INTERNALS is used by md.texi to determine whether to include the +@c whole of that file, in the internals manual, or only the part +@c dealing with constraints, in the user manual. +@clear INTERNALS + +@c NOTE: checks/things to do: +@c +@c -have bob do a search in all seven files for "mew" (ideally --mew, +@c but i may have forgotten the occasional "--"..). +@c Just checked... all have `--'! Bob 22Jul96 +@c Use this to search: grep -n '\-\-mew' *.texi +@c -item/itemx, text after all (sub/sub)section titles, etc.. +@c -consider putting the lists of options on pp 17--> etc in columns or +@c some such. +@c -overfulls. do a search for "mew" in the files, and you will see +@c overfulls that i noted but could not deal with. +@c -have to add text: beginning of chapter 8 + +@c +@c anything else? --mew 10feb93 + +@include gcc-common.texi +@include version.texi + +@settitle Using the Gjdoc Documentation System + +@c Create a separate index for command line options. +@defcodeindex op +@c Merge the standard indexes into a single one. +@syncodeindex fn cp +@syncodeindex vr cp +@syncodeindex ky cp +@syncodeindex pg cp +@syncodeindex tp cp + +@paragraphindent 1 + +@c %**end of header + +@copying +Copyright @copyright{} 2005 Free Software Foundation, Inc. + +This documentation is dual-licensed under the GNU Free Documentation +License and the GNU General Public License. + +@table @emph +@item GNU Free Documentation License + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.2 or +any later version published by the Free Software Foundation; with the +Invariant Sections being ``GNU General Public License'' and ``Funding +Free Software'', the Front-Cover texts being (a) (see below), and with +the Back-Cover Texts being (b) (see below). A copy of the license is +included in the section entitled ``GNU Free Documentation License''. + +(a) The FSF's Front-Cover Text is: + + A GNU Manual + +(b) The FSF's Back-Cover Text is: + + You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. + +@item GNU General Public License + +This program is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program; if not, write to the Free Software Foundation, +Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. + +@end table +@end copying +@ifnottex +@dircategory Programming +@direntry +* gcc: (gcc). The GNU Compiler Collection. +@end direntry +This file documents the use of the Gjdoc Java documentation framework. +@sp 1 +@insertcopying +@sp 1 +@end ifnottex + +@setchapternewpage odd +@c @shorttitlepage Using Gjdoc +@titlepage +@center @titlefont{Using Gjdoc} +@sp 2 +@center @subtitlefont{A Documentation Generation Framework for Java Source Files} +@sp 3 +@center Last updated 17 Feb 2005 +@sp 1 + +@center for Gjdoc @value{VERSION} +@page +@vskip 0pt plus 1filll +For Gjdoc Version @value{VERSION}@* +@sp 1 +@c Published by: +@c @multitable @columnfractions 0.5 0.5 +@c @item GNU Press +@c @tab Website: www.gnupress.org +@c @item a division of the +@c @tab General: @tex press@@gnu.org @end tex +@c @item Free Software Foundation +@c @tab Orders: @tex sales@@gnu.org @end tex +@c @item 59 Temple Place Suite 330 +@c @tab Tel 617-542-5942 +@c @item Boston, MA 02111-1307 USA +@c @tab Fax 617-542-2652 +@c @end multitable +@c @sp 2 +@c @ifset FSFPRINT +@c Update this ISBN when printing a new edition. +@c @acronym{ISBN} 1-882114-39-6 +@c +@c Cover art by Gary M. Torrisi. Cover design by Jonathan Richard. +@c @end ifset +@c @ifclear FSFPRINT +@c Last printed October 2003 for GCC 3.3.1.@* +@c Printed copies are available for $45 each. +@c @end ifclear +@c @sp 1 +@insertcopying +@end titlepage +@summarycontents +@contents +@page + +@node Top,,, (DIR) +@top Introduction +@cindex introduction + +This manual documents how to use the Gjdoc documentation framework. +It corresponds to Gjdoc version @value{VERSION}. + +@menu +* Invoking Gjdoc:: Command options supported by @samp{gjdoc}. +* Other Doclets:: Using Doclets other than the Standard Doclet. +* Gjdoc Concepts:: Concepts of the Gjdoc Documentation Framework. +* Option Index:: Index to command line options. +* Keyword Index:: Index of concepts and symbol names. + +* License:: Conditions for using and copying this documentation. +@end menu + +@include invoke.texi + +@node License +@unnumbered License +@cindex license + +This documentation is dual-licensed under the GNU Free Documentation +License and the GNU General Public License. + +@menu +* GNU Free Documentation License:: +* GNU General Public License:: +@end menu + +@lowersections +@include gpl.texi +@include fdl.texi +@raisesections + +@c --------------------------------------------------------------------- +@c GFDL +@c --------------------------------------------------------------------- + +@c @include fdl.texi + +@c @include contrib.texi + +@c --------------------------------------------------------------------- +@c Indexes +@c --------------------------------------------------------------------- + +@node Option Index +@unnumbered Option Index + +Gjdoc's command line options are indexed here without any initial @samp{-} +or @samp{--}. + +@printindex op + +@node Keyword Index +@unnumbered Keyword Index + +@printindex cp + +@c --------------------------------------------------------------------- +@c Epilogue +@c --------------------------------------------------------------------- + +@bye diff --git a/doc/invoke.texi b/doc/invoke.texi new file mode 100644 index 000000000..806066017 --- /dev/null +++ b/doc/invoke.texi @@ -0,0 +1,1428 @@ +@c Copyright (C) 2005 Free Software Foundation, Inc. +@c For copying conditions, see the file gjdoc.texi. + +@ignore +@c man begin COPYRIGHT +Copyright @copyright{} 2005 Free Software Foundation, Inc. + +This documentation is dual-licensed under the GNU Free Documentation +License and the GNU General Public License. + +@table @emph +@item GNU Free Documentation License + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.2 or +any later version published by the Free Software Foundation; with the +Invariant Sections being ``GNU General Public License'' and ``Funding +Free Software'', the Front-Cover texts being (a) (see below), and with +the Back-Cover Texts being (b) (see below). A copy of the license is +included in the section entitled ``GNU Free Documentation License''. + +(a) The FSF's Front-Cover Text is: + + A GNU Manual + +(b) The FSF's Back-Cover Text is: + + You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation + raise funds for GNU development. + +@item GNU General Public License + +This program is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2 of the License, or (at +your option) any later version. + +This program is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program; if not, write to the Free Software +Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, +USA. + +@end table +@c man end +@c Set file name and title for the man page. +@setfilename gjdoc +@settitle Documentation generation framework for Java source files. +@c man begin SYNOPSIS +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 +@c man begin SEEALSO +Info entry for @file{gjdoc}. +@c man end +@c man begin BUGS +Please report bugs to @w{@uref{http://savannah.gnu.org/bugs/?group=classpath}}. +@c man end +@c man begin AUTHOR +Julian Scheid +@c man end +@end ignore + +@node Invoking Gjdoc +@chapter Generating HTML Documentation +@cindex Gjdoc command options +@cindex command options +@cindex options, Gjdoc command + +@c man begin DESCRIPTION +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:: + +@end menu + +@c man end + +@node Invoking the Standard Doclet +@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}. + +@xref{Option Index}, for an index to Gjdoc's options. + +@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 + +@node Option Summary by Type +@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 @gol + -nosince -notree -public -protected -package -private @gol + -docfilessubdirs -excludedocfilessubdir @var{dirname} @gol + -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} @gol -title @var{text} + -header @var{text} -footer @var{text} -bottom @var{text} @gol + -helpfile @var{file} -stylesheetfile @var{file} -addstylesheet @var{file} @gol + -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} @gccoptlist{-bootclasspath} @gccoptlist{-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 +@section Selecting which Source Files to Process + +@table @gcctabopt +@item -s @var{pathlist} +@item -sourcepath @var{pathlist} +@opindex sourcepath +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 +@opindex 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{}} +@opindex subpackages +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{}} +@opindex exclude +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{} +@opindex packages +Process all classes in the given Java packages. + +@item @var{sourcefiles}@dots{} +@opindex sourcefiles +Process the classes in the given Java source files. +@end table + +@node Source Format Options +@section Specifying the Format of Input Files + +@table @gcctabopt +@item -source @var{release} +@opindex source +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} +@opindex encoding +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 +@opindex 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 +@section Interlinking with other Documentation Sets + +@table @gcctabopt +@item -link @var{url} +@opindex link + +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} +@opindex linkoffline + +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{}} +@opindex noqualifier + +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} +@opindex noqualifier +Omit package name qualifier from all class names. + +Specify this option to omit package name qualifiers altogether, + +@end table + +@node Generation Options +@section Selecting which Information to Generate + +@table @gcctabopt +@item -public +@opindex public +Only include public members of public classes in the output. By +default, protected class members are included as well. + +@item -protected +@opindex protected + +Include public or protected members of public classes in the output. +This is the default. + +@item -package +@opindex package + +Include public, protected and package-private members of public and +package-private classes. + +@item -private +@opindex private + +Include all classes and class members regardless of their access +level. + +@item -splitindex +@opindex 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 +@opindex 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 +@opindex 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 +@opindex 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 +@opindex nohelp +Do not generate the help page. + +This option is currently ignored as the Standard Doclet doesn't +provide a help page. + +@item -nodeprecated +@opindex 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 +@opindex 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 +@opindex 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 +@opindex 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 +@opindex 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 +@opindex 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 +@opindex 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 +@opindex 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 +@opindex 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 +@opindex 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{} +@opindex excludedocfilessubdir + +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 +@section Custom Documentation Tags + +@table @gcctabopt +@item -tagletpath @var{pathlist} +@opindex tagletpath +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} +@opindex taglet +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} +@opindex tag +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: invoke.texi,v 1.1 2008-05-27 19:25:31 jsumali Exp $ +@end smallexample + +Then the HTML output will contain something like + +@smallexample +CVS ID: + $Id: invoke.texi,v 1.1 2008-05-27 19:25:31 jsumali Exp $ +@end smallexample +@end table + +@node Doclet Options +@section Running Other Doclets + +@table @gcctabopt + +@item -docletpath @var{pathlist} +@opindex docletpath +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} +@opindex doclet +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 +@section Adding Information to the Output + +@table @gcctabopt +@item -windowtitle @var{text} +@opindex windowtitle +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} +@opindex doctitle +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} +@opindex header + +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} +@opindex footer + +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} +@opindex bottom + +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} +@opindex addstylesheet + +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{} +@opindex group + +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} +@opindex overview + +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} +@opindex stylesheetfile + +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} +@opindex title + +@emph{Deprecated.} Use @option{-doctitle} @var{text} instead. + +@item -helpfile @var{file} +@opindex helpfile + +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 +@section Controlling the Output. + +@table @gcctabopt +@item -d @var{directory} +@opindex d +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} +@opindex locale + +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} +@opindex 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} +@opindex docencoding + +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 +@opindex 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} +@opindex validhtml + +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 +@section Verbosity Options + +@table @gcctabopt +@item -quiet +@opindex quiet +Suppress all output except for warnings and error messages. + +@item -verbose +@opindex verbose +Be very verbose about what @command{gjdoc} is doing. + +This option is currently ignored. + +@end table + +@node Virtual Machine Options +@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} +@opindex classpath +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} +@opindex bootclasspath +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} +@opindex J + +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 + +@node Invoking a Custom Doclet +@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. + +@node Gjdoc Option Summary +@section Gjdoc Option Summary +@cindex Gjdoc Options + +@node Other Doclets +@chapter Generating Other Output Types + +@menu +* Built-in Doclets:: +* Third-party Doclets:: +@end menu + +@node Built-in Doclets +@section Using the Built-in Doclets +@cindex Built-in Doclets + +@menu +* Using XmlDoclet:: +* Using TexiDoclet:: +* Using IspellDoclet:: +* Using DebugDoclet:: +@end menu + +@node Using TexiDoclet +@subsection TexiDoclet: Generating Info, PDF, and other formats +@cindex TexiDoclet + +Missing. + +@node Using XmlDoclet +@subsection XmlDoclet: Generating XML Documentation +@cindex HtmlDoclet + +Missing. + +@node Using IspellDoclet +@subsection IspellDoclet: Spell-checking Source Code +@cindex IspellDoclet + +Missing. + +@node Using DebugDoclet +@subsection DebugDoclet: Inspecting the Doclet API +@cindex HtmlDoclet + +Missing. + +@node Third-party Doclets +@section Using Third-Party Doclets +@cindex Third-party Doclets + +@menu +* DocBook Doclet:: +* PDFDoclet:: +* JUnitDoclet:: +@end menu + +@node DocBook Doclet +@subsection DocBook Doclet +@cindex DocBook Doclet + +Missing. + +@node PDFDoclet +@subsection PDFDoclet +@cindex PDFDoclet + +Missing. + +@node JUnitDoclet +@subsection JUnitDoclet +@cindex JUnitDoclet + +Missing. + +@node Gjdoc Concepts +@chapter Advanced Concepts + +@menu +* Writing Doclets:: +* Taglets:: +* XHTML Fragments:: +* First Sentence Detector:: +* Adding Custom Resources:: +@end menu + + +@node Taglets +@section Adding Custom Tags to the Documentation +@cindex Taglet + +Missing. + +@node Writing Doclets +@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 + +@node Doclet Invocation Interface +@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. + +@node Using AbstractDoclet +@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}. + +@node GNU Doclet SPI +@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. + +@node XHTML Fragments +@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. + +@node First Sentence Detector +@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. + +@node Adding Custom Resources +@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. + +@c --version +@c -help, --help |