svn commit - mysqldoc@docsrva: r4870 - in trunk: . make.d xsl.d

[paul]

Author: paul
Date: 2007-02-09 06:53:40 +0100 (Fri, 09 Feb 2007)
New Revision: 4870

Log:
 r16040@frost:  paul | 2007-02-08 23:51:42 -0600
 Simplify the XML -> .txt transformation by eliminating the need for
 a separate toc-entries file.


Added:
   trunk/xsl.d/target-resolvers.xsl
Modified:
   trunk/make.d/vars-docbook
   trunk/make.d/xml-txt
   trunk/xsl.d/expand-links.xsl
   trunk/xsl.d/fixup-links.xsl

Property changes on: trunk
___________________________________________________________________
Name: svk:merge
   - 4767c598-dc10-0410-bea0-d01b485662eb:/mysqldoc-local/mysqldoc/trunk:19608
7d8d2c4e-af1d-0410-ab9f-b038ce55645b:/mysqldoc-local/mysqldoc:16018
b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:14218
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:13520
   + 4767c598-dc10-0410-bea0-d01b485662eb:/mysqldoc-local/mysqldoc/trunk:19608
7d8d2c4e-af1d-0410-ab9f-b038ce55645b:/mysqldoc-local/mysqldoc:16040
b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:14218
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:13520


Modified: trunk/make.d/vars-docbook
===================================================================
--- trunk/make.d/vars-docbook	2007-02-09 03:28:44 UTC (rev 4869)
+++ trunk/make.d/vars-docbook	2007-02-09 05:53:40 UTC (rev 4870)
Changed blocks: 1, Lines Added: 1, Lines Deleted: 1; 511 bytes

@@ -190,7 +190,7 @@
 EXPAND_LINKS_XSL = $(XSL_DIR)/expand-links.xsl
 EXPAND_LINKS_XSL_DEPS = \
 	$(EXPAND_LINKS_XSL) \
-	$(XSL_DIR)/resolve-xref.xsl \
+	$(XSL_DIR)/target-resolvers.xsl \
 	$(XSL_DIR)/map-spchars-txt.xsl
 
 # Transforms that extract help-table information (used to generate


Modified: trunk/make.d/xml-txt
===================================================================
--- trunk/make.d/xml-txt	2007-02-09 03:28:44 UTC (rev 4869)
+++ trunk/make.d/xml-txt	2007-02-09 05:53:40 UTC (rev 4870)
Changed blocks: 3, Lines Added: 3, Lines Deleted: 13; 1612 bytes

@@ -10,14 +10,6 @@
 #   suppresses the TOC.
 # - Use lynx -dump to convert HTML to text.
 
-# NOTE: If you include this file, you must also include include xml-toc
-# because rules here have -toc-entries.xml dependencies.
-
-# $PWD is used so that XSL transforms that need to find -toc-entries.xml
-# files have an absolute pathname to work with. (Otherwise, they look
-# in the same directory in which they are located, and may not find
-# the file.)
-
 # Do not delete these files when they are generated as intermediates
 # for a final target.  They are deleted by "make clean".
 

@@ -27,10 +19,8 @@
 # with the proper cross-reference information to replace the link.
 # This is an intermediate target for the .txt target.
 
-%-nolink.xml: %-prepped.xml %-toc-entries.xml $(EXPAND_LINKS_XSL_DEPS)
-	$(XSLTPROC) \
-		--stringparam toc.entry.file $$PWD/$*-toc-entries.xml \
-		--output $@-tmp $(EXPAND_LINKS_XSL) $*-prepped.xml
+%-nolink.xml: %-prepped.xml $(EXPAND_LINKS_XSL_DEPS)
+	$(XSLTPROC) --output $@-tmp $(EXPAND_LINKS_XSL) $*-prepped.xml
 	mv $@-tmp $@
 
 # Use standard HTML driver to convert -nolink.xml to HTML

@@ -40,7 +30,7 @@
 # on the same line. (They are glued together with "@@", which then
 # is mapped back after text conversion to ": ".)
 
-%.txt: %-nolink.xml %-toc-entries.xml
+%.txt: %-nolink.xml
 	$(XSLTPROC) \
 		--stringparam l10n.gentext.default.language $(DOC_LANG) \
 		--stringparam generate.toc "" \


Modified: trunk/xsl.d/expand-links.xsl
===================================================================
--- trunk/xsl.d/expand-links.xsl	2007-02-09 03:28:44 UTC (rev 4869)
+++ trunk/xsl.d/expand-links.xsl	2007-02-09 05:53:40 UTC (rev 4870)
Changed blocks: 1, Lines Added: 1, Lines Deleted: 9; 1113 bytes

