Skip to contentSkip to conversation

Style guide updates (round 2)

PATCH In review Akira Yokosawa 2 participants 12 messages Aug 18, 2017 – Aug 22, 2017

lore
Share & tools
lore

Akira Yokosawa

author
#0 lore raw

cover Style guide updates (round 2)

From af290804fbb9868bb242c8ad6d889d46dfa9add1 Mon Sep 17 00:00:00 2001
From: Akira Yokosawa <[email protected]>
Date: Fri, 18 Aug 2017 23:53:45 +0900
Subject: [PATCH 0/4] Style guide updates (round 2)

Hi Paul,

Let me explain each patch in this set first.

Patch #1 is for compatibility to older LaTeX installation.

Patch #2 adds the tweaked tables described below.

Patch #3 converts "tabulary" tables to "tabularx". It involves manual width adjustment, but the end result is not so different, with the bonus of increased font size. This enables us to try dashed lines of arydshln package.

Patch #4 adds examples using dashed lines. They look not so appealing in the particular tables, but there might be cases they are useful. On Ubuntu Trusty, an additional package "texlive-humanities" is necessary.

Regarding your message On 2017/08/14 08:32:46 -0700:

Quoted 3 lines

Perhaps single-column tables with (say) three or fewer rows might look like D.3, and more complex ones like D.4? Really complicated tables might need more \hlines, shaded cells, or some such.

There are few tables with three or fewer rows. So, most tables should look like D.4 (in the previous round). It is now Table D.3

Coloring of alternate rows could not be applied simply to Table 3.1 because of the \textcolor{} tweaks. I used siunitx's "S" column specifier instead in Table D.4.

Quoted 6 lines
Quoted 5 lines

For the coloring, all I did was adding a command "\rowcolors{1}{}{lightgray}".
The (not so) hard part was to make the header row to be actually one row. I used parbox for the moment.
Please give a look when you have time.

Quoted 7 lines

That does seem eminently reasonable for that table.

Tables 5.1 and 5.2 have more "interesting" headers, with the "Reads" spanning two columns, each of which has a subcolumn header. One approach would be to apply the "Reads" to each subcolumn like you did for D.4. But this approach looks to me to be less applicable to Table 13.1. And Table C.1.

I touched Tables 13.1 and C.1 in this patch set. They are Tables D.5 and D.7.
D.6 is another version of Table 13.1 with proper legends.

I didn't touch Tables 5.1 nor 5.2 in this round, but they should be easy.

Quoted 3 lines

Table 9.4 is a bit more challenging, and 10.1 is similar, though more suitable for your parbox trick. Thoughts?

Table 9.4 is reworked as Table D.8. As you see, I removed the "Category" column for coloring of rows to work.

Table 9.1 requires a different approach (not tried yet).

Table 10.1 can be regarded as a figure drawn by tabular environment and is not suitable to booktabs' rules.
Tables 7.1 and C.5 don't look suitable to booktabs' rules either. I'll keep them as is for the moment.

Quoted 4 lines

Table 14.1 might need to keep its hlines, but what are your thoughts? A clear separation between the number on the left and the columns corresponding to each CPU seems important. Ditto 14.2.

Table 14.1 is reworked as Table D.9.
Gaps in the mid-rule can represent the separation done by vertical rules in the original one. I don't think hlines are necessary here either. Or using dashed hlines might be an option.

Quoted 2 lines

Thoughts on Tables 17.1 and 17.2? (The HTM comparison tables.)

I have not tried these large and complex tables yet.
The "tabu" package might improve them. I'm kind of scared by the fancy looks of tabu document, though... There can be other options. Please give me a while.

Quoted 6 lines

But most of the rest of the tables look like they would do just fine as either D.3 (for the single-column ones with three or fewer columns) or D.4 (for the rest).

But what are your impressions?

So the other simple tables can have the rows colored.

Let me know what you think of the added tables.

Thanks, Akira
--
Akira Yokosawa (4):
Use 'fixltx2e' package
styleguide: Add more table experiments Get rid of 'tabulary' package
styleguide: Add table examples with dashed lines

 FAQ-BUILD.txt                      |   5 +-
 SMPdesign/SMPdesign.tex            |   8 +-
 appendix/styleguide/styleguide.tex | 557 +++++++++++++++++++++++++++++--------
 defer/rcuapi.tex                   |  11 +-
 defer/whichtochoose.tex            |  10 +-
 perfbook.tex                       |   6 +-
 6 files changed, 462 insertions(+), 135 deletions(-)
Signature · 1 line
2.7.4
author
#1 lore raw

PATCH 1/4 Use 'fixltx2e' package

From 8dd783f1bcb1eb6ee24cd98596e8b9099b8c3251 Mon Sep 17 00:00:00 2001
From: Akira Yokosawa <[email protected]>
Date: Fri, 18 Aug 2017 07:51:04 +0900
Subject: [PATCH 1/4] Use 'fixltx2e' package

"fixltx2e" package had provided several fixes to LaTeX core. Those fixes were applied to LaTeX core in 2015 [1]. We need it to use "\textsubscript" in older LaTeX installation. In later versions of LaTeX, this package is no-op.

[1]: https://www.tug.org/texlive/doc/texlive-en/texlive-en.html#x1-820009.1.12

Signed-off-by Akira Yokosawa <[email protected]>
---
 perfbook.tex | 1 +
 1 file changed, 1 insertion(+)
perfbook.tex +1 -0
index 9f1644d..4590338 100644
@@ -17,6 +17,7 @@
 \UseMicrotypeSet[protrusion]{basicmath} % disable protrusion for tt fonts
 \usepackage{etoolbox}
 
+\usepackage{fixltx2e} % for \textsubscript, nop on Tex Live 2015 and later
 \usepackage{float}
 \floatstyle{ruled}
 \newfloat{listing}{tbhp}{lst}[chapter]
Signature · 1 line
2.7.4
author
#2 lore raw

PATCH 2/4 styleguide: Add more table experiments

In reply to Akira Yokosawa

