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 ().
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:
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).
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>
Example:
Normal text <b>Bold text</b> normal text.will be formatted as:
Example
<table> <caption>This caption will end up above the table</caption> <th><td>Column 1</td><td>Column 2</td></th> </table>
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>
Example:
<element name="MyEnym"> <descr>Myenum is a simple enumeration type</descr> </element>
See also: element (), short (
), errors (
), seealso (
)
Example:
<dl> <dt>FPC</dt><dd>stands for Free Pascal Compiler.</dd> </dl>Will be typeset as
See also: dl (), dt (
), ol (
), ul (
)
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
See also: dt (), dd (
), ol (
), ul (
)
Example:
<dl> <dt>FPC</dt><dd>stands for Free Pascal Compiler.</dd> </dl>Will be typeset as
See also: dl (), dd (
), ol (
), ul (
)
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 (
)
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 (
)
Example:
Normal text <i>italic text</i> normal text.will be formatted as:
Example:
<ul> <li>First item in the list</li> <li>Second item in the list</li> </ul>Will be typeset as
<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
).
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 (
)
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
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 (
)
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 (
)
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...
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 (
)
Example:
<seealso> <link id="TStrings"/> <link id="TStringList.Create">Create</link> </seealso>
Example:
<element name="MyEnum.meOne"> <short>First element of MyEnum</short> </element>
See also: element (), descr (
)
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 (
)
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 (
)
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) |
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 (
)
Example:
Normal text <u>underlined text</u> normal text.will be formatted as:
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
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 (
)