From b39d172d5600f8621661f9a5bec6135a8703e46b Mon Sep 17 00:00:00 2001
From: Michael Smith <xmldoc@users.sourceforge.net>
Date: Mon, 27 Mar 2006 04:48:09 +0000
Subject: [PATCH] Added cvs2cl2docbook.xsl stylesheet for converting
 XML-formatted ChangeLog output of the cvs2cl command into DocBook form. It
 uses Jeni Tennison's "Markup Utility" stylesheet to auto-mark-up instances of
 DocBook element and parameter names in commit messages. It also preserves
 newlines in the messages.

Removed older version of this stylesheet from xsl/
---
 releasetools/Targets.mk                       |  43 +++--
 releasetools/Variables.mk                     |  42 +++--
 .../cvs2cl2docbook.xsl                        | 155 +++++++++++++++++-
 .../get-latest-tag.xsl                        |   7 +-
 releasetools/get-terms.xsl                    | 135 +++++++++++++++
 5 files changed, 337 insertions(+), 45 deletions(-)
 rename xsl/docsrc/release-notes.xsl => releasetools/cvs2cl2docbook.xsl (56%)
 rename xsl/docsrc/get-element-names.xsl => releasetools/get-latest-tag.xsl (81%)
 create mode 100644 releasetools/get-terms.xsl

diff --git a/releasetools/Targets.mk b/releasetools/Targets.mk
index d2c9c282a..88eea828d 100644
--- a/releasetools/Targets.mk
+++ b/releasetools/Targets.mk
@@ -26,15 +26,11 @@ endif
 RELEASE-NOTES-$(TAGVER).xml: RELEASE-NOTES.xml NEWS.xml
 	$(XINCLUDE) $< > $@
 
-NEWS.xml: ChangeLog.xml
-	$(XSLT) $< $(NEWS_MAKER) $@ \
-	latest-tag="'$(shell cat LatestTag)'" \
-	release-version="'$(RELVER)'"
-	for element in \
-	  $(shell $(XSLT) $(DOCBOOK_RNG) $(GET_ELEMENT_NAMES) | sort | uniq); \
-	do $(SED) $(SED_OPTS) -i \
-	  "s/\([^<\/A-Za-z0-9_\.\-]\)\($$element\)\([^A-Za-z0-9_\.\-]\)/\1<FOOM>\2<\/FOOM>\3/g" $@; done; \
-	$(SED) $(SED_OPTS) -i s/FOOM/tag/g $@
+NEWS.xml: ChangesSince$(LATEST_TAG).xml TERMS.xml
+	$(XSLT) $< $(CVS2CL2DOCBOOK) $@ \
+	latest-tag="'$(LATEST_TAG)'" \
+	release-version="'$(RELVER)'" \
+	terms.file="'$(shell readlink -f TERMS.xml)'"
 
 NEWS.html: NEWS.xml
 	$(XSLT) $< $(DOC-LINK-STYLE) $@
@@ -42,9 +38,9 @@ NEWS.html: NEWS.xml
 $(NEWSFILE): NEWS.html
 	LANG=C $(BROWSER) $(BROWSER_OPTS) $< > $@
 
-ChangeLog.xml: LatestTag
+ChangesSince$(LATEST_TAG).xml: LatestTag
 	$(CVS2CL) $(CVS2CL_OPTS) \
-	--delta $(shell cat LatestTag):HEAD --xml -f $@ -g -q
+	--delta $(LATEST_TAG):HEAD --xml -f $@ -g -q
 
 LatestTag:
 # Note that one of the old commit messsage in the cvs log contains
@@ -54,6 +50,21 @@ LatestTag:
 	| $(SED) $(SED_OPTS) 's/\x1a//g' \
 	| $(XSLTPROC) $(GET_LATEST_TAG) - > $@
 
