Hi,
This patch merges invoke.texi, the texinfo for gjdoc, into
cp-tools.texinfo, so that gjdoc info
is included in cp-tools.info. This fixes
http://gcc.gnu.org/bugzilla/show_bug.cgi?id=37082 .
2008-08-12 Joshua Sumali <[EMAIL PROTECTED]>
* doc/Makefile.am (gjdoc.pod): Generate gjdoc pod from cp-tools.texinfo
instead of invoke.texi.
* doc/invoke.texi: Removed and merged into ...
* doc/cp-tools.texinfo: Here.
Comments, or OK to commit?
Cheers,
Josh
* Note: I didn't include the removal of invoke.texi in the attached patch.
Index: Makefile.am
===================================================================
RCS file: /sources/classpath/classpath/doc/Makefile.am,v
retrieving revision 1.13
diff -u -r1.13 Makefile.am
--- Makefile.am 9 Jun 2008 20:58:09 -0000 1.13
+++ Makefile.am 12 Aug 2008 17:20:13 -0000
@@ -82,7 +82,7 @@
gtnameserv.pod: $(srcdir)/cp-tools.texinfo
-$(TEXI2POD) -D gtnameserv < $< > $@
-gjdoc.pod: $(srcdir)/invoke.texi
+gjdoc.pod: $(srcdir)/cp-tools.texinfo
-$(TEXI2POD) -D gjdoc < $< > $@
CLEANFILES = $(TOOLS_MANFILES)
Index: cp-tools.texinfo
===================================================================
RCS file: /sources/classpath/classpath/doc/cp-tools.texinfo,v
retrieving revision 1.6
diff -u -r1.6 cp-tools.texinfo
--- cp-tools.texinfo 9 Mar 2008 16:28:58 -0000 1.6
+++ cp-tools.texinfo 12 Aug 2008 17:20:13 -0000
@@ -134,6 +134,59 @@
* 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
@@ -1229,6 +1282,7 @@
* rmid Tool:: RMI activation daemon
* rmiregistry Tool:: Remote object registry
* tnameserv Tool:: Naming service
+* gjdoc Tool:: A documentation generator
@end menu
@comment ----------------------------------------------------------------------
@@ -1743,7 +1797,7 @@
@comment ----------------------------------------------------------------------
[EMAIL PROTECTED] tnameserv Tool, , rmiregistry Tool, Other Tools
[EMAIL PROTECTED] 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
@@ -1788,6 +1842,1364 @@
@comment ----------------------------------------------------------------------
[EMAIL PROTECTED]
[EMAIL PROTECTED] man begin SYNOPSIS gjdoc
+gjdoc [EMAIL PROTECTED] [EMAIL PROTECTED]
+ [EMAIL PROTECTED] [EMAIL PROTECTED] [EMAIL PROTECTED]:pkg:@dots{}}]
[EMAIL PROTECTED] [EMAIL PROTECTED]
+ [EMAIL PROTECTED] [EMAIL PROTECTED] [EMAIL PROTECTED] [EMAIL PROTECTED]
[EMAIL PROTECTED] [EMAIL PROTECTED]
+ [EMAIL PROTECTED] [EMAIL PROTECTED] [EMAIL PROTECTED] [EMAIL PROTECTED]
+ [EMAIL PROTECTED] [EMAIL PROTECTED] [EMAIL PROTECTED] [EMAIL PROTECTED]
[EMAIL PROTECTED] [EMAIL PROTECTED] [EMAIL PROTECTED] [EMAIL PROTECTED]
+ [EMAIL PROTECTED] [EMAIL PROTECTED] [EMAIL PROTECTED] [EMAIL PROTECTED]
@var{path}] [EMAIL PROTECTED] [EMAIL PROTECTED]:pkg:@dots{}}]
+ [EMAIL PROTECTED] [EMAIL PROTECTED] [EMAIL PROTECTED] [EMAIL PROTECTED]
[EMAIL PROTECTED] [EMAIL PROTECTED]
+ [EMAIL PROTECTED] [EMAIL PROTECTED] [EMAIL PROTECTED] [EMAIL PROTECTED]
[EMAIL PROTECTED]
+ [EMAIL PROTECTED] [EMAIL PROTECTED] [EMAIL PROTECTED] [EMAIL PROTECTED]
[EMAIL PROTECTED]
+ [EMAIL PROTECTED] [EMAIL PROTECTED]
+ [EMAIL PROTECTED]@dots{}] [EMAIL PROTECTED]@dots{}] [@@@var{cmdfile}]
+
+gjdoc [EMAIL PROTECTED] [EMAIL PROTECTED]
+ [EMAIL PROTECTED] [EMAIL PROTECTED] [EMAIL PROTECTED]:pkg:@dots{}}]
[EMAIL PROTECTED] [EMAIL PROTECTED]
+ [EMAIL PROTECTED] [EMAIL PROTECTED] [EMAIL PROTECTED] [EMAIL PROTECTED]
[EMAIL PROTECTED] [EMAIL PROTECTED]
+ [EMAIL PROTECTED] [EMAIL PROTECTED] [EMAIL PROTECTED] [EMAIL PROTECTED]
+ [EMAIL PROTECTED] [EMAIL PROTECTED] [EMAIL PROTECTED] [EMAIL PROTECTED]
+ [EMAIL PROTECTED]@dots{}] [EMAIL PROTECTED]@dots{}] [@@@var{cmdfile}]
+ [doclet options]
+
+gjdoc @option{--help}
+
+gjdoc @option{--version}
+
+Only the most useful options are listed here; see below for the
+remainder.
[EMAIL PROTECTED] man end
[EMAIL PROTECTED] ignore
[EMAIL PROTECTED] man begin SEEALSO gjdoc
+Info entry for @file{gjdoc}.
[EMAIL PROTECTED] man end
[EMAIL PROTECTED] man begin BUGS gjdoc
+Please report bugs to @[EMAIL
PROTECTED]://savannah.gnu.org/bugs/?group=classpath}}.
[EMAIL PROTECTED] man end
[EMAIL PROTECTED] man begin AUTHOR gjdoc
+Julian Scheid
[EMAIL PROTECTED] man end
+
[EMAIL PROTECTED] gjdoc Tool, , tnameserv Tool, Other Tools
[EMAIL PROTECTED] Generating HTML Documentation
[EMAIL PROTECTED] Gjdoc command options
[EMAIL PROTECTED] command options
[EMAIL PROTECTED] options, Gjdoc command
+
[EMAIL PROTECTED] 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
[EMAIL PROTECTED] to generate a set of HTML pages. The canonical
+usage is:
+
[EMAIL PROTECTED]
+gjdoc -s src/java/ -all -d api-docs/
[EMAIL PROTECTED] 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}.
+
[EMAIL PROTECTED]
+* 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
+
[EMAIL PROTECTED] menu
+
[EMAIL PROTECTED] man end
+
[EMAIL PROTECTED]
----------------------------------------------------------------------
+
[EMAIL PROTECTED] Invoking the Standard Doclet, Invoking a Custom Doclet, ,
gjdoc Tool
[EMAIL PROTECTED] Invoking the Standard Doclet
[EMAIL PROTECTED] Gjdoc command options
[EMAIL PROTECTED] command options
[EMAIL PROTECTED] 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}.
+
[EMAIL PROTECTED]
+* 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::
+
[EMAIL PROTECTED] menu
+
[EMAIL PROTECTED] man begin OPTIONS gjdoc
+
[EMAIL PROTECTED] Option Summary by Type, Gjdoc Option Summary, Invoking a
Custom Doclet, gjdoc Tool
[EMAIL PROTECTED] 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.
+
[EMAIL PROTECTED] @emph
[EMAIL PROTECTED] Source Set Options
[EMAIL PROTECTED] Set Options,,Options For Specifying the Source Files To
Operate on}.
[EMAIL PROTECTED] @var{pathlist} -subpackages @var{pkglist} -exclude
@var{pkglist}}
+
[EMAIL PROTECTED] Source Format Options
[EMAIL PROTECTED] Format Options,,Options For Specifying the Source Format}.
[EMAIL PROTECTED] @var{release} -encoding @var{encoding} -breakiterator}
+
[EMAIL PROTECTED] Interlinking Options
[EMAIL PROTECTED] Options,,Options For Specifying the Source Files To Operate
on}.
[EMAIL PROTECTED] @var{url} -linkoffline @var{url} @var{file} -noqualifier
@var{pkg:pkg:...}}
+
[EMAIL PROTECTED] Generation Options
[EMAIL PROTECTED] Options,,Options Controlling What is Included in the Output}.
[EMAIL PROTECTED] -licensetext -use -version -splitindex -noindex
+ -nodeprecated -nodeprecatedlist -nohelp -nonavbar
+ -nosince -notree -public -protected -package -private
+ -docfilessubdirs -excludedocfilessubdir @var{dirname}
+ -linksource}
+
[EMAIL PROTECTED] Output Options
[EMAIL PROTECTED] Options,,Options Controlling the Output}.
[EMAIL PROTECTED] -locale @var{name} -charset @var{charset} -docencoding
@var{charset}
+ -validhtml -baseurl @var{url}}
+
[EMAIL PROTECTED] Decoration Options
[EMAIL PROTECTED] @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{}}}
+
[EMAIL PROTECTED] Taglet Options
[EMAIL PROTECTED] Options,,Options For Specifying user-defined Taglets}.
[EMAIL PROTECTED] -taglet @var{classname} -tag @var{tagspec}}
+
[EMAIL PROTECTED] Doclet Options
[EMAIL PROTECTED] Options,,Options For Specifying the Doclet to use}.
[EMAIL PROTECTED] -doclet @var{classname}}
+
[EMAIL PROTECTED] Verbosity Options
[EMAIL PROTECTED] Options,,Options Controlling Gjdoc Behavior}.
[EMAIL PROTECTED] -verbose}
+
[EMAIL PROTECTED] Virtual Machine Options
[EMAIL PROTECTED] Machine Options,,Options Controlling Gjdoc Behavior}.
[EMAIL PROTECTED] @gccoptlist{-bootclasspath} @[EMAIL PROTECTED]
+
[EMAIL PROTECTED] table
+
[EMAIL PROTECTED]
+* Virtual Machine Options:: Controlling the kind of output:
+ an executable, object files, assembler files,
+ or preprocessed source.
[EMAIL PROTECTED] menu
+
[EMAIL PROTECTED] Source Set Options, Source Format Options, Gjdoc Option
Summary, gjdoc Tool
[EMAIL PROTECTED] Selecting which Source Files to Process
+
[EMAIL PROTECTED] @gcctabopt
[EMAIL PROTECTED] -s @var{pathlist}
[EMAIL PROTECTED] -sourcepath @var{pathlist}
+Look for source files in the specified directory or directories.
+
[EMAIL PROTECTED] 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 @[EMAIL PROTECTED]
+sub-directory, not the directory @[EMAIL PROTECTED]/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}.
+
[EMAIL PROTECTED] -all
[EMAIL PROTECTED]
+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}.
+
[EMAIL PROTECTED] -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.
+
[EMAIL PROTECTED] -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.
+
[EMAIL PROTECTED] @[EMAIL PROTECTED]
+Process all classes in the given Java packages.
+
[EMAIL PROTECTED] @[EMAIL PROTECTED]
+Process the classes in the given Java source files.
[EMAIL PROTECTED] table
+
[EMAIL PROTECTED] Source Format Options, Interlinking Options, Source Set
Options, gjdoc Tool
[EMAIL PROTECTED] Specifying the Format of Input Files
+
[EMAIL PROTECTED] @gcctabopt
[EMAIL PROTECTED] -source @var{release}
+Assume that the source files are targeted at the given release of the
+Java platform.
+
[EMAIL PROTECTED] 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.
+
[EMAIL PROTECTED] -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
[EMAIL PROTECTED]
+
+The semantics of @var{charset} are identical to those of
@samp{java.nio.charset.Charset.forName(String)}.
+
[EMAIL PROTECTED] -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
[EMAIL PROTECTED] (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.
[EMAIL PROTECTED] table
+
[EMAIL PROTECTED] Interlinking Options, Output Control Options, Source Format
Options, gjdoc Tool
[EMAIL PROTECTED] Interlinking with other Documentation Sets
+
[EMAIL PROTECTED] @gcctabopt
[EMAIL PROTECTED] -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.
+
[EMAIL PROTECTED] should be the root URL of the other documentation set. For
+example, to add hyperlinks to GNU Classpath, specify the following:
+
[EMAIL PROTECTED]
+-link http://developer.classpath.org/doc/
[EMAIL PROTECTED] 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.
+
[EMAIL PROTECTED] -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.
+
[EMAIL PROTECTED] -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.
+
[EMAIL PROTECTED] -noqualifier @samp{all}
+Omit package name qualifier from all class names.
+
+Specify this option to omit package name qualifiers altogether,
+
[EMAIL PROTECTED] table
+
[EMAIL PROTECTED] Generation Options, Decoration Options, Output Control
Options, gjdoc Tool
[EMAIL PROTECTED] Selecting which Information to Generate
+
[EMAIL PROTECTED] @gcctabopt
[EMAIL PROTECTED] -public
+Only include public members of public classes in the output. By
+default, protected class members are included as well.
+
[EMAIL PROTECTED] -protected
+
+Include public or protected members of public classes in the output.
+This is the default.
+
[EMAIL PROTECTED] -package
+
+Include public, protected and package-private members of public and
+package-private classes.
+
[EMAIL PROTECTED] -private
+
+Include all classes and class members regardless of their access
+level.
+
[EMAIL PROTECTED] -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.
+
[EMAIL PROTECTED] -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.
+
[EMAIL PROTECTED] -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.
+
[EMAIL PROTECTED] -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.
+
[EMAIL PROTECTED] -nohelp
+Do not generate the help page.
+
+This option is currently ignored as the Standard Doclet doesn't
+provide a help page.
+
[EMAIL PROTECTED] -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.
+
[EMAIL PROTECTED] -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.
+
[EMAIL PROTECTED] -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.
+
[EMAIL PROTECTED] -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.
+
[EMAIL PROTECTED] -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.
+
[EMAIL PROTECTED] -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.
+
[EMAIL PROTECTED] -author
+Include author information in the output.
+
+When specified, author information as specified using the
[EMAIL PROTECTED]@@author} tag in javadoc comments is incorporated into the
+output. By default, @samp{@@author} tags are ignored.
+
[EMAIL PROTECTED] -version
+Include version information in the output.
+
+When specified, version information as specified using the
[EMAIL PROTECTED]@@version} tag in javadoc comments is incorporated into the
+output. By default, @samp{@@version} tags are ignored.
+
[EMAIL PROTECTED] -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.
+
[EMAIL PROTECTED] -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.
+
[EMAIL PROTECTED] Custom Resources}.
+
[EMAIL PROTECTED] -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
[EMAIL PROTECTED] directory is omitted if listed.
+
[EMAIL PROTECTED] table
+
[EMAIL PROTECTED] Taglet Options, Virtual Machine Options, Decoration Options,
gjdoc Tool
[EMAIL PROTECTED] Custom Documentation Tags
+
[EMAIL PROTECTED] @gcctabopt
[EMAIL PROTECTED] -tagletpath @var{pathlist}
+Search @var{pathlist} when loading subsequent Taglet classes specified
+using @option{-taglet}.
+
[EMAIL PROTECTED] should be one or more paths to a directory or jar file,
+separated by your platform's path separator (usually @samp{:} or
[EMAIL PROTECTED];}).
+
[EMAIL PROTECTED] -taglet @var{classname}
+Register a Taglet.
+
[EMAIL PROTECTED] 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
[EMAIL PROTECTED], from the classpath specified using
[EMAIL PROTECTED] 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}.
+
[EMAIL PROTECTED] -tag @var{tagspec}
+Register a generic Taglet.
+
+The format of @var{tagspec} must be @samp{<tagname>:<flags>:"<taghead>"}.
+
[EMAIL PROTECTED] is the tag name to match, without the leading @@ sign.
+
[EMAIL PROTECTED] is one or more of the following characters, where each
+character specifies a source code context in which the tag is to be
+recognized.
+
[EMAIL PROTECTED] @gcctabopt
[EMAIL PROTECTED] a
+all contexts
[EMAIL PROTECTED] c
+constructors
[EMAIL PROTECTED] f
+fields
[EMAIL PROTECTED] m
+methods
[EMAIL PROTECTED] o
+overview
[EMAIL PROTECTED] p
+packages
[EMAIL PROTECTED] t
+types (classes, interfaces, exceptions, errors)
[EMAIL PROTECTED] X
+special character which temporarily disables the
+Taglet altogether.
[EMAIL PROTECTED] table
+
[EMAIL PROTECTED] 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:
+
[EMAIL PROTECTED]
+-tag cvsid:tpo:"CVS ID"
[EMAIL PROTECTED] smallexample
+
+Let's say that a class javadoc comment contains
+
[EMAIL PROTECTED]
+@@cvsid $Id: invoke.texi,v 1.1 2008/05/27 19:25:31 jsumali Exp $
[EMAIL PROTECTED] smallexample
+
+Then the HTML output will contain something like
+
[EMAIL PROTECTED]
+CVS ID:
+ $Id: invoke.texi,v 1.1 2008/05/27 19:25:31 jsumali Exp $
[EMAIL PROTECTED] smallexample
[EMAIL PROTECTED] table
+
[EMAIL PROTECTED] Doclet Options, Other Doclets, Verbosity Options, gjdoc Tool
[EMAIL PROTECTED] Running Other Doclets
+
[EMAIL PROTECTED] @gcctabopt
+
[EMAIL PROTECTED] -docletpath @var{pathlist}
+Search @var{pathlist} when loading classes for the Doclet specified
+using @option{-doclet}.
+
[EMAIL PROTECTED] should be one or more paths to a directory or jar file,
+separated by your platform's path separator (usually @samp{:} or
[EMAIL PROTECTED];}).
+
[EMAIL PROTECTED] -doclet @var{className}
+Run the specified doclet instead of the standard HtmlDoclet.
+
[EMAIL PROTECTED] should be the fully-qualified name of a class which
+has a public default constructor and contain a method with the
+following signature:
+
[EMAIL PROTECTED]
+ import com.sun.javadoc.RootDoc;
+ public static boolean start(RootDoc rootDoc)
[EMAIL PROTECTED] smallexample
+
+The Doclet classes will be loaded from the classpath specified using
[EMAIL PROTECTED], from the classpath specified using
[EMAIL PROTECTED] 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,
[EMAIL PROTECTED] 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.
+
[EMAIL PROTECTED] table
+
[EMAIL PROTECTED] Decoration Options, Taglet Options, Generation Options, gjdoc
Tool
[EMAIL PROTECTED] Adding Information to the Output
+
[EMAIL PROTECTED] @gcctabopt
[EMAIL PROTECTED] -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}.
+
[EMAIL PROTECTED] should be plain text (it should not contain HTML tags).
+
[EMAIL PROTECTED] -doctitle @var{text}
+Set the header text of the overview page to @var{text}.
+
[EMAIL PROTECTED] should be a short plain text string.
+
+When generating documentation for a single package, specifying this
+option forces generation of the overview page.
+
[EMAIL PROTECTED] -header @var{htmltext}
+
+Add @var{htmltext} to the right upper corner of every generated page.
[EMAIL PROTECTED] is usually set to the name of the project being
+documented.
+
[EMAIL PROTECTED] -footer @var{htmltext}
+
+Add @var{htmltext} to the right bottom corner of every generated page.
[EMAIL PROTECTED] is often set to the same value as for @option{-header}.
+
[EMAIL PROTECTED] -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.
+
[EMAIL PROTECTED] -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 @[EMAIL PROTECTED]://www.w3.org/TR/REC-CSS2/cascade.html#cascading-order}}.
+
[EMAIL PROTECTED] -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
[EMAIL PROTECTED] A more useful example would be
[EMAIL PROTECTED] to match @samp{javax.swing} and all of its
+sub-packages.
+
+This option can be given multiple times.
+
+FIXME: Information about group nesting here.
+
[EMAIL PROTECTED]
+gjdoc -group "Core Classes" 'java*' \
+ -group "Swing" 'javax.swing*' \
+ -group "XML APIs" 'javax.xml*' \
+ -group "Other Extensions" javax* \
+ @dots{}
[EMAIL PROTECTED] smallexample
+
[EMAIL PROTECTED] -overview @var{file}
+
+Add the XHTML body fragment from @var{file} to the overview page.
+
[EMAIL PROTECTED] 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.
[EMAIL PROTECTED] Sentence Detector}.
+
+When generating documentation for a single package, specifying this
+option forces generation of the overview page.
+
[EMAIL PROTECTED] -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
[EMAIL PROTECTED] instead.
+
[EMAIL PROTECTED] -title @var{text}
+
[EMAIL PROTECTED] Use @option{-doctitle} @var{text} instead.
+
[EMAIL PROTECTED] -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.
+
[EMAIL PROTECTED] table
+
[EMAIL PROTECTED] Output Control Options, Generation Options, Interlinking
Options, gjdoc Tool
[EMAIL PROTECTED] Controlling the Output.
+
[EMAIL PROTECTED] @gcctabopt
[EMAIL PROTECTED] -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.
+
[EMAIL PROTECTED] -locale @var{name}
+
+Use locale @var{name} instead of the default locale for all purposes.
+
[EMAIL PROTECTED] should be a locale specifier in the form @samp{ll_CC[_VAR]}
+where @samp{ll} is a lowercase two-letter ISO-639 language code,
[EMAIL PROTECTED] 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
[EMAIL PROTECTED] 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.
+
[EMAIL PROTECTED] -charset @var{charset}
+
[EMAIL PROTECTED] 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:
[EMAIL PROTECTED]@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.
+
[EMAIL PROTECTED] -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
[EMAIL PROTECTED]
+
+The semantics of this option correspond exactly to those of the
+constructors of class @samp{java.util.Locale}.
+
[EMAIL PROTECTED] -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.
+
[EMAIL PROTECTED] -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.
+
[EMAIL PROTECTED] table
+
[EMAIL PROTECTED] Verbosity Options, Doclet Options, Virtual Machine Options,
gjdoc Tool
[EMAIL PROTECTED] Verbosity Options
+
[EMAIL PROTECTED] @gcctabopt
[EMAIL PROTECTED] -quiet
+Suppress all output except for warnings and error messages.
+
[EMAIL PROTECTED] -verbose
+Be very verbose about what @command{gjdoc} is doing.
+
+This option is currently ignored.
+
[EMAIL PROTECTED] table
+
[EMAIL PROTECTED] Virtual Machine Options, Verbosity Options, Taglet Options,
gjdoc Tool
[EMAIL PROTECTED] 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.
+
[EMAIL PROTECTED] @gcctabopt
+
[EMAIL PROTECTED] -classpath @var{pathlist}
+Set the Virtual Machine @samp{classpath} to @var{pathlist}.
+
+In most cases you should use @option{-docletpath} or
[EMAIL PROTECTED] instead of this option.
+
[EMAIL PROTECTED] should be one or more paths to a directory or jar file,
+separated by your platform's path separator (usually @samp{:} or
[EMAIL PROTECTED];}).
+
+If this option is not intercepted at the wrapper level,
[EMAIL PROTECTED] currently fakes it by calling
[EMAIL PROTECTED]("java.class.path", @var{pathlist});} and
+outputs a warning.
+
[EMAIL PROTECTED] -bootclasspath @var{pathlist}
+Set the Virtual Machine @samp{bootclasspath} to @var{pathlist}.
+
+If this option is not intercepted at the wrapper level,
[EMAIL PROTECTED] outputs a warning.
+
[EMAIL PROTECTED] [EMAIL PROTECTED]
+
+Pass an arbitrary parameter to the Virtual Machine @command{gjdoc}
+runs on.
+
+If this option is not intercepted at the wrapper level,
[EMAIL PROTECTED] tries to emulate the option and outputs a warning.
+
+Currently, only the VM option @option{-D} for setting system
+properties is emulated.
+
[EMAIL PROTECTED] table
+
[EMAIL PROTECTED] man end
+
[EMAIL PROTECTED]
----------------------------------------------------------------------
+
[EMAIL PROTECTED] Invoking a Custom Doclet, Option Summary by Type, Invoking
the Standard Doclet, gjdoc Tool
[EMAIL PROTECTED] Invoking a Custom Doclet
+
+For invoking one of the other doclets shipping with @command{gjdoc} or
+a third-party doclet, the canonical usage is:
+
[EMAIL PROTECTED]
+gjdoc -s src/java/ -all \
+ -docletpath /path/to/doclet.jar -doclet foo.BarDoclet \
+ (more Gjdoc core options and Doclet-specific options here)
[EMAIL PROTECTED] smallexample
+
[EMAIL PROTECTED]/path/to/doclet.jar} is a placeholder for a class path
+specifying where the Doclet classes and dependencies can be found and
[EMAIL PROTECTED] is the fully-qualified name of the Doclet's main
+class.
+
[EMAIL PROTECTED]
----------------------------------------------------------------------
+
[EMAIL PROTECTED] Gjdoc Option Summary, Source Set Options, Option Summary by
Type, gjdoc Tool
[EMAIL PROTECTED] Gjdoc Option Summary
[EMAIL PROTECTED] Gjdoc Options
+
[EMAIL PROTECTED]
----------------------------------------------------------------------
+
[EMAIL PROTECTED] Other Doclets, Gjdoc Concepts, Doclet Options, gjdoc Tool
[EMAIL PROTECTED] Generating Other Output Types
+
[EMAIL PROTECTED]
+* Built-in Doclets::
+* Third-party Doclets::
[EMAIL PROTECTED] menu
+
[EMAIL PROTECTED]
----------------------------------------------------------------------
+
[EMAIL PROTECTED] Built-in Doclets, Third-party Doclets, , Other Doclets
[EMAIL PROTECTED] Using the Built-in Doclets
[EMAIL PROTECTED] Built-in Doclets
+
[EMAIL PROTECTED]
+* Using XmlDoclet::
+* Using TexiDoclet::
+* Using IspellDoclet::
+* Using DebugDoclet::
[EMAIL PROTECTED] menu
+
[EMAIL PROTECTED]
----------------------------------------------------------------------
+
[EMAIL PROTECTED] Using TexiDoclet, Using XmlDoclet, , Built-in Doclets
[EMAIL PROTECTED] TexiDoclet: Generating Info, PDF, and other formats
[EMAIL PROTECTED] TexiDoclet
+
+Missing.
+
[EMAIL PROTECTED]
----------------------------------------------------------------------
+
[EMAIL PROTECTED] Using XmlDoclet, Using IspellDoclet, Using TexiDoclet,
Built-in Doclets
[EMAIL PROTECTED] XmlDoclet: Generating XML Documentation
[EMAIL PROTECTED] HtmlDoclet
+
+Missing.
+
[EMAIL PROTECTED]
----------------------------------------------------------------------
+
[EMAIL PROTECTED] Using IspellDoclet, Using DebugDoclet, Using XmlDoclet,
Built-in Doclets
[EMAIL PROTECTED] IspellDoclet: Spell-checking Source Code
[EMAIL PROTECTED] IspellDoclet
+
+Missing.
+
[EMAIL PROTECTED]
----------------------------------------------------------------------
+
[EMAIL PROTECTED] Using DebugDoclet, , Using IspellDoclet, Built-in Doclets
[EMAIL PROTECTED] DebugDoclet: Inspecting the Doclet API
[EMAIL PROTECTED] HtmlDoclet
+
+Missing.
+
[EMAIL PROTECTED]
----------------------------------------------------------------------
+
[EMAIL PROTECTED] Third-party Doclets, , Built-in Doclets, Other Doclets
[EMAIL PROTECTED] Using Third-Party Doclets
[EMAIL PROTECTED] Third-party Doclets
+
[EMAIL PROTECTED]
+* DocBook Doclet::
+* PDFDoclet::
+* JUnitDoclet::
[EMAIL PROTECTED] menu
+
[EMAIL PROTECTED]
----------------------------------------------------------------------
+
[EMAIL PROTECTED] DocBook Doclet,PDFDoclet, ,Third-party Doclets
[EMAIL PROTECTED] DocBook Doclet
[EMAIL PROTECTED] DocBook Doclet
+
+Missing.
+
[EMAIL PROTECTED]
----------------------------------------------------------------------
+
[EMAIL PROTECTED] PDFDoclet, JUnitDoclet, DocBook Doclet, Third-party Doclets
[EMAIL PROTECTED] PDFDoclet
[EMAIL PROTECTED] PDFDoclet
+
+Missing.
+
[EMAIL PROTECTED]
----------------------------------------------------------------------
+
[EMAIL PROTECTED] JUnitDoclet, , PDFDoclet, Third-party Doclets
[EMAIL PROTECTED] JUnitDoclet
[EMAIL PROTECTED] JUnitDoclet
+
+Missing.
+
[EMAIL PROTECTED]
----------------------------------------------------------------------
+
[EMAIL PROTECTED] Gjdoc Concepts, , Other Doclets, gjdoc Tool
[EMAIL PROTECTED] Advanced Concepts
+
[EMAIL PROTECTED]
+* Writing Doclets::
+* Taglets::
+* XHTML Fragments::
+* First Sentence Detector::
+* Adding Custom Resources::
[EMAIL PROTECTED] menu
+
[EMAIL PROTECTED]
----------------------------------------------------------------------
+
[EMAIL PROTECTED] Taglets, Writing Doclets, , Gjdoc Concepts
[EMAIL PROTECTED] Adding Custom Tags to the Documentation
[EMAIL PROTECTED] Taglet
+
+Missing.
+
[EMAIL PROTECTED]
----------------------------------------------------------------------
+
[EMAIL PROTECTED] Writing Doclets, XHTML Fragments, Taglets, Gjdoc Concepts
[EMAIL PROTECTED] Writing Doclets
[EMAIL PROTECTED] Taglet
+
+If the various Doclets already available don't suit your needs, you
+can write a custom Doclet yourself.
+
[EMAIL PROTECTED]
+* Doclet Invocation Interface::
+* Using AbstractDoclet::
+* GNU Doclet SPI::
[EMAIL PROTECTED] menu
+
[EMAIL PROTECTED]
----------------------------------------------------------------------
+
[EMAIL PROTECTED] Doclet Invocation Interface, Using AbstractDoclet, , Writing
Doclets
[EMAIL PROTECTED] Implementing the Doclet Invocation Interface
+
+A Doclet is a class that contains a method with the following
+signature:
+
[EMAIL PROTECTED]
+public static boolean start(RootDoc rootDoc);
[EMAIL PROTECTED] smallexample
+
[EMAIL PROTECTED] is the root of an object hierarchy containing the
+information @command{gjdoc} extracted from the source files. See the
+Doclet API for more details.
+
[EMAIL PROTECTED] should process all the information and return
[EMAIL PROTECTED] on success, @samp{false} on failure.
+
+For printing status information, the Doclet should use methods
[EMAIL PROTECTED], @samp{printWarning} and @samp{printError} instead
+of @samp{System.err}. The Doclet can opt to use @samp{System.out} for
+redirectable output.
+
[EMAIL PROTECTED]
----------------------------------------------------------------------
+
[EMAIL PROTECTED] Using AbstractDoclet, GNU Doclet SPI, Doclet Invocation
Interface, Writing Doclets
[EMAIL PROTECTED] Deriving Your Doclet from AbstractDoclet
[EMAIL PROTECTED] 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
[EMAIL PROTECTED] This class
+provides the following benefits:
+
[EMAIL PROTECTED] @bullet
+
[EMAIL PROTECTED]
+Handles options @option{-tag}, @option{-taglet}, @option{-tagletpath}
+(Taglets)
+
[EMAIL PROTECTED]
+Provides standard taglets for @@version, @@author, @@since, @@serial,
+@@deprecated, @@see, @@param, @@return and handles all related options
+(@option{-version}, @option{-author}, @option{-nosince},
[EMAIL PROTECTED])
+
[EMAIL PROTECTED]
+Handles option @option{-d} (destination directory)
+
[EMAIL PROTECTED]
+Handles option @option{-noqualifier} (classes to omit qualifier for)
+
[EMAIL PROTECTED]
+Handles options @option{-docfilessubdirs} and
[EMAIL PROTECTED] (resource copying)
+
[EMAIL PROTECTED]
+Can generate a full index or an index split by first letter
+
[EMAIL PROTECTED]
+Can generate a full tree and package trees
+
[EMAIL PROTECTED]
+Can generate cross-reference information
+
[EMAIL PROTECTED]
+Can aggregate interface information (all superinterfaces, all
+subinterfaces, all implementing classes)
+
[EMAIL PROTECTED]
+Provides convenient access to constructors, fields, methods, and inner
+classes sorted by name/signature instead of the default sort order.
+
[EMAIL PROTECTED]
+Provides various other convenience methods
+
[EMAIL PROTECTED] itemize
+
+If you derive from @samp{AbstractDoclet}, there are a number of things
+you need to take care of:
+
[EMAIL PROTECTED] @bullet
+
[EMAIL PROTECTED]
+
[EMAIL PROTECTED] itemize
+
+you should not implement the
[EMAIL PROTECTED](RootDoc)} method as it is already defined by
[EMAIL PROTECTED] 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
[EMAIL PROTECTED] for more details.
+
+You should be aware that if you base your Doclet on
[EMAIL PROTECTED] 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
[EMAIL PROTECTED] and not on other documentation systems. Also note that
[EMAIL PROTECTED] has not been extensively tested in environments
+other than @samp{gjdoc}.
+
[EMAIL PROTECTED]
----------------------------------------------------------------------
+
[EMAIL PROTECTED] GNU Doclet SPI, , Using AbstractDoclet, Writing Doclets
[EMAIL PROTECTED] Preparing for the GNU Doclet Service Provider Interface
[EMAIL PROTECTED] 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
[EMAIL PROTECTED]/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
[EMAIL PROTECTED]:} Manifest attribute of your Doclet Jar.
+
+Your Doclet can then be invoked in one of the following ways:
[EMAIL PROTECTED]
+gjdoc -docletjar /path/to/doclet.jar
+gjdoc -docletpath /path/to/doclet.jar -docletname @var{docletname}
+gjdoc -docletname @var{docletname}
[EMAIL PROTECTED] smallexample
+
+Here, @var{docletname} is the name of your doclet as returned by
[EMAIL PROTECTED]()}.
+
+The last example will only work if your Doclet Jar is in
[EMAIL PROTECTED]'s @file{doclets} directory or if it is on the
+classpath.
+
[EMAIL PROTECTED]
----------------------------------------------------------------------
+
[EMAIL PROTECTED] XHTML Fragments, First Sentence Detector, Writing Doclets,
Gjdoc Concepts
[EMAIL PROTECTED] Well-formed Documentation Fragments
[EMAIL PROTECTED] 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
[EMAIL PROTECTED]@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.
+
[EMAIL PROTECTED]
----------------------------------------------------------------------
+
[EMAIL PROTECTED] First Sentence Detector, Adding Custom Resources, XHTML
Fragments, Gjdoc Concepts
[EMAIL PROTECTED] How Gjdoc Determines where the First Sentence Ends
[EMAIL PROTECTED] First Sentence Detector
+
+For a package, class or member summary, @command{gjdoc} only shows the
+first sentence of the documentation comment in question. Because
[EMAIL PROTECTED] is not human, it is not always obvious to
[EMAIL PROTECTED] 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
[EMAIL PROTECTED] However, consider examples like this:
[EMAIL PROTECTED]
+This work, by Thomas J. Shahan et al., is about the middle ages.
[EMAIL PROTECTED] smallexample
+
+As you can see, it is not trivial to determine the end of the
+sentence.
+
[EMAIL PROTECTED] 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
[EMAIL PROTECTED](@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.
+
[EMAIL PROTECTED] YET IMPLEMENTED:}
+
[EMAIL PROTECTED] also allows you to explicitly delineate the first
+sentence by putting it in a @samp{<span>} tag with the CSS class
[EMAIL PROTECTED] For example:
[EMAIL PROTECTED]
+/**
+ * <span class="first-sentence">This. is. the. first.
+ * sentence.</span> This is the second sentence.
+ */
[EMAIL PROTECTED] 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.
+
[EMAIL PROTECTED]
----------------------------------------------------------------------
+
[EMAIL PROTECTED] Adding Custom Resources, , First Sentence Detector, Gjdoc
Concepts
[EMAIL PROTECTED] Adding Images and Other Resources
[EMAIL PROTECTED] 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
[EMAIL PROTECTED]/@var{filename}}.
+
+For example, if you want to add an image to the description of class
[EMAIL PROTECTED], 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}:
[EMAIL PROTECTED]
+<img src="doc-files/diagram.png" width="200" height="150"
+ alt="Foo Diagram"/>
[EMAIL PROTECTED] 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
[EMAIL PROTECTED] 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
[EMAIL PROTECTED] For cases like this, use
[EMAIL PROTECTED] to specify directories to be omitted.
+
[EMAIL PROTECTED]
----------------------------------------------------------------------
+
@node I18N Issues, , Other Tools, Top
@comment node-name, next, previous, up
@chapter I18N Issues