From ed8efd5ad9c05e764a8084a56e88d5886f50c523 Mon Sep 17 00:00:00 2001
From: Akira Yokosawa <[email protected]>
Date: Wed, 16 Aug 2017 00:43:11 +0900
Subject: [PATCH 2/4] styleguide: Add more table experiments

Signed-off-by Akira Yokosawa <[email protected]>
---
 appendix/styleguide/styleguide.tex | 346 +++++++++++++++++++++++++++++++------
 1 file changed, 292 insertions(+), 54 deletions(-)
appendix/styleguide/styleguide.tex +292 -54
index 47251a1..31a83eb 100644
@@ -722,6 +722,20 @@ It should be regarded as a band-aid tweak.
 \subsubsection{Grouping Related Figures/Listings}
 \label{sec:app:styleguide:Grouping Related Figures/Listings}
 
+\begin{figure*}[tbhp]\centering
+\begin{minipage}[t][][t]{2.1in}
+\resizebox{2.1in}{!}{\includegraphics{cartoons/1kHz}}
+\caption{Timer Wheel at 1\,kHz}
+\label{fig:app:styleguide:Timer Wheel at 1kHz}
+\end{minipage}
+\qquad
+\begin{minipage}[t][][t]{2.3in}
+\resizebox{2.3in}{!}{\includegraphics{cartoons/100kHz}}
+\caption{Timer Wheel at 100\,kHz}
+\label{fig:app:styleguide:Timer Wheel at 100kHz}
+\end{minipage}
+\end{figure*}
+
 To prevent a pair of closely related figures or listings
 from being placed in different pages, it is desirable to group
 them into a single floating object.

@@ -739,20 +753,6 @@ as shown in
 Figures~\ref{fig:app:styleguide:Timer Wheel at 1kHz}
 and~\ref{fig:app:styleguide:Timer Wheel at 100kHz}.
 
-\begin{figure*}[tbhp]\centering
-\begin{minipage}[t][][t]{2.1in}
-\resizebox{2.1in}{!}{\includegraphics{cartoons/1kHz}}
-\caption{Timer Wheel at 1\,kHz}
-\label{fig:app:styleguide:Timer Wheel at 1kHz}
-\end{minipage}
-\qquad
-\begin{minipage}[t][][t]{2.3in}
-\resizebox{2.3in}{!}{\includegraphics{cartoons/100kHz}}
-\caption{Timer Wheel at 100\,kHz}
-\label{fig:app:styleguide:Timer Wheel at 100kHz}
-\end{minipage}
-\end{figure*}
-
 By using subfig package,
 Listings~\ref{lst:advsync:Message-Passing Litmus Test}
 and~\ref{lst:advsync:Enforcing Order of Message-Passing Litmus Test}