+ChangeLog.xml.zip: ChangeLog.xml
+	$(ZIP) $(ZIP_OPTS) $@ $<
+	$(RM) $<
+
+# ChangeLog.xml holds the whole change history for the module,
+# including all subdirectories
+ChangeLog.xml:
+	$(CVS2CL) $(CVS2CL_OPTS) \
+	--xml -f $@ -g -q
+
+TERMS.xml: $(GET_TERMS) $(DISTRIB_PARAMS_FILES) $(DOCBOOK_RNG_FILES)
+	$(XSLT) $< $< $@ \
+	element.files="'$(DOCBOOK_RNG_FILES)'" \
+	param.files="'$(DISTRIB_PARAMS_FILES)'"
+
 .CatalogManager.properties.example:
 	cp -p $(CATALOGMANAGER) .CatalogManager.properties.example
 
@@ -71,7 +82,7 @@ catalog.xml: .make-catalog.xsl
 install.sh: .CatalogManager.properties.example .urilist catalog.xml
 	cp $(INSTALL_SH) install.sh
 
-distrib: all $(DISTRIB_DEPENDS) RELEASE-NOTES.txt RELEASE-NOTES.pdf $(NEWSFILE)
+distrib: all $(DISTRIB_DEPENDS) ChangeLog.xml.zip RELEASE-NOTES.txt RELEASE-NOTES.pdf $(NEWSFILE)
 
 newversion:
 ifeq ($(CVSCHECK),)
@@ -157,7 +168,7 @@ endif
 	$(TAR) cf$(TARFLAGS) - -X $(TMP)/tar.exclude * .[^.]* | (cd $(TMP)/docbook-$(DISTRO)-$(ZIPVER); $(TAR) xf$(TARFLAGS) -)
 	umask 022; cd $(TMP) && $(TAR) cf$(TARFLAGS) - docbook-$(DISTRO)-$(ZIPVER) | gzip > docbook-$(DISTRO)-$(ZIPVER).tar.gz
 	umask 022; cd $(TMP) && $(TAR) cf$(TARFLAGS) - docbook-$(DISTRO)-$(ZIPVER) | bzip2 > docbook-$(DISTRO)-$(ZIPVER).tar.bz2
-	umask 022; cd $(TMP) && zip -q -rpD docbook-$(DISTRO)-$(ZIPVER).zip docbook-$(DISTRO)-$(ZIPVER)
+	umask 022; cd $(TMP) && $(ZIP) $(ZIPFLAGS) docbook-$(DISTRO)-$(ZIPVER).zip docbook-$(DISTRO)-$(ZIPVER)
 	$(RM) $(TMP)/tar.exclude
 
 # -----------------------------------------------------------------
@@ -187,7 +198,7 @@ ifneq ($(DISTRIB_PACKAGES),)
 	fi) ; \
 	umask 022; (cd $(TMP) && $(TAR) cf$(TARFLAGS) - docbook-$(DISTRO)-$(ZIPVER) | gzip > docbook-$(DISTRO)-$$part-$(ZIPVER).tar.gz); \
 	umask 022; (cd $(TMP) && $(TAR) cf$(TARFLAGS) - docbook-$(DISTRO)-$(ZIPVER) | bzip2 > docbook-$(DISTRO)-$$part-$(ZIPVER).tar.bz2); \
-	umask 022; (cd $(TMP) && zip -q -rpD docbook-$(DISTRO)-$$part-$(ZIPVER).zip docbook-$(DISTRO)-$(ZIPVER)); \
+	umask 022; (cd $(TMP) && $(ZIP) $(ZIPFLAGS) docbook-$(DISTRO)-$$part-$(ZIPVER).zip docbook-$(DISTRO)-$(ZIPVER)); \
 	$(RM) $(TMP)/tar.exclude; \
 	done
 endif
@@ -214,11 +225,13 @@ install: zip
 	   )"
 
 release-clean: clean
+	$(RM) TERMS.xml
 	$(RM) $(NEWSFILE)
 	$(RM) NEWS.html
 	$(RM) NEWS.xml
 	$(RM) RELEASE-NOTES-$(TAGVER).xml
