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

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

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