@@ -867,53 +867,17 @@ look ugly.\footnote{
 Vertical lines should be avoided and horizontal lines should be
 used sparingly, especially in tables of simple structure.
 
-For example,
-Table~\ref{tab:cpu:Performance of Synchronization Mechanisms on 4-CPU 1.8GHz AMD Opteron 844 System}
-can be tweaked by the help of ``booktabs'' package as is shown in
-Table~\ref{tab:app:styleguide:Performance of Synchronization Mechanisms of 4-CPU 1.8GHz AMD Opteron 844 System},
-with the caption at the top.
-
 \floatstyle{plaintop}
 \restylefloat{table}
 \captionsetup[table]{position=top,hangindent=30pt}
 \renewcommand*{\abovetopsep}{-7pt}
+\definecolor{lightgray}{gray}{0.9}
 
-\begin{table}[htb]
-\renewcommand*{\arraystretch}{1.2}\centering\small
-\begin{tabular}{@{}lrr@{}}\toprule
-
-	Operation		& Cost (ns) 	& \parbox[b]{.7in}{\raggedleft Ratio\par (cost/clock)} \\
-	\midrule
-	Clock period		&           0.6	&           1.0 \\
-	Best-case CAS		&          37.9	&          63.2 \\
-	Best-case lock		&          65.6	&         109.3 \\
-	Single cache miss	&         139.5	&         232.5 \\
-	CAS cache miss		&         306.0	&         510.0 \\
-	Comms Fabric		&       5,000\textcolor{white}{.0}
-						&       8,330\textcolor{white}{.0}
-								\\
-	Global Comms		& 195,000,000\textcolor{white}{.0}
-						& 325,000,000\textcolor{white}{.0} \\
-\bottomrule
-\end{tabular}
-\caption{Performance of Synchronization Mechanisms of 4-CPU 1.8\,GHz AMD Opteron 844 System}
-\label{tab:app:styleguide:Performance of Synchronization Mechanisms of 4-CPU 1.8GHz AMD Opteron 844 System}
-\end{table}
-
-Note that ruled lines of booktabs can not be mixed with
-vertical lines in a table.\footnote{
-  There is another package named ``arydshln'' which provides dashed lines
-  to be used in tables.
-  Unfortunately, it conflicts with the tabulary package and prevents us
-  from experimenting it for the moment.
-}
-
-Another option is to color rows alternately by using the feature of xcolor
-package. For example,
+For example,
 Table~\ref{tab:future:Refrigeration Power Consumption}
 can be tweaked as shown in
-Table~\ref{tab:app:styleguide:Refrigeration Power Consumption}.
-\definecolor{lightgray}{gray}{0.9}
+Table~\ref{tab:app:styleguide:Refrigeration Power Consumption}
+with the help of ``booktabs'' and ``xcolor'' packages.
 
 \begin{table}[htbp]
 \rowcolors{1}{}{lightgray}

@@ -948,6 +912,280 @@ IBM~Q	& $0.015$
 \label{tab:app:styleguide:Refrigeration Power Consumption}
 \end{table}
 
+Note that ruled lines of booktabs can not be mixed with
+vertical lines in a table.\footnote{
+  There is another package named ``arydshln'' which provides dashed lines
+  to be used in tables.
+  Unfortunately, it conflicts with the tabulary package and prevents us
+  from experimenting it for the moment.
+}
+
+\vfil
+\pagebreak % to permit wide tables to be printed
+
+\subsubsection{Table Layout Experiment}
+\label{sec:app:styleguide:Table Layout Experiment}
+
+To see how far we can go without vertical rules in tables,
+several experiments using booktabs and xcolors are presented
+in this section.
+
+Table~\ref{tab:cpu:Performance of Synchronization Mechanisms on 4-CPU 1.8GHz AMD Opteron 844 System}
+can be tweaked as is shown in
+Table~\ref{tab:app:styleguide:Performance of Synchronization Mechanisms of 4-CPU 1.8GHz AMD Opteron 844 System}.
+In this table, original tabular source contains tweaks with
+\verb|\textcolor{}| commands. They are removed by using ``S'' column
+specifiers provided by the ``siunitx'' package.
+
+\begin{table}[htb]
+\rowcolors{1}{}{lightgray}
+\renewcommand*{\arraystretch}{1.1}
+\sisetup{group-minimum-digits=4,group-separator={,}}
+\centering\small
+\begin{tabular}
+  {
+    l
+    S[table-format = 9.1]
+    S[table-format = 9.1]
+  }
+	\toprule
+	Operation		& \multicolumn{1}{r}{Cost (ns)}
+			& {\parbox[b]{.7in}{\raggedleft Ratio\\(cost/clock)}} \\
+	\midrule
+	Clock period		&           0.6	&           1.0 \\
+	Best-case CAS		&          37.9	&          63.2 \\
+	Best-case lock		&          65.6	&         109.3 \\
+	Single cache miss	&         139.5	&         232.5 \\
+	CAS cache miss		&         306.0	&         510.0 \\
+	Comms Fabric		&       5 000	&       8 330	\\
+	Global Comms		& 195 000 000	& 325 000 000   \\
+	\bottomrule
+\end{tabular}
+\caption{Performance of Synchronization Mechanisms of 4-CPU 1.8\,GHz AMD Opteron 844 System}
+\label{tab:app:styleguide:Performance of Synchronization Mechanisms of 4-CPU 1.8GHz AMD Opteron 844 System}
+\end{table}
+
+Table~\ref{tab:app:styleguide:Reference Counting and Synchronization Mechanisms}
+is a tweaked version of
+Table~\ref{tab:together:Reference Counting and Synchronization Mechanisms},
+which has more complex header than the tables experimented so far.
+
+\begin{table}[htbp]
+\small
+\centering
+\renewcommand*{\arraystretch}{1.25}
+\rowcolors{3}{}{lightgray}
+\begin{tabular}{lccc}
+	\toprule
+	& \multicolumn{3}{c}{Release Synchronization} \\
+	\cmidrule(l){2-4}
+	\parbox[c]{.8in}{Acquisition\\Synchronization}
+			& Locking
+				& \parbox[c]{.5in}{Reference\\Counting}
+				        & RCU \\
+	\cmidrule{1-1} \cmidrule(l){2-4}
+	Locking		& $-$	& CAM	& CA  \\
+	\parbox[c][6ex]{.8in}{Reference\\Counting}
+			& A	& AM	& A   \\
+	RCU		& CA	& MCA	& CA  \\
+	\bottomrule
+\end{tabular}
+\caption{Reference Counting and Synchronization Mechanisms}
+\label{tab:app:styleguide:Reference Counting and Synchronization Mechanisms}
+\end{table}
+
+In
+Table~\ref{tab:app:styleguide:Reference Counting and Synchronization Mechanisms},
+the gap in the mid-rule corresponds to the distinction
+which is represented by double vertical rules in
+Table~\ref{tab:together:Reference Counting and Synchronization Mechanisms}.
+
+However, it makes no sense when it is separated from the explanation near~%
+Table~\ref{tab:together:Reference Counting and Synchronization Mechanisms}
+due to the lack of explanation of abbreviations used in the matrix.
+An example with proper legends is shown in
+Table~\ref{tab:app:styleguide:Reference Counting and Synchronization Mechanisms (Legends)}.
+Two types of memory barrier are denoted by subscripts here.
+
+\begin{table}[htbp]
+\small
+\centering
+\renewcommand*{\arraystretch}{1.25}
+\rowcolors{3}{}{lightgray}
+\begin{tabular}{lccc}
+	\toprule
+	& \multicolumn{3}{c}{Release Synchronization} \\
+	\cmidrule(l){2-4}
+	\parbox[c]{.8in}{Acquisition\\Synchronization}
+			& Locking
+				& \parbox[c]{.5in}{Reference\\Counting}
+				        & RCU \\
+	\cmidrule{1-1} \cmidrule(l){2-4}
+	Locking		& $-$	& CAM\textsubscript{R}	& CA  \\
+	\parbox[c][6ex]{.8in}{Reference\\Counting}
+			& A	& AM\textsubscript{R}	& A   \\
+	RCU		& CA	& M\textsubscript{A}CA	& CA  \\
+	\bottomrule
+\end{tabular}
+
+\vspace{5pt}\hfill
+{\footnotesize
+\rowcolors{1}{}{lightgray}
+  \begin{tabular}{cp{1.5in}}
+        A	& Atomic counting \\
+        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}
+\label{tab:app:styleguide:Reference Counting and Synchronization Mechanisms (Legends)}
+\end{table}
+
+Table~\ref{tab:app:whymb:Cache Coherence Example}
+can be tweaked as in
+Table~\ref{tab:app:styleguide:Cache Coherence Example}
+in a similar manner.
+It is not a ``table'' in the narrow sense, rather a sequence diagram.
+A ``figure'' environment might be a proper choice here.
+
+\begin{table*}[htb]
+\small
+\centering
+\renewcommand*{\arraystretch}{1.2}
+\rowcolors{5}{}{lightgray} % 5 is chosen due to disturbance of row count by cmidrule
+\begin{tabular}{rclcccccc}
+	\toprule
+	& & & \multicolumn{4}{c}{CPU Cache} & \multicolumn{2}{c}{Memory} \\
+	\cmidrule(lr){4-7} \cmidrule(l){8-9}
+	Sequence \# & CPU \# & Operation & 0 & 1 & 2 & 3 & 0 & 8 \\
+	\cmidrule(r){1-3} \cmidrule(lr){4-7} \cmidrule(l){8-9}
+%	Seq CPU Operation	------------- CPU -------------   - Memory -
+%				   0	   1	   2	   3	    0   8
+	0 &   & Initial State	& $-$/I & $-$/I & $-$/I & $-$/I   & V & V \\
+	1 & 0 & Load		& 0/S &   $-$/I & $-$/I & $-$/I   & V & V \\
+	2 & 3 & Load		& 0/S &   $-$/I & $-$/I & 0/S     & V & V \\
+	3 & 0 & Invalidation	& 8/S &   $-$/I & $-$/I & 0/S     & V & V \\
+	4 & 2 & RMW		& 8/S &   $-$/I & 0/E &   $-$/I   & V & V \\
+	5 & 2 & Store		& 8/S &   $-$/I & 0/M &   $-$/I   & I & V \\
+	6 & 1 & Atomic Inc	& 8/S &   0/M &   $-$/I & $-$/I   & I & V \\
+	7 & 1 & Writeback	& 8/S &   8/S &   $-$/I & $-$/I   & V & V \\
+	\bottomrule
+\end{tabular}
+\caption{Cache Coherence Example}
+\label{tab:app:styleguide:Cache Coherence Example}
+\end{table*}
+
+Table~\ref{tab:app:styleguide:RCU Publish-Subscribe and Version Maintenance APIs}
+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.
+
+\begin{table*}[htb]
+\rowcolors{2}{}{lightgray}
+\renewcommand*{\arraystretch}{1.1}
+\footnotesize
+\centering
+\begin{tabular}{lll}
+\toprule
+	Primitives &
+		Availability &
+			Overhead \\
+\midrule\rowcolor{blue!15}
+	\multicolumn{3}{l}{\bfseries List traversal} \\ \hiderowcolors
+	\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
+	\tco{list_add_rcu()} &
+		2.5.44 &
+			Memory barrier \\
+	\tco{list_add_tail_rcu()} &
+		2.5.44 &
+			Memory barrier \\
+	\tco{list_del_rcu()} &
+		2.5.44 &
+			Simple instructions \\
+	\tco{list_replace_rcu()} &
+		2.6.9 &
+			Memory barrier \\
+	\tco{list_splice_init_rcu()} &
+		2.6.21 &
+			Grace-period latency \\
+\midrule\rowcolor{blue!15}
+	\multicolumn{3}{l}{\bfseries Hlist traversal} \\ \hiderowcolors
+	\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
+	\tco{hlist_add_after_rcu()} &
+		2.6.14 &
+			Memory barrier \\
+	\tco{hlist_add_before_rcu()} &
+		2.6.14 &
+			Memory barrier \\
+	\tco{hlist_add_head_rcu()} &
+		2.5.64 &
+			Memory barrier \\
+	\tco{hlist_del_rcu()} &
+		2.5.64 &
+			Simple instructions \\
+	\tco{hlist_replace_rcu()} &
+		2.6.15 &
+			Memory barrier \\
+\midrule\rowcolor{blue!15}
+	\multicolumn{3}{l}{\bfseries Pointer traversal} \\ \hiderowcolors
+	\tco{rcu_dereference()} &
+		2.6.9 &
+			Simple instructions (memory barrier on Alpha) \\
+\midrule\rowcolor{blue!15}
+	\multicolumn{3}{l}{\bfseries Pointer update} \\ \hiderowcolors
+	\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*}
+
+Table~\ref{tab:advsync:Memory Misordering: Store-Buffering Sequence of Events}
+can be tweaked as shown in
+Table~\ref{tab:app:styleguide:Memory Misordering: Store-Buffering Sequence of Events}.
+It is also a sequence diagram drawn as a tabular object.
+
+\begin{table*}[htb]
+\rowcolors{6}{}{lightgray}
+\renewcommand*{\arraystretch}{1.1}
+\small
+\centering\OneColumnHSpace{-0.1in}
+\begin{tabular}{rllllll}
+	\toprule
+	& \multicolumn{3}{c}{CPU 0} & \multicolumn{3}{c}{CPU 1} \\
+	\cmidrule(l){2-4} \cmidrule(l){5-7}
+	& Instruction & Store Buffer & Cache &
+		Instruction & Store Buffer & Cache \\
+	\cmidrule{1-1} \cmidrule(l){2-4} \cmidrule(l){5-7}
+	1 & (Initial state) & & \tco{x1==0} &
+		(Initial state) & & \tco{x0==0} \\
+	2 & \tco{x0 = 2;} & \tco{x0==2} & \tco{x1==0} &
+		\tco{x1 = 2;} & \tco{x1==2} & \tco{x0==0} \\
+	3 & \tco{r2 = x1;} (0) & \tco{x0==2} & \tco{x1==0} &
+		\tco{r2 = x0;} (0) & \tco{x1==2} & \tco{x0==0} \\
+	4 & (Read-invalidate) & \tco{x0==2} & \tco{x0==0} &
+		(Read-invalidate) & \tco{x1==2} & \tco{x1==0} \\
+	5 & (Finish store) & & \tco{x0==2} &
+		(Finish store) & & \tco{x1==2} \\
+	\bottomrule
+\end{tabular}
+\caption{Memory Misordering: Store-Buffering Sequence of Events}
+\label{tab:app:styleguide:Memory Misordering: Store-Buffering Sequence of Events}
+\end{table*}
+
 \floatstyle{plain}
 \restylefloat{table}
 \captionsetup[table]{position=bottom,hangindent=0pt}
