On Sun, Oct 29, 2017 at 09:19:18AM +0900, Akira Yokosawa wrote:
> >From 574dbdaffe6d9243921f4ac4f2cfcb9c3e86ae66 Mon Sep 17 00:00:00 2001
> From: Akira Yokosawa <akiyks@xxxxxxxxx>
> Date: Sun, 29 Oct 2017 09:15:02 +0900
> Subject: [PATCH] styleguide: Reflect table format conversion
>
> Signed-off-by: Akira Yokosawa <akiyks@xxxxxxxxx>
Applied, thank you! To me, Table D.3 looks better than either
D.10 or D.11, though I should look again later.
Thanx, Paul
> ---
> appendix/styleguide/styleguide.tex | 268 ++++++++++++++++++-------------------
> 1 file changed, 132 insertions(+), 136 deletions(-)
>
> diff --git a/appendix/styleguide/styleguide.tex b/appendix/styleguide/styleguide.tex
> index 024270c..11f539b 100644
> --- a/appendix/styleguide/styleguide.tex
> +++ b/appendix/styleguide/styleguide.tex
> @@ -733,6 +733,105 @@ As you can see, extra space is placed before the comma.
>
> The \verb|\ldots| macro behaves the same as the \verb|\dots| macro.
>
> +\subsection{Floating Object Format}
> +\label{sec:app:styleguide:Floating Object Format}
> +
> +\subsubsection{Ruled Line in Table}
> +\label{sec:app:styleguide:Ruled Line in Table}
> +
> +They say that tables drawn by using ruled lines of plain \LaTeX\
> +look ugly.\footnote{
> + \url{https://www.inf.ethz.ch/personal/markusp/teaching/guides/guide-tables.pdf}
> +}
> +Vertical lines should be avoided and horizontal lines should be
> +used sparingly, especially in tables of simple structure.
> +
> +\IfTblCpTop{}{
> +\floatstyle{plaintop}
> +\restylefloat{table}
> +\setlength{\abovetopsep}{-2pt}
> +\addtolength{\abovecaptionskip}{-2.5pt}
> +}
> +
> +Table~\ref{tab:app:styleguide:Refrigeration Power Consumption}
> +(corresponding to
> +Table~\ref{tab:future:Refrigeration Power Consumption})
> +is drawn by using the features of ``booktabs'' and ``xcolor'' packages.
> +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. A couple of experimental examples are presented in
> + Section~\ref{sec:app:styleguide:Table Layout Experiment}.
> +}
> +
> +\begin{table}[tbhp]
> +\rowcolors{1}{}{lightgray}
> +\renewcommand*{\arraystretch}{1.2}\centering\small
> +\begin{tabular}{lrrr}\toprule
> +Situation
> + & $T$ (K)
> + & $\CPf$ & \parbox[b]{.75in}{\raggedleft Power per watt\par waste heat (W)} \\
> +\midrule
> +Dry Ice
> + & $195$
> + & $1.990$
> + & 0.5 \\
> +Liquid N$_2$
> + & $77$
> + & $0.356$
> + & 2.8 \\
> +Liquid H$_2$
> + & $20$
> + & $0.073$
> + & 13.7 \\
> +Liquid He
> + & $4$
> + & $0.0138$
> + & 72.3 \\
> +IBM~Q & $0.015$
> + & $0.000051$
> + & 19,500.0 \\
> +\bottomrule
> +\end{tabular}
> +\caption{Refrigeration Power Consumption}
> +\label{tab:app:styleguide:Refrigeration Power Consumption}
> +\end{table}
> +
> +Most tables in the text have been converted to this format.
> +Tables~\ref{tab:future:Comparison of Locking and HTM}
> +and~\ref{tab:future:Comparison of Locking (Augmented by RCU or Hazard Pointers) and HTM}
> +are the exceptions. They are complex and require an alternative
> +approach.\footnote{Any suggestion is welcome!!!}
> +
> +\subsubsection{Position of Caption}
> +\label{sec:app:styleguide:Position of Caption}
> +
> +In \LaTeX\ conventions, captions of tables are usually placed
> +above them. The reason is the flow of your eye movement
> +when you look at them. Most tables have a row of heading at the
> +top. You naturally look at the top of a table at first. Captions at
> +the bottom of tables disturb this flow.
> +The same can be said of code snippets, which are read from
> +top to bottom.
> +
> +For code snippets, the ``ruled'' style chosen for listing
> +environment places the caption at the top.
> +See Listing~\ref{lst:app:styleguide:Sample Code Snippet}
> +for an example.
> +
> +As for tables, the position of caption is tweaked by
> +\verb|\floatstyle{}| and \verb|\restylefloat{}| macros
> +in preamble.
> +
> +Vertical skips below captions are reduced by setting a smaller
> +value to the \verb|\abovecaptionskip| variable,
> +which would also affect captions to figures.
> +
> +In the tables which use horizontal rules of ``booktabs'' package,
> +the vertical skips between captions and tables are further reduced
> +by setting a negative value to the \co{\\abovetopsep} variable,
> +which controls the behavior of \co{\\toprule}.
> +
> \subsection{Improvement Candidates}
> \label{sec:app:styleguide:Improvement Candidates}
>
> @@ -750,9 +849,6 @@ The \verb|\ldots| macro behaves the same as the \verb|\dots| macro.
> \end{minipage}
> \end{figure*}
>
> -\floatstyle{ruled}
> -\restylefloat{listing}
> -
> \begin{listing*}[tbh]%
> \caption{Message-Passing Litmus Test (by subfig)}%
> \label{lst:app:styleguide:Message-Passing Litmus Test (subfig)}%
> @@ -829,38 +925,7 @@ exists (1:r2=2 /\ 1:r3=0)
>
> There are a few areas yet to be attempted in perfbook
> which would further improve its appearance.
> -This section lists up such candidates.
> -
> -\subsubsection{Position of Caption}
> -\label{sec:app:styleguide:Position of Caption}
> -
> -In \LaTeX\ conventions, captions of tables are usually placed
> -above them. The reason is the flow of your eye movement
> -when you look at them. Most tables have a row of heading at the
> -top. You naturally look at the top of a table at first. Captions at
> -the bottom of tables disturb this flow.
> -The same can be said of code snippets, which are read from
> -top to bottom.
> -
> -For code snippets, the ``ruled'' style chosen for listing
> -environment places the caption at the top.
> -See Listing~\ref{lst:app:styleguide:Sample Code Snippet}
> -for an example.
> -
> -As for tables, the position of caption can be tweaked by
> -\verb|\floatstyle{}| and \verb|\restylefloat{}| macros
> -in preamble.
> -
> -In the sample tables shown in
> -Sections~\ref{sec:app:styleguide:Ruled Line in Table}
> -and~\ref{sec:app:styleguide:Table Layout Experiment},
> -vertical skips below captions are reduced by setting a smaller
> -value to the \verb|\abovecaptionskip| variable,
> -which would also affect captions to figures.\footnote{
> - The skip below table captions in these sections is further
> - reduced by setting a negative value to the \co{\\abovetopsep}
> - variable of the ``booktabs'' package which controls the behavior
> - of \co{\\toprule}.}
> +This section lists such candidates.
>
> \subsubsection{Grouping Related Figures/Listings}
> \label{sec:app:styleguide:Grouping Related Figures/Listings}
> @@ -909,75 +974,14 @@ subfloats.
> Otherwise, the resulting caption number would be off by one
> from the actual number.
>
> -\subsubsection{Ruled Line in Table}
> -\label{sec:app:styleguide:Ruled Line in Table}
> -
> -They say that tables drawn by using ruled lines of plain \LaTeX\
> -look ugly.\footnote{
> - \url{https://www.inf.ethz.ch/personal/markusp/teaching/guides/guide-tables.pdf}
> -}
> -Vertical lines should be avoided and horizontal lines should be
> -used sparingly, especially in tables of simple structure.
> -
> -\IfTblCpTop{}{
> -\floatstyle{plaintop}
> -\restylefloat{table}
> -\setlength{\abovetopsep}{-2pt}
> -\addtolength{\abovecaptionskip}{-2.5pt}
> -}
> -
> -For example,
> -Table~\ref{tab:future:Refrigeration Power Consumption}
> -can be tweaked as shown in
> -Table~\ref{tab:app:styleguide:Refrigeration Power Consumption}
> -with the help of ``booktabs'' and ``xcolor'' packages.
> -
> -\begin{table}[tbhp]
> -\rowcolors{1}{}{lightgray}
> -\renewcommand*{\arraystretch}{1.2}\centering\small
> -\begin{tabular}{lrrr}\toprule
> -Situation
> - & $T$ (K)
> - & $\CPf$ & \parbox[b]{.75in}{\raggedleft Power per watt\par waste heat (W)} \\
> -\midrule
> -Dry Ice
> - & $195$
> - & $1.990$
> - & 0.5 \\
> -Liquid N$_2$
> - & $77$
> - & $0.356$
> - & 2.8 \\
> -Liquid H$_2$
> - & $20$
> - & $0.073$
> - & 13.7 \\
> -Liquid He
> - & $4$
> - & $0.0138$
> - & 72.3 \\
> -IBM~Q & $0.015$
> - & $0.000051$
> - & 19,500.0 \\
> -\bottomrule
> -\end{tabular}
> -\caption{Refrigeration Power Consumption}
> -\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. A couple of experimental examples are presented in
> - Section~\ref{sec:app:styleguide:Table Layout Experiment}.
> -}
> -
> \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, xcolors, and arydshln packages
> -are presented in this section.
> +This section presents some experimental tables
> +using booktabs, xcolors, and arydshln packages.
> +The corresponding tables in the text have been converted using one of
> +the format shown here. The source of this section can be regarded
> +as a reference to be consulted when new tables are added in the text.
>
> \begin{table}[tb]
> \rowcolors{1}{}{lightgray}
> @@ -1007,25 +1011,26 @@ are presented in this section.
> \label{tab:app:styleguide:Performance of Synchronization Mechanisms of 4-CPU 1.8GHz AMD Opteron 844 System}
> \end{table}
>
> -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} using booktabs and xcolors.
> -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.
> +In
> +Table~\ref{tab:app:styleguide:Performance of Synchronization Mechanisms of 4-CPU 1.8GHz AMD Opteron 844 System}
> +(corresponding to
> +Table~\ref{tab:cpu:Performance of Synchronization Mechanisms on 4-CPU 1.8GHz AMD Opteron 844 System}),
> +the ``S'' column specifiers provided
> +by the ``siunitx'' package are used to align numbers.
>
> 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.
> -
> +(corresponding to
> +Table~\ref{tab:together:Reference Counting and Synchronization Mechanisms})
> +is an example of table with a complex header.
> 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}.
> -The legends in the frame box explain the abbreviations used in the matrix.
> -Two types of memory barrier are denoted by subscripts here.
> +which had been represented by double vertical rules before the conversion.
> +The legends in the frame box appended here explain the abbreviations used
> +in the matrix. Two types of memory barrier are denoted by subscripts here.
> +The legends and subscripts are not present in
> +Table~\ref{tab:together:Reference Counting and Synchronization Mechanisms}
> +since they are redundant there.
>
> \begin{table}[tb]
> \small
> @@ -1062,12 +1067,10 @@ Two types of memory barrier are denoted by subscripts here.
> \label{tab:app:styleguide:Reference Counting and Synchronization Mechanisms}
> \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.
> +(corresponding to
> +Table~\ref{tab:app:whymb:Cache Coherence Example})
> +is a sequence diagram drawn as a table.
>
> \begin{table*}[tbh]
> \small
> @@ -1117,12 +1120,15 @@ just below the mid-rules. This change makes it easier for
> 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
> +is another version 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.
> +In
> +Table~\ref{tab:defer:RCU Publish-Subscribe and Version Maintenance APIs},
> +the latter layout without partial row coloring has been
> +chosen for simplicity.
>
> \begin{table*}[tbh]
> \rowcolors{2}{}{blue!15}
> @@ -1272,10 +1278,10 @@ Pointer update &
> \label{tab:app:styleguide:RCU Publish-Subscribe and Version Maintenance APIs (colortbl)}
> \end{table*}
>
> -Table~\ref{tab:memorder: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.
> +Table~\ref{tab:app:styleguide:Memory Misordering: Store-Buffering Sequence of Events}
> +(corresponding to
> +Table~\ref{tab:memorder:Memory Misordering: Store-Buffering Sequence of Events})
> +is also a sequence diagram drawn as a tabular object.
>
> \begin{table*}[tbh]
> \rowcolors{6}{}{lightgray}
> @@ -1381,11 +1387,6 @@ IBM~Q & $0.015$
> \label{tab:app:styleguide:Refrigeration Power Consumption (arydshln-2)}
> \end{table}
>
> -Tables in Chapter~\ref{chp:Advanced Synchronization: Memory Ordering}
> -have been recently converted to the scheme presented in this section.
> -Refer to \path{memorder/memorder.tex}
> -for examples of tables with complex headings.
> -
> \IfTblCpTop{}{
> \floatstyle{plain}
> \restylefloat{table}
> @@ -1399,11 +1400,6 @@ for examples of tables with complex headings.
> Other improvement candidates are listed in the source of this
> section as comments.
>
> -% Trademarks:
> -% As the Legal page covers trademarks, there is no need to
> -% use trademark symbol in the text. They seems to have been
> -% imported from original publications.
> -%
> % Ugly line break by \co{}
> % __
> % atomic_store()
> --
> 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
