XDC - The XML Documentation Generator

Generates HTML pages of API documentation from XML source files.

Reference Guide

Synopsis

xdc [ options ] [ packagenames ] [ sourcefilenames ] [ @argfiles ]

Arguments can be in any order. See processing of Source Files for details on how the XDC tool determines which files to process.

options
Command-line options, as specified in this document.
packagenames
A series of names of packages, separated by spaces. You must separately specify each package you want to document. Wildcards are not allowed; use -subpackages for recursion. The XDC tool uses -sourcepath to look for these package names.
sourcefilenames
A series of source file names, separated by spaces, each of which may begin with a path relative to one of the source directories specified by the -sourcepath option. Both the path and the file name may contain wildcard:

  • A question mark ("?") represents any one character in the name of a directory or file.

  • An asterisk ("*") represents any sequence of characters in the name of one directory or file.

  • A double asterisk ("**") represents any sequence of names of directories contained in each other.

The XDC tool will process every file whose name ends with ".xml" or with one of the file extensions specified by the -extensions option. You can also mix packagenames and sourcefilenames.
@argfiles
One or more files that contain a list of XDC options, packagenames and sourcefilenames in any order. -J options are not allowed in these files (but wildcards such as "?", "*" and "**" are).

Description

The XDC tool parses the declarations and documentation comments in a set of XML source files and produces a corresponding set of HTML pages describing (by default) the root elements and their immediate child elements.

XDC aims to be for XML files what Javadoc is for Java. In order for users who are familiar with Javadoc to become easily accustomed with XDC, the XDC comment syntax strongly resembles that of the Javadoc documentation comments; moreover, many of the options and tags available for Javadoc are present with the same syntax and semantics in XDC (not to mention the similarity of this documentation with the corresponding Javadoc document).

You can run the XDC tool on entire packages, individual source files, or both. When documenting entire packages, you can either use -subpackages for traversing recursively down from a top-level directory, or pass in an explicit list of package names. When documenting individual source files, you pass in a list of source filenames. Examples are given at the end of this document. How XDC processes source files is covered next.

Processing of Source Files

If you run XDC by explicitly passing in individual source filenames, you an determine exactly which files are processed. However, that is not how most developers want to work, as it is simpler to pass in package names. The XDC tool can be run three ways without explicitly specifying the source filenames. You can (1) pass in package names, (2) use -subpackages, and (3) use wildcards ("?", "*", "**") with source filenames. Since XML structures may be contained in files with any entension, the XDC tool processes all files specified by the arguments of the XDC invocation.

Processing of links - During a run, the XDC tool automatically adds cross-reference links to package, file and elment names that are being documented as part of that run. Links appear in several places:

Other processing details - The XDC tool produces one complete document each time it is run; it cannot do incremental builds - that is, it cannot modify or directly incorporate results from previous XDC runs.

As implemented, XDC relies on an XSLT processor to do its job. Both the information about the structure of the processed XML element and its subelements and the information provided in the XDC comments is extracted and processed using (almost) pure XSLT 1.0 compliant stylesheets.

As a consequence, an XML file that is processed by the XDC tool is required to be well-formed XML (although it must not necessarily be valid).

Dialects

Different XML dialects are typically characterized by their (explicit or "implicit") DTD. They normally differ significantly in the sets of subelements and attributes that are of interest to the developer using the interface the source file provides. Consequently, each XML dialect defines different handling rules for the documented elements as well as for the XDC comments themselves (e.g. the xsl dialect recognizes a @param tag which other dialects do not understand).

Source Files

The XDC tool will generate output originating from four different types of "source" files: XML source files, package comment files, overview comment files, and miscellaneous unprocessed files.

XML source files

Each XML root element contained in an XML file and its subelements can have their own documentation comments. For more details about these XDC comments, see Documentation Comments.

Package Comment Files

Each package can have its own documentation comment, contained in its own "source" file, that the XDC tool will merge into the package summary page that it generates. You typically include in this comment any documentation that applies to the entire package.

To create a package comment file, you must name it xdc-package.html and place it in the package directory in the source tree along with the documented XML files. The XDC tool will automatically look for this filename in this location. Notice that the filename is identical for all packages.

The content of the package comment file is one big documentation comment, written in HTML, like all other comments. When writing the comment, you should make the first sentence a summary about the package, and not put a title or any other text between <body> and the first sentence. You can include XDC tags; as with any documentation comment, all tags except {@link} must appear after the main description. If you add a @see tag in a package comment file, it must have a fully-qualified name.

When the XDC tool runs, it will automatically look for this file; if found, the XDC tool does the following:

Overview Comment File

Each application or set of packages that you are documenting can have its own overview documentation comment, kept in its own "source" file, that the XDC tool will merge into the overview page that it generates. You typically include in this comment any documentation that applies to the entire application or set of packages.

To create an overview comment file, you can name the file anything you want, typically xdc-overview.html and place it anywhere, typically at the top level of the source tree. Notice you can have multiple overview comment files for the same set of source files, in case you want to run XDC multiple times on different sets of packages. For example, if the source files for the net.sf.xdc.xsl package are contained in the C:\user\src\net\sf\xdc\xsl directory, you could create an overview comment file at C:\user\src\xdc-overview.html.

