Erl_Docgen
User's Guide
Version 0.3

Chapters

• How to Build OTP like documentation
  • Top of chapter
  • Utilities to prepare XML files
  • Use xsltproc to generate different output formats
• Overview OTP DTDs
  • Top of chapter
  • DTD Suite
  • Basic Tags
• User's Guide DTDs
  • Top of chapter
  • The part DTD
  • <part>
  • <description>
  • <include>
  • The chapter DTD
  • <chapter>
  • <section>
  • <title>
• Reference Manual DTDs
  • Top of chapter
  • The application DTD
  • <application>
  • The appref DTD
  • The comref DTD
  • The cref DTD
  • The erlref DTD
  • The fileref DTD
  • <description>
  • <section>
  • <funcs>
  • <func>
  • <name>
  • <fsummary>
  • <type>
  • <v>
  • <d>
  • <desc>
  • <authors>
  • <aname>
  • <email>
• Header Tags
  • Top of chapter
  • <header>
  • <copyright>
  • <legalnotice>
  • <title>
  • <shorttitle>
  • <prepared>
  • <responsible>
  • <docno>
  • <approved>
  • <checked>
  • <date>
  • <rev>
  • <file>
• Block Tags
  • Top of chapter
  • <br> - Line Break
  • <code> - Code Example
  • <codeinclude> - Code Inclusion
  • <erleval> - Erlang Evaluation
  • <list> - List
  • <marker> - Marker
  • <p> - Paragraph
  • <note> - Note
  • <pre> - Pre-formatted Text
  • <quote> - Quotation
  • <taglist> - Definition List
  • <warning> - Warning
  • <image> - Image
  • <table> - Table
• Inline Tags
  • Top of chapter
  • <br> - Line Break
  • <c> - Code
  • <em> - Emphasis
  • <marker> - Marker
  • <seealso> - Local Cross Reference
  • <url> - Non-Local Cross Reference
  • <term>, <termdef> - Glossary
  • <cite>, <citedef> - Bibliography
• Character Entities
  • Top of chapter
  • Added Latin 1

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.