[erl_docgen] Move files from docbuilder to erl_docgen

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