Signature · 1 line
2.7.4
author
#3 lore raw

PATCH 3/4 Get rid of 'tabulary' package

In reply to Akira Yokosawa

From fe6cf8fa360b8d437d9dedeb626a1f841d44e127 Mon Sep 17 00:00:00 2001
From: Akira Yokosawa <[email protected]>
Date: Thu, 17 Aug 2017 19:39:04 +0900
Subject: [PATCH 3/4] Get rid of 'tabulary' package

Use "tabularx" package instead.
This change gives us the chance to try dashed rules of "arydshln" package.
Also increase the font size to footnotesize for readability.

Signed-off-by Akira Yokosawa <[email protected]>
---
 SMPdesign/SMPdesign.tex            |  8 +++++---
 appendix/styleguide/styleguide.tex |  4 +---
 defer/rcuapi.tex                   | 11 ++++++++---
 defer/whichtochoose.tex            | 10 +++++++---
 perfbook.tex                       |  4 ++--
 5 files changed, 23 insertions(+), 14 deletions(-)
SMPdesign/SMPdesign.tex +5 -3
index 842341f..1936d27 100644
@@ -1346,16 +1346,18 @@ as shown in
 Table~\ref{fig:app:questions:Schematic of Real-World Parallel Allocator}.
 
 \begin{table}[tbp]
