From 621d83937b6b3a86d5a41644d92d991142741d93 Mon Sep 17 00:00:00 2001
From: Michael Smith <xmldoc@users.sourceforge.net>
Date: Tue, 5 Jul 2005 02:49:13 +0000
Subject: [PATCH] Did some reorganizing.

- Moved prepare.manpage.contents template out of general.xsl file
  and into other.xsl; general.xsl templates are now all templates
  that are called multiple times for each refentry, while
  templates in other.xsl are called only once per each refentry.

- Removed get.metadata template; refentry metadata gathering is
  now done by common/refentry.xsl in a way that is independent of
  the final output format; so the common/refentry.xsl templates
  can be called not just by manpages stylesheets, but by
  stylesheets for any other output format

- Added a write.man.file template. This is basically just a
  wrapper around the write.text.chunk template; it takes "name"
  and "section" params, assembles those into a filename, then
  passes that filename to write.text.chunk
---
 xsl/manpages/general.xsl |  81 +-----------
 xsl/manpages/info.xsl    | 266 ++-------------------------------------
 xsl/manpages/other.xsl   |  93 ++++++++++++--
 3 files changed, 94 insertions(+), 346 deletions(-)

diff --git a/xsl/manpages/general.xsl b/xsl/manpages/general.xsl
index e6a00d06d..d808af036 100644
--- a/xsl/manpages/general.xsl
+++ b/xsl/manpages/general.xsl
@@ -19,7 +19,8 @@
 <!-- ==================================================================== -->
 
 <!-- * This file contains named and "non element" templates that are -->
-<!-- * called by templates in the other manpages stylesheet files. -->
+<!-- * called multiple times per each Refentry, by templates in the other -->
+<!-- * manpages stylesheet files. -->
 
 <!-- ==================================================================== -->
 
@@ -197,92 +198,16 @@
     </xsl:for-each>
   </xsl:template>
 
-  <!-- ================================================================== -->
-
-  <!-- * The prepare.manpage.contents template is called after -->
-  <!-- * everything else has been done, just before writing the actual -->
-  <!-- * man-page files to the filesystem. It works on the entire roff -->
-  <!-- * source for each man page (not just the visible contents). -->
-  <xsl:template name="prepare.manpage.contents">
-    <xsl:param name="content" select="''"/>
-
-    <!-- * First do "essential" string/character substitutions; for -->
-    <!-- * example, the backslash character _must_ be substituted with -->
-    <!-- * a double backslash, to prevent it from being interpreted as -->
-    <!-- * a roff escape -->
-    <xsl:variable name="adjusted.content">
-      <xsl:call-template name="apply-string-subst-map">
-        <xsl:with-param name="content" select="$content"/>
-        <xsl:with-param name="map.contents"
-                        select="exsl:node-set($man.string.subst.map)/*"/>
-      </xsl:call-template>
-    </xsl:variable>
-
-    <!-- * Optionally, apply a character map to replace Unicode -->
-    <!-- * symbols and special characters. -->
-    <xsl:choose>
-      <xsl:when test="$man.charmap.enabled != '0'">
-        <xsl:call-template name="apply-character-map">
-          <xsl:with-param name="content" select="$adjusted.content"/>
-          <xsl:with-param name="map.contents"
-                          select="exsl:node-set($man.charmap.contents)/*"/>
-        </xsl:call-template>
-      </xsl:when>
-      <xsl:otherwise>
-        <!-- * if we reach here, value of $man.charmap.enabled is zero, -->
-        <!-- * so we just pass the adjusted contents through "as is" -->
-        <xsl:value-of select="$adjusted.content"/>
-      </xsl:otherwise>
-    </xsl:choose>
-  </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">
-    <xsl:if test="$man.subheading.divider != ''">
+    <xsl:if test="$man.subheading.divider.enabled != 0">
       <xsl:text>.\" </xsl:text>
       <xsl:value-of select="$man.subheading.divider"/>
       <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 f256b84ae..99f160e85 100644
--- a/xsl/manpages/info.xsl
+++ b/xsl/manpages/info.xsl
@@ -14,265 +14,11 @@
 
      ******************************************************************** -->
 
