2014-09-21 17:33:12 +00:00
|
|
|
.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
|
2012-03-27 23:13:14 +00:00
|
|
|
.\"
|
|
|
|
|
.\" Standard preamble:
|
|
|
|
|
.\" ========================================================================
|
|
|
|
|
.de Sp \" Vertical space (when we can't use .PP)
|
|
|
|
|
.if t .sp .5v
|
|
|
|
|
.if n .sp
|
|
|
|
|
..
|
|
|
|
|
.de Vb \" Begin verbatim text
|
|
|
|
|
.ft CW
|
|
|
|
|
.nf
|
|
|
|
|
.ne \\$1
|
|
|
|
|
..
|
|
|
|
|
.de Ve \" End verbatim text
|
|
|
|
|
.ft R
|
|
|
|
|
.fi
|
|
|
|
|
..
|
|
|
|
|
.\" Set up some character translations and predefined strings. \*(-- will
|
|
|
|
|
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
|
|
|
|
|
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
|
|
|
|
|
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
|
|
|
|
|
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
|
|
|
|
|
.\" nothing in troff, for use with C<>.
|
|
|
|
|
.tr \(*W-
|
|
|
|
|
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
|
|
|
|
|
.ie n \{\
|
|
|
|
|
. ds -- \(*W-
|
|
|
|
|
. ds PI pi
|
|
|
|
|
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
|
|
|
|
|
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
|
|
|
|
|
. ds L" ""
|
|
|
|
|
. ds R" ""
|
|
|
|
|
. ds C` ""
|
|
|
|
|
. ds C' ""
|
|
|
|
|
'br\}
|
|
|
|
|
.el\{\
|
|
|
|
|
. ds -- \|\(em\|
|
|
|
|
|
. ds PI \(*p
|
|
|
|
|
. ds L" ``
|
|
|
|
|
. ds R" ''
|
2014-09-21 17:33:12 +00:00
|
|
|
. ds C`
|
|
|
|
|
. ds C'
|
2012-03-27 23:13:14 +00:00
|
|
|
'br\}
|
|
|
|
|
.\"
|
|
|
|
|
.\" Escape single quotes in literal strings from groff's Unicode transform.
|
|
|
|
|
.ie \n(.g .ds Aq \(aq
|
|
|
|
|
.el .ds Aq '
|
|
|
|
|
.\"
|
|
|
|
|
.\" If the F register is turned on, we'll generate index entries on stderr for
|
2014-09-21 17:33:12 +00:00
|
|
|
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
|
2012-03-27 23:13:14 +00:00
|
|
|
.\" entries marked with X<> in POD. Of course, you'll have to process the
|
|
|
|
|
.\" output yourself in some meaningful fashion.
|
2014-09-21 17:33:12 +00:00
|
|
|
.\"
|
|
|
|
|
.\" Avoid warning from groff about undefined register 'F'.
|
|
|
|
|
.de IX
|
2012-03-27 23:13:14 +00:00
|
|
|
..
|
2014-09-21 17:33:12 +00:00
|
|
|
.nr rF 0
|
|
|
|
|
.if \n(.g .if rF .nr rF 1
|
|
|
|
|
.if (\n(rF:(\n(.g==0)) \{
|
|
|
|
|
. if \nF \{
|
|
|
|
|
. de IX
|
|
|
|
|
. tm Index:\\$1\t\\n%\t"\\$2"
|
2012-03-27 23:13:14 +00:00
|
|
|
..
|
2014-09-21 17:33:12 +00:00
|
|
|
. if !\nF==2 \{
|
|
|
|
|
. nr % 0
|
|
|
|
|
. nr F 2
|
|
|
|
|
. \}
|
|
|
|
|
. \}
|
2012-03-27 23:13:14 +00:00
|
|
|
.\}
|
2014-09-21 17:33:12 +00:00
|
|
|
.rr rF
|
2012-03-27 23:13:14 +00:00
|
|
|
.\"
|
|
|
|
|
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
|
|
|
|
|
.\" Fear. Run. Save yourself. No user-serviceable parts.
|
|
|
|
|
. \" fudge factors for nroff and troff
|
|
|
|
|
.if n \{\
|
|
|
|
|
. ds #H 0
|
|
|
|
|
. ds #V .8m
|
|
|
|
|
. ds #F .3m
|
|
|
|
|
. ds #[ \f1
|
|
|
|
|
. ds #] \fP
|
|
|
|
|
.\}
|
|
|
|
|
.if t \{\
|
|
|
|
|
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
|
|
|
|
|
. ds #V .6m
|
|
|
|
|
. ds #F 0
|
|
|
|
|
. ds #[ \&
|
|
|
|
|
. ds #] \&
|
|
|
|
|
.\}
|
|
|
|
|
. \" simple accents for nroff and troff
|
|
|
|
|
.if n \{\
|
|
|
|
|
. ds ' \&
|
|
|
|
|
. ds ` \&
|
|
|
|
|
. ds ^ \&
|
|
|
|
|
. ds , \&
|
|
|
|
|
. ds ~ ~
|
|
|
|
|
. ds /
|
|
|
|
|
.\}
|
|
|
|
|
.if t \{\
|
|
|
|
|
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
|
|
|
|
|
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
|
|
|
|
|
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
|
|
|
|
|
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
|
|
|
|
|
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
|
|
|
|
|
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
|
|
|
|
|
.\}
|
|
|
|
|
. \" troff and (daisy-wheel) nroff accents
|
|
|
|
|
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
|
|
|
|
|
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
|
|
|
|
|
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
|
|
|
|
|
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
|
|
|
|
|
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
|
|
|
|
|
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
|
|
|
|
|
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
|
|
|
|
|
.ds ae a\h'-(\w'a'u*4/10)'e
|
|
|
|
|
.ds Ae A\h'-(\w'A'u*4/10)'E
|
|
|
|
|
. \" corrections for vroff
|
|
|
|
|
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
|
|
|
|
|
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
|
|
|
|
|
. \" for low resolution devices (crt and lpr)
|
|
|
|
|
.if \n(.H>23 .if \n(.V>19 \
|
|
|
|
|
\{\
|
|
|
|
|
. ds : e
|
|
|
|
|
. ds 8 ss
|
|
|
|
|
. ds o a
|
|
|
|
|
. ds d- d\h'-1'\(ga
|
|
|
|
|
. ds D- D\h'-1'\(hy
|
|
|
|
|
. ds th \o'bp'
|
|
|
|
|
. ds Th \o'LP'
|
|
|
|
|
. ds ae ae
|
|
|
|
|
. ds Ae AE
|
|
|
|
|
.\}
|
|
|
|
|
.rm #[ #] #H #V #F C
|
|
|
|
|
.\" ========================================================================
|
|
|
|
|
.\"
|
|
|
|
|
.IX Title "GJDOC 1"
|
2014-09-21 17:33:12 +00:00
|
|
|
.TH GJDOC 1 "2014-07-16" "0.99.1-pre" "GNU"
|
2012-03-27 23:13:14 +00:00
|
|
|
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
|
|
|
|
|
.\" way too many mistakes in technical documents.
|
|
|
|
|
.if n .ad l
|
|
|
|
|
.nh
|
|
|
|
|
.SH "NAME"
|
|
|
|
|
cp\-tools \- GNU Classpath Tools Guide
|
|
|
|
|
.SH "SYNOPSIS"
|
|
|
|
|
.IX Header "SYNOPSIS"
|
|
|
|
|
gjdoc [\fB\-sourcepath\fR \fIpathlist\fR]
|
|
|
|
|
[\fB\-all\fR] [\fB\-subpackages\fR \fIpkg:pkg:...\fR] [\fB\-exclude\fR \fIpkglist\fR]
|
|
|
|
|
[\fB\-encoding\fR \fIcharset\fR] [\fB\-locale\fR \fIname\fR] [\fB\-source\fR \fIrelease\fR]
|
|
|
|
|
[\fB\-public\fR] [\fB\-protected\fR] [\fB\-package\fR] [\fB\-private\fR]
|
|
|
|
|
[\fB\-doctitle\fR \fItext\fR] [\fB\-header\fR \fItext\fR] [\fB\-footer\fR \fItext\fR] [\fB\-bottom\fR \fItext\fR]
|
|
|
|
|
[\fB\-link\fR \fIurl\fR] [\fB\-linkoffline\fR \fIurl\fR \fIpath\fR] [\fB\-noqualifier\fR \fIpkg:pkg:...\fR]
|
|
|
|
|
[\fB\-tagletpath\fR \fIpathlist\fR] [\fB\-taglet\fR \fIclassName\fR] [\fB\-tag\fR \fItagspec\fR]
|
|
|
|
|
[\fB\-use\fR] [\fB\-linksource\fR] [\fB\-splitindex\fR] [\fB\-noindex\fR] [\fB\-notree\fR]
|
|
|
|
|
[\fB\-version\fR] [\fB\-author\fR] [\fB\-nosince\fR] [\fB\-addstylesheet\fR \fIfile\fR]
|
|
|
|
|
[\fB\-d\fR \fItargetdir\fR]
|
|
|
|
|
[\fIpackages\fR...] [\fIsourcefiles\fR...] [@\fIcmdfile\fR]
|
|
|
|
|
.PP
|
|
|
|
|
gjdoc [\fB\-sourcepath\fR \fIpathlist\fR]
|
|
|
|
|
[\fB\-all\fR] [\fB\-subpackages\fR \fIpkg:pkg:...\fR] [\fB\-exclude\fR \fIpkglist\fR]
|
|
|
|
|
[\fB\-encoding\fR \fIcharset\fR] [\fB\-locale\fR \fIname\fR] [\fB\-source\fR \fIrelease\fR]
|
|
|
|
|
[\fB\-public\fR] [\fB\-protected\fR] [\fB\-package\fR] [\fB\-private\fR]
|
|
|
|
|
[\fB\-docletpath\fR \fIpathlist\fR] [\fB\-doclet\fR \fIclassName\fR]
|
|
|
|
|
[\fIpackages\fR...] [\fIsourcefiles\fR...] [@\fIcmdfile\fR]
|
|
|
|
|
[doclet options]
|
|
|
|
|
.PP
|
|
|
|
|
gjdoc \fB\-\-help\fR
|
|
|
|
|
.PP
|
|
|
|
|
gjdoc \fB\-\-version\fR
|
|
|
|
|
.PP
|
|
|
|
|
Only the most useful options are listed here; see below for the
|
|
|
|
|
remainder.
|
|
|
|
|
.SH "DESCRIPTION"
|
|
|
|
|
.IX Header "DESCRIPTION"
|
|
|
|
|
Gjdoc can be used in two ways: as a stand-alone documentation tool, or
|
|
|
|
|
as a driver for a user-specified Doclet.
|
|
|
|
|
.PP
|
|
|
|
|
In the default mode, Gjdoc will use the Standard Doclet
|
|
|
|
|
\&\fBHtmlDoclet\fR to generate a set of \s-1HTML\s0 pages. The canonical
|
|
|
|
|
usage is:
|
|
|
|
|
.PP
|
|
|
|
|
.Vb 1
|
|
|
|
|
\& gjdoc \-s src/java/ \-all \-d api\-docs/
|
|
|
|
|
.Ve
|
|
|
|
|
.PP
|
|
|
|
|
Here, \fBsrc/java/\fR is the root of your source code class
|
|
|
|
|
hierarchy, \fB\-all\fR means that all valid Java files found under
|
|
|
|
|
this root directory should be processed, and \fBapi\-docs/\fR is the
|
|
|
|
|
directory where the generated documentation should be placed.
|
|
|
|
|
.PP
|
|
|
|
|
To learn more about running Doclets other than the Standard Doclet,
|
|
|
|
|
refer to the manual.
|
|
|
|
|
.SH "OPTIONS"
|
|
|
|
|
.IX Header "OPTIONS"
|
2014-09-21 17:33:12 +00:00
|
|
|
.SS "Option Summary by Type"
|
2012-03-27 23:13:14 +00:00
|
|
|
.IX Subsection "Option Summary by Type"
|
|
|
|
|
Here is a summary of all the options of both Gjdoc and the Standard
|
|
|
|
|
Doclet, grouped by type. Explanations are in the following sections.
|
|
|
|
|
.IP "\fISource Set Options\fR" 4
|
|
|
|
|
.IX Item "Source Set Options"
|
|
|
|
|
\&\fB\-sourcepath\fR \fIpathlist\fR \fB\-subpackages\fR \fIpkglist\fR \fB\-exclude\fR \fIpkglist\fR
|
|
|
|
|
.IP "\fISource Format Options\fR" 4
|
|
|
|
|
.IX Item "Source Format Options"
|
|
|
|
|
\&\fB\-source\fR \fIrelease\fR \fB\-encoding\fR \fIencoding\fR \fB\-breakiterator\fR
|
|
|
|
|
.IP "\fIInterlinking Options\fR" 4
|
|
|
|
|
.IX Item "Interlinking Options"
|
|
|
|
|
\&\fB\-link\fR \fIurl\fR \fB\-linkoffline\fR \fIurl\fR\fB \fR\fIfile\fR \fB\-noqualifier\fR \fIpkg:pkg:...\fR
|
|
|
|
|
.IP "\fIGeneration Options\fR" 4
|
|
|
|
|
.IX Item "Generation Options"
|
|
|
|
|
\&\fB\-author \-licensetext \-use \-version \-splitindex \-noindex
|
|
|
|
|
\-nodeprecated \-nodeprecatedlist \-nohelp \-nonavbar
|
|
|
|
|
\-nosince \-notree \-public \-protected \-package \-private
|
|
|
|
|
\-docfilessubdirs \-excludedocfilessubdir\fR \fIdirname\fR
|
|
|
|
|
\fB\-linksource\fR
|
|
|
|
|
.IP "\fIOutput Options\fR" 4
|
|
|
|
|
.IX Item "Output Options"
|
|
|
|
|
\&\fB\-d \-locale\fR \fIname\fR \fB\-charset\fR \fIcharset\fR \fB\-docencoding\fR \fIcharset\fR
|
|
|
|
|
\fB\-validhtml \-baseurl\fR \fIurl\fR
|
|
|
|
|
.IP "\fIDecoration Options\fR" 4
|
|
|
|
|
.IX Item "Decoration Options"
|
|
|
|
|
\&\fB\-windowtitle\fR \fItext\fR \fB\-doctitle\fR \fItext\fR \fB\-title\fR \fItext\fR
|
|
|
|
|
\fB\-header\fR \fItext\fR \fB\-footer\fR \fItext\fR \fB\-bottom\fR \fItext\fR
|
|
|
|
|
\fB\-helpfile\fR \fIfile\fR \fB\-stylesheetfile\fR \fIfile\fR \fB\-addstylesheet\fR \fIfile\fR
|
|
|
|
|
\fB\-group\fR \fIgroupheading\fR\fB \fR\fIpkgpattern:pkgpattern:...\fR
|
|
|
|
|
.IP "\fITaglet Options\fR" 4
|
|
|
|
|
.IX Item "Taglet Options"
|
|
|
|
|
\&\fB\-tagletpath \-taglet\fR \fIclassname\fR \fB\-tag\fR \fItagspec\fR
|
|
|
|
|
.IP "\fIDoclet Options\fR" 4
|
|
|
|
|
.IX Item "Doclet Options"
|
|
|
|
|
\&\fB\-docletpath \-doclet\fR \fIclassname\fR
|
|
|
|
|
.IP "\fIVerbosity Options\fR" 4
|
|
|
|
|
.IX Item "Verbosity Options"
|
|
|
|
|
\&\fB\-quiet \-verbose\fR
|
|
|
|
|
.IP "\fIVirtual Machine Options\fR" 4
|
|
|
|
|
.IX Item "Virtual Machine Options"
|
2014-09-21 17:33:12 +00:00
|
|
|
\&\fB\-classpath \-bootclasspath \-J\fR \fIvmopt\fR
|
|
|
|
|
.SS "Selecting which Source Files to Process"
|
2012-03-27 23:13:14 +00:00
|
|
|
.IX Subsection "Selecting which Source Files to Process"
|
|
|
|
|
.IP "\fB\-s\fR \fIpathlist\fR" 4
|
|
|
|
|
.IX Item "-s pathlist"
|
|
|
|
|
.PD 0
|
|
|
|
|
.IP "\fB\-sourcepath\fR \fIpathlist\fR" 4
|
|
|
|
|
.IX Item "-sourcepath pathlist"
|
|
|
|
|
.PD
|
|
|
|
|
Look for source files in the specified directory or directories.
|
|
|
|
|
.Sp
|
|
|
|
|
\&\fIpathlist\fR should be one or more directory paths separated by your
|
|
|
|
|
platform's path separator (usually \fB:\fR or \fB;\fR).
|
|
|
|
|
.Sp
|
|
|
|
|
If this option is not given, \fBgjdoc\fR will look for source
|
|
|
|
|
files in the current directory.
|
|
|
|
|
.Sp
|
|
|
|
|
The directories specified should be root directories in terms of the
|
|
|
|
|
Java package system. For example, if you want to generate
|
|
|
|
|
documentation for classes in package \fBfoo.bar\fR, you must specify
|
|
|
|
|
the directory containing the top-level \fB\f(BIfoo\fB\fR
|
|
|
|
|
sub-directory, not the directory \fB\f(BIfoo/bar/\fB\fR in which the
|
|
|
|
|
Java source files reside.
|
|
|
|
|
.Sp
|
|
|
|
|
The short-hand alias \fB\-s\fR is specific to \fBgjdoc\fR and
|
|
|
|
|
not compatible to Sun \fBjavadoc\fR.
|
|
|
|
|
.IP "\fB\-all\fR" 4
|
|
|
|
|
.IX Item "-all"
|
|
|
|
|
\&\fI[\s-1EXPERIMENTAL\s0]\fR
|
|
|
|
|
Process all valid Java source files found in the directories listed in
|
|
|
|
|
the source path and their sub-directories.
|
|
|
|
|
.Sp
|
|
|
|
|
This is an option specific to \fBgjdoc\fR and not compatible to
|
|
|
|
|
Sun \fBjavadoc\fR.
|
|
|
|
|
.IP "\fB\-subpackages\fR \fIpkg:pkg:...\fR" 4
|
|
|
|
|
.IX Item "-subpackages pkg:pkg:..."
|
|
|
|
|
Process the classes in the given Java packages and all sub-packages,
|
|
|
|
|
recursively. Note that multiple package names must be separated with
|
|
|
|
|
colons instead of whitespace.
|
|
|
|
|
.IP "\fB\-exclude\fR \fIpkg:pkg:...\fR" 4
|
|
|
|
|
.IX Item "-exclude pkg:pkg:..."
|
|
|
|
|
Do not process classes in the given Java packages and all
|
|
|
|
|
sub-packages, recursively. This option can be used in conjunction
|
|
|
|
|
with \fB\-all\fR or \fB\-subpackages\fR in order to exclude
|
|
|
|
|
individual packages or package sub-trees from the output.
|
|
|
|
|
.IP "\fIpackages\fR\fB...\fR" 4
|
|
|
|
|
.IX Item "packages..."
|
|
|
|
|
Process all classes in the given Java packages.
|
|
|
|
|
.IP "\fIsourcefiles\fR\fB...\fR" 4
|
|
|
|
|
.IX Item "sourcefiles..."
|
|
|
|
|
Process the classes in the given Java source files.
|
2014-09-21 17:33:12 +00:00
|
|
|
.SS "Specifying the Format of Input Files"
|
2012-03-27 23:13:14 +00:00
|
|
|
.IX Subsection "Specifying the Format of Input Files"
|
|
|
|
|
.IP "\fB\-source\fR \fIrelease\fR" 4
|
|
|
|
|
.IX Item "-source release"
|
|
|
|
|
Assume that the source files are targeted at the given release of the
|
|
|
|
|
Java platform.
|
|
|
|
|
.Sp
|
|
|
|
|
\&\fIrelease\fR should be the version number of a Java platform release
|
2014-09-21 17:33:12 +00:00
|
|
|
in the format \s-1MAJOR.MINOR,\s0 for example \fB1.4\fR.
|
2012-03-27 23:13:14 +00:00
|
|
|
.Sp
|
|
|
|
|
This option is currently ignored except that an error is raised if a
|
|
|
|
|
release number other than \fB1.2\fR, \fB1.3\fR or \fB1.4\fR is
|
|
|
|
|
specified.
|
|
|
|
|
.IP "\fB\-encoding\fR \fIcharset\fR" 4
|
|
|
|
|
.IX Item "-encoding charset"
|
|
|
|
|
Assume that the source files are encoded using \fIcharset\fR.
|
|
|
|
|
.Sp
|
|
|
|
|
Examples for \fIcharset\fR are \fBUS-ASCII\fR, \fB\s-1ISO\-8859\-1\s0\fR or
|
|
|
|
|
\&\fB\s-1UTF\-8\s0\fR.
|
|
|
|
|
.Sp
|
|
|
|
|
The semantics of \fIcharset\fR are identical to those of \fBjava.nio.charset.Charset.forName(String)\fR.
|
|
|
|
|
.IP "\fB\-breakiterator\fR" 4
|
|
|
|
|
.IX Item "-breakiterator"
|
|
|
|
|
Use the locale's java.text.BreakIterator instead of the internal
|
|
|
|
|
first sentence detector.
|
|
|
|
|
.Sp
|
|
|
|
|
By default, \fBgjdoc\fR uses an internal algorithm to determine
|
|
|
|
|
where a sentence ends. When this option is given, it will instead use
|
|
|
|
|
the \fBjava.text.BreakIterator\fR instance for the locale given with
|
|
|
|
|
\&\fB\-locale\fR (or the default locale).
|
|
|
|
|
.Sp
|
|
|
|
|
This option should be specified when applying \fBgjdoc\fR to
|
|
|
|
|
source code commented in a non-latin language for which the default
|
|
|
|
|
first sentence detector does not work. For all other cases, the
|
|
|
|
|
default (do not use BreakIterator) produces better results at the time
|
|
|
|
|
of this writing.
|
2014-09-21 17:33:12 +00:00
|
|
|
.SS "Interlinking with other Documentation Sets"
|
2012-03-27 23:13:14 +00:00
|
|
|
.IX Subsection "Interlinking with other Documentation Sets"
|
|
|
|
|
.IP "\fB\-link\fR \fIurl\fR" 4
|
|
|
|
|
.IX Item "-link url"
|
|
|
|
|
Create hyperlinks to another documentation set.
|
|
|
|
|
.Sp
|
|
|
|
|
By default, \fBgjdoc\fR will only create hyperlinks to classes in
|
|
|
|
|
the source set. Use this option to additionally create hyperlinks to
|
|
|
|
|
classes covered by the specified documentation set.
|
|
|
|
|
.Sp
|
|
|
|
|
\&\fIurl\fR should be the root \s-1URL\s0 of the other documentation set. For
|
|
|
|
|
example, to add hyperlinks to \s-1GNU\s0 Classpath, specify the following:
|
|
|
|
|
.Sp
|
|
|
|
|
.Vb 1
|
|
|
|
|
\& \-link http://developer.classpath.org/doc/
|
|
|
|
|
.Ve
|
|
|
|
|
.Sp
|
|
|
|
|
The \fB\-link\fR option can be specified multiple times.
|
|
|
|
|
.Sp
|
|
|
|
|
Note that specifying the \fB\-link\fR option will cause an \s-1HTTP\s0
|
|
|
|
|
access every time gjdoc is invoked. You can use \fB\-linkoffline\fR
|
|
|
|
|
instead to avoid this access.
|
|
|
|
|
.IP "\fB\-linkoffline\fR \fIurl\fR\fB \fR\fIfile\fR" 4
|
|
|
|
|
.IX Item "-linkoffline url file"
|
|
|
|
|
Create hyperlinks to another documentation set which is also present
|
|
|
|
|
on the local file system.
|
|
|
|
|
.Sp
|
|
|
|
|
This option works exactly like \fB\-link\fR, except that it accesses
|
|
|
|
|
the local file system instead of the network for determining which
|
|
|
|
|
classes are covered by the linked documentation set.
|
|
|
|
|
.Sp
|
|
|
|
|
When using \fB\-linkoffline\fR the remote documentation set is not
|
|
|
|
|
accessed at all, which can significantly speed up generation time
|
|
|
|
|
depending on your network connection. The generated hyperlinks to the
|
|
|
|
|
documentation set however refer to the remote set, not to the local
|
|
|
|
|
one, so that you can distribute the documentation without any further
|
|
|
|
|
dependencies.
|
|
|
|
|
.Sp
|
|
|
|
|
The \fB\-linkoffline\fR option can be specified multiple times.
|
|
|
|
|
.IP "\fB\-noqualifier\fR \fIpkg:pkg:...\fR" 4
|
|
|
|
|
.IX Item "-noqualifier pkg:pkg:..."
|
|
|
|
|
Do not qualify names of classes in the given packages with their
|
|
|
|
|
package name.
|
|
|
|
|
.Sp
|
|
|
|
|
By default, a class name is displayed unqualified only if the class is
|
|
|
|
|
part of the source set or a linked documentation set, and qualified
|
|
|
|
|
with the name of its containing package if it is not. You can use this
|
|
|
|
|
option to force unqualified names for classes even if they are not
|
|
|
|
|
part of the documentation set.
|
|
|
|
|
.Sp
|
|
|
|
|
For example, usually a reference to the String class is represented
|
|
|
|
|
fully-qualified as \fBjava.lang.String\fR (unless you link to the
|
|
|
|
|
appropriate documentation set using \fB\-link\fR) because it isn't
|
|
|
|
|
part of the documentation set. You can specify \fB\-noqualifier
|
|
|
|
|
java.lang\fR to render the same references just as \fBString\fR.
|
|
|
|
|
.Sp
|
|
|
|
|
Note that for all unqualified class names, a tooltip is provided when
|
|
|
|
|
you place your mouse pointer over it in the \s-1HTML\s0 documentation.
|
|
|
|
|
.IP "\fB\-noqualifier\fR \fBall\fR" 4
|
|
|
|
|
.IX Item "-noqualifier all"
|
|
|
|
|
Omit package name qualifier from all class names.
|
|
|
|
|
.Sp
|
|
|
|
|
Specify this option to omit package name qualifiers altogether,
|
2014-09-21 17:33:12 +00:00
|
|
|
.SS "Selecting which Information to Generate"
|
2012-03-27 23:13:14 +00:00
|
|
|
.IX Subsection "Selecting which Information to Generate"
|
|
|
|
|
.IP "\fB\-public\fR" 4
|
|
|
|
|
.IX Item "-public"
|
|
|
|
|
Only include public members of public classes in the output. By
|
|
|
|
|
default, protected class members are included as well.
|
|
|
|
|
.IP "\fB\-protected\fR" 4
|
|
|
|
|
.IX Item "-protected"
|
|
|
|
|
Include public or protected members of public classes in the output.
|
|
|
|
|
This is the default.
|
|
|
|
|
.IP "\fB\-package\fR" 4
|
|
|
|
|
.IX Item "-package"
|
|
|
|
|
Include public, protected and package-private members of public and
|
|
|
|
|
package-private classes.
|
|
|
|
|
.IP "\fB\-private\fR" 4
|
|
|
|
|
.IX Item "-private"
|
|
|
|
|
Include all classes and class members regardless of their access
|
|
|
|
|
level.
|
|
|
|
|
.IP "\fB\-splitindex\fR" 4
|
|
|
|
|
.IX Item "-splitindex"
|
|
|
|
|
Generate one index page per letter instead of a single, monolithic
|
|
|
|
|
index page.
|
|
|
|
|
.Sp
|
|
|
|
|
By default, the index created by the Standard Doclet contains all
|
|
|
|
|
entries on a single page. This is fine for small documentation sets,
|
|
|
|
|
but for large sets you should specify this option.
|
|
|
|
|
.IP "\fB\-nosince\fR" 4
|
|
|
|
|
.IX Item "-nosince"
|
|
|
|
|
Ignore \fB\f(CB@since\fB\fR tags in javadoc comments.
|
|
|
|
|
.Sp
|
|
|
|
|
By default, the generated output contains sections listing the version
|
|
|
|
|
of your \s-1API\s0 since which the package, class or class member in question
|
|
|
|
|
exists when this tag is encountered. Specify this option to omit this
|
|
|
|
|
information.
|
|
|
|
|
.IP "\fB\-notree\fR" 4
|
|
|
|
|
.IX Item "-notree"
|
|
|
|
|
Do not generate any tree pages.
|
|
|
|
|
.Sp
|
|
|
|
|
By default, the generated output includes one inheritance tree per
|
|
|
|
|
package, and \- if the documentation set consists of multiple packages
|
|
|
|
|
\&\- a page with the full inheritance tree. Specify this option to omit
|
|
|
|
|
generation of these pages.
|
|
|
|
|
.IP "\fB\-noindex\fR" 4
|
|
|
|
|
.IX Item "-noindex"
|
|
|
|
|
Do not output the alphabetical index.
|
|
|
|
|
.Sp
|
|
|
|
|
By default, gjdoc generates an alphabetical index of all program
|
|
|
|
|
elements in the documentation set (packages, classes, inner classes,
|
|
|
|
|
constructors, methods, and fields). Specify this option to omit this
|
|
|
|
|
information.
|
|
|
|
|
.IP "\fB\-nohelp\fR" 4
|
|
|
|
|
.IX Item "-nohelp"
|
|
|
|
|
Do not generate the help page.
|
|
|
|
|
.Sp
|
|
|
|
|
This option is currently ignored as the Standard Doclet doesn't
|
|
|
|
|
provide a help page.
|
|
|
|
|
.IP "\fB\-nodeprecated\fR" 4
|
|
|
|
|
.IX Item "-nodeprecated"
|
|
|
|
|
Do not output inline information about deprecated packages, classes or
|
|
|
|
|
class members.
|
|
|
|
|
.Sp
|
|
|
|
|
By default, the Standard Doclet adds a highlighted paragraph with
|
|
|
|
|
deprecation information to the description of each deprecated program
|
|
|
|
|
element. Specify this option to omit this information.
|
|
|
|
|
.IP "\fB\-nodeprecatedlist\fR" 4
|
|
|
|
|
.IX Item "-nodeprecatedlist"
|
|
|
|
|
Do not output the summary page for deprecated \s-1API\s0 elements.
|
|
|
|
|
.Sp
|
|
|
|
|
By default, the Standard Doclet generates a page listing all
|
|
|
|
|
deprecated \s-1API\s0 elements along with a deprecation description which
|
|
|
|
|
usually includes the reason for deprecation and possible
|
|
|
|
|
alternatives. Specify this option to omit this information.
|
|
|
|
|
.IP "\fB\-nonavbar\fR" 4
|
|
|
|
|
.IX Item "-nonavbar"
|
|
|
|
|
Do not output the navigation bar, header, and footer.
|
|
|
|
|
.Sp
|
|
|
|
|
By default, each output page is equipped with a top navigation bar
|
|
|
|
|
(which may include a user-specified header) and a bottom navigation
|
|
|
|
|
bar (which may include a user-specified footer). Specify this option
|
|
|
|
|
to omit this decoration.
|
|
|
|
|
.IP "\fB\-nocomment\fR" 4
|
|
|
|
|
.IX Item "-nocomment"
|
|
|
|
|
Omit all documentation text from the generated files and output only
|
|
|
|
|
declarations and program element relationships.
|
|
|
|
|
.Sp
|
|
|
|
|
This option is here for compatibility with \fBjavadoc\fR. If you
|
|
|
|
|
plan on extracting information about your project via \fBgjdoc\fR,
|
|
|
|
|
you should consider using a different Doclet for your purposes
|
|
|
|
|
instead, for example XmlDoclet. You could also use the Doclet \s-1API\s0
|
|
|
|
|
directly by implementing a new Doclet.
|
|
|
|
|
.IP "\fB\-linksource\fR" 4
|
|
|
|
|
.IX Item "-linksource"
|
|
|
|
|
Generate a page with syntax-highlighted source code for each class.
|
|
|
|
|
By default, this page is not generated.
|
|
|
|
|
.Sp
|
|
|
|
|
The source code can be accessed by clicking on the button labelled
|
|
|
|
|
\&\*(L"Source\*(R" in the navigation bar, or by clicking on the name of a
|
|
|
|
|
constructor, field, method, or inner class in the detail section of a
|
|
|
|
|
class documentation page.
|
|
|
|
|
.IP "\fB\-use\fR" 4
|
|
|
|
|
.IX Item "-use"
|
|
|
|
|
Generate a page with cross-reference information. By default, this
|
|
|
|
|
page is not generated.
|
|
|
|
|
.Sp
|
|
|
|
|
The cross-reference information can be accessed by clicking on the
|
|
|
|
|
button labelled `Use' in the navigation bar.
|
|
|
|
|
.Sp
|
|
|
|
|
The `Use' page lists all classes/interfaces in the documentation set
|
|
|
|
|
that extend/implement the class (type) in question; fields of the
|
|
|
|
|
type; methods or constructors accepting a parameter of the type;
|
|
|
|
|
methods returning the type; and methods or constructors throwing the
|
|
|
|
|
type.
|
|
|
|
|
.IP "\fB\-author\fR" 4
|
|
|
|
|
.IX Item "-author"
|
|
|
|
|
Include author information in the output.
|
|
|
|
|
.Sp
|
|
|
|
|
When specified, author information as specified using the
|
|
|
|
|
\&\fB\f(CB@author\fB\fR tag in javadoc comments is incorporated into the
|
|
|
|
|
output. By default, \fB\f(CB@author\fB\fR tags are ignored.
|
|
|
|
|
.IP "\fB\-version\fR" 4
|
|
|
|
|
.IX Item "-version"
|
|
|
|
|
Include version information in the output.
|
|
|
|
|
.Sp
|
|
|
|
|
When specified, version information as specified using the
|
|
|
|
|
\&\fB\f(CB@version\fB\fR tag in javadoc comments is incorporated into the
|
|
|
|
|
output. By default, \fB\f(CB@version\fB\fR tags are ignored.
|
|
|
|
|
.IP "\fB\-licensetext\fR" 4
|
|
|
|
|
.IX Item "-licensetext"
|
|
|
|
|
Assume that the first comment in each source file contains the license
|
|
|
|
|
text, and add license information to the footer of each generated
|
|
|
|
|
class page.
|
|
|
|
|
.Sp
|
|
|
|
|
This is an option specific to \fBgjdoc\fR and not compatible to
|
|
|
|
|
Sun \fBjavadoc\fR.
|
|
|
|
|
.Sp
|
|
|
|
|
This option is intended for use with free and open source projects
|
|
|
|
|
where source code is typically prefixed with a boilerplate license
|
|
|
|
|
comment, when there are legal reasons for including the license in the
|
|
|
|
|
documentation.
|
|
|
|
|
.IP "\fB\-docfilessubdirs\fR" 4
|
|
|
|
|
.IX Item "-docfilessubdirs"
|
|
|
|
|
Recursively copy all files in the \fIdoc-files\fR sub-directory of each
|
|
|
|
|
package directory.
|
|
|
|
|
.Sp
|
|
|
|
|
Usually, only the files in the \fIdoc-files\fR sub-directory are copied
|
|
|
|
|
without descending recursively.
|
|
|
|
|
.IP "\fB\-excludedocfilessubdir\fR \fIname\fR\fB:\fR\fIname\fR\fB:...\fR" 4
|
|
|
|
|
.IX Item "-excludedocfilessubdir name:name:..."
|
|
|
|
|
Do not copy some directories directly under the \fIdoc-files\fR
|
|
|
|
|
sub-directories when descending recursively.
|
|
|
|
|
.Sp
|
|
|
|
|
The argument to this option should be a colon-separated list of
|
|
|
|
|
directory names.
|
|
|
|
|
.Sp
|
|
|
|
|
This option only makes sense if \fB\-docfilessubdirs\fR is also
|
|
|
|
|
specified. In this case, any sub-directory located directly beneath a
|
|
|
|
|
\&\fIdoc-files\fR directory is omitted if listed.
|
2014-09-21 17:33:12 +00:00
|
|
|
.SS "Custom Documentation Tags"
|
2012-03-27 23:13:14 +00:00
|
|
|
.IX Subsection "Custom Documentation Tags"
|
|
|
|
|
.IP "\fB\-tagletpath\fR \fIpathlist\fR" 4
|
|
|
|
|
.IX Item "-tagletpath pathlist"
|
|
|
|
|
Search \fIpathlist\fR when loading subsequent Taglet classes specified
|
|
|
|
|
using \fB\-taglet\fR.
|
|
|
|
|
.Sp
|
|
|
|
|
\&\fIpathlist\fR should be one or more paths to a directory or jar file,
|
|
|
|
|
separated by your platform's path separator (usually \fB:\fR or
|
|
|
|
|
\&\fB;\fR).
|
|
|
|
|
.IP "\fB\-taglet\fR \fIclassname\fR" 4
|
|
|
|
|
.IX Item "-taglet classname"
|
|
|
|
|
Register a Taglet.
|
|
|
|
|
.Sp
|
|
|
|
|
\&\fIclassname\fR should be the fully-qualified name of a Java class
|
|
|
|
|
implementing \fBcom.sun.tools.doclets.Taglet\fR.
|
|
|
|
|
.Sp
|
|
|
|
|
The Taglet classes will be loaded from the classpath specified using
|
|
|
|
|
\&\fB\-tagletpath\fR, from the classpath specified using
|
|
|
|
|
\&\fB\-classpath\fR and from the default classpath.
|
|
|
|
|
.Sp
|
|
|
|
|
See the documentation of \fBcom.sun.tools.doclets.Taglet\fR for
|
|
|
|
|
further information.
|
|
|
|
|
.Sp
|
|
|
|
|
Note that for simple tags, there is also \fB\-tag\fR.
|
|
|
|
|
.IP "\fB\-tag\fR \fItagspec\fR" 4
|
|
|
|
|
.IX Item "-tag tagspec"
|
|
|
|
|
Register a generic Taglet.
|
|
|
|
|
.Sp
|
|
|
|
|
The format of \fItagspec\fR must be \fB<tagname>:<flags>:\*(L"<taghead>\*(R"\fR.
|
|
|
|
|
.Sp
|
|
|
|
|
\&\fItagname\fR is the tag name to match, without the leading @ sign.
|
|
|
|
|
.Sp
|
|
|
|
|
\&\fIflags\fR is one or more of the following characters, where each
|
|
|
|
|
character specifies a source code context in which the tag is to be
|
|
|
|
|
recognized.
|
|
|
|
|
.RS 4
|
|
|
|
|
.IP "\fBa\fR" 4
|
|
|
|
|
.IX Item "a"
|
|
|
|
|
all contexts
|
|
|
|
|
.IP "\fBc\fR" 4
|
|
|
|
|
.IX Item "c"
|
|
|
|
|
constructors
|
|
|
|
|
.IP "\fBf\fR" 4
|
|
|
|
|
.IX Item "f"
|
|
|
|
|
fields
|
|
|
|
|
.IP "\fBm\fR" 4
|
|
|
|
|
.IX Item "m"
|
|
|
|
|
methods
|
|
|
|
|
.IP "\fBo\fR" 4
|
|
|
|
|
.IX Item "o"
|
|
|
|
|
overview
|
|
|
|
|
.IP "\fBp\fR" 4
|
|
|
|
|
.IX Item "p"
|
|
|
|
|
packages
|
|
|
|
|
.IP "\fBt\fR" 4
|
|
|
|
|
.IX Item "t"
|
|
|
|
|
types (classes, interfaces, exceptions, errors)
|
|
|
|
|
.IP "\fBX\fR" 4
|
|
|
|
|
.IX Item "X"
|
|
|
|
|
special character which temporarily disables the
|
|
|
|
|
Taglet altogether.
|
|
|
|
|
.RE
|
|
|
|
|
.RS 4
|
|
|
|
|
.Sp
|
|
|
|
|
\&\fItaghead\fR is the string to display in the header of the section
|
|
|
|
|
devoted to the tag in question.
|
|
|
|
|
.Sp
|
|
|
|
|
For example, to define a tag matching \fB\f(CB@cvsid\fB\fR which is to be
|
|
|
|
|
accepted in overview, package and type pages and which is labelled
|
2014-09-21 17:33:12 +00:00
|
|
|
with the header \fB\s-1CVS ID\s0\fR, you would specify:
|
2012-03-27 23:13:14 +00:00
|
|
|
.Sp
|
|
|
|
|
.Vb 1
|
|
|
|
|
\& \-tag cvsid:tpo:"CVS ID"
|
|
|
|
|
.Ve
|
|
|
|
|
.Sp
|
|
|
|
|
Let's say that a class javadoc comment contains
|
|
|
|
|
.Sp
|
|
|
|
|
.Vb 1
|
2014-09-21 17:33:12 +00:00
|
|
|
\& @cvsid $Id: cp\-tools.texinfo,v 1.9 2012\-03\-07 15:27:27 gnu_andrew Exp $
|
2012-03-27 23:13:14 +00:00
|
|
|
.Ve
|
|
|
|
|
.Sp
|
|
|
|
|
Then the \s-1HTML\s0 output will contain something like
|
|
|
|
|
.Sp
|
|
|
|
|
.Vb 2
|
|
|
|
|
\& CVS ID:
|
2014-09-21 17:33:12 +00:00
|
|
|
\& $Id: cp\-tools.texinfo,v 1.9 2012\-03\-07 15:27:27 gnu_andrew Exp $
|
2012-03-27 23:13:14 +00:00
|
|
|
.Ve
|
|
|
|
|
.RE
|
2014-09-21 17:33:12 +00:00
|
|
|
.SS "Running Other Doclets"
|
2012-03-27 23:13:14 +00:00
|
|
|
.IX Subsection "Running Other Doclets"
|
|
|
|
|
.IP "\fB\-docletpath\fR \fIpathlist\fR" 4
|
|
|
|
|
.IX Item "-docletpath pathlist"
|
|
|
|
|
Search \fIpathlist\fR when loading classes for the Doclet specified
|
|
|
|
|
using \fB\-doclet\fR.
|
|
|
|
|
.Sp
|
|
|
|
|
\&\fIpathlist\fR should be one or more paths to a directory or jar file,
|
|
|
|
|
separated by your platform's path separator (usually \fB:\fR or
|
|
|
|
|
\&\fB;\fR).
|
|
|
|
|
.IP "\fB\-doclet\fR \fIclassName\fR" 4
|
|
|
|
|
.IX Item "-doclet className"
|
|
|
|
|
Run the specified doclet instead of the standard HtmlDoclet.
|
|
|
|
|
.Sp
|
|
|
|
|
\&\fIclassName\fR should be the fully-qualified name of a class which
|
|
|
|
|
has a public default constructor and contain a method with the
|
|
|
|
|
following signature:
|
|
|
|
|
.Sp
|
|
|
|
|
.Vb 2
|
|
|
|
|
\& import com.sun.javadoc.RootDoc;
|
|
|
|
|
\& public static boolean start(RootDoc rootDoc)
|
|
|
|
|
.Ve
|
|
|
|
|
.Sp
|
|
|
|
|
The Doclet classes will be loaded from the classpath specified using
|
|
|
|
|
\&\fB\-docletpath\fR, from the classpath specified using
|
|
|
|
|
\&\fB\-classpath\fR and from the default classpath.
|
|
|
|
|
.Sp
|
|
|
|
|
The \fBstart\fR method should process the information exposed by the
|
|
|
|
|
Doclet \s-1API\s0 via \fBrootDoc\fR and return \fBtrue\fR on success,
|
|
|
|
|
\&\fBfalse\fR on failure.
|
|
|
|
|
.Sp
|
|
|
|
|
If you are using a third-party doclet, refer to its documentation for
|
|
|
|
|
further instructions. Note that support for third-party doclets is
|
|
|
|
|
experimental. Please report any problems you encounter, or provide
|
|
|
|
|
feedback when successfully running third-party applets.
|
|
|
|
|
.Sp
|
|
|
|
|
This option can be specified multiple times, in which case all doclets
|
|
|
|
|
are executed with the same information tree exposed via the Doclet \s-1API\s0
|
|
|
|
|
for each Doclet run.
|
2014-09-21 17:33:12 +00:00
|
|
|
.SS "Adding Information to the Output"
|
2012-03-27 23:13:14 +00:00
|
|
|
.IX Subsection "Adding Information to the Output"
|
|
|
|
|
.IP "\fB\-windowtitle\fR \fItext\fR" 4
|
|
|
|
|
.IX Item "-windowtitle text"
|
|
|
|
|
Use \fItext\fR as the browser window title prefix.
|
|
|
|
|
.Sp
|
|
|
|
|
When specified, the browser window title for each page will be
|
|
|
|
|
prefixed with \fItext\fR instead of the default string \fBGenerated
|
|
|
|
|
\&\s-1API\s0 Documentation\fR.
|
|
|
|
|
.Sp
|
|
|
|
|
\&\fItext\fR should be plain text (it should not contain \s-1HTML\s0 tags).
|
|
|
|
|
.IP "\fB\-doctitle\fR \fItext\fR" 4
|
|
|
|
|
.IX Item "-doctitle text"
|
|
|
|
|
Set the header text of the overview page to \fItext\fR.
|
|
|
|
|
.Sp
|
|
|
|
|
\&\fItext\fR should be a short plain text string.
|
|
|
|
|
.Sp
|
|
|
|
|
When generating documentation for a single package, specifying this
|
|
|
|
|
option forces generation of the overview page.
|
|
|
|
|
.IP "\fB\-header\fR \fIhtmltext\fR" 4
|
|
|
|
|
.IX Item "-header htmltext"
|
|
|
|
|
Add \fIhtmltext\fR to the right upper corner of every generated page.
|
|
|
|
|
\&\fIhtmltext\fR is usually set to the name of the project being
|
|
|
|
|
documented.
|
|
|
|
|
.IP "\fB\-footer\fR \fIhtmltext\fR" 4
|
|
|
|
|
.IX Item "-footer htmltext"
|
|
|
|
|
Add \fIhtmltext\fR to the right bottom corner of every generated page.
|
|
|
|
|
\&\fIhtmltext\fR is often set to the same value as for \fB\-header\fR.
|
|
|
|
|
.IP "\fB\-bottom\fR \fIhtmltext\fR" 4
|
|
|
|
|
.IX Item "-bottom htmltext"
|
|
|
|
|
Add \fIhtmltext\fR to the very bottom of every generated page,
|
|
|
|
|
spanning the whole width of the page. When specified, \fIhtmltext\fR
|
|
|
|
|
usually consists of a copyright notice and/or links to other project
|
|
|
|
|
pages.
|
|
|
|
|
.IP "\fB\-addstylesheet\fR \fIfile\fR" 4
|
|
|
|
|
.IX Item "-addstylesheet file"
|
|
|
|
|
Augment the default \s-1CSS\s0 style sheets with the user-specified
|
|
|
|
|
stylesheet \fIfile\fR.
|
|
|
|
|
.Sp
|
|
|
|
|
The given stylesheet is simply loaded by each \s-1HTML\s0 page in addition to
|
|
|
|
|
the default ones, as the last stylesheet.
|
|
|
|
|
.Sp
|
|
|
|
|
Note that the \s-1CSS\s0 cascading rules apply. That is, your style
|
|
|
|
|
properties will only be assigned if they have a higher cascading order
|
|
|
|
|
than \fBgjdoc\fR's default style. One simple way to make sure
|
|
|
|
|
that this is the case is to declare your overrides \fB!important\fR.
|
|
|
|
|
.Sp
|
|
|
|
|
See <\fBhttp://www.w3.org/TR/REC\-CSS2/cascade.html#cascading\-order\fR>.
|
|
|
|
|
.IP "\fB\-group\fR \fIheading\fR\fB \fR\fIpkgwildcard\fR\fB:\fR\fIpkgwildcard\fR\fB:...\fR" 4
|
|
|
|
|
.IX Item "-group heading pkgwildcard:pkgwildcard:..."
|
|
|
|
|
Arrange the given packages in a separate group on the overview page.
|
|
|
|
|
.Sp
|
|
|
|
|
The first argument should be a short plain text which is used as the
|
|
|
|
|
title of the package group. The second argument should be a
|
|
|
|
|
colon-separated list of package wildcards. The group will consist of
|
|
|
|
|
all packages in the documentation set whose name matches any of the
|
|
|
|
|
given wildcards.
|
|
|
|
|
.Sp
|
|
|
|
|
There is only one wildcard character, \fB*\fR, which matches both
|
|
|
|
|
letters in package name components and the \fB.\fR separating package
|
|
|
|
|
name components. For example, \fBj*regex\fR would match package
|
|
|
|
|
\&\fBjava.util.regex\fR. A more useful example would be
|
|
|
|
|
\&\fBjavax.swing*\fR to match \fBjavax.swing\fR and all of its
|
|
|
|
|
sub-packages.
|
|
|
|
|
.Sp
|
|
|
|
|
This option can be given multiple times.
|
|
|
|
|
.Sp
|
|
|
|
|
\&\s-1FIXME:\s0 Information about group nesting here.
|
|
|
|
|
.Sp
|
|
|
|
|
.Vb 5
|
|
|
|
|
\& gjdoc \-group "Core Classes" \*(Aqjava*\*(Aq \e
|
|
|
|
|
\& \-group "Swing" \*(Aqjavax.swing*\*(Aq \e
|
|
|
|
|
\& \-group "XML APIs" \*(Aqjavax.xml*\*(Aq \e
|
|
|
|
|
\& \-group "Other Extensions" javax* \e
|
|
|
|
|
\& ...
|
|
|
|
|
.Ve
|
|
|
|
|
.IP "\fB\-overview\fR \fIfile\fR" 4
|
|
|
|
|
.IX Item "-overview file"
|
|
|
|
|
Add the \s-1XHTML\s0 body fragment from \fIfile\fR to the overview page.
|
|
|
|
|
.Sp
|
2014-09-21 17:33:12 +00:00
|
|
|
\&\fIfile\fR should contain an \s-1XHTML\s0 fragment with the \s-1HTML \s0\fBbody\fR
|
2012-03-27 23:13:14 +00:00
|
|
|
tag as the root node.
|
|
|
|
|
.Sp
|
|
|
|
|
This option can be used to supply a description of the documentation
|
|
|
|
|
set as a whole.
|
|
|
|
|
.Sp
|
|
|
|
|
When specified, the first sentence of the fragment will be put above
|
|
|
|
|
the tables listing the documented packages, along with a link to the
|
|
|
|
|
full copy of the fragment which is put below the tables.
|
|
|
|
|
.Sp
|
|
|
|
|
When generating documentation for a single package, specifying this
|
|
|
|
|
option forces generation of the overview page.
|
|
|
|
|
.IP "\fB\-stylesheetfile\fR \fIfile\fR" 4
|
|
|
|
|
.IX Item "-stylesheetfile file"
|
|
|
|
|
Use the \s-1CSS\s0 stylesheet in \fIfile\fR instead of the default \s-1CSS\s0
|
|
|
|
|
stylesheets.
|
|
|
|
|
.Sp
|
|
|
|
|
If you only want to override parts of the default stylesheets, use
|
|
|
|
|
\&\fB\-addstylesheet\fR instead.
|
|
|
|
|
.IP "\fB\-title\fR \fItext\fR" 4
|
|
|
|
|
.IX Item "-title text"
|
|
|
|
|
\&\fIDeprecated.\fR Use \fB\-doctitle\fR \fItext\fR instead.
|
|
|
|
|
.IP "\fB\-helpfile\fR \fIfile\fR" 4
|
|
|
|
|
.IX Item "-helpfile file"
|
|
|
|
|
This option is currently ignored.
|
|
|
|
|
.Sp
|
|
|
|
|
When implemented, it will use the \s-1XHTML\s0 fragment in \fIfile\fR for the
|
|
|
|
|
help page contents instead of the default help text.
|
2014-09-21 17:33:12 +00:00
|
|
|
.SS "Controlling the Output."
|
2012-03-27 23:13:14 +00:00
|
|
|
.IX Subsection "Controlling the Output."
|
|
|
|
|
.IP "\fB\-d\fR \fIdirectory\fR" 4
|
|
|
|
|
.IX Item "-d directory"
|
|
|
|
|
Place all output files into \fIdirectory\fR (and
|
|
|
|
|
sub-directories). \fIdirectory\fR will be created if it does not
|
|
|
|
|
exist, including all non-existing parent directories and all required
|
|
|
|
|
sub-directories.
|
|
|
|
|
.Sp
|
|
|
|
|
If not specified, output will be placed into the current directory.
|
|
|
|
|
.IP "\fB\-locale\fR \fIname\fR" 4
|
|
|
|
|
.IX Item "-locale name"
|
|
|
|
|
Use locale \fIname\fR instead of the default locale for all purposes.
|
|
|
|
|
.Sp
|
|
|
|
|
\&\fIname\fR should be a locale specifier in the form \fBll_CC[_VAR]\fR
|
|
|
|
|
where \fBll\fR is a lowercase two-letter \s-1ISO\-639\s0 language code,
|
|
|
|
|
\&\fB\s-1CC\s0\fR is an optional uppercase two-letter \s-1ISO\-3166\s0 country code,
|
|
|
|
|
and \fB\s-1VAR\s0\fR is an optional variant code. For example, \fBen\fR
|
|
|
|
|
specifies English, \fBen_US\fR specifies \s-1US\s0 English, and
|
|
|
|
|
\&\fBen_US_WIN\fR specifies a deviant variant of the \s-1US\s0 English locale.
|
|
|
|
|
.Sp
|
|
|
|
|
Note that the semantics of this option correspond exactly to those of
|
|
|
|
|
the constructors of class \fBjava.util.Locale\fR.
|
|
|
|
|
.Sp
|
|
|
|
|
This option currently only determines which Collator is being used for
|
|
|
|
|
sorting output elements. This means that the locale will only have an
|
|
|
|
|
effect when you are using non-ASCII characters in identifiers.
|
|
|
|
|
.IP "\fB\-charset\fR \fIcharset\fR" 4
|
|
|
|
|
.IX Item "-charset charset"
|
|
|
|
|
\&\fIDeprecated.\fR Override the specified encoding in output \s-1XHTML\s0
|
|
|
|
|
files with the one given by \fBcharset\fR.
|
|
|
|
|
.Sp
|
|
|
|
|
If this option is not given, the encoding specification in output
|
|
|
|
|
\&\s-1XHTML\s0 is chosen to match the encoding used when writing the file (the
|
|
|
|
|
encoding given with \fB\-docencoding\fR, or your platform's default
|
|
|
|
|
encoding).
|
|
|
|
|
.Sp
|
|
|
|
|
The semantics for \fIcharset\fR are specified here:
|
|
|
|
|
<\fBhttp://www.w3.org/TR/2000/REC\-xml\-20001006#NT\-EncName\fR>. For
|
|
|
|
|
all practical purposes, they are identical to those of the other
|
|
|
|
|
options accepting charset parameters.
|
|
|
|
|
.Sp
|
|
|
|
|
This option is here for compatibility with \fBjavadoc\fR and
|
|
|
|
|
should be avoided.
|
|
|
|
|
.IP "\fB\-docencoding\fR \fIcharset\fR" 4
|
|
|
|
|
.IX Item "-docencoding charset"
|
|
|
|
|
Use the given charset encoding when writing output files instead of
|
|
|
|
|
your platform's default encoding.
|
|
|
|
|
.Sp
|
|
|
|
|
Examples for \fIcharset\fR are \fBUS-ASCII\fR, \fB\s-1ISO\-8859\-1\s0\fR or
|
|
|
|
|
\&\fB\s-1UTF\-8\s0\fR.
|
|
|
|
|
.Sp
|
|
|
|
|
The semantics of this option correspond exactly to those of the
|
|
|
|
|
constructors of class \fBjava.util.Locale\fR.
|
|
|
|
|
.IP "\fB\-validhtml\fR" 4
|
|
|
|
|
.IX Item "-validhtml"
|
|
|
|
|
Force generation of valid \s-1XHTML\s0 code. This breaks compatibility to
|
|
|
|
|
the traditional Javadoc tool to some extent.
|
|
|
|
|
.Sp
|
|
|
|
|
If this option is specified, anchor names will be mangled so that they
|
2014-09-21 17:33:12 +00:00
|
|
|
are valid according to the \s-1XHTML 1.1\s0 specification. However, a
|
2012-03-27 23:13:14 +00:00
|
|
|
documentation set generated with this option cannot be linked to
|
|
|
|
|
properly using the traditional Javadoc tool. It can be linked to just
|
|
|
|
|
fine using Gjdoc, though.
|
|
|
|
|
.Sp
|
|
|
|
|
Without this option, anchor names for executable class members use the
|
|
|
|
|
traditional format, for example: \*(L"foo(String,int[])\*(R". This is
|
|
|
|
|
compatible to the traditional Javadoc tool, but according to both the
|
2014-09-21 17:33:12 +00:00
|
|
|
\&\s-1HTML 4.0\s0 and \s-1XHTML 1.0\s0 and 1.1 specifications, this format includes
|
2012-03-27 23:13:14 +00:00
|
|
|
illegal characters. Parentheses, square brackets, and the comma are
|
|
|
|
|
not allowed in anchor names.
|
|
|
|
|
.IP "\fB\-baseurl\fR \fIurl\fR" 4
|
|
|
|
|
.IX Item "-baseurl url"
|
|
|
|
|
Hardwire a page \s-1URL\s0 relative to \fIurl\fR into each generated page.
|
|
|
|
|
.Sp
|
|
|
|
|
If you are generating documentation which will exclusively be
|
2014-09-21 17:33:12 +00:00
|
|
|
available at a certain \s-1URL,\s0 you should use this option to specify this
|
|
|
|
|
\&\s-1URL.\s0
|
2012-03-27 23:13:14 +00:00
|
|
|
.Sp
|
|
|
|
|
This can help avoid certain redirect attacks used by spammers, and it
|
|
|
|
|
can be helpful for certain web clients.
|
2014-09-21 17:33:12 +00:00
|
|
|
.SS "Verbosity Options"
|
2012-03-27 23:13:14 +00:00
|
|
|
.IX Subsection "Verbosity Options"
|
|
|
|
|
.IP "\fB\-quiet\fR" 4
|
|
|
|
|
.IX Item "-quiet"
|
|
|
|
|
Suppress all output except for warnings and error messages.
|
|
|
|
|
.IP "\fB\-verbose\fR" 4
|
|
|
|
|
.IX Item "-verbose"
|
|
|
|
|
Be very verbose about what \fBgjdoc\fR is doing.
|
|
|
|
|
.Sp
|
|
|
|
|
This option is currently ignored.
|
2014-09-21 17:33:12 +00:00
|
|
|
.SS "Virtual Machine Options"
|
2012-03-27 23:13:14 +00:00
|
|
|
.IX Subsection "Virtual Machine Options"
|
|
|
|
|
Sun's \fBjavadoc\fR tool seems to be based on \fBjavac\fR and
|
|
|
|
|
as such it seems to operate on the \s-1VM\s0 level. \fBgjdoc\fR, in
|
|
|
|
|
contrast, is a pure Java application.
|
|
|
|
|
.PP
|
|
|
|
|
Therefore, \fBgjdoc\fR can only fake, or simulate, the following
|
|
|
|
|
VM-level options.
|
|
|
|
|
.IP "\fB\-classpath\fR \fIpathlist\fR" 4
|
|
|
|
|
.IX Item "-classpath pathlist"
|
|
|
|
|
Set the Virtual Machine \fBclasspath\fR to \fIpathlist\fR.
|
|
|
|
|
.Sp
|
|
|
|
|
In most cases you should use \fB\-docletpath\fR or
|
|
|
|
|
\&\fB\-tagletpath\fR instead of this option.
|
|
|
|
|
.Sp
|
|
|
|
|
\&\fIpathlist\fR should be one or more paths to a directory or jar file,
|
|
|
|
|
separated by your platform's path separator (usually \fB:\fR or
|
|
|
|
|
\&\fB;\fR).
|
|
|
|
|
.Sp
|
|
|
|
|
If this option is not intercepted at the wrapper level,
|
|
|
|
|
\&\fBgjdoc\fR currently fakes it by calling
|
|
|
|
|
\&\fBSystem.setProperty(\*(L"java.class.path\*(R",\fR \fIpathlist\fR\fB);\fR and
|
|
|
|
|
outputs a warning.
|
|
|
|
|
.IP "\fB\-bootclasspath\fR \fIpathlist\fR" 4
|
|
|
|
|
.IX Item "-bootclasspath pathlist"
|
|
|
|
|
Set the Virtual Machine \fBbootclasspath\fR to \fIpathlist\fR.
|
|
|
|
|
.Sp
|
|
|
|
|
If this option is not intercepted at the wrapper level,
|
|
|
|
|
\&\fBgjdoc\fR outputs a warning.
|
|
|
|
|
.IP "\fB\-J\fR\fIvmopt\fR" 4
|
|
|
|
|
.IX Item "-Jvmopt"
|
|
|
|
|
Pass an arbitrary parameter to the Virtual Machine \fBgjdoc\fR
|
|
|
|
|
runs on.
|
|
|
|
|
.Sp
|
|
|
|
|
If this option is not intercepted at the wrapper level,
|
|
|
|
|
\&\fBgjdoc\fR tries to emulate the option and outputs a warning.
|
|
|
|
|
.Sp
|
|
|
|
|
Currently, only the \s-1VM\s0 option \fB\-D\fR for setting system
|
|
|
|
|
properties is emulated.
|
|
|
|
|
.SH "BUGS"
|
|
|
|
|
.IX Header "BUGS"
|
|
|
|
|
Please report bugs to <\fBhttp://savannah.gnu.org/bugs/?group=classpath\fR>.
|
|
|
|
|
.SH "SEE ALSO"
|
|
|
|
|
.IX Header "SEE ALSO"
|
|
|
|
|
Info entry for \fIgjdoc\fR.
|
|
|
|
|
.SH "AUTHOR"
|
|
|
|
|
.IX Header "AUTHOR"
|
|
|
|
|
Julian Scheid
|
