mal2html-api: Started adding JS synopseswip/api-1-0

8 files changed, 274 insertions, 0 deletions

diff --git a/test/api/c_func4.page b/test/api/c_func4.page
new file mode 100644
index 00000000..9a89b4b1
--- /dev/null
+++ b/test/api/c_func4.page
@@ -0,0 +1,33 @@
+<page xmlns="http://projectmallard.org/1.0/"
+      xmlns:api="http://projectmallard.org/experimental/api/"
+      type="topic"
+      id="c_func4">
+
+<info>
+  <api:function>
+    <api:returns>
+      <api:type>void</api:type>
+    </api:returns>
+    <api:name>sort_of_long_function_name</api:name>
+    <api:arg>
+      <api:type>a_type *</api:type>
+      <api:name>arg1</api:name>
+    </api:arg>
+    <api:arg>
+      <api:type>a_type*</api:type>
+      <api:name>arg2</api:name>
+    </api:arg>
+    <api:arg>
+      <api:type>a_type</api:type>
+      <api:name>arg3</api:name>
+    </api:arg>
+    <api:arg>
+      <api:name>...</api:name>
+    </api:arg>
+  </api:function>
+  <link type="guide" xref="index" group="c"/>
+</info>
+
+<title>A Long Function Name</title>
+
+</page>
diff --git a/test/api/c_property1.page b/test/api/c_property1.page
new file mode 100644
index 00000000..71e6e498
--- /dev/null
+++ b/test/api/c_property1.page
@@ -0,0 +1,18 @@
+<page xmlns="http://projectmallard.org/1.0/"
+      xmlns:api="http://projectmallard.org/experimental/api/"
+      type="topic"
+      id="c_property1">
+
+<info>
+  <api:property>
+    <api:flag>Read</api:flag>
+    <api:flag>Write</api:flag>
+    <api:type>type1</api:type>
+    <api:name>property1</api:name>
+  </api:property>
+  <link type="guide" xref="index" group="c"/>
+</info>
+
+<title>Property #1</title>
+
+</page>
diff --git a/test/api/index.page b/test/api/index.page
index 61bbc5f4..10693f3c 100644
--- a/test/api/index.page
+++ b/test/api/index.page
@@ -13,4 +13,8 @@
   <title>Python</title>
 </links>
 
+<links type="topic" groups="js" api:mime="application/javascript">
+  <title>JavaScript</title>
+</links>
+
 </page>
