From efa7495f5321e1a00696cdc560e5c4d2064b89b3 Mon Sep 17 00:00:00 2001
From: Michael Smith <xmldoc@users.sourceforge.net>
Date: Mon, 17 Oct 2005 18:52:02 +0000
Subject: [PATCH] Improved handling or Author/Editor/Othercredit.

Reworked content of (non-visible) comment added at top of each
page (metadata stuff).

Added support for generating a manifest file (useful for cleaning
up after builds, etc.)
---
 xsl/manpages/docbook.xsl |  31 ++++++++++-
 xsl/manpages/info.xsl    |  85 +++++++++++++++++++++-------
 xsl/manpages/other.xsl   | 117 +++++++++++++++++++++++++++++++--------
 xsl/manpages/utility.xsl |  16 ++++++
 4 files changed, 207 insertions(+), 42 deletions(-)

diff --git a/xsl/manpages/docbook.xsl b/xsl/manpages/docbook.xsl
index d0563679d..300815164 100644
--- a/xsl/manpages/docbook.xsl
+++ b/xsl/manpages/docbook.xsl
@@ -5,6 +5,7 @@
                 version='1.0'>
 
   <xsl:import href="../html/docbook.xsl"/>
+  <xsl:import href="../html/manifest.xsl"/>
 
   <xsl:output method="text"
               encoding="UTF-8"
@@ -34,6 +35,9 @@
   <xsl:include href="lists.xsl"/>
   <xsl:include href="links.xsl"/>
 
+  <xsl:param name="generate.manifest">0</xsl:param>
+  <xsl:param name="man.manifest.filename">MANIFEST.man</xsl:param>
+
 <!-- ==================================================================== -->
 
   <!-- * if document does not contain at least one refentry, then emit a -->
@@ -42,6 +46,24 @@
     <xsl:choose>
       <xsl:when test="//refentry">
         <xsl:apply-templates select="//refentry"/>
+        <!-- * if $generate.manifest is non-zero, generate a manifest file -->
+        <xsl:if test="not($generate.manifest = '0')">
+          <xsl:call-template name="generate.manifest">
+            <xsl:with-param name="filename">
+              <xsl:choose>
+                <xsl:when test="not($man.manifest.filename = '')">
+                  <xsl:value-of select="$man.manifest.filename"/>
+                </xsl:when>
+                <!-- * we must have a manifest filename; so if user has -->
+                <!-- * unset $man.manifest.filename, default to using -->
+                <!-- * “MAN.MANIFEST” as the filename -->
+                <xsl:otherwise>
+                  <xsl:text>MAN.MANIFEST</xsl:text>
+                </xsl:otherwise>
+              </xsl:choose>
+            </xsl:with-param>
+          </xsl:call-template>
+        </xsl:if>
       </xsl:when>
       <xsl:otherwise>
         <xsl:message>No refentry elements!</xsl:message>
@@ -102,7 +124,14 @@
       <!-- * - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
       <!-- * top.comment = commented-out section at top of roff source -->
       <!-- * - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
-      <xsl:call-template name="top.comment"/>
+      <xsl:call-template name="top.comment">
+        <xsl:with-param name="info"       select="$info"/>
+        <xsl:with-param name="parentinfo" select="$parentinfo"/>
+        <xsl:with-param name="date"       select="$refentry.metadata/date"/>
+        <xsl:with-param name="title"      select="$refentry.metadata/title"/>
+        <xsl:with-param name="manual"     select="$refentry.metadata/manual"/>
+        <xsl:with-param name="source"     select="$refentry.metadata/source"/>
+      </xsl:call-template>
       <!-- * - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
       <!-- * TH.title.line = title line in header/footer of man page -->
       <!-- * - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
diff --git a/xsl/manpages/info.xsl b/xsl/manpages/info.xsl
index afdc7354f..3cf6fc31f 100644
--- a/xsl/manpages/info.xsl
+++ b/xsl/manpages/info.xsl
@@ -28,9 +28,44 @@
   
   <!-- * =============================================================== -->
 
