united security providers Logs

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")

Property Description
debug Lets the doclet print additional output in the console and to a logfile.
author Print "Author" tags
version Print "Version" tags
tag.since Print "since" tags
summary.table Create summary tables
create.links Create hyperlinks
encrypted Encrypt the PDF file
allow.printing Allow printing of the PDF file
create.frame Create a bookmark frame
api.title.page Print a title page
filter Enables the tag-based filter

Properties with a value

Property Description
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.title Overrides the text label to be printed for the title of the bookmarks.
label.bookmarks.index Overrides the text label to be printed for the index entry in the bookmarks.
label.bookmarks.overview Overrides the text label to be printed for the overview entry in the bookmarks.
label.bookmarks.packages Overrides the text label to be printed for the packages entry in the bookmarks.
label.bookmarks.otherPackages Only used with the -group parameter. Overrides the text label to be printed for the "Other Packages" entry in the bookmarks.
label.fields Overrides the text label to be printed for the fields entry in the bookmarks.
label.constructors Overrides the text label to be printed for the constructors entry in the bookmarks.
label.methods Overrides 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>.name Defines the name / number of the appendix.
appendix.<number>.title Defines 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.size <text> "letter" or "A4" (default).
page.orientation <text> "landscape" or "portrait" (default).
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.enc Optional 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.enc Optional 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.