mal2html-api: Signals for C/GObject

3 files changed, 162 insertions, 10 deletions

diff --git a/test/api/c_signal1.page b/test/api/c_signal1.page
new file mode 100644
index 00000000..4ef6e113
--- /dev/null
+++ b/test/api/c_signal1.page
@@ -0,0 +1,28 @@
+<page xmlns="http://projectmallard.org/1.0/"
+      xmlns:api="http://projectmallard.org/experimental/api/"
+      type="topic"
+      id="c_signal1">
+
+<info>
+  <api:signal>
+    <api:flag>Run Last</api:flag>
+    <api:flag>Run 4ever</api:flag>
+    <api:returns>
+      <api:type>void</api:type>
+    </api:returns>
+    <api:name>signal1</api:name>
+    <api:arg>
+      <api:type>a_type *</api:type>
+      <api:name>arg1</api:name>
+    </api:arg>
+    <api:arg>
+      <api:type>gpointer</api:type>
+      <api:name>user_data</api:name>
+    </api:arg>
+  </api:signal>
+  <link type="guide" xref="index" group="c"/>
+</info>
+
+<title>Signal #1</title>
+
+</page>
diff --git a/xslt/mallard/html/mal2html-api.xsl b/xslt/mallard/html/mal2html-api.xsl
index b617ab76..338d6aab 100644
--- a/xslt/mallard/html/mal2html-api.xsl
+++ b/xslt/mallard/html/mal2html-api.xsl
@@ -137,6 +137,14 @@ API metadata of the target nodes.
               <xsl:with-param name="target" select="$target"/>
             </xsl:call-template>
           </xsl:when>
+          <xsl:when test="$target/mal:info/api:signal/api:name">
+            <xsl:call-template name="mal2html.api.links.c.signal">
+              <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>
@@ -169,17 +177,19 @@ $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 formatted as a function for a synopsis in the C
-programming language. It is called by *{mal2html.api.links.c} when the ${target}
-contains an #{api:function} element in its #{info}.
+This template formats a link as a function for a synopsis in the C programming
+language. It is called by *{mal2html.api.links.c} when the ${target} contains
+an #{api:function} element in its #{info}.
 -->
 <xsl:template name="mal2html.api.links.c.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"/>
-  <div class="{$link/@class}">
+  <xsl:variable name="function" select="$target/mal:info/api:function[api:name][1]"/>
+  <!-- The span keeps libxslt from inserting a spurious newline when
+       the first child is an element (like a link) instead of text. -->
+  <div class="api-link {$link/@class}"><span>
     <xsl:for-each select="$link/@*">
       <xsl:if test="starts-with(name(.), 'data-')">
         <xsl:copy-of select="."/>
@@ -261,7 +271,115 @@ contains an #{api:function} element in its #{info}.
     <xsl:if test="not($function/api:arg)">
       <xsl:text>void);&#x000A;</xsl:text>
     </xsl:if>
