Subsections


4 The description file

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 W3 (World Wide Web) consortium: http://www.w3.org/

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

The minimal documentation file would look something like this:

<?xml version="1.0" encoding="ISO8859-1"?>
<fpdoc-descriptions>
<package name="fpc">
<module name="Classes">
</module>
</fpdoc-description>
</package>
The header xml tag is mandatory, and indicates that the file contains a documentation XML document.

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.

<module name="CRT">
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.

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:
<element name="myenum">
</element>
But also for each of the three enumerated values an element tag should exist:
<element name="myenum.meOne">
</element>
<element name="myenum.meTwo">
</element>
<element name="myenum.meThree">
</element>
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:

<element name="myenum">
<descr>
The MyEnum type is a simple enumeration type which is not
really useful, except for demonstration purposes.
</descr>
</element>

A second important tag is the short tag. It should contain a short description of the identifier, preferably 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:

<element name="myenum.meOne">
<short>The first enumeration value</short>
</element>
<element name="myenum.meTwo">
<short>The second enumeration value</short>
</element>
<element name="myenum.meThree">
<short>The third enumeration value</short>
</element>
This will be converted to a table looking more or less like this:

meOne The first enumeration value
meTwo The second enumeration value
meThree The third enumeration value

For functions and procedures, a list of possible error conditions can be documented inside a errors tag. This tag is equivalent to the descr tag, but is placed under a different heading in the generated documentation.

Finally, to cross-reference between related functions, types or classes, a seealso tag is also introduced. This will be used to lay out a series of links to related information. This tag can only have sub-tags which are link tags. For more about the link tag, see link ([*]).

2 Element names and cross-referencing

1 Element name conventions

As mentioned in the previous section, the element tag's name attribute is hierarchical. All levels in the hierarchy are denoted by a dot (.) in the name attribute.

As shown in the previous example, for an enumerated type, the various enumeration constants can be documented by specifying their name as enumname.constname. For example, given the type

Type
  MyEnum = (meOne,meTwo,meThree);
The various enumeration values can be documented using the element names MyEnum.meOne, MyEnum.meTwo and MyEnum.meThree:
<element name="myenum.meOne">
</element>
<element name="myenum.meTwo">
</element>
<element name="myenum.meThree">
</element>
Note that the casing of the name attribute need not be the same as the casing of the declaration.

This hierarchical structure can be used for all non-simple types:

2 Cross referencing: the link tag

To refer to another point in the documentation (a related function, class or whatever), a link tag exists. The link tag takes as a sole attribute a target id attribute. The link tag usually encloses a piece of 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 <link id="MyEnum">MyEnum</link> type is a simple type.

The link attribute also has a short form:

The <link id="MyEnum"/> 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:

<link id="myunit.myenum"/>
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 (#):

<link id="#fcl.classes.sofrombeginning"/>
will link to the constant sofrombeginning in the classes unit of the FCL reference documentation. 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).

3 Tag reference

1 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 (structtags)
  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 (formattags)


Table: Documentation structure tags



Table: Text formatting tags


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

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:

<descr>
Some beginning text
<ol>
<li>A list item</li>
</ol>
some ending text
</descr>
Instead, the correct XML should be
<descr>
<p>Some beginning text</p>
<ol>
<li>A list item</li>
</ol>
<p>some ending text</p>
</descr>


2 b : format bold

This tag will cause the text inside it to be formatted using a bold font.

Example:

Normal text <b>Bold text</b> normal text.
will be formatted as:
Normal text Bold text normal text.

See also: i ([*]), u ([*]).


3 caption : Specify table caption

This tag can occur inside a table tag and serves to set the table caption.

Example

<table>
<caption>This caption will end up above the table</caption>
<th><td>Column 1</td><td>Column 2</td></th>
</table>

See also: table ([*])


4 code : format as pascal code

The code tag serves to insert Pascal code into the text. When possible this code will be highlighted in the output. It can be used to put highlighted Pascal code in the documentation of some identifier. It can occur inside descr or errors tags.

Note that any text surrounding the code tag should be placed in paragraph tags p.

Example:

<code>
With Strings do
  For i:=Count-1 downto 0 do
    Delete(i);
</code>

