<!-- $Id: examples.xml,v 1.3 2007/05/11 08:16:44 thuffir Exp $ -->

<section>
<title>Examples of How to Create Documentation</title>

<section>
<title>HTML Example</title>
  <para> For this you need a web browser, say FireFox or Mozilla.  You can try
  this in the robodoc root directory.  It creates a document called
  <filename>HDocs/masterindex.html</filename> plus a lot of smaller
  documents from all the source files in the directory
  <filename>Source</filename>.</para>

<programlisting>
<command>robodoc</command> <option>--src</option> ./Source <option>--doc</option> ./HDocs <option>--multidoc</option> <option>--index</option> <option>--html</option>
</programlisting>
</section>

<section>
<title>RTF Example</title>

    <para>For this you need an rtf reader, for instance
    <command>Word</command>.  You can try this in the robodoc root
    directory.</para>

<programlisting>
<command>robodoc</command> <option>--src</option> ./Source <option>--doc</option> api <option>--singledoc</option> <option>--rtf</option> <option>--sections</option>
</programlisting>

    <para>This will create a document called
    <filename>api.rtf</filename>.</para>

    <para>By default the document looks pretty plain.  There is no
    chapter numbering or a table of contents, even if you asked for
    it.  All the information for this is included but not visible.
    This is because chapter numbering and a table of contents are
    generated by Word based on formatting information that is part of
    a Word document but not part of a RTF document.  </para>

    <para>To make it visible you include the generated document into a
    bigger document with the right formatting options.  This is best
    done with a cut-and-paste operation.  Use the cut-past-paste
    special menu, and paste it as RTF formatted text into your Word
    document.</para>

</section>

<section>
<title>LaTeX Example</title>

  <para> For this you need <command>latex</command> and
  <command>makeindex</command>. You can try this in the robodoc root
  directory.  It creates a single document called
  <filename>api.dvi</filename> from all the source files in the
  directory Source.</para>

<programlisting>
<command>robodoc</command> <option>--src</option> ./Source <option>--doc</option> api <option>--singledoc</option> <option>--latex</option> <option>--sections</option>
<command>latex</command> api.tex
<command>latex</command> api.tex
<command>makeindex</command> api.idx
<command>latex</command> api.tex
<command>xdvi</command> api.dvi
</programlisting>
</section>

<section>
<title>XML DocBook Example</title>

<para>
    DocBook is a xml format to create technical documentation, see.
    <ulink url="http://www.docbook.org/"><citetitle>DocBook.org</citetitle></ulink>.
    DocBook is quite nice. This manual for instance is written in DocBook and
    automatically translated into html and pdf format.
</para>

<para>
    You can use the DocBook output of ROBODoc to create several other formats,
    for instance: html, pdf, html-help.
    For this you need a tool that can process a DocBook file. There
    are several of these tools.
</para>

<section>
    <title>DocBook with html output</title>

<para>The easiest to use is <command>xsltproc</command>. It works under
    Windows and Unix.  A typical workflow under Windows is:
</para>

<programlisting>
<command>robodoc</command> <option>--src</option> ./Source <option>--doc</option> api <option>--singledoc</option> <option>--dbxml</option> <option>--sections</option>
<command>xsltproc</command> api.xsl api.xml > api.html
</programlisting>

<para>
    Where <filename>api.xsl</filename> contains:
</para>

<literallayout class="monospaced"><![CDATA[
<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
    <xsl:import href="e:/docbook/html/docbook.xsl"/>
    <xsl:param name="admon.graphics" select="1"/>
    <xsl:param name="section.autolabel" select="1"/>
</xsl:stylesheet>
]]>
</literallayout>

<para>For this you need <command>xsltproc</command>. For Windows these can be found at
    <ulink url="http://www.zlatkovic.com/libxml.en.html">
        <citetitle>http://www.zlatkovic.com libxml.en.html</citetitle></ulink>,
    and the stylesheets which can be found at
    <ulink url="http://docbook.sourceforge.net/"><citetitle>http://docbook.sourceforge.net/</citetitle></ulink>.
    In the example above the style sheets are installed on <filename>e:/docbook/</filename>.
</para>

<para>
    More information about xsl can be found at
    <ulink url="http://www.sagehill.net/docbookxsl/"><citetitle>http://www.sagehill.net/docbookxsl/</citetitle></ulink>.
</para>

</section>

<section>
    <title>DocBook with html help output</title>

<para>The same program can be used to
    <ulink
        url="http://docbook.sourceforge.net/release/xsl/current/doc/htmlhelp.html">
        <citetitle>create a html help</citetitle>
    </ulink> file. For this you need
    <ulink
        url="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/hwMicrosoftHTMLHelpDownloads.asp">
        <citetitle>HTML Help Workshop</citetitle>
    </ulink>. The workflow now is:
</para>

<programlisting>
<command>robodoc</command> <option>--src</option> ./Source <option>--doc</option> api <option>--singledoc</option> <option>--dbxml</option> <option>--sections</option>
<command>xsltproc</command> api.xsl api.xml
<command>hhc</command> htmlhelp.hhp
</programlisting>

<para>
    Where <filename>api.xsl</filename> contains:
</para>

<literallayout class="monospaced"><![CDATA[
<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
    <xsl:import href="e:/docbook/htmlhelp/htmlhelp.xsl"/>
    <xsl:param name="admon.graphics" select="1"/>
    <xsl:param name="section.autolabel" select="1"/>
</xsl:stylesheet>
]]>
</literallayout>

</section>


</section>
</section>