-	$(RM) ChangeLog.xml
+	$(RM) ChangeLog.xml.zip
+	$(RM) ChangesSince$(LATEST_TAG).xml
 	$(RM) LatestTag
 	$(RM) RELEASE-NOTES.txt
 	$(RM) RELEASE-NOTES.html
diff --git a/releasetools/Variables.mk b/releasetools/Variables.mk
index e134c91e1..1fff6ef65 100644
--- a/releasetools/Variables.mk
+++ b/releasetools/Variables.mk
@@ -12,31 +12,19 @@ CATALOGMANAGER=$(DOCBOOK_CVS)/releasetools/.CatalogManager.properties.example
 INSTALL_SH=$(DOCBOOK_CVS)/releasetools/install.sh
 MAKECATALOG=$(DOCBOOK_CVS)/releasetools/make-catalog.xsl
 
-XSLTPROC=xsltproc
-XSLTPROC_OPTS=
-
-XMLLINT=xmllint
-XMLLINT_OPTS=
-XINCLUDE=$(XMLLINT) $(XMLLINT_OPTS) --xinclude
-
-CVS2CL=cvs2cl
-CVS2CL_OPTS=
-
-SED=sed
-SED_OPTS=
-
 # stylesheet for generating HTML version of release notes
 DOC-LINK-STYLE=$(DOCBOOK_CVS)/xsl/docsrc/doc-link-docbook.xsl
 
-# stylesheet used in making NEWS file(s) and releases notes
-NEWS_MAKER=docsrc/release-notes.xsl
+# stylesheet used in taking XML output from the cvs2cl(1) perl
+# script, and using it to generate NEWS file(s) and releases notes
+CVS2CL2DOCBOOK=$(DOCBOOK_CVS)/releasetools/cvs2cl2docbook.xsl
 
 # stylesheet used for determining the latest cvs tag in cvs log
-GET_LATEST_TAG=docsrc/get-latest-tag.xsl
+GET_LATEST_TAG=$(DOCBOOK_CVS)/releasetools/get-latest-tag.xsl
 
-GET_ELEMENT_NAMES=docsrc/get-element-names.xsl
+GET_TERMS=$(DOCBOOK_CVS)/releasetools/get-terms.xsl
 
-DOCBOOK_RNG=../docbook/relaxng/docbook/docbook.rng
+DOCBOOK_RNG_FILES=$(DOCBOOK_CVS)/docbook/relaxng/docbook/docbook.rng
 
 # stylesheet for generating FO version of release notes
 FO-STYLE=$(DOCBOOK_CVS)/xsl/fo/docbook.xsl
@@ -55,6 +43,8 @@ FO_ENGINE_OPTS=
 # file containing "What's New" info generated from CVS log
 NEWSFILE=NEWS
 
+LATEST_TAG=$(shell if [ -f LatestTag ];then cat LatestTag; fi)
+
 # determine RELVER automatically by:
 #
 #   - figuring out if VERSION file exists
@@ -147,3 +137,19 @@ RELEASE_DIR=/home/groups/d/do/docbook/htdocs/release
 PROJECT_USER:=`sed 's/^:.\+:\([^@]\+\)@.\+$$/\1/' CVS/Root`
 TAR=tar
 TARFLAGS=P
+ZIP=zip
+ZIPFLAGS=-q -rpD
+
+XSLTPROC=xsltproc
+XSLTPROC_OPTS=
+
+XMLLINT=xmllint
+XMLLINT_OPTS=
+XINCLUDE=$(XMLLINT) $(XMLLINT_OPTS) --xinclude
+
+CVS2CL=cvs2cl
+CVS2CL_OPTS=
+
+SED=sed
+SED_OPTS=
+
diff --git a/xsl/docsrc/release-notes.xsl b/releasetools/cvs2cl2docbook.xsl
similarity index 56%
rename from xsl/docsrc/release-notes.xsl
rename to releasetools/cvs2cl2docbook.xsl
index 0d10fa686..93d052a7b 100644
--- a/xsl/docsrc/release-notes.xsl
+++ b/releasetools/cvs2cl2docbook.xsl
@@ -1,8 +1,9 @@
 <?xml version='1.0'?>
 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+                xmlns:exsl="http://exslt.org/common"
                 xmlns:sf="http://sourceforge.net/"
                 xmlns:cvs="http://www.red-bean.com/xmlns/cvs2cl/"
