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.