From bb1fbd9a4d16d0e8cb8a670f82cd1a7fd77486c1 Mon Sep 17 00:00:00 2001
From: Michael Smith <xmldoc@users.sourceforge.net>
Date: Fri, 1 Jul 2005 13:24:49 +0000
Subject: [PATCH] Checkpointing. In the middle of tinkering with composition of
 the .TH title line. Started pulling at thread and unwound things. This works
 as-is now (not broken) but is not finished.

---
 xsl/manpages/docbook.xsl |  23 ++--
 xsl/manpages/general.xsl |  42 +++++++-
 xsl/manpages/info.xsl    | 223 +++++++++++++++++++++++++--------------
 3 files changed, 199 insertions(+), 89 deletions(-)

diff --git a/xsl/manpages/docbook.xsl b/xsl/manpages/docbook.xsl
index b1e86d003..750c3e6c0 100644
--- a/xsl/manpages/docbook.xsl
+++ b/xsl/manpages/docbook.xsl
@@ -120,23 +120,24 @@
       <!-- * TH.title.line = title line in header/footer of man page -->
       <!-- * - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
       <xsl:call-template name="TH.title.line">
-        <!-- * .TH "TITLE" "SECTION" "extra1" "extra2" "extra3" -->
+        <!-- * .TH TITLE  section  extra1  extra2  extra3 -->
         <!-- *  -->
