aboutsummaryrefslogtreecommitdiffstats
path: root/lib/docbuilder/doc/src/overview.xml
diff options
context:
space:
mode:
authorLars Thorsen <[email protected]>2011-11-16 15:10:18 +0100
committerLars Thorsen <[email protected]>2011-11-18 14:28:43 +0100
commit2da3a1fb06caf0c7fc53a8efdfbc769278b4323f (patch)
tree1c134e180ab90756f970a2e9e1c7fe9c87dc0f1e /lib/docbuilder/doc/src/overview.xml
parent8dc7d8f4931f3c0cb1838c828ae54da08f943f74 (diff)
downloadotp-2da3a1fb06caf0c7fc53a8efdfbc769278b4323f.tar.gz
otp-2da3a1fb06caf0c7fc53a8efdfbc769278b4323f.tar.bz2
otp-2da3a1fb06caf0c7fc53a8efdfbc769278b4323f.zip
[erl_docgen] Move files from docbuilder to erl_docgen
Diffstat (limited to 'lib/docbuilder/doc/src/overview.xml')
-rw-r--r--lib/docbuilder/doc/src/overview.xml185
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>
-