Subsections


3 FPDOC usage

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.htex, 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.

2 FPDOC command-line options reference

In this section all FPDOC command-line options are explained.


1 content

This option tells FPDOC 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 (section [*], page [*]).


2 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 FPDOC to read documentation from crt.xml, while
--descr=@fcl.lst
will tell FPDOC 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.


3 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.

4 help

Gives a short copyright notice.


5 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.


6 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.

FPDOC 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


7 import

Import a table of contents file, generated by FPDOC for another package with the content option (section [*], page [*]). 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.

Note that for Latex documentation, this option is ignored.


8 input

This option tells FPDOC 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 Pascal compiler 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.


9 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.


10 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.


11 output

This option tells FPDOC 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 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.


12 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 (section [*], page [*]).


13 show-private

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


3 makeskel


1 introduction

The makeskel tool can be used to generate an empty description file for a unit. The description file will contain an element node for each identifier in the interface section of the Pascal unit.

It's usage is quite straightforward: the name of an input file (one or more) must be specified (as for FPDOC), an output file, and the name of a package:

makeskel --package=rtl --input=crt.pp --output=crt.xml
This will read the file crt.pp and will create a file crt.xml which contains empty nodes for all identifiers found in crt.pp, all in a package named rtl.

The input option can be given more than once, as for the fpdoc command:

makeskel --input='-Sn system.pp' --input=crt.pp --output=rtl.xml
As can be seen, the input option can contain some compiler options, as is the case for FPDOC. The above command will process the files system.pp and crt.pp, and will create element tags for the identifiers in both units in the file rtl.xml.

The output of makeskel is a valid, empty description file. It will contain a module tag for each unit specified, and each module will have element tags for each identifier in the unit.

Each element tag will by default contain short, descr, errors and seealso tags, but this can be customised.


4 Makeskel option reference

The output of makeskel can be customised using several options, which are discussed below.


1 disable-arguments

By default, for each function or procedure argument, a element tag will be generated. This option disables this behaviour: no element tags will be generated for procedure and function arguments.


2 disable-errors

If this option is specified, no errors tag will be generated in the element nodes. By default all element tags contain a errors node.

The errors tag is ignored when it is not needed; Normally, an errors tag is only needed for procedure and function elements.


3 disable-function-results

If this option is specified, then no element tag will be generated for function results. By default, makeskel will generate a result node for each function in the interface section. The result node is used in the documentation to document the return value of the function under a separate heading in the documentation page. Specifying this option suppresses the generation of the element tag for the function result.


4 disable-private

If this option is specified, then no element tags will be generated for private methods or fields of classes or objects. The default behaviour is to generate nodes for private methods or fields. It can be used to generate a skeleton for end-user and developer documentation.


5 disable-protected

If this option is specified, then no element tags will be generated for protected and private methods or fields of classes or objects. The default is to generate nodes for protected methods or fields. If this option is given, the option -disable-private is implied. It can be used to generate end-user-only documentation for classes.


6 disable-seealso

If this option is specified, no seealso tag will be generated in the element nodes. By default all element tags contain a seealso tag.


7 emitclassseparator

When this option is specified, at the beginning of the elements for the documentation of a class, a comment tag is emitted which contains a separator text. This can be useful to separate documentation of different classes and make the description file more understandable.


8 help

Makeskel emits a short copyright notice and exits when this option is specified.


9 input

This option is identical in meaning and functionality as the input option for FPDOC. (section [*], page [*]) It specifies the Pascal unit source file that will be scanned and for which a skeleton description file will be generated. Multiple input options can be given, and element tags will be written for all the files, in one big output file.


10 lang

This option is used to specify the language for messages emitted by makeskel. The supported languages are identical to the ones for FPDOC:
de
German.
fr
French.
nl
Dutch.


11 output

This option specifies the name of the output file. A full filename must be given, no extension will be added. If this option is omitted, the output will be sent to standard output.


12 package

This option specifies the package name that will be used when generating the skeleton. It is a mandatory option.




2004-02-13