Author: paul
Date: 2007-02-13 05:02:31 +0100 (Tue, 13 Feb 2007)
New Revision: 4917
Log:
r16183@frost: paul | 2007-02-12 22:00:45 -0600
In server-side help output, include the URL to the online manual
page that corresponds to the help topic. Users can use this to
obtain additional information.
Modified:
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
- 4767c598-dc10-0410-bea0-d01b485662eb:/mysqldoc-local/mysqldoc/trunk:19666
7d8d2c4e-af1d-0410-ab9f-b038ce55645b:/mysqldoc-local/mysqldoc:16159
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:19666
7d8d2c4e-af1d-0410-ab9f-b038ce55645b:/mysqldoc-local/mysqldoc:16183
b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:14218
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:13520
Modified: trunk/tools/fill_help_tables2.pl
===================================================================
--- trunk/tools/fill_help_tables2.pl 2007-02-12 21:49:25 UTC (rev 4916)
+++ trunk/tools/fill_help_tables2.pl 2007-02-13 04:02:31 UTC (rev 4917)
Changed blocks: 5, Lines Added: 18, Lines Deleted: 1; 2281 bytes
@@ -48,11 +48,13 @@
#
# (implicitly terminated by another @HELP-TOPIC, @HELP-CATEGORY, or EOF)
#
-# Each topic block contains section-id, keyword, syntax, description,
+# Each topic block contains section-id, URL, keyword, syntax, description,
# and example blocks. They look like this:
#
# @HELP-URL-ID id-value
#
+# @HELP-URL-ID url-value
+#
# @HELP-KEYWORDS-BEGIN
# ... keywords (plain text) ...
# @HELP-KEYWORDS-END
@@ -146,6 +148,10 @@
# - Ensure each insert statement is written on a single line, so that
# the output can be processed by mysqld --bootstrap (mysql_install_db
# invokes mysqld with the --bootstrap option).
+# 2007-02-12
+# - Handle @HELP-URL directive, which contains full URL to the section
+# that contains the help topic. The value is put out at the end of
+# the Description text.
use strict;
@@ -230,6 +236,7 @@
my $c_cat; # current category
my $c_topic; # current topic within category
my $c_url_id; # current URL id within topic
+my $c_url; # current URL within topic
my $c_keywords; # current keywords within topic
my $c_syntax; # current syntax within topic
my $c_description; # current description within topic
@@ -289,6 +296,13 @@
$c_url_id = $rest;
next;
}
+
+ if ($tag eq "URL")
+ {
+ die "$.:\@HELP-$tag found with no id value\n" unless $rest ne "";
+ $c_url = $rest;
+ next;
+ }
if ($tag eq "KEYWORDS-BEGIN")
{
@lines = parse_until ("KEYWORDS-END");
@@ -480,12 +494,15 @@
# if syntax was given, make it first part of description
$c_description = "" unless defined $c_description;
$c_description = "Syntax:\n$c_syntax\n$c_description" if defined $c_syntax;
+ # if URL was given, make it last part of description
+ $c_description .= "\nURL: $c_url\n" if defined $c_url;
add_description ($c_topic, $c_description) if $c_description;
add_example ($c_topic, $c_example) if defined $c_example;
$c_topic = undef;
$c_url_id = undef;
+ $c_url = undef;
$c_keywords = undef;
$c_syntax = undef;
$c_description = undef;
Modified: trunk/xsl.d/help-prep1.xsl
===================================================================
--- trunk/xsl.d/help-prep1.xsl 2007-02-12 21:49:25 UTC (rev 4916)
+++ trunk/xsl.d/help-prep1.xsl 2007-02-13 04:02:31 UTC (rev 4917)
Changed blocks: 4, Lines Added: 78, Lines Deleted: 25; 5049 bytes
@@ -92,7 +92,7 @@
standalone="no"
/>
-<!-- set to 1 to strip non-help-tag output (for debugging) -->
+<!-- set to 1 to include non-help-tag output (for debugging) -->
<xsl:param name="non.help.output" select="1"/>
<!-- define explicit newline variable that contains a newline character -->
@@ -223,34 +223,87 @@
and put it out for use in constructing URL of manual page associated
with topic.
-->
+ <xsl:variable name="container.id">
+ <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:variable>
+
<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:value-of select="$container.id"/>
</xsl:attribute>
</help-url-id>
+ <xsl:value-of select="$newline"/>
+
+ <!--
+ Determine whether the ID corresponds to an online manual page.
+ If so, the page is the same as the ID with .html.
+ If not, find nearest outermost ID that does have its own page.
+ In that case, the URL uses the container ID as an anchor within
+ the page.
+ -->
+ <xsl:variable name="page.id">
+ <xsl:choose>
+ <xsl:when test="key('toc-elt',$container.id)">
+ <xsl:value-of select="$container.id"/>
+ </xsl:when>
+ <xsl:when test="key('toc-elt',key('id',$container.id)/../@id)">
+ <xsl:value-of select="key('id',$container.id)/../@id"/>
+ </xsl:when>
+ <xsl:when test="key('toc-elt',key('id',$container.id)/../../@id)">
+ <xsl:value-of select="key('id',$container.id)/../../@id"/>
+ </xsl:when>
+ <xsl:when test="key('toc-elt',key('id',$container.id)/../../../@id)">
+ <xsl:value-of select="key('id',$container.id)/../../../@id"/>
+ </xsl:when>
+ <xsl:when test="key('toc-elt',key('id',$container.id)/../../../../@id)">
+ <xsl:value-of select="key('id',$container.id)/../../../../@id"/>
+ </xsl:when>
+ <xsl:when test="key('toc-elt',key('id',$container.id)/../../../../../@id)">
+ <xsl:value-of select="key('id',$container.id)/../../../../../@id"/>
+ </xsl:when>
+ <xsl:otherwise>
+ <!-- if this message ever appears, add new levels above -->
+ <xsl:message terminate="yes">
+ <xsl:text>XREF: DID NOT FIND TOC-ABLE ANCESTOR FOR id=</xsl:text>
+ <xsl:value-of select="$container.id"/>
+ </xsl:message>
+ </xsl:otherwise>
+ </xsl:choose>
+ </xsl:variable>
+
+ <help-url>
+ <xsl:value-of select="$doc.url.base"/>
+ <xsl:value-of select="$page.id"/>
+ <xsl:text>.html</xsl:text>
+ <xsl:if test="$page.id != $container.id">
+ <xsl:text>#</xsl:text>
+ <xsl:value-of select="$container.id"/>
+ </xsl:if>
+ </help-url>
+ <xsl:value-of select="$newline"/>
+
</xsl:template>
-
<!--
Convert remark with @role of "help-keywords" to <help-keywords> element
-->
@@ -359,7 +412,7 @@
is a TOC element. If pointed-to node is a TOC element, use it.
Otherwise, check ancestors to find TOC element.
-->
- <xsl:variable name="page-id">
+ <xsl:variable name="page.id">
<xsl:choose>
<xsl:when test="key('toc-elt',@linkend)">
<xsl:value-of select="@linkend"/>
@@ -389,7 +442,7 @@
</xsl:choose>
</xsl:variable>
<xsl:value-of select="$doc.url.base"/>
- <xsl:value-of select="$page-id"/>
+ <xsl:value-of select="$page.id"/>
<xsl:text>.html</xsl:text>
</xsl:otherwise>
</xsl:choose>
Modified: trunk/xsl.d/help-prep2.xsl
===================================================================
--- trunk/xsl.d/help-prep2.xsl 2007-02-12 21:49:25 UTC (rev 4916)
+++ trunk/xsl.d/help-prep2.xsl 2007-02-13 04:02:31 UTC (rev 4917)
Changed blocks: 3, Lines Added: 10, Lines Deleted: 0; 1115 bytes
@@ -21,6 +21,7 @@
<help-category>
<help-topic>
<help-url-id/>
+ <help-url/>
<help-keywords> ... </help-keywords>
<help-syntax> ... </help-syntax>
<help-description> ... </help-description>
@@ -113,6 +114,7 @@
<xsl:value-of select="@name"/>
<xsl:value-of select="$newline"/>
<xsl:apply-templates match="help-url-id
+ |help-url
|help-keywords
|help-syntax
|help-description
@@ -137,7 +139,15 @@
<xsl:value-of select="$newline"/>
</xsl:template>
+<!-- For URL, copy content -->
+<xsl:template match="help-url">
+ <xsl:text>@HELP-URL </xsl:text>
+ <xsl:copy-of select="normalize-space(.)"/>
+ <xsl:value-of select="$newline"/>
+</xsl:template>
+
+
<!-- For keywords, copy content -->
<xsl:template match="help-keywords">
| Thread |
|---|
| • svn commit - mysqldoc@docsrva: r4917 - in trunk: . tools xsl.d | paul | 13 Feb |
