User's Guide
Reference Manual
Release Notes
PDF
Top

Erl_Docgen
User's Guide
Version 0.3.3

Expand All
Contract All

Chapters

- How to Build OTP like documentation
  - Top of chapter
  - Utilities to prepare XML files
  - Use xsltproc to generate different output formats
- Overview OTP DTDs
  - Top of chapter
  - DTD Suite
  - Basic Tags
- User's Guide DTDs
  - Top of chapter
  - The part DTD
  - <part>
  - <description>
  - <include>
  - The chapter DTD
  - <chapter>
  - <section>
  - <title>
- Reference Manual DTDs
  - Top of chapter
  - The application DTD
  - <application>
  - The appref DTD
  - The comref DTD
  - The cref DTD
  - The erlref DTD
  - The fileref DTD
  - <description>
  - <section>
  - <funcs>
  - <func>
  - <name>
  - <fsummary>
  - <type>
  - <v>
  - <d>
  - <desc>
  - <authors>
  - <aname>
  - <email>
- Header Tags
  - Top of chapter
  - <header>
  - <copyright>
  - <legalnotice>
  - <title>
  - <shorttitle>
  - <prepared>
  - <responsible>
  - <docno>
  - <approved>
  - <checked>
  - <date>
  - <rev>
  - <file>
- Block Tags
  - Top of chapter
  - <br> - Line Break
  - <code> - Code Example
  - <codeinclude> - Code Inclusion
  - <erleval> - Erlang Evaluation
  - <list> - List
  - <marker> - Marker
  - <p> - Paragraph
  - <note> - Note
  - <pre> - Pre-formatted Text
  - <quote> - Quotation
  - <taglist> - Definition List
  - <warning> - Warning
  - <image> - Image
  - <table> - Table
- Inline Tags
  - Top of chapter
  - <br> - Line Break
  - <c> - Code
  - <em> - Emphasis
  - <marker> - Marker
  - <seealso> - Local Cross Reference
  - <url> - Non-Local Cross Reference
  - <term>, <termdef> - Glossary
  - <cite>, <citedef> - Bibliography
- Character Entities
  - Top of chapter
  - Added Latin 1

# 6 Block Tags

Block tags typically define a separate block of information, such as a paragraph or a list.

The following subset of block tags are common for all DTDs in the OTP DTD suite: <p>, <pre>, <code>, <list>, <taglist>, <codeinclude> and <erleval>.

### 6.1 <br> - Line Break

Forces a newline. Example:

    Eat yourself<br/>senseless!

results in:

Eat yourself
senseless!

The <br> tag is both a block- and an inline tag.

### 6.2 <code> - Code Example

Highlight code examples. Example:

    <code>
    sum([H|T]) ->
        H + sum(T);
    sum([]) ->
        0.
    </code>

results in:

    sum([H|T]) ->
        H + sum(T);
    sum([]) ->
        0.

There is an attribute type = "erl" | "c" | "none", but currently this attribute is ignored. Default value is "none"

Note

No tags are allowed within the tag and no character entities are expanded.

### 6.3 <codeinclude> - Code Inclusion

Include external code snippets. The attribute file gives the file name and tag defines a string which delimits the code snippet. Example:

    <codeinclude file="example.txt" tag="%% Erlang example"/>

results in:

provided there is a file named examples.txt looking like this:

    ...

    %% Erlang example
    -module(example).

    start() ->
        {error,"Pid required!"}.
    start(Pid) ->
        spawn(fun() -> init(Pid) end).
    %% Erlang example

    ...

If the tag attribute is omitted, the whole file is included.

There is also an attribute type = "erl" | "c" | "none", but currently this attribute is ignored. Default value is "none"

### 6.4 <erleval> - Erlang Evaluation

Include the result from evaluating an Erlang expression. Example:

    <erleval expr="{A,b,C}={a,b,c}. "/>

results in:

Note the '.' and space after the expression.

### 6.5 <list> - List

The attribute type = "ordered"|"bulleted" decides if the list is numbered or bulleted. Default is "bulleted".

Lists contains list items, tag <item>, which can contain plain text, the common subset of block tags and inline tags. Example:

    <list type="ordered">
      <item>Askosal:
        <list>
          <item>Nullalisis</item>
          <item>Facilisis</item>
        </list>
      </item>
      <item>Ankara</item>
    </list>

results in:

- Askosal:

  - Nullalisis
  - Facilisis