-\scriptsize
+\footnotesize
 \centering
-\begin{tabulary}{0.95\columnwidth}{l|l|L}
+\renewcommand*{\arraystretch}{1.25}
+\setlength\tabcolsep{4pt}
+\begin{tabularx}{\columnwidth}{l|l|>{\raggedright\arraybackslash}X}
 Level	& Locking & Purpose \\
 \hline
 Per-thread pool	  & Data ownership & High-speed allocation \\
 Global block pool & Data locking   & Distributing blocks among threads \\
 Coalescing	  & Data locking   & Combining blocks into pages \\
 System memory	  & Code locking   & Memory from/to system \\
-\end{tabulary}
+\end{tabularx}
 \caption{Schematic of Real-World Parallel Allocator}
 \label{fig:app:questions:Schematic of Real-World Parallel Allocator}
 \end{table}
appendix/styleguide/styleguide.tex +1 -3
index 31a83eb..40dfa74 100644
@@ -448,7 +448,7 @@ a white space, or an operator \tco{->}.
 Although \verb|\co{}| command is convenient for inlining within text,
 it is fragile because of its capability of line break.
 When it is used inside a ``tabular'' environment or its derivative
-such as ``tabulary'', it confuses column width
+such as ``tabularx'', it confuses column width
 estimation of those environments.
 Furthermore, \verb|\co{}| can not be safely used in section headings nor
 description headings.

@@ -916,8 +916,6 @@ Note that ruled lines of booktabs can not be mixed with
 vertical lines in a table.\footnote{
   There is another package named ``arydshln'' which provides dashed lines
   to be used in tables.
-  Unfortunately, it conflicts with the tabulary package and prevents us
-  from experimenting it for the moment.
 }
 
 \vfil
defer/rcuapi.tex +8 -3
index f2aa3ff..158ebff 100644
@@ -18,8 +18,13 @@ presents concluding remarks.
 
 \begin{sidewaystable*}[htbp]
 \centering
-\scriptsize\tymin=1.0in
-\begin{tabulary}{7.6in}{L|L|L|L|L|L}
+\footnotesize
+\begin{tabularx}{7.9in}{>{\raggedright\arraybackslash}p{1.08in}|
+    >{\raggedright\arraybackslash}X|
+    >{\raggedright\arraybackslash}X|
+    >{\raggedright\arraybackslash}X|
+    >{\raggedright\arraybackslash}X|
+    >{\raggedright\arraybackslash}p{1.22in}}
 Attribute &
     RCU Classic &
 	RCU BH &

@@ -118,7 +123,7 @@ Non-\tco{PREEMPT_RT} implementation &
 	    Forced Schedule on all CPUs &
 	        Realtime RCU &
 		    SRCU \\
-\end{tabulary}
+\end{tabularx}
 \caption{RCU Wait-to-Finish APIs}
 \label{tab:defer:RCU Wait-to-Finish APIs}
 \end{sidewaystable*}
defer/whichtochoose.tex +7 -3
index edbdcb9..0b716ef 100644
@@ -6,8 +6,12 @@
 
 \begin{table*}
 \footnotesize
-\centering\tymin=0.4in\tymax=2in\OneColumnHSpace{-.3in}
-\begin{tabulary}{5.3in}{L||L|L|L|L}
+\centering\OneColumnHSpace{-.3in}
+\begin{tabularx}{5.3in}{>{\raggedright\arraybackslash}p{1.1in}||
+    >{\raggedright\arraybackslash}p{1.2in}|
+    >{\raggedright\arraybackslash}X|
+    >{\raggedright\arraybackslash}X|
+    >{\raggedright\arraybackslash}p{.9in}}
 
 		& Reference Counting
 			& Hazard Pointers

@@ -83,7 +87,7 @@
 			& 79
 				& 79
 					& 73 \\
-\end{tabulary}
+\end{tabularx}
 \caption{Which Deferred Technique to Choose?}
 \label{tab:defer:Which Deferred Technique to Choose?}
 \end{table*}
perfbook.tex +2 -2
index 4590338..3cfc4fd 100644
@@ -45,7 +45,7 @@
 \usepackage{gensymb} % symbols for both text and math modes such as \degree and \micro
 \usepackage{verbatimbox}[2014/01/30] % for centering verbatim listing in figure environment
 \usepackage[bottom]{footmisc} % place footnotes under floating figures/tables
-\usepackage{tabulary}
+\usepackage{tabularx}
 \usepackage[hyphens]{url}
 \usepackage[bookmarks=true,bookmarksnumbered=true,pdfborder={0 0 0}]{hyperref}
 \usepackage{footnotebackref} % to enable cross-ref of footnote

@@ -98,7 +98,7 @@
 \AtBeginEnvironment{verbbox}{\renewcommand{\ttdefault}{lmtt}}
 \AtBeginEnvironment{table}{\renewcommand{\ttdefault}{lmtt}}
 \AtBeginEnvironment{tabular}{\renewcommand{\ttdefault}{lmtt}}
-\AtBeginEnvironment{tabulary}{\renewcommand{\ttdefault}{lmtt}}
+\AtBeginEnvironment{tabularx}{\renewcommand{\ttdefault}{lmtt}}
 \AtBeginEnvironment{minipage}{\renewcommand{\ttdefault}{lmtt}}
 \AtBeginEnvironment{listing}{\renewcommand{\ttdefault}{lmtt}}
 }{}
