From 2b6206f815d6e08cafc26bb9df5a09206b097a0e Mon Sep 17 00:00:00 2001
From: Michael Smith <xmldoc@users.sourceforge.net>
Date: Wed, 5 Mar 2008 15:16:10 +0000
Subject: [PATCH] Made reporting of missing refentry metadata more quiet:

  - we no longer report anything if usable-but-not-preferred
    metadata is found; we just quietly use whatever we manage to
    find

  - we now only report missing "source" metadata if the refentry
    is missing BOTH "source name" and "version" metadata; if it
    has one but not the other, we use whichever one it has and
    don't report anything as missing

The above changes were made because testing with some "real world"
source reveals that some authors are intentionally choosing to use
"non preferred" markup for some metadata, and also choosing to
omit "source name" or "version" metadata in there DocBook XML. So
it does no good to give them pedantic reminders about what they
already know...

Also, changed code to cause "fixme" text to be inserted in output
in particular cases:

  - if we can't manage to find any "source" metadata at all, we
    now put fixme text into the output

  - if we can't manage to find any "manual" metadata a all, we
    now put fixme text into the output

The "source" and "manual" metadata is necessary information, so
buy putting the fixme stuff in the output, we alert users to the
need problem of it being missing.
---
 xsl/common/refentry.xsl | 219 +++++++++++++++++++++-------------------
 1 file changed, 116 insertions(+), 103 deletions(-)

diff --git a/xsl/common/refentry.xsl b/xsl/common/refentry.xsl
index c6fa14553..54f4e46a5 100644
--- a/xsl/common/refentry.xsl
+++ b/xsl/common/refentry.xsl
@@ -559,8 +559,14 @@
       </xsl:choose>
       <xsl:copy-of select="$Version"/>
     </xsl:when>
-    <!-- * if no Name and no Version, use fallback (if any) -->
+    <!-- * if no Name and no Version, report it and use fallback (if any) -->
     <xsl:when test="not($prefs/@fallback = '')">
+      <xsl:call-template name="report.missing.source.name">
+        <xsl:with-param name="refname" select="$refname"/>
+      </xsl:call-template>
+      <xsl:call-template name="report.missing.version">
+        <xsl:with-param name="refname" select="$refname"/>
+      </xsl:call-template>
       <xsl:variable name="source.fallback">
         <xsl:call-template name="evaluate.info.profile">
           <xsl:with-param name="profile" select="$prefs/@fallback"/>
@@ -572,13 +578,14 @@
           <xsl:value-of select="$source.fallback"/>
         </xsl:when>
         <xsl:otherwise>
+          <xsl:text>[FIXME: source]</xsl:text>
           <xsl:if test="$refentry.meta.get.quietly = 0">
             <xsl:call-template name="log.message">
               <xsl:with-param name="level">Warn</xsl:with-param>
               <xsl:with-param name="source" select="$refname"/>
               <xsl:with-param name="context-desc">meta source</xsl:with-param>
               <xsl:with-param name="message">
-                <xsl:text>no valid fallback for source; leaving empty</xsl:text>
+                <xsl:text>no fallback for source, so inserted a fixme</xsl:text>
               </xsl:with-param>
             </xsl:call-template>
           </xsl:if>
@@ -586,13 +593,14 @@
       </xsl:choose>
     </xsl:when>
     <xsl:otherwise>
+      <xsl:text>[FIXME: source]</xsl:text>
       <xsl:if test="$refentry.meta.get.quietly = 0">
         <xsl:call-template name="log.message">
           <xsl:with-param name="level">Warn</xsl:with-param>
           <xsl:with-param name="source" select="$refname"/>
           <xsl:with-param name="context-desc">meta source</xsl:with-param>
           <xsl:with-param name="message">
-            <xsl:text>no source fallback specified; leaving empty</xsl:text>
+            <xsl:text>no source fallback given, so inserted a fixme</xsl:text>
           </xsl:with-param>
         </xsl:call-template>
       </xsl:if>
@@ -741,42 +749,6 @@
                 <xsl:with-param name="preferred">productname</xsl:with-param>
               </xsl:call-template>
             </xsl:when>
