On Wed, Aug 23, 2017 at 12:30:58AM +0900, Akira Yokosawa wrote:
> >From 1073fa92397e86ec3ce8810c5068075ed6962301 Mon Sep 17 00:00:00 2001
> From: Akira Yokosawa <akiyks@xxxxxxxxx>
> 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@xxxxxxxxx>
> ---
> 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
> 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
>
--
To unsubscribe from this list: send the line "unsubscribe perfbook" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
