From 4198b0a54f74cb7c24c3052793a0b878cf9d7553 Mon Sep 17 00:00:00 2001
From: Michael Smith <xmldoc@users.sourceforge.net>
Date: Thu, 21 Jun 2007 23:30:53 +0000
Subject: [PATCH] Improved general logging template to parameterize some parts
 that were hardcoded previously.

---
 xsl/common/common.xsl | 139 ++++++++++++++++++++++++++++++++++++------
 1 file changed, 119 insertions(+), 20 deletions(-)

diff --git a/xsl/common/common.xsl b/xsl/common/common.xsl
index 8edb30d4b..55ed906d5 100644
--- a/xsl/common/common.xsl
+++ b/xsl/common/common.xsl
@@ -1966,7 +1966,7 @@ unchanged.</para>
 <doc:template name="evaluate.info.profile" xmlns="">
   <refpurpose>Evaluates an info profile</refpurpose>
   <refdescription>
-    <para>This function evaluates an "info profile" matching the XPath
+    <para>This template evaluates an "info profile" matching the XPath
     expression given by the <parameter>profile</parameter>
     parameter. It relies on the XSLT <function>evaluate()</function>
     extension function.</para>
@@ -2033,8 +2033,8 @@ engine does not support it.
   <refpurpose>Logs/emits formatted notes and warnings</refpurpose>
 
   <refdescription>
-    <para>The <function>log.message</function> function is a utility
-    function for logging/emitting formatted messages&#xa0;– that is,
+    <para>The <function>log.message</function> template is a utility
+    template for logging/emitting formatted messages&#xa0;– that is,
     notes and warnings, along with a given log "level" and an
     identifier for the "source" that the message relates to.</para>
   </refdescription>
@@ -2044,7 +2044,8 @@ engine does not support it.
       <varlistentry>
         <term>level</term>
         <listitem>
-          <para>Text to indicate the message level
+          <para>Text to log/emit in the message-level field to
+            indicate the message level
           (<literal>Note</literal> or
           <literal>Warning</literal>)</para>
         </listitem>
@@ -2052,20 +2053,64 @@ engine does not support it.
       <varlistentry>
         <term>source</term>
         <listitem>
-          <para>Text to identify source element the
-          notification/warning relates to</para>
+          <para>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 <literal>source</literal> 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).</para>
+          <para>So the <literal>source</literal> value should be,
+            for example, an ID, book/chapter/article title, title
+            of some formal object, or even a string giving an
+            XPath expression.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>context-desc</term>
+        <listitem>
+          <para>Text to log/emit in the context-description field to
+            describe the context for the message.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>context-desc-field-length</term>
+        <listitem>
+          <para>Specifies length of the context-description field
+            (in characters); default is 12</para>
+          <para>If the text specified by the
+            <literal>context-desc</literal> parameter is longer
+            than the number of characters specified in
+            <literal>context-desc-field-length</literal>, it is
+            truncated to <literal>context-desc-field-length</literal>
+            (12 characters by default).</para>
+          <para>If the specified text is shorter than
+            <literal>context-desc-field-length</literal>,
+          it is right-padded out to
+          <literal>context-desc-field-length</literal> (12 by
+          default).</para>
+        <para>If no value has been specified for the
+          <literal>context-desc</literal> parameter, the field is
+          left empty and the text of the log message begins with
+          the value of the <literal>message</literal>
+          parameter.</para>
         </listitem>
       </varlistentry>
       <varlistentry>
         <term>message</term>
         <listitem>
-          <para>Message to lot/emit</para>
+          <para>Text to log/emit in the actual message field</para>
         </listitem>
       </varlistentry>
       <varlistentry>
-        <term>message-width</term>
+        <term>message-field-length</term>
         <listitem>
-          <para>Expected maximum message width</para>
+          <para>Specifies length of the message
+            field (in characters); default is 45</para>
         </listitem>
       </varlistentry>
     </variablelist>
@@ -2077,18 +2122,72 @@ engine does not support it.
 <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-width">50</xsl:param>
-  <xsl:message><xsl:value-of
-  select="$level"/><xsl:text>: </xsl:text><xsl:value-of
-  select="$message"/><xsl:call-template
-  name="copy-string">
-  <xsl:with-param name="string" select="'&#x20;'"/>
-  <xsl:with-param
-      name="count"
-      select="$message-width - string-length($message)"/>
-  </xsl:call-template><xsl:value-of
-  select="$source"/></xsl: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>
+  <!-- * emit the actual log message -->
+  <xsl:message>
+    <xsl:if test="not($level = '')">
+      <xsl:value-of select="$level"/>
+      <xsl:text>: </xsl:text>
+    </xsl:if>
+    <xsl:if test="not($context-desc = '')">
+      <xsl:value-of select="$context-desc-padded"/>
+      <xsl:text>: </xsl:text>
+    </xsl:if>
+    <xsl:value-of select="$message-padded"/>
+    <xsl:text>  </xsl:text>
+    <xsl:value-of select="$source"/>
+  </xsl:message>
 </xsl:template>
 
 </xsl:stylesheet>
-- 
2.40.0