From: Michael Smith <xmldoc@users.sourceforge.net>
Date: Sun, 22 Jul 2007 10:29:01 +0000 (+0000)
Subject: Added support for auto-generating doc hyperlinks for names of
X-Git-Tag: release/1.79.1~6^2~1895
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=45636c27221bfe161d4335a28bbf8f6a3ed0d661;p=docbook-dsssl

Added support for auto-generating doc hyperlinks for names of
docbook-xsl PIs referenced in the docs.
---

diff --git a/releasetools/Variables.mk b/releasetools/Variables.mk
index 7623df0e3..a3ddd7192 100644
--- a/releasetools/Variables.mk
+++ b/releasetools/Variables.mk
@@ -36,9 +36,12 @@ JREF2REFSECT1=$(DOCBUILD_STYLESHEETS)/jref2refsect1.xsl
 MAKE_ELEMENTS_XSL=$(DOCBUILD_STYLESHEETS)/make-elements.xsl
 # XSL params files to params list
 MAKE_PARAMS_XSL=$(DOCBUILD_STYLESHEETS)/make-xsl-params.xsl
+# XSL PI files to PI list
+MAKE_PI_XSL=$(DOCBUILD_STYLESHEETS)/make-xsl-pi.xsl
 # generated elements list
 DOCBOOK_ELEMENTS=$(DOCBUILD_STYLESHEETS)/docbook-elements.xsl
 XSL_PARAMS=$(DOCBUILD_STYLESHEETS)/xsl-params.xsl
+XSL_PI=$(DOCBUILD_STYLESHEETS)/xsl-pi.xsl
 DOCPARAM2TXT=$(DOCBUILD_STYLESHEETS)/docparam2txt.xsl
 
 # reference.xml to reference.html
diff --git a/xsl/docsrc/Makefile b/xsl/docsrc/Makefile
index 22cf9511a..66664c908 100644
--- a/xsl/docsrc/Makefile
+++ b/xsl/docsrc/Makefile
@@ -11,8 +11,9 @@ OTHER_XML_FILES=../common/common.xml ../common/utility.xml ../common/refentry.xm
 
 DOCBOOK_RNG=$(DOCBOOK_SVN)/releasetools/docbook.rng
 PARAM_XSL_FILES=$(foreach format,$(PARAM_DIRS),../$(format)/param.xsl)
+PI_XSL_FILES=$(foreach format,$(PI_DIRS),../$(format)/pi.xsl)
 
-all: $(PARAM_XML_FILES) ../lib/lib.xml $(PI_XML_FILES) $(OTHER_XML_FILES) $(DOCBOOK_ELEMENTS) $(XSL_PARAMS)
+all: $(PARAM_XML_FILES) ../lib/lib.xml $(PI_XML_FILES) $(OTHER_XML_FILES) $(DOCBOOK_ELEMENTS) $(XSL_PARAMS) $(XSL_PI)
 
 ../%/param.xml:
 	$(MAKE) -C $(dir $@) param.xml
@@ -39,6 +40,9 @@ $(DOCBOOK_ELEMENTS): $(MAKE_ELEMENTS_XSL) $(DOCBOOK_RNG)
 $(XSL_PARAMS): $(MAKE_PARAMS_XSL) $(PARAM_XSL_FILES)
 	$(XSLT) $< $< $@
 
+$(XSL_PI): $(MAKE_PI_XSL) $(PI_XSL_FILES)
+	$(XSLT) $< $< $@
+
 release-clean: clean
 	$(RM) $(DOCBOOK_ELEMENTS)
 	$(RM) $(XSL_PARAMS)
diff --git a/xsl/tools/xsl/build/.cvsignore b/xsl/tools/xsl/build/.cvsignore
index 820a42ae3..f6d8980e2 100644
--- a/xsl/tools/xsl/build/.cvsignore
+++ b/xsl/tools/xsl/build/.cvsignore
@@ -1,2 +1,3 @@
 docbook-elements.xsl
 xsl-params.xsl
