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