-            <xsl:otherwise>
-              <xsl:if test="$refentry.meta.get.quietly = 0">
-                <xsl:call-template name="log.message">
-                  <xsl:with-param name="level">Note</xsl:with-param>
-                  <xsl:with-param name="source" select="$refname"/>
-                  <xsl:with-param name="context-desc">meta source</xsl:with-param>
-                  <xsl:with-param name="message">
-                    <xsl:text>no *info/productname or alternative</xsl:text>
-                  </xsl:with-param>
-                </xsl:call-template>
-                <xsl:call-template name="log.message">
-                  <xsl:with-param name="level">Note</xsl:with-param>
-                  <xsl:with-param name="source" select="$refname"/>
-                  <xsl:with-param name="context-desc">meta source</xsl:with-param>
-                  <xsl:with-param name="message">
-                    <xsl:text>see http://docbook.sf.net/el/productname</xsl:text>
-                  </xsl:with-param>
-                </xsl:call-template>
-                <xsl:call-template name="log.message">
-                  <xsl:with-param name="level">Note</xsl:with-param>
-                  <xsl:with-param name="source" select="$refname"/>
-                  <xsl:with-param name="context-desc">meta source</xsl:with-param>
-                  <xsl:with-param name="message">
-                    <xsl:text>no refentry/refmeta/refmiscinfo@class=source</xsl:text>
-                  </xsl:with-param>
-                </xsl:call-template>
-                <xsl:call-template name="log.message">
-                  <xsl:with-param name="level">Note</xsl:with-param>
-                  <xsl:with-param name="source" select="$refname"/>
-                  <xsl:with-param name="context-desc">meta source</xsl:with-param>
-                  <xsl:with-param name="message">
-                    <xsl:text>see http://docbook.sf.net/el/refmiscinfo</xsl:text>
-                  </xsl:with-param>
-                </xsl:call-template>
-              </xsl:if>
-            </xsl:otherwise>
           </xsl:choose>
         </xsl:otherwise>
       </xsl:choose>
@@ -784,6 +756,44 @@
   </xsl:choose>
 </xsl:template>
 
+<xsl:template name="report.missing.source.name">
+  <xsl:param name="refname"/>
+  <xsl:if test="$refentry.meta.get.quietly = 0">
+    <xsl:call-template name="log.message">
+      <xsl:with-param name="level">Note</xsl:with-param>
+      <xsl:with-param name="source" select="$refname"/>
+      <xsl:with-param name="context-desc">meta source</xsl:with-param>
+      <xsl:with-param name="message">
+        <xsl:text>no *info/productname or alternative</xsl:text>
+      </xsl:with-param>
+    </xsl:call-template>
+    <xsl:call-template name="log.message">
+      <xsl:with-param name="level">Note</xsl:with-param>
+      <xsl:with-param name="source" select="$refname"/>
+      <xsl:with-param name="context-desc">meta source</xsl:with-param>
+      <xsl:with-param name="message">
+        <xsl:text>see http://docbook.sf.net/el/productname</xsl:text>
+      </xsl:with-param>
+    </xsl:call-template>
+    <xsl:call-template name="log.message">
+      <xsl:with-param name="level">Note</xsl:with-param>
+      <xsl:with-param name="source" select="$refname"/>
+      <xsl:with-param name="context-desc">meta source</xsl:with-param>
+      <xsl:with-param name="message">
+        <xsl:text>no refentry/refmeta/refmiscinfo@class=source</xsl:text>
+      </xsl:with-param>
+    </xsl:call-template>
+    <xsl:call-template name="log.message">
+      <xsl:with-param name="level">Note</xsl:with-param>
+      <xsl:with-param name="source" select="$refname"/>
+      <xsl:with-param name="context-desc">meta source</xsl:with-param>
+      <xsl:with-param name="message">
+        <xsl:text>see http://docbook.sf.net/el/refmiscinfo</xsl:text>
+      </xsl:with-param>
+    </xsl:call-template>
+  </xsl:if>
+</xsl:template>
+
 <!-- ==================================================================== -->
 <doc:template name="get.refentry.version" xmlns="">
   <refpurpose>Gets version metadata for a refentry</refpurpose>
@@ -886,42 +896,6 @@
                 <xsl:with-param name="preferred">productnumber</xsl:with-param>
               </xsl:call-template>
             </xsl:when>
