X-Git-Url: https://git.stg.codes/stg.git/blobdiff_plain/0c9c28efcd43f53ac54aa60b2dfefa69c70dbadf..6b6d9b29e9e9e91f79507a8bf193fb30de311dcc:/doc/help/xslt/common/utility.xml diff --git a/doc/help/xslt/common/utility.xml b/doc/help/xslt/common/utility.xml new file mode 100644 index 00000000..d9cbe3ca --- /dev/null +++ b/doc/help/xslt/common/utility.xml @@ -0,0 +1,259 @@ + + + + + Common » Utility Template Reference + + $Id: utility.xsl 7101 2007-07-20 15:32:12Z xmldoc $ + + + + + Introduction + +This is technical reference documentation for the + miscellaneous utility templates in the DocBook XSL + Stylesheets. + + + +These templates are defined in a separate file from the set + of “common” templates because some of the common templates + reference DocBook XSL stylesheet parameters, requiring the + entire set of parameters to be imported/included in any + stylesheet that imports/includes the common templates. + + +The utility templates don’t import or include any DocBook + XSL stylesheet parameters, so the utility templates can be used + without importing the whole set of parameters. + + + +This is not intended to be user documentation. It is + provided for developers writing customization layers for the + stylesheets. + + + + + +log.message +Logs/emits formatted notes and warnings + + +<xsl:template name="log.message"> +<xsl:param name="level"/> +<xsl:param name="source"/> +<xsl:param name="context-desc"/> +<xsl:param name="context-desc-field-length">12</xsl:param> +<xsl:param name="context-desc-padded"> + <xsl:if test="not($context-desc = '')"> + <xsl:call-template name="pad-string"> + <xsl:with-param name="leftRight">right</xsl:with-param> + <xsl:with-param name="padVar" select="substring($context-desc, 1, $context-desc-field-length)"/> + <xsl:with-param name="length" select="$context-desc-field-length"/> + </xsl:call-template> + </xsl:if> + </xsl:param> +<xsl:param name="message"/> +<xsl:param name="message-field-length" select="45"/> +<xsl:param name="message-padded"> + <xsl:variable name="spaces-for-blank-level"> + <!-- * if the level field is blank, we'll need to pad out --> + <!-- * the message field with spaces to compensate --> + <xsl:choose> + <xsl:when test="$level = ''"> + <xsl:value-of select="4 + 2"/> + <!-- * 4 = hard-coded length of comment text ("Note" or "Warn") --> + <!-- * + 2 = length of colon-plus-space separator ": " --> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="0"/> + </xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:variable name="spaces-for-blank-context-desc"> + <!-- * if the context-description field is blank, we'll need --> + <!-- * to pad out the message field with spaces to compensate --> + <xsl:choose> + <xsl:when test="$context-desc = ''"> + <xsl:value-of select="$context-desc-field-length + 2"/> + <!-- * + 2 = length of colon-plus-space separator ": " --> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="0"/> + </xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:variable name="extra-spaces" select="$spaces-for-blank-level + $spaces-for-blank-context-desc"/> + <xsl:call-template name="pad-string"> + <xsl:with-param name="leftRight">right</xsl:with-param> + <xsl:with-param name="padVar" select="substring($message, 1, ($message-field-length + $extra-spaces))"/> + <xsl:with-param name="length" select="$message-field-length + $extra-spaces"/> + </xsl:call-template> + </xsl:param> + ... +</xsl:template> + +Description + +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. + + Parameters + + + 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 + + + + + + Returns + +Outputs a message (generally, to standard error). + + + + +get.doc.title +Gets a title from the current document + + +<xsl:template name="get.doc.title"/> + +Description + +The get.doc.title template is a + utility template for returning the first title found in the + current document. + + Returns + +Returns a string containing some identifying title for the + current document . + + + + +pad-string +Right-pads or left-pads a string out to a certain length + + +<xsl:template name="pad-string"> +<xsl:param name="padChar" select="' '"/> +<xsl:param name="leftRight">left</xsl:param> +<xsl:param name="padVar"/> +<xsl:param name="length"/> + ... +</xsl:template> + +Description + +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 + +Returns a (padded) string. + + +