5 <title id="options.title">Options</title>
7 <para>The behavior of ROBODoc can be further fine-tune with a large number of
11 <!-- TODO make a varlist from this -->
12 <varlistentry><term>-c</term><listitem>
13 <para>Show the copyright message.</para>
14 </listitem></varlistentry>
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>
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>
27 <varlistentry><term>--dbxml</term><listitem>
28 <para>Generate documentation in XML DocBook format.</para>
29 </listitem></varlistentry>
31 <varlistentry><term>--debug</term><listitem>
32 <para>Works like --tell, bug gives a lot more information.</para>
33 </listitem></varlistentry>
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>
45 <command>--doc ./documents</command>
48 <command>--src ./Everything</command>
50 <command>--doc ./Everything</command>
53 </listitem></varlistentry>
55 <varlistentry><term>--doctype_name</term><listitem>
56 <para>DocBook output requires a <literal><!DOCTYPE></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>.
62 robodoc --src test --doc test
63 --doctype_location "-//OASIS//DTD Simplified DocBook XML V1.1//EN"
64 --doctype_name docbook-simple/sdocbook.dtd
68 results in the following docbook file with the following head:
71 <!DOCTYPE article PUBLIC "-//OASIS//DTD Simplified DocBook XML V1.1//EN"
72 "docbook-simple/sdocbook.dtd">
75 </listitem></varlistentry>
77 <varlistentry><term>--doctype_location</term><listitem>
78 <para>See <command>--doctype_name</command>.</para>
79 </listitem></varlistentry>
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>
86 <para>For html output this means that no
87 <literal><html><head> ..... <body></literal>
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>
100 <para>For XML DocBook output this means no
101 <literal><!DOCTYPE></literal>,
102 <literal><article></literal>, and
103 <literal><articleinfo></literal> is generated.
106 </listitem></varlistentry>
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.
113 </listitem></varlistentry>
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>
120 <para>For html output this means that no
121 <literal></body></html></literal>
125 <para>For LaTeX output this means no
126 <literal>\end{document}</literal> is generated.
129 <para>For XML DocBook output this means no
130 <literal></article></literal> is generated.
132 </listitem></varlistentry>
134 <varlistentry><term>--html</term><listitem>
135 <para>Generate documentation in HTML format.</para>
136 </listitem></varlistentry>
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>
144 <varlistentry><term>--internal</term><listitem>
145 <para>Also include headers marked internal.</para>
146 </listitem></varlistentry>
148 <varlistentry><term>--internalonly</term><listitem>
149 <para>Only include headers marked internal.</para>
150 </listitem></varlistentry>
152 <varlistentry><term>--index</term><listitem>
153 <para>Also create a master index file.</para>
154 </listitem></varlistentry>
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
163 </listitem></varlistentry>
165 <varlistentry><term>--multidoc</term><listitem>
166 <para>Generate one document per source file, and copy the
167 directory hierarchy.</para>
168 </listitem></varlistentry>
170 <varlistentry><term>--nosource</term><listitem>
171 <para>Do not include the SOURCE items.</para>
172 </listitem></varlistentry>
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>
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>
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>
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><PRE></literal> and
197 <literal></PRE></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.
204 </listitem></varlistentry>
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>
211 <varlistentry><term>--one_file_per_header</term><listitem>
212 <para>Create a separate documentation file for each header.
214 </listitem></varlistentry>
216 <varlistentry><term>--rc</term><listitem>
217 <para>Use the specified file instead of <filename>robodoc.rc</filename>.
219 </listitem></varlistentry>
221 <varlistentry><term>--rtf</term><listitem>
222 <para>Generate documentation in RTF format.</para>
223 </listitem></varlistentry>
225 <varlistentry><term>--sections</term><listitem>
226 <para>Create sections based on the module hierarchy.</para>
227 </listitem></varlistentry>
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>
235 <varlistentry><term>--singledoc</term><listitem>
236 <para> Define the documentation directory or documentation
238 </listitem></varlistentry>
240 <varlistentry><term>--singlefile</term><listitem>
241 <para> Generate a single document from a single file </para>
242 </listitem></varlistentry>
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
249 </listitem></varlistentry>
251 <varlistentry><term>--tabsize</term><listitem>
252 <para>Lets you specify the tab size.</para>
253 </listitem></varlistentry>
255 <varlistentry><term>--tabstops</term><listitem>
256 <para>Specify tab stop locations in a comma separated list.</para>
258 Example: <option>--tabstops 10,20,40,80</option>
260 </listitem></varlistentry>
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>
267 <varlistentry><term>--latex</term><listitem>
268 <para>Generate documentation in <literal>LaTeX</literal> format.</para>
269 </listitem></varlistentry>
271 <varlistentry><term>--tell</term><listitem>
272 <para>ROBODoc tells you what steps it is taking.</para>
273 </listitem></varlistentry>
275 <varlistentry><term>--documenttitle</term><listitem>
276 <para>Specify the Title of the whole documentation.</para>
277 </listitem></varlistentry>
279 <varlistentry><term>--altlatex</term><listitem>
280 <para>Alternate <literal>LaTeX</literal> file format
281 (bigger / clearer than normal).
283 </listitem></varlistentry>
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>
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>
296 <option>--syntaxcolors_enable
297 quotes,squotes,line_comments,block_comments,keywords,non_alpha</option>
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" />)
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" />)
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" />)
321 <listitem><option>non_alpha</option>
322 -- Enable highlighting of non alphanumeric characters
323 (like: <literal>#</literal>, <literal>$</literal>, <literal>%</literal>, etc...)
325 </itemizedlist></para>
326 <para>You don't need this if you have the
327 <option><xref linkend="cmode" endterm="cmode.term" /></option>
331 <option><xref linkend="syntaxcolors" endterm="syntaxcolors.term" /></option>
334 </listitem></varlistentry>
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>
344 <para>You don't need this if you have the
345 <option><xref linkend="cmode" endterm="cmode.term" /></option>
349 <option><xref linkend="syntaxcolors_enable" endterm="syntaxcolors_enable.term" /></option>
352 </listitem></varlistentry>
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>
360 <varlistentry><term>--masterindex</term><listitem>
361 <para>Specify the title and filename of the master index page
364 <option>--masterindex
365 <replaceable>title</replaceable>,<replaceable>filename</replaceable>
369 <option>--masterindex "Index Page,index"</option>
371 </listitem></varlistentry>
373 <varlistentry><term>--sourceindex</term><listitem>
374 <para>Specify the title and filename of the source files index
377 <option>--sourceindex
378 <replaceable>title</replaceable>,<replaceable>filename</replaceable>
382 <option>--sourceindex "Source files,sources"</option>
384 </listitem></varlistentry>
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>
392 Example: <option>--header_breaks 3</option>
394 </listitem></varlistentry>