diff --git a/test/api/js_func1.page b/test/api/js_func1.page
new file mode 100644
index 00000000..660f7827
--- /dev/null
+++ b/test/api/js_func1.page
@@ -0,0 +1,15 @@
+<page xmlns="http://projectmallard.org/1.0/"
+      xmlns:api="http://projectmallard.org/experimental/api/"
+      type="topic"
+      id="js_func1">
+
+<info>
+  <api:function>
+    <api:name>js_func_1</api:name>
+  </api:function>
+  <link type="guide" xref="index" group="js"/>
+</info>
+
+<title>Function #1</title>
+
+</page>
diff --git a/test/api/js_func2.page b/test/api/js_func2.page
new file mode 100644
index 00000000..155024af
--- /dev/null
+++ b/test/api/js_func2.page
@@ -0,0 +1,21 @@
+<page xmlns="http://projectmallard.org/1.0/"
+      xmlns:api="http://projectmallard.org/experimental/api/"
+      type="topic"
+      id="js_func2">
+
+<info>
+  <api:function>
+    <api:name>js_func_2</api:name>
+    <api:arg>
+      <api:name>arg1</api:name>
+    </api:arg>
+    <api:arg>
+      <api:name>arg2</api:name>
+    </api:arg>
+  </api:function>
+  <link type="guide" xref="index" group="js"/>
+</info>
+
+<title>Function #2</title>
+
+</page>
diff --git a/test/api/js_func3.page b/test/api/js_func3.page
new file mode 100644
index 00000000..1b2a0ac7
--- /dev/null
+++ b/test/api/js_func3.page
@@ -0,0 +1,26 @@
+<page xmlns="http://projectmallard.org/1.0/"
+      xmlns:api="http://projectmallard.org/experimental/api/"
+      type="topic"
+      id="js_func3">
+
+<info>
+  <api:function>
+    <api:name>js_func_3</api:name>
+    <api:returns>
+      <api:type>type3</api:type>
+    </api:returns>
+    <api:arg>
+      <api:type>type1</api:type>
+      <api:name>arg1</api:name>
+    </api:arg>
+    <api:arg>
+      <api:type>type2</api:type>
+      <api:name>arg2</api:name>
+    </api:arg>
+  </api:function>
+  <link type="guide" xref="index" group="js"/>
+</info>
+
+<title>Function #3</title>
+
+</page>
diff --git a/test/api/js_type1.page b/test/api/js_type1.page
new file mode 100644
index 00000000..c5a48963
--- /dev/null
+++ b/test/api/js_type1.page
@@ -0,0 +1,15 @@
+<page xmlns="http://projectmallard.org/1.0/"
+      xmlns:api="http://projectmallard.org/experimental/api/"
+      type="topic"
+      id="js_type1">
+
+<info>
+  <api:type>
+    <api:name>type1</api:name>
+  </api:type>
+  <link type="guide" xref="index" group="js"/>
+</info>
+
+<title>JavaScript Type #1</title>
+
+</page>
diff --git a/xslt/mallard/html/mal2html-api.xsl b/xslt/mallard/html/mal2html-api.xsl
index e924a755..074f396b 100644
--- a/xslt/mallard/html/mal2html-api.xsl
+++ b/xslt/mallard/html/mal2html-api.xsl
@@ -71,6 +71,12 @@ elements. It should be called by an appropriate template that handles the
         <xsl:with-param name="links" select="$links"/>
       </xsl:call-template>
     </xsl:when>
+    <xsl:when test="$node/@api:mime = 'application/javascript'">
+      <xsl:call-template name="mal2html.api.links.js">
+        <xsl:with-param name="node" select="$node"/>
+        <xsl:with-param name="links" select="$links"/>
+      </xsl:call-template>
+    </xsl:when>
     <xsl:otherwise>
       <xsl:call-template name="mal2html.links.ul">
         <xsl:with-param name="node" select="$node"/>
@@ -653,4 +659,140 @@ contains an #{api:function} element in its #{info}.
   </span></div>
 </xsl:template>
 