+  <xsl:template name="author.names">
+    <xsl:param name="info"/>
+    <xsl:param name="parentinfo"/>
+    <xsl:choose>
+      <xsl:when test="$info//author">
+        <xsl:apply-templates select="$info" mode="author.names"/>
+      </xsl:when>
+      <xsl:when test="$parentinfo//author">
+        <xsl:apply-templates select="$parentinfo" mode="author.names"/>
+      </xsl:when>
+    </xsl:choose>
+  </xsl:template>
+
+  <xsl:template match="info|refentryinfo|referenceinfo
+                       |articleinfo|chapterinfo|sectioninfo
+                       |sect1info|sect2info|sect3info|sect4info|sect5info
+                       |partinfo|prefaceinfo|appendixinfo|docinfo"
+                mode="author.names">
+    <xsl:for-each select="author">
+      <xsl:apply-templates select="." mode="author.names"/>
+      <xsl:choose>
+        <xsl:when test="position() = last()"/> <!-- do nothing -->
+        <xsl:otherwise>
+          <xsl:text>, </xsl:text>
+        </xsl:otherwise>
+      </xsl:choose>
+    </xsl:for-each>
+  </xsl:template>
+
+  <xsl:template match="author" mode="author.names">
+    <xsl:call-template name="person.name"/>
+    <xsl:if test=".//email">
+      <xsl:text> </xsl:text>
+      <xsl:apply-templates select=".//email"/>
+    </xsl:if>
+  </xsl:template>
+
   <xsl:template name="author.section">
-    <!-- * WARNING: The author.section API is slated for a rewrite and -->
-    <!-- * should not be considered stable. -->
     <xsl:param name="info"/>
     <xsl:param name="parentinfo"/>
     <xsl:choose>
@@ -60,31 +95,24 @@
     </xsl:call-template>
     <xsl:text>"&#10;</xsl:text>
 
-    <xsl:for-each select=".//author" >
-      <xsl:if test="position() > 1">
-        <xsl:text>, </xsl:text>
-      </xsl:if>
+    <xsl:for-each select="author|editor|othercredit">
       <xsl:apply-templates select="." mode="authorsect"/>
     </xsl:for-each>
-    <xsl:text>. &#10;</xsl:text>
-    <xsl:if test=".//editor">
-      <xsl:text>.br&#10;</xsl:text>
-      <xsl:apply-templates select=".//editor" mode="authorsect"/>
-      <xsl:text>. (man page)&#10;</xsl:text>
-    </xsl:if>
-    <xsl:for-each select="address">
-      <xsl:text>.br&#10;</xsl:text>
-      <xsl:apply-templates/>
-      <xsl:text>&#10;</xsl:text>
-    </xsl:for-each>
-  </xsl:template>
 
-  <xsl:template match="author|editor" mode="authorsect">
+  </xsl:template>
+  
+  <xsl:template match="author|editor|othercredit" mode="authorsect">
+    <xsl:text>.PP&#10;</xsl:text>
     <xsl:call-template name="person.name"/>
     <xsl:if test=".//email">
       <xsl:text> </xsl:text>
       <xsl:apply-templates select=".//email" mode="authorsect"/>
     </xsl:if>
+    <xsl:text>&#10;</xsl:text>
+    <xsl:if test="contrib|personblurb|authorblurb">
+      <xsl:apply-templates select="(contrib|personblurb|authorblurb)" mode="authorsect"/>
+    <xsl:text>&#10;</xsl:text>
+    </xsl:if>
   </xsl:template>
 
   <xsl:template match="email" mode="authorsect">
@@ -93,6 +121,25 @@
     <xsl:text>&gt;</xsl:text>
   </xsl:template>
 