-        <!-- * extra1 = date of publication of the man page (almost universally) -->
-        <!-- * extra2 = version and/or name of some kind (usually) -->
-        <!-- * extra3 = context description (e.g., often a description of the -->
-        <!-- *          group of related applications that the item documented -->
-        <!-- *          in the man page belongs to -->
+        <!-- * According to the man(7) man page: -->
+        <!-- *  -->
+        <!-- * extra1 = date,   "the date of the last revision" -->
+        <!-- * extra2 = source, "the source of the command" -->
+        <!-- * extra3 = manual, "the title of the manual -->
+        <!-- *                  (e.g., Linux Programmer's Manual)" -->
         <!-- * -->
-        <!-- * .TH TITLE SECTION DATE VERSION/NAME CONTEXT -->
+        <!-- * So, we end up with: -->
+        <!-- *  -->
+        <!-- * .TH TITLE  section  date  source  manual -->
         <!-- * -->
-        <!-- * If you want to chenge how the .TH line is constructed, change the -->
-        <!-- * order/content of the values of the "select" attributes below. -->
         <xsl:with-param name="title"   select="$metadata/title"/>
         <xsl:with-param name="section" select="$metadata/section"/>
         <xsl:with-param name="extra1"  select="$metadata/date"/>
-        <xsl:with-param name="extra2"  select="$metadata/versionorname"/>
-        <xsl:with-param name="extra3"  select="$metadata/othermetadata"/>
+        <xsl:with-param name="extra2"  select="$metadata/source"/>
+        <xsl:with-param name="extra3"  select="$metadata/manual"/>
       </xsl:call-template>
       <!-- * - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
       <!-- * Set default hyphenation, justification, and line-breaking -->
diff --git a/xsl/manpages/general.xsl b/xsl/manpages/general.xsl
index c5f12bab1..e6a00d06d 100644
--- a/xsl/manpages/general.xsl
+++ b/xsl/manpages/general.xsl
@@ -1,6 +1,9 @@
 <?xml version='1.0'?>
 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                 xmlns:exsl="http://exslt.org/common"
+                xmlns:dyn="http://exslt.org/dynamic"
+                xmlns:saxon="http://icl.com/saxon"
+                exclude-result-prefixes="exsl dyn saxon"
                 version='1.0'>
 
 <!-- ********************************************************************
@@ -244,5 +247,42 @@
       <xsl:text>&#10;</xsl:text>
     </xsl:if>
   </xsl:template>
-  
+
+  <!-- ================================================================== -->
+
+  <!-- * This function finds the first ocurrence of a anything -->
+  <!-- * matching the XPath expression given $profile. It relies on -->
+  <!-- * the XSLT evaluate() extension function. It appears to slow -->
+  <!-- * down processing with Saxon signficantly, but doesn't seem to -->
+  <!-- * slow down xsltproc at all. -->
+
+  <!--          The value of $profile can include the strings "$info" and -->
+  <!--          "$parentinfo". If found in the value of $profile, those are -->
+  <!--          evaluated using -->
+
+  <xsl:template name="find.first.profile.occurence">
+    <xsl:param name="profile"/>
+    <xsl:param name="info"/>
+    <xsl:param name="parentinfo"/>
+    <xsl:choose>
+      <!-- xsltproc and Xalan both support dyn:evaluate() -->
+      <xsl:when test="function-available('dyn:evaluate')">
+        <xsl:apply-templates
+            select="dyn:evaluate($profile)[1]/node()"/>
+      </xsl:when>
+      <!-- Saxon has its own evaluate() & doesn't support dyn:evaluate() -->
+      <xsl:when test="function-available('saxon:evaluate')">
+        <xsl:apply-templates
+            select="saxon:evaluate($profile)[1]/node()"/>
+      </xsl:when>
+      <xsl:otherwise>
+        <xsl:message terminate="yes">
+Error: The manpages stylesheets currently require an XSLT engine that
+supports the evaluate() XSLT extension function. Your XSLT engine does
+not support it.
+</xsl:message>
+      </xsl:otherwise>
+    </xsl:choose>
+  </xsl:template>
+
 </xsl:stylesheet>
diff --git a/xsl/manpages/info.xsl b/xsl/manpages/info.xsl
index 86338eb67..f256b84ae 100644
--- a/xsl/manpages/info.xsl
+++ b/xsl/manpages/info.xsl
@@ -14,6 +14,38 @@
 
      ******************************************************************** -->
 
+<xsl:param name="man.th.extra2.partA.profile">
+  $info/productname
+  |$parentinfo/productname
+  |$info/orgname
+  |$parentinfo/orgname
+  |$info/corpname
+  |$parentinfo/corpname
+  |$info/corpcredit
+  |$parentinfo/corpcredit
+  |$info/corpauthor
+  |$parentinfo/corpauthor
+  |$info/author/orgname
+  |$parentinfo/author/orgname
+  |$info//publishername
+  |$parentinfo//publishername
+</xsl:param>
+
+<xsl:param name="man.th.extra2.partB.profile">
+  refmeta/refmiscinfo[@class = 'version']
+  |$info/productnumber
+  |$parentinfo/productnumber
+  |$info/edition
+  |$parentinfo/edition
+  |$info/releaseinfo
+  |$parentinfo/releaseinfo
+</xsl:param>
+
+<xsl:param name="man.th.extra3.profile">
+  $parentinfo/title
+  |../title
+</xsl:param>
+
   <!-- ==================================================================== -->
 
   <xsl:template name="get.metadata">
@@ -22,28 +54,38 @@
 
     <!-- ******************************************************************** -->
     <!-- *  -->
-    <!-- * The get.metadata template returns a node-set with the following: -->
-    <!-- *  -->
+    <!-- * The get.metadata template returns a node-set with the elements -->
+    <!-- * listed below. The descriptions for <title>, <date>, <source>, -->
+    <!-- * and <manual> are all verbatim from the man(7) man page. -->
+    <!-- * -->
+    <!-- * -->
+    <!-- * <title>         = the title of the man page (e.g., MAN) -->
+    <!-- * <section>       = the section number the man page should be -->
+    <!-- *                   placed in (e.g., 7) -->
+    <!-- * <date>          = the date of the last revision -->
+    <!-- * <source>        = the source of the command -->
+    <!-- * <manual>        = the title of the manual (e.g., Linux -->
+    <!-- *                   Programmer's Manual) -->
+    <!-- * -->
     <!-- * <name>          = "real name" of the documented item -->
-    <!-- * <section>       = the man "section" that the documented item is in -->
     <!-- * <filename>      = <name>.<section>; for example: xsltproc.1 -->
-    <!-- * <title>         = often same as <name> but not necessarily -->
-    <!-- * <date>          = a date or maybe a pubdate -->
-    <!-- * <versionorname> = a version no. or product name. Or something else. -->
-    <!-- * <othermetadata> = other metadata :-) -->
-    <!-- *  -->
+    <!-- * -->
     <!-- ******************************************************************** -->
 
-    <!-- * $name & <name> = "real name" of the documented item; for example, in -->
-    <!-- * the case of a command, the <name> is what you would type in on the -->
-    <!-- * command line to run it. -->
+    <!-- * <name> = real name of the documented item -->
+    <!-- * -->    
+    <!-- * in the case of a command, the <name> is what you would type in -->
+    <!-- * on the command line to run it; that is, in DocBook, a <refname> -->
+    <!-- * (as opposed to a <refentrytitle> or <refdescriptor>) -->
     <xsl:variable name="name" select="refnamediv[1]/refname[1]"/>
     <name>
       <xsl:value-of select="$name"/>
     </name>
 
-    <!-- * $section & <section> = the man "section" that the documented item -->
-    <!-- * is in; if a manvolnum is not specified in the source, and we find -->
+    <!-- * <section> = "the section number the man page should be -->
+    <!-- *             placed in (e.g., 7)" -->
+    <!-- * -->    
+    <!-- * if we do not find a manvolnum specified in the source, and we find -->
     <!-- * that the refentry is for a function, we use the section number "3" -->
     <!-- * ["Library calls (functions within program libraries)"]; otherwise, -->
     <!-- * we default to using "1" ["Executable programs or shell commands"] -->
@@ -71,10 +113,12 @@
       </xsl:call-template>
     </filename>
 
-    <!-- * <title> = differs from <name> in that, if the refentry has a -->
-    <!-- * refentrytitle, we use that as the <title>; otherwise, we just use the -->
-    <!-- * <name>, which is the first refname in the first refnamediv in the -->
-    <!-- * source; see above -->
+    <!-- * <title> = "the title of the man page (e.g., MAN)" -->
+    <!-- * -->
+    <!-- * This differs from <name> in that, if the refentry has a -->
+    <!-- * refentrytitle, we use that as the <title>; otherwise, we -->
+    <!-- * just use the <name>, which is the first refname in the -->
+    <!-- * first refnamediv in the source; see above -->
     <title>
       <xsl:choose>
         <xsl:when test="refmeta/refentrytitle">
@@ -88,22 +132,19 @@
       </xsl:choose>
     </title>
 
-    <!-- * <date> is a date :-) If we can't find one, we add one; see below -->
+    <!-- * <date> = "the date of the last revision" -->
+    <!-- *          If we can't find one, we add one (see below) -->
     <date>
+      <xsl:variable name="Date">
+        <xsl:apply-templates
+            select="($info/date
+                    |$info/pubdate
+                    |$parentinfo/date
+                    |$parentinfo/pubdate)[1]/node()"/>
+      </xsl:variable>
       <xsl:choose>
