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.