+  <xsl:template match="personblurb|authorblurb" mode="authorsect">
+      <xsl:text>&#10;.IP&#10;</xsl:text>
+      <xsl:for-each select="title">
+        <xsl:apply-templates/>
+        <xsl:text>.</xsl:text>
+        <xsl:if test="following-sibling::*[name() != '']">
+          <xsl:text> </xsl:text>
+        </xsl:if>
+      </xsl:for-each>
+      <xsl:for-each select="*[name() != 'title']">
+        <xsl:apply-templates/>
+      </xsl:for-each>
+  </xsl:template>
+
+  <xsl:template match="contrib" mode="authorsect">
+    <xsl:text>&#10;.IP&#10;</xsl:text>
+    <xsl:apply-templates/>
+  </xsl:template>
+
   <!-- * ============================================================== -->
 
   <!-- * suppress refmeta and all *info (we grab what we need from them -->
diff --git a/xsl/manpages/other.xsl b/xsl/manpages/other.xsl
index 578aa9821..08f5a5657 100644
--- a/xsl/manpages/other.xsl
+++ b/xsl/manpages/other.xsl
@@ -54,17 +54,45 @@
 
 <!-- ==================================================================== -->
 
+<!-- * top.comment generates a comment containing metadata for the man -->
+<!-- * page; for example, Author, Generator, and Date information -->
+
   <xsl:template name="top.comment">
-    <xsl:text>.\" ** You probably do not want to</xsl:text>
-    <xsl:text> edit this file directly **&#10;</xsl:text>
-    <xsl:text>.\" It was generated using the DocBook</xsl:text>
-    <xsl:text> XSL Stylesheets (version </xsl:text>
+    <xsl:param name="info"/>
+    <xsl:param name="parentinfo"/>
+    <xsl:param name="date"/>
+    <xsl:param name="title"/>
+    <xsl:param name="manual"/>
+    <xsl:param name="source"/>
+    <xsl:text>.\"     Title: </xsl:text>
+    <xsl:value-of select="$title"/>
+    <xsl:text>&#10;</xsl:text>
+    <xsl:text>.\"    Author: </xsl:text>
+      <xsl:call-template name="author.names">
+        <xsl:with-param name="info" select="$info"/>
+        <xsl:with-param name="parentinfo" select="$parentinfo"/>
+      </xsl:call-template>
+    <xsl:text>&#10;</xsl:text>
+    <xsl:text>.\" Generator: DocBook XSL Stylesheets v</xsl:text>
     <xsl:value-of select="$VERSION"/>
-    <xsl:text>).&#10;</xsl:text>
-    <xsl:text>.\" Instead of manually editing it, you</xsl:text>
-    <xsl:text> probably should edit the DocBook XML&#10;</xsl:text>
-    <xsl:text>.\" source for it and then use the DocBook</xsl:text>
-    <xsl:text> XSL Stylesheets to regenerate it.&#10;</xsl:text>
+    <xsl:text> &lt;http://sourceforge.net/projects/docbook/></xsl:text>
+    <xsl:text>&#10;</xsl:text>
+    <xsl:text>.\"      Date: </xsl:text>
+      <xsl:call-template name="string.subst">
+        <!-- * replace hyphens in date with dots -->
+        <xsl:with-param name="string" select="$date"/>
+        <xsl:with-param name="target" select="'-'"/>
+        <xsl:with-param name="replacement" select="'.'"/>
+      </xsl:call-template>
+    <xsl:text>&#10;</xsl:text>
+    <xsl:text>.\"    Manual: </xsl:text>
+    <xsl:value-of select="$manual"/>
+    <xsl:text>&#10;</xsl:text>
+    <xsl:text>.\"    Source: </xsl:text>
+    <xsl:value-of select="$source"/>
+    <xsl:text>&#10;</xsl:text>
+    <xsl:text>.\"</xsl:text>
+    <xsl:text>&#10;</xsl:text>
   </xsl:template>
 
 <!-- ==================================================================== -->
@@ -238,12 +266,9 @@
     <xsl:param name="section"/>
     <xsl:param name="content"/>
     <xsl:param name="filename">
-      <xsl:call-template name="string.subst">
-        <!-- replace spaces in source filename with underscores in output filename -->
-        <xsl:with-param name="string"
-                        select="concat(normalize-space($name), '.', normalize-space($section))"/>
-        <xsl:with-param name="target" select="' '"/>
-        <xsl:with-param name="replacement" select="'_'"/>
+      <xsl:call-template name="make.adjusted.man.filename">
+        <xsl:with-param name="name" select="$name"/>
+        <xsl:with-param name="section" select="$section"/>
       </xsl:call-template>
     </xsl:param>
     <xsl:call-template name="write.text.chunk">
@@ -275,17 +300,65 @@
     <xsl:for-each select="refnamediv/refname">
       <xsl:if test=". != $first.refname">
         <xsl:call-template name="write.text.chunk">
-          <xsl:with-param name="filename"
-                          select="concat(normalize-space(.), '.',
-                                  $section)"/>
+          <xsl:with-param name="filename">
+            <xsl:call-template name="make.adjusted.man.filename">
+              <xsl:with-param name="name">
+                <xsl:apply-templates/>
+              </xsl:with-param>
+              <xsl:with-param name="section" select="$section"/>
+            </xsl:call-template>
+          </xsl:with-param>
           <xsl:with-param name="quiet" select="$man.output.quietly"/>
