GNOME Bugzilla – Bug 650544
Broken link for Gtk::Label in online doc
Last modified: 2011-12-31 01:14:12 UTC
There is a broken link for Gtk::Label in the online documentation. From http://developer.gnome.org/gtkmm/stable/group__Widgets.html to http://developer.gnome.org/gtkmm/stable/classGtk_1_1Label.html
Same for Gtk::Entry http://developer.gnome.org/gtkmm/stable/classGtk_1_1Entry.html
This is due to the old version of Python on library.gnome.org, which has problems with our tar format, which we need to use for our long paths, though I can't find that old bug right now.
*** Bug 651877 has been marked as a duplicate of this bug. ***
From irc: > murrayc: re library.gnome.org, it has now moved to a newer installation, and it runs python 2.6 so that bug should probably be revisited (not much time to do it now :/ ) <murrayc> fredp: So it could be enough just to regenerate it? <fredp> murrayc: maybe.
Who deals with these bugs now?
Is there anything I can do to help make this happen?
Sorry I slacked on this one, as it meant pinging sysadmins, waiting for an upgrade, etc. but I wrote it should have been revisited, and indeed, because this is not the "long filenames" bug. There are errors in some of the html files, and they can't get transformed into their developer.gnome.org versions, for exampel: <p>This function does not reflect attributes that come from the labels markup (see <a class="el" href="classGtk_1_1Label.html#a63c357c5247b89944d81ff2fc07977f4" title="Parses str which is marked up with the ", str); gtk_label_set_markup (GTK_LABEL (label), markup); g_free (markup); ]|.">set_markup()</a>). If you want to get the effective attributes for the label, use pango_layout_get_attribute (gtk_label_get_layout (label)). </p> (note the " inside the title attribute) I scanned the other files, and there is also classGtk_1_1Expander.html and classGtk_1_1Entry.html.
Thanks. Yes, that must be a bug in gmmproc when it finds a link in the C documentation. gmmproc is generating this in the .h file: /** Parses @a str which is marked up with the * , * setting the label's text and attribute list based on the parse results. * If characters in @a str are preceded by an underscore, they are underlined * indicating that they represent a keyboard accelerator called a mnemonic. * * The mnemonic key can be used to activate another widget, chosen * automatically, or explicitly using set_mnemonic_widget(). * @param str A markup string (see * ). */ void set_markup_with_mnemonic(const Glib::ustring& str);
This is what's in our gtk_docs.xml: <function name="gtk_label_set_markup_with_mnemonic"> <description> Parses @str which is marked up with the <link linkend="PangoMarkupFormat">Pango text markup language</link>, setting the label's text and attribute list based on the parse results. If characters in @str are preceded by an underscore, they are underlined indicating that they represent a keyboard accelerator called a mnemonic. The mnemonic key can be used to activate another widget, chosen automatically, or explicitly using gtk_label_set_mnemonic_widget(). </description> <parameters> <parameter name="label"> <parameter_description> a #GtkLabel </parameter_description> </parameter> <parameter name="str"> <parameter_description> a markup string (see <link linkend="PangoMarkupFormat">Pango markup format</link>) </parameter_description> </parameter> </parameters> <return></return> </function>
Actually, this is the one that's causing the real problem: /** Parses @a str which is marked up with the ", str); * gtk_label_set_markup (GTK_LABEL (label), markup); * g_free (markup); * ]| * @param str A markup string (see ). */ void set_markup(const Glib::ustring& str); and this is what's in gtk_doc.xml for that: <function name="gtk_label_set_markup"> <description> Parses @str which is marked up with the <link linkend="PangoMarkupFormat">Pango text markup language</link>, setting the label's text and attribute list based on the parse results. If the @str is external data, you may need to escape it with g_markup_escape_text() or g_markup_printf_escaped()<!-- -->: |[ char *markup; markup = g_markup_printf_escaped ("<span style=\"italic\">%s</span>", str); gtk_label_set_markup (GTK_LABEL (label), markup); g_free (markup); ]| </description> <parameters> <parameter name="label"> <parameter_description> a #GtkLabel </parameter_description> </parameter> <parameter name="str"> <parameter_description> a markup string (see <link linkend="PangoMarkupFormat">Pango markup format</link>) </parameter_description> </parameter> </parameters> <return></return> </function>
Note that bug #642852 causes a similar problem, apparently for a different reason.
We need to fix our generated documentation string, but we also need a fix in Doxygen, so I filed doxygen bug #659244 .
Created attachment 196864 [details] [review] Patch to fix our generated documentation string. This patch fixes the removal of the link tags so the generated string is correct. It also makes gmmproc translate the '|[' and ']|' to '@code' and '@endcode' respectively. This should make fixing this bug easier.
(In reply to comment #13) > This should make fixing this bug easier. Actually, the documentation more readable.
(In reply to comment #13) > Created an attachment (id=196864) [details] [review] > Patch to fix our generated documentation string. > > This patch fixes the removal of the link tags so the generated string is > correct. It also makes gmmproc translate the '|[' and ']|' to '@code' and > '@endcode' respectively. This should make fixing this bug easier. Many thanks. That fixes the problem. There is now no " in the doxygen comment, so it doesn't appear in the title. Pushed. I'll do a gtkmm tarball release to see if it works on developer.gnome.org. I think we should discard the example code in the C documentation, maybe with a warning on stdout, I think having the C documentation in our C++ documentation is worse than no documentation at all, though we should replace it with C++ example code ideally, via our *_overrides.xml files.
It looks OK now: http://developer.gnome.org/gtkmm/unstable/group__Widgets.html links to this page, which _is_ now there: http://developer.gnome.org/gtkmm/unstable/classGtk_1_1Label.html And this is here too: http://developer.gnome.org/gtkmm/unstable/classGtk_1_1Entry.html We can also see that the set_markup() documentation is now corrected: http://developer.gnome.org/gtkmm/unstable/classGtk_1_1Label.html#a63c357c5247b89944d81ff2fc07977f4 Thanks everyone. Please reopen this bug if there is still a problem.
Actually, someone in bug #660518 just noticed that the Entry page is not there anymore, though the Label page still is.
*** Bug 660518 has been marked as a duplicate of this bug. ***
Fred, do you have any idea why the Label page is not there?
Fred?
/var/cache/gnomeweb/developer.gnome.org/extracts/gtkmm-3.2.0/docs/reference/html/classGtk_1_1Entry.html:1136: parser error : CharRef: invalid decimal value ion in the entry contents (returned by get_text()) to a position in the entry The complete line is as follows: <p>Keep in mind that the layout text may contain a preedit string, so <a class="el" href="classGtk_1_1Entry.html#aa84bf0a3bc5daed4f6943beabc95537c" title="Converts from a position in the entry contents (returned by get_text()) to a position in the entry...">layout_index_to_text_index()</a> and <a class="el" href="classGtk_1_1Entry.html#a1ad913685fa2088c14ed9f1195edc279" title="Converts from a position in the entry's Pango::Layout (returned by get_layout()) to a position in...">text_index_to_layout_index()</a> are needed to convert byte indices in the layout to byte indices in the entry contents. </p> What happens is: - layout_index_to_text_index is turned into a link - the link title is set from layout_index_to_text_index documentation - for an unknown reason (perhaps because it will end in a html attribute), that string is first quoted (and "entry's Pango" → "entry&39;s Pango" - the documentation is ellipsised at the 100th character, - this is unfortunately in the middle of the html entity - the resulting html file has &3..., the parser chokes. I hand edited the file on the server, to fix the 404, it would be nice if doxygen could be fixed to ellipsize before escaping.
Ah, sorry for making you do all that investigation again. I guess you already discovered this for us in doxygen bug #642852 .
Running xmllint --noutout on our generated html shows that the first invalid html is caused when the doxygen bug is triggered by these lines in label.h, which look wrong anyway: /** Parses @a str which is marked up with the ", str); * gtk_label_set_markup (GTK_LABEL (label), markup); * g_free (markup); * ]| * @param str A markup string (see ). */ void set_markup(const Glib::ustring& str);
That's odd. I thought that the patch given earlier had fixed that. This is what I see in my local gtkmm for that method (I think it's also the same in the 3.2.0 tarball): /** Parses @a str which is marked up with the Pango text markup language, setting the * label's text and attribute list based on the parse results. If the @a str is * external data, you may need to escape it with Glib::markup_escape_text() or * Glib::markup_printf_escaped()<!-- -->: * @code * char *markup; * * markup = g_markup_printf_escaped ("<span style=\"italic\">%s</span>", str); * gtk_label_set_markup (GTK_LABEL (label), markup); * g_free (markup); * @endcode * @param str A markup string (see Pango markup format). */ void set_markup(const Glib::ustring& str);
Sorry. I was looking at some old html.
Created attachment 199977 [details] [review] gmmproc to discard C example code from the generated XML docs (In reply to comment #15) > I think we should discard the example code in the C documentation, maybe with a > warning on stdout, I think having the C documentation in our C++ documentation > is worse than no documentation at all, though we should replace it with C++ > example code ideally, via our *_overrides.xml files. Would this patch be okay? It removes example code in <informalexample></informalexample> tags and in '|[' ']|' markers.
Created attachment 199990 [details] [review] gmmproc: Updated patch to discard example code from the XML docs Actually, this patch might be better because it prints the function name along with the warning so that it is known which examples have been removed in case it is desired to translate them (or to confirm that the docs still read appropriately without the example).
(In reply to comment #27) > Created an attachment (id=199990) [details] [review] > gmmproc: Updated patch to discard example code from the XML docs Pushed. Thanks.
I guess one of my previous tarball uploads had old .html files. Anyway, this now seems to be fixed with the gtkmm 3.3.2 release: http://developer.gnome.org/gtkmm/unstable/classGtk_1_1Label.html I also added an xmllint check that runs during make check or distcheck, so we can't release another tarball with these errors. Frederic, thanks for your help. Now bug #651987 is the only serious problem left for the gtkmm API reference on developer.gnome.org. I hope you have the time to take a look, please.
Would it be doable to get this fixed for 2.24 as well?