diff options
Diffstat (limited to 'lib/docbuilder/doc/src/overview.xml')
| -rw-r--r-- | lib/docbuilder/doc/src/overview.xml | 185 |
1 files changed, 0 insertions, 185 deletions
diff --git a/lib/docbuilder/doc/src/overview.xml b/lib/docbuilder/doc/src/overview.xml deleted file mode 100644 index ca13c5d436..0000000000 --- a/lib/docbuilder/doc/src/overview.xml +++ /dev/null @@ -1,185 +0,0 @@ -<?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> - |