-                exclude-result-prefixes="sf cvs"
+                exclude-result-prefixes="exsl sf cvs"
                 version='1.0'>
   <!-- ********************************************************************
        $Id$
@@ -14,9 +15,42 @@
 
        ******************************************************************** -->
 
-  <!-- * This file auto-generates release-notes documentation from -->
-  <!-- * XML-formatted ChangeLog output of the cvs2cl command -->
+  <!-- * the markup.xsl file is Jeni Tennison's "Markup Utility" stylesheet -->
+  <!-- * -->
+  <!-- *   http://www.jenitennison.com/xslt/utilities/markup.html -->
+  <!-- * -->
+  <xsl:import href="../contrib/tools/tennison/markup.xsl" />
+  <xsl:include href="../xsl/lib/lib.xsl" />
+
+  <!-- * name of file that contains DocBook element names and DocBook -->
+  <!-- * param names -->
+  <xsl:param name="terms.file"/>
+
+  <!-- * This stylesheet converts XML-formatted ChangeLog output of the -->
+  <!-- * cvs2cl command into DocBook form. -->
+  <!-- * -->
   <!-- *   http://www.red-bean.com/cvs2cl/ -->
+  <!-- * -->
+  <!-- * Features :-->
+  <!-- * -->
+  <!-- * - groups commit messages by subdirectory name and generates -->
+  <!-- *   a Sect2 wrapper around each group (for example, all commit -->
+  <!-- *   messages for the "lib" subdirectory get grouped together -->
+  <!-- *   into a "Lib" Sect2 section -->
+  <!-- * -->
+  <!-- * - within each Sect2 section, generates an Itemizedlist, one -->
+  <!-- *   Listitem for each commit message -->
+  <!-- * -->
+  <!-- * - uses Jeni Tennison's "Markup Utility" stylesheet to -->
+  <!-- *   recognize special terms and mark them up; specifically, it -->
+  <!-- *   looks DocBook element names in commit messages and marks -->
+  <!-- *   them up with <tag>foo</tag> instances, an looks for DocBook -->
+  <!-- *   XSL stylesheet param names, and marks them up with -->
+  <!-- *   <parameter>hoge.moge.baz</parameter> instances -->
+  <!-- * -->
+  <!-- * - preserves newlines (by converting them to <sbr/> instances) -->
+  <!-- * -->
+  <!-- * - converts cvs usernames to corresponding users' real names -->
 
   <xsl:param name="release-version"/>
   <xsl:param name="release-version-ncname">
@@ -183,7 +217,7 @@
     <xsl:param name="dirname"/>
     <xsl:for-each select="cvs:entry[cvs:file/cvs:name[starts-with(.,concat($dirname,'/'))]]">
       
-      <!-- * each Listem corresponds to a single commit -->
+      <!-- * each Lisitem corresponds to a single commit -->
       <listitem>
         <xsl:text>&#xa;</xsl:text>
         <!-- * for each entry (commit), get just the commit message and -->
@@ -198,7 +232,32 @@
   </xsl:template>
 
   <xsl:template match="cvs:msg">
-    <xsl:apply-templates/>
+    <!-- * trim off any leading and trailing whitespace from this -->
+    <!-- * commit message -->
+    <xsl:variable name="trimmed">
+      <xsl:call-template name="trim.text">
+        <xsl:with-param name="contents" select="."/>
+      </xsl:call-template>
+    </xsl:variable>
+    <xsl:variable name="trimmed-contents" select="exsl:node-set($trimmed)"/>
+    <!-- * mask any periods in the contents -->
+    <xsl:variable name="masked-contents">
+      <xsl:apply-templates mode="mask.period" select="$trimmed-contents"/>
+    </xsl:variable>
+    <!-- * merk up the elements and params in the masked contents -->
+    <xsl:variable name="marked.up.contents">
+      <xsl:call-template name="markup">
+        <xsl:with-param name="text" select="$masked-contents" />
+        <xsl:with-param
+            name="phrases"
+            select="document($terms.file)//param|
+                    document($terms.file)//element"
+            />
+      </xsl:call-template>
+    </xsl:variable>
+    <xsl:variable name="marked.up" select="exsl:node-set($marked.up.contents)"/>
+    <!-- * return the marked-up contents, unmasked -->
+      <xsl:apply-templates select="$marked.up" mode="restore.period"/>
   </xsl:template>
 
   <xsl:template match="cvs:author">
@@ -208,6 +267,90 @@
     <xsl:value-of select="document('')//sf:users/sf:user[sf:username = $username]/sf:realname"/>
   </xsl:template>
 
-  <xsl:template match="*"/>
+  <xsl:template match="element" mode="markup">
+    <xsl:param name="word" />
+    <tag><xsl:value-of select="$word" /></tag>
+  </xsl:template>
+
+  <xsl:template match="param" mode="markup">
+    <xsl:param name="word" />
+    <parameter><xsl:value-of select="$word" /></parameter>
+  </xsl:template>
+
+  <!-- * ============================================================== -->
+  <!-- *    Kludges for dealing with dots in/after names                -->
+  <!-- * ============================================================== -->
+
+  <!-- * The mask.period and restore.period kludges are an attempt to -->
+  <!-- * deal with the need to make sure that parameters names that -->
+  <!-- * contain element names get marked up correctly -->
+
+  <!-- * The following mode "masks" periods by converting them to houses -->
+  <!-- * (that is, Unicode character x2302). It masks periods that are -->
+  <!-- * followed by a space or newline, or any period that is the last -->
+  <!-- * character in the given text node. -->
+  <xsl:template match="text()" mode="mask.period">
+    <xsl:call-template name="string.subst">
+      <xsl:with-param name="target">.&#xa;</xsl:with-param>
+      <xsl:with-param name="replacement">;&#x2302;&#xa;</xsl:with-param>
+      <xsl:with-param name="string">
+        <xsl:call-template name="string.subst">
+          <xsl:with-param name="target">. </xsl:with-param>
+          <xsl:with-param name="replacement">;&#x2302; </xsl:with-param>
+          <xsl:with-param name="string">
+              <xsl:choose>
+                <xsl:when test="substring(., string-length(.)) = '.'">
+                  <xsl:value-of
+                      select="concat(substring(.,1,string-length(.) - 1),';&#x2302;')"/>
+                </xsl:when>
+                <xsl:otherwise>
+                  <xsl:copy-of select="."/>
+                </xsl:otherwise>
+            </xsl:choose>
+          </xsl:with-param>
+        </xsl:call-template>
+      </xsl:with-param>
+    </xsl:call-template>
+  </xsl:template>
+
+  <!-- * unwind results of mask.period - and, as a bonus, convert all -->
+  <!-- * newlines characters to instances of a"linebreak element" -->
+  <xsl:template match="text()" mode="restore.period">
+    <xsl:call-template name="newlines.to.linebreak.element">
+      <xsl:with-param name="string">
+        <xsl:call-template name="string.subst">
+          <xsl:with-param name="string" select="."/>
+          <xsl:with-param name="target">;&#x2302;</xsl:with-param>
+          <xsl:with-param name="replacement">.</xsl:with-param>
+        </xsl:call-template>
+      </xsl:with-param>
+    </xsl:call-template>
+  </xsl:template>
+
+  <xsl:template match="*" mode="restore.period">
+    <xsl:copy-of select="."/>
+  </xsl:template>
+
+  <!-- * ============================================================== -->
+  <!-- *    Utility template for preserving linebreaks in output        -->
+  <!-- * ============================================================== -->
+  <xsl:template name="newlines.to.linebreak.element">
+    <xsl:param name="string"/>
+    <xsl:param name="linebreak.element"><sbr /></xsl:param>
+    <xsl:choose>
+      <xsl:when test="contains($string, '&#xA;')">
+        <xsl:value-of select="substring-before($string, '&#xA;')" />
+        <xsl:copy-of select="$linebreak.element" />
+        <xsl:call-template name="newlines.to.linebreak.element">
+          <xsl:with-param name="string"
+                          select="substring-after($string, '&#xA;')" />
+        </xsl:call-template>
+      </xsl:when>
+      <xsl:otherwise>
+        <xsl:value-of select="$string" />
+      </xsl:otherwise>
+    </xsl:choose>
+  </xsl:template>
 
 </xsl:stylesheet>
+
diff --git a/xsl/docsrc/get-element-names.xsl b/releasetools/get-latest-tag.xsl
similarity index 81%
rename from xsl/docsrc/get-element-names.xsl
rename to releasetools/get-latest-tag.xsl
index 7e2056c9b..e0ec25004 100644
--- a/xsl/docsrc/get-element-names.xsl
+++ b/releasetools/get-latest-tag.xsl
@@ -11,18 +11,13 @@
 
        ******************************************************************** -->
 
-  <xsl:param name="docbook.rng"/>
-
   <xsl:output method="text"/>
 
   <xsl:template match="/">
     <!-- * Get the value of the first tagdatetag element in the document -->
     <!-- * that starts with a "V" (V1691, etc.). That is, hopefully, the -->
     <!-- * tag for the previous release. -->
-    <xsl:for-each select="//*[local-name() = 'element'][@name]">
-      <xsl:value-of select="@name"/>
-      <xsl:text>&#xa;</xsl:text>
-    </xsl:for-each>
+    <xsl:value-of select="(//*[local-name() = 'tagdatetag'][starts-with(.,'V')])[1]"/>
   </xsl:template>
 
 </xsl:stylesheet>
diff --git a/releasetools/get-terms.xsl b/releasetools/get-terms.xsl
new file mode 100644
index 000000000..61fe5f188
--- /dev/null
+++ b/releasetools/get-terms.xsl
@@ -0,0 +1,135 @@
+<?xml version='1.0'?>
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+                version='1.0'>
+  <!-- ********************************************************************
+       $Id$
+       ********************************************************************
+
+       This file is part of the XSL DocBook Stylesheet distribution.
+       See ../README or http://docbook.sf.net/release/xsl/current/ for
+       copyright and other information.
+
+       ******************************************************************** -->
+  
+  <!-- * Given a list of files, this stylesheet collects certain -->
+  <!-- * element names (or "terms") from those files. The resulting -->
+  <!-- * list of terms is intended for use by another stylesheet that-->
+  <!-- * does processing of docs containing instances of the terms. -->
+ 
+  <!-- * the name of the root element to put into the result tree -->
+  <xsl:param name="result.root.element">terms</xsl:param>
+
+  <!-- * $element.files is a space-separated list of file names of RELAX -->
+  <!-- * NG schema files (.rng files, in the XML syntax) -->
+  <xsl:param name="element.files"/>
+
+  <!-- * $param.files is a space-separated list of file names of -->
+  <!-- * XSL files that contain param instances -->
+  <xsl:param name="param.files"/>
+
+  <xsl:template match="/">
+    <xsl:text>&#xa;</xsl:text>
+    <xsl:element name="{$result.root.element}">
+      <xsl:text>&#xa;</xsl:text>
+      <!-- * The following calls to the process.file template each pass data -->
+      <!-- * from a *.files param split into two parts: the part before the -->
+      <!-- * first space (the first filenames in the list), and the part -->
+      <!-- * after (all the other filenames) -->
+
+      <!-- * process the param files -->
+      <xsl:call-template name="process.file">
+        <xsl:with-param name="element">param</xsl:with-param>
+        <xsl:with-param name="file">
+          <xsl:choose>
+            <xsl:when test="contains($param.files, ' ')">
+              <xsl:value-of select="normalize-space(substring-before($param.files, ' '))"/>
+            </xsl:when>
+            <xsl:otherwise>
+              <xsl:value-of select="$param.files"/>
+            </xsl:otherwise>
+          </xsl:choose>
+        </xsl:with-param>
+        <xsl:with-param
+            name="remaining.files"
+            select="concat(normalize-space(substring-after($param.files, ' ')),' ')"/>
+      </xsl:call-template>
+
+      <!-- * process the element files -->
+      <xsl:call-template name="process.file">
+        <xsl:with-param name="element">element</xsl:with-param>
+        <xsl:with-param name="file">
+          <xsl:choose>
+            <xsl:when test="contains($element.files, ' ')">
+              <xsl:value-of select="normalize-space(substring-before($element.files, ' '))"/>
+            </xsl:when>
+            <xsl:otherwise>
+              <xsl:value-of select="$element.files"/>
+            </xsl:otherwise>
+          </xsl:choose>
+        </xsl:with-param>
+        <xsl:with-param
+            name="remaining.files"
+            select="concat(normalize-space(substring-after($element.files, ' ')),' ')"/>
+      </xsl:call-template>
+
+    </xsl:element>
+  </xsl:template>
+
+  <xsl:template name="process.file">
+    <!-- * This template does tail-recursion through a space-separated -->
+    <!-- * list of filenames, popping off filenames until it depletes the -->
+    <!-- * list. For each filename, it looks through the file for any -->
+    <!-- * elements matching the name given by $element, then runs -->
+    <!-- * apply-templates on that. -->
+    <xsl:param name="element"/>
+    <xsl:param name="file"/>
+    <xsl:param name="remaining.files"/>
+    <!-- * When the value of $file reaches empty, then we have depleted -->
+    <!-- * the list of filenames and it is time to stop recursing -->
+    <xsl:if test="not($file = '')">
+      <!-- * Only process elements that have a "name" attribute and  -->
+      <!-- * that are not in our list of "stop words" (common words -->
+      <!-- * that we don't want want to handle as terms. FIXME: -->
+      <!-- * ideally, the list of stop words probably ought to be -->
+      <!-- * parameterized somehow; but this works fine for now. -->
+      <xsl:for-each
+          select="document($file)//*[local-name() = $element]
+                  [@name
+                  and not(@name = 'set')
+                  and not(@name = 'part')
+                  and not(@name = 'parameter')
+                  and not(@name = 'optional')
+                  and not(@name = 'note')
+                  and not(@name = 'example')
+                  and not(@name = 'warning')
+                  and not(@name = 'type')
+                  and not(@name = 'markup')
+                  ]">
+        <xsl:apply-templates select="."/>
+      </xsl:for-each>
+      <xsl:call-template name="process.file">
+        <xsl:with-param name="element">param</xsl:with-param>
+        <!-- * pop the name of the next file off the list of -->
+        <!-- * remaining files -->
+        <xsl:with-param
+            name="file"
+            select="substring-before($remaining.files, ' ')"/>
+        <!-- * remove the current file from the list of -->
+        <!-- * remaining files -->
+        <xsl:with-param
+            name="remaining.files"
+            select="substring-after($remaining.files, ' ')"/>
+      </xsl:call-template>
+    </xsl:if>
+  </xsl:template>
+
+  <xsl:template match="*">
+    <!-- * For each match, add an element to the result tree, with the -->
+    <!-- * name of the element being the local name of the element in the -->
+    <!-- * source, and the content being the value of the "name" attribute -->
+    <!-- * on the element in the original source. -->
+    <xsl:element name="{local-name(.)}"><xsl:value-of select="@name"/></xsl:element>
+    <xsl:text>&#xa;</xsl:text>
+  </xsl:template>
+  
+</xsl:stylesheet>
-- 
2.40.0