<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html xmlns:fn="http://www.w3.org/2005/02/xpath-functions">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" href="../../../../doc/otp_doc.css" type="text/css">
<title>Erlang -- How to Build OTP like documentation</title>
</head>
<body bgcolor="white" text="#000000" link="#0000ff" vlink="#ff00ff" alink="#ff0000"><div id="container">
<script id="js" type="text/javascript" language="JavaScript" src="../../../../doc/js/flipmenu/flipmenu.js"></script><script id="js2" type="text/javascript" src="../../../../doc/js/erlresolvelinks.js"></script><script language="JavaScript" type="text/javascript">
<!--
function getWinHeight() {
var myHeight = 0;
if( typeof( window.innerHeight ) == 'number' ) {
//Non-IE
myHeight = window.innerHeight;
} else if( document.documentElement && ( document.documentElement.clientWidth ||
document.documentElement.clientHeight ) ) {
//IE 6+ in 'standards compliant mode'
myHeight = document.documentElement.clientHeight;
} else if( document.body && ( document.body.clientWidth || document.body.clientHeight ) ) {
//IE 4 compatible
myHeight = document.body.clientHeight;
}
return myHeight;
}
function setscrollpos() {
var objf=document.getElementById('loadscrollpos');
document.getElementById("leftnav").scrollTop = objf.offsetTop - getWinHeight()/2;
}
function addEvent(obj, evType, fn){
if (obj.addEventListener){
obj.addEventListener(evType, fn, true);
return true;
} else if (obj.attachEvent){
var r = obj.attachEvent("on"+evType, fn);
return r;
} else {
return false;
}
}
addEvent(window, 'load', setscrollpos);
//--></script><div id="leftnav"><div class="innertube">
<img alt="Erlang logo" src="../../../../doc/erlang-logo.png"><br><small><a href="users_guide.html">User's Guide</a><br><a href="index.html">Reference Manual</a><br><a href="release_notes.html">Release Notes</a><br><a href="../pdf/erl_docgen-0.3.3.pdf">PDF</a><br><a href="../../../../doc/index.html">Top</a></small><p><strong>Erl_Docgen</strong><br><strong>User's Guide</strong><br><small>Version 0.3.3</small></p>
<br><a href="javascript:openAllFlips()">Expand All</a><br><a href="javascript:closeAllFlips()">Contract All</a><p><small><strong>Chapters</strong></small></p>
<ul class="flipMenu" imagepath="../../../../doc/js/flipmenu">
<li id="loadscrollpos" title="How to Build OTP like documentation" expanded="true">How to Build OTP like documentation<ul>
<li><a href="doc-build.html">
Top of chapter
</a></li>
<li title="Utilities to prepare XML files"><a href="doc-build.html#id63368">Utilities to prepare XML files</a></li>
<li title="Use xsltproc to generate different output formats"><a href="doc-build.html#id61175">Use xsltproc to generate different output formats</a></li>
</ul>
</li>
<li id="no" title="Overview OTP DTDs" expanded="false">Overview OTP DTDs<ul>
<li><a href="overview.html">
Top of chapter
</a></li>
<li title="DTD Suite"><a href="overview.html#id64762">DTD Suite</a></li>
<li title="Basic Tags"><a href="overview.html#id68138">Basic Tags</a></li>
</ul>
</li>
<li id="no" title="User's Guide DTDs" expanded="false">User's Guide DTDs<ul>
<li><a href="user_guide_dtds.html">
Top of chapter
</a></li>
<li title="The part DTD"><a href="user_guide_dtds.html#id60222">The part DTD</a></li>
<li title="<part>"><a href="user_guide_dtds.html#id60510"><part></a></li>
<li title="<description>"><a href="user_guide_dtds.html#id68097"><description></a></li>
<li title="<include>"><a href="user_guide_dtds.html#id60627"><include></a></li>
<li title="The chapter DTD"><a href="user_guide_dtds.html#id68049">The chapter DTD</a></li>
<li title="<chapter>"><a href="user_guide_dtds.html#id63655"><chapter></a></li>
<li title="<section>"><a href="user_guide_dtds.html#id62101"><section></a></li>
<li title="<title>"><a href="user_guide_dtds.html#id62142"><title></a></li>
</ul>
</li>
<li id="no" title="Reference Manual DTDs" expanded="false">Reference Manual DTDs<ul>
<li><a href="refman_dtds.html">
Top of chapter
</a></li>
<li title="The application DTD"><a href="refman_dtds.html#id64613">The application DTD</a></li>
<li title="<application>"><a href="refman_dtds.html#id64497"><application></a></li>
<li title="The appref DTD"><a href="refman_dtds.html#id67949">The appref DTD</a></li>
<li title="The comref DTD"><a href="refman_dtds.html#id63005">The comref DTD</a></li>
<li title="The cref DTD"><a href="refman_dtds.html#id65218">The cref DTD</a></li>
<li title="The erlref DTD"><a href="refman_dtds.html#id65347">The erlref DTD</a></li>
<li title="The fileref DTD"><a href="refman_dtds.html#id65477">The fileref DTD</a></li>
<li title="<description>"><a href="refman_dtds.html#id65618"><description></a></li>
<li title="<section>"><a href="refman_dtds.html#id65651"><section></a></li>
<li title="<funcs>"><a href="refman_dtds.html#id65692"><funcs></a></li>
<li title="<func>"><a href="refman_dtds.html#id65718"><func></a></li>
<li title="<name>"><a href="refman_dtds.html#id65761"><name></a></li>
<li title="<fsummary>"><a href="refman_dtds.html#id65831"><fsummary></a></li>
<li title="<type>"><a href="refman_dtds.html#id65859"><type></a></li>
<li title="<v>"><a href="refman_dtds.html#id65891"><v></a></li>
<li title="<d>"><a href="refman_dtds.html#id65907"><d></a></li>
<li title="<desc>"><a href="refman_dtds.html#id65934"><desc></a></li>
<li title="<authors>"><a href="refman_dtds.html#id65964"><authors></a></li>
<li title="<aname>"><a href="refman_dtds.html#id66000"><aname></a></li>
<li title="<email>"><a href="refman_dtds.html#id66016"><email></a></li>
</ul>
</li>
<li id="no" title="Header Tags" expanded="false">Header Tags<ul>
<li><a href="header_tags.html">
Top of chapter
</a></li>
<li title="<header>"><a href="header_tags.html#id66099"><header></a></li>
<li title="<copyright>"><a href="header_tags.html#id66115"><copyright></a></li>
<li title="<legalnotice>"><a href="header_tags.html#id66159"><legalnotice></a></li>
<li title="<title>"><a href="header_tags.html#id66188"><title></a></li>
<li title="<shorttitle>"><a href="header_tags.html#id66219"><shorttitle></a></li>
<li title="<prepared>"><a href="header_tags.html#id66234"><prepared></a></li>
<li title="<responsible>"><a href="header_tags.html#id66250"><responsible></a></li>
<li title="<docno>"><a href="header_tags.html#id66266"><docno></a></li>
<li title="<approved>"><a href="header_tags.html#id66297"><approved></a></li>
<li title="<checked>"><a href="header_tags.html#id66313"><checked></a></li>
<li title="<date>"><a href="header_tags.html#id66328"><date></a></li>
<li title="<rev>"><a href="header_tags.html#id66344"><rev></a></li>
<li title="<file>"><a href="header_tags.html#id66376"><file></a></li>
</ul>
</li>
<li id="no" title="Block Tags" expanded="false">Block Tags<ul>
<li><a href="block_tags.html">
Top of chapter
</a></li>
<li title="<br> - Line Break"><a href="block_tags.html#id66498"><br> - Line Break</a></li>
<li title="<code> - Code Example"><a href="block_tags.html#id66536"><code> - Code Example</a></li>
<li title="<codeinclude> - Code Inclusion"><a href="block_tags.html#id66589"><codeinclude> - Code Inclusion</a></li>
<li title="<erleval> - Erlang Evaluation"><a href="block_tags.html#id66663"><erleval> - Erlang Evaluation</a></li>
<li title="<list> - List"><a href="block_tags.html#id66698"><list> - List</a></li>
<li title="<marker> - Marker"><a href="block_tags.html#id66782"><marker> - Marker</a></li>
<li title="<p> - Paragraph"><a href="block_tags.html#id66808"><p> - Paragraph</a></li>
<li title="<note> - Note"><a href="block_tags.html#id66849"><note> - Note</a></li>
<li title="<pre> - Pre-formatted Text"><a href="block_tags.html#id66895"><pre> - Pre-formatted Text</a></li>
<li title="<quote> - Quotation"><a href="block_tags.html#id66970"><quote> - Quotation</a></li>
<li title="<taglist> - Definition List"><a href="block_tags.html#id67018"><taglist> - Definition List</a></li>
<li title="<warning> - Warning"><a href="block_tags.html#id67121"><warning> - Warning</a></li>
<li title="<image> - Image"><a href="block_tags.html#id67173"><image> - Image</a></li>
<li title="<table> - Table"><a href="block_tags.html#id67236"><table> - Table</a></li>
</ul>
</li>
<li id="no" title="Inline Tags" expanded="false">Inline Tags<ul>
<li><a href="inline_tags.html">
Top of chapter
</a></li>
<li title="<br> - Line Break"><a href="inline_tags.html#id67434"><br> - Line Break</a></li>
<li title="<c> - Code"><a href="inline_tags.html#id67460"><c> - Code</a></li>
<li title="<em> - Emphasis"><a href="inline_tags.html#id67508"><em> - Emphasis</a></li>
<li title="<marker> - Marker"><a href="inline_tags.html#id67549"><marker> - Marker</a></li>
<li title="<seealso> - Local Cross Reference"><a href="inline_tags.html#id67607"><seealso> - Local Cross Reference</a></li>
<li title="<url> - Non-Local Cross Reference"><a href="inline_tags.html#id67687"><url> - Non-Local Cross Reference</a></li>
<li title="<term>, <termdef> - Glossary"><a href="inline_tags.html#id67726"><term>, <termdef> - Glossary</a></li>
<li title="<cite>, <citedef> - Bibliography"><a href="inline_tags.html#id67790"><cite>, <citedef> - Bibliography</a></li>
</ul>
</li>
<li id="no" title="Character Entities" expanded="false">Character Entities<ul>
<li><a href="character_entities.html">
Top of chapter
</a></li>
<li title="Added Latin 1"><a href="character_entities.html#id67860">Added Latin 1</a></li>
</ul>
</li>
</ul>
</div></div>
<div id="content">
<div class="innertube">
<h1>1 How to Build OTP like documentation</h1>
<h3><a name="id63368">1.1
Utilities to prepare XML files</a></h3>
<h4>Create XML files from code</h4>
<p>
If there are EDoc comments in a module, the escript <span class="code">xml_from_edoc.escript</span>
can be used to generate an XML file according to the <span class="code">erlref</span> DTD
for this module.
</p>
<p>
Example:
</p>
<div class="example"><pre>
1> escript $(ERL_TOP)/lib/erl_docgen/priv/bin/xml_from_edoc.escript ex1.erl
</pre></div>
<h4>Include code in XML</h4>
<p>If there are OTP DTD codeinclude tags in the source XML file, the escript
<span class="code">codeline_preprocessing.escript</span> can be used to include the code and produce
an XML file according to the OTP DTDs.
</p>
<p>
Example:
</p>
<div class="example"><pre>
1> escript $(ERL_TOP)/lib/erl_docgen/priv/bin/codeline_preprocessing.escript ex1.xmlsrc ex1.xml
</pre></div>
<h3><a name="id61175">1.2
Use xsltproc to generate different output formats</a></h3>
<h4>Parameters used in all the the XSL transformations</h4>
<p>
These parameters to <span class="code">xsltproc</span> are used for all the supported output formats.
</p>
<dl>
<dt><strong><span class="code">docgen</span></strong></dt>
<dd>
Path to erl_docgen's top directory.
</dd>
<dt><strong><span class="code">gendate</span></strong></dt>
<dd>
The date string that will be used in the documentation.
</dd>
<dt><strong><span class="code">appname</span></strong></dt>
<dd>
The name of the application.>
</dd>
<dt><strong><span class="code">appver</span></strong></dt>
<dd>
The version of the application.
</dd>
</dl>
<h4>Generate HTML output</h4>
<p>
When generating HTML one also needs these three pramaters to <span class="code">xsltproc</span>.
</p>
<dl>
<dt><strong><span class="code">outdir</span></strong></dt>
<dd>
Output directory for the produced html files.
</dd>
<dt><strong><span class="code">topdocdir</span></strong></dt>
<dd>
If one builds a standalone documentation for an application this should be set to ".".
</dd>
<dt><strong><span class="code">pdfdir</span></strong></dt>
<dd>
Relative path from the html directory to where the pdf file are placed.
</dd>
</dl>
<p>
Example:
</p>
<div class="example"><pre>
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
</pre></div>
<h4>Generate PDF</h4>
<p>
The generation of the PDF file is done in two steps. First is <span class="code">xsltproc</span> used to generate a <span class="code">.fo</span> file
which is used as input to the <span class="code">fop</span> command to produce th PDF file.
</p>
<p>
Example:
</p>
<div class="example"><pre>
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
</pre></div>
<h4>Generate man pages</h4>
<p>
Unix man pages can be generated with <span class="code">xsltproc</span> from XML files written according to
the different OTP ref type DTDs.
</p>
<p>
Example:
</p>
<div class="example"><pre>
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
</pre></div>
<h4>Upcomming changes</h4>
<p>
The output from the <span class="code">erl_docgen</span> 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.
</p>
</div>
<div class="footer">
<hr>
<p>Copyright © 2004-2012 Ericsson AB. All Rights Reserved.</p>
</div>
</div>
</div></body>
</html>
distrib
>
Fedora
>
17
>
i386
>
media
>
updates
>
by-pkgid
>
675c8c8167236dfcf8d66da674f931e8
>
files
>
570
