Make xrefs and olinks work, and prevent instances of “ and

” entities in output (closes #741578 and #956072; thanks to
Jens Granseuer and Sam Steingold for reporting the problems)

::Problem:
  If you include an xref in a source document, instead of getting
  the xref text you would expect in the output, you just get
  "[xref to refsect1]", where "refsect" is the name of the target
  element for the xref.  If you include an olink, it works as
  expected -- except that the output text has “ and ”
  entities (double "curly" quotation marks).

::Cause:
  The manpages/docbook.xsl driver imports the html/docbook.xsl
  stylesheet, which in turn imports the html/xref.xsl file.

  The manpages/docbook.xsl file then imports the manpages/xref.xsl
  file. That file contains a "xref" template that overrides the
  the one in html/xref.xsl and that, by design, does nothing
  except to generate the "[xref to refsect1]" text instead of the
  expected xref output.

  On the other hand, the manpages stylesheets don't override the
  "olink" template; therefore, the "olink" template from the
  html/xref.xsl file is used "as is". And being that it is
  intended for HTML output, that template uses the “ and
  ” to wrap titles in xref output.

::Fix:
  The original manpages/xref.xsl file has now been removed. The
  build for the manpages distribution now makes that file, using
  the textify.xsl stylesheet to automatically generate it from the
  html/xref.xsl file. It is built in such a away that it basically
  just contains special copies of the "xref" and "olink" templates
  that cause “ and ” instances to be transformed into
  "\(lq" and "\(rq" (groff "left quote" and "right quote").

  It might seem odd that templates from the html/xref.xsl are
  used, since those templates a designed to generate hyperlinks of
  the form <a href="#foo">the section called "Bar"</a>. But it
  works because the manpages stylesheets end up using the text
  value of the output of the above. Thus, the <a href="#foo"> and
  </a> parts are stripped out, leaving just the text between
  ('the section called "Bar"').

::Affects
  Only affects output of xref and olink elements. The fix may not
  be complete and/or may cause other problems. Please test.

  In particular, while it may fix the &#8220; and &#8221; problem
  that English lang/locales users have run into, it doesn't fix
  the corresponding problem for output of xrefs and olinks in many
  non-English locales, which use quoting characters other than
  &#8220; and &#8221;

  To give just one example of many: in Japanese, the quoting
  characters are &#12300; and &#12301; ("left corner bracket" and
  "right corner bracket"). It is possible to "fix" the problem for
  all locales; but it is just a question of whether there is
  enough of a demand for it that it is worth doing.

diff --git a/xsl/manpages/.cvsignore b/xsl/manpages/.cvsignore
index e2d754768832781b86e4dea29ab7ae649ac609ec..bf7e41f8e05ca0733e9775ed2105d52c6890b81c 100644 (file)
--- a/xsl/manpages/.cvsignore
+++ b/xsl/manpages/.cvsignore
@@ -2,3 +2,4 @@ Makefile.param
 param.xml
 param.xsl
 profile-docbook.xsl
+xref.xsl

diff --git a/xsl/manpages/Makefile b/xsl/manpages/Makefile
index cb31e51a147ea56af537e27899bd3a4195cd6245..0f17ee1fc9298f325cda020c56de4b8a487a72fb 100644 (file)
--- a/xsl/manpages/Makefile
+++ b/xsl/manpages/Makefile
@@ -1,17 +1,19 @@
-XSLT=../../cvstools/saxon
-XJPARSE=../../cvstools/xjparse
+include ../../cvstools/Makefile.incl
 
 PARAMPROF=.param.profiled
 PARAMSTRIP=.param.stripped
 
 include Makefile.param
 
-all: param.xsl profile-docbook.xsl
+all: xref.xsl param.xsl profile-docbook.xsl
 
 xml: param.xml
 
 html: param.html
 
+xref.xsl: ../html/xref.xsl
+       $(XSLT) $< textify.xsl $@
+
 param.html: param.xml
        $(XSLT) $< ../docsrc/lrefentry.xsl $@
 