The content of the overview comment file is one big documentation comment, written in HTML, like the package comment file described previously. See that description for details. To re-iterate, when writing the comment, you should make the first sentence a summary about the application or set of packages, and not put a title or any other text between <body> and the first sentence. You can include XDC tags; as with any documentation comment, all tags except in-line tags, such as {@link}, must appear after the main description. If you add a @see tag, it must have a fully-qualified name.

When you run the XDC tool, you specify the overview comment file name with the -overview option. The file is then processed similar to that of a package comment file.

Miscellaneous Unprocessed Files

You can also include in your source any miscellaneous files that you want the XDC tool to copy to the destination directory. These typically include graphic files, example XML source files, and self-standing HTML files whose content would overwhelm the documentation comment of a normal Java source file.

To include unprocessed files, put them in a directory called xdc-doc-files which can be a subdirectory of any package directory that contains source files. You can have more than one such subdirectory for each package (if your sources are drawn from more than one source directory). You might include any type of file. For example, if you want to include the diagram diagram.gif illustrating the business logic in an XSLT stylesheet my/stylesheet.xsl, you place that file in the /home/user/src/my/xdc-doc-files/ directory.

All links to these unprocessed files must be hard-coded, because the XDC tool does not look at the files – it simply copies the directory and all its contents to the destination. For example, the link in the stylesheet.xsl doc comment might look like: 


      <!---
          - The business logic is illustrated by the following image:
          - <img src="xdc-doc-files/diagram.gif" alt="Business logic"/>
         -->

Generated Files

By default, XDC uses XSLT transformations that generate HTML-formatted documentation. In this process the following kinds of files are generated (where each HTML "page" corresponds to a separate file). Note that XDC generates files with two types of names: those named after XML elements, and those that are not (such as package-summary.html).

Basic Content Pages Support Files HTML Frames

The XDC tool will generate either two or three frames, as shown by the figure below. It creates the minimum necessary number of frames by omitting the list of packages if there is only one package (or no packages). That is, when you pass a single package name or source files belonging to a single package as arguments into the XDC command, it will create only one frame (C) in the left-hand column – the list of classes. When you pass into XDC two or more package names, it creates a third frame (P) listing all packages, as well as an overview page (Detail). This overview page has the filename overview-summary.html. Thus, this file is created only if you pass in two or more package names. You can bypass frames by clicking on the "No Frames" link or entering at overview-summary.html.

If you are unfamiliar with HTML frames, you should be aware that frames can have focus for printing and scrolling. To give a frame focus, click on it. Then on many browsers the arrow keys and page keys will scroll that frame, and the print menu command will print it. 

              ------------                  ------------
              |C| Detail |                  |P| Detail |
              | |        |                  | |        |
              | |        |                  |-|        |
              | |        |                  |C|        |
              | |        |                  | |        |
              | |        |                  | |        |
              ------------                  ------------
               xdc *.xml                    xdc pkg1 pkg2
Load one of the following two files as the starting page depending on whether you want HTML frames or not:

Generated File Structure

The generated class and interface files are organized in the same directory hierarchy that source files and class files are organized. This structure is one directory per subpackage.

For example, the document generated for the file base-page.xsl in the package net.sf.xdc.xsl would be located at net/sf/xdc/xsl/base-page.xsl.html. The file structure for the net.sf.xdc.xsl package follows, given that the destination directory is named xdcdocs. All files that contain the word "frame" appear in the upper-left or lower-left frames, as noted. All other HTML files appear in the right-hand frame.

NOTE - Directories are shown in bold. The asterisks (*) indicate the files and directories that are omitted when XDC produces a frameset consisting of two (rather than three) frames. The xdc-doc-files directory will not be created in the destination unless it exists in the source tree.
xdcdocs   Top directory
   allclasses-frame.html   Lists all files for all packages, used in lower-left frame
   allclasses-noframe.html   Lists all files for all packages, used outside of any frameset
   help-doc.html   Lists user help for how these pages are organized
   index.html   Initial page that sets up HTML frames
 * overview-frame.html   Lists all packages, used in upper-left frame
 * overview-summary.html   Lists all packages with first sentence summaries
   stylesheet.css   HTML style sheet for defining fonts, colors and positions
   net   Package directory
      sf   Subackage directory
         xdc   Subackage directory
            xsl   Subackage directory
               package-frame.html   Lists classes in this package, used in lower left-hand frame (for three-part framesets) or outside of frameset (in case of two-part framesets)
               package-summary.html   Lists classes with first sentence summaries for this package
               base-page.xsl.html   Page for the base-page.xsl file
               other .html files   Pages for the other source files
               xdc-doc-files   Directory holding image and other files
   src-html   Source code directory
      net   Package directory
         sf   Subackage directory
            xdc   Subackage directory
               xsl   Subackage directory
                  base-page.xsl.html   Page for the base-page.xsl source code
                  other .html files   Pages for the source code of the other source files