-            <xsl:otherwise>
-              <xsl:if test="$refentry.meta.get.quietly = 0">
-                <xsl:call-template name="log.message">
-                  <xsl:with-param name="level">Note</xsl:with-param>
-                  <xsl:with-param name="source" select="$refname"/>
-                  <xsl:with-param name="context-desc">meta version</xsl:with-param>
-                  <xsl:with-param name="message">
-                    <xsl:text>no *info/productnumber or alternative</xsl:text>
-                  </xsl:with-param>
-                </xsl:call-template>
-                <xsl:call-template name="log.message">
-                  <xsl:with-param name="level">Note</xsl:with-param>
-                  <xsl:with-param name="source" select="$refname"/>
-                  <xsl:with-param name="context-desc">meta version</xsl:with-param>
-                  <xsl:with-param name="message">
-                    <xsl:text>see http://docbook.sf.net/el/productnumber</xsl:text>
-                  </xsl:with-param>
-                </xsl:call-template>
-                <xsl:call-template name="log.message">
-                  <xsl:with-param name="level">Note</xsl:with-param>
-                  <xsl:with-param name="source" select="$refname"/>
-                  <xsl:with-param name="context-desc">meta version</xsl:with-param>
-                  <xsl:with-param name="message">
-                    <xsl:text>no refentry/refmeta/refmiscinfo@class=version</xsl:text>
-                  </xsl:with-param>
-                </xsl:call-template>
-                <xsl:call-template name="log.message">
-                  <xsl:with-param name="level">Note</xsl:with-param>
-                  <xsl:with-param name="source" select="$refname"/>
-                  <xsl:with-param name="context-desc">meta version</xsl:with-param>
-                  <xsl:with-param name="message">
-                    <xsl:text>see http://docbook.sf.net/el/refmiscinfo</xsl:text>
-                  </xsl:with-param>
-                </xsl:call-template>
-              </xsl:if>
-            </xsl:otherwise>
           </xsl:choose>
         </xsl:otherwise>
       </xsl:choose>
@@ -929,6 +903,44 @@
   </xsl:choose>
 </xsl:template>
 
+<xsl:template name="report.missing.version">
+  <xsl:param name="refname"/>
+  <xsl:if test="$refentry.meta.get.quietly = 0">
+    <xsl:call-template name="log.message">
+      <xsl:with-param name="level">Note</xsl:with-param>
+      <xsl:with-param name="source" select="$refname"/>
+      <xsl:with-param name="context-desc">meta version</xsl:with-param>
+      <xsl:with-param name="message">
+        <xsl:text>no *info/productnumber or alternative</xsl:text>
+      </xsl:with-param>
+    </xsl:call-template>
+    <xsl:call-template name="log.message">
+      <xsl:with-param name="level">Note</xsl:with-param>
+      <xsl:with-param name="source" select="$refname"/>
+      <xsl:with-param name="context-desc">meta version</xsl:with-param>
+      <xsl:with-param name="message">
+        <xsl:text>see http://docbook.sf.net/el/productnumber</xsl:text>
+      </xsl:with-param>
+    </xsl:call-template>
+    <xsl:call-template name="log.message">
+      <xsl:with-param name="level">Note</xsl:with-param>
+      <xsl:with-param name="source" select="$refname"/>
+      <xsl:with-param name="context-desc">meta version</xsl:with-param>
+      <xsl:with-param name="message">
+        <xsl:text>no refentry/refmeta/refmiscinfo@class=version</xsl:text>
+      </xsl:with-param>
+    </xsl:call-template>
+    <xsl:call-template name="log.message">
+      <xsl:with-param name="level">Note</xsl:with-param>
+      <xsl:with-param name="source" select="$refname"/>
+      <xsl:with-param name="context-desc">meta version</xsl:with-param>
+      <xsl:with-param name="message">
+        <xsl:text>see http://docbook.sf.net/el/refmiscinfo</xsl:text>
+      </xsl:with-param>
+    </xsl:call-template>
+  </xsl:if>
+</xsl:template>
+
 <!-- ==================================================================== -->
 <doc:template name="get.refentry.manual" xmlns="">
   <refpurpose>Gets source metadata for a refentry</refpurpose>
@@ -1109,28 +1121,29 @@
           <xsl:value-of select="$manual.fallback"/>
         </xsl:when>
         <xsl:otherwise>
+          <xsl:text>[FIXME: manual]</xsl:text>
           <xsl:if test="$refentry.meta.get.quietly = 0">
             <xsl:call-template name="log.message">
               <xsl:with-param name="level">Warn</xsl:with-param>
               <xsl:with-param name="source" select="$refname"/>
               <xsl:with-param name="context-desc">meta manual</xsl:with-param>
               <xsl:with-param name="message">
