1  How to Build OTP like documentation

1 How to Build OTP like documentation

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

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

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

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

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

Output directory for the produced html files.
If one builds a standalone documentation for an application this should be set to ".".
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

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

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

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.