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

[paul]

Author: paul
Date: 2005-11-09 21:39:36 +0100 (Wed, 09 Nov 2005)
New Revision: 305

Log:
 r922@kite-hub:  paul | 2005-11-09 14:38:42 -0600
 For each help topic, pull out id of containing section for
 use in filling in url column of help_topic table.


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


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

Modified: trunk/tools/fill_help_tables2.pl
===================================================================
--- trunk/tools/fill_help_tables2.pl	2005-11-09 20:38:51 UTC (rev 304)
+++ trunk/tools/fill_help_tables2.pl	2005-11-09 20:39:36 UTC (rev 305)
@@ -2,10 +2,8 @@
 # vim:set ts=2 sw=2 expandtab:
 
 # To do:
-# - help_category.url column should be changed to allow NULL.  Currently
-#   we do not specify any value for this column, so NULL is the most
-#   sensible value -- but we cannot specify NULL because the column does
-#   not allow it.  This requires changes that can't be made here.
+# - Still need a version number for the manual, so that the proper
+#   version-specific URL can be constructed.
 
 # Copyright (C) 2003 MySQL AB
 # For a more info consult the file COPYRIGHT distributed with this file.
@@ -50,9 +48,11 @@
 #
 # (implicitly terminated by another @HELP-TOPIC, @HELP-CATEGORY, or EOF)
 #
-# Each topic block contains keyword, syntax, description, and example
-# blocks.  They look like this:
+# Each topic block contains section-id, keyword, syntax, description,
+#  and example blocks.  They look like this:
 #
+# @HELP-URL-ID id-value
+#
 # @HELP-KEYWORDS-BEGIN
 # ... keywords (plain text) ...
 # @HELP-KEYWORDS-END
@@ -82,6 +82,7 @@
 #
 # @HELP-CATEGORY Comparison operators@Functions
 # @HELP-TOPIC =
+# @HELP-URL-ID comparison-operators
 # @HELP-SYNTAX-BEGIN
 # @HELP-TEXT-BEGIN WRAP
 # =
@@ -132,6 +133,15 @@
 #   that hadn't been handled), but '@' is fine in DocBook.
 # 2005-11-07
 # - Handle @HELP-RESET directive, which causes the category to be forgotten.
+# 2005-11-09
+# - Handle @HELP-URL-ID directive, which contains page name for URL
+#   in online manual.  This means we write the help_topic.url value in
+#   INSERT statements. That has the advantage that the output now will
+#   load in MySQL 5.0 in strict mode.  Previously, without url in the
+#   INSERT, it would default to NULL, but url is defined as NOT NULL
+#   for some reason.  (Well, it won't quite work.  The help_cateogory
+#   also has a url column.  But I have no idea what that should be, so
+#   it's now set to '' explicitly.)
 
 use strict;
 
@@ -215,6 +225,7 @@
 my $pc_cat;         # current parent category (default: Contents)
 my $c_cat;          # current category
 my $c_topic;        # current topic within category
+my $c_url_id;       # current URL id within topic
 my $c_keywords;     # current keywords within topic
 my $c_syntax;       # current syntax within topic
 my $c_description;  # current description within topic
@@ -268,6 +279,12 @@
   # All other tags occur within topic and REQUIRE the topic to be known
   die "$.:\@HELP-$tag found but topic unknown\n" unless defined $c_topic;
 
+  if ($tag eq "URL-ID")
+  {
+    die "$.:\@HELP-$tag found with no id value\n" unless $rest ne "";
+    $c_url_id = $rest;
+    next;
+  }
   if ($tag eq "KEYWORDS-BEGIN")
   {
     @lines = parse_until ("KEYWORDS-END");
@@ -347,7 +364,7 @@
   }
 
   my $header= "insert into help_category ".
