[Ericsson AB]

3 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:

The differences between the DTDs are the tags for the name, the short summary and some tags inside the "formal" definitions.

3.1 The application DTD

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>
    

3.2 The appref DTD

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.

3.2.1 <appref>

Contains <header>, <app>, <appsummary>, <description>, zero or more <section> and <funcs>, followed by <authors>.

3.2.2 <app>

The application name as plain text.

3.2.3 <appsummary>

Short summary as plain text.

3.3 The comref DTD

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>
    

3.3.1 <comref>

Contains <header>, <com>, <comsummary>, <description>, zero or more <section> and <funcs>, followed by <authors>.

3.3.2 <com>

The command name as plain text.

3.3.3 <comsummary>

Short summary as plain text.

3.4 The cref DTD

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>
    

3.4.1 <cref>

Contains <header>, <lib>, <libsummary>, <description>, zero or more <section> and <funcs>, followed by <authors>.

3.4.2 <lib>

The C library name or acronym as plain text.

3.4.3 <libsummary>

Short summary as plain text.

3.5 The erlref DTD

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>
    

3.5.1 <erlref>

Contains <header>, <module>, <modulesummary>, <description>, zero or more <section> and <funcs>, followed by <authors>.

3.5.2 <module>

The module name as plain text.

3.5.3 <modulesummary>

Short summary as plain text.

3.6 The fileref DTD

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.

3.6.1 <fileref>

Contains <header>, <file>, <filesummary>, <description>, zero or more <section> and <funcs>, followed by <authors>.

3.6.2 <file>

The file name as plain text.

3.6.3 <filesummary>

Short summary as plain text.

3.7 <description>

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

3.8 <section>

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

3.9 <funcs>

Contains one or more <func>.

3.10 <func>

Contains one or more <name>, followed by <fsummary>, <type> (optional) and <desc> (optional).

3.11 <name>

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.

3.12 <fsummary>

Function/command summary as plain text, <func> and <func>.

3.13 <type>

One or more pairs of <v> and <d> (optional).

3.14 <v>

Type definition for an argument or return value as plain text.

3.15 <d>

Description of an argument or return value as plain text, <func> and <func>.

3.16 <desc>

Function/command description, contains <func> except <image> and <table>.

3.17 <authors>

One or more pairs of <aname> and <email> (optional).

3.18 <aname>

Author name as plain text.

3.19 <email>

Author email address as plain text.


docbuilder 0.9
Copyright © 1991-2007 Ericsson AB