MySQL Lists are EOL. Please join:

List:Internals« Previous MessageNext Message »
From:paul Date:October 1 2005 4:13am
Subject:bk commit - mysqldoc@docsrva tree (paul:1.3658)
View as plain text  
Below is the list of changes that have just been committed into a local
mysqldoc repository of paul. When paul does a push these changes will
be propagated to the main repository and, within 24 hours after the
push, to the public repository.
For information on how to access the public repository
see http://www.mysql.com/doc/I/n/Installing_source_tree.html

ChangeSet
  1.3658 05/09/30 23:13:55 paul@stripped +2 -0
  Help-tag processing revisions.

  xsl.d/help-prep2.xsl
    1.2 05/09/30 23:13:50 paul@stripped +21 -3
    Help-tag processing revisions.

  xsl.d/help-prep1.xsl
    1.2 05/09/30 23:13:50 paul@stripped +102 -10
    Help-tag processing revisions.

# This is a BitKeeper patch.  What follows are the unified diffs for the
# set of deltas contained in the patch.  The rest of the patch, the part
# that BitKeeper cares about, is below these diffs.
# User:	paul
# Host:	frost.snake.net
# Root:	/Users/paul/bk/mysqldoc

--- 1.1/xsl.d/help-prep1.xsl	2005-09-29 12:47:00 -05:00
+++ 1.2/xsl.d/help-prep1.xsl	2005-09-30 23:13:50 -05:00
@@ -7,7 +7,7 @@
   help-prep1.xsl - prep a DocBook document for extracting
   help-table information, stage 1.
 
-  Help tags are written using paired <remark> elements that use the
+  Most help tags are written using paired <remark> elements that use the
   @role attribute to indicate the beginning or end of a particular
   kind of help information.  Some begin tags have a @condition
   attribute.  Examples:
@@ -28,9 +28,18 @@
   <help-example>
   </help-example>
 
-  The result is not DocBook, but that doesn't matter. What matters is that
-  the result has elements from which we can extract their contents in the
-  next processing stage.
+  Some single-tag constructs are used:
+
+  <remark role="help-example"/> indicates that the next element (which
+  must be a <programlisting>) is an example.
+
+  The result of this transform is not DocBook, but that doesn't matter.
+  What matters is that the result has elements from which we can
+  extract their contents in the next processing stage.
+
+  To do:
+  - Require help-category-begin, help-topic-begin, help-topic to
+    have a @condition attribute.
 -->
 
 <!--
@@ -55,13 +64,13 @@
 <xsl:variable name="newline" select="'&#xA;'"/>
 
 <!--
-  Match <remark> elements that are tagged as help text with
-  a @role attribute of 'help-XXX-begin' or 'help-XXX-end'.
-  Write out a corresponding <help-XXX> or </help-XXX> begin or
+  Match paired <remark> elements that are tagged as help text
+  with a @role attribute of 'help-XXX-begin' or 'help-XXX-end'.
+  Write out a corresponding <help-XXX> begin tag or </help-XXX>
   end tag.
 
   This is an abuse of XSLT, which operates on trees.  Here we
-  write individual begin or end tags, which results in
+  write individual begin or end tags, which will result in
   unbalanced tags in the output if the input <remark> elements
   are not properly paired.
 -->
@@ -120,11 +129,93 @@
   </xsl:call-template>
 </xsl:template>
 