-            "(help_category_id,name,parent_category_id) values ";
+            "(help_category_id,name,parent_category_id,url) values ";
   $count= 0;
   foreach $cat_name (@category_names)
   {
@@ -355,7 +372,7 @@
     my $parent_cat_name= $categories{$cat_name}->{__parent_category__};
     my $parent_cat_id= $parent_cat_name eq "" 
         ? "0" : $categories{$parent_cat_name}->{__id__};
-    print "\n(", $count+1, ",\"$cat_name\",$parent_cat_id)";
+    print "\n(", $count+1, ",\"$cat_name\",$parent_cat_id,'')";
     $count++;
   }
   printf ";\n\n";
@@ -365,7 +382,7 @@
 if (scalar(@topic_names))
 {
   my $header= "insert into help_topic ".
-      "(help_topic_id,help_category_id,name,description,example) values ";
+      "(help_topic_id,help_category_id,name,description,example,url) values ";
   my $topic_name;
   my $count= 0;
   foreach $topic_name (@topic_names)
@@ -376,7 +393,8 @@
     print "$topic->{category}->{__id__},";
     print "\"$topic_name\",";
     print "\"$topic->{description}\",";
-    print "\"$topic->{example}\")";
+    print "\"$topic->{example}\",";
+    print "\"$topic->{url}\")";
     $topics{$topic_name}->{__id__}= $count;
     $count++;
   }
@@ -398,7 +416,7 @@
   printf ";\n\n";
     
   $header= "insert into help_relation ".
-	"(help_topic_id,help_keyword_id) values ";
+    "(help_topic_id,help_keyword_id) values ";
   $count= 0;
   my $count_keyword= 0;
   foreach $keyword_name (@keywords_names)
@@ -438,6 +456,8 @@
   warn "$.:No description for topic ", uc($c_topic), "\n"
     unless defined $c_description;
 
+  add_url ($c_topic, $c_url_id) if defined $c_url_id;
+
   foreach my $keyword (split (/\s+/, $c_keywords))
   {
     add_keyword ($c_topic, $keyword);
@@ -451,6 +471,7 @@
   add_example ($c_topic, $c_example) if defined $c_example;
 
   $c_topic = undef;
+  $c_url_id = undef;
   $c_keywords = undef;
   $c_syntax = undef;
   $c_description = undef;
@@ -823,6 +844,23 @@
   $keywords{$keyword}->{$topic_name}= $topics{$topic_name};
 }
 
+# The argument is the id of the section that contains the topic.
+# This is the basename of the corresponding page in the online manual.
+# There is NO lettercase mapping of this id!
+
+sub add_url
+{
+  my ($topic_name,$url)= @_;
+    
+  $topic_name=~ tr/a-z/A-Z/;
+    
+  if (exists($topics{$topic_name}->{url}))
+  {
+    print_error "double URL id for $topic_name\n";
+  }
+  $topics{$topic_name}->{url}= $url;
+}
+
 # ----------------------------------------------------------------------
 
 # test results of parsing:
@@ -858,7 +896,7 @@
     print STDERR "Error opening lex file \"$path_to_lex_file\" $!\n";
   }
   else