-          <xsl:with-param
-              name="content"
-              select="concat('.so man', $section, '/',
-                      $first.refname, '.', $section, '&#10;')"/>
+          <xsl:with-param name="content">
+            <xsl:value-of select="concat('.so man', $section, '/')"/>
+            <xsl:call-template name="make.adjusted.man.filename">
+              <xsl:with-param name="name" select="$first.refname"/>
+              <xsl:with-param name="section" select="$section"/>
+            </xsl:call-template>
+            <xsl:text>&#10;</xsl:text>
+          </xsl:with-param>
         </xsl:call-template>
       </xsl:if>
     </xsl:for-each>
   </xsl:template>
 
+  <!-- ============================================================== -->
+
+  <!-- *  A manifest file is useful for doing “make clean” during -->
+  <!-- *  builds and for other purposes. When we make the manifest -->
+  <!-- *  file, we need to include in it a filename for each man-page -->
+  <!-- *  generated, including any “stub” pages. -->
+  <xsl:template name="generate.manifest">
+    <xsl:param name="filename">MAN.MANIFEST</xsl:param>
+    <xsl:variable name="filelist">
+      <xsl:for-each select="//refentry">
+        <!-- * all refname instances in a Refentry inherit their section -->
+        <!-- * numbers from the parent Refentry; so we only need to get -->
+        <!-- * the section once per Refentry, not once per Refname -->
+        <xsl:variable name="section">
+          <xsl:call-template name="get.refentry.section"/>
+        </xsl:variable>
+        <xsl:for-each select="refnamediv/refname">
+          <xsl:call-template name="make.adjusted.man.filename">
+            <xsl:with-param name="name" select="."/>
+            <xsl:with-param name="section" select="$section"/>
+          </xsl:call-template>
+          <xsl:text>&#10;</xsl:text>
+        </xsl:for-each>
+      </xsl:for-each>
+    </xsl:variable>
+
+    <!-- * we write the manifest file once per document, not once per -->
+    <!-- * Refentry -->
+    <xsl:call-template name="write.text.chunk">
+      <xsl:with-param name="filename">
+        <xsl:value-of select="$man.manifest.filename"/>
+      </xsl:with-param>
+      <xsl:with-param name="quiet" select="$man.output.quietly"/>
+      <xsl:with-param name="content">
+        <xsl:value-of select="$filelist"/>
+      </xsl:with-param>
+    </xsl:call-template>
+  </xsl:template>
+
 </xsl:stylesheet>
diff --git a/xsl/manpages/utility.xsl b/xsl/manpages/utility.xsl
index 9d3546cdf..c8efaf39e 100644
--- a/xsl/manpages/utility.xsl
+++ b/xsl/manpages/utility.xsl
@@ -211,7 +211,23 @@
   </xsl:template>
 
   <!-- ================================================================== -->
+
+  <!-- * Replace any spaces in $name with underscores & then append -->
+  <!-- * .$section to create a man filename -->
+
+  <xsl:template name="make.adjusted.man.filename">
+    <xsl:param name="name"/>
+    <xsl:param name="section"/>
+    <xsl:call-template name="string.subst">
+      <xsl:with-param name="string"
+                      select="concat(normalize-space($name), '.', normalize-space($section))"/>
+      <xsl:with-param name="target" select="' '"/>
+      <xsl:with-param name="replacement" select="'_'"/>
+    </xsl:call-template>
+  </xsl:template>
   
+  <!-- ================================================================== -->
+
   <!-- * Put a horizontal rule or other divider around section titles -->
   <!-- * in roff source (just to make things easier to read). -->
   <xsl:template name="mark.subheading">
-- 
2.40.0