- Ankara

### 6.6 <marker> - Marker

Used as an anchor for hypertext references. The <marker> tag is both a block- and an inline tag and is described in the Inline Tags section.

### 6.7 <p> - Paragraph

Paragraphs contain plain text and inline tags. Example:

    <p>I call specific attention to
      the authority given by the <em>21st Amendment</em>
      to the Constitution to prohibit transportation
      or importation of intoxicating liquors into
      any State in violation of the laws of such
      State.</p>

results in:

I call specific attention to the authority given by the 21st Amendment to the Constitution to prohibit transportation or importation of intoxicating liquors into any State in violation of the laws of such State.

### 6.8 <note> - Note

Highlights a note. Can contain block tags except <note>, <warning>, <image> and <table>. Example:

    <note>
      <p>This function is mainly intended for debugging.</p>
    </note>

results in:

Note

This function is mainly intended for debugging.

### 6.9 <pre> - Pre-formatted Text

Used for documentation of system interaction. Can contain text, seealso, url and <input> tags.

The <input> tag is used to highlight user input. Example:

    <pre>
    $ <input>erl</input>
    Erlang (BEAM) emulator version 5.5.3 [async-threads:0] [hipe] [kernel-poll:false]

    Eshell V5.5.3  (abort with ^G)
    1> <input>pwd().</input>
    /home/user
    2> <input>halt().</input>
    </pre>

results in:

    $ erl
    Erlang (BEAM) emulator version 5.5.3 [async-threads:0] [hipe] [kernel-poll:false]

    Eshell V5.5.3  (abort with ^G)
    1> pwd().
    /home/user
    2> halt().

All character entities are expanded.

### 6.10 <quote> - Quotation

Highlight quotations from other works, or dialog spoken by characters in a narrative. Contains one or more <p> tags. Example:

    <p>Whereas Section 217(a) of the Act of Congress entitled
    "An Act ..." approved June 16, 1933, provides as follows:</p>
    <quote>
      <p>Section 217(a) The President shall proclaim the law.</p>
    </quote>

results in:

Whereas Section 217(a) of the Act of Congress entitled "An Act ..." approved June 16, 1933, provides as follows:

Section 217(a) The President shall proclaim the law.

### 6.11 <taglist> - Definition List

Definition lists contains pairs of tags, <tag>, and list items, <item>.

<tag> can contain plain text, <c>, <em>, <seealso> and <url> tags.

<item> can contain plain text, the common subset of block tags and inline tags. Example:

    <taglist>
      <tag><c>eacces</c></tag>
      <item>Permission denied.</item>
      <tag><c>enoent</c></tag>
      <item>No such file or directory.</item>
    </taglist>

results in:

eacces
  Permission denied.
enoent
  No such file or directory.

### 6.12 <warning> - Warning

Highlights a warning. Can contain block tags except <note>, <warning>, <image> and <table>. Example:

    <warning>
      <p>This function might be removed in a future version without
        prior warning.</p>
    </warning>

results in:

Warning

This function might be removed in a future version without prior warning.

### 6.13 <image> - Image

Graphics is imported using the <image> tag. An image caption <icaption>, containing plain text, must be supplied. Example:

    <image file="man">
      <icaption>A Silly Man</icaption>
    </image>

results in:

Figure 6.1: A Silly Man

This assumes that man.gif exists in the current directory.

### 6.14 <table> - Table

The table format is similar to how tables are described in HTML 3.2. A table contains one or more rows, <row>, and a table caption <tcaption>, containing plain text.

Each row contains one or more cells, <cell>. The attributes align = "left"|"center"|"right" and valign = "top"|"middle"|"bottom" decides how text is aligned in the cell horizontally and vertically. Default is "left" and "middle".

Each cell contains plain text and inline tags. Example:

        <table>
          <row>
            <cell align="left" valign="top"><em>Boys</em></cell>
            <cell align="center" valign="middle"><em>Girls</em></cell>
          </row>
          <row>
            <cell align="left" valign="middle">Juda</cell>
            <cell align="right" valign="bottom">Susy</cell>
          </row>
          <row>
            <cell align="left" valign="middle">Anders</cell>
            <cell align="left" valign="middle">Victoria</cell>
          </row>
          <tcaption>A table caption</tcaption>
        </table>

results in:

Boys | Girls
Juda | Susy
Anders | Victoria

Table 6.1: A table caption