[libvirt] [PATCH 2/2 v2] docs: Add some style and color to the HTML documentation

[Claudio Bley]

At Thu, 10 Jan 2013 13:58:28 +0100,
Jiri Denemark wrote:
> 
> On Wed, Jan 09, 2013 at 15:40:08 +0100, Claudio Bley wrote:
> > 
> > Signed-off-by: Claudio Bley <cbley at av-test.de>
> > ---
> >  docs/generic.css |    4 ++++
> >  docs/libvirt.css |   56 ++++++++++++++++++++++++++++++++++++++++++++++++++++--
> >  2 files changed, 58 insertions(+), 2 deletions(-)
> 
> Overall it looks quite well except for few issues...
> 
> > 
> > diff --git a/docs/generic.css b/docs/generic.css
> > index dbf7b56..1def6bf 100644
> > --- a/docs/generic.css
> > +++ b/docs/generic.css
> > @@ -73,3 +73,7 @@ dl dd {
> >    margin-right: 2em;
> >    margin-bottom: 0.5em;
> >  }
> > +
> > +tt, pre {
> > +  font-family: "Ubuntu Monospace", "Consolas", "Lucida Console", monospace;
> > +}
> 
> Do not do this. Default font-family for tt/pre is just good enough. If
> you don't like it, change your desktop/browser settings.

I beg to differ. I tried 4 Browsers on 2 OSes, and it looked bad to me
in all of them using the default user agent settings.

IMO, the 80% font-size is too small to look any decent using the user
agent font settings for tt / pre elements. It's hardly readable! (bad
with Firefox on Fedora, worse with Webkit on Windows)

But removing the 80% font-size setting looks ugly, too.

Any way, if there was only a single browser with bad defaults,
wouldn't it make sense trying to fix this for better user experience
instead of telling all users to change their settings (on every single
system they use)?

As this is mainly a matter of taste, other opinions, please! Or better
yet, alternative solutions...

> > +.api {
> > +    font-family: "Ubuntu Monospace", "Consolas", "Lucida Console", monospace;
> > +    line-height: 175%;
> > +}

> Just
> 
>     font-family: monospace;
> 
> without other families and without the huge line-height which makes
> reading hard.

OK, I'll reduce the line-height. It had to be that large for the
underline decoration of links. But see below.

> > diff --git a/docs/libvirt.css b/docs/libvirt.css
> > index 5123ed6..2bd9f8f 100644
> > --- a/docs/libvirt.css
> > +++ b/docs/libvirt.css
> > +.api :link:hover, .api :link:focus {
> > +    color: blue;
> > +    border-color: blue;
> > +}
> > +
> > +.api :link {
> > +    text-decoration: none;
> > +    padding-bottom: 2px;
> > +    border-bottom: 1px dashed grey;
> > +}
> 
> Leaving just
> 
>     text-decoration: none;
> 
> would be best.

Agreed.

Here's a follow-up patch:

--- >8 ----
diff --git a/docs/generic.css b/docs/generic.css
index 1def6bf..522fda2 100644
--- a/docs/generic.css
+++ b/docs/generic.css
@@ -4,7 +4,7 @@ body {
   padding: 0px;
   color: rgb(0,0,0);
   font-family: Verdana, Arial, Helvetica, sans-serif;
-  font-size: 80%;
+  font-size: smaller;
   background: #ffffff;
 }

diff --git a/docs/libvirt.css b/docs/libvirt.css
index 2bd9f8f..a3e3ee1 100644
--- a/docs/libvirt.css
+++ b/docs/libvirt.css
@@ -417,7 +417,7 @@ table.data tbody td.n {

 .api {
     font-family: "Ubuntu Monospace", "Consolas", "Lucida Console", monospace;
-    line-height: 175%;
+    line-height: 135%;
 }

 .api .type {
@@ -461,6 +461,4 @@ table.data tbody td.n {

 .api :link {
     text-decoration: none;
-    padding-bottom: 2px;
-    border-bottom: 1px dashed grey;
 }