svn commit - mysqldoc@docsrva: r292 - in trunk: . tools xsl.d

[paul]

Author: paul
Date: 2005-11-08 00:04:51 +0100 (Tue, 08 Nov 2005)
New Revision: 292

Log:
 r3469@frost:  paul | 2005-11-07 16:10:13 -0600
 "electric fence" for help tags: Forget category at beginning
 of each chapter. This forces category to be set within chapters
 before any topic markup occurs.


Modified:
   trunk/
   trunk/tools/fill_help_tables2.pl
   trunk/xsl.d/help-prep2.xsl


Property changes on: trunk
___________________________________________________________________
Name: svk:merge
   - b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:3443
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:340
   + b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:3469
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:340

Modified: trunk/tools/fill_help_tables2.pl
===================================================================
--- trunk/tools/fill_help_tables2.pl	2005-11-07 20:59:28 UTC (rev 291)
+++ trunk/tools/fill_help_tables2.pl	2005-11-07 23:04:51 UTC (rev 292)
@@ -108,6 +108,14 @@
 #         -> 1    
 # @HELP-TEXT-END
 # @HELP-EXAMPLE-END
+#
+# The input also may contain @HELP-RESET directives, which causes the
+# current category to be forgotten.  These are emitted at the beginning
+# of chapters to prevent inadvertent category "bleeding" from one
+# chapter to the next. (Normally, a chapter's topics are not in the
+# same category as the previous chapter. Resetting the category forces
+# each chapter containing help markup to require the category to be
+# set before any topic markup appears.)
 
 # Change history:
 
@@ -122,6 +130,8 @@
 # - Remove the stuff that checks for '@' characters in descriptions and
 #   examples. That made sense for Texinfo (@ probably indicated @-markup
 #   that hadn't been handled), but '@' is fine in DocBook.
+# 2005-11-07
+# - Handle @HELP-RESET directive, which causes the category to be forgotten.
 
 use strict;
 
@@ -222,6 +232,15 @@
   my $rest = $2;
   warn "$.:in:$_\n" if $debug;
   warn "$.:tag:$tag\n" if $debug;
+
+  if ($tag eq "RESET")  # forget category
+  {
+    end_topic () if defined $c_topic;
+    $c_cat = $pc_cat = undef;
+    warn "Resetting category\n" if $debug;
+    next;
+  }
+
   if ($tag eq "CATEGORY")
   {
     die "$.:\@HELP-$tag found with no category value\n" unless $rest ne "";

Modified: trunk/xsl.d/help-prep2.xsl
===================================================================
--- trunk/xsl.d/help-prep2.xsl	2005-11-07 20:59:28 UTC (rev 291)
+++ trunk/xsl.d/help-prep2.xsl	2005-11-07 23:04:51 UTC (rev 292)
@@ -246,7 +246,23 @@
   </xsl:message>
 </xsl:template>
 
+<!--
+  At the beginning of each chapter, do a reset.  The only purpose of
+  this is to cause the help category to be forgotten, which triggers
+  an error in the postprocessor if a help topic markup appears in a
+  chapter without being preceded by a category specification.  (Topics
+  tend to group by chapter, so if a topic is given in one chapter,it's
+  unlikely that it will be in the same category as topics in the
+  previous chapter.
+-->
 
+<xsl:template match="preface|chapter|appendix">
+  <xsl:text>@HELP-RESET</xsl:text>
+  <xsl:value-of select="$newline"/>
+  <xsl:apply-templates select="*"/>
+</xsl:template>
+
+
 <!--
   Discard text and elements not otherwise explicitly matched:
   - Match elements and text