[gtk-doc] Use a table for signal synopsis

[William Jon McCann <mccann src gnome org>]

commit 3469633a71c52984f7119de88cb246f7725260ff
Author: William Jon McCann <william jon mccann gmail com>
Date:   Sun Feb 9 19:08:21 2014 -0500

    Use a table for signal synopsis
    
    https://bugzilla.gnome.org/show_bug.cgi?id=723991

 gtkdoc-mkdb.in  |   47 +++++++++++++++++++++++++++--------------------
 style/style.css |   10 ++++++++++
 2 files changed, 37 insertions(+), 20 deletions(-)
---
diff --git a/gtkdoc-mkdb.in b/gtkdoc-mkdb.in
index 516524e..3f5f4de 100755
--- a/gtkdoc-mkdb.in
+++ b/gtkdoc-mkdb.in
@@ -684,8 +684,16 @@ sub OutputSGML {
                     $signals_synop = <<EOF;
 <refsect1 id="$section_id.signals" role="signal_proto">
 <title role="signal_proto.title">Signals</title>
-<synopsis>
-${signals_synop}</synopsis>
+<informaltable frame="none">
+<tgroup cols="3">
+<colspec colname="return" colwidth="150px"/>
+<colspec colname="name" colwidth="300px"/>
+<colspec colname="flags" colwidth="200px"/>
+<tbody>
+${signals_synop}
+</tbody>
+</tgroup>
+</informaltable>
 </refsect1>
 EOF
                      $signals_desc = TrimTextBlock($signals_desc);
@@ -3493,7 +3501,6 @@ sub GetSignals {
             my $id = &CreateValidSGMLID ("$object-$name");
 
             my $pad = ' ' x (46 - length($name));
-            $synop .= "  “<link linkend=\"$id\">$name</link>”$pad ";
 
             $desc .= "<refsect2 id=\"$id\" role=\"signal\"><title>The <literal>“$name”</literal> 
signal</title>\n";
             $desc .= MakeIndexterms($symbol, $id);
@@ -3524,31 +3531,32 @@ sub GetSignals {
             # do two passes, the first one is to calculate padding
             for ($l = 0; $l < 2; $l++) {
                 for ($j = 0; $j <= $#params; $j++) {
+                    my $param_name;
                     # allow alphanumerics, '_', '[' & ']' in param names
                     if ($params[$j] =~ m/^\s*(\w+)\s*(\**)\s*([\w\[\]]+)\s*$/) {
                         $type = $1;
                         $pointer = $2;
                         if (defined($sourceparams)) {
-                            $name = $$sourceparams[$PARAM_FIELD_COUNT * $j];
+                            $param_name = $$sourceparams[$PARAM_FIELD_COUNT * $j];
                         }
                         else {
-                            $name = $3;
+                            $param_name = $3;
                         }
-                        if (!defined($name)) {
-                            $name = "arg$j";
+                        if (!defined($param_name)) {
+                            $param_name = "arg$j";
                         }
                         if ($l == 0) {
                             if (length($type) + length($pointer) > $type_len) {
                                 $type_len = length($type) + length($pointer);
                             }
-                            if (length($name) > $name_len) {
-                                $name_len = length($name);
+                            if (length($param_name) > $name_len) {
+                                $name_len = length($param_name);
                             }
                         }
                         else {
                             $xref = &MakeXRef ($type, &tagify($type, "type"));
                             $pad = ' ' x ($type_len - length($type) - length($pointer));
-                            $desc .= "$xref$pad $pointer$name,\n";
+                            $desc .= "$xref$pad $pointer${param_name},\n";
                             $desc .= (' ' x ($SYMBOL_FIELD_WIDTH + $RETURN_TYPE_FIELD_WIDTH));
                         }
                     } else {
@@ -3566,46 +3574,45 @@ sub GetSignals {
 
             if (defined ($flags)) {
               if ($flags =~ m/f/) {
-                $flags_string = "<link linkend=\"G-SIGNAL-RUN-FIRST:CAPS\"><literal>Run 
First</literal></link>";
+                $flags_string = "<link linkend=\"G-SIGNAL-RUN-FIRST:CAPS\">Run First</link>";
               }
               elsif ($flags =~ m/l/) {
-                $flags_string = "<link linkend=\"G-SIGNAL-RUN-LAST:CAPS\"><literal>Run 
Last</literal></link>";
+                $flags_string = "<link linkend=\"G-SIGNAL-RUN-LAST:CAPS\">Run Last</link>";
               }
               elsif ($flags =~ m/c/) {
-                $flags_string = "<link 
linkend=\"G-SIGNAL-RUN-CLEANUP:CAPS\"><literal>Cleanup</literal></link>";
+                $flags_string = "<link linkend=\"G-SIGNAL-RUN-CLEANUP:CAPS\">Cleanup</link>";
                 $flags_string = "Cleanup";
               }
               if ($flags =~ m/r/) {
                 if ($flags_string) { $flags_string .= " / "; }
-                $flags_string = "<link linkend=\"G-SIGNAL-NO-RECURSE:CAPS\"><literal>No 
Recursion</literal></link>";
+                $flags_string = "<link linkend=\"G-SIGNAL-NO-RECURSE:CAPS\">No Recursion</link>";
               }
               if ($flags =~ m/d/) {
                 if ($flags_string) { $flags_string .= " / "; }
-                $flags_string = "<link linkend=\"G-SIGNAL-DETAILED:CAPS\"><literal>Has 
Details</literal></link>";
+                $flags_string = "<link linkend=\"G-SIGNAL-DETAILED:CAPS\">Has Details</link>";
               }
               if ($flags =~ m/a/) {
                 if ($flags_string) { $flags_string .= " / "; }
-                $flags_string = "<link linkend=\"G-SIGNAL-ACTION:CAPS\"><literal>Action</literal></link>";
+                $flags_string = "<link linkend=\"G-SIGNAL-ACTION:CAPS\">Action</link>";
               }
               if ($flags =~ m/h/) {
                 if ($flags_string) { $flags_string .= " / "; }
-                $flags_string = "<link linkend=\"G-SIGNAL-NO-HOOKS:CAPS\"><literal>No 
Hooks</literal></link>";
+                $flags_string = "<link linkend=\"G-SIGNAL-NO-HOOKS:CAPS\">No Hooks</link>";
               }
             }
 
             if ($flags_string)
               {
-                $synop .= ": $flags_string\n";
-
                 $pad = ' ' x (5 + $name_len - length("user_data"));
                 $desc  .= "$pad : $flags_string</programlisting>\n";
               }
             else
               {
-                $synop .= "\n";
                 $desc  .= "</programlisting>\n";
               }
 
+            $synop .= "<row><entry role=\"signal_type\">${ret_type_output}</entry><entry 
role=\"signal_name\"><link linkend=\"$id\">${name}</link></entry><entry 
role=\"signal_flags\">${flags_string}</entry></row>\n";
+
             $desc .= &MakeDeprecationNote($symbol);
 
             my $parameters = &OutputParamDescriptions ("SIGNAL", $symbol);
diff --git a/style/style.css b/style/style.css
index f067c93..42d0824 100644
--- a/style/style.css
+++ b/style/style.css
@@ -163,6 +163,16 @@ div.informaltable table td, div.informaltable table th
   color: #555753;
 }
 
+.signal_type
+{
+  text-align: right;
+}
+
+.signal_flags
+{
+  color: #555753;
+}
+
 div.table table
 {
   border-collapse: collapse;