X-Git-Url: https://git.stg.codes/stg.git/blobdiff_plain/bfec9cc7ab5a396f7662090b208691ec59a69f1b..2f1753cc3e240fa497a87873ed19fe3f11e22331:/doc/help/xslt/common/utility.xml diff --git a/doc/help/xslt/common/utility.xml b/doc/help/xslt/common/utility.xml deleted file mode 100644 index d9cbe3ca..00000000 --- a/doc/help/xslt/common/utility.xml +++ /dev/null @@ -1,259 +0,0 @@ - - - - - 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. - - -