16.4.18 Defining a Documentation format
GPS has support for textual (as opposed to binary format like PDF)
documentation format. A textual documentation format can be described
using external template files. This way, it is possible to add support
for new textual documentation format by providing a set of templates files.
The node name to define a new documentation format is docgen_backend
.
The attributes for this node are:
name (string)
- The name of the documentation format (for example HTML).
format (string)
- The format is either text or binary. Only text is
supported at the moment.
There are two categories of children. One is to describe the format
itself, the other is to specify the set of template to use. In the
latter case the children's name are ending with _template
:
extension
- The extension to use for the generated files. This name is also used
as part of the directory name under which the documentation is generated.
description
- A description about the documentation format. GPS uses this description
in the documentation selection dialog.
file_header_template
- Point to a template file used as header for each generated files.
file_footer_template
- Point to a template file used as footer for each generated files.
comment_template
- Point to a template file used to output comment strings.
keyword_template
- Point to a template file used to output keywords.
string_template
- Point to a template file used to output strings.
char_template
- Point to a template file used to output characters.
subtitle_template
- Point to a template file used to output a subtitle give its name, size and
indentation level.
package_desc_template
- Point to a template file used to output package's description.
package_template
- Point to a template file used to output the package declaration or
ending.
with_template
- Point to a template file used to output with clauses.
variable_template
- Point to a template file used to output variables declarations.
exception_template
- Point to a template file used to output exception declaration.
type_template
- Point to a template file used to output type declarations.
tagged_type_template
- Point to a template file used to output tagged types.
calls_references_template
- Point to a template file used to output subprograms calls.
caller_references_template
- Point to a template file used to output caller references.
entity_template
- Point to a template file used to output entity.
subprogram_template
- Point to a template file used to output subprograms.
header_template
- Point to a template file used to output the start a package description.
footer_template
- Point to a template file used to output the end of a package description.
private_header_template
- Point to a template file used to output the start of package's private section.
main_frame_template
- Point to a template file used to output the main file (the file
index.html in the HTML backend for example).
unit_index_header_template
- Point to a template file used to output the units index header.
subprogram_index_header_template
- Point to a template file used to output the subprograms index header.
type_index_header_template
- Point to a template file used to output the types index header.
tagged_type_index_header_template
- Point to a template file used to output the tagged types index header.
item_index_template
- Point to a template file used to output an item index.
tagged_type_index_template
- Point to a template file used to output the tagged types index.
private_index_header_template
- Point to a template file used to output the private types index header.
public_index_header_template
- Point to a template file used to output the public types index header.
index_footer_template
- Point to a template file used to output the end of indexes.
block_template
- Point to a template file used to output block of text with a reference.
link_template
- Point to a template file used to output all cross references.
description_template
- Point to a template file used to output subprograms description based
on comments found just below its spec.
All template files are given as relative path. GPS will first look for the
template file under share/gps/docgen
and if not found it looks
under $HOME/.gps/docgen
.
A template file is a file that contains tags and commands. Those files
are parsed by the Templates Parser
module as found in
AWS
. We give hereafter a short description of this format, for
a complete description see the Templates Parser User's Guide.
simple tag
- A simple tag is surrounded by
@_
and _@
like in
@_NAME_@
. The templates engine will replace @_NAME_@
with the value associated with the tag named NAME
.
vector tag
- A vector tag contains a set of values. Each value will be used in
sequence if the tag appears inside a
TABLE
command tag.
For example, if the vector tag COLOR contains the three values Red,
Green and Blue then:
@@TABLE@@
> @_COLOR_@
@@END_TABLE@@
Will be expanded as:
> Red
> Green
> Blue
filter
-
Filters can be added to any tag. For example it is possible to output
all values in upper case by applying the
UPPER
filter in the previous
example.
@@TABLE@@
> @_UPPER:COLOR_@
@@END_TABLE@@
Will be expanded as:
> RED
> GREEN
> BLUE
It exists many filters, see the Template Parser User's Guide for a
complete description.
Note that each HTML template files, provided with GPS, contains a
complete description of the usage of each tag in the header comments.