+xsl-pi.xsl
diff --git a/xsl/tools/xsl/build/make-xsl-pi.xsl b/xsl/tools/xsl/build/make-xsl-pi.xsl
new file mode 100644
index 000000000..47b929a4f
--- /dev/null
+++ b/xsl/tools/xsl/build/make-xsl-pi.xsl
@@ -0,0 +1,133 @@
+<?xml version="1.0"?>
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+  xmlns:exsl="http://exslt.org/common"
+  xmlns:xslt="dummy"
+  xmlns:doc="http://nwalsh.com/xsl/documentation/1.0"
+  version="1.0">
+  <xsl:output indent="yes"/>
+  <xsl:namespace-alias stylesheet-prefix="xslt" result-prefix="xsl"/>
+  <!-- ********************************************************************
+       $Id: make-xsl-params.xsl 6853 2007-06-22 10:35:45Z xmldoc $
+       ********************************************************************
+
+       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.
+
+       ******************************************************************** -->
+
+  <!-- ==================================================================== -->
+
+  <!-- * This stylesheet expects itself as input  -->
+  <xsl:param name="pi.dirs">html fo common</xsl:param>
+
+  <xsl:template match="/">
+    <xslt:stylesheet version="1.0"> 
+      <xsl:text>&#xa;</xsl:text>
+      <xsl:text>&#xa;</xsl:text>
+      <xsl:comment> * WARNING WARNING WARNING </xsl:comment>
+      <xsl:text>&#xa;</xsl:text>
+      <xsl:comment> * WARNING WARNING WARNING </xsl:comment>
+      <xsl:text>&#xa;</xsl:text>
+      <xsl:comment> * This stylesheet was generated automatically. </xsl:comment>
+      <xsl:text>&#xa;</xsl:text>
+      <xsl:comment> * Edit the make-xsl-pi.xsl file to rebuild this. </xsl:comment>
+      <xsl:text>&#xa;</xsl:text>
+      <xsl:comment> * WARNING WARNING WARNING </xsl:comment>
+      <xsl:text>&#xa;</xsl:text>
+      <xsl:comment> * WARNING WARNING WARNING </xsl:comment>
+
+      <xslt:variable name="xsl-pi-list">
+        <simplelist role="pi">
+          <!-- * Process pis for each directory that's listed in $pi.dirs, -->
+          <!-- * by splitting the value of $pi.dirs into two parts: the part -->
+          <!-- * before the first space (first directory name in the list), and -->
+          <!-- * the part after the first space (all other directory names) -->
+          <xsl:call-template name="make.pi.list">
+            <xsl:with-param name="dir">
+              <xsl:choose>
+                <xsl:when test="contains($pi.dirs, ' ')">
+                  <xsl:value-of select="normalize-space(substring-before($pi.dirs, ' '))"/>
+                </xsl:when>
+                <xsl:otherwise>
+                  <xsl:value-of select="$pi.dirs"/>
+                </xsl:otherwise>
+              </xsl:choose>
+            </xsl:with-param>
+            <xsl:with-param
+              name="remaining.dirs"
+              select="concat(normalize-space(substring-after($pi.dirs, ' ')),' ')"/>
+          </xsl:call-template>
+        </simplelist>
+      </xslt:variable>
+      <xslt:variable name="xsl-pi" select="exsl:node-set($xsl-pi-list)/simplelist"/>
+      <xslt:template name="is-pi">
+        <xslt:param name="pi" select="''"/>
+        <xslt:choose>
+          <xslt:when test="$xsl-pi/member[. = $pi]">1</xslt:when>
+          <xslt:otherwise>0</xslt:otherwise>
+        </xslt:choose>
+      </xslt:template>
+    </xslt:stylesheet>
+    <xsl:text>&#x0a;</xsl:text>
+  </xsl:template>
+
+  <!-- ==================================================================== -->
+
+  <!-- * The following templates do tail-recursion through a space-separated -->
+  <!-- * list of directories, popping off directory names until they -->
+  <!-- * deplete the list. -->
+  
+  <xsl:template name="make.pi.list">
+    <!-- * For each directory, construct a relative URL for a -->
+    <!-- * pi.xsl file, then read through that pi.xsl file -->
+    <!-- * to collect PI names. -->
+    <xsl:param name="dir"/>
+    <xsl:param name="adjusted-dir">
+      <xsl:call-template name="make.adjusted-dir">
+        <xsl:with-param name="dir" select="$dir"/>
+      </xsl:call-template>
+    </xsl:param>
+    <xsl:param name="remaining.dirs"/>
+    <!-- * When the value of $dir reaches empty, then we have depleted -->
+    <!-- * the list of directories and it's time to stop recursing -->
+    <xsl:if test="not($dir = '')">
+      <xsl:variable name="pi.xsl" select="concat('../../../', $dir, '/', 'pi.xsl')"/>
+      <xsl:for-each select="document($pi.xsl)//doc:pi">
+        <xsl:sort select="@name"/>
+        <member><xsl:value-of select="@name"/></member>
+      </xsl:for-each>
+      <xsl:call-template name="make.pi.list">
+        <!-- * pop the name of the next directory off the list of -->
+        <!-- * remaining directories -->
+        <xsl:with-param
+          name="dir"
+          select="substring-before($remaining.dirs, ' ')"/>
+        <!-- * remove the current directory from the list of -->
+        <!-- * remaining directories -->
+        <xsl:with-param
+          name="remaining.dirs"
+          select="substring-after($remaining.dirs, ' ')"/>
+      </xsl:call-template>
+    </xsl:if>
+  </xsl:template>
+
+  <xsl:template name="make.adjusted-dir">
+    <xsl:param name="dir"/>
+    <xsl:param name="basedir">
+      <xsl:value-of select="substring-before($dir, '/')"/>
+    </xsl:param>
+    <xsl:param name="subdir">
+      <xsl:value-of select="substring-after($dir, '/')"/>
+    </xsl:param>
+      <xsl:choose>
+        <xsl:when test="contains($dir,'/')">
+          <xsl:value-of select="concat($basedir,'-',$subdir)"/>
+        </xsl:when>
+        <xsl:otherwise>
+          <xsl:value-of select="$dir"/>
+        </xsl:otherwise>
+      </xsl:choose>
+  </xsl:template>
+
+</xsl:stylesheet>
diff --git a/xsl/tools/xsl/build/reference.xsl b/xsl/tools/xsl/build/reference.xsl
index 18430c4df..e0bfc5dce 100644
--- a/xsl/tools/xsl/build/reference.xsl
+++ b/xsl/tools/xsl/build/reference.xsl
@@ -1,6 +1,7 @@
 <?xml version="1.0" encoding="utf-8"?>
 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
