4 参考手册 DTD

有五个 DTD 用于编写关于应用程序、shell 命令、C 库、Erlang 模块和文件的联机帮助页，它们都具有类似的结构

一个头部。
应用程序/命令/库/模块/文件的名称。
简短摘要（一行）。
更长的描述。
函数或命令的“正式”定义。
可选的自由文本部分。
可选部分，包含作者的姓名和电子邮件。

DTD 之间的差异在于用于名称、简短摘要以及“正式”定义内的一些标签。

4.1 应用程序 DTD

application DTD 用于参考手册，并将一组联机帮助页分组为一个单元。结构类似于部分 DTD：首先是介绍，然后是联机帮助页，它们分别用 appref、comref、cref、erlref 或 fileref DTD 编写。

示例

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

4.2 <application>

application DTD 的顶层标签。

包含 <header>、可选的 <description>，然后是一个或多个 <include>。

4.3 appref DTD

这是用于编写应用程序联机帮助页的 DTD。

示例

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

<appref>

appref DTD 的顶层标签。

包含 <header>、<app>、<appsummary>、<description>、零个或多个 <section> 和 <funcs>，然后是零个或多个 <authors>。

<app>

应用程序名称。包含纯文本。

<appsummary>

简短摘要。包含纯文本。

4.4 comref DTD

这是用于编写命令联机帮助页的 DTD。

示例

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

<comref>

comref DTD 的顶层标签。

包含 <header>、<com>、<comsummary>、<description>、零个或多个 <section> 和 <funcs>，然后是零个或多个 <authors>。

<com>

命令名称。包含纯文本。

<comsummary>

简短摘要。包含纯文本。

4.5 cref DTD

这是用于编写 C 库联机帮助页的 DTD。

示例

<?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 ghlink="maint/lib/erl_docgen/doc/src/refman_dtds.xml#L285">
    <p>A longer description of the C library.</p>
  </description>
  
  <funcs>
    <func ghlink="maint/lib/erl_docgen/doc/src/refman_dtds.xml#L290">
      <name><ret>void</ret><nametext>start(bar)</nametext></name>
      <name><ret>void</ret><nametext>start(foo)</nametext></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 ghlink="maint/lib/erl_docgen/doc/src/refman_dtds.xml#L306">
    <title>A title</title>

    <p>Some text...</p>
  </section>
  
  
</cref>

<cref>

cref DTD 的顶层标签。

包含 <header>、<lib>、<libsummary>、<description>、零个或多个 <section> 和 <funcs>，然后是零个或多个 <authors>。

<lib>

C 库名称或缩写。包含纯文本。

<libsummary>

简短摘要。包含纯文本。

4.6 erlref DTD

这是用于编写 Erlang 模块联机帮助页的 DTD。

示例

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

<erlref>

erlref DTD 的顶层标签。

包含 <header>、<module>、<modulesummary>、<description>、零个或多个 <section> 和 <funcs>，然后是零个或多个 <authors>。

<module>

模块名称。包含纯文本。

<modulesummary>

简短摘要。包含纯文本。

4.7 fileref DTD

这是用于编写文件联机帮助页的 DTD。在 OTP 中，此 DTD 用于定义例如 .rel 和 .app 文件的格式。

示例

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

文件参考手册也可以包含函数定义，类似于 erlref DTD。

<fileref>

fileref DTD 的顶层标签。

包含 <header>、<file>、<filesummary>、<description>、零个或多个 <section> 和 <funcs>，然后是零个或多个 <authors>。

<file>

文件或文件类型的名称。包含纯文本。

<filesummary>

简短摘要。包含纯文本。

4.8 <description>

标题之后、部分和“正式”定义之前的介绍。

包含除 <image> 和 <table> 以外的任何组合和任何数量的块标签。

4.9 <section>

文档的细分。包含一个可选的 <marker>、一个 <title>，然后是除 <image> 和 <table> 以外的任何组合和任何数量的块标签。

4.10 <funcs>

一组“正式”函数定义。

包含一个或多个 <func>。

4.11 <func>

一个“正式”函数定义。

包含一个或多个 <name>，然后是 <fsummary>、<type>（可选）和 <desc>（可选）。

4.12 <name>

函数/命令签名，包含名称、参数和返回值。包含纯文本，除了 cref DTD，它包含 <ret>（返回值类型，纯文本）和 <nametext>（函数名称和参数，纯文本）。

在 erlref DTD 的情况下，将在函数定义之前自动添加一个标记，<marker id="Name/Arity"> 或 <marker id="Name">，它基于此标签内容生成函数定义之前的标记。

示例：考虑以下名称定义

<name>foo(Arg1, Arg2) -> ok | {error, Reason}</name>

然后，在生成的 HTML 中，将在函数定义之前添加如下标记 <marker id="foo/2">。也就是说，使用 <seemfa marker="#foo/2">foo/2</seemfa> 引用函数将自动起作用。

4.13 <fsummary>

函数/命令摘要。包含纯文本、<c> 和 <em>。

4.14 <type>

函数/命令的类型声明。

包含一个或多个 <v> 和 <d>（可选）对。

4.15 <v>

参数或返回值的类型声明。包含纯文本。

4.16 <d>

参数或返回值的描述。包含纯文本、<c> 和 <em>。

4.17 <desc>

函数/命令描述。包含块标签，但不包含 <image> 和 <table>。

4.18 <authors>

联机帮助页的作者。authors 元素是可选的。

包含一个或多个 <aname> 和 <email> 对。

4.19 <aname>

作者姓名。包含纯文本。

4.20 <email>

作者电子邮件地址。包含纯文本。