Erlang -- How to Build OTP like documentation

User's Guide
Reference Manual
Release Notes
PDF
Top

Erl_Docgen
User's Guide
Version 0.3.2

Expand All
Contract All

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.