-  {	
+  {
     for (<TLEX>)
     {
       my ($a,$lex,$b)=m|(.+?)\"(.+?)\"(.+?)$|;

Modified: trunk/xsl.d/help-prep1.xsl
===================================================================
--- trunk/xsl.d/help-prep1.xsl	2005-11-09 20:38:51 UTC (rev 304)
+++ trunk/xsl.d/help-prep1.xsl	2005-11-09 20:39:36 UTC (rev 305)
@@ -60,6 +60,9 @@
   extract their contents in the next processing stage.
 
   Other actions:
+  - For each topic, add <help-url-id name="XXX"/> element containing the
+    @id attribute of the containing section.  This is used for generating
+    the URL of the corresponding page in the online manual.
   - "Resolve" cross-references by converting <xref linkend="target-id"/>
     into [target-id].
 -->
@@ -147,9 +150,7 @@
   </xsl:call-template>
 </xsl:template>
 
-<xsl:template match="remark[@role='help-category']
-                    |remark[@role='help-topic']
-                    ">
+<xsl:template match="remark[@role='help-category']">
   <!-- require @condition attribute -->
   <xsl:if test="not(@condition)">
     <xsl:message terminate="yes">
@@ -166,7 +167,54 @@
   <xsl:value-of select="$newline"/>
 </xsl:template>
 
+<xsl:template match="remark[@role='help-topic']">
+  <!-- require @condition attribute -->
+  <xsl:if test="not(@condition)">
+    <xsl:message terminate="yes">
+      <xsl:text>ERROR: Found </xsl:text>
+      <xsl:value-of select="@role"/>
+      <xsl:text> tag without required condition attribute</xsl:text>
+    </xsl:message>
+  </xsl:if>
+  <xsl:element name="{@role}">
+    <xsl:attribute name="name">
+      <xsl:value-of select="@condition"/>
+    </xsl:attribute>
+  </xsl:element>
+  <xsl:value-of select="$newline"/>
+  <!--
+    Look up id for surrounding section (or preface, chapter, or appendix)
+    and put it out for use in constructing URL of manual page associated
+    with topic.
+  -->
+  <help-url-id>
+    <xsl:attribute name="name">
+      <xsl:choose>
+        <xsl:when test="ancestor::section">
+          <xsl:value-of select="ancestor::section[1]/@id"/>
+        </xsl:when>
+        <xsl:when test="ancestor::preface">
+          <xsl:value-of select="ancestor::preface/@id"/>
+        </xsl:when>
+        <xsl:when test="ancestor::chapter">
+          <xsl:value-of select="ancestor::chapter/@id"/>
+        </xsl:when>
+        <xsl:when test="ancestor::appendix">
+          <xsl:value-of select="ancestor::appendix/@id"/>
+        </xsl:when>
+        <xsl:otherwise>
+          <xsl:message terminate="yes">
+            <xsl:text>ERROR: Cannot determine parent section id for
</xsl:text>
+            <xsl:value-of select="@role"/>
+            <xsl:text> topic</xsl:text>
+          </xsl:message>
+        </xsl:otherwise>
+      </xsl:choose>
+    </xsl:attribute>
+  </help-url-id>
+</xsl:template>
 
+
 <!--
   Convert remark with @role of "help-keywords" to <help-keywords> element
 -->

Modified: trunk/xsl.d/help-prep2.xsl
===================================================================
--- trunk/xsl.d/help-prep2.xsl	2005-11-09 20:38:51 UTC (rev 304)
+++ trunk/xsl.d/help-prep2.xsl	2005-11-09 20:39:36 UTC (rev 305)
@@ -20,6 +20,7 @@
   <help-information>
     <help-category>
       <help-topic>
+        <help-url-id/>
         <help-keywords> ... </help-keywords>
         <help-syntax> ... </help-syntax>
         <help-description> ... </help-description>
@@ -111,7 +112,8 @@
   <xsl:text>@HELP-TOPIC </xsl:text>
   <xsl:value-of select="@name"/>
   <xsl:value-of select="$newline"/>
-  <xsl:apply-templates match="help-keywords
+  <xsl:apply-templates match="help-url-id
+                             |help-keywords
                              |help-syntax
                              |help-description
                              |help-example
@@ -119,6 +121,23 @@
 </xsl:template>
 
 
+<!-- For URL ID, copy @name attribute -->
+
+<xsl:template match="help-url-id">
+  <!-- require @name attribute -->
+  <xsl:if test="not(@name)">
+    <xsl:message terminate="yes">
+      <xsl:text>ERROR: Found </xsl:text>
+      <xsl:value-of select="local-name(.)"/>
+      <xsl:text> tag without required value attribute</xsl:text>
+    </xsl:message>
+  </xsl:if>
+  <xsl:text>@HELP-URL-ID </xsl:text>
+  <xsl:value-of select="@name"/>
+  <xsl:value-of select="$newline"/>
+</xsl:template>
+
+
 <!-- For keywords, copy content -->
 
 <xsl:template match="help-keywords">