XSLT Coding Conventions

This page lists coding conventions used in the XSLT transforms.

=General=


 * XSLT coding for the Open Siddur Project is in XSLT 2.0 Basic. Do not use schema-aware features.
 * xsl:stylesheet is used as the root element. (This avoids a bug in XSLTDoc which doesn't recognize xsl:transform)

=File management=


 * Each new XSLT transform must be listed in the common XML catalog under its filename.
 * Each new target format should have its own directory within the source tree

=Indentation=


 * Code is indented using spaces, where each indentation level (tab width) is 2 spaces wide.
 * Unless otherwise necessary, all lines should be fewer than 80 characters wide.

=Documentation=


 * Code is documented using XSLTDoc (Our version is distributed along with the source. It is modified from the original so it works correctly with XML catalogs.)
 * All stylesheets (transforms), templates, functions, global parameters and global variables must be documented.
 * All parameters to templates or functions should be documented when used.
 * The documentation should include a description of the input and output of the stylesheet, unless it would be repetitive of stylesheet-global documentation.

=Variables and parameters=


 * Variable and parameter names are lowercase, with words separated by a dash (-)
 * All variables and parameters should be typed with @as, unless there's a good reason not to (document it!).
 * The type should be as restrictive as possible.
 * Parameters to named templates may be tunneled or non-tunneled. Parameters to match templates must be tunneled.  This allows extension by chaining through xsl:next-match.

=Priorities=


 * Some priority levels are reserved. A list is here: insert list

=Templates=


 * Template names are lowercase, with words separated by a dash (-)

Modes

 * The default mode is the mode that performs the conversion from *either* the original format or an intermediate format to the destination format. Any conversions to intermediate formats should be done using non-default modes.
 * Avoid matching #all unless you really mean it.

=Functions=


 * Function names are lowercase, with words separated by a dash (-)
 * Functions must declare return types.

=Namespaces and prefixes=


 * The XSLT namespace is given the prefix `xsl`.
 * The XSLTDoc namespace is given the prefix `xd`.
 * The XML Schema namespace is given the prefix `xs`.
 * The TEI namespace is given the prefix `tei`.
 * The JLP namespace is given the prefix `j`.
 * XSLT extension functions have the namespace `http://jewishliturgy.org/ns/functions/xslt`. It is conventionally given the prefix `func`.

=Inclusion vs. import=


 * XSLT transforms that declare priorities are not importable (all their priorities will collapse on import), so they should be included once by the top-level stylesheet that uses them.
 * XSLT transforms that do not rely on priorities may be imported by any stylesheet that relies on them.
 * It is preferable to use xsl:import instead of xsl:include wherever feasible.