X-Git-Url: https://git.stg.codes/stg.git/blobdiff_plain/0c9c28efcd43f53ac54aa60b2dfefa69c70dbadf..6b6d9b29e9e9e91f79507a8bf193fb30de311dcc:/doc/help/xslt/common/common.xml diff --git a/doc/help/xslt/common/common.xml b/doc/help/xslt/common/common.xml new file mode 100644 index 00000000..da79980e --- /dev/null +++ b/doc/help/xslt/common/common.xml @@ -0,0 +1,622 @@ + + + + + Common » Base Template Reference + + $Id: common.xsl 8784 2010-07-28 12:32:54Z mzjn $ + + + + + Introduction + +This is technical reference documentation for the “base” + set of common templates in the DocBook XSL Stylesheets. + + +This is not intended to be user documentation. It is + provided for developers writing customization layers for the + stylesheets. + + + + + +is.component +Tests if a given node is a component-level element + + +<xsl:template name="is.component"> +<xsl:param name="node" select="."/> + ... +</xsl:template> + +Description + +This template returns '1' if the specified node is a component +(Chapter, Appendix, etc.), and '0' otherwise. + +Parameters + + +node + + +The node which is to be tested. + + + + + +Returns + +This template returns '1' if the specified node is a component +(Chapter, Appendix, etc.), and '0' otherwise. + + + + + +is.section +Tests if a given node is a section-level element + + +<xsl:template name="is.section"> +<xsl:param name="node" select="."/> + ... +</xsl:template> + +Description + +This template returns '1' if the specified node is a section +(Section, Sect1, Sect2, etc.), and '0' otherwise. + +Parameters + + +node + + +The node which is to be tested. + + + + + +Returns + +This template returns '1' if the specified node is a section +(Section, Sect1, Sect2, etc.), and '0' otherwise. + + + + + +section.level +Returns the hierarchical level of a section + + +<xsl:template name="section.level"> +<xsl:param name="node" select="."/> + ... +</xsl:template> + +Description + +This template calculates the hierarchical level of a section. +The element sect1 is at level 1, sect2 is +at level 2, etc. + + + +Recursive sections are calculated down to the fifth level. + +Parameters + + +node + + +The section node for which the level should be calculated. +Defaults to the context node. + + + + + +Returns + +The section level, 1, 2, etc. + + + + + + +qanda.section.level +Returns the hierarchical level of a QandASet + + +<xsl:template name="qanda.section.level"/> + +Description + +This template calculates the hierarchical level of a QandASet. + + +Returns + +The level, 1, 2, etc. + + + + + + +select.mediaobject +Selects and processes an appropriate media object from a list + + +<xsl:template name="select.mediaobject"> +<xsl:param name="olist" select="imageobject|imageobjectco |videoobject|audioobject|textobject"/> + ... +</xsl:template> + +Description + +This template takes a list of media objects (usually the +children of a mediaobject or inlinemediaobject) and processes +the "right" object. + + + +This template relies on a template named +"select.mediaobject.index" to determine which object +in the list is appropriate. + + + +If no acceptable object is located, nothing happens. + +Parameters + + +olist + + +The node list of potential objects to examine. + + + + + +Returns + +Calls <xsl:apply-templates> on the selected object. + + + + + +select.mediaobject.index +Selects the position of the appropriate media object from a list + + +<xsl:template name="select.mediaobject.index"> +<xsl:param name="olist" select="imageobject|imageobjectco |videoobject|audioobject|textobject"/> +<xsl:param name="count">1</xsl:param> + ... +</xsl:template> + +Description + +This template takes a list of media objects (usually the +children of a mediaobject or inlinemediaobject) and determines +the "right" object. It returns the position of that object +to be used by the calling template. + + + +If the parameter use.role.for.mediaobject +is nonzero, then it first checks for an object with +a role attribute of the appropriate value. It takes the first +of those. Otherwise, it takes the first acceptable object +through a recursive pass through the list. + + + +This template relies on a template named "is.acceptable.mediaobject" +to determine if a given object is an acceptable graphic. The semantics +of media objects is that the first acceptable graphic should be used. + + + + +If no acceptable object is located, no index is returned. + +Parameters + + +olist + + +The node list of potential objects to examine. + + + +count + + +The position in the list currently being considered by the +recursive process. + + + + + +Returns + +Returns the position in the original list of the selected object. + + + + + +is.acceptable.mediaobject +Returns '1' if the specified media object is recognized + + +<xsl:template name="is.acceptable.mediaobject"> +<xsl:param name="object"/> + ... +</xsl:template> + +Description + +This template examines a media object and returns '1' if the +object is recognized as a graphic. + +Parameters + + +object + + +The media object to consider. + + + + + +Returns + +0 or 1 + + + + + +check.id.unique +Warn users about references to non-unique IDs + + +<xsl:template name="check.id.unique"> +<xsl:param name="linkend"/> + ... +</xsl:template> + +Description + +If passed an ID in linkend, +check.id.unique prints +a warning message to the user if either the ID does not exist or +the ID is not unique. + + + + + +check.idref.targets +Warn users about incorrectly typed references + + +<xsl:template name="check.idref.targets"> +<xsl:param name="linkend"/> +<xsl:param name="element-list"/> + ... +</xsl:template> + +Description + +If passed an ID in linkend, +check.idref.targets makes sure that the element +pointed to by the link is one of the elements listed in +element-list and warns the user otherwise. + + + + + +copyright.years +Print a set of years with collapsed ranges + + +<xsl:template name="copyright.years"> +<xsl:param name="years"/> +<xsl:param name="print.ranges" select="1"/> +<xsl:param name="single.year.ranges" select="0"/> +<xsl:param name="firstyear" select="0"/> +<xsl:param name="nextyear" select="0"/> + ... +</xsl:template> + +Description + +This template prints a list of year elements with consecutive +years printed as a range. In other words: + + +<year>1992</year> +<year>1993</year> +<year>1994</year> + + +is printed 1992-1994, whereas: + + +<year>1992</year> +<year>1994</year> + + +is printed 1992, 1994. + + + +This template assumes that all the year elements contain only +decimal year numbers, that the elements are sorted in increasing +numerical order, that there are no duplicates, and that all the years +are expressed in full century+year +(1999 not 99) notation. + +Parameters + + +years + + +The initial set of year elements. + + + +print.ranges + + +If non-zero, multi-year ranges are collapsed. If zero, all years +are printed discretely. + + + +single.year.ranges + + +If non-zero, two consecutive years will be printed as a range, +otherwise, they will be printed discretely. In other words, a single +year range is 1991-1992 but discretely it's +1991, 1992. + + + + + +Returns + +This template returns the formatted list of years. + + + + + +find.path.params +Search in a table for the "best" match for the node + + +<xsl:template name="find.path.params"> +<xsl:param name="node" select="."/> +<xsl:param name="table" select="''"/> +<xsl:param name="location"> + <xsl:call-template name="xpath.location"> + <xsl:with-param name="node" select="$node"/> + </xsl:call-template> + </xsl:param> + ... +</xsl:template> + +Description + +This template searches in a table for the value that most-closely +(in the typical best-match sense of XSLT) matches the current (element) +node location. + + + + + +string.upper +Converts a string to all uppercase letters + + +<xsl:template name="string.upper"> +<xsl:param name="string" select="''"/> + ... +</xsl:template> + +Description + +Given a string, this template does a language-aware conversion +of that string to all uppercase letters, based on the values of the +lowercase.alpha and +uppercase.alpha gentext keys for the current +locale. It affects only those characters found in the values of +lowercase.alpha and +uppercase.alpha. All other characters are left +unchanged. + +Parameters + + +string + + +The string to convert to uppercase. + + + + + + + + + +string.lower +Converts a string to all lowercase letters + + +<xsl:template name="string.lower"> +<xsl:param name="string" select="''"/> + ... +</xsl:template> + +Description + +Given a string, this template does a language-aware conversion +of that string to all lowercase letters, based on the values of the +uppercase.alpha and +lowercase.alpha gentext keys for the current +locale. It affects only those characters found in the values of +uppercase.alpha and +lowercase.alpha. All other characters are left +unchanged. + +Parameters + + +string + + +The string to convert to lowercase. + + + + + + + + + +select.choice.separator +Returns localized choice separator + + +<xsl:template name="select.choice.separator"/> + +Description + +This template enables auto-generation of an appropriate + localized "choice" separator (for example, "and" or "or") before + the final item in an inline list (though it could also be useful + for generating choice separators for non-inline lists). + + +It currently works by evaluating a processing instruction + (PI) of the form <?dbchoice choice="foo"?> : + + + + if the value of the choice + pseudo-attribute is "and" or "or", returns a localized "and" + or "or" + + + otherwise returns the literal value of the + choice pseudo-attribute + + + + The latter is provided only as a temporary workaround because the + locale files do not currently have translations for the word + or. So if you want to generate a a + logical "or" separator in French (for example), you currently need + to do this: + <?dbchoice choice="ou"?> + + + + +The dbchoice processing instruction is + an unfortunate hack; support for it may disappear in the future + (particularly if and when a more appropriate means for marking + up "choice" lists becomes available in DocBook). + + + + + + +evaluate.info.profile +Evaluates an info profile + + +<xsl:template name="evaluate.info.profile"> +<xsl:param name="profile"/> +<xsl:param name="info"/> + ... +</xsl:template> + +Description + +This template evaluates an "info profile" matching the XPath + expression given by the profile + parameter. It relies on the XSLT evaluate() + extension function. + + + +The value of the profile parameter + can include the literal string $info. If found + in the value of the profile parameter, the + literal string $info string is replaced with + the value of the info parameter, which + should be a set of *info nodes; the + expression is then evaluated using the XSLT + evaluate() extension function. + + Parameters + + + + profile + + +A string representing an XPath expression + + + + + info + + +A set of *info nodes + + + + + + Returns + +Returns a node (the result of evaluating the + profile parameter) + + + +