diff options
Diffstat (limited to 'lib/erl_docgen/doc/src/overview.xml')
| -rw-r--r-- | lib/erl_docgen/doc/src/overview.xml | 185 |
1 files changed, 185 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..ca13c5d436 --- /dev/null +++ b/lib/erl_docgen/doc/src/overview.xml @@ -0,0 +1,185 @@ +<?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>Background</title> + + <p>DocBuilder has been used within the OTP project to generate + documentation for Erlang/OTP itself for more than ten years. + It has now been released as a regular Erlang/OTP application.</p> + + <p>The intention with DocBuilder is that it should be as easy to + use and maintain as possible and generate adequate documentation + for OTP's needs. It uses frames, which can probably be regarded as + old-fashioned today. Hopefully, this should be improved in + the future.</p> + + <p>Originally, DocBuilder input was SGML files and external tools + was used for parsing. The internal version used in the OTP + project can generate not only HTML code but also LaTeX (for PDF + and PostScript) and nroff (for UNIX man pages). (Again, using + external tools). Because of this, the parsed source code is + transformed into a tree structure before being transformed again + into the desired format.</p> + </section> + + <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> + + <p>A special kind of DTD, + <seealso marker="fasc_dtds">fascicules</seealso>, can be used to + specify the different parts of the documentation, and which one + of those should be shown as default.</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 DocBuilder 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 DocBuilder + documentation itself:</p> + <list> + <item>This User's Guide is written using the <c>part</c> and + <c>chapter</c> DTDs.</item> + + <item>The Reference Manual is 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 function + <seealso marker="docb_gen#module/1">docb_gen:module/1,2</seealso> + 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> + + <item> + <p>Generate HTML files by using + <seealso marker="docb_transform#file/1">docb_transform:file/1,2</seealso>. + </p> + </item> + </list> + </section> +</chapter> + |