diff options
Diffstat (limited to 'lib/erl_docgen/doc/src/refman_dtds.xml')
| -rw-r--r-- | lib/erl_docgen/doc/src/refman_dtds.xml | 667 |
1 files changed, 667 insertions, 0 deletions
diff --git a/lib/erl_docgen/doc/src/refman_dtds.xml b/lib/erl_docgen/doc/src/refman_dtds.xml new file mode 100644 index 0000000000..7b01c57db4 --- /dev/null +++ b/lib/erl_docgen/doc/src/refman_dtds.xml @@ -0,0 +1,667 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>1997</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + 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. + + </legalnotice> + + <title>Reference Manual DTDs</title> + <prepared></prepared> + <docno></docno> + <date></date> + <rev></rev> + <file>refman_dtds.xml</file> + </header> + + <p>There are five DTDs for writing manual pages about applications, + shell commands, C libraries, Erlang modules and files, all with a + similar structure:</p> + + <list type="bulleted"> + <item>A header.</item> + <item>Name of the application/command/library/module/file.</item> + <item>Short summary (one line).</item> + <item>A longer description.</item> + <item>"Formal" definitions of functions or commands.</item> + <item>Optional sections of free text.</item> + <item>Optional section with the name(s) and email(s) of the author(s).</item> + </list> + + <p>The differences between the DTDs are the tags for the name, + the short summary and some tags inside the "formal" definitions.</p> + + <section> + <marker id="applicationDTD"></marker> + <title>The application DTD</title> + + <p>The <c>application</c> 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 + <seealso marker="#apprefDTD">appref</seealso>, + <seealso marker="#comrefDTD">comref</seealso>, + <seealso marker="#crefDTD">cref</seealso>, + <seealso marker="#erlrefDTD">erlref</seealso>, or + <seealso marker="#filerefDTD">fileref</seealso> DTD.</p> + + <p>Example:</p> + <pre> +<?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> + </pre> + </section> + + <section> + <marker id="applicationTAG"></marker> + <title><application></title> + + <p>The top level tag of an <c>application</c> DTD.</p> + + <p>Contains a + <seealso marker="header_tags"><header></seealso>, + an optional + <seealso marker="user_guide_dtds#descriptionTAG"><description></seealso>, + followed by one or more + <seealso marker="user_guide_dtds#includeTAG"><include></seealso>. + </p> + </section> + + <section> + <marker id="apprefDTD"></marker> + <title>The appref DTD</title> + + <p>This is the DTD for writing an application manual page.</p> + + <p>Example:</p> + <pre> +<?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> + </pre> + + <section> + <marker id="apprefTAG"></marker> + <title><appref></title> + + <p>The top level tag of an <c>appref</c> DTD.</p> + + <p>Contains + <seealso marker="header_tags#headerTAG"><header></seealso>, + <seealso marker="#appTAG"><app></seealso>, + <seealso marker="#appsummaryTAG"><appsummary></seealso>, + <seealso marker="#descriptionTAG"><description></seealso>, + zero or more + <seealso marker="#sectionTAG"><section></seealso> and + <seealso marker="#funcsTAG"><funcs></seealso>, + followed by zero or more + <seealso marker="#authorsTAG"><authors></seealso>.</p> + </section> + + <section> + <marker id="appTAG"></marker> + <title><app></title> + + <p>The application name. Contains plain text.</p> + </section> + + <section> + <marker id="appsummaryTAG"></marker> + <title><appsummary></title> + + <p>Short summary. Contains plain text.</p> + </section> + </section> + + <section> + <marker id="comrefDTD"></marker> + <title>The comref DTD</title> + + <p>This is the DTD for writing a command manual page.</p> + + <p>Example:</p> + <pre> +<?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> + </pre> + + <section> + <marker id="comrefTAG"></marker> + <title><comref></title> + + <p>The top level tag for a <c>comref</c> DTD.</p> + + <p>Contains + <seealso marker="header_tags#headerTAG"><header></seealso>, + <seealso marker="#comTAG"><com></seealso>, + <seealso marker="#comsummaryTAG"><comsummary></seealso>, + <seealso marker="#descriptionTAG"><description></seealso>, + zero or more + <seealso marker="#sectionTAG"><section></seealso> and + <seealso marker="#funcsTAG"><funcs></seealso>, + followed by zero or more + <seealso marker="#authorsTAG"><authors></seealso>.</p> + </section> + + <section> + <marker id="comTAG"></marker> + <title><com></title> + + <p>The command name. Contains plain text.</p> + </section> + + <section> + <marker id="comsummaryTAG"></marker> + + <title><comsummary></title> + + <p>Short summary. Contains plain text.</p> + </section> + </section> + + <section> + <marker id="crefDTD"></marker> + <title>The cref DTD</title> + + <p>This is the DTD for writing a C library manual page.</p> + + <p>Example:</p> + <pre><![CDATA[ +<?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><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> + <title>A title</title> + + <p>Some text...</p> + </section> + + +</cref> + ]]></pre> + + <section> + <marker id="crefTAG"></marker> + <title><cref></title> + + <p>The top level tag for a <c>cref</c> DTD.</p> + + <p>Contains + <seealso marker="header_tags#headerTAG"><header></seealso>, + <seealso marker="#libTAG"><lib></seealso>, + <seealso marker="#libsummaryTAG"><libsummary></seealso>, + <seealso marker="#descriptionTAG"><description></seealso>, + zero or more + <seealso marker="#sectionTAG"><section></seealso> and + <seealso marker="#funcsTAG"><funcs></seealso>, followed by + zero or more + <seealso marker="#authorsTAG"><authors></seealso>.</p> + </section> + + <section> + <marker id="libTAG"></marker> + <title><lib></title> + + <p>The C library name or acronym. Contains plain text.</p> + </section> + + <section> + <marker id="libsummaryTAG"></marker> + <title><libsummary></title> + + <p>Short summary. Contains plain text.</p> + </section> + </section> + + <section> + <marker id="erlrefDTD"></marker> + <title>The erlref DTD</title> + + <p>This is the DTD for writing Erlang module manual pages.</p> + + <p>Example:</p> + <pre> +<?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> + </pre> + + <section> + <marker id="erlrefTAG"></marker> + <title><erlref></title> + + <p>The top level tag for an <c>erlref</c> DTD.</p> + + <p>Contains + <seealso marker="header_tags#headerTAG"><header></seealso>, + <seealso marker="#moduleTAG"><module></seealso>, + <seealso marker="#modulesummaryTAG"><modulesummary></seealso>, + <seealso marker="#descriptionTAG"><description></seealso>, + zero or more + <seealso marker="#sectionTAG"><section></seealso> and + <seealso marker="#funcsTAG"><funcs></seealso>, + followed by zero or more + <seealso marker="#authorsTAG"><authors></seealso>.</p> + </section> + + <section> + <marker id="moduleTAG"></marker> + <title><module></title> + + <p>The module name. Contains plain text.</p> + </section> + + <section> + <marker id="modulesummaryTAG"></marker> + <title><modulesummary></title> + + <p>Short summary. Contains plain text.</p> + </section> + </section> + + <section> + <marker id="filerefDTD"></marker> + <title>The fileref DTD</title> + + <p>This is the DTD for writing file manual pages. In OTP, this DTD + is used for defining the format of for example <c>.rel</c> and + <c>.app</c> files.</p> + + <p>Example:</p> + <pre> +<?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> + </pre> + + <p>The file reference manual can also contain function definitions, + similar to the <c>erlref</c> DTD.</p> + + <section> + <marker id="filerefTAG"></marker> + <title><fileref></title> + + <p>The top level tag for a <c>fileref</c> DTD.</p> + + <p>Contains + <seealso marker="header_tags#headerTAG"><header></seealso>, + <seealso marker="#fileTAG"><file></seealso>, + <seealso marker="#filesummaryTAG"><filesummary></seealso>, + <seealso marker="#descriptionTAG"><description></seealso>, + zero or more + <seealso marker="#sectionTAG"><section></seealso> and + <seealso marker="#funcsTAG"><funcs></seealso>, + followed by zero or more + <seealso marker="#authorsTAG"><authors></seealso>.</p> + </section> + + <section> + <marker id="fileTAG"></marker> + <title><file></title> + + <p>The name of the file or file type. Contains plain text.</p> + </section> + + <section> + <marker id="filesummaryTAG"></marker> + <title><filesummary></title> + + <p>Short summary. Contains plain text.</p> + </section> + </section> + + <section> + <marker id="descriptionTAG"></marker> + <title><description></title> + + <p>The introduction after the title and before sections and + "formal" definitions.</p> + + <p>Contains any combination and any number of + <seealso marker="block_tags">block tags</seealso> except + <c><![CDATA[<image>]]></c> and <c><![CDATA[<table>]]></c>.</p> + </section> + + <section> + <marker id="sectionTAG"></marker> + <title><section></title> + + <p>Subdivisions of the document. Contains an optional + <seealso marker="inline_tags#markerTAG"><marker></seealso>, + a <seealso marker="user_guide_dtds#titleTAG"><title></seealso>, + + followed by any combination and any number of + <seealso marker="block_tags">block tags</seealso> except + <c><![CDATA[<image>]]></c> and <c><![CDATA[<table>]]></c>.</p> + </section> + + <section> + <marker id="funcsTAG"></marker> + <title><funcs></title> + + <p>A group of "formal" function definitions.</p> + + <p>Contains one or more + <seealso marker="#funcTAG"><func></seealso>.</p> + </section> + + <section> + <marker id="funcTAG"></marker> + <title><func></title> + + <p>A "formal" function definition.</p> + + <p>Contains one or more + <seealso marker="#nameTAG"><name></seealso>, followed by + <seealso marker="#fsummaryTAG"><fsummary></seealso>, + <seealso marker="#typeTAG"><type></seealso> (optional) and + <seealso marker="#descTAG"><desc></seealso> (optional).</p> + </section> + + <section> + <marker id="nameTAG"></marker> + <title><name></title> + + <p>Function/command signature with name, arguments and return value. + Contains plain text, except for the <c>cref</c> DTD where it + contains a <c><![CDATA[<ret>]]></c> (return type, plain text) and + a <c><![CDATA[<nametext>]]></c> (function name and arguments, + plain text).</p> + + <p>In the case of an <c>erlref</c> DTD, it will + automatically be added a + <seealso marker="inline_tags#markerTAG">marker</seealso>, + <c><![CDATA[<marker id="Name/Arity">]]></c> or + <c><![CDATA[<marker id="Name">]]></c>, based on the contents of + this tag before the function definition.</p> + + <p>Example: Consider the following name definition</p> + <pre><![CDATA[ +<name>foo(Arg1, Arg2) -> ok | {error, Reason}</name> + ]]></pre> + + <p>Then a marker like this will be added + <c><![CDATA[<marker id="foo/2">]]></c> before the function + definition in the generated HTML. That is, referring to + the function using + <c><![CDATA[<seealso marker="#foo/2">foo/2</seealso>]]></c> will + automatically work.</p> + </section> + + <section> + <marker id="fsummaryTAG"></marker> + <title><fsummary></title> + + <p>Function/command summary. Contains plain text, + <seealso marker="inline_tags#cTAG"><c></seealso> and + <seealso marker="inline_tags#emTAG"><em></seealso>.</p> + </section> + + <section> + <marker id="typeTAG"></marker> + <title><type></title> + + <p>Type declarations for the function/command.</p> + + <p>Contains one or more pairs of + <seealso marker="#vTAG"><v></seealso> and + <seealso marker="#dTAG"><d></seealso> (optional).</p> + </section> + + <section> + <marker id="vTAG"></marker> + <title><v></title> + + <p>Type declaration for an argument or return value. Contains plain + text.</p> + </section> + + <section> + <marker id="dTAG"></marker> + <title><d></title> + + <p>Description for an argument or return value. Contains plain text, + <seealso marker="inline_tags#cTAG"><c></seealso> and + <seealso marker="inline_tags#emTAG"><em></seealso>.</p> + </section> + + <section> + <marker id="descTAG"></marker> + <title><desc></title> + + <p>Function/command description. Contains + <seealso marker="block_tags">block tags</seealso> except + <c><image></c> and <c><table></c>.</p> + </section> + + <section> + <marker id="authorsTAG"></marker> + <title><authors></title> + + <p>Authors of the manual page. The <c>authors</c> element is optional.</p> + + <p>Contains one or more pairs of + <seealso marker="#anameTAG"><aname></seealso> and + <seealso marker="#emailTAG"><email></seealso>.</p> + </section> + + <section> + <marker id="anameTAG"></marker> + <title><aname></title> + + <p>Author name. Contains plain text.</p> + </section> + + <section> + <marker id="emailTAG"></marker> + <title><email></title> + + <p>Author email address. Contains plain text.</p> + </section> +</chapter> + |