Subsections
3 FPDOC usage
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.
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.
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