-<!-- Strip stuff that we know we won't ever use -->
+
+<!--
+  Convert remark with @role of "help-keywords" to <help-keywords> element
+-->
+
+<xsl:template match="remark[@role='help-keywords']">
+  <help-keywords>
+    <xsl:value-of select="normalize-space(.)"/>
+  </help-keywords>
+  <xsl:value-of select="$newline"/>
+</xsl:template>
+
+
+<!--
+  Match unpaired help tags that indicate the following single
+  element comprises a help text object.
+-->
+
+<!--
+  <remark role="help-syntax"/> indicates that the following element
+  should be a <para> or <programlisting> element syntax description.
+  Emit that element within <help-syntax> tags.
+
+  <remark role="help-description"/> indicates that the following element
+  should be a <para> element that provides descriptive text.
+  Emit that element within <help-description> tags.
+
+  <remark role="help-example"/> indicates that the following element
+  should be a <programlisting> element help example.  Emit that element
+  within <help-example> tags.
+
+  Emit a warning if the next element is not of the required type.
+-->
+
+<xsl:template match="remark[@role='help-syntax']">
+  <xsl:if test="count(following-sibling::*[1][self::para|self::programlisting]) = 0">
+    <xsl:message terminate="yes">
+      <xsl:text>WARNING: </xsl:text>
+      <xsl:value-of select="@role"/>
+      <xsl:text> tag without following para or programlisting</xsl:text>
+    </xsl:message>
+  </xsl:if>
+  <help-syntax>
+    <xsl:copy-of select="following-sibling::*[1][self::para|self::programlisting]"/>
+  </help-syntax>
+  <xsl:value-of select="$newline"/>
+</xsl:template>
+
+
+<xsl:template match="remark[@role='help-description']">
+  <xsl:if test="count(following-sibling::*[1][self::para]) = 0">
+    <xsl:message terminate="yes">
+      <xsl:text>WARNING: </xsl:text>
+      <xsl:value-of select="@role"/>
+      <xsl:text> tag without following para</xsl:text>
+    </xsl:message>
+  </xsl:if>
+  <help-description>
+    <xsl:copy-of select="following-sibling::*[1][self::para]"/>
+  </help-description>
+  <xsl:value-of select="$newline"/>
+</xsl:template>
+
+
+<xsl:template match="remark[@role='help-example']">
+  <xsl:if test="count(following-sibling::*[1][self::programlisting]) = 0">
+    <xsl:message terminate="yes">
+      <xsl:text>WARNING: </xsl:text>
+      <xsl:value-of select="@role"/>
+      <xsl:text> tag without following programlisting</xsl:text>
+    </xsl:message>
+  </xsl:if>
+  <help-example>
+    <xsl:copy-of select="following-sibling::*[1][self::programlisting]"/>
+  </help-example>
+  <xsl:value-of select="$newline"/>
+</xsl:template>
+
+
+<!--
+  Strip stuff that we know we won't ever use
+-->
 
 <xsl:template match="comment()"/>
 <xsl:template match="indexterm"/>
-<xsl:template match="remark"/>
+<xsl:template match="remark"/> <!-- strip remarks not otherwise matched -->
+
 
 <!--
 Match text nodes that follow a comment.  If the text begins with a
@@ -143,6 +234,7 @@
     </xsl:otherwise>
   </xsl:choose>
 </xsl:template>
+
 
 <!--
 Identity transform, with the following exception:

--- 1.1/xsl.d/help-prep2.xsl	2005-09-29 12:47:01 -05:00
+++ 1.2/xsl.d/help-prep2.xsl	2005-09-30 23:13:50 -05:00
@@ -29,6 +29,10 @@
   Other non-help tex/elements might occur at other points, so we
   match and discard those that do not occur within <help-syntax>,
   <help-description>, or <help-example>.
+
+  To do:
+  - Die if help-category has no @value attribute.
+  - Die if help-topic has no @value attribute.
 -->
 
 <!--
@@ -71,7 +75,8 @@
 <xsl:template match="help-topic">
   <xsl:copy>
     <xsl:copy-of select="@*"/>
-    <xsl:apply-templates match="help-syntax
+    <xsl:apply-templates match="help-keywords
+                               |help-syntax
                                |help-description
                                |help-example
                                "/>
@@ -80,6 +85,19 @@
 </xsl:template>
 
 
+<!-- For keywords, copy content -->
+
+<xsl:template match="help-keywords">
+  <xsl:copy>
+    <xsl:copy-of select="@*"/>
+    <xsl:copy-of select="normalize-space(.)"/>
+  </xsl:copy>
+  <xsl:value-of select="$newline"/>
+</xsl:template>
+
+
+<!-- For syntax and description, copy subelements -->
+
 <xsl:template match="help-syntax
                     |help-description
                     ">
@@ -91,7 +109,7 @@
 </xsl:template>
 
 
-<!-- accept only programlisting within examples -->
+<!-- For examples, copy only programlisting subelements -->
 
 <xsl:template match="help-example">
   <xsl:copy>
@@ -102,7 +120,7 @@
 </xsl:template>
 
 
-<!-- discard elements not explicitly matched otherwise -->
+<!-- discard text and elements not otherwise explicitly matched -->
 
 <xsl:template match="node()">
   <xsl:apply-templates select="*"/>
Thread
bk commit - mysqldoc@docsrva tree (paul:1.3658)paul1 Oct