-                version="1.0">
+  xmlns:xlink="http://www.w3.org/1999/xlink"
+  version="1.0">
 
 <!-- ********************************************************************
      $Id$
@@ -15,9 +16,17 @@
 <!-- ==================================================================== -->
 
 <xsl:import href="../../../html/chunk.xsl"/>
+
+<!-- * The following are stylesheets for auto-adding doc links to -->
+<!-- * DocBook: The Definitive Guide and to the param and PI -->
+<!-- * documentation in the docbook-xsl docs -->
 <xsl:include href="tdg-link.xsl"/>
 <xsl:include href="xsl-param-link.xsl"/>
-<!-- * params -->
+<xsl:include href="xsl-pi-link.xsl"/>
+
+<xsl:param name="tcg.base.url">http://www.sagehill.net/docbookxsl/</xsl:param>
+
+<!-- * standard params -->
 <xsl:param name="admon.graphics" select="0"/>
 <xsl:param name="admon.textlabel" select="0"></xsl:param>
 <xsl:param name="chunk.append"><xsl:text>&#x0a;</xsl:text></xsl:param>
@@ -75,4 +84,28 @@ set       toc,title
     </a>
   </i>
 </xsl:template>
+
+<xsl:template match="link[@role = 'tcg']|ulink[@role = 'tcg']">
+  <!-- * Preface this TCG page link with a "DocBook XSL: TCG" direct link -->
+  <!-- * - unless this link has an ancestor with @role=tcg, which means -->
+  <!-- * it's in a section of the docbook-xsl docs that already has a -->
+  <!-- * title indicating the links in it are to TCG. -->
+  <xsl:if test="not(ancestor::*[@role = 'tcg'])">
+    <a href="{$tcg.base.url}">DocBook XSL: TCG</a>
+    <xsl:text>, </xsl:text>
+  </xsl:if>
+  <xsl:choose>
+    <xsl:when test="@xlink:href">
+      <xsl:call-template name="link">
+        <xsl:with-param name="xhref" select="concat($tcg.base.url,@xlink:href)"/>
+      </xsl:call-template>
+    </xsl:when>
+    <xsl:otherwise>
+      <xsl:call-template name="ulink">
+        <xsl:with-param name="url" select="concat($tcg.base.url,@url)"/>
+      </xsl:call-template>
+    </xsl:otherwise>
+  </xsl:choose>
+</xsl:template>
+
 </xsl:stylesheet>