-<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">
-    <xsl:param name="info"/>
-    <xsl:param name="parentinfo"/>
-
-    <!-- ******************************************************************** -->
-    <!-- *  -->
-    <!-- * 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 -->
-    <!-- * <filename>      = <name>.<section>; for example: xsltproc.1 -->
-    <!-- * -->
-    <!-- ******************************************************************** -->
-
-    <!-- * <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> = "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"] -->
-    <xsl:variable name="section">
-      <xsl:choose>
-        <xsl:when test="refmeta/manvolnum">
-          <xsl:value-of select="refmeta/manvolnum"/>
-        </xsl:when>
-        <xsl:when test=".//funcsynopsis">3</xsl:when>
-        <xsl:otherwise>1</xsl:otherwise>
-      </xsl:choose>
-    </xsl:variable>
-    <section>
-      <xsl:value-of select="$section"/>
-    </section>
-    
-    <!-- * <filename> = name.section; for example: xsltproc.1 -->
-    <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), '.', $section)"/>
-        <xsl:with-param name="target" select="' '"/>
-        <xsl:with-param name="replacement" select="'_'"/>
-      </xsl:call-template>
-    </filename>
-
-    <!-- * <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">
-          <xsl:copy>
-            <xsl:apply-templates select="refmeta/refentrytitle/node()"/>
-          </xsl:copy>
-        </xsl:when>
-        <xsl:otherwise>
-          <xsl:copy-of select="$name"/>
-        </xsl:otherwise>
-      </xsl:choose>
-    </title>
-
-    <!-- * <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>
-        <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. -->
-        <xsl:otherwise>
-          <xsl:call-template name="datetime.format">
-            <xsl:with-param name="date">
-              <xsl:choose>
-                <xsl:when test="function-available('date:date-time')">
-                  <xsl:value-of select="date:date-time()"/>
-                </xsl:when>
-                <xsl:when test="function-available('date:dateTime')">
-                  <!-- Xalan quirk -->
-                  <xsl:value-of select="date:dateTime()"/>
-                </xsl:when>
-              </xsl:choose>
-            </xsl:with-param>
-            <xsl:with-param name="format">
-              <xsl:call-template name="gentext.template">
-                <xsl:with-param name="context" select="'datetime'"/>
-                <xsl:with-param name="name" select="'format'"/>
-              </xsl:call-template>
-            </xsl:with-param>
-          </xsl:call-template>
-        </xsl:otherwise>
-      </xsl:choose>
-    </date>
-
-    <!-- * <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>
-        <!-- * 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 <source> empty -->
-        </xsl:otherwise>
-      </xsl:choose>
-    </source>
-
-    <!-- * <manual> = "the title of the manual (e.g., Linux -->
-    <!-- *            Programmer's Manual)" -->
-    <!-- * -->
-    <!-- * Examples from some real-world man pages: -->
-    <!-- * -->
-    <!-- *   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 -->
-    <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="$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 -->
-        </xsl:otherwise>
-      </xsl:choose>
-    </manual>
-
-  </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>
@@ -337,11 +83,17 @@
 
   <!-- * ============================================================== -->
 
