GNOME Bugzilla – Bug 783368
Support for non-breaking strings
Last modified: 2017-12-18 15:18:44 UTC
Dear gtk-doc, sometimes we don't want long strings to be wrapped on two lines. It's especially true for signal and property names, which contain hyphens. The GTK+ CSS documentation pages (docs/reference/gtk/css-*.xml) tackled this problem by using some special characters: - U+2011 Non-breaking Hyphen - U+00A0 No-break Space It does the job, but it also has an unwanted side-effect: searching for the word will not work anymore. For example, visit <https://developer.gnome.org/gtk3/stable/chap-css-properties.html>, and search for 'font-family'. It will match only one occurrence (that uses a standard hyphen), but won't match other occurrences that use the non-breaking hyphen. I did a bit of research, and it looks like the usual way to solve this problem in the HTML/CSS world is to use the <span> element like this: <span class="nowrap">i-dont-want-to-be-broken</span> Then the class 'nowrap' receives the CSS property: white-space: nowrap; At least, that's how Wikipedia handles that [1]. Now, back to GTK+ documentation, which uses the Docbook XML format. We can achieve that by using the <phrase> element along with the 'role' attribute. For example, here's how it could be used in the file 'docs/reference/gtk/css-properties.xml'. Right now, it looks like that: <entry>-gtk-outline-bottom-left-radius</entry> With <phrase>, it would look like that: <entry><phrase role="nowrap">-gtk-outline-bottom-left-radius</phrase></entry> The 'role' attribute maps to a CSS class name [2]. The HTML generated looks like that: <td><span class="nowrap">-gtk-outline-bottom-left-radius</span></td> Then, the only thing left to do is to add the class 'nowrap' to the file 'style.css'. span.nowrap { white-space: nowrap; } I tried that, and it works. Remaining questions: This only deal with the CSS/HTML issue. Does the gtk documentation is also compiled to other formats, like PDF ? Disclaimer: I'm not HTML/CSS developer, don't trust me on that part. I also never dealt with gtk-doc before, so don't trust me there either. Good luck with that :) Command-lines snippets: Dealing with weird Unicode characters from the command-line is a pain, so let me paste some useful commands here. Finding the non-breaking hyphens ? cd docs/references grep -rl $'\xe2\x80\x91' . grep $'\xe2\x80\x91' ./gtk/css-overview.xml Replacing it with normal hyphens ? sed -i 's:\xe2\x80\x91:-:g' css-*.xml References: [1]: https://en.wikipedia.org/wiki/Template:Nowrap#Technical_details [2]: http://www.sagehill.net/docbookxsl/UsingCSS.html#CustomClass
Thanks for the research. I'll give this a try. Lets ignore the pdf story for now.
Hmm, https://git.gnome.org/browse/gtk+/tree/docs/reference/gtk is a handwritten file. So this can be already fixed there. In gtkdoc itself all <entry> nodes are produced here: https://git.gnome.org/browse/gtk-doc/tree/gtkdoc/mkdb.py#n336 where I could apply your suggestion too. I'll check for special unicode chars in the generated docs.
Ping?
Hey ! Sorry for the delay ! > In gtkdoc itself all <entry> nodes are produced here: > https://git.gnome.org/browse/gtk-doc/tree/gtkdoc/mkdb.py#n336 > where I could apply your suggestion too. I grepped again the gtk source for non-breaking hyphens and non-breaking spaces. They are found only in the following files: - ./docs/reference/gtk/css-overview.xml - ./docs/reference/gtk/css-properties.xml (There's also a few non-breaking spaces in some c files, but I believe they're here by mistake, so let's forget about them.) So here we're talking about two handwritten files only, where the <entry> nodes already exist. So I think there's no need to change anything in the mkdb.py. > https://git.gnome.org/browse/gtk+/tree/docs/reference/gtk > is a handwritten file. So this can be already fixed there. Are we talking about the css-*.xml files mentioned above here ? Your link points to the gtk directory, so I'm not 100% sure. Assuming that we're talking about the css-*.xml files, so yes, this can be fixed directly there, and it's exactly what I suggest. Ie, replacing in these files: <entry>-gtk-outline-bottom-left-radius</entry> with: <entry><phrase role="nowrap">-gtk-outline-bottom-left-radius</phrase></entry> This would work, assuming that the file 'style.css' contains something like that: span.nowrap { white-space: nowrap; } And the file 'style.css' is part of gtk-doc, not gtk !! That was not clear in my first message, sorry :) So I suggest this addition to the 'style.css' in **gtk-doc**, then modifying the css-*.xml files in **gtk** to make good use of this gtk-doc change. Of course we need to confirm that the gtk devs are OK with that, I'm not a gtk dev myself. Tell me if it's still unclear, I'll try to explain better. Useful commands: grep -rlI $'\xe2\x80\x91' . # non-breaking hyphens grep -rlI $'\xc2\xa0' . # non-breaking spaces
Thanks for the explanation. Getting this now. We could do this for the time being. I will need to check how one does this in plain markdown since we would like to migrate away from docbook (slow beyond repair :/). If you want to attach a patch with the css change. I am happy to push this, it won't hurt. I am going to do a release before christmas too.
Created attachment 365193 [details] [review] style: add span.nowrap for text that should never wrap
Please notify me when you merge this patch, then I'll submit some patches to GTK+ to make use of this nowrap thinggy.
Looking forward to it!
Hey, I just submitted a series of patch on GTK+ bugtracker: https://bugzilla.gnome.org/show_bug.cgi?id=791710 It would have been easier through Git, is there a way to submit merge requests against GTK+ ?
The following fix has been pushed: 06baafc style: add span.nowrap for text that should never wrap
Created attachment 365707 [details] [review] style: add span.nowrap for text that should never wrap And here's an example of how to use that from a Docbook xml file: <phrase role="nowrap">dont-break-me never ever</phrase> Fixes #783368. Signed-off-by: Arnaud Rebillout <elboulangero@gmail.com>