Re: [PATCH 0/4] Style guide updates (round 2)

[Akira Yokosawa <akiyks@gmail.com>]

From 1073fa92397e86ec3ce8810c5068075ed6962301 Mon Sep 17 00:00:00 2001
From: Akira Yokosawa <akiyks@gmail.com>
Date: Wed, 23 Aug 2017 00:01:14 +0900
Subject: [PATCH 5/4] styleguide: Add example of partially colored rows

Also add explanation of interference of a \rowcolors{} command and
\cmidrule{} commands.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
Hi Paul,

This is a followup patch to the patch set "[PATCH 0/4] Style guide updates (round 2)"

On 2017/08/18 17:26:10 -0700, Paul E. McKenney wrote:
> On Sat, Aug 19, 2017 at 08:29:29AM +0900, Akira Yokosawa wrote:
[...]
>> I touched Tables 13.1 and C.1 in this patch set.
>> They are Tables D.5 and D.7.
> 
> The gap in the midrule for D.5 does help with the separation in a
> nice subtle way.  Table D.7 also looks very good to me.  But I will
> need some education on the "\rowcolors{5}{}{lightgray}".  Would this
> need to change if the number of rows changed?

I added comment to explain the use of \rowcolors and the choice of row count
to start coloring in the LaTeX source. And now "6" is specified in the
command. Please have a look.

[...]
>> Table 9.4 is reworked as Table D.8. As you see, I removed the "Category"
>> column for coloring of rows to work.
> 
> Ah, and added them as headers on each group.  If you left them in their
> own column the coloring of the Category column looks strange?

I added another example to partially color rows in the same table
with the "Category" column kept. This looks good. The "colortbl" package
mentioned there is loaded via "xcolor" package with the "table" option.
In doing this, I also simplified the source of Table D.8 a little.  

Note: This patch is relative to 4/4 of the previous patch set.

     Thanks, Akira
--
 appendix/styleguide/styleguide.tex | 137 ++++++++++++++++++++++++++++++++-----
 1 file changed, 118 insertions(+), 19 deletions(-)

diff --git a/appendix/styleguide/styleguide.tex b/appendix/styleguide/styleguide.tex
index cfa3234..c0636db 100644
--- a/appendix/styleguide/styleguide.tex
+++ b/appendix/styleguide/styleguide.tex
@@ -1027,12 +1027,12 @@ Two types of memory barrier are denoted by subscripts here.

 \vspace{5pt}\hfill
 {\footnotesize
-\rowcolors{1}{}{lightgray}
-  \begin{tabular}{cp{1.5in}}
+\rowcolors{1}{}{}
+  \begin{tabular}{lp{1.8in}}
         A	& Atomic counting \\
+        C	& Check combined with the atomic acquisition operation \\
         M\textsubscript{R}	& Memory barriers required only on release \\
         M\textsubscript{A}	& Memory barriers required on acquire \\
-        C	& Check combined with the atomic acquisition operation \\
   \end{tabular}
 }
 \caption{Reference Counting and Synchronization Mechanisms}
@@ -1050,7 +1050,18 @@ A ``figure'' environment might be a proper choice here.
 \small
 \centering
 \renewcommand*{\arraystretch}{1.2}
-\rowcolors{5}{}{lightgray} % 5 is chosen due to disturbance of row count by cmidrule
+\rowcolors{6}{}{lightgray}
+% "6" is chosen due to disturbance of row count by cmidrule.
+% The command definition is:
+%     \rowcolors{<row>}{<odd-row color>}{<even-row color>}
+% Here, <row> specifies the row count where the coloring start.
+% In this table, the "Seq = 0" row is the 3rd row, so a "3" would
+% be a right choice.
+% However, because of the \cmidrule{} commands used in the heading,
+% internal row count of the "Seq = 0" row becomes "6".
+% This is why the 3rd row has the background color of <even-row color>.
+%
+% \cline of plain LaTeX also interferes the row count.
 \begin{tabular}{rclcccccc}
 	\toprule
 	& & & \multicolumn{4}{c}{CPU Cache} & \multicolumn{2}{c}{Memory} \\
@@ -1078,10 +1089,20 @@ is a tweaked version of
 Table~\ref{tab:defer:RCU Publish-Subscribe and Version Maintenance APIs}.
 Here, the ``Category'' column in the original is removed
 and the categories are indicated in rows of bold-face font
-just below the mid-rules.
+just below the mid-rules. This change makes it easier for
+\verb|\rowcolors{}| command of ``xcolor'' package to work
+properly.
+
+Table~\ref{tab:app:styleguide:RCU Publish-Subscribe and Version Maintenance APIs (colortbl)}
+is another example which keeps original columns and colors rows only where
+a category has multiple rows. This is done by combining \verb|\rowcolors{}|
+of ``xcolor'' and \verb|\cellcolor{}| commands of the ``colortbl''
+package (\verb|\cellcolor{}| overrides \verb|\rowcolors{}|).
+
+For consistent looks, the latter layout might be our choice.

 \begin{table*}[tbh]
-\rowcolors{2}{}{lightgray}
+\rowcolors{2}{}{blue!15}
 \renewcommand*{\arraystretch}{1.1}
 \footnotesize
 \centering
@@ -1090,64 +1111,142 @@ just below the mid-rules.
 	Primitives &
 		Availability &
 			Overhead \\
-\midrule\rowcolor{blue!15}
-	\multicolumn{3}{l}{\bfseries List traversal} \\ \hiderowcolors
+\midrule
+	\multicolumn{3}{l}{\bfseries List traversal} \\
 	\tco{list_for_each_entry_rcu()} &
 		2.5.59 &
 			Simple instructions (memory barrier on Alpha) \\