-  <!-- * suppress all *info (we grab what we need from it elsewhere -->
+  <!-- * suppress refmeta and all *info (we grab what we need from them -->
+  <!-- * elsewhere) -->
+
+  <xsl:template match="refmeta"/>
+
   <xsl:template match="info|refentryinfo|referenceinfo|refsynopsisdivinfo
                        |refsectioninfo|refsect1info|refsect2info|refsect3info
                        |articleinfo|chapterinfo|sectioninfo
                        |sect1info|sect2info|sect3info|sect4info|sect5info
                        |partinfo|prefaceinfo|appendixinfo|docinfo"/>
 
+  <!-- ============================================================== -->
+  
 </xsl:stylesheet>
diff --git a/xsl/manpages/other.xsl b/xsl/manpages/other.xsl
index 43a4cc053..558f7df4c 100644
--- a/xsl/manpages/other.xsl
+++ b/xsl/manpages/other.xsl
@@ -1,5 +1,7 @@
 <?xml version='1.0'?>
 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+                xmlns:exsl="http://exslt.org/common"
+                exclude-result-prefixes="exsl"
                 version='1.0'>
 
 <!-- ********************************************************************
@@ -13,13 +15,19 @@
      ******************************************************************** -->
 
 <!-- * This file contains named templates that are related to things -->
-<!-- * other than just generating the actual text of the main text flow -->
+<!-- * other than just assembling the actual text of the main text flow -->
 <!-- * of each man page. This "other" stuff currently amounts to: -->
 <!-- * -->
 <!-- *  - adding a comment to top part of roff source of each page -->
 <!-- *  - making a .TH title line (for controlling page header/footer) -->
 <!-- *  - setting hyphenation, alignment, & line-breaking defaults -->
-<!-- *  - writing any related "stub" pages -->
+<!-- *  - "preparing" the complete man page contents for final output -->
+<!-- *  - writing the actual man file to the filesystem -->
+<!-- *  - writing any "stub" pages to the filesystem -->
+<!-- * -->
+<!-- * The templates in this file are actually called only once per -->
+<!-- * each Refentry; they are just in a separate file for the purpose -->
+<!-- * of keeping things modular. -->
 
 <!-- ==================================================================== -->
 
@@ -128,6 +136,68 @@
     </xsl:if>
   </xsl:template>
 
+  <!-- ================================================================== -->
+
+  <!-- * The prepare.manpage.contents template is called after -->
+  <!-- * everything else has been done, just before writing the actual -->
+  <!-- * man-page files to the filesystem. It works on the entire roff -->
+  <!-- * source for each man page (not just the visible contents). -->
+  <xsl:template name="prepare.manpage.contents">
+    <xsl:param name="content" select="''"/>
+
+    <!-- * First do "essential" string/character substitutions; for -->
+    <!-- * example, the backslash character _must_ be substituted with -->
+    <!-- * a double backslash, to prevent it from being interpreted as -->
+    <!-- * a roff escape -->
+    <xsl:variable name="adjusted.content">
+      <xsl:call-template name="apply-string-subst-map">
+        <xsl:with-param name="content" select="$content"/>
+        <xsl:with-param name="map.contents"
+                        select="exsl:node-set($man.string.subst.map)/*"/>
+      </xsl:call-template>
+    </xsl:variable>
+
+    <!-- * Optionally, apply a character map to replace Unicode -->
+    <!-- * symbols and special characters. -->
+    <xsl:choose>
+      <xsl:when test="$man.charmap.enabled != 0">
+        <xsl:call-template name="apply-character-map">
+          <xsl:with-param name="content" select="$adjusted.content"/>
+          <xsl:with-param name="map.contents"
+                          select="exsl:node-set($man.charmap.contents)/*"/>
+        </xsl:call-template>
+      </xsl:when>
+      <xsl:otherwise>
+        <!-- * if we reach here, value of $man.charmap.enabled is zero, -->
+        <!-- * so we just pass the adjusted contents through "as is" -->
+        <xsl:value-of select="$adjusted.content"/>
+      </xsl:otherwise>
+    </xsl:choose>
+  </xsl:template>
+
+  <!-- ================================================================== -->
+  
+  <xsl:template name="write.man.file">
+    <xsl:param name="name"/>
+    <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>
+    </xsl:param>
+    <xsl:call-template name="write.text.chunk">
+      <xsl:with-param name="filename" select="$filename"/>
+      <xsl:with-param name="quiet" select="$man.output.quietly"/>
+      <xsl:with-param name="encoding" select="$man.output.encoding"/>
+      <xsl:with-param name="content" select="$content"/>
+    </xsl:call-template>
+  </xsl:template>
+
   <!-- ============================================================== -->
 
   <!-- * A "stub" is sort of alias for another file, intended to be read -->
@@ -137,25 +207,26 @@
   <!-- *  .so manX/realname.X -->
   <!-- * -->
   <!-- * "realname" is a name of another man-page file. That .so line is -->
-  <!-- * basically a *roff "include" statement.  When the man command finds -->
-  <!-- * it, it calls soelim(1) (I think) and includes and displays the -->
-  <!-- * contents of the manX/realqname.X file. -->
+  <!-- * basically a roff "include" statement.  When the man command finds -->
+  <!-- * it, it calls soelim(1) and includes and displays the contents of -->
+  <!-- * the manX/realqname.X file. -->
   <!-- * -->
   <!-- * If a refentry has multiple refnames, we generate a "stub" page for -->
-  <!-- * each additional refname found. -->
+  <!-- * each refname found, except for the first one. -->
   <xsl:template name="write.stubs">
-    <xsl:param name="metadata"/>
+    <xsl:param name="first.refname"/>
+    <xsl:param name="section"/>
     <xsl:for-each select="refnamediv/refname">
-      <xsl:if test=". != $metadata/name">
+      <xsl:if test=". != $first.refname">
         <xsl:call-template name="write.text.chunk">
           <xsl:with-param name="filename"
                           select="concat(normalize-space(.), '.',
-                                  $metadata/section)"/>
+                                  $section)"/>
           <xsl:with-param name="quiet" select="$man.output.quietly"/>
           <xsl:with-param
               name="content"
-              select="concat('.so man', $metadata/section, '/',
-                      $metadata/name, '.', $metadata/section, '&#10;')"/>
+              select="concat('.so man', $section, '/',
+                      $first.refname, '.', $section, '&#10;')"/>
         </xsl:call-template>
       </xsl:if>
     </xsl:for-each>
-- 
2.40.0