Message-ID: <20201207123406.3863d221@coco.lan>
Date:   Mon, 7 Dec 2020 12:34:06 +0100
From:   Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To:     Jonathan Corbet <corbet@....net>
Cc:     Linux Doc Mailing List <linux-doc@...r.kernel.org>,
        linux-kernel@...r.kernel.org
Subject: Re: [PATCH v4 0/3] improve get_feat.pl output when all features are
 displayed

Em Mon, 7 Dec 2020 10:33:40 +0100
Mauro Carvalho Chehab <mchehab+huawei@...nel.org> escreveu:

> Em Sat, 5 Dec 2020 17:03:50 +0100
> Mauro Carvalho Chehab <mchehab+huawei@...nel.org> escreveu:
> 
> > Em Fri, 4 Dec 2020 14:48:43 -0700
> > Jonathan Corbet <corbet@....net> escreveu:
> >   
> > > On Fri,  4 Dec 2020 16:32:27 +0100
> > > Mauro Carvalho Chehab <mchehab+huawei@...nel.org> wrote:
> > >     
> > > > As requested, those patches improve the output of the script, when all features
> > > > are displayed.
> > > > 
> > > > The first patch was already posted as-is at v3.
> > > > 
> > > > Patch 2 is optional. IMO, it makes more sense for the admin guide to show
> > > > the architectures where the features are OK, then TODO, and finally the
> > > > ones that are incompatible with the features. I already sent it together
> > > > with a comment.
> > > > 
> > > > Patch 3 is new: it tries to reduce the width of the table, in order for it
> > > > to better fit on a terminal. With the patch, the number of columns were
> > > > reduced, in order to better fit at console output. Before the patch, the
> > > > output takes 281 lines with 158 columns (total size: 38.9 kB). 
> > > > After the patch, displaying all features require 439 lines and 92 columns
> > > > (total size: 37.6 kB).      
> > > 
> > > OK, this is much improved, thanks; applied.    
> > 
> > Anytime.
> >   
> > > 
> > > The one last thing I would do is stick "valign=top" on all the table
> > > entries, but we can leave the shed a different color for now :)    
> > 
> > I actually prefer myself valign=center on tables ;-)
> > 
> > In any case, a change like that should be simple to do.
> > 
> > either adjust:
> > 
> > 	Documentation/sphinx-static/theme_overrides.css
> > 
> > to change it globally for all tables or create a "table_valign_top" CSS
> > class on it, changing the script to add:
> > 
> > 	.. cssclass:: table_valign_top
> > 
> > Before each table.  
> 
> Btw, if you want to play with changing the table alignment, the
> enclosed patch changes the alignment to use valign=top for all
> tables (and not only for the feature ones).
> 
> Don't forget to remove the old theme before testing the
> patch with:
> 
> 	$ rm $(find Documentation/output/ -name theme_overrides.css)
> 
> As sphinx (at least version 2.4.4) only writes it if the file
> doesn't exist.

Btw, if you want to vertically align just some tables - like the
ones produced by get_feat.pl, the enclosed patch should do the
job.

-

PS.: It seems worth mentioning here, as others may find issues when
trying to customize the Kernel-specific CSS styles.

It took me a while to find a way for the style to be properly
applied, due to CSS Specificity[1].

[1] I don't usually deal with CSS style sheets :-)
    So, had to do some research and lots of tests.

    Those are two useful references about that:
	https://stackoverflow.com/questions/12258596/class-overrule-when-two-classes-assigned-to-one-div
	https://www.smashingmagazine.com/2007/07/css-specificity-things-you-should-know/
	
The thing is that the tables (tested with Sphinx 2.4.4) are created
with multiple classes:

	<table class="top-aligned docutils align-default">

As the user-specified class (top-aligned) is the first one (instead of
the last one), it has less precedence than "docutils" or "align-default"
classes.

So, if one specifies at the CSS file just:

	.top-aligned {
		vertical-align: top;
		color: red;
	}

The table color will change to red as expected, but the vertical-align 
will be overridden by the other classes.

So, we need to place all classes there, in order to increase
the CSS Specificity:

	table.top-aligned.docutils.align-default td {
		vertical-align: top;
	}

Thanks,
Mauro

[PATCH] scripts: get_feat.pl: align tables vertically on top

In order to make the full features tables, align
them on the top.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>

diff --git a/Documentation/sphinx-static/theme_overrides.css b/Documentation/sphinx-static/theme_overrides.css
index 459ec5b29d68..7ccf69d005fc 100644
--- a/Documentation/sphinx-static/theme_overrides.css
+++ b/Documentation/sphinx-static/theme_overrides.css
@@ -42,6 +42,11 @@ p {
 	font-size: 100%;
 }
 
+/* use vertical alignment on tables */
+table.top-aligned.docutils.align-default td {
+	vertical-align: top;
+}
+
 /* Interim: Code-blocks with line nos - lines and line numbers don't line up.
  * see: https://github.com/rtfd/sphinx_rtd_theme/issues/419
  */
diff --git a/scripts/get_feat.pl b/scripts/get_feat.pl
index 457712355676..f5725803063e 100755
--- a/scripts/get_feat.pl
+++ b/scripts/get_feat.pl
@@ -410,6 +410,7 @@ sub output_matrix {
 			print "$title\n";
 			print "=" x length($title) . "\n\n";
 
+			print ".. cssclass:: top-aligned\n\n";
 
 			matrix_lines($desc_size, $status_size, 0);
 

Powered by blists - more mailing lists