command-line options reference

In this section all command-line options are explained.

auto-index

This option generates an index of all the types including objects, classes, their methods and enums, sorted alphabetically. Methods of classes and objects will appear as subitems of their class. If used in combination with –index-file this option will be used instead. This option only applies to the chm backend.

auto-toc

This option generates a Table of Contents that displays all classes, objects and routines in several ways. If used in combination with –toc-file this option will be used instead. This option only applies to the chm backend.

charset

This option can be used to specify the character set to be used for the HTML backend. It is simply inserted in the HTML tree. The default character set is iso-8859-1

For example

--charset=UTF8

will result in an UTF8 specification of the attribute of the tag in the generated HTML file:

<meta content="text/html; charset=UTF8" http-equiv="Content-Type">

chm-title

This option is to specify a nicer title than the default title which is the same value as –package=value.

content

This option tells to generate a content file. A content file contains a list of all the possible anchors (labels) in the generated documentation file, and can be used to create cross-links in documentation for units in other packages, using the counterpart of the content option, the import option ().

css-file

This option only applies to the chm backend. Use this option to set the css file used to style the html when the html is rendered by a viewer.

default-page

This option only applies to the chm backend. The default page to load when the chm is opened by a viewer. Using this option does not include a file but instead specifies a file you have included using –other-files. You only need to use this option if you have used the –other-files option and included a page you wish to use instead of the default page.

descr

This option specifies the name of a description file that contains the actual documentation for the unit. This option can be given several times, for several description files. The file will be searched relative to the current directory. No extension is added to the file, it should be a complete filename.

If the filename starts with an ’at’ sign @, then it is interpreted as a text file which contains a list of filenames, one per line. Each of these files will be added to the list of description files.

The nodes in the description files will be merged into one big tree. This means that the documentation can be divided over multiple files. When merging the description files, nodes that occur twice will end up only once in the big node tree: the last node will always be the node that ends up in the parse tree. This means that the order of the various input commands or the ordering of the files in the file list is important.

Examples:

--descr=crt.xml 

will tell to read documentation from crt.xml, while

--descr=@fcl.lst 

will tell to read filenames from fcl.lst; each of the filenames found in it will be added to the list of files to be scanned for descriptions.

emit-notes

This option tells the documentation engine to include notes in the text. By default, notes are not included in the text as they serve as working notes for the documenter.

footer

This option tells the HTML engine to include the file indicated by this option as the footer of each generated HTML page. The file is assumed to contain a valid XHTML fragment. The contents of the file will be inserted in the HTML tree.

Example:

--footer=footer.xml

Where footer.xml contains for example:

<hr/>
<i>Date generated : June 1, 2008</i>

This option is mutually exclusive with the footer-date option.

footer-date

This option tells the HTML engine to generate a footer for each page containing the current date. The optional format argument can be used to specify the format of the date. The format must be a formatting string as understood by the FormatDateTime function in the sysutils unit.

For example

--footer-date='mmm dd yyyy'

This option is mutually exclusive with the footer option.

format

Specifies the output format in which the documentation will be generated. Currently, the following formats are known:

htm

Plain HTML with 8.3 conforming filenames.

html

HTML with long filenames.

xhtml

XHTML with long filenames.

latex

LaTex, which uses the fpc.sty style used by the Free Pascal documentation.

xml-struct

Structured XML.

chm

Compressed HTML.

help

Gives a short copyright notice.

hide-protected

By default, the documentation will include descriptions and listings of protected fields and methods in classes or objects. This option changes this behaviour; if it is specified, no documentation will be generated for these methods. Note that public methods or properties that refer to these protected methods will then have a dangling (i.e. unavailable) link.

html-search

This option can be used when generating HTML documentation, to specify an url that can be used to search in the generated documentation. The URL will be included in the header of each generated page with a Search caption. The option is ignored for non-html output formats.

does not generate a search page, this should be made by some external tool. Only the url to such a page can be specified.

Example:

--html-search=../search.html

image-dir

This option tells the backend where the images are located. By default, a directory images is assumed. A path using forward slashes must be provided.

Example:

--image-dir=pictures/

image-url

This option tells the HTML backend where the images are located: the argument must be an absolute URL. By default, the images are assumed to be in a images directory below the package directory. Note that the URL must be absolute, i.e. if it is provided, the link to the image will be composed from the argument of this option with the filename.

Example:

--image-url=http://www.mysite.org/docs/pictures/

import

Import a table of contents file, generated by for another package with the content option (). This option can be used to refer to documentation nodes in documentation sets for other packages. The argument consists of two parts: a filename, and a link prefix.

