[yelp-xsl] doc: Extract docs for xslt keys

[Shaun McCance <shaunm src gnome org>]

commit 647465751d4ce199b9177e004f45ec1479fc4bac
Author: Shaun McCance <shaunm gnome org>
Date:   Wed Jan 25 10:16:07 2012 -0500

    doc: Extract docs for xslt keys

 doc/yelp-xsl/C/keys.page         |   40 +++++++++++++++++++++++++++++
 doc/yelp-xsl/xsldoc-scan.awk     |   12 ++++++++-
 doc/yelp-xsl/xsldoc-scan.xsl     |   51 ++++++++++++++++++++++++++++++++++++++
 xslt/mallard/common/mal-link.xsl |   27 ++++++++++++++++++-
 4 files changed, 127 insertions(+), 3 deletions(-)
---
diff --git a/doc/yelp-xsl/C/keys.page b/doc/yelp-xsl/C/keys.page
new file mode 100644
index 0000000..79b6f77
--- /dev/null
+++ b/doc/yelp-xsl/C/keys.page
@@ -0,0 +1,40 @@
+<?xml version="1.0"?>
+<page xmlns="http://projectmallard.org/1.0/";
+      type="guide"
+      id="keys">
+  <info>
+    <link type="guide" xref="index"/>
+    <title type="link">Keys</title>
+    <title type="link" role="topic">XSLT Keys</title>
+  </info>
+
+  <title>XSLT Keys</title>
+
+  <links type="topic" style="linklist" groups="mal2html">
+    <title>Mallard to HTML</title>
+  </links>
+  <links type="topic" style="linklist" groups="mal">
+    <title>Mallard Common</title>
+  </links>
+  <links type="topic" style="linklist" groups="db2html">
+    <title>DocBook to HTML</title>
+  </links>
+  <links type="topic" style="linklist" groups="db">
+    <title>DocBook Common</title>
+  </links>
+  <links type="topic" style="linklist" groups="html">
+    <title>HTML Output</title>
+  </links>
+  <links type="topic" style="linklist" groups="l10n">
+    <title>Localization</title>
+  </links>
+  <links type="topic" style="linklist" groups="color">
+    <title>Colors</title>
+  </links>
+  <links type="topic" style="linklist" groups="icons">
+    <title>Icons</title>
+  </links>
+  <links type="topic" style="linklist" groups="#first #default #last">
+    <title>Other</title>
+  </links>
+</page>
diff --git a/doc/yelp-xsl/xsldoc-scan.awk b/doc/yelp-xsl/xsldoc-scan.awk
index 002dbec..a8859df 100644
--- a/doc/yelp-xsl/xsldoc-scan.awk
+++ b/doc/yelp-xsl/xsldoc-scan.awk
@@ -55,7 +55,7 @@
 #
 # Note that we need to add a special character for processing instructions.
 function runline (line, ix, jx, pre, aft, char, name, id, fmt) {
-    ix = match(line, /[\*\$\ \%\!\#]\{[^\}]*\}/)
+    ix = match(line, /[\*\$\ \+\%\!\#]\{[^\}]*\}/)
     if (ix > 0) {
         jx = ix + index(substr(line, ix), "}");
 	pre = substr(line, 1, ix - 1);
@@ -69,6 +69,8 @@ function runline (line, ix, jx, pre, aft, char, name, id, fmt) {
 	    fmt = "<code style='xslt-template' xref='%s'>%s</code>";
 	else if (char == "%")
 	    fmt = "<code style='xslt-mode' xref='%s'>%s</code>";
+  else if (char == "+")
+      fmt = "<code style='xslt-key' xref='%s'>%s</code>";
 	else if (char == "@") 
 	    fmt = "<code style='xslt-param' xref='P.%s'>%s</code>";
 	else if (char == "$") 
@@ -133,6 +135,13 @@ cur_block = "";
     cur_block = "";
     next;
 }
+/<\!--\+\+/ {
+    print "\n<section style='xslt-key'>";
+    cur_line_mode = "title";
+    comment_type = "key";
+    cur_block = "";
+    next;
+}
 /<\!--\ \@/ {
     print "\n<section style='xslt-param'>"
     cur_line_mode = "title";
@@ -320,6 +329,7 @@ cur_line_mode == "body" && end_mode {
 
 end_comment && comment_type == "template" { print "</section>"; }
 end_comment && comment_type == "mode" { print "</section>"; }
+end_comment && comment_type == "key" { print "</section>"; }
 end_comment && comment_type == "param" { print "</section>"; }
 end_comment {
     cur_line_mode = "";
diff --git a/doc/yelp-xsl/xsldoc-scan.xsl b/doc/yelp-xsl/xsldoc-scan.xsl
index 83d4ca4..3132baa 100644
--- a/doc/yelp-xsl/xsldoc-scan.xsl
+++ b/doc/yelp-xsl/xsldoc-scan.xsl
@@ -123,6 +123,42 @@ free software.
   </xsl:if>
 </xsl:template>
 
+<xsl:template name="calls_keys">
+  <xsl:param name="node" select="."/>
+  <xsl:param name="page"/>
+  <xsl:param name="xslt_node"/>
+  <xsl:variable name="calls_keys">
+    <xsl:for-each select="$xslt_node//xsl:variable/@select   |
+                          $xslt_node//xsl:param/@select      |
+                          $xslt_node//xsl:with-param/@select |
+                          $xslt_node//xsl:for-each/@select   |
+                          $xslt_node//xsl:sort/@select       |
+                          $xslt_node//xsl:value-of/@select   |
+                          $xslt_node//xsl:if/@test           | 
+                          $xslt_node//xsl:when/@test         ">
+      <xsl:variable name="xpath_node" select="."/>
+      <xsl:if test="contains($xpath_node, 'key(')">
+        <!-- libxslt doesn't str:split when the string starts with the split arg -->
+        <xsl:for-each select="str:split(concat(' ', $xpath_node), 'key(')[position() > 1]">
+          <xsl:for-each select="str:tokenize(., concat('&quot;', &quot;&apos;&quot;))[1]">
+            <key><xsl:value-of select="."/></key>
+          </xsl:for-each>
+        </xsl:for-each>
+      </xsl:if>
+    </xsl:for-each>
+  </xsl:variable>
+  <xsl:variable name="calls_keys_nodes" select="exsl:node-set($calls_keys)/*"/>
+  <xsl:if test="count($calls_keys_nodes) > 0">
+    <list style="compact">
+      <title>Calls Keys</title>
+      <xsl:for-each select="set:distinct($calls_keys_nodes)">
+        <xsl:sort select="."/>
+        <item><p><link xref="{.}"/></p></item>
+      </xsl:for-each>
+    </list>
+  </xsl:if>
+</xsl:template>
+
 <xsl:template match="mal:page">
   <xsl:variable name="page" select="."/>
   <page id="{$xsldoc.id}" type="guide" style="xslt-stylesheet">
@@ -222,6 +258,9 @@ free software.
     <links type="topic" groups="templates" style="linklist">
       <title>Templates</title>
     </links>
+    <links type="topic" groups="keys" style="linklist">
+      <title>Keys</title>
+    </links>
     <xsl:variable name="requires" select="$page/mal:info/mal:link[ type = 'xslt-requires']"/>
     <xsl:if test="count($requires) > 0">
       <list style="compact">
@@ -240,6 +279,10 @@ free software.
       <xsl:with-param name="page" select="$page"/>
       <xsl:with-param name="xslt_node" select="$xslt_file"/>
     </xsl:call-template>
+    <xsl:call-template name="calls_keys">
+      <xsl:with-param name="page" select="$page"/>
+      <xsl:with-param name="xslt_node" select="$xslt_file"/>
+    </xsl:call-template>
   </page>
 </xsl:template>
 
@@ -253,6 +296,9 @@ free software.
       <xsl:when test="@style = 'xslt-template'">
         <xsl:text>templates</xsl:text>
       </xsl:when>
+      <xsl:when test="@style = 'xslt-key'">
+        <xsl:text>keys</xsl:text>
+      </xsl:when>
       <xsl:when test="@style = 'xslt-mode'">
         <xsl:text>modes</xsl:text>
       </xsl:when>
@@ -307,6 +353,11 @@ free software.
           <xsl:with-param name="page" select="ancestor::mal:page"/>
           <xsl:with-param name="xslt_node" select="$xslt_node"/>
         </xsl:call-template>
+        <xsl:call-template name="calls_keys">
+          <xsl:with-param name="node" select="."/>
+          <xsl:with-param name="page" select="ancestor::mal:page"/>
+          <xsl:with-param name="xslt_node" select="$xslt_node"/>
+        </xsl:call-template>
       </xsl:if>
     </page>
   </exsl:document>
diff --git a/xslt/mallard/common/mal-link.xsl b/xslt/mallard/common/mal-link.xsl
index 6b15033..bcd6368 100644
--- a/xslt/mallard/common/mal-link.xsl
+++ b/xslt/mallard/common/mal-link.xsl
@@ -64,12 +64,35 @@ it to a file.  Those tools can use this parameter directly.
 <xsl:param name="mal.cache" select="document($mal.cache.file, /)/cache:cache"/>
 
 
-<!--============================================================================
+<!--++==========================================================================
 mal.cache.key
+Get a page or section from the #{id} attribute.
+:Revision:version="3.4" date="2012-01-25" status="final"
+
+This key returns a #{page} or #{section} element from a Mallard cache file from
+the #{id} attribute. In cache files, the #{id} attribute of #{section} elements
+is set to a qualified ID by prefixing it with the containing page ID and the
+hash character.
+
+The context node must be in the document @{mal.cache} when this key is called.
 -->
 <xsl:key name="mal.cache.key" match="mal:page | mal:section" use="@id"/>
+
+
+<!--++==========================================================================
+mal.cache.link.key
+Get #{link} elements from a link type and #{xref} attribute.
+:Revision:version="3.4" date="2012-01-25" status="final"
+
+This key returns all #{link} elements from a Mallard cache file from the #{type}
+and #{xref} attributes. They key is the concatenation of the #{type} attribute,
+the colon character, and the #{xref} attribute. Only #{link} elements with both
+a #{type} and #{xref} attribute are supported.
+
+The context node must be in the document @{mal.cache} when this key is called.
+-->
 <xsl:key name="mal.cache.link.key"
-         match="mal:info/mal:link[ type]"
+         match="mal:info/mal:link[ type][@xref]"
          use="concat(@type, ':', @xref)"/>