Signature · 1 line
2.7.4
author
#4 lore raw

PATCH 4/4 styleguide: Add table examples with dashed lines

In reply to Akira Yokosawa

From af290804fbb9868bb242c8ad6d889d46dfa9add1 Mon Sep 17 00:00:00 2001
From: Akira Yokosawa <[email protected]>
Date: Fri, 18 Aug 2017 00:19:05 +0900
Subject: [PATCH 4/4] styleguide: Add table examples with dashed lines

These examples use dashed lines provided by "arydshln" package. On Ubuntu 14.04LTS, "arydshln" is contained in "texlive-humanities" package.

On Ubuntu 16.04LTS, it is covered in "texlive-latex-extra".

Also update FAQ-BUILD.txt accordingly and tweak position of floating objects.

Signed-off-by Akira Yokosawa <[email protected]>
---
 FAQ-BUILD.txt                      |   5 +-
 appendix/styleguide/styleguide.tex | 293 +++++++++++++++++++++++--------------
 perfbook.tex                       |   1 +
 3 files changed, 189 insertions(+), 110 deletions(-)
FAQ-BUILD.txt +4 -1
index 6b618b4..2bd37f1 100644
@@ -34,7 +34,7 @@
 	find it?
 
 	A.	The "pdflatex" package is a variant of Don Knuth's
-		digital typesetting program.  On Ubuntu Trusty and Xenial,
+		digital typesetting program.  On Ubuntu Xenial,
 		installing the following set of packages suffices:
 
 			texlive-latex-base texlive-latex-extra psutils

@@ -43,6 +43,9 @@
 			texlive-science texlive-bibtex-extra latex2html
 			gnuplot-x11 xfig inkscape graphviz fig2ps
 
+		On Ubuntu Trusty, in addition to the above, you need:
+			texlive-humanities
+
 		On Fedora 24, installing the following set of packages
 		suffices:
 			fig2ps graphviz texlive-epstopdf inkscape latex2html
appendix/styleguide/styleguide.tex +184 -109

374 lines not on this page · raw message

perfbook.tex +1 -0
index 3cfc4fd..17f38e8 100644
@@ -92,6 +92,7 @@
 
 \usepackage{bm} % for bold math mode fonts --- should be after math mode font choice
 \usepackage{booktabs}
+\usepackage{arydshln}
 
 \IfLmttForCode{
 \AtBeginEnvironment{verbatim}{\renewcommand{\ttdefault}{lmtt}}
Signature · 1 line
2.7.4
#5 lore raw
In reply to Akira Yokosawa
Quoted 22 lines · Akira Yokosawa
Quoted 1 line

From af290804fbb9868bb242c8ad6d889d46dfa9add1 Mon Sep 17 00:00:00 2001

From: Akira Yokosawa <[email protected]>
Date: Fri, 18 Aug 2017 23:53:45 +0900
Subject: [PATCH 0/4] Style guide updates (round 2)

Hi Paul,

Let me explain each patch in this set first.

Patch #1 is for compatibility to older LaTeX installation.

Patch #2 adds the tweaked tables described below.

Patch #3 converts "tabulary" tables to "tabularx". It involves manual width adjustment, but the end result is not so different, with the bonus of increased font size. This enables us to try dashed lines of arydshln package.

Patch #4 adds examples using dashed lines. They look not so appealing in the particular tables, but there might be cases they are useful. On Ubuntu Trusty, an additional package "texlive-humanities" is necessary.

Quoted 8 lines

Regarding your message On 2017/08/14 08:32:46 -0700:

Quoted 3 lines

Perhaps single-column tables with (say) three or fewer rows might look like D.3, and more complex ones like D.4? Really complicated tables might need more \hlines, shaded cells, or some such.

There are few tables with three or fewer rows. So, most tables should look like D.4 (in the previous round). It is now Table D.3

I should have said "three or fewer columns", apologies for my confusion!

Quoted 3 lines

Coloring of alternate rows could not be applied simply to Table 3.1 because of the \textcolor{} tweaks. I used siunitx's "S" column specifier instead in Table D.4.

But you did get the headers set up correctly despite their complexity, good show! The latex source for the body of the table certainly looks good. This table could probably be unruled as it only has three columns, but again, good demonstration of handling the headers.

Quoted 8 lines
Quoted 8 lines
Quoted 5 lines

For the coloring, all I did was adding a command "\rowcolors{1}{}{lightgray}".
The (not so) hard part was to make the header row to be actually one row. I used parbox for the moment.
Please give a look when you have time.

That does seem eminently reasonable for that table.

Quoted 8 lines
Quoted 5 lines

Tables 5.1 and 5.2 have more "interesting" headers, with the "Reads" spanning two columns, each of which has a subcolumn header. One approach would be to apply the "Reads" to each subcolumn like you did for D.4. But this approach looks to me to be less applicable to Table 13.1. And Table C.1.

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?

Quoted 1 line

D.6 is another version of Table 13.1 with proper legends.

I will have to think about the legend in this case. Nice in general, but a surprising fraction of the total space used by the table. Would it make sense to allow more than 1.5 inches for the definition so that it took less vertical space?

Quoted 9 lines

I didn't touch Tables 5.1 nor 5.2 in this round, but they should be easy.

Quoted 3 lines

Table 9.4 is a bit more challenging, and 10.1 is similar, though more suitable for your parbox trick. Thoughts?

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?

Quoted 8 lines

Table 9.1 requires a different approach (not tried yet).

Table 10.1 can be regarded as a figure drawn by tabular environment and is not suitable to booktabs' rules.
Tables 7.1 and C.5 don't look suitable to booktabs' rules either. I'll keep them as is for the moment.

Quoted 1 line
Quoted 8 lines
Quoted 3 lines

Table 14.1 might need to keep its hlines, but what are your thoughts? A clear separation between the number on the left and the columns corresponding to each CPU seems important. Ditto 14.2.

Table 14.1 is reworked as Table D.9.
Gaps in the mid-rule can represent the separation done by vertical rules in the original one. I don't think hlines are necessary here either. Or using dashed hlines might be an option.

No, D.9 looks quite good to me. Much better than the lined original, in fact.

Quoted 6 lines
Quoted 1 line

Thoughts on Tables 17.1 and 17.2? (The HTM comparison tables.)

I have not tried these large and complex tables yet.
The "tabu" package might improve them. I'm kind of scared by the fancy looks of tabu document, though... There can be other options. Please give me a while.

As far as I know, we are not under any schedule pressure on this item. ;-)