Documentation Comments

Commenting the Source Code

You can include XML documentation comments ("XDC comments") in the source code, ahead of declarations for any top-level element and immediate subelement. You can also create XDC comments for each package and another one for the overview, though their syntax is slightly different. An XDC comment consists of the characters between the characters <!--- that begin the comment and the characters --> that end it. Leading dashes ('-') are allowed on each line and are described further below. The text in a comment can continue onto multiple lines. 


<!---
    - This is the typical format of a simple documentation comment
    - that spans two lines.
   -->
To save space you can put a comment on one line: 

<!--- This comment takes up only one line. -->

Placement of comments - XDC comments are recognized only when placed immediately before XML elements (optionally separated by processing instructions and/or non-XDC comments). XDC comments placed in the body of an XML element method are ignored (unless they are used for documenting a subelement). Only one XDC comment per declaration statement is recognized by the XDC tool.

An XDC comment is composed of a main description followed by a tag section - The main description begins after the starting delimiter <!--- and continues until the tag section. The tag section starts with the first block tag, which is defined by the first @ character that begins a line (ignoring leading dashes, white space, and leading delimiter <!---). It is possible to have a comment with only a tag section and no main description. The main description cannot continue after the tag section begins. The argument to a tag can span multiple lines. There can be any number of tags – some types of tags can be repeated while others cannot. For example, this @version starts the tag section: 


      <!---
          - This is the main description.
          - @version 1.0
         -->

