Re: linking to signals

["Matthias Clasen" <matthias clasen gmail com>]

On 5/28/07, Damon Chaplin <damon karuna eclipse co uk> wrote:
> On Sat, 2007-05-26 at 21:44 -0400, Matthias Clasen wrote:
> > I've recently started to use the #GtkWidet::expose-event syntax that was
> > introduced some time ago to create links to signal documentation. It is
> > really great to have this convenient syntax for it, but here are two
> > things that I think should be improved:
> >
> > a) While it is necessary to specify the class to uniquely identify a
> > signal, in practice there is rarely confusion about which class a signal
> > belongs to. Therefore, I'd welcome it if we could simplify the formatted
> > link text in the output to just ::signal-name.
>
> Yes, that would probably look better.
>
>
> > b) The link syntax moves ::signal-name closer to being the "official"
> > way to refer to signals in the docs. It would therefore be more
> > consistent if the autogenerated signal docs would also use ::signal-name
> > in their title, instead of "signal_name".
>
> That is probably OK too, as long as it is still obviously a signal.

Here is a patch.

--- gtkdoc-mkdb.in	2007-05-30 00:41:22.000000000 -0400
+++ gtkdoc-mkdb	2007-05-30 00:40:20.000000000 -0400
@@ -1934,7 +1934,7 @@
     # Convert '#symbol'
     # if $1 is Object::signal change id to Object-signal
     # if $1 is Object:property change id to Object--property
-    $text =~ s/#([\w\-:]+)/&MakeHashXRef(&symbolify($1), &tagify2($1, "type"));/eg;
+    $text =~ s/#([\w\-:]+)/&MakeHashXRef(&symbolify($1), &tagify2(classless($1), "type"));/eg;
   }
 
   return $text;
@@ -2031,6 +2031,14 @@
   return $symbol;
 }
 
+sub classless {
+  my ($symbol) = @_;
+
+  $symbol =~ s/^[^:]*:/:/;
+
+  return $symbol;
+}
+
 sub tagify {
    my ($text, $elem) = @_;
    return "<" . $elem . ">" . $text . "</" . $elem . ">";
@@ -2443,9 +2451,9 @@
 	    my $id = &CreateValidSGMLID ("$object-$name");
 
 	    my $pad = ' ' x (46 - length($name));
-	    $synop .= "  &quot;<link linkend=\"$id\">$name</link>&quot;$pad ";
+	    $synop .= "  <link linkend=\"$id\">$name</link>$pad ";
 
-	    $desc .= "<refsect2><title><anchor id=\"$id\"${empty_element_end}The &quot;$name&quot; signal</title>\n";
+	    $desc .= "<refsect2><title><anchor id=\"$id\"${empty_element_end}The <literal>::$name</literal> signal</title>\n";
 	    $desc .= MakeIndexterms($symbol);
 	    $desc .= "<programlisting>";
 
@@ -2678,10 +2686,10 @@
 	        $kind = "property";
 	    }
 
- 	    my $arg_synop = "  &quot;<link linkend=\"$id\">$name</link>&quot;$pad1 $type_output $pad2 : $flags_string\n";
-	    my $arg_desc = "<refsect2><title><anchor id=\"$id\"${empty_element_end}The &quot;<literal>$name</literal>&quot; $kind</title>\n";
+ 	    my $arg_synop = "  <link linkend=\"$id\">$name</link>$pad1 $type_output $pad2 : $flags_string\n";
+	    my $arg_desc = "<refsect2><title><anchor id=\"$id\"${empty_element_end}The :<literal>$name</literal> $kind</title>\n";
 	    $arg_desc .= MakeIndexterms($symbol);
-	    $arg_desc .= "<programlisting>  &quot;$name&quot;$pad1 $type_output $pad2 : $flags_string</programlisting>\n";
+	    $arg_desc .= "<programlisting>  $name$pad1 $type_output $pad2 : $flags_string</programlisting>\n";
 	    $arg_desc .= $blurb;
 	    if ($range ne "") {
 	        $arg_desc .= "<para>Allowed values: $range_output</para>\n";