There are five DTDs for writing manual pages about applications, shell commands, C libraries, Erlang modules and files, all with a similar structure:
The differences between the DTDs are the tags for the name, the short summary and some tags inside the "formal" definitions.
The application
DTD groups a set of manual pages into one
unit. An application can consist of some Erlang modules and some C
functions or libraries, each with there own manual page.
The structure is similar to the part DTD: first a description of
the application, then a list of files with the actual manual pages
to include.
An example of an application:
<?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>
This is the DTD for writing an application manual page.
An 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>
The application reference manual can also contain function
definitions, similar to the erlref
DTD.
Contains <header>, <app>, <appsummary>, <description>, zero or more <section> and <funcs>, followed by <authors>.
The application name as plain text.
This is the DTD for writing a command manual page.
An 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>
Contains <header>, <com>, <comsummary>, <description>, zero or more <section> and <funcs>, followed by <authors>.
The command name as plain text.
This is the DTD for writing a C library manual page.
An 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> <p>A longer description of the C library.</p> </description> <funcs> <func> <name><ret>void</ret> start(bar)</name> <name><ret>void</ret> start(foo)</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> <title>A title</title> <p>Some text...</p> </section> <authors> <aname>Name of author</aname> <email>Email of author</email> </authors> </cref>
Contains <header>, <lib>, <libsummary>, <description>, zero or more <section> and <funcs>, followed by <authors>.
The C library name or acronym as plain text.
This is the DTD for writing Erlang module manual pages.
An 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>
Contains <header>, <module>, <modulesummary>, <description>, zero or more <section> and <funcs>, followed by <authors>.
The module name as plain text.
This is the DTD for writing file manual pages. In OTP, this DTD
is used for defining the format of .rel
and .app
files, for example.
An 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.
Contains <header>, <file>, <filesummary>, <description>, zero or more <section> and <funcs>, followed by <authors>.
The introduction after the title and before sections and "formal" definitions.
Can contain any combination and any number of
block tags except
<image>
and <table>
.
Subdivisions of the document. Contains an optional
<marker>,
a title <title>
containing plain text,
followed by any combination and any number of
block tags except
<image>
and <table>
.
Contains one or more <func>.
Contains one or more <name>, followed by <fsummary>, <type> (optional) and <desc> (optional).
Function/command name, arguments and return value as plain text.
In the case of an erlref
or cref
DTD, DocBuilder
will automatically try to add a
<marker>Name/Arity
or Name
based on the contents of this tag
before the function definition. Example: For the following
name definition
<name>foo(Arg1, Arg2) -> ok | {error, Reason}</name>
DocBuilder will create a marker 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.
Function/command summary as plain text, <func> and <func>.
One or more pairs of <v> and <d> (optional).
Type definition for an argument or return value as plain text.
Description of an argument or return value as plain text, <func> and <func>.
Function/command description, contains
<func> except
<image>
and <table>
.
One or more pairs of <aname> and <email> (optional).
Author email address as plain text.