diff options
Diffstat (limited to 'lib/erl_docgen/doc/src/overview.xml')
| -rw-r--r-- | lib/erl_docgen/doc/src/overview.xml | 155 |
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> + |