From Open Siddur Project Development Wiki

This page lists coding conventions used in the XSLT transforms.

Contents 1 General 2 File management 3 Indentation 4 Documentation 5 Variables and parameters 6 Priorities 7 Templates 7.1 Modes 8 Functions 9 Namespaces and prefixes 10 Inclusion vs. import

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

Reserved for |

template must match before any other templates |

template is the default fallback |

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.