-        <!-- look for date or pubdate in *info -->
-        <xsl:when test="$info/date|$info/pubdate">
-          <xsl:copy>
-            <xsl:apply-templates
-                select="($info/date/node()|$info/pubdate/node())[1]"/>
-          </xsl:copy>
-        </xsl:when>
-        <!-- look for date or pubdate in parent's *info -->
-        <xsl:when test="$parentinfo/date|$parentinfo/pubdate">
-          <xsl:copy>
-            <xsl:apply-templates
-                select="($parentinfo/date/node()|$parentinfo/pubdate/node())[1]"/>
-          </xsl:copy>
+        <xsl:when test="$Date != ''">
+          <xsl:value-of select="$Date"/>
         </xsl:when>
         <!-- * If we can't find a date, then we generate a date. -->
         <!-- * And we make it an appropriately localized date. -->
@@ -131,73 +172,101 @@
       </xsl:choose>
     </date>
 
-    <!-- * <versionorname> = (in the best case) we just want to find some kind -->
-    <!-- * of version number. If we can't find that, we try to find a product -->
-    <!-- * name. If we can't find that, we try to find some other kind of info. -->
-    <!-- * And if that fails, well, then we just leave it empty. -->
-    <versionorname>
+    <!-- * <source> = "the source of the command" -->
+    <!-- * -->
+    <!-- * Here are the examples from the man(7) man page: -->
+    <!-- * -->
+    <!-- *   For binaries, use something like: GNU, NET-2, -->
+    <!-- *   SLS Distribution, MCC Distribution. -->
+    <!-- * -->
+    <!-- *   For system calls, use the version of the -->
+    <!-- *   kernel that you are currently looking at: -->
+    <!-- *   Linux 0.99.11. -->
+    <!-- * -->
+    <!-- *   For library calls, use the source of the -->
+    <!-- *   function: GNU, BSD 4.3, Linux DLL 4.4.1. -->
+    <!-- * -->
+    <!-- * So, it looks like what we have is a two-part field, -->
+    <!-- * "PartA PartB", where: -->
+    <!-- * -->
+    <!-- *   PartA = product name (BSD) or organization name (GNU) -->
+    <!-- *   PartB = version name (if PartA is a product name) -->
+    <!-- * -->
+    <!-- * Each part is optional. -->
+    <!-- * -->
+    <source>
+      <!-- * by default, here we try to locate a product or -->
+      <!-- * organization or publisher name -->
+      <xsl:variable name="partA">
+        <xsl:call-template name="find.first.profile.occurence">
+          <xsl:with-param name="profile" select="$man.th.extra2.partA.profile"/>
+          <xsl:with-param name="info" select="$info"/>
+          <xsl:with-param name="parentinfo" select="$parentinfo"/>
+        </xsl:call-template>
+      </xsl:variable>
+      <!-- * by default, here we try to locate a version number -->
+      <xsl:variable name="partB">
+        <xsl:call-template name="find.first.profile.occurence">
+          <xsl:with-param name="profile" select="$man.th.extra2.partB.profile"/>
+          <xsl:with-param name="info" select="$info"/>
+          <xsl:with-param name="parentinfo" select="$parentinfo"/>
+        </xsl:call-template>
+      </xsl:variable>
       <xsl:choose>
