Extracting Documentation with ROBODoc

Extracting Documentation with ROBODoc
Prev		Next

Now that you have prepared your source code for use with ROBODoc you are ready to extract the documentation. There are several choices to be made.

Single document or many smaller documents

First of all, ROBODoc can be used in three modes.

multidoc -- in this mode ROBODoc scans all the source files in your source directory and creates a separate document file for each of these in a document directory. The document directory is created automatically. Its structure is a mirror of the structure of your source directory.
singledoc -- in this mode ROBODoc scans all the source files in your source directory and creates a single documentation file that contains all the documentation extracted from your source files.
singlefile -- in this mode ROBODoc scans a single source file and creates a single documentation file.

multidoc

The multidoc mode is useful to create browsable documents. For instance many small HTML files that can be viewed with a web-browser. This mode requires the following arguments:

robodoc {--src source directory} {--doc document directory} {--multidoc} [other options]

An additional option that is useful with this mode is --index, this creates a series of index files, one for each header type.

singledoc

The singledoc mode is useful to create bulk documentation that can be incorporated in other documents, or that can be delivered to a client as a single document. For instance a file created in RTF format can be included into a larger design document written in Word format. This mode requires the following arguments:

robodoc {--src source directory} {--doc document file without extension} {--singledoc} [other options]

An additional option that is useful with this mode is --sections, this causes the headers to follow a section layout based on the module element hierarchy defined in the header name.

singlefile

The singlefile mode is not very useful. It is mainly used for debugging purposes. This mode requires the following arguments:

robodoc {--src source file} {--doc document file} {--singlefile} [other options]

Output formats

Your next choice is the output format. ROBODoc can create documentation in several formats:

HTML, option --html
RTF, option --rtf
LaTeX, option --latex
XML DocBook, option --dbxml

What format to use depends on your wishes. If you want a single printable document, use LaTeX or XML DocBook. If you want a document that can be included into a larger (Word) document use RTF. If you want something that is browsable use HTML, or use XML DocBook and then convert it to HTML.

Options

The behavior of ROBODoc can be further fine-tune with a large number of options.

-c

Show the copyright message.

--cmode

Use ANSI C grammar in SOURCE items and use this for some syntax highlighting (HTML only).

--css

Use to content of the specified file to create the robodoc.css. The content of the file is copied into robodoc.css.

--dbxml

Generate documentation in XML DocBook format.

--debug

Works like --tell, bug gives a lot more information.

--doc

Define the path to the documentation directory or documentation file. A path can start with ./ or /. Do not use .. in the path. The documentation directory can be a subdirectory of the source directory, or be parallel to the source directory, however they can not be equal. So --src ./sources together with --doc ./documents is fine, but --src ./Everything together with --doc ./Everything is not.

--folds

Use fold marks to split a big document into smaller ones.

--headless

Do not create the head of a document. This allows you to create documents that can be included in other documents, or to which you can add your own style.

For html output this means that no <html><head> ..... <body> is generated.

For LaTeX output this means none of the document initialization code is generated, such as \documentclass{article} or \begin{document} is generated. If you use this option in combination with --footless you can use \include or \input commands to include the ROBODoc generated documents in a larger document.

For XML DocBook output this means no <!DOCTYPE>, <article>, and <articleinfo> is generated.

--footless

Do not create the foot of a document. This allows you to create documents that can be included in other documents, or to which you can add your own style.

For html output this means that no </body></html> is generated.

For LaTeX output this means no \end{document} is generated.

For XML DocBook output this means no </article> is generated.

--html

Generate documentation in HTML format.

--ignore_case_when_linking

Ignore differences in case when creating crosslinks. This is handy for languages such as Fortran or Pascal, but in most cases it is better not to use it.

--internal

Also include headers marked internal.

--internalonly

Only include headers marked internal.

--index

Also create a master index file.

--lock

Per source file robodoc locks on the first headermarker it finds and will recognize only that particular headermarker for the remaining part of the file. In addition it locks on the first remark marker in each header and will recognize only that particular remark marker for the remaining part of the header.

--multidoc

Generate one document per source file, and copy the directory hierarchy.

--nosource

Do not include the SOURCE items.

--nodesc

Do not scan any subdirectories, scan only the top level directory of the source tree.

--nosort

Do not sort the headers when generating the documentation. The headers will appear in the same order in the documentation as they appear in the source code.

--nopre

With this option ROBODoc does not generate preformatted text when creating the item documentation. (Using the <PRE> and </PRE> construction in HTML format for instance). Instead ROBODoc tries to deduce the formatting from the indentation and special characters. See Text Formatting. This creates much better looking documentation.

--nogeneratedwith

Do not add the "generated with robodoc" message at the top of each documentation file.

--rc

Use the specified file instead of robodoc.rc.

--rtf

Generate documentation in RTF format.

--sections

Create sections based on the module hierarchy.

--sectionnameonly

ROBODoc generates the section headers with names only, no chapter numbers, no parent section names.

--singledoc

Define the documentation directory or documentation file.

--singlefile

Generate a single document from a single file

--src

Define the path for the source directory or source file. The path can start with ./ or /. Do not use .. in the path.

--tabsize

Lets you specify the tabsize.

--toc

Add a table of contents. This works in multidoc mode as well as singledoc mode.

--latex

Generate documentation in LaTeX format.

--tell

ROBODoc tells you what steps it is taking.

Prev		Next
Preparing your source code for ROBODoc	Home	Customizing ROBODoc