From 84adefa331c4159d432d22840663c38f155cd4c1 Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Fri, 20 Nov 2009 14:54:40 +0000 Subject: The R13B03 release. --- lib/docbuilder/doc/src/refman_dtds.xml | 667 +++++++++++++++++++++++++++++++++ 1 file changed, 667 insertions(+) create mode 100644 lib/docbuilder/doc/src/refman_dtds.xml (limited to 'lib/docbuilder/doc/src/refman_dtds.xml') diff --git a/lib/docbuilder/doc/src/refman_dtds.xml b/lib/docbuilder/doc/src/refman_dtds.xml new file mode 100644 index 0000000000..a7beaed708 --- /dev/null +++ b/lib/docbuilder/doc/src/refman_dtds.xml @@ -0,0 +1,667 @@ + + + + +
+ + 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>
+
+
+ +
+ + <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>
+
+ +
+ + <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.

+
+ +
+ + <appsummary> + +

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

+
+ +
+ + + <comsummary> + +

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.

+
+ +
+ + <libsummary> + +

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

+
+ +
+ + <module> + +

The module name. Contains plain text.

+
+ +
+ + <modulesummary> + +

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.

+ +
+ + <fileref> + +

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.

+
+ +
+ + <filesummary> + +

Short summary. Contains plain text.

+
+
+ +
+ + <description> + +

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

+ +

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

+
+ +
+ + <section> + +

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.

+
+ +
+ + <fsummary> + +

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

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.

+
+ + -- cgit v1.2.3