Block tags and in-line tags - A tag is a special keyword within an XDC comment that the XDC tool can process. There are two kinds of tags: block tags, which appear as @tag (also known as "standalone tags"), and in-line tags, which appear within curly braces, as {@tag}. To be interpreted, a block tag must appear at the beginning of a line, ignoring leading dashes, white space, and separator (<!---). This means you can use the @ character elsewhere in the text and it will not be interpreted as the start of a tag. If you want to start a line with the @ character and not have it be interpreted, use the HTML entity &#064;. Each block tag has associated text, which includes any text following the tag up to, but not including, either the next tag, or the end of the XDC comment. This associated text can span multiple lines. An in-line tag is allowed and interpreted anywhere that text is allowed. The following example contains the in-line tag {@link}. 


      <!---
          - For detailed description, see {@link #entry~name~entry1 first entry}.
         -->

Comments are written in HTML - The text must be written in HTML, in that they should use HTML entities and can use HTML tags. You can use whichever version of HTML your browser supports.

For example, entities for the less-than (<) and greater-than (>) symbols should be written &lt; and &gt;. Likewise, the ampersand (&) should be written &amp;. The bold HTML tag <b> is shown in the following example.

Here is a doc comment: 


      <!---
          - This is an <b>XDC</b> comment.
         -->

Leading dashes - When XDC parses a doc comment, leading dash (-) characters on each line are discarded; blanks and tabs preceding the initial dash characters are also discarded. If you omit the leading dash on a line, the leading white space is no longer removed. This enables you to paste code examples directly into an XDC comment inside a <pre> tag, and its indentation will be honored. Spaces are generally interpreted by browsers more uniformly than tabs. Indentation is relative to the left margin (rather than the separator <!--- or <pre> tag).

First sentence - The first sentence of each XDC comment should be a summary sentence, containing a concise but complete description of the declared entity. This sentence ends at the first period that is followed by a blank, tab, line terminator or an HTML element, or at the first block tag. The XDC tool copies this first sentence to the member summary at the top of the HTML page.

Use header tags carefully - When writing documentation comments for XML subelements, it's best not to use HTML heading tags such as <h1> and <h2>, because the XDC tool creates an entire structured document and these structural tags might interfere with the formatting of the generated document. However, it is fine to use these headings in top-level element and package comments to provide your own structure.

XDC Tags

The XDC tool parses special tags when they are embedded within a XML doc comment. These XDC tags enable you to autogenerate a complete, well-formatted API from your source code. The tags start with an "at" sign (@) and are case-sensitive – they must be typed with the uppercase and lowercase letters as shown. A tag must start at the beginning of a line (after any leading spaces and an optional dash) or it is treated as normal text. By convention, tags with the same name are grouped together (even though this is not a necessity). For example, you should put all @see tags together.

Tags come in two types:

The current tags for the generic XML dialect are:

@author
{@code}
{@docRoot}
{@link}
{@linkplain}
{@literal}
@see
@since
@version

The XSLT dialect recognizes one additional tag:

@param

@author  name-text 

Adds an "Author" entry with the specified name-text to the generated docs when the -author option is used. An XDC comment may contain multiple @author tags. You can specify one name per @author tag or multiple names per tag. In the former case, the XDC tool inserts a comma (,) and space between names. In the latter case, the entire text is simply copied to the generated document without being parsed. Therefore, you can use multiple names per line if you want a localized name separator other than comma.


{@code  text }  

Equivalent to <code>{@literal text}<code>.

Displays text in code font without interpreting the text as HTML markup or nested XDC tags. This enables you to use regular angle brackets (< and >) instead of the HTML entities (&lt; and &gt;) in XDC comments, such as in XML elements (<xsl:template>), inequalities (3 < 4), or arrows (<-). For example, the XDC comment text: 

  {@code a<b>c}
displays in the generated HTML page unchanged, as: 
  a<b>c
The noteworthy point is that the <b> is not interpreted as bold and is in code font.

If you want the same functionality without the code font, use {@literal} .


{@docRoot}  

Represents the relative path to the generated document's (destination) root directory from any generated page. It is useful when you want to include a file, such as a copyright page or company logo, that you want to reference from all generated pages. Linking to the copyright page from the bottom of each page is common.

This {@docRoot} tag can be used both on the command line and in an XDC comment: This tag is valid in all doc comments, including the text portion of any tag (such as @return, @param and @deprecated).

  1. On the command line, where the header/footer/bottom are defined: 

    
  javadoc -bottom '<a href="{@docRoot}/copyright.html">Copyright</a>'
    NOTE - When using {@docRoot} this way in a make file, some makefile programs require special escaping for the brace {} characters. For example, the Inprise MAKE version 52 running on Windows requires double braces: {{@docRoot}}. It also requires double (rather than single) quotes to enclose arguments to options such as -bottom (with the quotes around the href argument omitted). Care should also be taken if the option is used in an Apache Ant call that no dollar sign ($) immediately precedes the opening brace character.

  2. In an XDC comment: 

    
  <!---
      - See the <a href="{@docRoot}/copyright.html">Copyright</a>.
     -->

The reason this tag is needed is because the generated docs are in hierarchical directories, as deep as the number of subpackages. This expression: 

  <a href="{@docRoot}/copyright.html">
would resolve to: 

  <a href="../../../copyright.html">      for net/sf/xdc/test.xml
and 

  <a href="../../../../copyright.html">   for net/sf/xdc/xsl/util.xml


{@link  reference label }  

Inserts an in-line link with visible text label that points to the documentation at the location specified by reference. This tag is valid in all XDC comments, including the text portion of any block tag.

The reference can be of one of two formats:

package/file#element

The package and file constituents denote the package resp. the file containing the referenced element; the element part is composed of the name of the referenced element followed by the names and values of all its attributes, each separated by a tilde (~), with the attribute names sorted alphabetically.

package/file##pattern

The package and file constituents denote the package resp. the file containing the referenced element; the pattern part is an XPath expression specifying the referenced element within the source file.

This tag is very simliar to @see – both require the same references and accept exactly the same syntax for package/file#element and label. The main difference is that {@link} generates an in-line link rather than placing the link in the "See Also" section. Also, the {@link} tag begins and ends with curly braces to separate it from the rest of the in-line text. If you need to use "}" inside the label, use the HTML entity notation &#125;

There is no limit to the number of {@link} tags allowed in a sentence. You can use this tag in the main description part of any XDC comment or in the text portion of any block tag.

For example, here is a comment that refers to the XSLT template with match="/" and mode="util.getPath" in the stylesheet file util.xsl in the same package as the refering file: 

  Use the template with {@link util.xsl#xsl:template~match~/~mode~util.getPath mode="util.getPath"}.
From this, the XDC tool would generate the following HTML: 
  Use the template with <a href="util.xsl.html#xsl:template~match~/~mode~util.getPath">mode="util.getPath"</a>.
Which appears on the web page as:

Use the template with mode="util.getPath" .


{@linkplain  reference label }  

Identical to {@link}, except the link's label is displayed in plain text than code font. Useful when the label is plain text. Example: 

  Use the {@linkplain util.xsl#xsl:template~match~/~mode~util.getPath previous template}.
This would display as:

Use the previous template.


{@literal  text }  

Displays text without interpreting the text as HTML markup or nested XDC tags. This enables you to use regular angle brackets (< and >) instead of the HTML entities (&lt; and &gt;) in XDC comments, such as in XML elements (<xsl:template>), inequalities (3 < 4), or arrows (<-). For example, the XDC comment text: 

  {@literal a<b>c}
displays in the generated HTML page unchanged, as:
a<b>c
The noteworthy point is that the <b> is not interpreted as bold (and it is not in code font).

If you want the same functionality but with the text in code font, use {@code}.


@param  parameter-name description 

This tag is only recognized by the XSLT dialect.

The @param tag adds a parameter with the specified parameter-name followed by the specified description to the "Parameters" section. When writing the XDC comment, you may continue the description onto multiple lines. This tag is valid only in an XDC comment for an XSLT stylesheet or template.


@see  reference 

Adds a "See Also" heading with a link or text entry that points to reference. An XDC comment may contain any number of @see tags, which are all grouped under the same heading. The @see tag has three variations; the third form below is the most common. This tag is valid in any XDC comment. For inserting an in-line link within a sentence of the main description in an XDC comment, see {@link} .

@see  "string" 

Adds a text entry for string. No link is generated. The string is a book or other reference to information not available by URL. The XDC tool distinguishes this from the other cases by looking for a double-quote (") as the first character. For example: 

  @see "XDC for dummies"
This generates text such as:
See Also:
    "XDC for dummies"


@see  <a href="URL#anchor">label</a> 

Adds a link as defined by URL#anchor. The URL#anchor is a relative or absolute URL. The XDC tool distinguishes this from other cases by looking for a less-than symbol (<) as the first character. For example: 

  @see <a href="http://xdc.sf.net">XDC home page</a>
This generates text such as:
See Also:
     XDC home page


@see  package/file#element label 

Adds a link, with visible text label, that points to the documentation for the XML element specified by the name package/file#element. The label is optional; if omitted, the name appears instead as the visible text. Use the label when you want the visible text to be different from the specified name.

  • package/file#element is any valid XML element name that is referenced – a package, file or element name – except that the character ahead of the element name should be a hash character (#). The file represents any documented source XML file. The member represents any top-level element or subelement. If this name is in the documented files, the XDC tool will automatically create a link to it. This argument is described at greater length below.

  • label is optional text that is visible as the link's label. The label can contain whitespace. If label is omitted, then package.file#element will appear.

  • A space is the delimiter between package/file#element and label.

  • The package.file#element as well as the complete label must be placed on the same line!

  • The constituents of the name of the referenced package (if included) must be separated with a forward slash (/). For files contained in the "unnamed" package, a single slash must be used for the package name.

  • The name of the file must be the file name of the documented source file, not that of the generated XDC page file.

  • The name of the referenced element is composed of the element name followed by the names and the values of all attributes, each separated by a tilde (~), with the attribute names sorted alphabetically.

Example

In this example, a @see tag (in the file net/sf/xdc/xsl/xsl.xsl) refers to the XSLT template with mode="comments.displayXdcTagLabel". The tag includes both the name "base-page.xsl#xsl:template~match~/~mode~comments.displayXdcTagLabel" and the label "The defining template". 


  <!---
      - @see base-page.xsl#xsl:template~match~/~mode~comments.displayXdcTagLabel The defining template
     -->
From this XDC tag, the XDC tool will produce something like this: 

  <dl class="memberBodyCommentDetail">
    <dt>
      <b>See also:</b>
    <dd>
      <a href="base-page.xsl.html#xsl:template~match~/~mode~comments.displayXdcTagLabel">The defining template</a>
  </dl>
Which looks something like this in a browser, where the label is the visible link text:
See Also:
     The defining template

Specifying a name

This package.class#member name can be either fully-qualified, such as net/sf/xdc/xsl/base-page.xsl#xsl:template~match~/~mode~comments.displayXdcTagLabel or not, such as base-page.xsl#xsl:template~match~/~mode~comments.displayXdcTagLabel or #xsl:template~match~/~mode~comments.displayXdcTagLabel.

Of course the advantage of providing shorter, "partially-qualified" names is that they are shorter to type and there is less clutter in the source code. The following forms of the name are possible:

Referencing an element in the current file

@see #element~key1~value1~...

Referencing a file in the current package

@see file#element~key1~value1~...

Referencing a file in any package

@see package/file#element~key1~value1~...


@see  package/file##pattern label 

Adds a link, with visible text label, that points to the documentation for the XML element specified by the name package/file#element. The lebel is optional (but recommended); if omitted, the name appears instead as the visible text. Use the label when you want the visible text to be different from the specified name.

  • package/file##pattern is a reference to an XML element contained in the file referenced by package/file. The pattern is an XPath expression representing any top-level element or subelement. If this element is in the documented files, the XDC tool will automatically create a link to it. This argument is described at greater length below.

  • In all other aspects, links of this style behave like the ones in the package/file#element style.



@since  since-text 

Adds a "Since" heading with the specified since-text to the generated documentation. The text has no special internal structure. This tag is valid in XDC comments for top-level elements as well as subelements. This tag means that this change or feature has existed since the software release specified by the since-text. For example: 

  @since 0.5
Multiple @since tags are allowed and are treated like multiple @author tags. You could use multiple tags if the prgram element is used by more than one API.


@version  version-text 

Adds a "Version" subheading with the specified version-text to the generated docs when the -version option is used. This tag is intended to hold the current version number of the software that this code is part of (as opposed to @since , which holds the version number where this code was introduced). The version-text has no special internal structure. An XDC comment may contain multiple @version tags. If it makes sense, you can specify one version number per @version tag or multiple version numbers per tag. In the former case, the XDC tool inserts a comma (,) and space between names. In the latter case, the entire text is simply copied to the generated document without being parsed. Therefore, you can use multiple names per line if you want a localized name separator other than comma.


Options

The XDC tool provides a set of command-line options which are described below under the sub-heading XDC Options. All option names are case-insensitive, though their arguments can be case-sensitive.

The options are:

-author
-bottom
-charset
-d
 -defaultexcludes
 -dialect
 -dialects
 -dialectmapping
 -docencoding
 -doctitle
 -encoding
 		-exclude
 -extensions
 -footer
-forceoptions
 -header
-help
 -helpfile
 -J
 -linksource
 -locale
 -nohelp
-nonavbar
-nosince
-notimestamp
-overview
 -reportmissing
 -sourcepath
 -stylesheetfile
 -subpackages
 -version
-windowtitle

The options displayed in italic font may also be specified on a per-file basis in the source file itself by placing them in the form of key-value pairs (with the values for the zero-argument options being "1") in a processing instruction named "xdc": 


  <?xdc header="Generic XML structure"
        version="1"
        author="1"?>

XDC Options

-overview path/filename 

Specifies that XDC should retrieve the text for the overview documentation from the "source" file specified by path/filename and place it on the Overview page (overview-summary.html). The path/filename is relative to the -sourcepath .

While you can use any name you want for filename and place it anywhere you want for path, a typical thing to do is to name it xdc-overview.html and place it in the source tree at the directory that contains the topmost package directories. In this location, no path is needed when documenting packages, since -sourcepath will point to this file. For example, if the source tree for the net.sf.xdc.xsl package is C:\user\src\net\sf\xdc\xsl\, then you could place the overview file at C:\user\src\overview.html.

For information about the file specified by path/filename, see overview comment file.

Note that the overview page is created only if you pass into XDC two or more package names. For further explanation, see HTML Frames.

The title on the overview page is set by -doctitle .


-help 

Displays the online help, which lists these XDC command line options.


-sourcepath sourcepathlist 

Specifies the search paths for finding source files when passing package names or -subpackages into the XDC command. The sourcepathlist can contain multiple paths by separating them with a semicolon (;). The XDC tool will search in all subdirectories of the specified paths.

Set sourcepathlist to the root directory of the source tree for the package you are documenting. For example, suppose you want to document a package called com.mypackage whose source files are located at: 

C:\user\src\com\mypackage\*.xml
In this case you would specify the sourcepath to C:\user\src, the directory that contains com\mypackage, and then supply the package name com.mypackage: 
  C:> xdc -sourcepath C:\user\src com.mypackage
This is easy to remember by noticing that if you concatenate the value of sourcepath and the package name together and change the dot to a backslash "\", you end up with the full path to the package: C:\user\src\com\mypackage.

To point to two source paths: 

  C:> xdc -sourcepath C:\user1\src;C:\user2\src com.mypackage


-subpackages package1:package2:... 

Generates documentation from source files in the specified packages and recursively in their subpackages. This option is useful when adding new subpackages to the source code, as they are automatically included. Each package argument is any top-level subpackage or fully qualified package that does not need to contain source files. Arguments are separated by colons (on all operating systmes). Wildcards are not needed or allowed. Use -sourcepath to specify where to find the packages. This option is smart about not processing source files that are in the source tree but do not belong to the packages, as described at processing of source files.

For example: 

  C:> xdc -d docs -sourcepath C:\user\src -subpackages net

-exclude package1:package2 

Unconditionally excludes the specified packages and their subpackages from the list formed by -subpackages . It excludes those packages even if they would otherwise be included by some previous or later -subpackages option. For example: 

  C:> xdc -sourcepath C:\user\src -subpackages net.sf.xdc -exclude net.sf.xdc.resources
would include net.sf.xdc.xsl (among others), but would exclude packages rooted at net.sf.xdc.resources. Notice this excludes all subpackages of net.sf.xdc.resources as well.


-locale language_country_variant 

Specifies the locale that XDC uses when generating documentation. The argument is the name of the locale, as described in java.util.Locale documentation, such as en_US (English, United States) or en_US_WIN (Windows variant).

Specifying a locale causes XDC to choose the resource files of that locale for messages (strings in the navigation bar, headings for lists and tables, and so forth). It does not determine the locale of the doc comment text specified in the source files of the documented classes.


-encoding name 

Specifies the encoding name of the source files, such as EUCJIS/SJIS. If this option is not specified, the platform default converter is used.

Also see -docencoding and -charset .


-J flag 

Passes flag directly to the runtime system java that runs XDC. Notice there must be no space between the J and the flag. For example, if you need to ensure that the system sets aside 32 megabytes of memory in which to process the generated documentation, then you would call the -Xmx option of java as follows (-Xms is optional, as it only sets the size of initial memory, which is useful if you know the minimum amount of memory required): 

  C:> xdc -J-Xmx32m -J-Xms32m com.mypackage


-d directory 

Specifies the destination directory where XDC saves the generated HTML files. (The "d" means "destination.") Omitting this option causes the files to be saved in the first specified -sourcepath . The value directory can be absolute, or relative to the current working directory. The destination directory is automatically created when XDC is run.

For example, the following generates the documentation for the package com.mypackage and saves the results in the C:\user\doc\ directory: 

  C:> xdc -d \user\doc com.mypackage


-version 

Includes the @version text in the generated docs. This text is omitted by default.


-author 

Includes the @author text in the generated docs.


-windowtitle title 

Specifies the title to be placed in the HTML <title> tag. This appears in the window title and in any browser bookmarks (favorite places) that someone creates for this page. This title should not contain any HTML tags, as the browser will not properly interpret them. Any internal quotation marks within title may have to be escaped. If -windowtitle is omitted, the XDC tool uses the value of -doctitle for this option. 

  C:> xdc -windowtitle "XDC - the XML Documentation Generator" net.sf.xdc.xsl


-doctitle title 

Specifies the title to be placed near the top of the overview summary file. The title will be placed as a centered, level-one heading directly beneath the upper navigation bar. The title may contain html tags and white space, though if it does, it must be enclosed in quotes. Any internal quotation marks within title may have to be escaped. 

  C:> xdc -doctitle "XDC - the XML Documentation Generator" net.sf.xdc.xsl


-header header 

Specifies the header text to be placed at the top of each output file. The header will be placed to the right of the upper navigation bar. header may contain HTML tags and white space, though if it does, it must be enclosed in quotes. Any internal quotation marks within header may have to be escaped. 

  C:> xdc -header "XDC - v. 0.5" net.sf.xdc.xsl


-footer footer 

Specifies the footer text to be placed at the bottom of each output file. The footer will be placed to the right of the lower navigation bar. footer may contain HTML tags and white space, though if it does, it must be enclosed in quotes. Any internal quotation marks within footer may have to be escaped.


-bottom text 

Specifies the text to be placed at the bottom of each output file. The text will be placed at the bottom of the page, below the lower navigation bar. The text may contain HTML tags and white space, though if it does, it must be enclosed in quotes. Any internal quotation marks within text may have to be escaped.


-linksource 

Creates an HTML version of each source file (with line numbers) and adds links to them from the standard HTML documentation. Links are created for top-level elements and all documented subelements.

This option exposes all private implementation details in the included source files.

Each link appears on the XML element summary of the documented XML element. For example, the link to the source code of the XSLT stylesheet in the file comments.xsl would be on the start tag of the xsl:stylesheet element:

File comments.xsl

<xsl:stylesheet version="1.0">
  <xsl:import href="util.xsl"/>
</xsl:stylesheet>
and the link to the source code of the XSLT template with mode="basePage.renderNavbar" is on the opening tag of the xsl:template element: 
<xsl:template match="/" mode="basePage.renderNavbar">
  <xsl:param name="headerText"/>
</xsl:template>


-nosince 

Omits from the generated docs the "Since" sections associated with the @since tags.


-nohelp 

Omits the HELP link in the navigation bars at the top and bottom of each page of output.


-nonavbar 

Prevents the generation of the navigation bar, header and footer, otherwise found at the top and bottom of the generated pages. Has no effect on the "bottom" option. The -nonavbar option is useful when you are interested only in the content and have no need for navigation, such as converting the files to PostScript or PDF for print only.


-helpfile path/filename 

Specifies the path of an alternate help file path\filename that the HELP link in the top and bottom navigation bars link to. Without this option, the XDC tool automatically creates a help file help-doc.html that is hard-coded in the XDC tool. This option enables you to override this default. The filename can be any name and is not restricted to help-doc.html – the XDC tool will adjust the links in the navigation bar accordingly. For example: 

  C:> xdc -helpfile C:\user\myhelp.html net.sf.xdc.xsl.*.xsl


-stylesheetfile path/filename 

Specifies the path of an alternate HTML stylesheet file. Without this option, the XDC tool automatically creates a help file stylesheet.css that is hard-coded in the XDC tool. This option enables you to override this default. The filename can be any name and is not restricted to stylesheet.css. For example: 

  C:> xdc -stylesheetfile C:\user\mystylesheet.css net.sf.xdc.xsl.*.xsl


-charset name 

Specifies the HTML character set for this document. The name should be a preferred MIME name as given in the IANA Registry. For example: 

  C:> xdc -charset "iso-8859-1" mypackage
would insert the following line in the head of every generated page: 
  <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
This META tag is described in the HTML standard. (4197265 and 4137321)

Also see -encoding and -docencoding .


-docencoding name 

Specifies the encoding of the generated HTML files. The name should be a preferred MIME name as given in the IANA Registry. If you omit this option but use -encoding , then the encoding of the generated HTML files is determined by -encoding. Example: 

  C:> xdc -docencoding "iso-8859-1" mypackage

Also see -encoding and -charset .


-notimestamp 

Suppresses the timestamp, which is hidden in an HTML comment in the generated HTML near the top of each page. Useful when you want to run XDC on two source bases and diff them, as it prevents timestamps from causing a diff (which would otherwise be a diff on every page). The timestamp currently looks like this: 

  <!--generated by xdc on Mon Mar 20 17:34:10 CET 2006-->


-reportmissing 

This option causes XDC to issue a warning whenever it generates documentation for a top-level element or subelement which has no XDC documentation comment in the source. The output files are not affected by this option.


-forceoptions 

By default, XDC options specified via an XDC processing instruction take precedence over those specified on the command line. If the -forceoptions option is specified, this precedence order is reversed.


-extensions 

This option allows to restrict the set of processed files further by their file extensions. Multiple extensions are separated by commas: 

  C:> 


-defaultexcludes 

This option can be used to exclude files and directories from processing that are normally used by a version control system. Excluded filename patterns are:

  • *~
  • #*#
  • .#*
  • %*%
  • ._*
  • CVS
  • .cvsignore
  • SCCS
  • vssver.scc
  • .svn
  • .DS_Store


-dialects dialect-definition-file 

The XDC tool includes stylesheets for three built-in XML dialects:

  • xsl for XSLT stylesheet files
  • ant for Apache Ant build files
  • generic for generic XML files

If XML files for additional XML dialects need to be processed by the XDC tool, stylesheets for these dialects need to be registered in a properties file. This dialects file is then specified via the -dialects option.

For example, if JSP tag library descriptor files should be processed, a stylesheet named tld.xsl that handles the dialect specific elements should be written and registered in a file named e.g. myDialects.properties: 

  tld=c:\user\xdc\tld.xsl
The XDC tool can then be invoked with the -dialects option: 
  C:> xdc -dialects c:\user\xdc\myDialects.properties -dialect tld c:\user\xdc\**\*.tld


-dialect dialect-name 

By default, the XDC tool treats all XML source files as generic XML files with the exceptions of files named build.xml (which is always considered an Ant build file) and all files with the extension .xsl (which are always considered XSLT stylesheet files).

In cases where XDC should only process files of one XML dialect, the -dialect option can be used to specify that dialect.

If this is a dialect other than the three built-in dialects xsl, ant and generic, it must be registered using the -dialects option.


-dialectmapping dialect-mapping-file 

In cases in which XDC processes files of more than one XML dialect and in which the mapping of files to dialects is different than the built-in mapping described above, mappings from path/file patterns can be defined in a properties file which is specified using the -dialectmapping option.

In the example above, the dialect-mapping-file could be a file named dialectMapping.properties containg the line 

  **/*.tld=tld
which can then be used with the -dialectmapping option: 
  C:> xdc -dialects c:\user\xdc\myDialects.properties -dialectmapping c:\user\xdc\dialectMapping.properties c:\user\xdc\**\*


Command Line Argument Files

To shorten or simplify the XDC command line, you can specify one or more files that themselves contain arguments to the XDC command (except -J options). This enables you to create XDC commands of any length on any operating system.

An argument file can include XDC options, source filenames and package names in any combination, or just arguments to XDC options. The arguments within a file can be separated by spaces, tabs or newlines. Filenames within an argument file are relative to the current directory, not the location of the argument file. Wildcards ('?', '*', '**') are allowed in these lists. Use of the '@' character to recursively interpret files is not supported. The -J options are not supported because they are passed to the launcher, which does not support argument files.

The hash character ('#') is used to start comments; comments are terminated by the end of the current line.

Double quotes ('"') are used to delimit arguments that may contain whitespace characters but that are to be treated as a single option.

The backslash character ('\') may be used to escape any character which has a special meaning (such as '"', '#' or '\' itself).

When executing XDC, pass in the path and name of each argument file with the '@' leading character. When XDC encounters an argument beginning with the character '@', it expands the contents of that file into the argument list.

Example - Single Arg File

You could use a single argument file named "argfile" to hold all XDC arguments: 

  C:> xdc @argfile
This argument file could contain the contents of both files shown in the next example.

Example - Two Arg Files

You can create two argument files - one for the XDC options and the other for the package names or source filenames: (Notice the following lists have no line-continuation characters.)

Create a file named "options" containing: 


      -linksource
      -defaultexcludes
      -subpackages net.sf.xdc
      -extensions xml,xsl
      -overview c:/work/Projects/xdc/src/xdc-overview.html
      -doctitle "XDC - the XML Documentation Generator"
      -windowtitle "XDC - the XML Documentation Generator"
      -header "XDC - v. 0.5"
      -footer "XDC - v. 0.5"
      -bottom "<font size=\"-1\"><i>Copyright &\#169; 2005 - 2006 Jens Voß</i></font>"
      -author
Create a file named "packages" containing: 
      com.mypackage1
      com.mypackage2
      com.mypackage3
You would then run XDC with: 
  C:> xdc @options @packages

Example - Arg Files with Paths

The argument files can have paths, but any filenames inside the files are relative to the current working directory (not path1 or path2): 

  C:> xdc @path1\options @path2\packages

Example - Option Arguments

Here's an example of saving just an argument to an XDC option in an argument file. We'll use the -bottom option, since it can have a lengthy argument. You could create a file named "bottomtext" containing its text argument: 


"<font size=\"-1\"><i>Copyright &\#169; 2005 - 2006 Jens Voß</i></font>"

Then run the XDC tool with: 
  C:> xdc -bottom @bottomtext @packages
Or you could include the -bottom option at the start of the argument file, and then just run it as: 
  C:> xdc @bottomtext @packages
It is even legal (though rather peculiar) to place the XDC option -bottom in a separate file named "bottomcall" (but not in "bottomtext") and invoke the XDC tool with 
  C:> xdc @bottomcall @bottomtext @packages
Java TM and Javadoc TM are trademarks of Sun Microsystems, Inc.