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.