Seealso: pre ([*]), p ([*])


5 descr : Descriptions

This is the actual documentation tag. The contents of this tag will be written as the documentation of the element. It can contain any mixture of text and markup tags. The descr tag can only occur inside a element or module.

Example:

<element name="MyEnym">
<descr>Myenum is a simple enumeration type</descr>
</element>

See also: element ([*]), short ([*]), errors ([*]), seealso ([*])


6 dd : definition data.

The dd tag is used to denote the definition of a term in a definition list. It can occur only inside a definition list tag (dl), after a definition term (dt) tag. It's usage is identical to the one in HTML.

Example:

<dl>
<dt>FPC</dt><dd>stands for Free Pascal Compiler.</dd>
</dl>
Will be typeset as
FPC
stands for Free Pascal Compiler.

See also: dl ([*]), dt ([*]), ol ([*]), ul ([*])


7 dl : definition list.

Definition lists are meant to type a set of terms together with their explanation. It's usage is identical to the one in HTML, with the exception that it cannot occur inside ordinary text: surrounding text should always be enclosed in paragraph tags.

Example:

<dl>
<dt>meOne</dt><dd>First element of the enumeration type.</dd>
<dt>meTwo</dt><dd>Second element of the enumeration type.</dd>
<dt>meThree</dt><dd>Thir element of the enumeration type.</dd>
</dl>
Will be typeset as
meOne
First element of the enumeration type.
meTwo
Second element of the enumeration type.
meThree
Third element of the enumeration type.

See also: dt ([*]), dd ([*]), ol ([*]), ul ([*])


8 dt : definition term.

The dt tag is used in definition lists to enclose the term for which a definition is presented. It's usage is identical to the usage in HTML.

Example:

<dl>
<dt>FPC</dt><dd>stands for Free Pascal Compiler.</dd>
</dl>
Will be typeset as
FPC
stands for Free Pascal Compiler.

See also: dl ([*]), dd ([*]), ol ([*]), ul ([*])


9 element : Identifier documentation

The element contains the documentation for an identifier in a unit. It should occur inside a module tag. It can contain 4 tags:
short
For a one-line description of the identifier. Is used as a header or is used in overviews of constants, types, variables or classes.
descr
Contains the actual description of the identifier.
errors
For functions an procedures this can be used to describe error conditions. It will be put in a separate section below the description section.
seealso
Used to refer to other nodes. will be typeset in a separate section.

The element tag should have at least the name attribute, it is used to link the element node to the actual identifier in the Pascal unit. Other attributes may be added in future.

Example:

<element name="MyEnym">
<descr>Myenum is a simple enumeration type</descr>
</element>

See also: descr ([*]), short ([*]), errors ([*]), seealso ([*])


10 errors : Error section.

The errors tag is used to document any errors that can occur when calling a function or procedure. it is placed in a different section in the generated documentation. It occurs inside a element tag, at the same level as a descr or short tag. It's contents can be any text or formatting tag.

Example:

<element name="MyDangerousFunction">
<descr>MyDangerousFunction is a dangerous function</descr>
<errors>When MyDangerousFunction fails, all is lost</errors>
</element>

See also: descr ([*]), short ([*]), element ([*]), seealso ([*])


11 fpdoc-description : Global tag

The fpdoc-description tag is the topmost tag in a description file. It contains a series of package tags, one for each package that is described in the file.

See also: package ([*])


12 i : Format italics

The i tag will cause its contents to be typeset in italics. It can occur mixed with any text.

Example:

Normal text <i>italic text</i> normal text.
will be formatted as:
Normal text italic text normal text.

See also: b ([*]), u ([*])


13 li : list element

The tag li denotes an element in a ol or ul list. The usage is the same as for it's HTML counterpart: It can occur only inside one of the ol or ul list tags. It's contents may be arbitrary text and formatting tags, contrary to HTML tags, the li tag always must have a closing tag. Note that it cannot be used in a definition list (dl ([*])).

Example:

<ul>
<li>First item in the list</li>
<li>Second item in the list</li>
</ul>
Will be typeset as

See also: ol ([*]), ul ([*]).


14 link : Cross-reference

