diff options
Diffstat (limited to 'lib/erl_docgen/doc/src/doc-build.xml')
| -rw-r--r-- | lib/erl_docgen/doc/src/doc-build.xml | 188 |
1 files changed, 188 insertions, 0 deletions
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> |