Docs/options.xml

   1
   2
   3
   4 <section id="options">
   5     <title id="options.title">Options</title>
   6
   7     <para>The behavior of ROBODoc can be further fine-tune with a large number of
   8         options.</para>
   9
  10     <variablelist>
  11         <!-- TODO make a varlist from this -->
  12         <varlistentry><term>-c</term><listitem>
  13                 <para>Show the copyright message.</para>
  14         </listitem></varlistentry>
  15
  16         <varlistentry id="cmode"><term id="cmode.term">--cmode</term><listitem>
  17                 <para>Use ANSI C grammar in SOURCE items and use this
  18                     for syntax highlighting (<literal>HTML</literal> only).</para>
  19         </listitem></varlistentry>
  20
  21         <varlistentry><term>--css</term><listitem>
  22                 <para> Use the content of the specified file to create the
  23                     <filename>robodoc.css</filename>.  The content of the file is
  24                     copied into <filename>robodoc.css</filename>.  </para>
  25         </listitem></varlistentry>
  26
  27         <varlistentry><term>--dbxml</term><listitem>
  28                 <para>Generate documentation in XML DocBook format.</para>
  29         </listitem></varlistentry>
  30
  31         <varlistentry><term>--debug</term><listitem>
  32                 <para>Works like --tell, bug gives a lot more information.</para>
  33         </listitem></varlistentry>
  34
  35         <varlistentry><term>--doc</term><listitem>
  36                 <para>Define the path to the documentation directory or
  37                     documentation file.  A path can start with
  38                     <literal>./</literal> or <literal>/</literal>.  Do not use
  39                     <literal>..</literal> in the path.  The documentation
  40                     directory can be a subdirectory of the source directory,
  41                     or be parallel to the source directory,
  42                     however they can not be equal. So
  43                     <command>--src ./sources</command>
  44                     together with
  45                     <command>--doc ./documents</command>
  46                     is fine,
  47                     but
  48                     <command>--src ./Everything</command>
  49                     together with
  50                     <command>--doc ./Everything</command>
  51                     is not.
  52                 </para>
  53         </listitem></varlistentry>
  54
  55         <varlistentry><term>--doctype_name</term><listitem>
  56                 <para>DocBook output requires a <literal>&lt;!DOCTYPE&gt;</literal> tag.
  57                     With this option you can specify your own version of it.  You have
  58                     to use it in combination with <command>--doctype_location</command>.
  59                     An example:
  60                 </para>
  61 <programlisting>
  62     robodoc --src test --doc test
  63         --doctype_location "-//OASIS//DTD Simplified DocBook XML V1.1//EN"
  64         --doctype_name docbook-simple/sdocbook.dtd
  65         --dbxml
  66 </programlisting>
  67                 <para>
  68                     results in the following docbook file with the following head:
  69                 </para>
  70 <programlisting>
  71 &lt;!DOCTYPE article PUBLIC "-//OASIS//DTD Simplified DocBook XML V1.1//EN"
  72 "docbook-simple/sdocbook.dtd"&gt;
  73 </programlisting>
  74
  75         </listitem></varlistentry>
  76
  77         <varlistentry><term>--doctype_location</term><listitem>
  78             <para>See <command>--doctype_name</command>.</para>
  79         </listitem></varlistentry>
  80
  81         <varlistentry><term>--headless</term><listitem>
  82                 <para>Do not create the head of a document. This allows you to
  83                     create documents that can be included in other documents, or
  84                     to which you can add your own style.</para>
  85
  86                 <para>For html output this means that no
  87                     <literal>&lt;html&gt;&lt;head&gt; ..... &lt;body&gt;</literal>
  88                     is generated.
  89                 </para>
  90
  91                 <para>For LaTeX output this means none of the document
  92                     initialization code is generated, such as
  93                     <literal>\documentclass{article}</literal> or
  94                     <literal>\begin{document}</literal> is generated.  If you use
  95                     this option in combination with <option> --footless</option>
  96                     you can use <literal>\include</literal> or
  97                     <literal>\input</literal> commands to include the ROBODoc
  98                     generated documents in a larger document.</para>
  99
 100                 <para>For XML DocBook output this means no
 101                     <literal>&lt;!DOCTYPE&gt;</literal>,
 102                     <literal>&lt;article&gt;</literal>, and
 103                     <literal>&lt;articleinfo&gt;</literal> is generated.
 104                 </para>
 105
 106         </listitem></varlistentry>
 107
 108         <varlistentry><term>--first_section_level</term><listitem>
 109                 <para>Make the first section start at the specified level
 110                     instead of 1.  This is useful if you want to include the
 111                     generated documentation in another document.
 112                 </para>
 113         </listitem></varlistentry>
 114
 115         <varlistentry><term>--footless</term><listitem>
 116                 <para>Do not create the foot of a document. This allows you to
 117                     create documents that can be included in other documents, or
 118                     to which you can add your own style.</para>
 119
 120                 <para>For html output this means that no
 121                     <literal>&lt;/body&gt;&lt;/html&gt;</literal>
 122                     is generated.
 123                 </para>
 124
 125                 <para>For LaTeX output this means no
 126                     <literal>\end{document}</literal> is generated.
 127                 </para>
 128
 129                 <para>For XML DocBook output this means no
 130                     <literal>&lt;/article&gt;</literal> is generated.
 131                 </para>
 132         </listitem></varlistentry>
 133
 134         <varlistentry><term>--html</term><listitem>
 135                 <para>Generate documentation in HTML format.</para>
 136         </listitem></varlistentry>
 137
 138         <varlistentry><term>--ignore_case_when_linking</term><listitem>
 139                 <para>Ignore differences in case when creating cross links.
 140                     This is handy for languages such as Fortran or Pascal, but
 141                     in most cases it is better not to use it.</para>
 142         </listitem></varlistentry>
 143
 144         <varlistentry><term>--internal</term><listitem>
 145                 <para>Also include headers marked internal.</para>
 146         </listitem></varlistentry>
 147
 148         <varlistentry><term>--internalonly</term><listitem>
 149                 <para>Only include headers marked internal.</para>
 150         </listitem></varlistentry>
 151
 152         <varlistentry><term>--index</term><listitem>
 153                 <para>Also create a master index file.</para>
 154         </listitem></varlistentry>
 155
 156         <varlistentry><term>--lock</term><listitem>
 157                 <para> Per source file robodoc locks on the first header marker
 158                     it finds and will recognize only that particular header marker
 159                     for the remaining part of the file.  In addition it locks on
 160                     the first remark marker in each header and will recognize only
 161                     that particular remark marker for the remaining part of the
 162                     header.  </para>
 163         </listitem></varlistentry>
 164
 165         <varlistentry><term>--multidoc</term><listitem>
 166                 <para>Generate one document per source file, and copy the
 167                     directory hierarchy.</para>
 168         </listitem></varlistentry>
 169
 170         <varlistentry><term>--nosource</term><listitem>
 171                 <para>Do not include the SOURCE items.</para>
 172         </listitem></varlistentry>
 173
 174
 175         <varlistentry><term>--no_subdirectories</term><listitem>
 176                 <para>Do not create any subdirectories in the documentation directory
 177                 instead write all the documentation files in the root directory. The root directory is the one specified with <option>--doc</option>.</para>
 178         </listitem></varlistentry>
 179
 180
 181         <varlistentry><term>--nodesc</term><listitem>
 182                 <para>Do not scan any subdirectories, scan only the top level
 183                     directory of the source tree.</para>
 184         </listitem></varlistentry>
 185
 186         <varlistentry><term>--nosort</term><listitem>
 187                 <para>Do not sort the headers when generating the
 188                     documentation. The headers will appear in the same order in
 189                     the documentation as they appear in the source code.</para>
 190         </listitem></varlistentry>
 191
 192         <varlistentry id="nopre">
 193         <term id="nopre.term">--nopre</term><listitem>
 194                 <para>With this option ROBODoc does not generate preformatted
 195                     text when creating the item documentation. (Using
 196                     the <literal>&lt;PRE&gt;</literal> and
 197                     <literal>&lt;/PRE&gt;</literal> construction in HTML format
 198                     for instance). Instead ROBODoc tries to deduce
 199                     the formatting from the indentation and special
 200                     characters. See <xref linkend="formatting"
 201                         endterm="formatting.title" />. This creates much better
 202                     looking documentation.
 203                 </para>
 204         </listitem></varlistentry>
 205
 206         <varlistentry><term>--nogeneratedwith</term><listitem>
 207                 <para>Do not add the "generated with robodoc" message at the
 208                     top of each documentation file.</para>
 209         </listitem></varlistentry>
 210
 211         <varlistentry><term>--one_file_per_header</term><listitem>
 212                 <para>Create a separate documentation file for each header.
 213                 </para>
 214         </listitem></varlistentry>
 215
 216         <varlistentry><term>--rc</term><listitem>
 217                 <para>Use the specified file instead of <filename>robodoc.rc</filename>.
 218                 </para>
 219         </listitem></varlistentry>
 220
 221         <varlistentry><term>--rtf</term><listitem>
 222                 <para>Generate documentation in RTF format.</para>
 223         </listitem></varlistentry>
 224
 225         <varlistentry><term>--sections</term><listitem>
 226                 <para>Create sections based on the module hierarchy.</para>
 227         </listitem></varlistentry>
 228
 229         <varlistentry><term>--sectionnameonly</term><listitem>
 230                 <para>ROBODoc generates the section headers with names only,
 231                     no chapter numbers, no parent section names.</para>
 232         </listitem></varlistentry>
 233
 234
 235         <varlistentry><term>--singledoc</term><listitem>
 236                 <para> Define the documentation directory or documentation
 237                     file.</para>
 238         </listitem></varlistentry>
 239
 240         <varlistentry><term>--singlefile</term><listitem>
 241                 <para> Generate a single document from a single file </para>
 242         </listitem></varlistentry>
 243
 244         <varlistentry><term>--src</term><listitem>
 245                 <para> Define the path for the source directory or source
 246                     file.  The path can start with <literal>./</literal> or
 247                     <literal>/</literal>.  Do not use <literal>..</literal> in the
 248                     path.  </para>
 249         </listitem></varlistentry>
 250
 251         <varlistentry><term>--tabsize</term><listitem>
 252                 <para>Lets you specify the tab size.</para>
 253         </listitem></varlistentry>
 254
 255         <varlistentry><term>--tabstops</term><listitem>
 256                 <para>Specify tab stop locations in a comma separated list.</para>
 257                 <para>
 258                   Example: <option>--tabstops 10,20,40,80</option>
 259                 </para>
 260         </listitem></varlistentry>
 261
 262         <varlistentry><term>--toc</term><listitem>
 263                 <para>Add a table of contents. This works in multidoc mode as
 264                     well as singledoc mode.</para>
 265         </listitem></varlistentry>
 266
 267         <varlistentry><term>--latex</term><listitem>
 268                 <para>Generate documentation in <literal>LaTeX</literal> format.</para>
 269         </listitem></varlistentry>
 270
 271         <varlistentry><term>--tell</term><listitem>
 272                 <para>ROBODoc tells you what steps it is taking.</para>
 273         </listitem></varlistentry>
 274
 275         <varlistentry><term>--documenttitle</term><listitem>
 276                 <para>Specify the Title of the whole documentation.</para>
 277         </listitem></varlistentry>
 278
 279         <varlistentry><term>--altlatex</term><listitem>
 280                 <para>Alternate <literal>LaTeX</literal> file format
 281                 (bigger / clearer than normal).
 282                 </para>
 283         </listitem></varlistentry>
 284
 285         <varlistentry><term>--latexparts</term><listitem>
 286                 <para>Make the first module level as <literal>PART</literal>
 287                 in <literal>LaTeX</literal> output
 288                 (Gives you one more subsection level).</para>
 289         </listitem></varlistentry>
 290
 291         <varlistentry id="syntaxcolors_enable">
 292         <term id="syntaxcolors_enable.term">--syntaxcolors_enable</term><listitem>
 293                 <para>Enable only specific syntax highlighting features in
 294                 <literal>SOURCE</literal> items (<literal>HTML</literal> only).</para>
 295                 <para>Usage:
 296                   <option>--syntaxcolors_enable
 297                   quotes,squotes,line_comments,block_comments,keywords,non_alpha</option>
 298                 </para>
 299                 <para><itemizedlist>
 300                   <listitem><option>quotes</option>
 301                     -- Enable highlighting of <literal>"string literals"
 302                   </literal></listitem>
 303                   <listitem><option>squotes</option>
 304                     -- Enable highlighting of <literal>'string literals'
 305                   </literal></listitem>
 306                   <listitem id="syntaxcolors_enable_line_comments">
 307                     <option id="syntaxcolors_enable_line_comments.option">line_comments</option>
 308                     -- Enable highlighting of comments that span until the end of lines
 309                     (See <xref linkend="linecomments" endterm="linecomments.title" />)
 310                   </listitem>
 311                   <listitem id="syntaxcolors_enable_block_comments">
 312                   <option id="syntaxcolors_enable_block_comments.option">block_comments</option>
 313                     -- Enable highlighting of block comments
 314                     (See <xref linkend="remark_begin_end" endterm="remark_begin_end.title" />)
 315                   </listitem>
 316                   <listitem id="syntaxcolors_enable_keywords">
 317                     <option id="syntaxcolors_enable_keywords.option">keywords</option>
 318                     -- Enable highlighting of keywords
 319                     (See <xref linkend="keywords" endterm="keywords.title" />)
 320                   </listitem>
 321                   <listitem><option>non_alpha</option>
 322                     -- Enable highlighting of non alphanumeric characters
 323                     (like: <literal>#</literal>, <literal>$</literal>, <literal>%</literal>, etc...)
 324                   </listitem>
 325                 </itemizedlist></para>
 326                 <para>You don't need this if you have the
 327                   <option><xref linkend="cmode" endterm="cmode.term" /></option>
 328                   option specified.
 329                 </para>
 330                 <para> See also the
 331                   <option><xref linkend="syntaxcolors" endterm="syntaxcolors.term" /></option>
 332                   option.
 333                 </para>
 334         </listitem></varlistentry>
 335
 336         <varlistentry id="syntaxcolors">
 337         <term id="syntaxcolors.term">--syntaxcolors</term><listitem>
 338                 <para>Turn on all syntax highlighting features in <literal>SOURCE</literal>
 339                 items (<literal>HTML</literal> only).</para>
 340                 <para>This option equals to:
 341                   <option>--syntaxcolors_enable
 342                   quotes,squotes,line_comments,block_comments,keywords,non_alpha</option>
 343                 </para>
 344                 <para>You don't need this if you have the
 345                   <option><xref linkend="cmode" endterm="cmode.term" /></option>
 346                   option specified.
 347                 </para>
 348                 <para> See also the
 349                   <option><xref linkend="syntaxcolors_enable" endterm="syntaxcolors_enable.term" /></option>
 350                   option.
 351                 </para>
 352         </listitem></varlistentry>
 353
 354         <varlistentry><term>--dotname</term><listitem>
 355                 <para>Specify the name (and path / options) of
 356                 <literal>DOT</literal> tool.</para>
 357                 <para>See <xref linkend="tools" endterm="tools.title" />.</para>
 358         </listitem></varlistentry>
 359
 360         <varlistentry><term>--masterindex</term><listitem>
 361                 <para>Specify the title and filename of the master index page
 362                 </para>
 363                 <para>Usage:
 364                   <option>--masterindex
 365                   <replaceable>title</replaceable>,<replaceable>filename</replaceable>
 366                   </option>
 367                 </para>
 368                 <para>Example:
 369                   <option>--masterindex "Index Page,index"</option>
 370                 </para>
 371         </listitem></varlistentry>
 372
 373         <varlistentry><term>--sourceindex</term><listitem>
 374                 <para>Specify the title and filename of the source files index
 375                 page</para>
 376                 <para>Usage:
 377                   <option>--sourceindex
 378                   <replaceable>title</replaceable>,<replaceable>filename</replaceable>
 379                   </option>
 380                 </para>
 381                 <para>Example:
 382                   <option>--sourceindex "Source files,sources"</option>
 383                 </para>
 384         </listitem></varlistentry>
 385
 386         <varlistentry><term>--header_breaks</term><listitem>
 387                 <para>If a header has multiple names, ROBODoc can insert line breaks after every
 388                 specified number of header names to improve readability. If you do not specify this
 389                 option, ROBODoc will insert a line break after every two header names. Set it to
 390                 zero to disable the line breaks.</para>
 391                 <para>
 392                   Example: <option>--header_breaks 3</option>
 393                 </para>
 394         </listitem></varlistentry>
 395
 396     </variablelist>
 397
 398 </section>
 399
 400