Docs/extracting.xml

   1 <section>
   2 <title>Extracting Documentation with ROBODoc</title>
   3
   4     <para>Now that you have prepared your source code for use with
   5     ROBODoc you are ready to extract the documentation.  There are
   6     several choices to be made.</para>
   7
   8 <section>
   9 <title>Single document or many smaller documents</title>
  10
  11     <para>First of all, ROBODoc can be used in three modes.</para>
  12
  13     <itemizedlist>
  14
  15     <listitem><para>multidoc -- in this mode ROBODoc scans
  16     all the source files in your source directory and creates a
  17     separate document file for each of these in a document directory.
  18     The document directory is created automatically. Its structure is
  19     a mirror of the structure of your source directory.</para></listitem>
  20
  21     <listitem><para>singledoc -- in this mode ROBODoc scans all the source
  22     files in your source directory and creates a single documentation
  23     file that contains all the documentation extracted from your
  24     source files.  </para></listitem>
  25
  26     <listitem><para>singlefile -- in this mode ROBODoc scans a single source
  27     file and creates a single documentation file.</para></listitem>
  28
  29     </itemizedlist>
  30 </section>
  31
  32 <section>
  33 <title>multidoc</title>
  34
  35     <para>The multidoc mode is useful to create browsable documents.
  36     For instance many small HTML files that can be viewed with a
  37     web-browser.  This mode requires the following arguments:</para>
  38
  39     <para>
  40     <command>robodoc
  41     --src <replaceable>source directory</replaceable>
  42     --doc <replaceable>document directory</replaceable>
  43     --multidoc
  44     other options
  45     </command>
  46 </para>
  47
  48     <para>An additional option that is useful with this mode is
  49     <option>--index</option>, this creates a series of index files,
  50     one for each header type.</para>
  51
  52 </section>
  53
  54
  55 <section>
  56 <title>singledoc</title>
  57
  58     <para> The singledoc mode is useful to create bulk documentation
  59     that can be incorporated in other documents, or that can be
  60     delivered to a client as a single document.  For instance a file
  61     created in RTF format can be included into a larger design
  62     document written in Word format.  This mode requires the following
  63     arguments:</para>
  64
  65 <para>
  66     <command>robodoc
  67         --src <replaceable>source directory</replaceable>
  68         --doc <replaceable>document file without extension</replaceable>
  69         --singledoc
  70         <replaceable>other options</replaceable>
  71     </command>
  72 </para>
  73
  74     <para>An additional option that is useful with this mode is
  75     <option>--sections</option>, this causes the headers to follow a
  76     section layout based on the module element hierarchy defined in the
  77     header name.</para>
  78
  79 </section>
  80
  81
  82 <section>
  83 <title>singlefile</title>
  84
  85     <para>The singlefile mode is not very useful.  It is mainly used
  86     for debugging purposes.  This mode requires the following
  87     arguments:</para>
  88
  89 <para>
  90     <command>robodoc
  91     --src <replaceable>source file</replaceable>
  92     --doc <replaceable>document file</replaceable>
  93     --singlefile
  94     other options
  95 </command>
  96 </para>
  97
  98 </section>
  99
 100 <section>
 101 <title>Output formats</title>
 102
 103     <para>Your next choice is the output format. ROBODoc can create
 104     documentation in several formats:</para>
 105
 106     <itemizedlist>
 107     <listitem><para>HTML, option <option>--html</option></para></listitem>
 108     <listitem><para>RTF, option <option>--rtf</option></para></listitem>
 109     <listitem><para>LaTeX, option <option>--latex</option></para></listitem>
 110     <listitem><para>XML DocBook, option <option>--dbxml</option></para></listitem>
 111     </itemizedlist>
 112
 113     <para>What format to use depends on your wishes. If you want a
 114     single printable document, use LaTeX or XML DocBook.  If you want
 115     a document that can be included into a larger (Word) document use
 116     RTF.  If you want something that is browsable use HTML, or use XML
 117     DocBook and then convert it to HTML.</para>
 118
 119 </section>
 120 </section>
 121