Erlang -- How to Build OTP like documentation

# 1 How to Build OTP like documentation

###
1.1 Utilities to prepare XML files

####
Create XML files from code

If there are EDoc comments in a module, the escript xml_from_edoc.escript can be used to generate an XML file according to the erlref DTD for this module.

Example:

    	1> escript $ERL_TOP/lib/erl_docgen/priv/bin/xml_from_edoc.escript ex1.erl

####
Include code in XML

If there are OTP DTD codeinclude tags in the source XML file, the escript codeline_preprocessing.escript can be used to include the code and produce an XML file according to the OTP DTDs.

Example:

    	1> escript $ERL_TOP/lib/erl_docgen/priv/bin/codeline_preprocessing.escript \
    	   ex1.xmlsrc ex1.xml

###
1.2 Use xsltproc to generate different output formats

####
Parameters used in all the the XSL transformations

These parameters to xsltproc are used for all the supported output formats.

docgen
  Path to erl_docgen's top directory.
gendate
  The date string that will be used in the documentation.
appname
  The name of the application.>
appver
  The version of the application.

####
Generate HTML output

When generating HTML one also needs these three pramaters to xsltproc.

outdir
  Output directory for the produced html files.
topdocdir
  If one builds a standalone documentation for an application this should be set to ".".
pdfdir
  Relative path from the html directory to where the pdf file are placed.

Example:

    	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

####
Generate PDF

The generation of the PDF file is done in two steps. First is xsltproc used to generate a .fo file which is used as input to the fop command to produce th PDF file.

Example:

    	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

####
Generate man pages

Unix man pages can be generated with xsltproc from XML files written according to the different OTP ref type DTDs.

Example:

    	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

####
Upcoming changes

The output from the erl_docgen 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.