3.1 fpdoc

Using FPDOC is quite simple. It takes some command-line options, and based on these options, creates documentation. The command-line options can be given as long or short options, as is common for most GNU programs.

In principle, only 2 command-line options are needed:

package: This specifies the name of the package for which documentation must be created. Exactly one package option can be specified.
input: The name of a unit file for which documentation should be generated. This can be a simple filename, but can also contain some syntax options as they could be given to the Free Pascal scanner. More than one input option can be given, and documentation will be generated for all specified input files.

Some examples:

 fpdoc --package=fcl --input=crt.pp

This will scan the crt.pp file and generate documentation for it in a directory called fcl.

 fpdoc --package=fcl --input='-I../inc -S2 -DDebug classes.pp'

This will scan the file classes.pp, with the DEBUG symbol defined, the scanner will look for include files in the ../inc directory, and OBJFPC-mode syntax will be accepted.

(for more information about these options, see the Free Pascal compiler user’s guide)

With the above commands, a set of documentation files will be generated in HTML format (this is the standard). There will be no description of any of the identifiers found in the unit’s interface section, but all identifiers declarations will be present in the documentation.

The actual documentation (i.e. the description of each of the identifiers) resides in a description file, which can be specified with the descr option:

 fpdoc --package=fcl --descr=crt.xml --input=crt.pp

This will scan the crt.pp file and generate documentation for it, using the descriptions found in the filecrt.xml file. The documentation will be written in a directory called fcl.

 fpdoc --package=fcl --descr=classes.xml \
       --input='-I../inc -S2 -DDebug classes.pp'

All options should be given on one line. This will scan the file classes.pp, with the DEBUG symbol defined, the scanner will look for include files in the ../inc directory, and OBJFPC-mode syntax will be accepted.

More than one input file or description file can be given:

 fpdoc --package=fcl --descr=classes.xml --descr=process.xml \
       --input='-I../inc -S2 -DDebug classes.pp' \
       --input='-I../inc -S2 -DDebug process.pp'

Here, documentation will be generated for 2 units: classes and process

The format of the description file is discussed in the next chapter.

Other formats can be generated, such as latex:

 fpdoc --format=latex --package=fcl \
       --descr=classes.xml --descr=process.xml\
       --input='-I../inc -S2 -DDebug classes.pp' \
       --input='-I../inc -S2 -DDebug process.pp'

This will generate a LaTeX file called fcl.tex, which contains the documentation of the units classes and process. The latex file contains no document preamble, it starts with a chapter command. It is meant to be included (using the LaTeX include command) in a latex document with a preamble.

The output of FPDOC can be further customised by several command-line options, which will be explained in the next section.

[next] [front] [up]