-  </div>
+  </span></div>
+</xsl:template>
+
+
+<!--**==========================================================================
+mal2html.api.links.c.signal
+Output a link as a signal for a synopsis in C.
+$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 signal for a synopsis in the C programming
+language. It is called by *{mal2html.api.links.c} when the ${target} contains
+an #{api:signal} element in its #{info}. Since C does not have a native signal
+system, this template formats signals for GObject APIs.
+-->
+<xsl:template name="mal2html.api.links.c.signal">
+  <xsl:param name="node"/>
+  <xsl:param name="links"/>
+  <xsl:param name="link"/>
+  <xsl:param name="target"/>
+  <xsl:variable name="signal" select="$target/mal:info/api:signal[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:variable name="name">
+      <xsl:apply-templates mode="mal2html.inline.mode" select="$signal/api:name/node()"/>
+    </xsl:variable>
+    <xsl:text>"</xsl:text>
+    <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:variable name="tab" select="$mal2html.api.tab.c.func - string-length($name) - 2"/>
+    <xsl:choose>
+      <xsl:when test="$tab > 1">
+        <xsl:value-of select="str:padding($tab)"/>
+      </xsl:when>
+      <xsl:otherwise>
+        <xsl:text>&#x000A;</xsl:text>
+        <xsl:value-of select="str:padding($mal2html.api.tab.c.func)"/>
+      </xsl:otherwise>
+    </xsl:choose>
+    <xsl:for-each select="$signal/api:flag">
+      <xsl:if test="position() != 1">
+        <xsl:text> · </xsl:text>
+      </xsl:if>
+      <xsl:apply-templates mode="mal2html.inline.mode" select="node()"/>
+    </xsl:for-each>
+    <xsl:text>&#x000A;</xsl:text>
+    <xsl:value-of select="str:padding($mal2html.api.tab.c.func)"/>
+    <xsl:variable name="type">
+      <xsl:apply-templates mode="mal2html.inline.mode" select="$signal/api:returns/api:type/node()"/>
+    </xsl:variable>
+    <xsl:variable name="paren" select="$mal2html.api.tab.c.args -
+                                         $mal2html.api.tab.c.func -
+                                         string-length($type)"/>
+    <xsl:copy-of select="$type"/>
+    <xsl:choose>
+      <xsl:when test="$paren > 1">
+        <xsl:value-of select="str:padding($paren)"/>
+      </xsl:when>
+      <xsl:otherwise>
+        <xsl:text>&#x000A;</xsl:text>
+        <xsl:value-of select="str:padding($mal2html.api.tab.c.args)"/>
+      </xsl:otherwise>
+    </xsl:choose>
+    <xsl:text>(</xsl:text>
+    <xsl:for-each select="$signal/api:arg">
+      <xsl:if test="position() != 1">
+        <xsl:value-of select="str:padding($mal2html.api.tab.c.args + 1)"/>
+      </xsl:if>
+      <xsl:apply-templates mode="mal2html.inline.mode" select="api:type/node()"/>
+      <xsl:if test="api:type and (
+                    substring(api:type, string-length(api:type)) != '*'
+                    or not(contains(api:type, '*')))">
+        <xsl:text> </xsl:text>
+      </xsl:if>
+      <xsl:apply-templates mode="mal2html.inline.mode" select="api:name/node()"/>
+      <xsl:choose>
+        <xsl:when test="position() != last()">
+          <xsl:text>,</xsl:text>
+        </xsl:when>
+        <xsl:otherwise>
+          <xsl:text>);</xsl:text>
+        </xsl:otherwise>
+      </xsl:choose>
+      <xsl:text>&#x000A;</xsl:text>
+    </xsl:for-each>
+    <xsl:if test="not($signal/api:arg)">
+      <xsl:text>void);&#x000A;</xsl:text>
+    </xsl:if>
+  </span></div>
 </xsl:template>
 
 
@@ -352,7 +470,7 @@ $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 formatted as a function for a synopsis in the Python
+This template formats a link as a function for a synopsis in the Python
 programming language. It is called by *{mal2html.api.links.py} when the ${target}
 contains an #{api:function} element in its #{info}.
 -->
@@ -361,8 +479,8 @@ contains an #{api:function} element in its #{info}.
   <xsl:param name="links"/>
   <xsl:param name="link"/>
   <xsl:param name="target"/>
-  <xsl:variable name="function" select="$target/mal:info/api:function"/>
-  <div class="{$link/@class}">
+  <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="."/>
@@ -404,7 +522,7 @@ contains an #{api:function} element in its #{info}.
       <xsl:apply-templates mode="mal2html.inline.mode" select="$function/api:returns/api:type/node()"/>
     </xsl:if>
     <xsl:text>&#x000A;</xsl:text>
-  </div>
+  </span></div>
 </xsl:template>
 
 </xsl:stylesheet>
diff --git a/xslt/mallard/html/mal2html-page.xsl b/xslt/mallard/html/mal2html-page.xsl
index 2c53e26d..584d78c8 100644
--- a/xslt/mallard/html/mal2html-page.xsl
+++ b/xslt/mallard/html/mal2html-page.xsl
@@ -1092,6 +1092,12 @@ span.hi {
     <xsl:value-of select="$color.yellow_background"/><xsl:text>;
 }
 
+div.api-link { padding: 0.5em 0 0.5em 0; }
+div.api-link + div.api-link {
+  border-top: solid 1px </xsl:text>
+    <xsl:value-of select="$color.dark_background"/><xsl:text>;
+}
+
 div.facets {
   display: inline-block;
   padding: 6px;