ROBODoc can be configured with a configuration file called
robodoc.rc. With it you can define item
names, frequently used options, and translations for English
terms. One should note that if configuration file is specified,
its definitions over-ride ROBODoc internal (i.e. built-in) settings.
This is a feature; some arbitrary langugage may include syntax
which conflicts with ROBODoc's internal markers. By taking use
of a configuration file, these sort of issues and conflicts
can be circumvented.
An example is shown below.
# Example robodoc.rc
#
items:
NAME
SYNOPSIS
INPUTS
OUTPUTS
SIDE EFFECTS
HISTORY
BUGS
ignore items:
HISTORY
BUGS
source items:
SYNOPSIS
options:
--src ./source
--doc ./doc
--html
--multidoc
--index
--tabsize 8
headertypes:
e "Makefile Entries" robo_mk_entries
x "System Tests" robo_syst_tests
q Queries robo_queries
ignore files:
README
CVS
*.bak
*~
"a test_*"
accept files:
*.c
*.h
*.pl
header markers:
/****
#****
remark markers:
*
#
end markers:
****
#****
remark begin markers:
/*
remark end markers:
*/
The configuration file consists of a number of blocks.
Each block starts with a name followed by a
:. There are currently eight blocks:
items, ignore items, options, header types, ignore files,
header markers, remark markers, and end markers.
In each block you define a number of values. Each value must
start with at least one space.
In this block you can define the names of items that ROBODoc should recognize. Item names can consist of more than one word but should be written in all uppercase characters. Define one item name per line. You do not need to put quotes around them if they contain spaces.
If you do not define an items block ROBODoc uses its default list of item names. If you define an items block ROBODoc uses only those item names, any of the default items names (except SOURCE) are no longer recognized.
In this block you can define the names of items that ROBODoc should ignore when generating documentation. This can be useful if you want to create documentation for a client, but for instance do not want to include the history items and bugs items.
In this block you can define the names of items that ROBODoc handle in the same way as the SOURCE item.
In this block you can define frequently used options. The options you specify here are added to any options you specify on the command line.
In this block you can define your own headertypes. These are added to the existing headertypes. Each new headertype requires three parameters: the character used to indicate a header of this type, the title for this type as used in the master index, the name of the file in which the index this type is stored. If you use a character of an existing headertype, this headertype is overwritten.
In this block you can define the names of files or
directories that ROBODoc should ignore while scanning
the directory tree for source files. You can use the
wildcard symbols * and
?. If you use spaces in the expression
enclose the experssion in quotes.
For instance, the rc file above causes ROBODoc
to skip all README files, all files with
the name CVS (these are usually
directories). It also skips all files with a name that ends
with .bak or ~ or
that start with a test_
Normally you specify the names of directories here and do the filtering of file names with a accept files block.
In this block you can define the names of files that robodoc should accept. This test is carried out after the 'ignore files' filtering is performed. Any files that do not match the patterns in this block are ignored by ROBODoc.
If there is no accept files block all files are accepted.
In this block you define what ROBODoc will recognize as start of a header. If you use this block ROBODoc only recognizes these markers, any of the inbuild markers will be ignored.
In this block you define what ROBODoc will recognize as start of remark. If you use this block ROBODoc only recognizes these markers, any of the inbuild markers will be ignored.
In this block you define what ROBODoc will recognize as end of a header. If you use this block ROBODoc only recognizes these markers, any of the inbuild markers will be ignored.
In this block you define what ROBODoc will recognize as the begin of a remark block. This is used in
combination with the source items block. This allows robodoc to recognize that a header ends and source
begins. For example it makes it possible that ROBODoc interprets
int foo( float correction ) as code in the following header.
/****f* Bar/foo
* FUNCTION
* foo computues the foo factor.
* SYNOPSIS
*/
int foo( float correction )
/*
* BUGS
* no bugs.
*****/
{
return correction * 42.0;
}
In this block you define what ROBODoc will recognize as the begin of a remark block. See the previous block.
ROBODoc searches the your current directory for the
robodoc.rc file. If it can't find
it there it will search in $HOME/, then
$HOMEDRIVE$HOMEPATH/, and finally in
/usr/share/robodoc/.
With the --rc option can tell ROBODoc to
use a different file then robodoc.rc as
configuration file. The is handy if you want to create
documentation in different formats. For instance:
robodoc --rc htmlsingle.rc robodoc --rc rtfsingle.rc robodoc --rc htmlmulti.rc