1 <!-- $Id: examples.xml,v 1.3 2007/05/11 08:16:44 thuffir Exp $ -->
4 <title>Examples of How to Create Documentation</title>
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>
15 <command>robodoc</command> <option>--src</option> ./Source <option>--doc</option> ./HDocs <option>--multidoc</option> <option>--index</option> <option>--html</option>
20 <title>RTF Example</title>
22 <para>For this you need an rtf reader, for instance
23 <command>Word</command>. You can try this in the robodoc root
27 <command>robodoc</command> <option>--src</option> ./Source <option>--doc</option> api <option>--singledoc</option> <option>--rtf</option> <option>--sections</option>
30 <para>This will create a document called
31 <filename>api.rtf</filename>.</para>
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>
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
49 <title>LaTeX Example</title>
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>
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
68 <title>XML DocBook Example</title>
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.
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.
85 <title>DocBook with html output</title>
87 <para>The easiest to use is <command>xsltproc</command>. It works under
88 Windows and Unix. A typical workflow under Windows is:
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
97 Where <filename>api.xsl</filename> contains:
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"/>
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>.
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>.
126 <title>DocBook with html help output</title>
128 <para>The same program can be used to
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
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:
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
146 Where <filename>api.xsl</filename> contains:
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"/>