-                <xsl:text>no valid fallback for manual; leaving empty</xsl:text>
+                <xsl:text>no fallback for manual, so inserted a fixme</xsl:text>
               </xsl:with-param>
             </xsl:call-template>
           </xsl:if>
         </xsl:otherwise>
       </xsl:choose>
-
     </xsl:when>
     <xsl:otherwise>
+      <xsl:text>[FIXME: manual]</xsl:text>
       <xsl:if test="$refentry.meta.get.quietly = 0">
         <xsl:call-template name="log.message">
           <xsl:with-param name="level">Warn</xsl:with-param>
           <xsl:with-param name="source" select="$refname"/>
           <xsl:with-param name="context-desc">meta manual</xsl:with-param>
           <xsl:with-param name="message">
-            <xsl:text>no manual fallback specified; leaving empty</xsl:text>
+            <xsl:text>no manual fallback given, so inserted a fixme</xsl:text>
           </xsl:with-param>
         </xsl:call-template>
       </xsl:if>
@@ -1260,31 +1273,31 @@
   <xsl:param name="contents"/>
   <xsl:param name="context"/>
   <xsl:param name="preferred"/>
-  <xsl:if test="not($preferred = '')">
-    <xsl:if test="$refentry.meta.get.quietly = 0">
-      <xsl:call-template name="log.message">
-        <xsl:with-param name="level">Note</xsl:with-param>
-        <xsl:with-param name="source" select="$refname"/>
-        <xsl:with-param name="context-desc" select="concat('meta ', $context)"/>
-        <xsl:with-param name="message" select="concat('No ', $preferred)"/>
-      </xsl:call-template>
-      <xsl:call-template name="log.message">
-        <xsl:with-param name="level">Note</xsl:with-param>
-        <xsl:with-param name="source" select="$refname"/>
-        <xsl:with-param name="context-desc" select="concat('meta ', $context)"/>
-        <xsl:with-param name="message">
-          <xsl:text>no refentry/refmeta/refmiscinfo@class=</xsl:text>
-          <xsl:value-of select="$context"/>
-        </xsl:with-param>
-      </xsl:call-template>
-      <xsl:call-template name="log.message">
-        <xsl:with-param name="level">Note</xsl:with-param>
-        <xsl:with-param name="source" select="$refname"/>
-        <xsl:with-param name="context-desc" select="concat('meta ', $context)"/>
-        <xsl:with-param name="message" select="concat('Using ', local-name($contents))"/>
-      </xsl:call-template>
-    </xsl:if>
-  </xsl:if>
+  <!-- * <xsl:if test="not($preferred = '')"> -->
+    <!-- * <xsl:if test="$refentry.meta.get.quietly = 0"> -->
+      <!-- * <xsl:call-template name="log.message"> -->
+        <!-- * <xsl:with-param name="level">Note</xsl:with-param> -->
+        <!-- * <xsl:with-param name="source" select="$refname"/> -->
+        <!-- * <xsl:with-param name="context-desc" select="concat('meta ', $context)"/> -->
+        <!-- * <xsl:with-param name="message" select="concat('No ', $preferred)"/> -->
+      <!-- * </xsl:call-template> -->
+      <!-- * <xsl:call-template name="log.message"> -->
+        <!-- * <xsl:with-param name="level">Note</xsl:with-param> -->
+        <!-- * <xsl:with-param name="source" select="$refname"/> -->
+        <!-- * <xsl:with-param name="context-desc" select="concat('meta ', $context)"/> -->
+        <!-- * <xsl:with-param name="message"> -->
+          <!-- * <xsl:text>no refentry/refmeta/refmiscinfo@class=</xsl:text> -->
+          <!-- * <xsl:value-of select="$context"/> -->
+        <!-- * </xsl:with-param> -->
+      <!-- * </xsl:call-template> -->
+      <!-- * <xsl:call-template name="log.message"> -->
+        <!-- * <xsl:with-param name="level">Note</xsl:with-param> -->
+        <!-- * <xsl:with-param name="source" select="$refname"/> -->
+        <!-- * <xsl:with-param name="context-desc" select="concat('meta ', $context)"/> -->
+        <!-- * <xsl:with-param name="message" select="concat('Using ', local-name($contents))"/> -->
+      <!-- * </xsl:call-template> -->
+    <!-- * </xsl:if> -->
+  <!-- * </xsl:if> -->
   <xsl:value-of select="$contents"/>
 </xsl:template>
 
-- 
2.40.0