The filename is the name of the file that will be imported. The link prefix is a prefix that will be made to each HTML link; this needs to be done to be able to place the files in different directories.

Example:

--import=../fcl.cnt,../fcl

This will read the file fcl.cnt in the parent directory. For HTML documentation, all links to items in the fcl.cnt file, the link will be prepended with ../fcl.

This allows a setup where all packages have their own subdirectory of a common documentation directory, and all content files reside in the main documentation directory, as e.g. in the following directory tree:

/docs/fcl
     /fpdoc
     /fpgui
     /fpgfx
     /fpimg

The file fcl.cnt would reside in the docs directory. Similarly, for each package a contents file xxx.cnt could be places in that directory. Inside the subdirectory, commands as the above could be used to provide links to other documentation packages.

Example:

--import=../fcl.cnt,ms-its:fcl.chm::/

As in the previous example this will read the file fcl.cnt in the parent directory. But all links to items in the fcl.cnt file, will be prepended with ms-its:fcl.chm::/. This is how chm’s are crosslinked.

Note that for Latex documentation, this option is ignored.

index-colcount

For the HTML backend, this option can be used to specify the number of columns that should be used when generating an identifier index page. By default, 3 columns are used.

Example:

--index-colcount=4

Will use 4 columns instead.

index-file

Use this option to specify a local file to include and use as the index. This file is in the sitemap format. You can use the unit chmsitemap in your programs to read and write this type of file. Usually this file ends with .hhk. This option only applies to the chm backend.

input

This option tells what input file should be used. The argument can be just a filename, but can also be a complete compiler command-line with options that concern the scanning of the Pascal source: defines, include files, syntax options, as they would be specified to the Free Pascalcompiler when compiling the file. If a complete command is used, then it should be enclosed in single or double quotes, so the shell will not break them in parts.

It is possible to specify multiple input commands; they will be treated one by one, and documentation will be generated for each of the processed files.

lang

Select the language for the generated documentation. This will change all header names to the equivalent in the specified language. The documentation itself will not be translated, only the captions and headers used in the text.

Currently, valid choices are

de

German.

fr

French.

nl

Dutch.

Example:

--lang=de

Will select German language for headers.

The language files should be installed correctly for this option to work. See the section on installing to check whether the languages are installed correctly.

latex-highlight

Switches on an internal latex syntax highlighter. This is not yet implemented. By default, syntax highlighting is provided by the syntax package that comes with Free Pascal.

make-searchable

This option generates an index of all the *.htm* files added in the chm, including files added with the –other-files option so that a full text search is possible. This option only applies to the chm backend.

other-files

This option specifies a text file with one filename per line to be included in the chm. You can include any type of file you want; it does not have to be a html file. For instance you can include images that you have linked to in the xml descr files. The files should be in a subfolder of the working directory and within their own folder to avoid naming conflicts with the auto generated files. This option only applies to the chm backend.

output

This option tells where the output file should be generated. How this option is interpreted depends on the format that is used. For latex, this is interpreted as the filename for the tex file. For chm, this is interpreted as the output filename. For all other formats, this is interpreted as the directory where all documentation files will be written. The directory will be created if it does not yet exist.

The filename or directory name is interpreted as relative to the current directory.

Example:

--format=html --output=docs/classes

will generate HTML documentation in the directory docs/classes.

--format=latex --output=docs/classes.tex

will generate latex documentation in the file docs/classes.

--format=chm --output=docs.chm

will generate chm documentation in the file docs.chm.

package

This option specifies the name of the package to be used. The package name will also be used as a default for the output option ().

Note that if a project file is specified with multiple packages, this option will be used to select the package for which to produce documentation.

project

can work with a project file. This is an XML file which can contain specifies global options, and which contains the definition for one or more packages, for which it lists input files and description files etc. The project file is described in more detail in chapter The project file.

This option expects an argument, the name of the project file to use.

Example:

fpdoc --project=rtl-project.xml --format=html --package=rtl

show-private

By default, no documentation is generated for private methods or fields of classes or objects. This option causes to generate documentation for these methods and fields as well.

toc-file

Use this option to specify a local file to include as Table of Contents. The table of contents is in the sitemap format and usually ends in .hhc. You can use the unit chmsitemap in your programs to read and write files of this type. This option only applies to the chm backend of .

warn-no-node

If this option is given, then fpdoc will emit a warning if it cannot find a documentation node for some identifier. This can be used to see whether the description files are up-to-date, or whether they must be updated.

write-project

can create a project file based on all options given on the command line. For more information about the project file, chapter The project file.

This option expects an argument, the name of the project file to write.

Example:

fpdoc --write-project=rtl-project.xml --format=html --package=rtl
--input=file.pp --descr=file.xml