libjava/classpath/doc/gjdoc.1

   1 .\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "GJDOC 1"
 127 .TH GJDOC 1 "2013-05-31" "0.99.1-pre" "GNU"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 cp\-tools \- GNU Classpath Tools Guide
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 gjdoc [\fB\-sourcepath\fR \fIpathlist\fR]
 137       [\fB\-all\fR] [\fB\-subpackages\fR \fIpkg:pkg:...\fR] [\fB\-exclude\fR \fIpkglist\fR]
 138       [\fB\-encoding\fR \fIcharset\fR] [\fB\-locale\fR \fIname\fR] [\fB\-source\fR \fIrelease\fR]
 139       [\fB\-public\fR] [\fB\-protected\fR] [\fB\-package\fR] [\fB\-private\fR]
 140       [\fB\-doctitle\fR \fItext\fR] [\fB\-header\fR \fItext\fR] [\fB\-footer\fR \fItext\fR] [\fB\-bottom\fR \fItext\fR]
 141       [\fB\-link\fR \fIurl\fR] [\fB\-linkoffline\fR \fIurl\fR \fIpath\fR] [\fB\-noqualifier\fR \fIpkg:pkg:...\fR]
 142       [\fB\-tagletpath\fR \fIpathlist\fR] [\fB\-taglet\fR \fIclassName\fR] [\fB\-tag\fR \fItagspec\fR]
 143       [\fB\-use\fR] [\fB\-linksource\fR] [\fB\-splitindex\fR] [\fB\-noindex\fR] [\fB\-notree\fR]
 144       [\fB\-version\fR] [\fB\-author\fR] [\fB\-nosince\fR] [\fB\-addstylesheet\fR \fIfile\fR]
 145       [\fB\-d\fR \fItargetdir\fR]
 146       [\fIpackages\fR...] [\fIsourcefiles\fR...] [@\fIcmdfile\fR]
 147 .PP
 148 gjdoc [\fB\-sourcepath\fR \fIpathlist\fR]
 149       [\fB\-all\fR] [\fB\-subpackages\fR \fIpkg:pkg:...\fR] [\fB\-exclude\fR \fIpkglist\fR]
 150       [\fB\-encoding\fR \fIcharset\fR] [\fB\-locale\fR \fIname\fR] [\fB\-source\fR \fIrelease\fR]
 151       [\fB\-public\fR] [\fB\-protected\fR] [\fB\-package\fR] [\fB\-private\fR]
 152       [\fB\-docletpath\fR \fIpathlist\fR] [\fB\-doclet\fR \fIclassName\fR]
 153       [\fIpackages\fR...] [\fIsourcefiles\fR...] [@\fIcmdfile\fR]
 154       [doclet options]
 155 .PP
 156 gjdoc \fB\-\-help\fR
 157 .PP
 158 gjdoc \fB\-\-version\fR
 159 .PP
 160 Only the most useful options are listed here; see below for the
 161 remainder.
 162 .SH "DESCRIPTION"
 163 .IX Header "DESCRIPTION"
 164 Gjdoc can be used in two ways: as a stand-alone documentation tool, or
 165 as a driver for a user-specified Doclet.
 166 .PP
 167 In the default mode, Gjdoc will use the Standard Doclet
 168 \&\fBHtmlDoclet\fR to generate a set of \s-1HTML\s0 pages.  The canonical
 169 usage is:
 170 .PP
 171 .Vb 1
 172 \&        gjdoc \-s src/java/ \-all \-d api\-docs/
 173 .Ve
 174 .PP
 175 Here, \fBsrc/java/\fR is the root of your source code class
 176 hierarchy, \fB\-all\fR means that all valid Java files found under
 177 this root directory should be processed, and \fBapi\-docs/\fR is the
 178 directory where the generated documentation should be placed.
 179 .PP
 180 To learn more about running Doclets other than the Standard Doclet,
 181 refer to the manual.
 182 .SH "OPTIONS"
 183 .IX Header "OPTIONS"
 184 .SS "Option Summary by Type"
 185 .IX Subsection "Option Summary by Type"
 186 Here is a summary of all the options of both Gjdoc and the Standard
 187 Doclet, grouped by type.  Explanations are in the following sections.
 188 .IP "\fISource Set Options\fR" 4
 189 .IX Item "Source Set Options"
 190 \&\fB\-sourcepath\fR \fIpathlist\fR  \fB\-subpackages\fR \fIpkglist\fR  \fB\-exclude\fR \fIpkglist\fR
 191 .IP "\fISource Format Options\fR" 4
 192 .IX Item "Source Format Options"
 193 \&\fB\-source\fR \fIrelease\fR  \fB\-encoding\fR \fIencoding\fR  \fB\-breakiterator\fR
 194 .IP "\fIInterlinking Options\fR" 4
 195 .IX Item "Interlinking Options"
 196 \&\fB\-link\fR \fIurl\fR  \fB\-linkoffline\fR \fIurl\fR\fB \fR\fIfile\fR  \fB\-noqualifier\fR \fIpkg:pkg:...\fR
 197 .IP "\fIGeneration Options\fR" 4
 198 .IX Item "Generation Options"
 199 \&\fB\-author  \-licensetext  \-use  \-version  \-splitindex  \-noindex
 200  \-nodeprecated  \-nodeprecatedlist  \-nohelp  \-nonavbar
 201  \-nosince  \-notree  \-public  \-protected  \-package  \-private
 202  \-docfilessubdirs  \-excludedocfilessubdir\fR \fIdirname\fR
 203  \fB\-linksource\fR
 204 .IP "\fIOutput Options\fR" 4
 205 .IX Item "Output Options"
 206 \&\fB\-d  \-locale\fR \fIname\fR  \fB\-charset\fR \fIcharset\fR  \fB\-docencoding\fR \fIcharset\fR
 207  \fB\-validhtml  \-baseurl\fR \fIurl\fR
 208 .IP "\fIDecoration Options\fR" 4
 209 .IX Item "Decoration Options"
 210 \&\fB\-windowtitle\fR \fItext\fR  \fB\-doctitle\fR \fItext\fR  \fB\-title\fR \fItext\fR
 211  \fB\-header\fR \fItext\fR  \fB\-footer\fR \fItext\fR  \fB\-bottom\fR \fItext\fR
 212  \fB\-helpfile\fR \fIfile\fR  \fB\-stylesheetfile\fR \fIfile\fR  \fB\-addstylesheet\fR \fIfile\fR
 213  \fB\-group\fR \fIgroupheading\fR\fB \fR\fIpkgpattern:pkgpattern:...\fR
 214 .IP "\fITaglet Options\fR" 4
 215 .IX Item "Taglet Options"
 216 \&\fB\-tagletpath  \-taglet\fR \fIclassname\fR  \fB\-tag\fR \fItagspec\fR
 217 .IP "\fIDoclet Options\fR" 4
 218 .IX Item "Doclet Options"
 219 \&\fB\-docletpath  \-doclet\fR \fIclassname\fR
 220 .IP "\fIVerbosity Options\fR" 4
 221 .IX Item "Verbosity Options"
 222 \&\fB\-quiet  \-verbose\fR
 223 .IP "\fIVirtual Machine Options\fR" 4
 224 .IX Item "Virtual Machine Options"
 225 \&\fB\-classpath  \-bootclasspath  \-J\fR \fIvmopt\fR
 226 .SS "Selecting which Source Files to Process"
 227 .IX Subsection "Selecting which Source Files to Process"
 228 .IP "\fB\-s\fR \fIpathlist\fR" 4
 229 .IX Item "-s pathlist"
 230 .PD 0
 231 .IP "\fB\-sourcepath\fR \fIpathlist\fR" 4
 232 .IX Item "-sourcepath pathlist"
 233 .PD
 234 Look for source files in the specified directory or directories.
 235 .Sp
 236 \&\fIpathlist\fR should be one or more directory paths separated by your
 237 platform's path separator (usually \fB:\fR or \fB;\fR).
 238 .Sp
 239 If this option is not given, \fBgjdoc\fR will look for source
 240 files in the current directory.
 241 .Sp
 242 The directories specified should be root directories in terms of the
 243 Java package system.  For example, if you want to generate
 244 documentation for classes in package \fBfoo.bar\fR, you must specify
 245 the directory containing the top-level \fB\f(BIfoo\fB\fR
 246 sub-directory, not the directory \fB\f(BIfoo/bar/\fB\fR in which the
 247 Java source files reside.
 248 .Sp
 249 The short-hand alias \fB\-s\fR is specific to \fBgjdoc\fR and
 250 not compatible to Sun \fBjavadoc\fR.
 251 .IP "\fB\-all\fR" 4
 252 .IX Item "-all"
 253 \&\fI[\s-1EXPERIMENTAL\s0]\fR
 254 Process all valid Java source files found in the directories listed in
 255 the source path and their sub-directories.
 256 .Sp
 257 This is an option specific to \fBgjdoc\fR and not compatible to
 258 Sun \fBjavadoc\fR.
 259 .IP "\fB\-subpackages\fR \fIpkg:pkg:...\fR" 4
 260 .IX Item "-subpackages pkg:pkg:..."
 261 Process the classes in the given Java packages and all sub-packages,
 262 recursively.  Note that multiple package names must be separated with
 263 colons instead of whitespace.
 264 .IP "\fB\-exclude\fR \fIpkg:pkg:...\fR" 4
 265 .IX Item "-exclude pkg:pkg:..."
 266 Do not process classes in the given Java packages and all
 267 sub-packages, recursively.  This option can be used in conjunction
 268 with \fB\-all\fR or \fB\-subpackages\fR in order to exclude
 269 individual packages or package sub-trees from the output.
 270 .IP "\fIpackages\fR\fB...\fR" 4
 271 .IX Item "packages..."
 272 Process all classes in the given Java packages.
 273 .IP "\fIsourcefiles\fR\fB...\fR" 4
 274 .IX Item "sourcefiles..."
 275 Process the classes in the given Java source files.
 276 .SS "Specifying the Format of Input Files"
 277 .IX Subsection "Specifying the Format of Input Files"
 278 .IP "\fB\-source\fR \fIrelease\fR" 4
 279 .IX Item "-source release"
 280 Assume that the source files are targeted at the given release of the
 281 Java platform.
 282 .Sp
 283 \&\fIrelease\fR should be the version number of a Java platform release
 284 in the format \s-1MAJOR\s0.MINOR, for example \fB1.4\fR.
 285 .Sp
 286 This option is currently ignored except that an error is raised if a
 287 release number other than \fB1.2\fR, \fB1.3\fR or \fB1.4\fR is
 288 specified.
 289 .IP "\fB\-encoding\fR \fIcharset\fR" 4
 290 .IX Item "-encoding charset"
 291 Assume that the source files are encoded using \fIcharset\fR.
 292 .Sp
 293 Examples for \fIcharset\fR are \fBUS-ASCII\fR, \fB\s-1ISO\-8859\-1\s0\fR or
 294 \&\fB\s-1UTF\-8\s0\fR.
 295 .Sp
 296 The semantics of \fIcharset\fR are identical to those of \fBjava.nio.charset.Charset.forName(String)\fR.
 297 .IP "\fB\-breakiterator\fR" 4
 298 .IX Item "-breakiterator"
 299 Use the locale's java.text.BreakIterator instead of the internal
 300 first sentence detector.
 301 .Sp
 302 By default, \fBgjdoc\fR uses an internal algorithm to determine
 303 where a sentence ends. When this option is given, it will instead use
 304 the \fBjava.text.BreakIterator\fR instance for the locale given with
 305 \&\fB\-locale\fR (or the default locale).
 306 .Sp
 307 This option should be specified when applying \fBgjdoc\fR to
 308 source code commented in a non-latin language for which the default
 309 first sentence detector does not work. For all other cases, the
 310 default (do not use BreakIterator) produces better results at the time
 311 of this writing.
 312 .SS "Interlinking with other Documentation Sets"
 313 .IX Subsection "Interlinking with other Documentation Sets"
 314 .IP "\fB\-link\fR \fIurl\fR" 4
 315 .IX Item "-link url"
 316 Create hyperlinks to another documentation set.
 317 .Sp
 318 By default, \fBgjdoc\fR will only create hyperlinks to classes in
 319 the source set.  Use this option to additionally create hyperlinks to
 320 classes covered by the specified documentation set.
 321 .Sp
 322 \&\fIurl\fR should be the root \s-1URL\s0 of the other documentation set. For
 323 example, to add hyperlinks to \s-1GNU\s0 Classpath, specify the following:
 324 .Sp
 325 .Vb 1
 326 \&        \-link http://developer.classpath.org/doc/
 327 .Ve
 328 .Sp
 329 The \fB\-link\fR option can be specified multiple times.
 330 .Sp
 331 Note that specifying the \fB\-link\fR option will cause an \s-1HTTP\s0
 332 access every time gjdoc is invoked. You can use \fB\-linkoffline\fR
 333 instead to avoid this access.
 334 .IP "\fB\-linkoffline\fR \fIurl\fR\fB \fR\fIfile\fR" 4
 335 .IX Item "-linkoffline url file"
 336 Create hyperlinks to another documentation set which is also present
 337 on the local file system.
 338 .Sp
 339 This option works exactly like \fB\-link\fR, except that it accesses
 340 the local file system instead of the network for determining which
 341 classes are covered by the linked documentation set.
 342 .Sp
 343 When using \fB\-linkoffline\fR the remote documentation set is not
 344 accessed at all, which can significantly speed up generation time
 345 depending on your network connection.  The generated hyperlinks to the
 346 documentation set however refer to the remote set, not to the local
 347 one, so that you can distribute the documentation without any further
 348 dependencies.
 349 .Sp
 350 The \fB\-linkoffline\fR option can be specified multiple times.
 351 .IP "\fB\-noqualifier\fR \fIpkg:pkg:...\fR" 4
 352 .IX Item "-noqualifier pkg:pkg:..."
 353 Do not qualify names of classes in the given packages with their
 354 package name.
 355 .Sp
 356 By default, a class name is displayed unqualified only if the class is
 357 part of the source set or a linked documentation set, and qualified
 358 with the name of its containing package if it is not. You can use this
 359 option to force unqualified names for classes even if they are not
 360 part of the documentation set.
 361 .Sp
 362 For example, usually a reference to the String class is represented
 363 fully-qualified as \fBjava.lang.String\fR (unless you link to the
 364 appropriate documentation set using \fB\-link\fR) because it isn't
 365 part of the documentation set.  You can specify \fB\-noqualifier
 366 java.lang\fR to render the same references just as \fBString\fR.
 367 .Sp
 368 Note that for all unqualified class names, a tooltip is provided when
 369 you place your mouse pointer over it in the \s-1HTML\s0 documentation.
 370 .IP "\fB\-noqualifier\fR \fBall\fR" 4
 371 .IX Item "-noqualifier all"
 372 Omit package name qualifier from all class names.
 373 .Sp
 374 Specify this option to omit package name qualifiers altogether,
 375 .SS "Selecting which Information to Generate"
 376 .IX Subsection "Selecting which Information to Generate"
 377 .IP "\fB\-public\fR" 4
 378 .IX Item "-public"
 379 Only include public members of public classes in the output.  By
 380 default, protected class members are included as well.
 381 .IP "\fB\-protected\fR" 4
 382 .IX Item "-protected"
 383 Include public or protected members of public classes in the output.
 384 This is the default.
 385 .IP "\fB\-package\fR" 4
 386 .IX Item "-package"
 387 Include public, protected and package-private members of public and
 388 package-private classes.
 389 .IP "\fB\-private\fR" 4
 390 .IX Item "-private"
 391 Include all classes and class members regardless of their access
 392 level.
 393 .IP "\fB\-splitindex\fR" 4
 394 .IX Item "-splitindex"
 395 Generate one index page per letter instead of a single, monolithic
 396 index page.
 397 .Sp
 398 By default, the index created by the Standard Doclet contains all
 399 entries on a single page.  This is fine for small documentation sets,
 400 but for large sets you should specify this option.
 401 .IP "\fB\-nosince\fR" 4
 402 .IX Item "-nosince"
 403 Ignore \fB\f(CB@since\fB\fR tags in javadoc comments.
 404 .Sp
 405 By default, the generated output contains sections listing the version
 406 of your \s-1API\s0 since which the package, class or class member in question
 407 exists when this tag is encountered.  Specify this option to omit this
 408 information.
 409 .IP "\fB\-notree\fR" 4
 410 .IX Item "-notree"
 411 Do not generate any tree pages.
 412 .Sp
 413 By default, the generated output includes one inheritance tree per
 414 package, and \- if the documentation set consists of multiple packages
 415 \&\- a page with the full inheritance tree.  Specify this option to omit
 416 generation of these pages.
 417 .IP "\fB\-noindex\fR" 4
 418 .IX Item "-noindex"
 419 Do not output the alphabetical index.
 420 .Sp
 421 By default, gjdoc generates an alphabetical index of all program
 422 elements in the documentation set (packages, classes, inner classes,
 423 constructors, methods, and fields).  Specify this option to omit this
 424 information.
 425 .IP "\fB\-nohelp\fR" 4
 426 .IX Item "-nohelp"
 427 Do not generate the help page.
 428 .Sp
 429 This option is currently ignored as the Standard Doclet doesn't
 430 provide a help page.
 431 .IP "\fB\-nodeprecated\fR" 4
 432 .IX Item "-nodeprecated"
 433 Do not output inline information about deprecated packages, classes or
 434 class members.
 435 .Sp
 436 By default, the Standard Doclet adds a highlighted paragraph with
 437 deprecation information to the description of each deprecated program
 438 element.  Specify this option to omit this information.
 439 .IP "\fB\-nodeprecatedlist\fR" 4
 440 .IX Item "-nodeprecatedlist"
 441 Do not output the summary page for deprecated \s-1API\s0 elements.
 442 .Sp
 443 By default, the Standard Doclet generates a page listing all
 444 deprecated \s-1API\s0 elements along with a deprecation description which
 445 usually includes the reason for deprecation and possible
 446 alternatives.  Specify this option to omit this information.
 447 .IP "\fB\-nonavbar\fR" 4
 448 .IX Item "-nonavbar"
 449 Do not output the navigation bar, header, and footer.
 450 .Sp
 451 By default, each output page is equipped with a top navigation bar
 452 (which may include a user-specified header) and a bottom navigation
 453 bar (which may include a user-specified footer).  Specify this option
 454 to omit this decoration.
 455 .IP "\fB\-nocomment\fR" 4
 456 .IX Item "-nocomment"
 457 Omit all documentation text from the generated files and output only
 458 declarations and program element relationships.
 459 .Sp
 460 This option is here for compatibility with \fBjavadoc\fR.  If you
 461 plan on extracting information about your project via \fBgjdoc\fR,
 462 you should consider using a different Doclet for your purposes
 463 instead, for example XmlDoclet.  You could also use the Doclet \s-1API\s0
 464 directly by implementing a new Doclet.
 465 .IP "\fB\-linksource\fR" 4
 466 .IX Item "-linksource"
 467 Generate a page with syntax-highlighted source code for each class.
 468 By default, this page is not generated.
 469 .Sp
 470 The source code can be accessed by clicking on the button labelled
 471 \&\*(L"Source\*(R" in the navigation bar, or by clicking on the name of a
 472 constructor, field, method, or inner class in the detail section of a
 473 class documentation page.
 474 .IP "\fB\-use\fR" 4
 475 .IX Item "-use"
 476 Generate a page with cross-reference information. By default, this
 477 page is not generated.
 478 .Sp
 479 The cross-reference information can be accessed by clicking on the
 480 button labelled `Use' in the navigation bar.
 481 .Sp
 482 The `Use' page lists all classes/interfaces in the documentation set
 483 that extend/implement the class (type) in question; fields of the
 484 type; methods or constructors accepting a parameter of the type;
 485 methods returning the type; and methods or constructors throwing the
 486 type.
 487 .IP "\fB\-author\fR" 4
 488 .IX Item "-author"
 489 Include author information in the output.
 490 .Sp
 491 When specified, author information as specified using the
 492 \&\fB\f(CB@author\fB\fR tag in javadoc comments is incorporated into the
 493 output. By default, \fB\f(CB@author\fB\fR tags are ignored.
 494 .IP "\fB\-version\fR" 4
 495 .IX Item "-version"
 496 Include version information in the output.
 497 .Sp
 498 When specified, version information as specified using the
 499 \&\fB\f(CB@version\fB\fR tag in javadoc comments is incorporated into the
 500 output. By default, \fB\f(CB@version\fB\fR tags are ignored.
 501 .IP "\fB\-licensetext\fR" 4
 502 .IX Item "-licensetext"
 503 Assume that the first comment in each source file contains the license
 504 text, and add license information to the footer of each generated
 505 class page.
 506 .Sp
 507 This is an option specific to \fBgjdoc\fR and not compatible to
 508 Sun \fBjavadoc\fR.
 509 .Sp
 510 This option is intended for use with free and open source projects
 511 where source code is typically prefixed with a boilerplate license
 512 comment, when there are legal reasons for including the license in the
 513 documentation.
 514 .IP "\fB\-docfilessubdirs\fR" 4
 515 .IX Item "-docfilessubdirs"
 516 Recursively copy all files in the \fIdoc-files\fR sub-directory of each
 517 package directory.
 518 .Sp
 519 Usually, only the files in the \fIdoc-files\fR sub-directory are copied
 520 without descending recursively.
 521 .IP "\fB\-excludedocfilessubdir\fR \fIname\fR\fB:\fR\fIname\fR\fB:...\fR" 4
 522 .IX Item "-excludedocfilessubdir name:name:..."
 523 Do not copy some directories directly under the \fIdoc-files\fR
 524 sub-directories when descending recursively.
 525 .Sp
 526 The argument to this option should be a colon-separated list of
 527 directory names.
 528 .Sp
 529 This option only makes sense if \fB\-docfilessubdirs\fR is also
 530 specified.  In this case, any sub-directory located directly beneath a
 531 \&\fIdoc-files\fR directory is omitted if listed.
 532 .SS "Custom Documentation Tags"
 533 .IX Subsection "Custom Documentation Tags"
 534 .IP "\fB\-tagletpath\fR \fIpathlist\fR" 4
 535 .IX Item "-tagletpath pathlist"
 536 Search \fIpathlist\fR when loading subsequent Taglet classes specified
 537 using \fB\-taglet\fR.
 538 .Sp
 539 \&\fIpathlist\fR should be one or more paths to a directory or jar file,
 540 separated by your platform's path separator (usually \fB:\fR or
 541 \&\fB;\fR).
 542 .IP "\fB\-taglet\fR \fIclassname\fR" 4
 543 .IX Item "-taglet classname"
 544 Register a Taglet.
 545 .Sp
 546 \&\fIclassname\fR should be the fully-qualified name of a Java class
 547 implementing \fBcom.sun.tools.doclets.Taglet\fR.
 548 .Sp
 549 The Taglet classes will be loaded from the classpath specified using
 550 \&\fB\-tagletpath\fR, from the classpath specified using
 551 \&\fB\-classpath\fR and from the default classpath.
 552 .Sp
 553 See the documentation of \fBcom.sun.tools.doclets.Taglet\fR for
 554 further information.
 555 .Sp
 556 Note that for simple tags, there is also \fB\-tag\fR.
 557 .IP "\fB\-tag\fR \fItagspec\fR" 4
 558 .IX Item "-tag tagspec"
 559 Register a generic Taglet.
 560 .Sp
 561 The format of \fItagspec\fR must be \fB<tagname>:<flags>:\*(L"<taghead>\*(R"\fR.
 562 .Sp
 563 \&\fItagname\fR is the tag name to match, without the leading @ sign.
 564 .Sp
 565 \&\fIflags\fR is one or more of the following characters, where each
 566 character specifies a source code context in which the tag is to be
 567 recognized.
 568 .RS 4
 569 .IP "\fBa\fR" 4
 570 .IX Item "a"
 571 all contexts
 572 .IP "\fBc\fR" 4
 573 .IX Item "c"
 574 constructors
 575 .IP "\fBf\fR" 4
 576 .IX Item "f"
 577 fields
 578 .IP "\fBm\fR" 4
 579 .IX Item "m"
 580 methods
 581 .IP "\fBo\fR" 4
 582 .IX Item "o"
 583 overview
 584 .IP "\fBp\fR" 4
 585 .IX Item "p"
 586 packages
 587 .IP "\fBt\fR" 4
 588 .IX Item "t"
 589 types (classes, interfaces, exceptions, errors)
 590 .IP "\fBX\fR" 4
 591 .IX Item "X"
 592 special character which temporarily disables the
 593 Taglet altogether.
 594 .RE
 595 .RS 4
 596 .Sp
 597 \&\fItaghead\fR is the string to display in the header of the section
 598 devoted to the tag in question.
 599 .Sp
 600 For example, to define a tag matching \fB\f(CB@cvsid\fB\fR which is to be
 601 accepted in overview, package and type pages and which is labelled
 602 with the header \fB\s-1CVS\s0 \s-1ID\s0\fR, you would specify:
 603 .Sp
 604 .Vb 1
 605 \&        \-tag cvsid:tpo:"CVS ID"
 606 .Ve
 607 .Sp
 608 Let's say that a class javadoc comment contains
 609 .Sp
 610 .Vb 1
 611 \&        @cvsid $Id: cp\-tools.texinfo,v 1.9 2012\-03\-07 15:27:27 gnu_andrew Exp $
 612 .Ve
 613 .Sp
 614 Then the \s-1HTML\s0 output will contain something like
 615 .Sp
 616 .Vb 2
 617 \&        CVS ID:
 618 \&          $Id: cp\-tools.texinfo,v 1.9 2012\-03\-07 15:27:27 gnu_andrew Exp $
 619 .Ve
 620 .RE
 621 .SS "Running Other Doclets"
 622 .IX Subsection "Running Other Doclets"
 623 .IP "\fB\-docletpath\fR \fIpathlist\fR" 4
 624 .IX Item "-docletpath pathlist"
 625 Search \fIpathlist\fR when loading classes for the Doclet specified
 626 using \fB\-doclet\fR.
 627 .Sp
 628 \&\fIpathlist\fR should be one or more paths to a directory or jar file,
 629 separated by your platform's path separator (usually \fB:\fR or
 630 \&\fB;\fR).
 631 .IP "\fB\-doclet\fR \fIclassName\fR" 4
 632 .IX Item "-doclet className"
 633 Run the specified doclet instead of the standard HtmlDoclet.
 634 .Sp
 635 \&\fIclassName\fR should be the fully-qualified name of a class which
 636 has a public default constructor and contain a method with the
 637 following signature:
 638 .Sp
 639 .Vb 2
 640 \&           import com.sun.javadoc.RootDoc;
 641 \&           public static boolean start(RootDoc rootDoc)
 642 .Ve
 643 .Sp
 644 The Doclet classes will be loaded from the classpath specified using
 645 \&\fB\-docletpath\fR, from the classpath specified using
 646 \&\fB\-classpath\fR and from the default classpath.
 647 .Sp
 648 The \fBstart\fR method should process the information exposed by the
 649 Doclet \s-1API\s0 via \fBrootDoc\fR and return \fBtrue\fR on success,
 650 \&\fBfalse\fR on failure.
 651 .Sp
 652 If you are using a third-party doclet, refer to its documentation for
 653 further instructions.  Note that support for third-party doclets is
 654 experimental.  Please report any problems you encounter, or provide
 655 feedback when successfully running third-party applets.
 656 .Sp
 657 This option can be specified multiple times, in which case all doclets
 658 are executed with the same information tree exposed via the Doclet \s-1API\s0
 659 for each Doclet run.
 660 .SS "Adding Information to the Output"
 661 .IX Subsection "Adding Information to the Output"
 662 .IP "\fB\-windowtitle\fR \fItext\fR" 4
 663 .IX Item "-windowtitle text"
 664 Use \fItext\fR as the browser window title prefix.
 665 .Sp
 666 When specified, the browser window title for each page will be
 667 prefixed with \fItext\fR instead of the default string \fBGenerated
 668 \&\s-1API\s0 Documentation\fR.
 669 .Sp
 670 \&\fItext\fR should be plain text (it should not contain \s-1HTML\s0 tags).
 671 .IP "\fB\-doctitle\fR \fItext\fR" 4
 672 .IX Item "-doctitle text"
 673 Set the header text of the overview page to \fItext\fR.
 674 .Sp
 675 \&\fItext\fR should be a short plain text string.
 676 .Sp
 677 When generating documentation for a single package, specifying this
 678 option forces generation of the overview page.
 679 .IP "\fB\-header\fR \fIhtmltext\fR" 4
 680 .IX Item "-header htmltext"
 681 Add \fIhtmltext\fR to the right upper corner of every generated page.
 682 \&\fIhtmltext\fR is usually set to the name of the project being
 683 documented.
 684 .IP "\fB\-footer\fR \fIhtmltext\fR" 4
 685 .IX Item "-footer htmltext"
 686 Add \fIhtmltext\fR to the right bottom corner of every generated page.
 687 \&\fIhtmltext\fR is often set to the same value as for \fB\-header\fR.
 688 .IP "\fB\-bottom\fR \fIhtmltext\fR" 4
 689 .IX Item "-bottom htmltext"
 690 Add \fIhtmltext\fR to the very bottom of every generated page,
 691 spanning the whole width of the page.  When specified, \fIhtmltext\fR
 692 usually consists of a copyright notice and/or links to other project
 693 pages.
 694 .IP "\fB\-addstylesheet\fR \fIfile\fR" 4
 695 .IX Item "-addstylesheet file"
 696 Augment the default \s-1CSS\s0 style sheets with the user-specified
 697 stylesheet \fIfile\fR.
 698 .Sp
 699 The given stylesheet is simply loaded by each \s-1HTML\s0 page in addition to
 700 the default ones, as the last stylesheet.
 701 .Sp
 702 Note that the \s-1CSS\s0 cascading rules apply.  That is, your style
 703 properties will only be assigned if they have a higher cascading order
 704 than \fBgjdoc\fR's default style.  One simple way to make sure
 705 that this is the case is to declare your overrides \fB!important\fR.
 706 .Sp
 707 See <\fBhttp://www.w3.org/TR/REC\-CSS2/cascade.html#cascading\-order\fR>.
 708 .IP "\fB\-group\fR \fIheading\fR\fB \fR\fIpkgwildcard\fR\fB:\fR\fIpkgwildcard\fR\fB:...\fR" 4
 709 .IX Item "-group heading pkgwildcard:pkgwildcard:..."
 710 Arrange the given packages in a separate group on the overview page.
 711 .Sp
 712 The first argument should be a short plain text which is used as the
 713 title of the package group.  The second argument should be a
 714 colon-separated list of package wildcards.  The group will consist of
 715 all packages in the documentation set whose name matches any of the
 716 given wildcards.
 717 .Sp
 718 There is only one wildcard character, \fB*\fR, which matches both
 719 letters in package name components and the \fB.\fR separating package
 720 name components.  For example, \fBj*regex\fR would match package
 721 \&\fBjava.util.regex\fR.  A more useful example would be
 722 \&\fBjavax.swing*\fR to match \fBjavax.swing\fR and all of its
 723 sub-packages.
 724 .Sp
 725 This option can be given multiple times.
 726 .Sp
 727 \&\s-1FIXME:\s0 Information about group nesting here.
 728 .Sp
 729 .Vb 5
 730 \&        gjdoc \-group "Core Classes" \*(Aqjava*\*(Aq \e
 731 \&              \-group "Swing" \*(Aqjavax.swing*\*(Aq \e
 732 \&              \-group "XML APIs" \*(Aqjavax.xml*\*(Aq \e
 733 \&              \-group "Other Extensions" javax* \e
 734 \&              ...
 735 .Ve
 736 .IP "\fB\-overview\fR \fIfile\fR" 4
 737 .IX Item "-overview file"
 738 Add the \s-1XHTML\s0 body fragment from \fIfile\fR to the overview page.
 739 .Sp
 740 \&\fIfile\fR should contain an \s-1XHTML\s0 fragment with the \s-1HTML\s0 \fBbody\fR
 741 tag as the root node.
 742 .Sp
 743 This option can be used to supply a description of the documentation
 744 set as a whole.
 745 .Sp
 746 When specified, the first sentence of the fragment will be put above
 747 the tables listing the documented packages, along with a link to the
 748 full copy of the fragment which is put below the tables.
 749 .Sp
 750 When generating documentation for a single package, specifying this
 751 option forces generation of the overview page.
 752 .IP "\fB\-stylesheetfile\fR \fIfile\fR" 4
 753 .IX Item "-stylesheetfile file"
 754 Use the \s-1CSS\s0 stylesheet in \fIfile\fR instead of the default \s-1CSS\s0
 755 stylesheets.
 756 .Sp
 757 If you only want to override parts of the default stylesheets, use
 758 \&\fB\-addstylesheet\fR instead.
 759 .IP "\fB\-title\fR \fItext\fR" 4
 760 .IX Item "-title text"
 761 \&\fIDeprecated.\fR Use \fB\-doctitle\fR \fItext\fR instead.
 762 .IP "\fB\-helpfile\fR \fIfile\fR" 4
 763 .IX Item "-helpfile file"
 764 This option is currently ignored.
 765 .Sp
 766 When implemented, it will use the \s-1XHTML\s0 fragment in \fIfile\fR for the
 767 help page contents instead of the default help text.
 768 .SS "Controlling the Output."
 769 .IX Subsection "Controlling the Output."
 770 .IP "\fB\-d\fR \fIdirectory\fR" 4
 771 .IX Item "-d directory"
 772 Place all output files into \fIdirectory\fR (and
 773 sub-directories). \fIdirectory\fR will be created if it does not
 774 exist, including all non-existing parent directories and all required
 775 sub-directories.
 776 .Sp
 777 If not specified, output will be placed into the current directory.
 778 .IP "\fB\-locale\fR \fIname\fR" 4
 779 .IX Item "-locale name"
 780 Use locale \fIname\fR instead of the default locale for all purposes.
 781 .Sp
 782 \&\fIname\fR should be a locale specifier in the form \fBll_CC[_VAR]\fR
 783 where \fBll\fR is a lowercase two-letter \s-1ISO\-639\s0 language code,
 784 \&\fB\s-1CC\s0\fR is an optional uppercase two-letter \s-1ISO\-3166\s0 country code,
 785 and \fB\s-1VAR\s0\fR is an optional variant code.  For example, \fBen\fR
 786 specifies English, \fBen_US\fR specifies \s-1US\s0 English, and
 787 \&\fBen_US_WIN\fR specifies a deviant variant of the \s-1US\s0 English locale.
 788 .Sp
 789 Note that the semantics of this option correspond exactly to those of
 790 the constructors of class \fBjava.util.Locale\fR.
 791 .Sp
 792 This option currently only determines which Collator is being used for
 793 sorting output elements.  This means that the locale will only have an
 794 effect when you are using non-ASCII characters in identifiers.
 795 .IP "\fB\-charset\fR \fIcharset\fR" 4
 796 .IX Item "-charset charset"
 797 \&\fIDeprecated.\fR Override the specified encoding in output \s-1XHTML\s0
 798 files with the one given by \fBcharset\fR.
 799 .Sp
 800 If this option is not given, the encoding specification in output
 801 \&\s-1XHTML\s0 is chosen to match the encoding used when writing the file (the
 802 encoding given with \fB\-docencoding\fR, or your platform's default
 803 encoding).
 804 .Sp
 805 The semantics for \fIcharset\fR are specified here:
 806 <\fBhttp://www.w3.org/TR/2000/REC\-xml\-20001006#NT\-EncName\fR>.  For
 807 all practical purposes, they are identical to those of the other
 808 options accepting charset parameters.
 809 .Sp
 810 This option is here for compatibility with \fBjavadoc\fR and
 811 should be avoided.
 812 .IP "\fB\-docencoding\fR \fIcharset\fR" 4
 813 .IX Item "-docencoding charset"
 814 Use the given charset encoding when writing output files instead of
 815 your platform's default encoding.
 816 .Sp
 817 Examples for \fIcharset\fR are \fBUS-ASCII\fR, \fB\s-1ISO\-8859\-1\s0\fR or
 818 \&\fB\s-1UTF\-8\s0\fR.
 819 .Sp
 820 The semantics of this option correspond exactly to those of the
 821 constructors of class \fBjava.util.Locale\fR.
 822 .IP "\fB\-validhtml\fR" 4
 823 .IX Item "-validhtml"
 824 Force generation of valid \s-1XHTML\s0 code.  This breaks compatibility to
 825 the traditional Javadoc tool to some extent.
 826 .Sp
 827 If this option is specified, anchor names will be mangled so that they
 828 are valid according to the \s-1XHTML\s0 1.1 specification.  However, a
 829 documentation set generated with this option cannot be linked to
 830 properly using the traditional Javadoc tool.  It can be linked to just
 831 fine using Gjdoc, though.
 832 .Sp
 833 Without this option, anchor names for executable class members use the
 834 traditional format, for example: \*(L"foo(String,int[])\*(R".  This is
 835 compatible to the traditional Javadoc tool, but according to both the
 836 \&\s-1HTML\s0 4.0 and \s-1XHTML\s0 1.0 and 1.1 specifications, this format includes
 837 illegal characters.  Parentheses, square brackets, and the comma are
 838 not allowed in anchor names.
 839 .IP "\fB\-baseurl\fR \fIurl\fR" 4
 840 .IX Item "-baseurl url"
 841 Hardwire a page \s-1URL\s0 relative to \fIurl\fR into each generated page.
 842 .Sp
 843 If you are generating documentation which will exclusively be
 844 available at a certain \s-1URL\s0, you should use this option to specify this
 845 \&\s-1URL\s0.
 846 .Sp
 847 This can help avoid certain redirect attacks used by spammers, and it
 848 can be helpful for certain web clients.
 849 .SS "Verbosity Options"
 850 .IX Subsection "Verbosity Options"
 851 .IP "\fB\-quiet\fR" 4
 852 .IX Item "-quiet"
 853 Suppress all output except for warnings and error messages.
 854 .IP "\fB\-verbose\fR" 4
 855 .IX Item "-verbose"
 856 Be very verbose about what \fBgjdoc\fR is doing.
 857 .Sp
 858 This option is currently ignored.
 859 .SS "Virtual Machine Options"
 860 .IX Subsection "Virtual Machine Options"
 861 Sun's \fBjavadoc\fR tool seems to be based on \fBjavac\fR and
 862 as such it seems to operate on the \s-1VM\s0 level.  \fBgjdoc\fR, in
 863 contrast, is a pure Java application.
 864 .PP
 865 Therefore, \fBgjdoc\fR can only fake, or simulate, the following
 866 VM-level options.
 867 .IP "\fB\-classpath\fR \fIpathlist\fR" 4
 868 .IX Item "-classpath pathlist"
 869 Set the Virtual Machine \fBclasspath\fR to \fIpathlist\fR.
 870 .Sp
 871 In most cases you should use \fB\-docletpath\fR or
 872 \&\fB\-tagletpath\fR instead of this option.
 873 .Sp
 874 \&\fIpathlist\fR should be one or more paths to a directory or jar file,
 875 separated by your platform's path separator (usually \fB:\fR or
 876 \&\fB;\fR).
 877 .Sp
 878 If this option is not intercepted at the wrapper level,
 879 \&\fBgjdoc\fR currently fakes it by calling
 880 \&\fBSystem.setProperty(\*(L"java.class.path\*(R",\fR \fIpathlist\fR\fB);\fR and
 881 outputs a warning.
 882 .IP "\fB\-bootclasspath\fR \fIpathlist\fR" 4
 883 .IX Item "-bootclasspath pathlist"
 884 Set the Virtual Machine \fBbootclasspath\fR to \fIpathlist\fR.
 885 .Sp
 886 If this option is not intercepted at the wrapper level,
 887 \&\fBgjdoc\fR outputs a warning.
 888 .IP "\fB\-J\fR\fIvmopt\fR" 4
 889 .IX Item "-Jvmopt"
 890 Pass an arbitrary parameter to the Virtual Machine \fBgjdoc\fR
 891 runs on.
 892 .Sp
 893 If this option is not intercepted at the wrapper level,
 894 \&\fBgjdoc\fR tries to emulate the option and outputs a warning.
 895 .Sp
 896 Currently, only the \s-1VM\s0 option \fB\-D\fR for setting system
 897 properties is emulated.
 898 .SH "BUGS"
 899 .IX Header "BUGS"
 900 Please report bugs to <\fBhttp://savannah.gnu.org/bugs/?group=classpath\fR>.
 901 .SH "SEE ALSO"
 902 .IX Header "SEE ALSO"
 903 Info entry for \fIgjdoc\fR.
 904 .SH "AUTHOR"
 905 .IX Header "AUTHOR"
 906 Julian Scheid