-        <xsl:when test="$info/productnumber">
-          <xsl:apply-templates select="$info/productnumber/node()"/>
-        </xsl:when>
-        <xsl:when test="refmeta/refmiscinfo[@class = 'version']">
-          <xsl:apply-templates select="refmeta/refmiscinfo/node()"/>
-        </xsl:when>
-        <xsl:when test="$parentinfo/productnumber">
-          <xsl:apply-templates select="$parentinfo/productnumber/node()"/>
-        </xsl:when>
-        <xsl:when test="$info/productname">
-          <xsl:apply-templates select="$info/productname/node()"/>
-        </xsl:when>
-        <xsl:when test="$parentinfo/productname">
-          <xsl:apply-templates select="$parentinfo/productname/node()"/>
+        <!-- * if we have a partA and/or partB, use either or both -->
+        <!-- * of those, in the form "partA partB" or just "partA" -->
+        <!-- * or just "partB" -->
+        <xsl:when test="$partA != '' or $partB != ''">
+          <xsl:value-of select="normalize-space(concat($partA, ' ', $partB))"/>
         </xsl:when>
+        <!-- * if no partA or partB, use fallback (if any) -->
+        <!-- * by default, we fall back to first Refmiscinfo found -->
         <xsl:when test="refmeta/refmiscinfo">
           <xsl:apply-templates select="refmeta/refmiscinfo[1]/node()"/>
         </xsl:when>
         <xsl:otherwise>
