Free Pascal document, Apuntes de Introducción a la Informática

¡Descarga Free Pascal document y más Apuntes en PDF de Introducción a la Informática solo en Docsity!

FPDoc :

Free Pascal code documenter: Reference manual

Reference manual for FPDoc

Document version 0.

June 26, 2003

Michaël Van Canneyt

Contents

• 1 Introduction
  • 1.1 About this document
  • 1.2 About FPDOC
  • 1.3 Getting more information.
• 2 Compiling and Installing FPDOC
  • 2.1 Compiling
  • 2.2 Installation
• 3 FPDOC usage
  • 3.1 fpdoc
  • 3.2 FPDOC command-line options reference
    • content
    • descr
    • format
    • help
    • hide-protected
    • html-search
    • import
    • input
    • lang
    • latex-highlight
    • output
    • package
    • show-private
  • 3.3 makeskel
    • introduction
  • 3.4 Makeskel option reference
    • disable-arguments
    • disable-errors
    • disable-function-results
    • disable-private CONTENTS
    • disable-protected
    • disable-seealso
    • emitclassseparator
    • help
    • input
    • lang
    • output
    • package
• 4 The description file
  • 4.1 Introduction
  • 4.2 Element names and cross-referencing
    • Element name conventions
    • Cross referencing: the link tag
  • 4.3 Tag reference
    • Overview
    • b : format bold
    • caption : Specify table caption
    • code : format as pascal code
    • descr : Descriptions
    • dd : definition data.
    • dl : definition list.
    • dt : definition term.
    • element : Identifier documentation
    • errors : Error section.
    • fpdoc-description : Global tag
    • i : Format italics
    • li : list element
    • link : Cross-reference
    • module : Unit reference
    • ol : Numbered list.
    • p : Paragraph
    • package : Package reference
    • pre : Insert text as-is
    • remark : format as remark
    • seealso : Cross-reference section
    • short : Short description
    • table : Table start
    • td : Table cell
    • th : Table header CONTENTS
    • tr : table row
    • u : Format underlined
    • ul : bulleted list
    • var : variable
• 5 Generated output files.
  • 5.1 HTML output
  • 5.2 Latex output

Chapter 1

Introduction

1.1 About this document

This is the reference manual for FPDOC, a free documentation tool for Pascal units. It describes the usage of FPDOC and how to write documentation with it.

It attempts to be complete, but the tool is under continuous development, and so there may be some slight differences between the documentation and the actual program. In case of discrepancy, the sources of the tool are the final reference. A README or CHANGES file may be provided, and can also give some hints as to things which have changed. In case of doubt, these files or the sources are authoritative.

1.2 About FPDOC

FPDOC is a tool that combines a Pascal unit file and a description file in XML format and produces reference documentation for the unit. The reference documentation contains documentation for all of the identifiers found in the unit’s interface section. The documentation is fully cross-referenced, making it easy to navigate. It is also possible to refer to other documentation sets written with FPDOC, making it possible to maintain larger documentation sets for large projects.

Contrary to some other documentation techniques, FPDOC does not require the presence of formatted comments in the source code. It takes a source file and a documentation file (in XML format) and merges these two together to a full documentation of the source. This means that the code doesn’t get obfuscated with large pieces of comment, making it hard to read and understand.

FPDOC is package-oriented, which means that it considers units as part of a package. Documentation for all units in a package can be generated in one run.

At the moment of writing, the documentation can be generated in the following formats:

HTML Plain HTML. Javascript is used to be able to show a small window with class properties or class methods, but the generated HTML will work without JavaScript as well. Style sheets are used to do the markup, so the output can be customised.

XHTML As HTML, but using a more strict syntax.

LaTeX LaTeX files, which can be used with the fpc.sty file which comes with the Free Pascal doc- umentation. From this output, PDF documents can be generated, and with the use of latex2rtf, RTF or Winhelp files. Text files can also be generated.

Plans exist to create direct text output and RTF output as well.

Chapter 2

Compiling and Installing FPDOC

2.1 Compiling

In order to compile FPDOC, the following things are needed:

1. The fpdoc sources. These can be downloaded from the FPDOC website.
2. The Free Pascal compiler sources. FPDOC uses the scanner from the Free Pascal comiler to scan the source file.
3. The FCL units (or their sources) should be installed.
4. fpcmake is needed to create the makefile for fpdoc. It comes with Free Pascal, so if Free Pascal is installed, there should be no problem.
5. To make new internationalisation support files, rstconv must be installed, and the GNU gettext package.

Links to download all these programs can be found on the FPDOC website.

When the fpdoc sources have been unzipped, the Makefile must be generated. Before generating the makefile, the location of the compiler source directory should be indicated. In the Makefile.fpc file, which has a windows ini file format, locate the fpcdir entry in the defaults section:

fpcdir=../..

and change it so it points to the top-level Free Pascal source directory.

After that, running fpcmake will produce the Makefile, and running make should produce 2 execut- ables: fpdoc and makeskel.

2.2 Installation

When installing from sources, a simple

make install cd intl make install

CHAPTER 2. COMPILING AND INSTALLING FPDOC

should completely install the documentation tool.

When installing from a archive with the binaries, it should be sufficient to copy the binaries to a directory in the PATH.

To have fpdoc available in several languages, the language files should be installed in the following directory on Unix systems:

/usr/local/share/locale/XX/LC_MESSAGES/

or

/usr/share/locale/XX/LC_MESSAGES/

Depending on the setup. Here XX should be replaced by the locale identifier.

CHAPTER 3. FPDOC USAGE

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.

3.2 FPDOC command-line options reference

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

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 doc- umentation for units in other packages, using the counterpart of the content option, the import option (section 3.2, page 11).

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.