@@ -16,21 +16,13 @@
   - Replace <mailto> elements with their contents.
   - <quote>xxx</quote> becomes "xxx".
   - Some elements are deleted: <index>, <indexterm>
-
-  Templates in included files REQUIRE that the $toc.entry.file string
-  parameter be set to the name of the file that contains table of
-  contents information so that the links can be resolved.  In xsltproc,
-  you can do that with a stringparam option on the command line.
 -->
 
-<xsl:include href="resolve-xref.xsl"/>
+<xsl:include href="target-resolvers.xsl"/>
 
 <!-- include special-char mapping template -->
 <xsl:include href="map-spchars-txt.xsl"/>
 
-<!-- global variable containing the TOC entries for document sections -->
-<xsl:variable name="toc-entries" select="document($toc.entry.file)"/>
-
 <!-- we want links expanded without retaining the <xref> tags -->
 <xsl:variable name="retain-link-tag" select="0"/>
 


Modified: trunk/xsl.d/fixup-links.xsl
===================================================================
--- trunk/xsl.d/fixup-links.xsl	2007-02-09 03:28:44 UTC (rev 4869)
+++ trunk/xsl.d/fixup-links.xsl	2007-02-09 05:53:40 UTC (rev 4870)
Changed blocks: 1, Lines Added: 11, Lines Deleted: 19; 2014 bytes

@@ -2,29 +2,21 @@
 <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
 
 <!--
-fixup-links.xsl
+  fixup-links.xsl
 
-This is like an identity transform with the following exceptions:
-- <link> elements the represent cross-references are replaced with
-  elements of the form:
-  <link ..>{Chapter|Section} n. "Text of title"</link>
-  If there is a punctuation character following the </link> tag in
-  the input document, it is moved inside the closing quote.
-  In essence, this transformation replaces the content of the link
-  with a value that adds the section number and quotes around the
-  referred-to section's title.
-
-Templates in included files REQUIRE that the $toc.entry.file string
-parameter be set to the name of the file that contains table of
-contents information so that the links can be resolved.  In xsltproc,
-you can do that with a stringparam option on the command line.
+  This is like an identity transform with the following exceptions:
+  - <link> elements the represent cross-references are replaced with
+    elements of the form:
+    <link ..>{Chapter|Section} n. "Text of title"</link>
+    If there is a punctuation character following the </link> tag in
+    the input document, it is moved inside the closing quote.
+    In essence, this transformation replaces the content of the link
+    with a value that adds the section number and quotes around the
+    referred-to section's title.
 -->
 
-<xsl:include href="resolve-xref.xsl"/>
+<xsl:include href="target-resolvers.xsl"/>
 
-<!-- global variable containing the TOC entries for document sections -->
-<xsl:variable name="toc-entries" select="document($toc.entry.file)"/>
-
 <!-- we want links expanded but with the <link> tags retained -->
 <xsl:variable name="retain-link-tag" select="1"/>
 


Added: trunk/xsl.d/target-resolvers.xsl
===================================================================
--- trunk/xsl.d/target-resolvers.xsl	                        (rev 0)
+++ trunk/xsl.d/target-resolvers.xsl	2007-02-09 05:53:40 UTC (rev 4870)
Changed blocks: 1, Lines Added: 279, Lines Deleted: 0; 10017 bytes

