$Id$ Walsh Norman 19992000 Norman Walsh This is technical reference documentation for the DocBook XSL Stylesheets; it documents (some of) the parameters, templates, and other elements of the stylesheets. This is not intended to be user documentation. It is provided for developers writing customization layers for the stylesheets, and for anyone who's interested in how it works. Although I am trying to be thorough, this documentation is known to be incomplete. Don't forget to read the source, too :-) Tests if a given node is a component-level element This template returns '1' if the specified node is a component (Chapter, Appendix, etc.), and '0' otherwise. node The node which is to be tested. This template returns '1' if the specified node is a component (Chapter, Appendix, etc.), and '0' otherwise. 1 0 Tests if a given node is a section-level element This template returns '1' if the specified node is a section (Section, Sect1, Sect2, etc.), and '0' otherwise. node The node which is to be tested. This template returns '1' if the specified node is a section (Section, Sect1, Sect2, etc.), and '0' otherwise. 1 0 Returns the hierarchical level of a section 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. node The section node for which the level should be calculated. Defaults to the context node. The section level, 1, 2, etc. 1 2 3 4 5 6 5 4 3 2 1 2 3 4 5 5 5 4 3 2 1 1 Returns the hierarchical level of a QandASet This template calculates the hierarchical level of a QandASet. The level, 1, 2, etc. 1 1 1 2 3 5 4 3 2 1 1 question answer qandadiv qandaset [FAMILY Given] , , [ ] { } [ ] ... | 4pi Selects and processes an appropriate media object from a list 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. olist The node list of potential objects to examine. Calls <xsl:apply-templates> on the selected object. Selects the position of the appropriate media object from a list 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. olist The node list of potential objects to examine. count The position in the list currently being considered by the recursive process. Returns the position in the original list of the selected object. 1 1 0 0 1 0 1 Returns '1' if the specified media object is recognized This template examines a media object and returns '1' if the object is recognized as a graphic. object The media object to consider. 0 or 1 0 1 1 1 0 . . Warn users about references to non-unique IDs 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. Error: no ID for constraint linkend: . Warning: multiple "IDs" for constraint linkend: . Warn users about incorrectly typed references 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. Error: linkend ( ) points to " " not (one of): Unexpected context in procedure.step.numeration: 1 2 loweralpha lowerroman upperalpha upperroman arabic arabic circle square disc Print a set of years with collapsed ranges This template prints a list of year elements with consecutive years printed as a range. In other words: 1992 1993 1994]]> is printed 1992-1994, whereas: 1992 1994]]> 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. 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. This template returns the formatted list of years. , , - , , , - , Search in a table for the "best" match for the node 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. / Converts a string to all uppercase letters 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. string The string to convert to uppercase. Converts a string to all lowercase letters 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. string The string to convert to lowercase. Returns localized choice separator 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). choice Evaluates an info profile 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. profile A string representing an XPath expression info A set of *info nodes Returns a node (the result of evaluating the profile parameter) Error: The "info profiling" mechanism currently requires an XSLT engine that supports the evaluate() XSLT extension function. Your XSLT engine does not support it. Logs/emits formatted notes and warnings The log.message template is a utility template for logging/emitting formatted messages – that is, notes and warnings, along with a given log "level" and an identifier for the "source" that the message relates to. level Text to log/emit in the message-level field to indicate the message level (Note or Warning) source Text to log/emit in the source field to identify the “source” to which the notification/warning relates. This can be any arbitrary string, but because the message lacks line and column numbers to identify the exact part of the source document to which it relates, the intention is that the value you pass into the source parameter should give the user some way to identify the portion of their source document on which to take potentially take action in response to the log message (for example, to edit, change, or add content). So the source value should be, for example, an ID, book/chapter/article title, title of some formal object, or even a string giving an XPath expression. context-desc Text to log/emit in the context-description field to describe the context for the message. context-desc-field-length Specifies length of the context-description field (in characters); default is 12 If the text specified by the context-desc parameter is longer than the number of characters specified in context-desc-field-length, it is truncated to context-desc-field-length (12 characters by default). If the specified text is shorter than context-desc-field-length, it is right-padded out to context-desc-field-length (12 by default). If no value has been specified for the context-desc parameter, the field is left empty and the text of the log message begins with the value of the message parameter. message Text to log/emit in the actual message field message-field-length Specifies length of the message field (in characters); default is 45 Outputs a message (generally, to standard error). 12 right right : : Get a title for the current document The get.doc.title template is a utility template for returning the first title found in the current document. Returns a string containing some identifying title for the current document . Right-pad or left-pad a string out to a certain length This function takes string padVar and pads it out in the direction rightLeft to the string-length length, using string padChar (a space character by default) as the padding string (note that padChar can be a string; it is not limited to just being a single character). This function began as a copy of Nate Austin's prepend-pad function in the Padding Content section of Dave Pawson's XSLT FAQ. Returns a (padded) string. left