diff --git a/xsl/tools/xsl/build/xsl-pi-link.xsl b/xsl/tools/xsl/build/xsl-pi-link.xsl
new file mode 100644
index 000000000..7104b95b2
--- /dev/null
+++ b/xsl/tools/xsl/build/xsl-pi-link.xsl
@@ -0,0 +1,59 @@
+<?xml version="1.0"?>
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+  version="1.0">
+
+  <xsl:include href="xsl-pi.xsl"/>
+
+  <!-- * We check for tag@class=xmlpi|pi instances and generate doc -->
+  <!-- * links for those that reference PIs used in the docbook-xsl -->
+  <!-- * stylsesheets code; but do exclude the ones that appear in -->
+  <!-- * synopsis content (because we want those to appear literally, -->
+  <!-- * not as hyperlinks) -->
+  <xsl:template match="
+    tag[@class = 'xmlpi' or @class='pi'][not(ancestor::synopsis)]
+    |sgmltag[@class = 'xmlpi' or @class='pi'][not(ancestor::synopsis)]">
+    <xsl:variable name="tagmarkup">
+      <xsl:apply-imports/>
+    </xsl:variable>
+    <xsl:variable name="underscored-pi">
+      <!-- * Replace any space, non-breaking space, or @ mark in the -->
+      <!-- * marked-up PI with an underscore (because that's the from we -->
+      <!-- * use for the PI ID/filenames in the docs). -->
+      <xsl:value-of select="translate(normalize-space(.),' &#xa0;@','___')"/>
+    </xsl:variable>
+    <xsl:variable name="adjusted-pi-name">
+      <xsl:choose>
+        <!-- * If the marked-up PI is of the form, e.g., <?dbhtml foo="bar"?>, -->
+        <!-- * then just get the part before the equal sign (=), because -->
+        <!-- * that part is what we use as the "name" of hte PI in our docs -->
+        <xsl:when test="contains($underscored-pi,'=')">
+          <xsl:value-of select="substring-before($underscored-pi,'=')"/>
+        </xsl:when>
+        <xsl:otherwise>
+          <xsl:value-of select="$underscored-pi"/>
+        </xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+    <xsl:variable name="ispi">
+      <!-- * check the PI name we have to see if it is in the -->
+      <!-- * auto-geneated list of PIs in the docbook-xsl code -->
+      <xsl:call-template name="is-pi">
+        <xsl:with-param name="pi" select="$adjusted-pi-name"/>
+      </xsl:call-template>
+    </xsl:variable>
+    <xsl:choose>
+      <xsl:when test="not($ispi = 0)">
+        <!-- * If $ispi is non-zero, it means we have the name of a PI -->
+        <!-- * that's used in the docbook-xsl stylesheets, and -->
+        <!-- * documented; so we created a hyperlink to its doc page -->
+        <!-- * doc-baseuri is declared in the xsl-param-link.xsl file -->
+        <a href="{concat($doc-baseuri, 'pi/',normalize-space($adjusted-pi-name))}.html">
+          <xsl:copy-of select="$tagmarkup"/>
+        </a>
+      </xsl:when>
+      <xsl:otherwise>
+        <xsl:copy-of select="$tagmarkup"/>
+      </xsl:otherwise>
+    </xsl:choose>
+  </xsl:template>
+</xsl:stylesheet>