4 Reference Manual DTDs
There are five DTDs for writing manual pages about applications, shell commands, C libraries, Erlang modules and files, all with a similar structure:
- A header.
- Name of the application/command/library/module/file.
- Short summary (one line).
- A longer description.
- "Formal" definitions of functions or commands.
- Optional sections of free text.
- Optional section with the name(s) and email(s) of the author(s).
The differences between the DTDs are the tags for the name, the short summary and some tags inside the "formal" definitions.
4.1 The application DTD
The application DTD is intended for a Reference Manual and groups a set of manual pages into one unit. The structure is similar to the part DTD: first an introduction and then the manual pages, written in separate files with the appref, comref, cref, erlref, or fileref DTD.
Example:
<?xml version="1.0" encoding="latin1" ?>
<!DOCTYPE application SYSTEM "application.dtd">
<application>
<header>
<title>Application name</title>
<prepared/>
<docno/>
<date/>
<rev/>
</header>
<description>
<p>Application description...</p>
</description>
<include file="module1">
<include file="module2">
</application>
4.2 <application>
The top level tag of an application DTD.
Contains a <header>, an optional <description>, followed by one or more <include>.
4.3 The appref DTD
This is the DTD for writing an application manual page.
Example:
<?xml version="1.0" encoding="latin1" ?>
<!DOCTYPE appref SYSTEM "appref.dtd">
<appref>
<header>
<title>Application name</title>
<prepared/>
<docno/>
<date/>
<rev/>
</header>
<app>Application name</app>
<appsummary>A short application summary.</appsummary>
<description>
<p>A longer description of the application.</p>
</description>
<section>
<title>Configuration</title>
<p>...</p>
</section>
...
<authors>
<aname>Name of author</aname>
<email>Email of author</email>
</authors>
</appref>
<appref>
The top level tag of an appref DTD.
Contains <header>, <app>, <appsummary>, <description>, zero or more <section> and <funcs>, followed by zero or more <authors>.
<app>
The application name. Contains plain text.
<appsummary>
Short summary. Contains plain text.
4.4 The comref DTD
This is the DTD for writing a command manual page.
Example:
<?xml version="1.0" encoding="latin1" ?>
<!DOCTYPE comref SYSTEM "comref.dtd">
<comref>
<header>
<title>Command name</title>
<prepared/>
<docno/>
<date/>
<rev/>
</header>
<com>Command name</com>
<comsummary>A short command summary.</comsummary>
<description>
<p>A long description of the command.</p>
</description>
<funcs>
<func>
<name>command</name>
<name>command -flag <arg></name>
<fsummary>A short command summary (max 40 characters).</fsummary>
<desc>
<p>An extended command description.
</desc>
</func>
</funcs>
<section>
<title>Options</title>
<p>...</p>
</section>
<authors>
<aname>Name of author</aname>
<email>Email of author</email>
</authors>
</comref>
<comref>
The top level tag for a comref DTD.
Contains <header>, <com>, <comsummary>, <description>, zero or more <section> and <funcs>, followed by zero or more <authors>.
<com>
The command name. Contains plain text.
<comsummary>
Short summary. Contains plain text.
4.5 The cref DTD
This is the DTD for writing a C library manual page.
Example:
<?xml version="1.0" encoding="latin1" ?>
<!DOCTYPE cref SYSTEM "cref.dtd">
<cref>
<header>
<title>C library name</title>
<prepared/>
<docno/>
<date/>
<rev/>
</header>
<lib>C library name</lib>
<libsummary>A short C library summary.</libsummary>
<description ghlink="maint/lib/erl_docgen/doc/src/refman_dtds.xml#L285">
<p>A longer description of the C library.</p>
</description>
<funcs>
<func ghlink="maint/lib/erl_docgen/doc/src/refman_dtds.xml#L290">
<name><ret>void</ret><nametext>start(bar)</nametext></name>
<name><ret>void</ret><nametext>start(foo)</nametext></name>
<fsummary>A short function summary (max 40 characters).</fsummary>
<type>
<v>char bar</v>
<v>int foo</v>
</type>
<desc>
<p>An extended function description.</p>
</desc>
</func>
...
</funcs>
<section ghlink="maint/lib/erl_docgen/doc/src/refman_dtds.xml#L306">
<title>A title</title>
<p>Some text...</p>
</section>
</cref>
<cref>
The top level tag for a cref DTD.
Contains <header>, <lib>, <libsummary>, <description>, zero or more <section> and <funcs>, followed by zero or more <authors>.
<lib>
The C library name or acronym. Contains plain text.
<libsummary>
Short summary. Contains plain text.
4.6 The erlref DTD
This is the DTD for writing Erlang module manual pages.
Example:
<?xml version="1.0" encoding="latin1" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">
<erlref>
<header>
<title>Module name</title>
<prepared/>
<docno/>
<date/>
<rev/>
</header>
<module>Module name</module>
<modulesummary>A short module summary.</modulesummary>
<description>
<p>A longer description of the module.</p>
</description>
<funcs>
<func>
<name>start() -> Result</name>
<name>start(N) -> Result</name>
<fsummary>A short function summary (max 40 characters).</fsummary>
<type>
<v>Pid = pid()</v>
<v>N = int()</v>
<v>Result = {ok, Pid} | {error, Reason}</v>
<v>Reason = term()</v>
<d>A parameter description.</d>
</type>
<desc>
<p>An extended function description.</p>
</desc>
</func>
...
</funcs>
<section>
<title>Some Title</title>
<p>Some text...</p>
</section>
<authors>
<aname>Name of author</aname>
<email>Email of author</email>
</authors>
</erlref>
<erlref>
The top level tag for an erlref DTD.
Contains <header>, <module>, <modulesummary>, <description>, zero or more <section> and <funcs>, followed by zero or more <authors>.
<module>
The module name. Contains plain text.
<modulesummary>
Short summary. Contains plain text.
4.7 The fileref DTD
This is the DTD for writing file manual pages. In OTP, this DTD is used for defining the format of for example .rel and .app files.
Example:
<?xml version="1.0" encoding="latin1" ?>
<!DOCTYPE fileref SYSTEM "fileref.dtd">
<fileref>
<header>
<title>File name</title>
<prepared/>
<docno/>
<date/>
<rev/>
</header>
<file>fileref</file>
<filesummary>A short file summary.</filesummary>
<description>
<p>A longer description of the file.</p>
</description>
<section>
<title>File format</title>
<p>...</p>
</section>
<authors>
<aname>Name of author</aname>
<email>Email of author</email>
</authors>
</fileref>
The file reference manual can also contain function definitions, similar to the erlref DTD.
<fileref>
The top level tag for a fileref DTD.
Contains <header>, <file>, <filesummary>, <description>, zero or more <section> and <funcs>, followed by zero or more <authors>.
<file>
The name of the file or file type. Contains plain text.
<filesummary>
Short summary. Contains plain text.
4.8 <description>
The introduction after the title and before sections and "formal" definitions.
Contains any combination and any number of block tags except <image> and <table>.
4.9 <section>
Subdivisions of the document. Contains an optional <marker>, a <title>, followed by any combination and any number of block tags except <image> and <table>.
4.10 <funcs>
A group of "formal" function definitions.
Contains one or more <func>.
4.11 <func>
A "formal" function definition.
Contains one or more <name>, followed by <fsummary>, <type> (optional) and <desc> (optional).
4.12 <name>
Function/command signature with name, arguments and return value. Contains plain text, except for the cref DTD where it contains a <ret> (return type, plain text) and a <nametext> (function name and arguments, plain text).
In the case of an erlref DTD, it will automatically be added a marker, <marker id="Name/Arity"> or <marker id="Name">, based on the contents of this tag before the function definition.
Example: Consider the following name definition
<name>foo(Arg1, Arg2) -> ok | {error, Reason}</name>
Then a marker like this will be added <marker id="foo/2"> before the function definition in the generated HTML. That is, referring to the function using <seealso marker="#foo/2">foo/2</seealso> will automatically work.
4.13 <fsummary>
Function/command summary. Contains plain text, <c> and <em>.
4.14 <type>
Type declarations for the function/command.
Contains one or more pairs of <v> and <d> (optional).
4.15 <v>
Type declaration for an argument or return value. Contains plain text.
4.16 <d>
Description for an argument or return value. Contains plain text, <c> and <em>.
4.17 <desc>
Function/command description. Contains block tags except <image> and <table>.
4.18 <authors>
Authors of the manual page. The authors element is optional.
Contains one or more pairs of <aname> and <email>.
4.19 <aname>
Author name. Contains plain text.
4.20 <email>
Author email address. Contains plain text.