Reference Manual DTDs

19972009 Ericsson AB. All Rights Reserved. The contents of this file are subject to the Erlang Public License, Version 1.1, (the "License"); you may not use this file except in compliance with the License. You should have received a copy of the Erlang Public License along with this software. If not, it can be retrieved online at http://www.erlang.org/. Software distributed under the License is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the specific language governing rights and limitations under the License. Reference Manual DTDs refman_dtds.xml

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.

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>

The top level tag of an application DTD.

Contains a <header>, an optional <description>, followed by one or more <include>.

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>

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.

Short summary. Contains plain text.

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>

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.

Short summary. Contains plain text.

The cref DTD

This is the DTD for writing a C library manual page.

Example:




  
    C library name
    
    
    
    
  

  C library name

  A short C library summary.

  
    A longer description of the C library.
  
  
  
    
      voidstart(bar)
      voidstart(foo)
      A short function summary (max 40 characters).
      
        char bar
        int foo
      
      
        An extended function description.
      
    

    ...
  

  
    A title

    Some text...
  
  
  

    ]]>

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

Short summary. Contains plain text.

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>

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

The module name. Contains plain text.

Short summary. Contains plain text.

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.

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.

Short summary. Contains plain text.

The introduction after the title and before sections and "formal" definitions.

Contains any combination and any number of block tags except ]]> and ]]>.

Subdivisions of the document. Contains an optional <marker>, a <title>, followed by any combination and any number of block tags except ]]> and ]]>.

<funcs>

A group of "formal" function definitions.

Contains one or more <func>.

<func>

A "formal" function definition.

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

<name>

Function/command signature with name, arguments and return value. Contains plain text, except for the cref DTD where it contains a ]]> (return type, plain text) and a ]]> (function name and arguments, plain text).

In the case of an erlref DTD, DocBuilder will automatically try to add a marker, ]]> or ]]>, based on the contents of this tag before the function definition.

Example: Consider the following name definition

foo(Arg1, Arg2) -> ok | {error, Reason}
    ]]>

DocBuilder will create a marker ]]> before the function definition in the generated HTML. That is, referring to the function using foo/2]]> will automatically work.

Function/command summary. Contains plain text, <c> and <em>.

<type>

Type declarations for the function/command.

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

<v>

Type declaration for an argument or return value. Contains plain text.

<d>

Description for an argument or return value. Contains plain text, <c> and <em>.

<desc>

Function/command description. Contains block tags except <image> and <table>.

Authors of the manual page. The authors element is optional.

Contains one or more pairs of <aname> and <email>.

<aname>

Author name. Contains plain text.

<email>

Author email address. Contains plain text.