[erl_docgen] Updated users guide

4 files changed, 202 insertions, 62 deletions

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"/>