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
      Upcomming 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.
