GNOME Bugzilla – Bug 603930
gmmproc: Property documentation: Loses text after comma
Last modified: 2011-05-27 13:50:35 UTC
The documentation for Gtk::CellRendererCombo::property_has_entry() (on http://library.gnome.org/devel/gtkmm/unstable/classGtk_1_1CellRendererCombo.html#af552c276bbfe5de8ad68765982e7ef1e) contains the text " If FALSE. You rarely need to use properties because there are get_ and set_ methods for almost all of them. " Which is downright impossible to understand.
glibmm/tools/pmProperty.pm gets the correct text from the gtk_signals.defs file, but m4 seems to lose anything after the comma when parsing the _PROPERTY_PROXY() call, as written here: http://git.gnome.org/browse/glibmm/tree/tools/pm/Output.pm#n621 Adding `' around the $s, as done elsewhere in that file, like so, my $str = sprintf("_PROPERTY_PROXY(%s,%s,%s,%s,\`%s\')dnl\n", partly fixes it, but leaves a trailing ' in the .h file, like so: /** If FALSE, dont allow to enter strings other than the chosen ones.' Notice also that don't has changed to dont. CCing Daniel Elstner in case he knows how to do this properly.
Any ideas, Daniel?
Created attachment 160304 [details] [review] Patch to quote property docs without leaving trailing single quotes I know the question was addressed to Daniel, but he might be a little busy. One quick way to solve it could be to change the quotes before and after the docs string so that single quotes are not an issue. A patch is attached.
Sure. Many thanks. If that fixes it then please commit. I guess that an explanatory comment next to those lines of code might be useful though.
Okay. Committed with the comments: http://git.gnome.org/browse/glibmm/commit/?id=3b643e509757fb2c15c55bd7a1d0707096fa4506
Reopening, as a reminder for me to take a look at the problem again when I find the time, because changequote() is evil (see the M4 and Autoconf manuals for details). Even if it appears to work now, there is at least the problem that it will break again as soon as you use [ or ] in the comment text. The underlying issue is that M4 cannot handle unbalanced quote characters. If I remember correctly, gmmproc substitutes the dangerous quote characters in source code with special escape sequences, and converts the escapes back as the final step before writing the result to disk. I guess what happens here is that the comment does not count as part of the source code proper, since it is an M4 macro argument and thus parsed as M4 syntax.
*** Bug 647799 has been marked as a duplicate of this bug. ***
(In reply to comment #1) > Adding `' around the $s, as done elsewhere in that file, like so, > my $str = sprintf("_PROPERTY_PROXY(%s,%s,%s,%s,\`%s\')dnl\n", > partly fixes it, but leaves a trailing ' in the .h file, like so: > > /** If FALSE, dont allow to enter strings other than the chosen ones.' > > Notice also that don't has changed to dont. When m4 removes a level of quotations in /** `If FALSE, don't allow to enter strings other than the chosen ones.' it removes ` and the first ' after that, i.e. the ' in don't, leaving the trailing ', which lacks a corresponding quote start (`). (In reply to comment #6) > If I remember correctly, gmmproc substitutes the dangerous quote characters > in source code with special escape sequences, and converts the escapes back > as the final step before writing the result to disk. Yes Daniel, you remember correctly. E.g. WrapParser::on_comment_c() puts a level of m4 quotes around a comment, and within the comment it replaces ` and ' by '__BT__` and '__FT__` resp. __BT__ and __FT__ are m4 macros, defined in glibmm/tools/m4/base.m4. DocsParser::convert_docs_to_cpp() does something similar, but rather half- heartedly. It ought to be more like WrapParser::on_comment_c(). Output::output_wrap_property() should also prepare the comment text similarly to what WrapParser::on_comment_c() does. There are at least two peculiarities of m4 to be aware of: - The quote characters (`') are important. In macro calls, also comma (,) and parentheses have special significance, unless quoted. - Every word in unquoted text is a potential macro call. If the word is the name of a macro, macro substitution is performed. It's important to quote at least all comments, and to replace m4's quote characters in comments the way WrapParser::on_comment_c() and some other functions do. Daniel, you said in comment 6 that you plan to take a look at this problem. If you don't mind, I can make a patch.
> Daniel, you said in comment 6 that you plan to take a look at this problem. > If you don't mind, I can make a patch. I think Daniel is unlikely to find time for this, so a patch would be very welcome.
Created attachment 187705 [details] [review] gmmproc: Protect documentation with m4 quotes. (glibmm) Here's the patch. Now it's possible to include in property documentation: m4 quotes (`'), commas, square brackets, balanced and unbalanced parentheses (bug 647799), names of m4 macros. In method documentation: names of m4 macros (The other stuff is possible even without this patch or the patch in comment 3, I think.) gmmproc has long since protected documentation (comments) read from the .hg files with m4 quotes before it's sent to the m4 macro processor. No change needed there. Note that this is a glibmm patch, although this bug is assigned to gtkmm.
Please push. Thanks.
Is the request to push the patch meant for me? I have no Git account, and then I can't push anything, can I? Do you think it's about time I apply for a Git account?
(In reply to comment #12) > Do you think it's about time I apply for a Git account? Yes, please, you have long since qualified for one.
I have pushed the patch in comment 10. This bug is thus fixed, but I have no permission to close it. I haven't found any instructions how to apply for extra permissions in Bugzilla.
Thanks. You probably have to ask the GNOME bugsquad for more permissions.