Quoted 9 lines
Quoted 5 lines

But most of the rest of the tables look like they would do just fine as either D.3 (for the single-column ones with three or fewer columns) or D.4 (for the rest).

But what are your impressions?

So the other simple tables can have the rows colored.

Let me know what you think of the added tables.

I did have to find an arydshln.sty. I ended up using this one:

http://ex.osaka-kyoiku.ac.jp/~fujii/dl/arydshln.sty

Is that a reasonable choice, or is there a better one elsewhere?

Thanx, Paul

Quoted 19 lines

Thanks, Akira
--
Akira Yokosawa (4):
Use 'fixltx2e' package
styleguide: Add more table experiments Get rid of 'tabulary' package
styleguide: Add table examples with dashed lines

 FAQ-BUILD.txt                      |   5 +-
 SMPdesign/SMPdesign.tex            |   8 +-
 appendix/styleguide/styleguide.tex | 557 +++++++++++++++++++++++++++++--------
 defer/rcuapi.tex                   |  11 +-
 defer/whichtochoose.tex            |  10 +-
 perfbook.tex                       |   6 +-
 6 files changed, 462 insertions(+), 135 deletions(-)
Signature · 1 line
2.7.4
author
#6 lore raw
Quoted 25 lines · Paul E. McKenney
Quoted 24 lines · Akira Yokosawa
Quoted 1 line

From af290804fbb9868bb242c8ad6d889d46dfa9add1 Mon Sep 17 00:00:00 2001

From: Akira Yokosawa <[email protected]>
Date: Fri, 18 Aug 2017 23:53:45 +0900
Subject: [PATCH 0/4] Style guide updates (round 2)

Hi Paul,

Let me explain each patch in this set first.

Patch #1 is for compatibility to older LaTeX installation.

Patch #2 adds the tweaked tables described below.

Patch #3 converts "tabulary" tables to "tabularx". It involves manual width adjustment, but the end result is not so different, with the bonus of increased font size. This enables us to try dashed lines of arydshln package.

Patch #4 adds examples using dashed lines. They look not so appealing in the particular tables, but there might be cases they are useful. On Ubuntu Trusty, an additional package "texlive-humanities" is necessary.

Regarding your message On 2017/08/14 08:32:46 -0700:

Quoted 8 lines
Quoted 6 lines
Quoted 3 lines

Perhaps single-column tables with (say) three or fewer rows might look like D.3, and more complex ones like D.4? Really complicated tables might need more \hlines, shaded cells, or some such.

There are few tables with three or fewer rows. So, most tables should look like D.4 (in the previous round). It is now Table D.3

I should have said "three or fewer columns", apologies for my confusion!

Ah, that explains.

Quoted 32 lines
Quoted 4 lines

Coloring of alternate rows could not be applied simply to Table 3.1 because of the \textcolor{} tweaks. I used siunitx's "S" column specifier instead in Table D.4.

But you did get the headers set up correctly despite their complexity, good show! The latex source for the body of the table certainly looks good. This table could probably be unruled as it only has three columns, but again, good demonstration of handling the headers.

Quoted 8 lines
Quoted 8 lines
Quoted 5 lines

For the coloring, all I did was adding a command "\rowcolors{1}{}{lightgray}".
The (not so) hard part was to make the header row to be actually one row. I used parbox for the moment.
Please give a look when you have time.

That does seem eminently reasonable for that table.

Quoted 8 lines
Quoted 5 lines

Tables 5.1 and 5.2 have more "interesting" headers, with the "Reads" spanning two columns, each of which has a subcolumn header. One approach would be to apply the "Reads" to each subcolumn like you did for D.4. But this approach looks to me to be less applicable to Table 13.1. And Table C.1.

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?

Quoted 6 lines
Quoted 1 line

D.6 is another version of Table 13.1 with proper legends.

I will have to think about the legend in this case. Nice in general, but a surprising fraction of the total space used by the table. Would it make sense to allow more than 1.5 inches for the definition so that it took less vertical space?

Yes, the legends can be tuned as you like. This is just an example.

Quoted 5 lines
Quoted 5 lines

I didn't touch Tables 5.1 nor 5.2 in this round, but they should be easy.

Quoted 1 line
Quoted 8 lines
Quoted 5 lines
Quoted 2 lines

Table 9.4 is a bit more challenging, and 10.1 is similar, though more suitable for your parbox trick. Thoughts?

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 thought so. If you want, I can add that version in the experiment.

Quoted 39 lines
Quoted 9 lines

Table 9.1 requires a different approach (not tried yet).

Table 10.1 can be regarded as a figure drawn by tabular environment and is not suitable to booktabs' rules.
Tables 7.1 and C.5 don't look suitable to booktabs' rules either. I'll keep them as is for the moment.

Quoted 1 line
Quoted 8 lines
Quoted 3 lines

Table 14.1 might need to keep its hlines, but what are your thoughts? A clear separation between the number on the left and the columns corresponding to each CPU seems important. Ditto 14.2.

Table 14.1 is reworked as Table D.9.
Gaps in the mid-rule can represent the separation done by vertical rules in the original one. I don't think hlines are necessary here either. Or using dashed hlines might be an option.

No, D.9 looks quite good to me. Much better than the lined original, in fact.

Quoted 6 lines
Quoted 1 line

Thoughts on Tables 17.1 and 17.2? (The HTM comparison tables.)

I have not tried these large and complex tables yet.
The "tabu" package might improve them. I'm kind of scared by the fancy looks of tabu document, though... There can be other options. Please give me a while.

As far as I know, we are not under any schedule pressure on this item. ;-)