+
+<!--**==========================================================================
+mal2html.api.links.js
+Output links as a synopsis for the JavaScript programming language.
+$node: A #{links} element to link from.
+$links: A list of links, as from a template in !{mal-link}.
+
+This template outputs links as a synopsis in the JavaScript programming language.
+It is called by *{mal2html.api.links} when the #{api:mime} attribute of ${node}
+is #{application/javascript}. The target nodes of ${links} are expected to have
+appropriate API metadata elements in their #{info} elements. Links to targets
+without correct API metadata are output with *{mal2html.links.ul} after the
+synopsis.
+
+This template calls other templates to format each link, based on what type of
+API the target node is declared as.
+
+This template handles link sorting, and may have specialized sorting using the
+API metadata of the target nodes.
+-->
+<xsl:template name="mal2html.api.links.js">
+  <xsl:param name="node"/>
+  <xsl:param name="links"/>
+  <xsl:variable name="apilinks_">
+    <xsl:for-each select="$links">
+      <xsl:variable name="link" select="."/>
+      <xsl:for-each select="$mal.cache">
+        <xsl:variable name="target" select="key('mal.cache.key', $link/@xref)"/>
+        <xsl:variable name="apiname" select="$target/mal:info/api:*/api:name[1]"/>
+        <xsl:for-each select="$link">
+          <xsl:copy>
+            <xsl:copy-of select="@*"/>
+            <xsl:copy-of select="*"/>
+            <xsl:copy-of select="$apiname"/>
+          </xsl:copy>
+        </xsl:for-each>
+      </xsl:for-each>
+    </xsl:for-each>
+  </xsl:variable>
+  <xsl:variable name="apilinks" select="exsl:node-set($apilinks_)/*"/>
+  <xsl:variable name="out_">
+    <xsl:for-each select="$apilinks">
+      <xsl:sort select="api:name"/>
+      <xsl:sort data-type="number" select="@groupsort"/>
+      <xsl:sort select="mal:title[@type = 'sort']"/>
+      <xsl:variable name="link" select="."/>
+      <xsl:for-each select="$mal.cache">
+        <xsl:variable name="target" select="key('mal.cache.key', $link/@xref)"/>
+        <xsl:choose>
+          <xsl:when test="$target/mal:info/api:function/api:name">
+            <xsl:call-template name="mal2html.api.links.js.function">
+              <xsl:with-param name="node" select="$node"/>
+              <xsl:with-param name="links" select="$links"/>
+              <xsl:with-param name="link" select="$link"/>
+              <xsl:with-param name="target" select="$target"/>
+            </xsl:call-template>
+          </xsl:when>
+          <xsl:otherwise>
+            <xsl:copy-of select="$link"/>
+          </xsl:otherwise>
+        </xsl:choose>
+      </xsl:for-each>
+    </xsl:for-each>
+  </xsl:variable>
+  <xsl:variable name="out" select="exsl:node-set($out_)"/>
+  <xsl:if test="$out/*[not(self::mal:link)]">
+    <div class="synopsis">
+      <pre class="contents">
+        <xsl:copy-of select="$out/*[not(self::mal:link)]"/>
+      </pre>
+    </div>
+  </xsl:if>
+  <xsl:if test="$out/mal:link">
+    <xsl:call-template name="mal2html.links.ul">
+      <xsl:with-param name="node" select="$node"/>
+      <xsl:with-param name="links" select="$out/mal:link"/>
+    </xsl:call-template>
+  </xsl:if>
+</xsl:template>
+
+
+<!--**==========================================================================
+mal2html.api.links.js.function
+Output a link as a function for a synopsis in JavaScript.
+$node: A #{links} element to link from.
+$links: A list of links, as from a template in !{mal-link}.
+$link: The #{mal:link} element from ${links} to process.
+$target: The node pointed to by ${link}.
+
+This template formats a link as a function for a synopsis in the JavaScript
+programming language. It is called by *{mal2html.api.links.js} when the
+${target} contains an #{api:function} element in its #{info}.
+-->
+<xsl:template name="mal2html.api.links.js.function">
+  <xsl:param name="node"/>
+  <xsl:param name="links"/>
+  <xsl:param name="link"/>
+  <xsl:param name="target"/>
+  <xsl:variable name="function" select="$target/mal:info/api:function[api:name][1]"/>
+  <div class="api-link {$link/@class}"><span>
+    <xsl:for-each select="$link/@*">
+      <xsl:if test="starts-with(name(.), 'data-')">
+        <xsl:copy-of select="."/>
+      </xsl:if>
+    </xsl:for-each>
+    <xsl:text>function </xsl:text>
+    <xsl:variable name="name">
+      <xsl:apply-templates mode="mal2html.inline.mode" select="$function/api:name/node()"/>
+    </xsl:variable>
+    <a>
+      <xsl:attribute name="href">
+        <xsl:call-template name="mal.link.target">
+          <xsl:with-param name="node" select="$node"/>
+          <xsl:with-param name="xref" select="$link/@xref"/>
+        </xsl:call-template>
+      </xsl:attribute>
+      <xsl:attribute name="title">
+        <xsl:call-template name="mal.link.tooltip">
+          <xsl:with-param name="node" select="$node"/>
+          <xsl:with-param name="xref" select="$link/@xref"/>
+        </xsl:call-template>
+      </xsl:attribute>
+      <xsl:copy-of select="$name"/>
+    </a>
+    <xsl:text>(</xsl:text>
+    <xsl:for-each select="$function/api:arg">
+      <xsl:if test="position() != 1">
+        <xsl:text>, </xsl:text>
+      </xsl:if>
+      <xsl:apply-templates mode="mal2html.inline.mode" select="api:name/node()"/>
+    </xsl:for-each>
+    <xsl:text>)</xsl:text>
+    <xsl:text>&#x000A;</xsl:text>
+  </span></div>
+</xsl:template>
+
 </xsl:stylesheet>