+++ /dev/null
-<?xml version="1.0"?>\r
-\r
-<reference xml:id="utility">\r
- <info>\r
- <title>Common » Utility Template Reference</title>\r
- <releaseinfo role="meta">\r
- $Id: utility.xsl 7101 2007-07-20 15:32:12Z xmldoc $\r
- </releaseinfo>\r
- </info>\r
- \r
- <partintro xml:id="partintro">\r
- <title>Introduction</title>\r
- \r
-<para>This is technical reference documentation for the\r
- miscellaneous utility templates in the DocBook XSL\r
- Stylesheets.</para>\r
-\r
- <note>\r
- \r
-<para>These templates are defined in a separate file from the set\r
- of “common” templates because some of the common templates\r
- reference DocBook XSL stylesheet parameters, requiring the\r
- entire set of parameters to be imported/included in any\r
- stylesheet that imports/includes the common templates.</para>\r
-\r
- \r
-<para>The utility templates don’t import or include any DocBook\r
- XSL stylesheet parameters, so the utility templates can be used\r
- without importing the whole set of parameters.</para>\r
-\r
- </note>\r
- \r
-<para>This is not intended to be user documentation. It is\r
- provided for developers writing customization layers for the\r
- stylesheets.</para>\r
-\r
- </partintro>\r
-\r
-<refentry xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.log.message">\r
-<refnamediv>\r
-<refname>log.message</refname>\r
-<refpurpose>Logs/emits formatted notes and warnings</refpurpose>\r
-</refnamediv>\r
-<refsynopsisdiv>\r
-<synopsis><xsl:template name="log.message">\r
-<xsl:param name="level"/>\r
-<xsl:param name="source"/>\r
-<xsl:param name="context-desc"/>\r
-<xsl:param name="context-desc-field-length">12</xsl:param>\r
-<xsl:param name="context-desc-padded">\r
- <xsl:if test="not($context-desc = '')">\r
- <xsl:call-template name="pad-string">\r
- <xsl:with-param name="leftRight">right</xsl:with-param>\r
- <xsl:with-param name="padVar" select="substring($context-desc, 1, $context-desc-field-length)"/>\r
- <xsl:with-param name="length" select="$context-desc-field-length"/>\r
- </xsl:call-template>\r
- </xsl:if>\r
- </xsl:param>\r
-<xsl:param name="message"/>\r
-<xsl:param name="message-field-length" select="45"/>\r
-<xsl:param name="message-padded">\r
- <xsl:variable name="spaces-for-blank-level">\r
- <!-- * if the level field is blank, we'll need to pad out -->\r
- <!-- * the message field with spaces to compensate -->\r
- <xsl:choose>\r
- <xsl:when test="$level = ''">\r
- <xsl:value-of select="4 + 2"/>\r
- <!-- * 4 = hard-coded length of comment text ("Note" or "Warn") -->\r
- <!-- * + 2 = length of colon-plus-space separator ": " -->\r
- </xsl:when>\r
- <xsl:otherwise>\r
- <xsl:value-of select="0"/>\r
- </xsl:otherwise>\r
- </xsl:choose>\r
- </xsl:variable>\r
- <xsl:variable name="spaces-for-blank-context-desc">\r
- <!-- * if the context-description field is blank, we'll need -->\r
- <!-- * to pad out the message field with spaces to compensate -->\r
- <xsl:choose>\r
- <xsl:when test="$context-desc = ''">\r
- <xsl:value-of select="$context-desc-field-length + 2"/>\r
- <!-- * + 2 = length of colon-plus-space separator ": " -->\r
- </xsl:when>\r
- <xsl:otherwise>\r
- <xsl:value-of select="0"/>\r
- </xsl:otherwise>\r
- </xsl:choose>\r
- </xsl:variable>\r
- <xsl:variable name="extra-spaces" select="$spaces-for-blank-level + $spaces-for-blank-context-desc"/>\r
- <xsl:call-template name="pad-string">\r
- <xsl:with-param name="leftRight">right</xsl:with-param>\r
- <xsl:with-param name="padVar" select="substring($message, 1, ($message-field-length + $extra-spaces))"/>\r
- <xsl:with-param name="length" select="$message-field-length + $extra-spaces"/>\r
- </xsl:call-template>\r
- </xsl:param>\r
- ...\r
-</xsl:template></synopsis>\r
-</refsynopsisdiv>\r
-<refsect1><title>Description</title>\r
- \r
-<para>The <function>log.message</function> template is a utility\r
- template for logging/emitting formatted messages – that is,\r
- notes and warnings, along with a given log “level” and an\r
- identifier for the “source” that the message relates to.</para>\r
-\r
- </refsect1><refsect1><title>Parameters</title>\r
- \r
-<variablelist>\r
- <varlistentry><term>level</term>\r
- <listitem>\r
- \r
-<para>Text to log/emit in the message-level field to\r
- indicate the message level\r
- (<literal>Note</literal> or\r
- <literal>Warning</literal>)</para>\r
-\r
- </listitem>\r
- </varlistentry>\r
- <varlistentry><term>source</term>\r
- <listitem>\r
- \r
-<para>Text to log/emit in the source field to identify the\r
- “source” to which the notification/warning relates.\r
- This can be any arbitrary string, but because the\r
- message lacks line and column numbers to identify the\r
- exact part of the source document to which it\r
- relates, the intention is that the value you pass\r
- into the <literal>source</literal> parameter should\r
- give the user some way to identify the portion of\r
- their source document on which to take potentially\r
- take action in response to the log message (for\r
- example, to edit, change, or add content).</para>\r
-\r
- \r
-<para>So the <literal>source</literal> value should be,\r
- for example, an ID, book/chapter/article title, title\r
- of some formal object, or even a string giving an\r
- XPath expression.</para>\r
-\r
- </listitem>\r
- </varlistentry>\r
- <varlistentry><term>context-desc</term>\r
- <listitem>\r
- \r
-<para>Text to log/emit in the context-description field to\r
- describe the context for the message.</para>\r
-\r
- </listitem>\r
- </varlistentry>\r
- <varlistentry><term>context-desc-field-length</term>\r
- <listitem>\r
- \r
-<para>Specifies length of the context-description field\r
- (in characters); default is 12</para>\r
-\r
- \r
-<para>If the text specified by the\r
- <literal>context-desc</literal> parameter is longer\r
- than the number of characters specified in\r
- <literal>context-desc-field-length</literal>, it is\r
- truncated to <literal>context-desc-field-length</literal>\r
- (12 characters by default).</para>\r
-\r
- \r
-<para>If the specified text is shorter than\r
- <literal>context-desc-field-length</literal>,\r
- it is right-padded out to\r
- <literal>context-desc-field-length</literal> (12 by\r
- default).</para>\r
-\r
- \r
-<para>If no value has been specified for the\r
- <literal>context-desc</literal> parameter, the field is\r
- left empty and the text of the log message begins with\r
- the value of the <literal>message</literal>\r
- parameter.</para>\r
-\r
- </listitem>\r
- </varlistentry>\r
- <varlistentry><term>message</term>\r
- <listitem>\r
- \r
-<para>Text to log/emit in the actual message field</para>\r
-\r
- </listitem>\r
- </varlistentry>\r
- <varlistentry><term>message-field-length</term>\r
- <listitem>\r
- \r
-<para>Specifies length of the message\r
- field (in characters); default is 45</para>\r
-\r
- </listitem>\r
- </varlistentry>\r
- </variablelist>\r
-\r
- </refsect1><refsect1><title>Returns</title>\r
- \r
-<para>Outputs a message (generally, to standard error).</para>\r
-</refsect1></refentry>\r
-\r
-<refentry xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.get.doc.title">\r
-<refnamediv>\r
-<refname>get.doc.title</refname>\r
-<refpurpose>Gets a title from the current document</refpurpose>\r
-</refnamediv>\r
-<refsynopsisdiv>\r
-<synopsis><xsl:template name="get.doc.title"/></synopsis>\r
-</refsynopsisdiv>\r
-<refsect1><title>Description</title>\r
- \r
-<para>The <function>get.doc.title</function> template is a\r
- utility template for returning the first title found in the\r
- current document.</para>\r
-\r
- </refsect1><refsect1><title>Returns</title>\r
- \r
-<para>Returns a string containing some identifying title for the\r
- current document .</para>\r
-</refsect1></refentry>\r
-\r
-<refentry xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="template.pad-string">\r
-<refnamediv>\r
-<refname>pad-string</refname>\r
-<refpurpose>Right-pads or left-pads a string out to a certain length</refpurpose>\r
-</refnamediv>\r
-<refsynopsisdiv>\r
-<synopsis><xsl:template name="pad-string">\r
-<xsl:param name="padChar" select="' '"/>\r
-<xsl:param name="leftRight">left</xsl:param>\r
-<xsl:param name="padVar"/>\r
-<xsl:param name="length"/>\r
- ...\r
-</xsl:template></synopsis>\r
-</refsynopsisdiv>\r
-<refsect1><title>Description</title>\r
- \r
-<para>This function takes string <parameter>padVar</parameter> and\r
- pads it out in the direction <parameter>rightLeft</parameter> to\r
- the string-length <parameter>length</parameter>, using string\r
- <parameter>padChar</parameter> (a space character by default) as\r
- the padding string (note that <parameter>padChar</parameter> can\r
- be a string; it is not limited to just being a single\r
- character).</para>\r
-\r
- <note>\r
- \r
-<para>This function began as a copy of Nate Austin's\r
- <function>prepend-pad</function> function in the <link xlink:href="http://www.dpawson.co.uk/xsl/sect2/padding.html">Padding\r
- Content</link> section of Dave Pawson's <link xlink:href="http://www.dpawson.co.uk/xsl/index.html">XSLT\r
- FAQ</link>.</para>\r
-\r
- </note>\r
- </refsect1><refsect1><title>Returns</title>\r
- \r
-<para>Returns a (padded) string.</para>\r
-</refsect1></refentry>\r
-</reference>\r
-\r
projects / Evergreen-DocBook.git / blobdiff