@@ -0,0 +1,279 @@
+<?xml version="1.0" encoding="utf-8"?>
+<xsl:stylesheet
+  version="1.0"
+  xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
+
+<!--
+  target-resolvers.xsl: templates for resolving cross-references
+
+  xref: expand cross-references to text of the cross-reference
+  target-elt-type: Return name corresponding to the target element
+  target-toc-num: Return table-of-contents section number of the target element
+  target-title: Process the title of the target element
+
+To do:
+- Need to move the id key-constructor into calling stylesheets.
+
+ Contingencies that apply to any stylesheet that includes this one:
+ - A key on id attributes should be constructed to speed up id-lookups.
+   Use a construct like this:
+     <xsl:key name="id" match="*" use="@id"/>
+ - The $retain-link-tag should be zero or non-zero to determine whether
+   the xref template omits or retains <xref> tags and attributes.
+
+  Deficiencies:
+  - TOC-element name display should be gentext-ed.
+-->
+
+<!--
+  Construct a key for all elements with an @id attribute, except
+  <xref id="xxx"/>, which occurs in studyguide-DTD documents.
+ -->
+
+<xsl:key name="id" match="*[not(self::xref)]" use="@id"/>
+
+<!--
+  Handle <xref> (cross-reference)
+
+  Locate the node with an @id attribute that matches the @linkend
+  attribute from the <xref>. If no such @id is found, or found
+  multiple times, emit a warning.
+
+  The template prefers the @linkend attribute (<xref linkend="xxx"/>), as
+  used in DocBook.  However, the DTD for Study Guide 4.0/4.1 used the @id
+  attribute (<xref id="xxx"/>).  To accommodate documents written using
+  either DTD, this template handles either attribute.
+
+  This template can either retain the <xref> tags and attributes, or not.
+  Any stylesheet that includes this one and uses the xref template
+  must set the $retain-link-tag variable.
+-->
+
+<xsl:template match="xref">
+  <!-- determine whether @linkend or @id is present -->
+  <xsl:variable name="target.name">
+    <xsl:choose>
+      <xsl:when test="@linkend">
+        <xsl:value-of select="@linkend"/> <!-- DocBook <xref> -->
+      </xsl:when>
+      <xsl:when test="@id">
+        <xsl:value-of select="@id"/> <!-- studyguide-DTD <xref> -->
+      </xsl:when>
+      <xsl:otherwise>
+        <xsl:message>
+        <xsl:text>Error: bad xref: no @linkend or @id attribute
found</xsl:text>
+        </xsl:message>
+      </xsl:otherwise>
+    </xsl:choose>
+  </xsl:variable>
+  <xsl:variable name="targets" select="key('id',$target.name)"/>
+  <xsl:variable name="target" select="$targets[1]"/>
+
+  <xsl:variable name="link-content">
+    <xsl:choose>
+      <!--
+        Determine whether the target ID is present once (the desired
+        result), more than once, or missing.  If more than once, use
+        the first instance but issue a warning.
+      -->
+      <xsl:when test="count($targets) > 0">
+        <!-- target ID is present at least once -->
+        <xsl:if test="count($targets) > 1">
+          <xsl:message>
+            <xsl:text>Warning: multiple targets for xref (id=</xsl:text>
+            <xsl:value-of select="$target.name"/>
+            <xsl:text>)</xsl:text>
+          </xsl:message>
+        </xsl:if>
+        <!--
+          Get the TOC number for the target. If it is not empty, display it
+          preceded by the type of thing that it is (Chapter, Appendix,
+          Section) and followed by a comma and a space. (Preface sections
+          have no numbers)
+         -->
+        <xsl:variable name="toc-num">
+          <xsl:call-template name="target-toc-num">
+            <xsl:with-param name="target" select="$target"/>
+          </xsl:call-template>
+        </xsl:variable>
+
+        <xsl:if test="$toc-num != ''">
+          <xsl:call-template name="target-elt-type">
+            <xsl:with-param name="target" select="$target"/>
+          </xsl:call-template>
+          <xsl:text> </xsl:text>
+          <xsl:value-of select="$toc-num"/>
+          <xsl:text>, </xsl:text>
+        </xsl:if>
+
+        <!-- display section title within quotes -->
+        <xsl:text>"</xsl:text>
+        <xsl:call-template name="target-title">
+          <xsl:with-param name="target" select="$target"/>
+        </xsl:call-template>
+        <!--
+          Check whether next character is a punctuation character that
+          should go inside the closing quote. Note: text processing rule
+          elsewhere must check whether the text() node is preceded by an
+          <xref> element and remove the punctuation character if so, so
+          that it doesn't appear in the output twice.
+        -->
+        <xsl:variable name="char"
+            select="substring(following-sibling::text()[1], 1, 1)" />
+        <xsl:if test="contains('.?!,:;', $char)">
+          <xsl:value-of select="$char" />
+        </xsl:if>
+        <xsl:text>"</xsl:text>
+      </xsl:when>
+
+      <xsl:otherwise>
+        <!-- target ID not present; write message to stdout and stderr -->
+        <xsl:text>[WARNING: missing xref target (id=</xsl:text>
+        <xsl:value-of select="$target.name"/>
+        <xsl:text>)]</xsl:text>
+        <xsl:message>
+          <xsl:text>Warning: missing xref target (id=</xsl:text>
+          <xsl:value-of select="$target.name"/>
+          <xsl:text>)</xsl:text>
+        </xsl:message>
+      </xsl:otherwise>
+    </xsl:choose>
+  </xsl:variable>
+
+  <xsl:choose>
+    <xsl:when test="$retain-link-tag != 0">
+      <!-- keep the xref tag and attributes -->
+      <xref>
+        <xsl:copy-of select="@*"/>
+        <xsl:value-of select="$link-content"/>
+      </xref>
+    </xsl:when>
+    <xsl:otherwise>
+      <!-- write only the xref content -->
+      <xsl:value-of select="$link-content"/>
+    </xsl:otherwise>
+  </xsl:choose>
+</xsl:template>
+
+<!--
+  Determine element type for target and return its name:
+  <part> -> Part, <chapter> -> Chapter, and so forth.
+  <preface> isn't numbered, so return nothing.
+-->
+
+<xsl:template name="target-elt-type">
+  <xsl:param name="target"/>
+  <!-- use for-each to select $target as the context node -->
+  <xsl:for-each select="$target">
+    <xsl:choose>
+      <xsl:when test="self::part">
+        <xsl:text>Part</xsl:text>
+      </xsl:when>
+      <xsl:when test="ancestor-or-self::preface">
+        <!-- preface and its subsections are not numbered -->
+      </xsl:when>
+      <xsl:when test="self::chapter">
+        <xsl:text>Chapter</xsl:text>
+      </xsl:when>
+      <xsl:when test="self::appendix">
+        <xsl:text>Appendix</xsl:text>
+      </xsl:when>
+      <xsl:when test="self::section
+                     |self::subsection
+                     |self::subsubsection">
+        <xsl:text>Section</xsl:text>
+      </xsl:when>
+      <xsl:when test="self::example">
+        <xsl:text>Example</xsl:text>
+      </xsl:when>
+      <xsl:otherwise>
+        <xsl:text>Section</xsl:text>
+        <xsl:message>Warning: target-elt-type invoked inside unknown element!
+        <xsl:value-of select="name(.)"/>
+        </xsl:message>
+      </xsl:otherwise>
+    </xsl:choose>
+  </xsl:for-each>
+</xsl:template>
+
+<!--
+  Return the TOC section number for the target passed as the argument
+  (or the parent of the current node if no argument is given; this is
+  useful if you're currently processing a <title> and need to display
+  the element type and section number preceding the title text).
+  <preface> and its subsections aren't numbered, so return nothing.
+
+  The <subsection> and <subsubsection> elements are listed here to
+  accommodate documents that use the DTD for Study Guide 4.0/4.1.
+-->
+
+<xsl:template name="target-toc-num">
+  <xsl:param name="target" select=".."/>
+  <!-- use for-each to select $target as the context node -->
+  <xsl:for-each select="$target">
+    <xsl:choose>
+      <!-- for part, number only top-level element -->
+      <xsl:when test="self::part">
+        <xsl:number count="part" level="any" format="I"/>
+      </xsl:when>
+      <!-- preface sections are not numbered -->
+      <xsl:when test="ancestor-or-self::preface">
+        <!-- no numbering for preface -->
+      </xsl:when>
+      <xsl:when test="ancestor-or-self::chapter">
+        <xsl:number count="chapter" level="any" format="1"/>
+        <xsl:if test="ancestor::chapter">
+          <xsl:number count="section
+                            |subsection
+                            |subsubsection"
+              level="multiple"
+              format=".1.1.1.1.1"/>
+        </xsl:if>
+      </xsl:when>
+      <xsl:when test="ancestor-or-self::appendix">
+        <xsl:number count="appendix" level="any" format="A"/>
+        <xsl:if test="ancestor::appendix">
+          <xsl:number count="section
+                            |subsection
+                            |subsubsection"
+              level="multiple"
+              format=".1.1.1.1.1"/>
+        </xsl:if>
+      </xsl:when>
+      <xsl:otherwise>
+        <xsl:text>Section</xsl:text>
+        <xsl:message>Warning: target-toc-num invoked inside unknown element!
+        <xsl:value-of select="local-name(.)"/>
+        </xsl:message>
+      </xsl:otherwise>
+    </xsl:choose>
+  </xsl:for-each>
+</xsl:template>
+
+<!--
+  Process the title for the target node.  (It's assumed to have a <title>
+  element as a child.)
+-->
+
+<xsl:template name="target-title">
+  <xsl:param name="target"/>
+  <!-- use for-each to select $target as the context node -->
+  <xsl:for-each select="$target">
+    <xsl:choose>
+      <xsl:when test="title">
+        <xsl:apply-templates select="title" mode="extract.title"/>
+      </xsl:when>
+      <xsl:otherwise>
+        <xsl:message>Warning: target-title found no title in element
+        <xsl:value-of select="name(.)"/>
+        </xsl:message>
+      </xsl:otherwise>
+    </xsl:choose>
+  </xsl:for-each>
+</xsl:template>
+
+<xsl:template match="title" mode="extract.title">
+  <xsl:apply-templates/>
+</xsl:template>
+
+</xsl:stylesheet>