linking to signals

[Matthias Clasen]

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.

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".

Opinions ?

_______________________________________________
gtk-doc-list mailing list
gtk-doc-list@...
http://mail.gnome.org/mailman/listinfo/gtk-doc-list

[Damon Chaplin-2]

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.

Damon


_______________________________________________
gtk-doc-list mailing list
gtk-doc-list@...
http://mail.gnome.org/mailman/listinfo/gtk-doc-list

[Matthias Clasen-2]

On 5/28/07, Damon Chaplin <damon@...> 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.

[signal.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 .= "  "<link linkend=\"$id\">$name</link>"$pad ";
+    $synop .= "  <link linkend=\"$id\">$name</link>$pad ";
 
-    $desc .= "<refsect2><title><anchor id=\"$id\"${empty_element_end}The "$name" 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 = "  "<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";
+    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>  "$name"$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";

---

_______________________________________________
gtk-doc-list mailing list
gtk-doc-list@...
http://mail.gnome.org/mailman/listinfo/gtk-doc-list

[Damon Chaplin-2]

On Wed, 2007-05-30 at 00:47 -0400, Matthias Clasen wrote:

> 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;
   }


That will affect properties as well, won't it? Was that intentional?

Damon


_______________________________________________
gtk-doc-list mailing list
gtk-doc-list@...
http://mail.gnome.org/mailman/listinfo/gtk-doc-list

[Matthias Clasen]

On Fri, 2007-06-01 at 09:58 +0100, Damon Chaplin wrote:

> On Wed, 2007-05-30 at 00:47 -0400, Matthias Clasen wrote:
>
> > 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;
>    }
>
>
> That will affect properties as well, won't it? Was that intentional?

Ah, yes. Didn't I mention that I'd like to see property links shortened
as well ? But we can treat that independently, if you want. I guess even
better would be some context-sensitive solution, ie create short links
when in the context of the same class, ie for a link from
gtk_foo_set_bar to Foo:bar, and create full links otherwise. But that
may be a bit harder.

_______________________________________________
gtk-doc-list mailing list
gtk-doc-list@...
http://mail.gnome.org/mailman/listinfo/gtk-doc-list

[Damon Chaplin-2]

On Fri, 2007-06-01 at 08:25 -0400, Matthias Clasen wrote:
> On Fri, 2007-06-01 at 09:58 +0100, Damon Chaplin wrote:

> > That will affect properties as well, won't it? Was that intentional?
>
> Ah, yes. Didn't I mention that I'd like to see property links shortened
> as well ? But we can treat that independently, if you want. I guess even
> better would be some context-sensitive solution, ie create short links
> when in the context of the same class, ie for a link from
> gtk_foo_set_bar to Foo:bar, and create full links otherwise. But that
> may be a bit harder.

I've just tried the patch and I'm afraid I don't really like the
':property' and '::signal' in the output. It seems more confusing than
helpful to me.

I agree about shortening the link text though. I've changed it to just
use "property" and "signal". Hopefully that is good enough.

Damon


_______________________________________________
gtk-doc-list mailing list
gtk-doc-list@...
http://mail.gnome.org/mailman/listinfo/gtk-doc-list

[Matthias Clasen]

On Mon, 2007-06-11 at 15:06 +0100, Damon Chaplin wrote:

> On Fri, 2007-06-01 at 08:25 -0400, Matthias Clasen wrote:
> > On Fri, 2007-06-01 at 09:58 +0100, Damon Chaplin wrote:
>
> > > That will affect properties as well, won't it? Was that intentional?
> >
> > Ah, yes. Didn't I mention that I'd like to see property links shortened
> > as well ? But we can treat that independently, if you want. I guess even
> > better would be some context-sensitive solution, ie create short links
> > when in the context of the same class, ie for a link from
> > gtk_foo_set_bar to Foo:bar, and create full links otherwise. But that
> > may be a bit harder.
>
> I've just tried the patch and I'm afraid I don't really like the
> ':property' and '::signal' in the output. It seems more confusing than
> helpful to me.
>
> I agree about shortening the link text though. I've changed it to just
> use "property" and "signal". Hopefully that is good enough.
>

I disagree a bit with this. ::foo-bar is already a relatively widespread
conventions for referring to signals, just look through the GTK+ docs.
One of the big advantages of my proposal was to unify the non-link and
link appearance of signals. If I can't have ::foo-bar, I'd rather have
the long names back...

_______________________________________________
gtk-doc-list mailing list
gtk-doc-list@...
http://mail.gnome.org/mailman/listinfo/gtk-doc-list

[Damon Chaplin-2]

On Mon, 2007-06-11 at 10:34 -0400, Matthias Clasen wrote:
> On Mon, 2007-06-11 at 15:06 +0100, Damon Chaplin wrote:

> > I've just tried the patch and I'm afraid I don't really like the
> > ':property' and '::signal' in the output. It seems more confusing than
> > helpful to me.
> >
> > I agree about shortening the link text though. I've changed it to just
> > use "property" and "signal". Hopefully that is good enough.
> >
>
> I disagree a bit with this. ::foo-bar is already a relatively widespread
> conventions for referring to signals, just look through the GTK+ docs.
> One of the big advantages of my proposal was to unify the non-link and
> link appearance of signals. If I can't have ::foo-bar, I'd rather have
> the long names back...

I think that since the signal name is mainly used as a literal string
within code, it makes more sense to use that string in the
documentation.

::foo-bar doesn't relate to anything used in code and beginners will
just wonder 'what do the colons mean?'.

Damon


_______________________________________________
gtk-doc-list mailing list
gtk-doc-list@...
http://mail.gnome.org/mailman/listinfo/gtk-doc-list

[Stefan Kost]

Hi,

Damon Chaplin wrote:

> On Mon, 2007-06-11 at 10:34 -0400, Matthias Clasen wrote:
>> On Mon, 2007-06-11 at 15:06 +0100, Damon Chaplin wrote:
>
>>> I've just tried the patch and I'm afraid I don't really like the
>>> ':property' and '::signal' in the output. It seems more confusing than
>>> helpful to me.
>>>
>>> I agree about shortening the link text though. I've changed it to just
>>> use "property" and "signal". Hopefully that is good enough.
>>>
>> I disagree a bit with this. ::foo-bar is already a relatively widespread
>> conventions for referring to signals, just look through the GTK+ docs.
>> One of the big advantages of my proposal was to unify the non-link and
>> link appearance of signals. If I can't have ::foo-bar, I'd rather have
>> the long names back...
>
>
> I think that since the signal name is mainly used as a literal string
> within code, it makes more sense to use that string in the
> documentation.
>
> ::foo-bar doesn't relate to anything used in code and beginners will
> just wonder 'what do the colons mean?'.
>
> Damon

I am also for using full names. One alternative would be to decorate the link
with icons (Class, Property, Signal,...) using css. I could check if e.g. anjuta
has fitting ones and come up with a patch.

Stefan
_______________________________________________
gtk-doc-list mailing list
gtk-doc-list@...
http://mail.gnome.org/mailman/listinfo/gtk-doc-list