diff --git a/xsl/manpages/textify.xsl b/xsl/manpages/textify.xsl
new file mode 100644 (file)
index 0000000..b664225
--- /dev/null
+++ b/xsl/manpages/textify.xsl
@@ -0,0 +1,101 @@
+<?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">
+
+  <xsl:output method="xml"
+              encoding="US-ASCII"
+              indent="yes"/>
+  <xsl:preserve-space elements="*"/>
+
+  <!-- textify.xsl - Make "textified" copies of templates from a stylesheet. -->
+
+  <!-- $Id -->
+
+  <!-- This stylesheet is currently only used as part of the build for -->
+  <!-- DocBook manpages releases. It creates a manpages/xref.xsl stylesheet -->
+  <!-- containing transformed copies of templates for processing the "xref" -->
+  <!-- and "olink" templates. -->
+
+  <xsl:template match="/">
+    <xsl:text>&#10;</xsl:text>
+    <xsl:comment> * This file was created automatically by textify.xsl </xsl:comment>
+    <xsl:text>&#10;</xsl:text>
+    <xsl:comment> * as part of the DocBook manpages stylesheet build </xsl:comment>
+    <xsl:text>&#10;</xsl:text>
+    <xsl:comment> * </xsl:comment>
+    <xsl:text>&#10;</xsl:text>
+    <xsl:comment> * DocBook Project developers: DO NOT EDIT THIS FILE. </xsl:comment>
+    <xsl:text>&#10;</xsl:text>
+    <xsl:comment> * </xsl:comment>
+    <xsl:text>&#10;</xsl:text>
+    <xsl:comment> * Instead, edit a source stylesheet and then re-run </xsl:comment>
+    <xsl:text>&#10;</xsl:text>
+    <xsl:comment> * textify.xsl to generate a new version of this file. </xsl:comment>
+    <xsl:text>&#10;</xsl:text>
+    <xsl:apply-templates/>
+    <xsl:text>&#10;</xsl:text>
+  </xsl:template>
+
+  <xsl:template match="xsl:stylesheet" >
+    <xsl:copy>
+      <xsl:copy-of select="@*"/>
+      <xsl:apply-templates/>
+    </xsl:copy>
+  </xsl:template>
+
+  <xsl:template match="xsl:output">
+    <xsl:copy>
+      <xsl:copy-of select="@*"/>
+      <xsl:attribute name="method">xml</xsl:attribute>
+      <xsl:attribute name="encoding">UTF-8</xsl:attribute>
+    </xsl:copy>
+  </xsl:template>
+
+  <xsl:template match="*">
+    <xsl:copy>
+      <xsl:copy-of select="@*"/>
+      <xsl:apply-templates/>
+    </xsl:copy>
+  </xsl:template>
+
+  <!-- copy a template but transform it such that, when the copy is used, it -->
+  <!-- takes the content which the original template would have output and -->
+  <!-- instead reads into a variable which it then runs through -->
+  <!-- "replace-entities" template -->
+
+  <!-- the main purpose of this change is to make it possible to replace -->
+  <!-- entities in output of xrefs and onlinks -->
+  <xsl:template match="xsl:template">
+    <xsl:choose>
+      <xsl:when test="
+                      @match = 'xref' or
+                      @match = 'olink'
+                      ">
+        <xsl:copy>
+          <xsl:copy-of select="@*"/>
+          <xsl:element name="xsl:variable">
+            <xsl:attribute name="name">content</xsl:attribute>
+            <xsl:apply-templates/>
+          </xsl:element>
+          <xsl:element name="xsl:call-template">
+            <xsl:attribute name="name">replace-entities</xsl:attribute>
+            <xsl:element name="xsl:with-param">
+              <xsl:attribute name="name">content</xsl:attribute>
+              <xsl:attribute name="select">$content</xsl:attribute>
+            </xsl:element>
+          </xsl:element>
+        </xsl:copy>
+      </xsl:when>
+      <xsl:otherwise/>
+    </xsl:choose>
+  </xsl:template>
+
+  <xsl:template match="processing-instruction()">
+    <xsl:copy/>
+  </xsl:template>
+
+  <xsl:template match="comment()|text()"/>
+
+</xsl:stylesheet>

diff --git a/xsl/manpages/xref.xsl b/xsl/manpages/xref.xsl
deleted file mode 100644 (file)
index 671b87d..0000000
--- a/xsl/manpages/xref.xsl
+++ /dev/null
@@ -1,44 +0,0 @@
-<?xml version='1.0'?>
-<!-- vim:set sts=2 shiftwidth=2 syntax=sgml: -->
-<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
-                version='1.0'>
-
-<xsl:template match="xref">
-  <xsl:variable name="targets" select="key('id', @linkend)"/>
-  <xsl:variable name="target" select="$targets[1]"/>
-  <xsl:variable name="type" select="local-name($target)"/>
-
-  <xsl:choose>
-    <xsl:when test="$type=''">
-      <xsl:message>
-        <xsl:text>xref to nonexistent id </xsl:text>
-        <xsl:value-of select="@linkend"/>
-      </xsl:message>
-    </xsl:when>
-
-    <xsl:when test="$type='refentry'">
-      <xsl:call-template name="do-citerefentry">
-        <xsl:with-param name="refentrytitle"
-                        select="$target/refmeta/refentrytitle[1]"/>
-        <xsl:with-param name="manvolnum"
-                       select="$target/refmeta/manvolnum"/>
-      </xsl:call-template>
-    </xsl:when>
-
-    <xsl:when test="$type='refname'">
-      <xsl:call-template name="do-citerefentry">
-        <xsl:with-param name="refentrytitle" select="$target"/>
-        <xsl:with-param name="manvolnum"
-          select="$target/../../refmeta/manvolnum"/>
-      </xsl:call-template>
-    </xsl:when>
-
-    <xsl:otherwise>
-      <xsl:text>[xref to </xsl:text>
-      <xsl:value-of select="$type"/>
-      <xsl:text>]</xsl:text>
-    </xsl:otherwise>
-  </xsl:choose>
-</xsl:template>
-
-</xsl:stylesheet>