From 5a649701ee9413a43fe8542e8a8146618464d485 Mon Sep 17 00:00:00 2001
From: Lars Thorsen <lars@erlang.org>
Date: Wed, 7 Dec 2011 13:01:40 +0100
Subject: [erl_docgen] Updated users guide
---
lib/erl_docgen/doc/src/Makefile | 1 +
lib/erl_docgen/doc/src/doc-build.xml | 188 +++++++++++++++++++++++++++++++++++
lib/erl_docgen/doc/src/overview.xml | 72 ++------------
lib/erl_docgen/doc/src/part.xml | 3 +-
lib/erl_docgen/info | 1 -
5 files changed, 202 insertions(+), 63 deletions(-)
create mode 100644 lib/erl_docgen/doc/src/doc-build.xml
(limited to 'lib')
diff --git a/lib/erl_docgen/doc/src/Makefile b/lib/erl_docgen/doc/src/Makefile
index a546d8da33..ff50c12895 100644
--- a/lib/erl_docgen/doc/src/Makefile
+++ b/lib/erl_docgen/doc/src/Makefile
@@ -44,6 +44,7 @@ XML_PART_FILES = \
XML_CHAPTER_FILES = \
overview.xml \
+ doc-build.xml \
user_guide_dtds.xml \
refman_dtds.xml \
notes.xml \
diff --git a/lib/erl_docgen/doc/src/doc-build.xml b/lib/erl_docgen/doc/src/doc-build.xml
new file mode 100644
index 0000000000..08410a1539
--- /dev/null
+++ b/lib/erl_docgen/doc/src/doc-build.xml
@@ -0,0 +1,188 @@
+<?xml version="1.0" encoding="iso-8859-1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+ <header>
+ <copyright>
+ <year>1997</year><year>2011</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>How to Build OTP like documentation</title>
+ <prepared></prepared>
+ <docno></docno>
+ <date></date>
+ <rev></rev>
+ <file>doc-build.xml</file>
+ </header>
+
+ <section>
+ <title>Utilities to prepare XML files</title>
+ <section>
+ <title>Create XML files from code</title>
+ <p>
+ If there are EDoc comments in a module, the escript <c>xml_from_edoc.escript</c>
+ can be used to generate an XML file according to the <c>erlref</c> DTD
+ for this module.
+ </p>
+ <p>
+ Example:
+ </p>
+ <code>
+
+ 1> escript $(ERL_TOP)/lib/erl_docgen/priv/bin/xml_from_edoc.escript ex1.erl
+ </code>
+ </section>
+ <section>
+ <title>Include code in XML</title>
+ <p>If there are OTP DTD <i>codeinclude</i> tags in the source XML file, the escript
+ <c>codeline_preprocessing.escript</c> can be used to include the code and produce
+ an XML file according to the OTP DTDs.
+ </p>
+ <p>
+ Example:
+ </p>
+ <code>
+
+ 1> escript $(ERL_TOP)/lib/erl_docgen/priv/bin/codeline_preprocessing.escript ex1.xmlsrc ex1.xml
+ </code>
+ </section>
+ </section>
+
+ <section>
+ <title>Use xsltproc to generate different output formats</title>
+
+ <section>
+ <title>Parameters used in all the the XSL transformations</title>
+ <p>
+ These parameters to <c>xsltproc</c> are used for all the supported output formats.
+ </p>
+ <taglist>
+ <tag><c>docgen</c></tag>
+ <item>
+ Path to erl_docgen's top directory.
+ </item>
+ <tag><c>gendate</c></tag>
+ <item>
+ The date string that will be used in the documentation.
+ </item>
+ <tag><c>appname</c></tag>
+ <item>
+ The name of the application.>
+ </item>
+ <tag><c>appver</c></tag>
+ <item>
+ The version of the application.
+ </item>
+ </taglist>
+ </section>
+
+ <section>
+ <title>Generate HTML output</title>
+ <p>
+ When generating HTML one also needs these three pramaters to <c>xsltproc</c>.
+ </p>
+ <taglist>
+ <tag><c>outdir</c></tag>
+ <item>
+ Output directory for the produced html files.
+ </item>
+ <tag><c>topdocdir</c></tag>
+ <item>
+ If one builds a standalone documentation for an application this should be set to ".".
+ </item>
+ <tag><c>pdfdir</c></tag>
+ <item>
+ Relative path from the html directory to where the pdf file are placed.
+ </item>
+ </taglist>
+ <p>
+ Example:
+ </p>
+ <code>
+
+ 1> xsltproc --noout --stringparam outdir /tmp/myhtmldoc \
+ --stringparam docgen $(ERL_TOP)/lib/erl_docgen \
+ --stringparam topdocdir . \
+ --stringparam pdfdir "$(PDFDIR)" \
+ --xinclude \
+ --stringparam gendate "December 5 2011" \
+ --stringparam appname MyApp \
+ --stringparam appver 0.1 \
+ -path $ERL_TOP/lib/erl_docgen/priv/dtd \
+ -path $ERL_TOP/lib/erl_docgen/priv/dtd_html_entities \
+ $ERL_TOP/lib/erl_docgen/priv/xsl/db_html.xsl mybook.xml
+ </code>
+ </section>
+
+ <section>
+ <title>Generate PDF</title>
+ <p>
+ The generation of the PDF file is done in two steps. First is <c>xsltproc</c> used to generate a <c>.fo</c> file
+ which is used as input to the <c>fop</c> command to produce th PDF file.
+ </p>
+ <p>
+ Example:
+ </p>
+ <code>
+
+ 1> xsltproc --output MyApp.fo \
+ --stringparam docgen $ERL_TOP/lib/erl_docgen \
+ --stringparam gendate "December 5 2011" \
+ --stringparam appname MyApp \
+ --stringparam appver 0.1 \
+ --xinclude \
+ -path $ERL_TOP/lib/erl_docgen/priv/dtd \
+ -path $ERL_TOP/lib/erl_docgen/priv/dtd_html_entities \
+ $ERL_TOP/lib/erl_docgen/priv/xsl/db_pdf.xsl mybook.xml
+
+
+ 2> fop -fo MyApp.fo -pdf MyApp.pdf
+ </code>
+ </section>
+
+ <section>
+ <title>Generate man pages</title>
+ <p>
+ Unix man pages can be generated with <c>xsltproc</c> from XML files written according to
+ the different OTP ref type DTDs.
+ </p>
+ <p>
+ Example:
+ </p>
+ <code>
+
+ 1> xsltproc --output my_module.3\
+ --stringparam docgen $ERL_TOP/lib/erl_docgen \
+ --stringparam gendate "December 5 2011" \
+ --stringparam appname MyApp \
+ --stringparam appver 0.1 \
+ --xinclude -path $ERL_TOP/lib/erl_docgen/priv/dtd \
+ -path $ERL_TOP/lib/erl_docgen/priv/dtd_man_entities \
+ $ERL_TOP/lib/erl_docgen/priv/xsl/db_man.xsl my_refpage.xml
+ </code>
+ </section>
+
+ <section>
+ <title>Upcomming changes</title>
+ <p>
+ The output from the <c>erl_docgen</c> documentation build process is now just the OTP style.
+ But in a near future we will for example add the possibility to change logo, color in the PDF and
+ style sheet for the HTML.
+ </p>
+ </section>
+
+ </section>
+</chapter>
diff --git a/lib/erl_docgen/doc/src/overview.xml b/lib/erl_docgen/doc/src/overview.xml
index f0f97d8d45..2a420c53d9 100644
--- a/lib/erl_docgen/doc/src/overview.xml
+++ b/lib/erl_docgen/doc/src/overview.xml
@@ -1,10 +1,10 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="iso-8859-1" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">
<chapter>
<header>
<copyright>
- <year>1997</year><year>2009</year>
+ <year>1997</year><year>2011</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -20,7 +20,7 @@
under the License.
</legalnotice>
- <title>Overview</title>
+ <title>Overview OTP DTDs</title>
<prepared></prepared>
<docno></docno>
<date></date>
@@ -42,7 +42,7 @@
A collection of chapters
(<seealso marker="user_guide_dtds#chapterDTD">chapter</seealso>).
</p>
- </item>
+ </item>
<tag><em>Reference Manual</em></tag>
<item>
@@ -72,23 +72,16 @@
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 structure of the different documents and the meaning of the
+ tags are explained. There are numerous examples of documentation
+ source code.</p>
- <p>The left frame also contains links to a bibliography and a
- glossary, which are automatically generated.</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>
- <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>
@@ -108,48 +101,5 @@
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>
diff --git a/lib/erl_docgen/doc/src/part.xml b/lib/erl_docgen/doc/src/part.xml
index 4594778a2f..26d660df08 100644
--- a/lib/erl_docgen/doc/src/part.xml
+++ b/lib/erl_docgen/doc/src/part.xml
@@ -27,10 +27,11 @@
<rev></rev>
</header>
<description>
- <p><em>Erl_Docgen</em> provides functionality for generating HTML/PDF
+ <p><em>Erl_Docgen</em> provides functionality for generating HTML/PDF/man
documentation for Erlang modules and Erlang/OTP applications
from XML source code and/or EDoc comments in Erlang source code.</p>
</description>
+ <xi:include href="doc-build.xml"/>
<xi:include href="overview.xml"/>
<xi:include href="user_guide_dtds.xml"/>
<xi:include href="refman_dtds.xml"/>
diff --git a/lib/erl_docgen/info b/lib/erl_docgen/info
index 4dc2a02bfb..31c7eb911a 100644
--- a/lib/erl_docgen/info
+++ b/lib/erl_docgen/info
@@ -1,3 +1,2 @@
group: doc Documentation Applications
short: A utility used to produce the OTP documentation.
-
--
cgit v1.2.3