]>

# The documentation system of Foundry

## Overview

Foundry comes with a documentation system which creates the reference documentations for template tags and helper functions on the fly. The documentation system – which you using at the moment by the way – consists of three parts:

- An `index.jsp` file in the `doc` directory which invokes the XSL transformer. Using an JSP here has the advantage that the behaviour is similar to an `index.html`.
- Some XSL templates.
- And the documentation itself which consists of some XML files, some static texts and the documentation in the other templates.

The general structure of the documentation is defined by the `doc/foundry-documentation.xml` file. This file is the entry point for the XSL processor. The chapters of the documentation are defined by the `foundry:doc-chapter` elements. The sections of the chapters are defined using `foundry:doc-section` elements. The section which use static texts have a `static`. The value of the `static` attribute is the name of the file to include from the `doc/static-texts` directory. These files are normal HTML files in XML syntax. They must have a `main` element. Only the content of the `main` element is included into the documentation.

Sections which are generated on the fly from the XSL files of Foundry have a `generate` attribute. The `generate` attribute controls which documentations appear in the section.

## Documentation inside XSL templates

Templates, functions and global variables are documented using the `foundry:doc` element which is placed in the XSL directly before the element to document. The `foundry:doc` element has two mandatory attributes. The `section` elements is used to control in which section the documentation appears. The second attribute is the `type` attribute. This attribute is used to format the documentation. The possible values are:

`template-tag`
  The following XSL template is a tag which can be used in the layout templates.
`env-var`
  The following `xsl:variable` or `xsl:param` defines a global variable.
`function`
  The following `xsl:function` is a helper function which can be used in the implementation of template tags.
`function-template`
  The following `xsl:template` is a helper template.

A `foundry:doc` element can have to following child elements:

`foundry:doc-desc`
  A text describing the template, function or variable. The must be structured using HTML elements like `p`, even it is only a single paragraph. Otherwise the text is not copied into the documentation. Look at one of the XSL files of Foundry for an example.
`foundry:doc-attributes`
  Surrounds the documentation for attributes which can be used on a template tag. The individual attributes are documented by `foundry:doc-attribute` elements. The `foundry:doc-attribute` has a mandatory attribute `name` which contains the name of the attribute. The documentation of the attribute must be enclosed in HTML elements. Look at one of the XSL files of Foundry for an example.
`foundry:doc-parameters`
  Surrounds the documentation for parameters which can be used on a function. The individual parameters are documented by `foundry:doc-parameter` elements. The `foundry:doc-parameter` has a mandatory parameter `name` which contains the name of the parameter. The documentation of the parameter must be enclosed in HTML elements. Look at one of the XSL files of Foundry for an example.
`foundry:doc-see-also`
  Contains links to other parts of the documentation or the external resources. The links are defined using `foundry:doc-link` attributes. Each `foundry:doc-link` has a `href` attribute which the link. The description of the link is the content of the element.