GNOME Bugzilla – Bug 736725
Documentation consists mostly of empty space
Last modified: 2015-05-06 20:26:27 UTC
The new CSS styles add so much empty space, namely vertical but also horizontal, that they render the documentation difficult to use on smaller screens. An example quantitative comparison of a brief section of the documentation (see the attached screenshots): Vertical size Empty vertical space Old 470 px 51% New 833 px 61% So the same information needs 70% (!) more vertical screen estate to display, despite a slightly smaller font. More than 60% of the height is consumed by empty space in the new style. You can't even display the documentation of the two simple functions together on a 720p HD display. I know GNOME loves empty space in design but this is just too much.
Created attachment 286268 [details] Screenshot of the old style
Created attachment 286269 [details] Screenshot of the new style
I tend to agree. Initial change where adding even more whitespace. E.g. after the 'parameters' sub heading the space is not good. Do you want to tweak this can send you changes to the css?
I will try to tweak the style.
I was fighting with not being able to find anything using devhelp at all (https://bugzilla.redhat.com/show_bug.cgi?id=1161959) so the formatting of documentation I could not get to become somewhat secondary issue... Anyway, I had a limited success with the style tweaks. The overview lists can be improved simply with --- style.css.orig +++ style.css @@ -60,7 +60,7 @@ div.informaltable table { border-collapse: separate; - border-spacing: 1em 0.5em; + border-spacing: 1em 0.0em; border: none; } as the vertical spaces there are not necessary as visual guides. And anyway for visual guides I would prefer highlighting of the current row, i.e. something like --- style.css.orig 2014-11-09 21:15:03.500150330 +0100 +++ style.css 2014-11-09 22:18:31.049355306 +0100 @@ -59,14 +59,21 @@ div.informaltable table { - border-collapse: separate; - border-spacing: 1em 0.5em; + border-collapse: collapse; border: none; } +div.informaltable table tr:hover +{ + /* tango:aluminium highlight */ + background-color: #eeeeec; +} + However, the hard problem is parameters and return values. Particularly due to the introduction of ‘Parameters’ and ‘Returns’ headers that eat lots of vertical screen estate. For simpler function they need considerably space than the actual descriptions of parameters and return value. I would prefer to get rid of them and move the return value back to the list, like in the old style. I did not find the old format confusing, but the return value can be called ‘Return value’ instead of just ‘Returns’ and/or it can be separated a bit more from the other items if necessary and/or other typographical means can be used. But I fear the addition of the headers was some design decision from high places... So, should I even try?
The table of contents lists can be reaonsably compactified with --- style.css.orig +++ style.css @@ -166,17 +173,13 @@ padding-bottom: 0.25em; } -dl.toc > dd > dl > dt +dl.toc > dt { - padding-top: 0.25em; - padding-bottom: 0.25em; + font-weight: bold; } -dl.toc > dt -{ - padding-top: 1em; +dl.toc dl { padding-bottom: 0.5em; - font-weight: bold; } .parameter The ‘Parameters’ and ‘Returns’ cannot be safely styled-out in CSS because they are normal h4 headers, the same as occasionally present as section headers elsewhere. So the only way to compactify this part is to change the generated docbook code in gtk-doc itself.
I followed your first suggestion from comment #5, but settleted on 0.3em and applied the change from comment #6. I also reduced the space around h4 (parameters and returns). I'll see how it will look if I change 'Parameters' to 'Parameters and Result' and separate the return value with some extra space in the table (blank line perhaps). commit 968ebfd953487011eb36ca87996e5607654ee1a0 Author: Stefan Sauer <ensonic@users.sf.net> Date: Wed May 6 22:24:41 2015 +0200 style.css: save a little screen space The new style went a bit overboard with the whitespace. Fixes #736725