The link tag is used to insert a reference to an element inside some piece of text or inside the seealso section. It is similar in functionality to the
<A HREF="SomeAnchor">some linked text</A>
construct in HTML.

The mandatory id attribute of the link tag should have the name of an element tag in it. This name is not case sensitive. FPDOC will issue a warning if it cannot find a matching name. It will look for matching names in the current file, and in all content files that have been specified with the import command-line option.

The link tag can exist in 2 forms: one with separate closing tag, surrounding a piece of text, one without separate closing tag. If a piece of text is surrounded by the link tag, then the text will be converted to a hyperlink in the HTML documentation. If there is no surrounded text, then the value of the id attribute will be used as the text. This means that

<link id="TStream">TStream</link>
and
<link id="TStream"/>
are completely equivalent.

Example:

The <link id="TStringlist">stringlist</link> class is a descendent of the
<link id="TStrings"/> class.

See also: element ([*]), the import option (section [*], page [*]).


15 module : Unit reference

The module tag encloses all element tags for a unit. It can contain only element tags for all identifiers in the unit and a descr tag describing the unit itself. The module tag should occur inside a package tag.

The name attribute should have as a value the name of the unit which is described by the module. This name is not case sensitive.

Example:

<module name="classes">
<descr>
The classes unit contains basic class definitions for the FCL.
</descr>
</module>

See also: package ([*]), descr ([*]), element ([*])


16 ol : Numbered list.

The ol tag starts a numbered list. It can contain only li ([*]) tags, which denote the various elements in the list. Each item will be preceded by a number. The ol tag can occur inside a text, but surrounding text should always be enclosed in a p ([*]) paragraph tag, i.e. an ol tag should occur always at the same level as a p tag.

Example:

<p> some text before</p>
<ol>
<li>First item in the list</li>
<li>Second item in the list</li>
</ol>
Will be typeset as:

some text before

  1. First item in the list.
  2. Second item in the list.

See also: li ([*]), ul ([*]).


17 p : Paragraph

The p tag is the paragraph tag. Every description text should be enclosed in a p tag. Only when there is only one paragraph (and no lists or tables or remarks) in a description node, then the p tag may be skipped.

Note that if a description node contains a table, pre, code or any list tag, then the text surrounding these tags must be put inside a p paragraph tag. This is different from the behaviour in HTML.

The paragraph tag must always have an opening tag and a closing tag, unlike html where only the opening tag may be present.

Example:

<descr>
This is a paragraph which need not be surrounded by paragraph tags.
</descr>
<descr>
<p>
This is the first paragraph.
</p>
<p>
This is the second paragraph.
</p>
</descr>

See also: table ([*]), dl ([*]), remark ([*]),code ([*]), ol ([*]),ul ([*]),ol ([*])


18 package : Package reference

The package tag indicates the package for which the description file contains documentation. A package is a collection of units which are logically grouped together (for a library, program, component suites). The name attribute of the package tag will be used to select the package node in the description file: Only the package node with name as specified by the package command-line option will be used when generating documentation. All other package nodes will be ignored.

The package node must always reside in a fpdoc-description node. It can contain a descr node, and various module nodes, one node per unit in the package.

See also: fpdocdescription ([*]), module ([*]), descr ([*])


19 pre : Insert text as-is

The pre tag can be used to insert arbitrary text in the documentation. The text will not be formatted in any way, and will be displayed as it is encountered in the description node. It is functionally equivalent to the pre tag in HTML.

Note that if there is text surrounding the pre tag, it should be placed inside a p paragraph tag.

Example:

<pre>
This is some text.
  This is some more text

    And yet more text...
</pre>
This will be typeset as:
This is some text.
  This is some more text

    And yet more text...

See also: code ([*]), p ([*])


20 remark : format as remark

A remark tag can be used to make a paragraph stand out. The remark is equivalent to the p tag, but it's contents is formatted in a way that makes it stand out from the rest of the text.

Note that any text before or after the remark tag must be enclosed in paragraph (p) tags.

Example:

<p>Normal text.</p>
<remark>
This text will stand out.
<example>
<p>Again normal text.</p>
Will be formatted as

Normal text.

Remark: This text will stand out.

Again normal text.

See also: p ([*]), code ([*]), pre ([*])


21 seealso : Cross-reference section

