Docs/examples.xml

   1 <!-- $Id: examples.xml,v 1.3 2007/05/11 08:16:44 thuffir Exp $ -->
   2
   3 <section>
   4 <title>Examples of How to Create Documentation</title>
   5
   6 <section>
   7 <title>HTML Example</title>
   8   <para> For this you need a web browser, say FireFox or Mozilla.  You can try
   9   this in the robodoc root directory.  It creates a document called
  10   <filename>HDocs/masterindex.html</filename> plus a lot of smaller
  11   documents from all the source files in the directory
  12   <filename>Source</filename>.</para>
  13
  14 <programlisting>
  15 <command>robodoc</command> <option>--src</option> ./Source <option>--doc</option> ./HDocs <option>--multidoc</option> <option>--index</option> <option>--html</option>
  16 </programlisting>
  17 </section>
  18
  19 <section>
  20 <title>RTF Example</title>
  21
  22     <para>For this you need an rtf reader, for instance
  23     <command>Word</command>.  You can try this in the robodoc root
  24     directory.</para>
  25
  26 <programlisting>
  27 <command>robodoc</command> <option>--src</option> ./Source <option>--doc</option> api <option>--singledoc</option> <option>--rtf</option> <option>--sections</option>
  28 </programlisting>
  29
  30     <para>This will create a document called
  31     <filename>api.rtf</filename>.</para>
  32
  33     <para>By default the document looks pretty plain.  There is no
  34     chapter numbering or a table of contents, even if you asked for
  35     it.  All the information for this is included but not visible.
  36     This is because chapter numbering and a table of contents are
  37     generated by Word based on formatting information that is part of
  38     a Word document but not part of a RTF document.  </para>
  39
  40     <para>To make it visible you include the generated document into a
  41     bigger document with the right formatting options.  This is best
  42     done with a cut-and-paste operation.  Use the cut-past-paste
  43     special menu, and paste it as RTF formatted text into your Word
  44     document.</para>
  45
  46 </section>
  47
  48 <section>
  49 <title>LaTeX Example</title>
  50
  51   <para> For this you need <command>latex</command> and
  52   <command>makeindex</command>. You can try this in the robodoc root
  53   directory.  It creates a single document called
  54   <filename>api.dvi</filename> from all the source files in the
  55   directory Source.</para>
  56
  57 <programlisting>
  58 <command>robodoc</command> <option>--src</option> ./Source <option>--doc</option> api <option>--singledoc</option> <option>--latex</option> <option>--sections</option>
  59 <command>latex</command> api.tex
  60 <command>latex</command> api.tex
  61 <command>makeindex</command> api.idx
  62 <command>latex</command> api.tex
  63 <command>xdvi</command> api.dvi
  64 </programlisting>
  65 </section>
  66
  67 <section>
  68 <title>XML DocBook Example</title>
  69
  70 <para>
  71     DocBook is a xml format to create technical documentation, see.
  72     <ulink url="http://www.docbook.org/"><citetitle>DocBook.org</citetitle></ulink>.
  73     DocBook is quite nice. This manual for instance is written in DocBook and
  74     automatically translated into html and pdf format.
  75 </para>
  76
  77 <para>
  78     You can use the DocBook output of ROBODoc to create several other formats,
  79     for instance: html, pdf, html-help.
  80     For this you need a tool that can process a DocBook file. There
  81     are several of these tools.
  82 </para>
  83
  84 <section>
  85     <title>DocBook with html output</title>
  86
  87 <para>The easiest to use is <command>xsltproc</command>. It works under
  88     Windows and Unix.  A typical workflow under Windows is:
  89 </para>
  90
  91 <programlisting>
  92 <command>robodoc</command> <option>--src</option> ./Source <option>--doc</option> api <option>--singledoc</option> <option>--dbxml</option> <option>--sections</option>
  93 <command>xsltproc</command> api.xsl api.xml > api.html
  94 </programlisting>
  95
  96 <para>
  97     Where <filename>api.xsl</filename> contains:
  98 </para>
  99
 100 <literallayout class="monospaced"><![CDATA[
 101 <?xml version='1.0'?>
 102 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
 103     <xsl:import href="e:/docbook/html/docbook.xsl"/>
 104     <xsl:param name="admon.graphics" select="1"/>
 105     <xsl:param name="section.autolabel" select="1"/>
 106 </xsl:stylesheet>
 107 ]]>
 108 </literallayout>
 109
 110 <para>For this you need <command>xsltproc</command>. For Windows these can be found at
 111     <ulink url="http://www.zlatkovic.com/libxml.en.html">
 112         <citetitle>http://www.zlatkovic.com libxml.en.html</citetitle></ulink>,
 113     and the stylesheets which can be found at
 114     <ulink url="http://docbook.sourceforge.net/"><citetitle>http://docbook.sourceforge.net/</citetitle></ulink>.
 115     In the example above the style sheets are installed on <filename>e:/docbook/</filename>.
 116 </para>
 117
 118 <para>
 119     More information about xsl can be found at
 120     <ulink url="http://www.sagehill.net/docbookxsl/"><citetitle>http://www.sagehill.net/docbookxsl/</citetitle></ulink>.
 121 </para>
 122
 123 </section>
 124
 125 <section>
 126     <title>DocBook with html help output</title>
 127
 128 <para>The same program can be used to
 129     <ulink
 130         url="http://docbook.sourceforge.net/release/xsl/current/doc/htmlhelp.html">
 131         <citetitle>create a html help</citetitle>
 132     </ulink> file. For this you need
 133     <ulink
 134         url="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/hwMicrosoftHTMLHelpDownloads.asp">
 135         <citetitle>HTML Help Workshop</citetitle>
 136     </ulink>. The workflow now is:
 137 </para>
 138
 139 <programlisting>
 140 <command>robodoc</command> <option>--src</option> ./Source <option>--doc</option> api <option>--singledoc</option> <option>--dbxml</option> <option>--sections</option>
 141 <command>xsltproc</command> api.xsl api.xml
 142 <command>hhc</command> htmlhelp.hhp
 143 </programlisting>
 144
 145 <para>
 146     Where <filename>api.xsl</filename> contains:
 147 </para>
 148
 149 <literallayout class="monospaced"><![CDATA[
 150 <?xml version='1.0'?>
 151 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
 152     <xsl:import href="e:/docbook/htmlhelp/htmlhelp.xsl"/>
 153     <xsl:param name="admon.graphics" select="1"/>
 154     <xsl:param name="section.autolabel" select="1"/>
 155 </xsl:stylesheet>
 156 ]]>
 157 </literallayout>
 158
 159 </section>
 160
 161
 162 </section>
 163 </section>
 164