aboutsummaryrefslogtreecommitdiffstats
path: root/lib/erl_docgen/doc/src/overview.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/erl_docgen/doc/src/overview.xml')
-rw-r--r--lib/erl_docgen/doc/src/overview.xml155
1 files changed, 155 insertions, 0 deletions
diff --git a/lib/erl_docgen/doc/src/overview.xml b/lib/erl_docgen/doc/src/overview.xml
new file mode 100644
index 0000000000..f0f97d8d45
--- /dev/null
+++ b/lib/erl_docgen/doc/src/overview.xml
@@ -0,0 +1,155 @@
+<?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>Overview</title>
+ <prepared></prepared>
+ <docno></docno>
+ <date></date>
+ <rev></rev>
+ <file>overview.xml</file>
+ </header>
+
+ <section>
+ <title>DTD Suite</title>
+
+ <p>Input is written as XML according to one of the DTDs and output
+ is corresponding HTML. Documentation for an Erlang/OTP application
+ is usually organized as follows:</p>
+ <taglist>
+ <tag><em>User's Guide</em></tag>
+ <item>
+ <p>(DTD:
+ <seealso marker="user_guide_dtds#partDTD">part</seealso>)
+ A collection of chapters
+ (<seealso marker="user_guide_dtds#chapterDTD">chapter</seealso>).
+ </p>
+ </item>
+
+ <tag><em>Reference Manual</em></tag>
+ <item>
+ <p>(DTD:
+ <seealso marker="refman_dtds#applicationDTD">application</seealso>
+ A collection of manual pages for modules
+ (<seealso marker="refman_dtds#erlrefDTD">erlref</seealso>),
+ applications
+ (<seealso marker="refman_dtds#apprefDTD">appref</seealso>),
+ commands
+ (<seealso marker="refman_dtds#comrefDTD">comref</seealso>),
+ C libraries
+ (<seealso marker="refman_dtds#crefDTD">cref</seealso>) and
+ files
+ (<seealso marker="refman_dtds#filerefDTD">fileref</seealso>).
+ </p>
+ </item>
+
+ <tag><em>Release Notes</em></tag>
+ <item>
+ <p>Same structure as the User's Guide.</p>
+ </item>
+ </taglist>
+
+ <p>In some cases, one or more of the User's Guide, Reference Manual
+ and Release Notes are omitted. Also, it is possible to use either
+ the <c>application</c> or <c>part</c> DTD to write other types
+ of documentation for the application.</p>
+
+ </section>
+
+ <section>
+ <title>Structure of Generated HTML</title>
+
+ <p>The generated HTML corresponding to a <c>part</c> or
+ <c>application</c> document is split into a left frame and a right
+ frame. The left frame contains information about the document
+ and links to the included files, that is chapters or manual pages.
+ The right frame is used to display either the front page for
+ the document, or the selected chapter/manual page.</p>
+
+ <p>The left frame also contains links to a bibliography and a
+ glossary, which are automatically generated.</p>
+
+ <p>In the case of an <c>application</c> document, the left frame
+ also contains a link to an automatically generated index.</p>
+ </section>
+
+ <section>
+ <title>Basic Tags</title>
+
+ <p>All DTDs in the OTP DTD suite share a basic set of tags.
+ An author can easily switch from one DTD to another and still use
+ the same basic tags. It is furthermore easy to copy pieces of
+ information from one document to another, even though they do not
+ use the same DTD.</p>
+
+ <p>The basic set of tags are divided into two categories:
+ <seealso marker="block_tags">block tags</seealso> and
+ <seealso marker="inline_tags">inline tags</seealso>. Block tags
+ typically define a separate block of information, like a
+ paragraph or a list. Inline tags are typically used within block
+ tags, for example a highlighted word within a paragraph.</p>
+ </section>
+
+ <section>
+ <title>About This Document</title>
+
+ <p>In this User's Guide, the structure of the different documents
+ and the meaning of the tags are explained. There are numerous
+ examples of documentation source code.</p>
+
+ <p>For readability and simplicity, the examples have been kept as
+ short as possible. For an example of what the generated HTML
+ will look like, it is recommended to look at the documentation of
+ an OTP application.</p>
+ <list>
+ <item>This User's Guides are written using the <c>part</c> and
+ <c>chapter</c> DTDs.</item>
+
+ <item>The Reference Manuals are written using
+ the <c>application</c>, <c>appref</c> and <c>erlref</c> DTDs.
+ </item>
+ </list>
+ </section>
+
+ <section>
+ <title>Usage</title>
+
+ <list type="ordered">
+ <item>
+ <p>Create the relevant XML files.</p>
+
+ <p>If there are EDoc comments in a module, the escript
+ <!-- seealso marker="xml_from_edoc">xml_from_edoc</seealso -->
+ <c>xml_from_edoc</c>
+ can be used to generate an XML file according to
+ the <c>erlref</c> DTD for this module.</p>
+ </item>
+
+ <!-- item>
+ <p>The XML files can be validated using
+ <seealso marker="docb_xml_check#validate/1">docb_xml_check:validate/1</seealso>.
+ </p>
+ </item -->
+
+ </list>
+ </section>
+</chapter>
+