-\midrule\rowcolor{blue!15}
-	\multicolumn{3}{l}{\bfseries List update} \\ \showrowcolors
+\midrule
+	\multicolumn{3}{l}{\bfseries List update} \\
 	\tco{list_add_rcu()} &
 		2.5.44 &
 			Memory barrier \\
+	\rowcolor{lightgray}\tco{list_add_tail_rcu()} &
+		2.5.44 &
+			Memory barrier \\
+	\tco{list_del_rcu()} &
+		2.5.44 &
+			Simple instructions \\
+	\rowcolor{lightgray}\tco{list_replace_rcu()} &
+		2.6.9 &
+			Memory barrier \\
+	\tco{list_splice_init_rcu()} &
+		2.6.21 &
+			Grace-period latency \\
+\midrule
+	\multicolumn{3}{l}{\bfseries Hlist traversal} \\
+	\tco{hlist_for_each_entry_rcu()} &
+		2.6.8 &
+			Simple instructions (memory barrier on Alpha) \\
+\midrule
+	\multicolumn{3}{l}{\bfseries Hlist update} \\
+	\tco{hlist_add_after_rcu()} &
+		2.6.14 &
+			Memory barrier \\
+	\rowcolor{lightgray}\tco{hlist_add_before_rcu()} &
+		2.6.14 &
+			Memory barrier \\
+	\tco{hlist_add_head_rcu()} &
+		2.5.64 &
+			Memory barrier \\
+	\rowcolor{lightgray}\tco{hlist_del_rcu()} &
+		2.5.64 &
+			Simple instructions \\
+	\tco{hlist_replace_rcu()} &
+		2.6.15 &
+			Memory barrier \\
+\midrule
+	\multicolumn{3}{l}{\bfseries Pointer traversal} \\
+	\tco{rcu_dereference()} &
+		2.6.9 &
+			Simple instructions (memory barrier on Alpha) \\
+\midrule
+	\multicolumn{3}{l}{\bfseries Pointer update} \\
+	\tco{rcu_assign_pointer()} &
+		2.6.10 &
+			Memory barrier \\
+\bottomrule
+\end{tabular}
+\caption{RCU Publish-Subscribe and Version Maintenance APIs}
+\label{tab:app:styleguide:RCU Publish-Subscribe and Version Maintenance APIs}
+\end{table*}
+
+\begin{table*}[tbhp]
+\renewcommand*{\arraystretch}{1.2}
+\rowcolors{3}{lightgray}{}
+\footnotesize
+\centering
+\begin{tabular}{lllp{1.2in}}\toprule
+Category &
+	Primitives &
+		Availability &
+			Overhead \\
+\midrule
+List traversal &
+	\tco{list_for_each_entry_rcu()} &
+		2.5.59 &
+			Simple instructions (memory barrier on Alpha) \\
+\midrule
+\cellcolor{white}List update &
+	\tco{list_add_rcu()} &
+		2.5.44 &
+			Memory barrier \\
+&
 	\tco{list_add_tail_rcu()} &
 		2.5.44 &
 			Memory barrier \\
+\cellcolor{white} &
 	\tco{list_del_rcu()} &
 		2.5.44 &
 			Simple instructions \\
+&
 	\tco{list_replace_rcu()} &
 		2.6.9 &
 			Memory barrier \\
+\cellcolor{white} &
 	\tco{list_splice_init_rcu()} &
 		2.6.21 &
 			Grace-period latency \\
-\midrule\rowcolor{blue!15}
-	\multicolumn{3}{l}{\bfseries Hlist traversal} \\ \hiderowcolors
+\midrule
+Hlist traversal &
 	\tco{hlist_for_each_entry_rcu()} &
 		2.6.8 &
 			Simple instructions (memory barrier on Alpha) \\
-\midrule\rowcolor{blue!15}
-	\multicolumn{3}{l}{\bfseries Hlist update} \\ \showrowcolors
+\midrule
+\cellcolor{white}Hlist update &
 	\tco{hlist_add_after_rcu()} &
 		2.6.14 &
 			Memory barrier \\
+&
 	\tco{hlist_add_before_rcu()} &
 		2.6.14 &
 			Memory barrier \\
+\cellcolor{white} &
 	\tco{hlist_add_head_rcu()} &
 		2.5.64 &
 			Memory barrier \\
+&
 	\tco{hlist_del_rcu()} &
 		2.5.64 &
 			Simple instructions \\
+\cellcolor{white} &
 	\tco{hlist_replace_rcu()} &
 		2.6.15 &
 			Memory barrier \\
-\midrule\rowcolor{blue!15}
-	\multicolumn{3}{l}{\bfseries Pointer traversal} \\ \hiderowcolors
+\midrule\hiderowcolors
+Pointer traversal &
 	\tco{rcu_dereference()} &
 		2.6.9 &
 			Simple instructions (memory barrier on Alpha) \\
-\midrule\rowcolor{blue!15}
-	\multicolumn{3}{l}{\bfseries Pointer update} \\ \hiderowcolors
+\midrule
+Pointer update &
 	\tco{rcu_assign_pointer()} &
 		2.6.10 &
 			Memory barrier \\
 \bottomrule
 \end{tabular}
 \caption{RCU Publish-Subscribe and Version Maintenance APIs}
-\label{tab:app:styleguide:RCU Publish-Subscribe and Version Maintenance APIs}
+\label{tab:app:styleguide:RCU Publish-Subscribe and Version Maintenance APIs (colortbl)}
 \end{table*}

 Table~\ref{tab:advsync:Memory Misordering: Store-Buffering Sequence of Events}
-- 
2.7.4