GNOME Bugzilla – Bug 758137
GtkLabel and GtkShortcutsShortcut notes on escaping character entities don't render properly
Last modified: 2016-04-12 03:32:39 UTC
The docs for GtkLabel render as “literal <, > and & characters must be escaped as <, >, and &.” when they should say “literal <, > and & characters must be escaped as <, >, and &.” There is a similar problem with the GtkShortcutsShortcut docs. The gtk-doc wiki¹ says “Note that we no longer interpret XML markup in text, so it is no longer necessary (and not working, either) to escape the special characters '<', '>', '()', '@', '%', or '#' as XML entities "<", ">", "(", ")", "@", "%" and "#".” So they need to be written as ‘&lt;’ etc. ¹https://wiki.gnome.org/Projects/GTK%2B/DocumentationSyntax/Markdown
Created attachment 315631 [details] [review] Fix notes on escaping character entities The docs for GtkLabel render as “literal <, > and & characters must be escaped as <, >, and &.” when they should say “literal <, > and & characters must be escaped as <, >, and &.” There is a similar problem with the GtkShortcutsShortcut docs. The gtk-doc wiki¹ says “Note that we no longer interpret XML markup in text, so it is no longer necessary (and not working, either) to escape the special characters '<', '>', '()', '@', '%', or '#' as XML entities "<", ">", "(", ")", "@", "%" and "#".” So they need to be written as ‘&lt;’ etc. ¹https://wiki.gnome.org/Projects/GTK%2B/DocumentationSyntax/Markdown
Note that your reference from the gtk-doc wiki contradicts what you suggesting.
(In reply to Matthias Clasen from comment #2) > Note that your reference from the gtk-doc wiki contradicts what you > suggesting. I'm not sure if this is a bug with gtk-doc or gtk+ as I find the wording of the wiki confusing. What I do know is that '<' renders as '<' and '&lt;' renders as '<' If that is inconsistent with the wiki either there is a bug in gtk-doc or the wiki is wrong. Do you know what the intended behaviour of gtk-doc is?
Created attachment 315643 [details] [review] Escape entity references in markdown The documentation for the markdown format promises that we can just write &foo; or <foo> in text when discussing XML. This works for tags, but entity references such as < are still expanded. To fix this, escape all & that we find with &, not just 'freestanding' ones.
I've filed Bug 758175 and Bug 758174 to convert character entities into their characters for gtk and glib as they will break if gtk-doc starts to work as advertized.
Review of attachment 315643 [details] [review]: Do we want to support character entities with \< in the same way that we can escape < with \< to embed xml tags?
(In reply to Phillip Wood from comment #6) > Review of attachment 315643 [details] [review] [review]: > > Do we want to support character entities with \< in the same way that we > can escape < with \< to embed xml tags? The wiki seems to say you can escape < with \< but having tried it, it doesn't work in practice the generated xml is '\<' not '<'
(In reply to Phillip Wood from comment #7) > (In reply to Phillip Wood from comment #6) > > Review of attachment 315643 [details] [review] [review] [review]: > > > > Do we want to support character entities with \< in the same way that we > > can escape < with \< to embed xml tags? > > The wiki seems to say you can escape < with \< but having tried it, it > doesn't work in practice the generated xml is '\<' not '<' The wiki is a bit unclear on that point. The \ escaping is meant only for characters that are significant in markdown (or gtk-doc extensions), not in xml. So, you can do \@, \# and \%
Review of attachment 315643 [details] [review]: ::: gtkdoc-mkdb.in @@ +2758,2 @@ # First, convert freestanding & to & + $text =~ s/&/&/g; Should we skip this if there is a '\' before the '&'?
FYI, The gtk-doc help is the authority, the wiki page is not maintained by myself. But given comment 8. I think the patch is actually right.
(In reply to Stefan Sauer (gstreamer, gtkdoc dev) from comment #10) > FYI, The gtk-doc help is the authority, the wiki page is not maintained by > myself. But given comment 8. I think the patch is actually right. I've just had another look at the gtk-doc help¹ and it explicitly says one *has* to use character entities for ‘<’ etc which is incorrect. The wiki is also currently incorrect in saying that character entities are not supported. The help also says that docbook markup is supported within markdown but that does not seem to be the case. If you look at https://developer.gnome.org/glib/stable/glib-Error-Reporting.html#gerror-rules the 9th item in the list has docbook tags in the rendered output. The help also refers readers to the wiki for details on gtk-doc’s markdown support which is confusing if the manual is the definitive reference. I'm happy to have a go at updating the wiki one I know what is meant to be supported and what isn't. ¹https://developer.gnome.org/gtk-doc-manual/1.24/documenting_syntax.html.en
(In reply to Stefan Sauer (gstreamer, gtkdoc dev) from comment #9) > Review of attachment 315643 [details] [review] [review]: > > ::: gtkdoc-mkdb.in > @@ +2758,2 @@ > # First, convert freestanding & to & > + $text =~ s/&/&/g; > > Should we skip this if there is a '\' before the '&'? That might be useful if the source does not use utf8 (e.g. wants/needs to be restricted to ascii for some reason) but using the real character is more in keeping with the markdown’s aim of readable source code.
(In reply to Matthias Clasen from comment #8) > (In reply to Phillip Wood from comment #7) > > (In reply to Phillip Wood from comment #6) > > > Review of attachment 315643 [details] [review] [review] [review] [review]: > > > > > > Do we want to support character entities with \< in the same way that we > > > can escape < with \< to embed xml tags? > > > > The wiki seems to say you can escape < with \< but having tried it, it > > doesn't work in practice the generated xml is '\<' not '<' > > The wiki is a bit unclear on that point. The \ escaping is meant only for > characters that are significant in markdown (or gtk-doc extensions), not in > xml. So, you can do \@, \# and \% Thanks for clearing that up. I'd forgotten that ‘>’ was used in markdown as well as xml.