Quoted 8 lines
Quoted 5 lines

But most of the rest of the tables look like they would do just fine as either D.3 (for the single-column ones with three or fewer columns) or D.4 (for the rest).

But what are your impressions?

So the other simple tables can have the rows colored.

Quoted 7 lines
Quoted 1 line

Let me know what you think of the added tables.

I did have to find an arydshln.sty. I ended up using this one:

http://ex.osaka-kyoiku.ac.jp/~fujii/dl/arydshln.sty

Is that a reasonable choice, or is there a better one elsewhere?

As mentioned in the commit log of 4/4 (and FAQ-BUIDL.txt updated there), you need "texlive-humanities" package for arydshln on Ubuntu Trusty.

Thanks, Akira

Quoted 24 lines

Thanx, Paul

Quoted 19 lines

Thanks, Akira
--
Akira Yokosawa (4):
Use 'fixltx2e' package
styleguide: Add more table experiments Get rid of 'tabulary' package
styleguide: Add table examples with dashed lines

 FAQ-BUILD.txt                      |   5 +-
 SMPdesign/SMPdesign.tex            |   8 +-
 appendix/styleguide/styleguide.tex | 557 +++++++++++++++++++++++++++++--------
 defer/rcuapi.tex                   |  11 +-
 defer/whichtochoose.tex            |  10 +-
 perfbook.tex                       |   6 +-
 6 files changed, 462 insertions(+), 135 deletions(-)
Signature · 1 line
2.7.4
#7 lore raw
Quoted 4 lines · Akira Yokosawa
Quoted 3 lines · Paul E. McKenney
Quoted 2 lines · Akira Yokosawa
Quoted 1 line

From af290804fbb9868bb242c8ad6d889d46dfa9add1 Mon Sep 17 00:00:00 2001

From: Akira Yokosawa <[email protected]>

[ . . . ]

Quoted 8 lines
Quoted 5 lines

I did have to find an arydshln.sty. I ended up using this one:

http://ex.osaka-kyoiku.ac.jp/~fujii/dl/arydshln.sty

Is that a reasonable choice, or is there a better one elsewhere?

As mentioned in the commit log of 4/4 (and FAQ-BUIDL.txt updated there), you need "texlive-humanities" package for arydshln on Ubuntu Trusty.

Indeed you did, and it does work, thank you!

Thanx, Paul

author
#8 lore raw
In reply to Paul E. McKenney

From 1073fa92397e86ec3ce8810c5068075ed6962301 Mon Sep 17 00:00:00 2001
From: Akira Yokosawa <[email protected]>
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 <[email protected]>

---
Hi Paul,

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

Quoted 1 line · Paul E. McKenney

On Sat, Aug 19, 2017 at 08:29:29AM +0900, Akira Yokosawa wrote:

[...]

Quoted 7 lines
Quoted 2 lines

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.

[...]

Quoted 5 lines
Quoted 2 lines

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(-)
appendix/styleguide/styleguide.tex +118 -19
index cfa3234..c0636db 100644
@@ -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}
Signature · 1 line
2.7.4
#9 lore raw
Quoted 5 lines · Akira Yokosawa
Quoted 1 line

From 1073fa92397e86ec3ce8810c5068075ed6962301 Mon Sep 17 00:00:00 2001

From: Akira Yokosawa <[email protected]>
Date: Wed, 23 Aug 2017 00:01:14 +0900
Subject: [PATCH 5/4] styleguide: Add example of partially colored rows

Quoted 8 lines

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

Signed-off-by Akira Yokosawa <[email protected]>

---
Hi Paul,

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

Gah!!! I forgot to do "git push" again. I will blame excitement about the solar eclipse. Now pushed. If you send the patch below, I will apply and hopefully remember to push it this time! ;-)

Thanx, Paul

Quoted 256 lines · Paul E. McKenney
Quoted 1 line · Akira Yokosawa

[...]

Quoted 7 lines
Quoted 2 lines

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.

[...]

Quoted 5 lines
Quoted 2 lines

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(-)
appendix/styleguide/styleguide.tex +118 -19
index cfa3234..c0636db 100644
@@ -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}
Signature · 1 line
2.7.4
author
#10 lore raw

PATCH RESEND 1/1 styleguide: Add example of partially colored rows

From 2bc37e7fd32155f0496228080eeb34fbe8dac73a Mon Sep 17 00:00:00 2001
From: Akira Yokosawa <[email protected]>
Date: Wed, 23 Aug 2017 00:01:14 +0900
Subject: [PATCH RESEND] styleguide: Add example of partially colored rows

Also add explanation of interference of \rowcolors{} commands and \cmidrule{} commands in LaTeX source.

Signed-off-by Akira Yokosawa <[email protected]>
---
 appendix/styleguide/styleguide.tex | 137 ++++++++++++++++++++++++++++++++-----
 1 file changed, 118 insertions(+), 19 deletions(-)
appendix/styleguide/styleguide.tex +118 -19
index cfa3234..c0636db 100644
@@ -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 interfares 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}
Signature · 1 line
2.7.4
#11 lore raw

Re: [PATCH RESEND] styleguide: Add example of partially colored rows

Quoted 9 lines · Akira Yokosawa
Quoted 1 line

From 2bc37e7fd32155f0496228080eeb34fbe8dac73a Mon Sep 17 00:00:00 2001

From: Akira Yokosawa <[email protected]>
Date: Wed, 23 Aug 2017 00:01:14 +0900
Subject: [PATCH RESEND] styleguide: Add example of partially colored rows

Also add explanation of interference of \rowcolors{} commands and \cmidrule{} commands in LaTeX source.

Signed-off-by Akira Yokosawa <[email protected]>

Applied and pushed, thank you!

Thanx, Paul

Quoted 227 lines
---
 appendix/styleguide/styleguide.tex | 137 ++++++++++++++++++++++++++++++++-----
 1 file changed, 118 insertions(+), 19 deletions(-)
appendix/styleguide/styleguide.tex +118 -19
index cfa3234..c0636db 100644
@@ -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 interfares 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}
Signature · 1 line
2.7.4