CHAPTER 3. FPDOC USAGE

Examples:

--descr=crt.xml

will tell FPDOC to read documentation from crt.xml, while

[email protected]

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.

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.

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.

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

CHAPTER 3. FPDOC USAGE

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

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.

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 3.2, page 12).

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

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

CHAPTER 3. FPDOC USAGE

This will read the file crt.pp and will create a file crt.xml which contains empty nodes for all identi- fiers 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.

3.4 Makeskel option reference

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

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.

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.

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.

disable-private CONTENTS

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.

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

Chapter 4

The description file

4.1 Introduction

The description file is a XML document, which means that it is a kind of HTML or SGML like format, however it is more structured than HTML, making it easier to parse - and makes it easier to connect or merge it with a Pascal source file. Since the allowed syntax uses a lot of HTML tags, this makes it easy to write code for those that are familiar with writing HTML.

More information about the XML format, SGML and HTML can be found on the website of the W (World Wide Web) consortium: http://www.w3.org/

The remaining of this chapter assumes a basic knowledge of tags, their attributes and markup lan- guage, so these terms will not be explained here.

The minimal documentation file would look something like this:

The header xml tag is mandatory, and indicates that the file contains a documentation XML docu- ment.

Inside the document, one or more top-level fpdoc-descriptions tags may appear. Each of these tags can contain one or more package tags, which must have a name attribute. The name attribute will be used by fpdoc to select the documentation nodes.

Inside a package tag, one or more module tags may appear. there should be one module tag per unit that should be documented. The value of the name attribute of the module should be the name of the unit for which the module tag contains the documentation. The value of the name attribute is case insensitive, i.e.

can be used for the documentation of the crt unit.

As it is above, the documentation description does not do much. To write real documentation, the module tag must be filled with the documentation for each identifier that appears in the unit interface header.

CHAPTER 4. THE DESCRIPTION FILE

For each identifier in the unit interface header, the module should contain a tag that documents the identifier: this is the element tag. The name attribute of the element tag links the documentation to the identifier: the name attribute should have as value the fully qualified name of the identifier in the unit.

For example, to document the type

Type MyEnum = (meOne,meTwo,meThree);

an element tag called myenum should exist:

But also for each of the three enumerated values an element tag should exist:

As it can be seen, the names of the identifiers follow a hierarchical structure. More about this in the next section.

Now the tags for the types are present, all that should be done is to fill it with the actual description. For this, several tags can be placed inside a element tag. The most important tag is the descr tag. The contents of the descr tag will be used to describe a type, function, constant or variable:

The MyEnum type is a simple enumeration type which is not really useful, except for demonstration purposes.

A second important tag is the short tag. It should contain a short description of the identifier, prefer- ably a description that fits on one line. The short tag will be used in various overviews, at the top of a page in the HTML documentation (a synopsis) or will be used instead of the descr tag if that one is not available. It can also be used in different other cases: For instance the different values of an enumeration type will be laid out in a table, using the short description:

The first enumeration value The second enumeration value The third enumeration value

This will be converted to a table looking more or less like this:

CHAPTER 4. THE DESCRIPTION FILE

text. In the HTML version of the documentation, this piece of text will function as a hyperlink. In the latex version, a page number reference will be printed.

The id attribute contains the name of an element to which the link refers. The name is not case sensitive, but it must be a fully qualified name.

An example of the link type would be:

The MyEnum type is a simple type.

The link attribute also has a short form:

The type is a simple type.

In the short form, the value of the id attribute will be used as the text which will be hyperlinked. This is especially useful in the seealso tag.

To refer to a type in another unit, the unit name must be prepended to the id attribute:

will link to the myenum type in a unit named myunit.

To refer to a node in the documentation of another package, the package name should be prepended to the id attribute, and it should be prepended with the hash symbol (#):

will link to the constant sofrombeginning in the classes unit of the FCL reference document- ation. Note that for this to work correctly, the contents file which was created when generating the documentation of the type must be imported correctly (see the import option).

4.3 Tag reference

Overview

The tags can roughly be divided in 2 groups:

1. Documentation structure tags. These are needed for fpdoc to do it’s work. They determine what elements are documented. See table (4.1)
2. Text structure and formartting tags. These tags indicate blocks of text, such as paragraphs, tables, lists and remarks, but also specify formatting: apply formatting (make-up) to the text, or to provide links to other parts of the text. These mostly occur in text structure tags. See table (4.2)

The nodes for formatting a text resemble closely the basic HTML formatting tags with the following exceptions:

• Each opening tag must have a corresponding closing tag.
• Tags are case sensitive.
• Tables and paragraphs are at the same level, i.e. a table cannot occur inside a paragraph. The same is true for all ’structural’ tags such as lists,

Also, if special formatting tags such as a table or lists are inserted, then the remaining text must be inside a paragraph tag. This means that the following is wrong:

CHAPTER 4. THE DESCRIPTION FILE

Table 4.1: Documentation structure tags Tag Description Page descr Element description 20 element Identifier documentation 22 errors Error section 22 fpdoc-description Global tag 22 module Unit tag 24 package Package global tab 25 seealso Cross-reference section 26 short Short description 26

Table 4.2: Text formatting tags Tag Description Page b Format bold 20 caption Specify table caption 20 code Syntax highlight code 20 dd definition data 21 dl definition list 21 dt Definition term 21 i format italics 22 li list element 23 link Cross-reference 23 ol numbered list 24 p paragraph 24 pre Preformatted text 25 remark remark paragraph 26 table Table 27 td Table cell 27 th Table header 28 tr Table row 28 u format underlined 28 ul bulleted list 29 var format as variable 29

Some beginning text

1. A list item

some ending text

Instead, the correct XML should be

Some beginning text

1. A list item

some ending text