-          <!-- found nothing, so leave it empty -->
+          <!-- * found nothing, so leave <source> empty -->
         </xsl:otherwise>
       </xsl:choose>
-    </versionorname>
+    </source>
 
-    <!-- * The <othermetadata> element holds information other than the title, -->
-    <!-- * section number, date, or application/product version/name; typically, -->
-    <!-- * what we want in <othermetadata> is some kind of "context description" -->
-    <!-- * about the item - for example, it is often a description of the -->
-    <!-- * "superset" of applications/functions, etc., that the item documented in -->
-    <!-- * the man page belongs to -->
+    <!-- * <manual> = "the title of the manual (e.g., Linux -->
+    <!-- *            Programmer's Manual)" -->
     <!-- * -->
-    <!-- * Examples: -->
+    <!-- * Examples from some real-world man pages: -->
     <!-- * -->
-    <!-- *   PROGRAM     CONTEXT INFO (in TH "extra3") -->
-    <!-- *   =======   - ==================================== -->
-    <!-- *   dpkg-name - "dpkg utilities" -->
-    <!-- *   GET       - "User Contributed Perl Documentation" -->
-    <!-- *   ld        - "GNU Development Tools" -->
-    <!-- *   ddate     - "Emperor Norton Utilities" -->
-    <!-- *   dh_clean  - "Debhelper" -->
-    <!-- *   faked     - "Debian GNU/Linux manual" -->
-    <!-- *   gimp      - "GIMP Manual Pages" -->
-    <!-- *   qt2kdoc   - "KDOC Documentation System" -->
+    <!-- *   dpkg-name  -  "dpkg utilities" -->
+    <!-- *   GET        -  "User Contributed Perl Documentation" -->
+    <!-- *   ld         -  "GNU Development Tools" -->
+    <!-- *   ddate      -  "Emperor Norton Utilities" -->
+    <!-- *   dh_clean   -  "Debhelper" -->
+    <!-- *   faked      -  "Debian GNU/Linux manual" -->
+    <!-- *   gimp       -  "GIMP Manual Pages" -->
+    <!-- *   qt2kdoc    -  "KDOC Documentation System" -->
     <!-- * -->
     <!-- * We just leave it empty if we can't find anything to use -->
-    <othermetadata>
+    <manual>
+      <xsl:variable name="Manual">
+        <xsl:call-template name="find.first.profile.occurence">
+          <xsl:with-param name="profile" select="$man.th.extra3.profile"/>
+          <xsl:with-param name="info" select="$info"/>
+          <xsl:with-param name="parentinfo" select="$parentinfo"/>
+        </xsl:call-template>
+      </xsl:variable>
       <xsl:choose>
-        <xsl:when test="$parentinfo/title">
-          <xsl:apply-templates select="$parentinfo/title/node()"/>
-        </xsl:when>
-        <xsl:when test="../title">
-          <xsl:apply-templates select="../title/node()"/>
+        <xsl:when test="$Manual != ''">
+          <xsl:value-of select="$Manual"/>
         </xsl:when>
+        <!-- * if no Manual, use contents of specified -->
+        <!-- * Fallback (if any) -->
         <xsl:when test="refmeta/refmiscinfo">
           <xsl:apply-templates select="refmeta/refmiscinfo[1]/node()"/>
         </xsl:when>
         <xsl:otherwise>
-          <!-- found nothing, so leave it empty -->
+          <!-- * found nothing, so leave it empty -->
         </xsl:otherwise>
       </xsl:choose>
-    </othermetadata>
+    </manual>
 
   </xsl:template>
 
-- 
2.40.0