The seealso section can occur inside any element tag, and will be used to create a list of cross-references. The contents of the seealso tag is a list of link tags. No other text is allowed inside this tag. Note that both the long and short form if the link tag may be used.

Example:

<seealso>
<link id="TStrings"/>
<link id="TStringList.Create">Create</link>
</seealso>

See also: link ([*]), element ([*])


22 short : Short description

The short description is used to give a short description of an identifier. If possible, the description should fit on a single line of text. The contents of this tag will be used for the following purposes:

Example:

<element name="MyEnum.meOne">
<short>First element of MyEnum</short>
</element>

See also: element ([*]), descr ([*])


23 table : Table start

The table tag starts a table, as in HTML. A table can contain tr (table row), th (table header row) or caption tags. Any text surrounding the table must be enclosed in paragraph tags (p).

Example:

<table>
<caption>
<var>TALignment</var> values and their meanings.
</caption>
<th><td>Value</td><td>Meaning</td></th>
<tr>
  <td><var>taLeftJustify</var></td>
  <td>Text is displayed aligned to the left.</td>
</tr>
<tr>
  <td><var>taRightJustify</var></td>
  <td>Text is displayed aligned to the right</td>
</tr>
<tr>
  <td><var>taCenter</var></td>
  <td>Text is displayed centred.</td>
</tr>
</table>
Will be formatted approximately as follows:

Value Meaning
taLeftJustify Text is displayed aligned to the left.
taRightJustify Text is displayed aligned to the right
taCenter Text is displayed centred.

See also: th ([*]), caption ([*]), tr ([*]), p ([*])


24 td : Table cell

The td tag is used to denote one cell in a table. It occurs inside a tr or th tag, and can contain any text and formatting tags.

Example:

<table>
<tr><td>Cell (1,1)</td><td>Cell (2,1)</td></tr>
<tr><td>Cell (1,2)</td><td>Cell (2,2)</td></tr>
</table>
Will be formatted approximately as

Cell (1,1) Cell (2,1)
Cell (1,2) Cell (2,2)

See also: table ([*]), th ([*]), tr ([*])


25 th : Table header

The th table header tag is used to denote the first row(s) of a table: It (they) will be made up differently from the other rows in the table. Exactly how it is made up depends on the format. In printed documentation (latex) a line will be drawn under the row. In HTML, the font and background may be formatted differently.

The th tag can only occur inside a table tag, and can contain only td tags.

Example:

<table>
<th><td>Cell (1,1)</td><td>Cell (2,1)</td></th>
<tr><td>Cell (1,2)</td><td>Cell (2,2)</td></tr>
</table>
Will be formatted approximately as

Cell (1,1) Cell (2,1)
Cell (1,2) Cell (2,2)

See also: tr ([*]), table ([*])


26 tr : table row

The tr tag denotes a row in a table. It works the same as in HTML. It can occur only in a table tag, and should contain only td table data tags.

Example:

<table>
<tr><td>Cell (1,1)</td><td>Cell (2,1)</td></tr>
<tr><td>Cell (1,2)</td><td>Cell (2,2)</td></tr>
</table>
Will be formatted approximately as

Cell (1,1) Cell (2,1)
Cell (1,2) Cell (2,2)

See also: table ([*]), th ([*]), td ([*])


27 u : Format underlined

Example:

Normal text <u>underlined text</u> normal text.
will be formatted as:
Normal text underlined text normal text.

See also: i ([*]), b ([*]).


28 ul : bulleted list

The ul tag starts a bulleted list. This works as under HTML, with the exception that any text surrounding the list must be enclosed in paragraph tags (p). The list elements should be enclosed in li tags.

Example:

<p> some text before</p>
<ol>
<li>First item in the list</li>
<li>Second item in the list</li>
</ol>
Will be typeset as:

some text before

See also: li ([*]), ol ([*]).


29 var : variable

The var tag is used to mark a piece of text as a variable (or, more general, as an identifier). It will be typeset differently from the surrounding text. Exactly how this is done depends on the output format.

Example:

The <var>Items</var> property gives indexed access to...
Will be typeset as

The Items property gives indexed access to...

See also: b ([*]), u ([*]), i ([*]), code ([*])




2004-02-13