Configuration

Overview

PDFDoclet should be configured through a property file. This is (IMHO) the clearest and easiest way of maintaining a set of configuration values (instead of using dozens of parameters). However, all settings can also be configured through commandline parameters.

For using a property file, specify the file with the "-config" commandline argument: 

  -config <property file path>

All other configuration values can be specified as an argument or in a property file. For example, to print the "author" tag, either the commandline argument "-author" may be specified, or the property "author" may be set in the config file.

Note that all properties with a boolean value ("true"/"yes" or "false"/"no") DON'T TAKE A VALUE when specified as commandline argument. In that case, they are by default assumed to be "true". For example, specifiying "-author" (without a specific value) on the commandline has the same meaning as specifying "author=true" or "author=yes" in the configuration file.

Properties

Here is a list of all available configuration properties. The list has been split in two parts: The first lists all simple boolean "yes"/"no" properties. The second list shows all the properties which need an additional value argument on the command line.

Boolean properties (value "yes"/"no")

PropertyDescription
debugLets the doclet print additional output in the console and to a logfile.
authorPrint "Author" tags
versionPrint "Version" tags
tag.sincePrint "since" tags
summary.tableCreate summary tables
create.linksCreate hyperlinks
encryptedEncrypt the PDF file
allow.printingAllow printing of the PDF file
create.frameCreate a bookmark frame
api.title.pagePrint a title page
filterEnables the tag-based filter

Properties with a value

PropertyDescription
pdf <file>The path of the created PDF file.
workdir <dir>The base directory for image file path specifications (default is the current directory).
sort <list>Optional comma-separated list of package names to define the ordering of the packages in the bookmarks frame.
dontspec <list>Optional comma-separated list of package names to define packages whose classes should not be printed fully qualified (just "String" instead of "java.lang.String").
label.tag.<name> <label>Specifies a custom doc tag with a certain label.
label.bookmarks.titleOverrides the text label to be printed for the title of the bookmarks.
label.bookmarks.indexOverrides the text label to be printed for the index entry in the bookmarks.
label.bookmarks.overviewOverrides the text label to be printed for the overview entry in the bookmarks.
label.bookmarks.packagesOverrides the text label to be printed for the packages entry in the bookmarks.
label.bookmarks.otherPackagesOnly used with the -group parameter. Overrides the text label to be printed for the "Other Packages" entry in the bookmarks.
label.fieldsOverrides the text label to be printed for the fields entry in the bookmarks.
label.constructorsOverrides the text label to be printed for the constructors entry in the bookmarks.
label.methodsOverrides the text label to be printed for the methods entry in the bookmarks.
label.tag.<tagname>Defines the text label for a tag. Can either override the label of a default tag such as "author", or define the label for a custom tag (custom tags are not printed as long as no label is defined for them).
inherited.summary.table=[yes|internal]Create summary tables for inherited fields/methods. If the values is set to internal, summary tables are printed only for elements inherited by classes and interfaces within the scope of the API. Elements inherited from other classes such as java.lang.Object are ignored.
appendix.<number>.nameDefines the name / number of the appendix.
appendix.<number>.titleDefines the title label of the appendix.
appendix.<number>.file=<file path>[,page,from-to,..,..]Path of the HTML or PDF file that should be included. If a PDF file is specified, the filename may be followed by a comma-separated list of single page numbers or page ranges, to define which pages to import from the PDF document.
page.numbers.prefix <text>Prefix-text for page numbers.
page.numbers.type <type>"full" or "simple"
page.numbers.alignment <type>"left", "center", "right" or "switch". Defines the alignment of page numbers. "switch" means that they will switch from left to right and back, as needed for printing.
api.title.file <file>The path of a HTML file used for the title page of the PDF.
api.title <file>Title for the title page if no external HTML title page is used.
api.copyright <copyright>Copyright remark for the title page if no external HTML title page is used.
api.author <author>Author's name for the title page if no external HTML title page is used.
font.text.name <ttf-file>Font to be used for all regular text. Default is TIMES-ROMAN (path of TrueType-font, like ./fonts/garait.ttf).
font.text.encOptional encoding for the text font.
font.code.name <ttf-file>Font to be used for all fixed-width code parts. Default is COURIER.
font.code.encOptional encoding for the code font.
filter.tags <taglist>Comma-separated list of filter tags.
filter.tag.<name> <label>Filter tag with certain name and value.

Font embedding

As for the fonts: The specified font will be embedded into the PDF. If that is not possible (due to legal restrictions of the font), the doclet will fail to create the PDF.

Overriding properties with parameters

Please note: A configuration file can be used in combination with command-line arguments. However, every configuration value specified on the command line will override the same configuration property from the property file. For example, if the command-line parameter "-workdir=./example/src3" is used, but in the configuration file there's a property "workdir=./example/src1", the value will be "./example/src3".

IMPORTANT NOTE: In versions 0.6.0 and older of PDFDoclet, it was exactly the other way around, which was not very logical and intuitive. Therefore I decided to change it (better getting rid of bad implementation at the risk of causing some temporary confusion than keeping it forever).

For information about how to use additional parameters with a custom doclet, read Sun's javadoc instructions. Also check out the targets "example" and "test-pdf" in the build.xml file to see how it can be done.