This is the documentation for SET's Documentation Generator.
Copyright © 1997,1998,1999,2000 Salvador Eduardo Tropea
This documentation may be freely distributed, provided this copyright notice is left intact on all copies.
The following master menu lists the major topics in this documentation, including all the indices.
That's the documentation for the SET's Documentation Generator (SDG) program.
The objetive of the program is generate documentation of your source code using some special comments in your code. The program simplifies the task a lot because you don't need to type things like the prototype of your functions, file where the functions are located, class, etc.
E-Mail: Salvador Eduardo Tropea
Telephone: (+5411) 4759-0013
Postal Address:
Salvador E. Tropea
Curapaligüe 2124
(1678) Caseros - 3 de Febrero
Prov: Buenos Aires
Argentina
Even when SDG is a complex tool you can use it without a deep knowledge of the program. This chapter explains the basic steps to use SDG, you'll consult the advanced reference for an in deep explanation.
You must add some special comments in your code. To make the task easier I created some pseudo-macros for my editor; they are /t and /d and are expanded to:
/**[txh]**********************************************************************
Function:
Class:
Include:
Module:
Prototype:
Description:
Return:
Example:
*****************************************************************************/
/**[txh]**********************************************************************
Description:
Return:
Example:
*****************************************************************************/
You must fill one or more of these fields. Some of them are filled automatically. The following table shows how these fields work.
| Variable | Meaning | Behavior |
|---|---|---|
Function | Is the name of the function | Automatic (type 5) |
Class | Used for member functions | Automatic (type 4) |
Include | Is the file that contains the prototype | Semiautomatic (type 2) |
Module | The module, library or category of the function | Semiautomatic (type 2) |
Prototype | The prototype of the function | Automatic (type 3) |
Description | How the function works | Manual (type 1) |
Return | Value returned; type and meaning | Manual (type 1) |
Example | How to use it | Manual (type 1) |
/t macro is normally used for the first function in your file; it sets the Include and
Module fields for the rest of the functions. As Function, Class and Prototype are filled automatically most of the time
you'll need to use the /d macro. Additionally you'll need to add very complet comments for inline members because their prototypes are declared in the class and hence the program can't fill the fields automatocally.
If you want to get a better result you can add another comments to your sources. These comments looks like this:
/**[txh]**********************************************************************
XXXXX:
Comments:
*****************************************************************************/
The field XXXXX can be one of the following: Class or Module. This special comment can be used ones per class or module and is the
description of this class or module. Comments is a
Variables type 6 .
2.2 What can I assign to the fields?
SDG have some macro and formating facilties. SDG defines some macros and you can define your own macros in the format file. Because SDG must recognize the macros some characters have an special meaning and you aren't totally free to use them.
As this section is a little hard I'll provide a little subsection explaining the basic concepts. If you are in a hurry or read only this first section.
The macros starts with @ so you can put a single @ in your comments. If you need to put a @ use two, like this @@.
SDG have some special macros hardcoded they are @p, @* and @x. Use @p to indicate an end of paragraph and
@* to break a line inside of a paragraph.
The syntax for cross references is more complex so I'll show you it with some examples.
@<subtitle>{That's a subtitle with a }}
SDG can be confused by the } and end the title in the wrong place. To avoid it use @{ and @}.
2.2.2 More about cross references
As you saw in the previous chapter is hard to explain what's the syntax for it so here is a detailed explanation on how it works.
To understand it better you must know more about what's generated by a cross reference, for it consult the Commands section .
Basically a cross reference have two parts; the visible name and the name of the node pointed by it. In the following explanations I'll call 0 to the visible name and 1 to the node. The available cases are:
@x{A,B} here 0 is A and 1 is B.
@x{A} here 0 and 1 contains A.
@x{::A} here 0 is A and 1 is A (class name).
@x{A::B} here 0 is B and 1 is B (A).
SDG first fills the values of the variables 0 and 1 and then expands the code defined for the cross reference.
The general syntax for the macros is:
@<Macro Name>{List of parameters}
The parameters are separated by ,. You can't use } and { inside the parameters. Use @{ and @} instead. For similar reasons you can't use
> in the name of the macro; use @> instead.
You can use @{ and @} in any place safetly but is necesary only in the case named above. You can define your own macros, for that look the DefinedCommands section .
The parameters of the macros are passed by the macro expander so you can use macros here too. For example:
@<xx@>>{That's @<xx2>{too} complex @} thing}
That will call to the macro xx> passing to it:
That's @<xx2>{too} complex @} thing
As the parameter 0, then it will evaluate the parameter calling to the macro xx2 passing the word too as parameter 0. As you can see you can make complex things with it but SDG wasn't designed to be a complex interpreter so be carreful and be aware that you'll find some limitations.
The number of parameters passed to a macro can be range from zero to ten. You can use the following syntax for zero parameters:
@<Macro Name>
If the name of the macro doesn't match with any defined macro you won't get a warning, instead SDG will output the name of the macro as-is. As an example you can generate an HTML tag making the
following:
@<<any tag@>>
That's no recomended because you are limiting the output format to HTML but you can do it.
2.3 What I will get after adding it?
SDG will generate a documentation with:
2.4 What other thing are needed to be tunned?
SDG uses a .fmt file to generate the documentation. You'll need to tune some constants of the section [Replace] of this file.
These constants controls the name of the documentation and other similar things. They are dependent of the format generated so I can make a general description of these constants.
3 How to control the generated documentation
This chapter explains how to configure SDG. SDG is very versatile and can be configured to behave very different to the original configuration.
SDG uses a format file (.fmt) to generate the documentation. Actually I have two format files; one for .info, .html and .txt files and other for
.html files. The former is called multi.fmt and the last is called html.fmt.If you are wondering why I have a separated file for .html when the
other works for HTML the answer is easy; html.fmt generated much better .html files and doesn't need the help of makeinfo.
The syntax used in format files is tricky but is easy for easy tasks.
Format files are divided in sections. Each section is started by a label with the following format: [Section name]. The rules are the following:
[ must be in the first column.
] delimites the name and the rest of the characters are ignored.
# or a blanck character is ignored. There are exceptions for it. In the Replace section the variables defined are strings, these strings
can use more than one line; inside of these strings you can't use comments. In the Gen* sections the # are allowed but the blank lines aren't skipped. Even
when these rules can look a little stupid now you'll see they are logic. The lines are limited to 200 characters, if they are longer will be cutted.
Here is a list of the sections of the format file.
This section indicates what programs are used to generate the documentation and what formats are generated with this format file. An example is:
CommandLine=makeinfo --no-validate --fill-column 78 -o ~1.info ~0
Name=Info (.info) file format
CommandLine=makeinfo --no-validate --fill-column 78 -Dhtml -o ~1.html ~0
Name=HTML file format
CommandLine=makeinfo --no-validate --fill-column 78 -Dtext -o ~1.txt ~0
Name=Text (.txt) file format
That indicates that three formats are generated. CommandLine must be used before Name and you must provide pairs.
This variable indicates what program is called. The ~0 mark is replaced by the name of the temporary file created by SDG. ~1 is replaced by the name of the outuput file, you must provide the extention.
If you need a long command line or various commands use a batch or script file.
This variable indicates the name of the format generated, make it descriptive but avoid making it too long.
This section defines the delimiters used to detect the special comments. SDG will search for these delimiters in the source files. For example:
SectionStart=/**[txh]**
SectionEnd=*********/
This variable defines the start of the comments. The variable is limited to 11 characters. A line containing it will be taked as the start of the comment and the rest of the line will be discarded.
This variable defines the end of the special comments. The variable is limited to 11 characters. A line containing it will be taked as the end of the special comment and the rest of the line will be discarded.
This is a very important section; it defines the fields recognized inside of the special comments.
You can define up to 16 variables. Each variable have a number; the first defined is the variable 0, the next 1, etc. The variable 0 is special and normally is used for the name of the functions because this variable is used for the main index and the associations.
Additionally there are some special variables created internally:
| Number | Meaning |
|---|---|
90 | Name of the file |
91 | Line number of the end of the comment |
92 | Name of the var 0 in the format: ~0 ~~Distinguish{(~Distinguish)~} (node name) |
To define a variable you'll use the following syntax:
AddDefinition=Name of Variable,Type
One problem that appears here is the fact that two functions can have the same name. To avoid problems you must avoid the automatic function name detection and put the name of the function by hand
adding to the name some thing to distinguish it from the other. A very special case is the one of the classes, is very common to find members with the same name in two classes. In this case is very hard to add some distinguish code by hand so SDG can do it automatically. For this you must say what other variable is the one used to make the difference. The syntax is:
Distinguish=Number of the variable
With that SDG will add the name of this variable to the name of the variable 0. If the variable doesn't exist for that function SDG will skip it. The distingish variable appears between parentheses.
For more information see the section
More about cross references . The allowed types for variables are:
These are normal variables they put your content if exist.
They are "Repeat" variables. If one of them appears in one comment the default for this variable is set with this value. If the variable doesn't exist in one comment SDG will use the default.
A good example is the Include variable. Normally all the functions of one source have your prototypes in one header so indicating that in the first comment SDG will assume that
all the functions are in the same include.
SDG provides two special values that you can use in the comments to stop the use of the default value. If you use ~no SDG will not use the default for this function. If you use
~clear SDG will delete the default value.
If this variable isn't in the comment SDG will try to replace it with the function prototype. It uses an heuristic so isn't perfect.
If this variable isn't in the comment SDG will try to replace it with the class of the function. It uses an heuristic so isn't perfect.
If this variable isn't in the comment SDG will try to replace it with the name of the function. It uses an heuristic so isn't perfect.
That's a very special kind of variables. They disable the node generation for this comment. The variable is stored in the first variable that have associations and is in the comment. Is used to create comments for modules and classes.
The associations are used to make groups of functions with a particular relation. You can define up to 8 associations. Each association associates the 0 variable and another variable.
That's used to create for example a list of classes and your members.
The syntax is the following:
AddAssoc=Title of the menu for it,Name of the node,Variable,Distinguish
SDG will create a chapter (node) for this list called Name of the node that will be available from the main menu with the name Title of the menu for it.
Additionally to distinguish this chapter from the name of a function SDG will add the Distinguish string, that's optional.
A good example for Distinguish are classes where the constructor could make a collition with the class name.
Here is an example:
AddAssoc=List by classes,Classes,1,(class)
AddAssoc=List by modules,Modules,3
AddAssoc=List by files,Files,90
This section is used to define constants that can be called latter in the Gen* section.
Each constant have the following syntax:
Constant="Value"
Value can be extended various lines and is ended with the second ". You can use macros , inside the constants. An example is:
Constant="This document describes the functions of my library
@p
This document applies to version 0.0.1
of the program named A Real World
@p"
This section controls the the hardcoded macros of SDG.
There are three hardcoded macros they are:
@p and you can define the code generated by it setting the variable EndOfPar.
@* and you can control it with the BreakLine variable.
@x{parameters}. The generated code is controled by CrossRef. This macro takes two parameters and you can indicate
where to put these values with the ~0 and ~1 markers.
makeinfo uses @ in a similar way that SDG you'll need to indicate that this sequence must be passed
as-is to makeinfo. For this you can use the Double@ variable. The following is an example of these variables for the HTML format:
EndOfPar=<p>
BreakLine=<br>
CrossRef=<a href="#~1">~0</a>
Double@=
For more information see the section
More about cross references . This section defines the user macros. The syntax is the following:
Name of macro=Code generated
You can recall the values of the parameters in the Code generated part using the ~n markers. For more information about how ~n works look
the
GenNode section . An example is:
subtitle=<Font Size=+1><u>~0</u></Font><p>
With this definition the following code
@<subtitle>{Hello}
Will generate:
<Font Size=+1><u>Hello</u></Font><p>
Read the "More about macros" section for more information about it.
More about macros . This section is used to indicate how to handle special characters. A good example are the accents. The syntax is the following:
ASCII=code
Code will be passed directly to the output without expanding macros or escaping characters. This section is used to indicate what code is generated for each function. The text included in this function is processed in the following way:
GenNode section the variables are the variables from the
Variables section . So 0 to 15 are the fields of the comment and 90 to 92 are the values mentioned in that section. This section is used to indicate how to create a menu in the output file.
You must define three variables:
Start defines how to start a menu.
Entry defines how to create an entry in the menu. It takes two parameters, the parameter 1 is the name of the menu item and the parameter
2 is the cross reference to it.
End defines how to end a menu.
Here is the HTML code example:
Start=<Menu>
Entry=<li><a href="#~2">~1</a>
End=</Menu>
This section is used to indicate how to create the first node for an association. The text included in this function is processed in the way explained in the GenNode section .
The variables available are ~1 the name of the association and ~2 the menu for it generated with the information in the
GenMenu section .
See the GenAssoRest , for more information.
This section is used to indicate how to create the rest of the nodes for an association. The text included in this function is processed in the way explained in the GenNode section .
The variables available are ~1 the name of the association, ~2 is the same name but without the distingish, ~3 is the comment collected for
it using a
variable type 6 . and ~4 the menu for this association generated with the information in the
GenMenu section .
This section is used to indicate how to create the output file. The text included in this function is processed in the way explained in the GenNode section .
The variables available are ~1 the main menu, ~2 the name of the function list node, ~3 the menu for all the functions,
~4 the code for all the associations generated according to the information in the
GenAssoMain . and
GenAssoRest . sections and ~5 all the function nodes.
The menus are generated with the information in the
GenMenu section .
Additionally all the constants defined in the
Replace section , can be recalled adding 50 to it. For example the ~50 recalls the constant number 0, that's the first defined.