[PATCH 0/5] Style guide updates

[PATCH 0/5] Style guide updates

[Akira Yokosawa]

From 24d4de52c8186c1ec1787e76d13e22646d804a53 Mon Sep 17 00:00:00 2001
From: Akira Yokosawa <akiyks@gmail.com>
Date: Sun, 13 Aug 2017 11:00:48 +0900
Subject: [PATCH 0/5] Style guide updates

Hi Paul,

The style guide needs some updates regarding recent changes in
litmus tests in memory barriers section. (Patch #3)
Also I recovered the tweaks in table layout. I added another
option to color rows alternately. (Patch #1 and #2)
Patch #4 is my attempt to convince you that using commas for
digit grouping should be regarded as harmful in global POV.
My suggestion is to use \num{} commands in LaTeX source and
let a reader to pick a style of his/her choice.

\num{} command can slow down pdflatex processing somewhat,
but should be acceptable on modern platforms.

Thoughts?

        Thanks, Akira
--
Akira Yokosawa (5):
  styleguide: Add examples of alternative table layout
  styleguide: Tweak layout of 'Limitation' table
  styleguide: Update LaTeX source of code snippet
  styleguide: Add example of options to \num{} command
  styleguide: Emphasize source part of epigraph

 appendix/styleguide/samplecodesnippet.tex    |  19 --
 appendix/styleguide/samplecodesnippetfig.tex |  19 ++
 appendix/styleguide/samplecodesnippetlst.tex |  19 ++
 appendix/styleguide/styleguide.tex           | 375 ++++++++++++++++++---------
 perfbook.tex                                 |   5 +-
 5 files changed, 301 insertions(+), 136 deletions(-)
 delete mode 100644 appendix/styleguide/samplecodesnippet.tex
 create mode 100644 appendix/styleguide/samplecodesnippetfig.tex
 create mode 100644 appendix/styleguide/samplecodesnippetlst.tex

-- 
2.7.4

[PATCH 1/5] styleguide: Add examples of alternative table layout

[Akira Yokosawa]

From f6016bad16a5f46896aba335168d9e95e375e861 Mon Sep 17 00:00:00 2001
From: Akira Yokosawa <akiyks@gmail.com>
Date: Wed, 9 Aug 2017 19:48:03 +0900
Subject: [PATCH 1/5] styleguide: Add examples of alternative table layout

Add examples using:
  1) ruled lines of "booktabs" package,
  2) color alternate rows using "table" option of xcolor.

Also add footnote on "arydshln" package's conflict with
tabulary package.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
 appendix/styleguide/styleguide.tex | 86 +++++++++++++++++++++++++++++++++++++-
 perfbook.tex                       |  3 +-
 2 files changed, 87 insertions(+), 2 deletions(-)

diff --git a/appendix/styleguide/styleguide.tex b/appendix/styleguide/styleguide.tex
index 829a9c2..6b41897 100644
--- a/appendix/styleguide/styleguide.tex
+++ b/appendix/styleguide/styleguide.tex
@@ -808,7 +808,91 @@ look ugly.\footnote{
 Vertical lines should be avoided and horizontal lines should be
 used sparingly, especially in tables of simple structure.

-% TODO: Add example
+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}
+
+\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,
+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}
+
+\begin{table}[htbp]
+\rowcolors{1}{}{lightgray}
+\renewcommand*{\arraystretch}{1.2}\centering\small
+\begin{tabular}{lrrr}\toprule
+Situation
+	& $T$ (K)
+		& $C_P$	& \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}
+
+\floatstyle{plain}
+\restylefloat{table}
+\captionsetup[table]{position=bottom,hangindent=0pt}
+\renewcommand*{\abovetopsep}{0pt}

 \subsubsection{Miscellaneous Candidates}
 \label{sec:app:styleguide:Miscellaneous Candidates}
diff --git a/perfbook.tex b/perfbook.tex
index 8f166ec..23146ad 100644
--- a/perfbook.tex
+++ b/perfbook.tex
@@ -33,7 +33,7 @@
 \setlist[description]{style=unboxed}
 %\usepackage{enumerate}
 \usepackage{ifthen}
-\usepackage{xcolor}
+\usepackage[table]{xcolor}
 \usepackage[shortcuts]{extdash}
 \usepackage{changepage}
 \usepackage{listings}
@@ -89,6 +89,7 @@
 \newcommand{\LstLineNo}{\makebox[5ex][r]{\arabic{VerbboxLineNo}\hspace{2ex}}}

 \usepackage{bm} % for bold math mode fonts --- should be after math mode font choice
+\usepackage{booktabs}

 \IfLmttForCode{
 \AtBeginEnvironment{verbatim}{\renewcommand{\ttdefault}{lmtt}}
-- 
2.7.4

[PATCH 2/5] styleguide: Tweak layout of 'Limitation' table

[Akira Yokosawa]

From 9ecafff80ede69a2d85d5a28562fa86a5d925609 Mon Sep 17 00:00:00 2001
From: Akira Yokosawa <akiyks@gmail.com>
Date: Wed, 9 Aug 2017 19:49:18 +0900
Subject: [PATCH 2/5] styleguide: Tweak layout of 'Limitation' table

Use nice ruled lines of "booktabs".

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
 appendix/styleguide/styleguide.tex | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/appendix/styleguide/styleguide.tex b/appendix/styleguide/styleguide.tex
index 6b41897..2312316 100644
--- a/appendix/styleguide/styleguide.tex
+++ b/appendix/styleguide/styleguide.tex
@@ -391,12 +391,13 @@ Table~\ref{tab:app:styleguide:Limitation of Monospace Macro}
 lists such limitations.

 \begin{table}[tbh]
-\centering\footnotesize
-\begin{tabular}{lll}
+\renewcommand*{\arraystretch}{1.2}\centering\footnotesize
+\begin{tabular}{@{}lll@{}}\toprule
   Macro &  Need Escape & Should Avoid \\
-  \hline
+  \midrule
   \co{\\co}, \co{\\nbco} & \co{\\}, \%, \{, \} & \\
   \co{\\tco}  & \# & \%, \{, \}, \co{\\} \\
+  \bottomrule
 \end{tabular}
 \caption{Limitation of Monospace Macro}
 \label{tab:app:styleguide:Limitation of Monospace Macro}
-- 
2.7.4

[PATCH 3/5] styleguide: Update LaTeX source of code snippet

[Akira Yokosawa]

From 7729d8527d2594aaabc0d4669ec2f3f9fc10142d Mon Sep 17 00:00:00 2001
From: Akira Yokosawa <akiyks@gmail.com>
Date: Thu, 10 Aug 2017 00:23:48 +0900
Subject: [PATCH 3/5] styleguide: Update LaTeX source of code snippet

Present up-to-date scheme for code snippets.
Also catch up to the on-going modifications in main text inspired
by the style guide.
Also, clarify which of yet to be followed NIST rules can be
taken care of in the near future

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
 appendix/styleguide/samplecodesnippet.tex    |  19 ---
 appendix/styleguide/samplecodesnippetfig.tex |  19 +++
 appendix/styleguide/samplecodesnippetlst.tex |  19 +++
 appendix/styleguide/styleguide.tex           | 242 ++++++++++++++-------------
 perfbook.tex                                 |   1 +
 5 files changed, 168 insertions(+), 132 deletions(-)
 delete mode 100644 appendix/styleguide/samplecodesnippet.tex
 create mode 100644 appendix/styleguide/samplecodesnippetfig.tex
 create mode 100644 appendix/styleguide/samplecodesnippetlst.tex

diff --git a/appendix/styleguide/samplecodesnippet.tex b/appendix/styleguide/samplecodesnippet.tex
deleted file mode 100644
index 9020805..0000000
--- a/appendix/styleguide/samplecodesnippet.tex
+++ /dev/null
@@ -1,19 +0,0 @@
-\begin{figure}[tbh]
-{ \scriptsize
-\begin{verbbox}
-  1 /*
-  2  * Sample Code Snippet
-  3  */
-  4  #include <stdio.h>
-  5  int main(void)
-  6  {
-  7    printf("Hello world!\n");
-  8    return 0;
-  9  }
-\end{verbbox}
-}
-\centering
-\theverbbox
-\caption{Sample Code Snippet}
-\label{fig:app:styleguide:Sample Code Snippet}
-\end{figure}
diff --git a/appendix/styleguide/samplecodesnippetfig.tex b/appendix/styleguide/samplecodesnippetfig.tex
new file mode 100644
index 0000000..9020805
--- /dev/null
+++ b/appendix/styleguide/samplecodesnippetfig.tex
@@ -0,0 +1,19 @@
+\begin{figure}[tbh]
+{ \scriptsize
+\begin{verbbox}
+  1 /*
+  2  * Sample Code Snippet
+  3  */
+  4  #include <stdio.h>
+  5  int main(void)
+  6  {
+  7    printf("Hello world!\n");
+  8    return 0;
+  9  }
+\end{verbbox}
+}
+\centering
+\theverbbox
+\caption{Sample Code Snippet}
+\label{fig:app:styleguide:Sample Code Snippet}
+\end{figure}
diff --git a/appendix/styleguide/samplecodesnippetlst.tex b/appendix/styleguide/samplecodesnippetlst.tex
new file mode 100644
index 0000000..06df5cc
--- /dev/null
+++ b/appendix/styleguide/samplecodesnippetlst.tex
@@ -0,0 +1,19 @@
+\begin{listing}
+{ \scriptsize
+\begin{verbbox}[\LstLineNo]
+/*
+ * Sample Code Snippet
+ */
+#include <stdio.h>
+int main(void)
+{
+  printf("Hello world!\n");
+  return 0;
+}
+\end{verbbox}
+}
+\centering
+\theverbbox
+\caption{Sample Code Snippet}
+\label{lst:app:styleguide:Sample Code Snippet}
+\end{listing}
diff --git a/appendix/styleguide/styleguide.tex b/appendix/styleguide/styleguide.tex
index 2312316..c90bbe7 100644
--- a/appendix/styleguide/styleguide.tex
+++ b/appendix/styleguide/styleguide.tex
@@ -185,44 +185,24 @@ Example:
 \label{sec:app:styleguide:NIST Guides Yet To Be Followed}

 There are a few cases where NIST style guide is not followed.
-Other English conventions are preferred in such cases.
-
-\subsubsection{Digit Spacing}
-\label{sec:app:styleguide:Digit Spacing}
-
-Quote from NIST check list:\footnote{
-  \#16 in \url{http://physics.nist.gov/cuu/Units/checklist.html}.
-}
-
-\begin{quote}
-  The digits of numerical values having more than four digits on either
-  side of the decimal marker are separated into groups of three using
-  a thin, fixed space counting from both the left and right of the decimal
-  marker. Commas are not used to separate digits into groups of three.
-\end{quote}
-
-\begin{quote}
-\begin{tabular}{ll}
-  NIST Example:& 15\,739.012\,53\,ms\\
-  Our conventions:& 15,739.01253\,ms\\
-\end{tabular}
-\end{quote}
-
-In \LaTeX\ coding, it is cumbersome to place thin spaces as are recommended
-in NIST guide. The \verb|\num{}| command provided by the ``siunitx''
-package would be of help for us to follow this rule.
+Other English conventions are followed in such cases.
+NIST rules of
+Sections~\ref{sec:app:styleguide:Percent Symbol}
+and~\ref{sec:app:styleguide:Font Style}
+are deemed acceptable by the editor.
+Contributions in those areas should be welcome.

 \subsubsection{Percent Symbol}
 \label{sec:app:styleguide:Percent Symbol}

 NIST style guide treats the percent symbol (\%) as the same as SI unit
 symbols.
-In this textbook, no space is required in front of a percent symbol.
+In this textbook, no space is placed in front of a percent symbol.

 \begin{quote}
 \begin{tabular}{ll}
   NIST guide:& 50\,\% possibility\\
-  Our conventions:& 50\% possibility\\
+  Current convention:& 50\% possibility\\
 \end{tabular}
 \end{quote}

@@ -262,7 +242,31 @@ in math mode by default.\footnote{
   See \url{https://tex.stackexchange.com/questions/119248/}
   for the historical reason.}

-\pagebreak % to prevent footnotes from spilling into next page
+\subsubsection{Digit Spacing}
+\label{sec:app:styleguide:Digit Spacing}
+
+Quote from NIST check list:\footnote{
+  \#16 in \url{http://physics.nist.gov/cuu/Units/checklist.html}.
+}
+
+\begin{quote}
+  The digits of numerical values having more than four digits on either
+  side of the decimal marker are separated into groups of three using
+  a thin, fixed space counting from both the left and right of the decimal
+  marker. Commas are not used to separate digits into groups of three.
+\end{quote}
+
+\begin{quote}
+\begin{tabular}{ll}
+  NIST Example:& 15\,739.012\,53\,ms\\
+  Our convention:& 15,739.01253\,ms\\
+\end{tabular}
+\end{quote}
+
+In \LaTeX\ coding, it is cumbersome to place thin spaces as are recommended
+in NIST guide. The \verb|\num{}| command provided by the ``siunitx''
+package would be of help for us to follow this rule.
+
 \section{\LaTeX\ Conventions}
 \label{sec:app:styleguide:LaTeX Conventions}

@@ -293,38 +297,90 @@ centering layout.
 %  by the ``listings'' package. We are already using its ``lstinline''
 %  command in the definition of \co{\\co\{\}} macro.

-\begin{figure}[tbh]
+\begin{listing}[tbh]
 { \scriptsize
 \verbfilebox[{\makebox[5ex][r]{\arabic{VerbboxLineNo}:\hspace{2ex}}}]
-	{appendix/styleguide/samplecodesnippet.tex}
+	{appendix/styleguide/samplecodesnippetlst.tex}
 }
 \centering
 \theverbbox
-\caption{\LaTeX\ Source of Sample Code Snippet}
-\label{fig:app:styleguide:LaTeX Source of Sample Code Snippet}
-\end{figure}
+\caption{\LaTeX\ Source of Sample Code Snippet (Current)}
+\label{lst:app:styleguide:LaTeX Source of Sample Code Snippet (Current)}
+\end{listing}

-\input{appendix/styleguide/samplecodesnippet}
+\input{appendix/styleguide/samplecodesnippetlst}

 The \LaTeX\ source of a sample code snippet is shown in
-Figure~\ref{fig:app:styleguide:LaTeX Source of Sample Code Snippet}
+Listing~\ref{lst:app:styleguide:LaTeX Source of Sample Code Snippet (Current)}
 and is typeset as show in
-Figure~\ref{fig:app:styleguide:Sample Code Snippet}.
+Listing~\ref{lst:app:styleguide:Sample Code Snippet}.

-Note that the verbbox environment is placed inside the figure environment.
+Note that the verbbox environment is placed inside the listing environment.
 This is to avoid a side effect of verbbox environment that interferes
 with the ``afterheading\-/ness'' of a section's first sentence
 when a verbbox is placed just below a heading.

+Until recently, code snippets were coded using a different scheme.
+A sample \LaTeX\ source is shown in
+Listing~\ref{lst:app:styleguide:LaTeX Source of Sample Code Snippet (Obsolescent)}
+and is typeset as shown in
+Figure~\ref{fig:app:styleguide:Sample Code Snippet}.
+
+\begin{listing}[tbh]
+{ \scriptsize
+\verbfilebox[{\makebox[5ex][r]{\arabic{VerbboxLineNo}:\hspace{2ex}}}]
+	{appendix/styleguide/samplecodesnippetfig.tex}
+}
+\centering
+\theverbbox
+\caption{\LaTeX\ Source of Sample Code Snippet (Obsolescent)}
+\label{lst:app:styleguide:LaTeX Source of Sample Code Snippet (Obsolescent)}
+\end{listing}
+
+\input{appendix/styleguide/samplecodesnippetfig}
+
+In Listing~\ref{lst:app:styleguide:LaTeX Source of Sample Code Snippet (Obsolescent)},
+the code snippet is coded as a ``figure'' object.
 Line numbers are manually placed for ease of referencing them within
-\LaTeX\ sources.\footnote{
-  As a matter of fact, the verbatimbox package has its own line
-  number counter and the count can be displayed in the resulting
-  listing. Leftmost line numbers in
-  Figure~\ref{fig:app:styleguide:LaTeX Source of Sample Code Snippet}
-  are output by the feature. The litmus tests in
-  Section~\ref{sec:advsync:Memory Barriers}
-  have been converted to use the auto-numbering feature.}
+\LaTeX\ sources.
+
+This is how most code snippets are coded as of this writing.
+However, strictly speaking, code snippets are \emph{not} figures
+and they deserve their own floating environment.
+The ``float'' package provides the feature to define additional
+floating environments.\footnote{
+  The ``floatrow'' package provides us even more flexible
+  control of floating objects. However, because of an issue
+  in two-column layout, we can not use it at the moment.}
+
+Transition to the auto-numbering scheme of verbbox and
+the ``listing'' environment defined for code snippets
+has recently started in
+Section~\ref{sec:advsync:Memory Barriers}.
+The transition also permits us to choose distinct looks
+for code snippets, including moving captions to top of the
+listings
+(discussed in Section~\ref{sec:app:styleguide:Position of Caption}).
+
+The auto\-/numbering feature of verbbox is enabled by
+the \verb|\LstLineNo| macro specified in the option to verbbox
+(line~3 in
+Listing~\ref{lst:app:styleguide:LaTeX Source of Sample Code Snippet (Current)}).
+The macro is defined in the preamble of \path{perfbook.tex}
+as the following:
+
+\noindent\begin{minipage}{\columnwidth}
+{ \scriptsize
+\begin{verbbox}
+\newcommand{\LstLineNo}
+  {\makebox[5ex][r]{\arabic{VerbboxLineNo}\hspace{2ex}}}
+\end{verbbox}
+}
+\vspace{10pt}
+\centering
+\theverbbox
+\vspace{10pt}
+\end{minipage}

 The verbatim environment is used for listings with too many lines
 to fit in a column. It is also used to avoid overwhelming
@@ -554,7 +610,7 @@ Example with a simple dash:

 \begin{quote}
   Lines~4\=/12 in
-  Figure~\ref{fig:app:styleguide:LaTeX Source of Sample Code Snippet}
+  Listing~\ref{lst:app:styleguide:LaTeX Source of Sample Code Snippet (Current)}
   are the contents of the verbbox environment. The box is output
   by the \co{\\theverbbox} macro on line~16.
 \end{quote}
@@ -563,7 +619,7 @@ Example with an en dash:

 \begin{quote}
   Lines~4\==12 in
-  Figure~\ref{fig:app:styleguide:LaTeX Source of Sample Code Snippet}
+  Listing~\ref{lst:app:styleguide:LaTeX Source of Sample Code Snippet (Current)}
   are the contents of the verbbox environment. The box is output
   by the \co{\\theverbbox} macro on line~16.
 \end{quote}
@@ -585,81 +641,41 @@ There are a few areas yet to be attempted in perfbook
 which would further improve its appearance.
 This section lists up such candidates.

-\subsubsection{Environment for Code Snippets}
-\label{sec:app:styleguide:Environment for Code Snippets}
-
-Strictly speaking, code snippets are \emph{not} figures.
-They deserve their own floating environment.
-The ``float'' package would be of help.\footnote{
-  The ``floatrow'' package provides us even more flexible
-  control of floating objects. However, because of an issue
-  in two-column layout, we can not use it at the moment.}
-
-Figure~\ref{fig:app:styleguide:Sample Code Snippet}
-can be typeset as in
-Listing~\ref{lst:app:styleguide:Sample Code Snippet}
-using an experimental environment ``listing''.
-
-\begin{listing}
-{ \scriptsize
-\begin{verbbox}[\LstLineNo]
-/*
- * Sample Code Snippet
- */
-#include <stdio.h>
-int main(void)
-{
-  printf("Hello world!\n");
-  return 0;
-}
-\end{verbbox}
-}
-\centering
-\theverbbox
-\caption{Sample Code Snippet}
-\label{lst:app:styleguide:Sample Code Snippet}
-\end{listing}
-
 \subsubsection{Position of Caption}
 \label{sec:app:styleguide:Position of Caption}

-In \LaTeX\ conventions, captions of tables should be placed
+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.
-The float package mentioned above also has the capability
-to adjust layout of caption.
-
-For code snippets, the ``ruled'' style would be our choice.
-Listing~\ref{lst:app:styleguide:Sample Code Snippet (Ruled)}
-is an example using the style.
-
-\begin{listing}
-{ \scriptsize
-\begin{verbbox}[\LstLineNo]
-/*
- * Sample Code Snippet
- */
-#include <stdio.h>
-int main(void)
-{
-  printf("Hello world!\n");
-  return 0;
-}
-\end{verbbox}
-}
-\centering
-\theverbbox
-\caption{Sample Code Snippet (Ruled)}
-\label{lst:app:styleguide:Sample Code Snippet (Ruled)}
-\end{listing}

-Once the conversion of code sippets to a new environment has
-completed, we would be able to choose one of the style options
-as the default for the environment.
+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.
+
+Currently, as most code snippets are figures with their captions
+at the bottom, captions of tables at the top might look inconsistent.
+Once the transition of code snippets to listing environment
+completes, there would be fewer figures and the caption of tables
+at the top would hopefully be acceptable.
+
+Vertical space between captions at the top and the table bodies
+can be reduced by the help of ``ctable'' package.
+
+In the sample tables shown in
+Section~\ref{sec:app:styleguide:Ruled Line in Table},
+the vertical skip is manually reduced by setting a negative value to the
+\verb|\abovetopsep| variable which controls the behavior of
+\verb|\toprule| of the ``booktabs'' package.
+It should be regarded as a band-aid tweak.

 \subsubsection{Grouping Related Figures/Listings}
 \label{sec:app:styleguide:Grouping Related Figures/Listings}
diff --git a/perfbook.tex b/perfbook.tex
index 23146ad..f8421ca 100644
--- a/perfbook.tex
+++ b/perfbook.tex
@@ -98,6 +98,7 @@
 \AtBeginEnvironment{tabular}{\renewcommand{\ttdefault}{lmtt}}
 \AtBeginEnvironment{tabulary}{\renewcommand{\ttdefault}{lmtt}}
 \AtBeginEnvironment{minipage}{\renewcommand{\ttdefault}{lmtt}}
+\AtBeginEnvironment{listing}{\renewcommand{\ttdefault}{lmtt}}
 }{}

 \begin{document}
-- 
2.7.4

[PATCH 4/5] styleguide: Add example of options to \num{} command

[Akira Yokosawa]

From 5a9c793796655ca1be1505d544604cd059fd4a48 Mon Sep 17 00:00:00 2001
From: Akira Yokosawa <akiyks@gmail.com>
Date: Sat, 12 Aug 2017 18:30:34 +0900
Subject: [PATCH 4/5] styleguide: Add example of options to \num{} command

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
 appendix/styleguide/styleguide.tex | 46 ++++++++++++++++++++++++++++++++++++--
 perfbook.tex                       |  1 +
 2 files changed, 45 insertions(+), 2 deletions(-)

diff --git a/appendix/styleguide/styleguide.tex b/appendix/styleguide/styleguide.tex
index c90bbe7..0ab9e68 100644
--- a/appendix/styleguide/styleguide.tex
+++ b/appendix/styleguide/styleguide.tex
@@ -242,8 +242,8 @@ in math mode by default.\footnote{
   See \url{https://tex.stackexchange.com/questions/119248/}
   for the historical reason.}

-\subsubsection{Digit Spacing}
-\label{sec:app:styleguide:Digit Spacing}
+\subsubsection{Digit Grouping}
+\label{sec:app:styleguide:Digit Grouping}

 Quote from NIST check list:\footnote{
   \#16 in \url{http://physics.nist.gov/cuu/Units/checklist.html}.
@@ -266,6 +266,48 @@ Quote from NIST check list:\footnote{
 In \LaTeX\ coding, it is cumbersome to place thin spaces as are recommended
 in NIST guide. The \verb|\num{}| command provided by the ``siunitx''
 package would be of help for us to follow this rule.
+It would also help us overcome different conventions.
+We can select a specific digit-grouping style as
+a default in preamble, or specify an option to each \verb|\num{}|
+command as is shown in
+Table~\ref{tab:app:styleguide:Digit-Grouping Style}.
+
+\newcommand{\NumDigitGrpA}{12 345}
+\newcommand{\NumDigitGrpB}{12.345}
+\newcommand{\NumDigitGrp}{1 234 567.89}
+\begin{table}[htbp]
+\small\centering
+\begin{tabular}{lrrr}\toprule
+  Style & \multicolumn{3}{c}{Outputs of \co{\\num\{\}}} \\
+  \midrule
+  NIST/SI (English) & \num{\NumDigitGrpA} & \num{\NumDigitGrpB} & \num{\NumDigitGrp} \\
+  SI (French) & \num[locale=FR]{\NumDigitGrpA} &
+    \num[locale=FR]{\NumDigitGrpB} & \num[locale=FR]{\NumDigitGrp} \\
+  English & \num[group-separator={,},group-digits=integer]{\NumDigitGrpA} &
+    \num[group-separator={,},group-digits=integer]{\NumDigitGrpB} &
+      \num[group-separator={,},group-digits=integer]{\NumDigitGrp} \\
+  French & \num[locale=FR]{\NumDigitGrpA} &
+    \num[locale=FR]{\NumDigitGrpB} & \num[locale=FR]{\NumDigitGrp} \\
+  Other Europe & \num[group-separator={.},output-decimal-marker={,},group-digits=integer]{\NumDigitGrpA} &
+    \num[group-separator={.},output-decimal-marker={,},group-digits=integer]{\NumDigitGrpB} &
+      \num[group-separator={.},output-decimal-marker={,},group-digits=integer]{\NumDigitGrp} \\
+\bottomrule
+\end{tabular}
+\caption{Digit-Grouping Style}
+\label{tab:app:styleguide:Digit-Grouping Style}
+\end{table}
+
+As are evident in
+Table~\ref{tab:app:styleguide:Digit-Grouping Style},
+periods and commas used as other than decimal markers are confusing
+and should be avoided, especially in documents expecting global
+audiences.
+
+By marking up constant decimal values by \verb|\num{}| commands,
+the \LaTeX\ source would be exempted from any particular conventions.
+
+Because of its open-source policy, this approach should give
+more ``portability'' to perfbook.

 \section{\LaTeX\ Conventions}
 \label{sec:app:styleguide:LaTeX Conventions}
diff --git a/perfbook.tex b/perfbook.tex
index f8421ca..9f1644d 100644
--- a/perfbook.tex
+++ b/perfbook.tex
@@ -53,6 +53,7 @@
 \setlength{\epigraphwidth}{2.6in}
 \usepackage[xspace]{ellipsis}
 \usepackage{braket} % for \ket{} macro in QC section
+\usepackage{siunitx} % for \num{} macro

 % custom packages

-- 
2.7.4

[PATCH 5/5] styleguide: Emphasize source part of epigraph

[Akira Yokosawa]

From 24d4de52c8186c1ec1787e76d13e22646d804a53 Mon Sep 17 00:00:00 2001
From: Akira Yokosawa <akiyks@gmail.com>
Date: Sat, 12 Aug 2017 19:58:22 +0900
Subject: [PATCH 5/5] styleguide: Emphasize source part of epigraph

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
 appendix/styleguide/styleguide.tex | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/appendix/styleguide/styleguide.tex b/appendix/styleguide/styleguide.tex
index 0ab9e68..47251a1 100644
--- a/appendix/styleguide/styleguide.tex
+++ b/appendix/styleguide/styleguide.tex
@@ -4,7 +4,7 @@
 \chapter{Style Guide}
 \label{chp:app:styleguide:Style Guide}
 %
-\Epigraph{De gustibus non est disputandum.}{Latin maxim}
+\Epigraph{De gustibus non est disputandum.}{\emph{Latin maxim}}

 This appendix is a collection of style guides which is intended
 as a reference to improve consistency in perfbook. It also contains
-- 
2.7.4

Re: [PATCH 0/5] Style guide updates

[Paul E. McKenney]

On Sun, Aug 13, 2017 at 12:27:52PM +0900, Akira Yokosawa wrote:
> >From 24d4de52c8186c1ec1787e76d13e22646d804a53 Mon Sep 17 00:00:00 2001
> From: Akira Yokosawa <akiyks@gmail.com>
> Date: Sun, 13 Aug 2017 11:00:48 +0900
> Subject: [PATCH 0/5] Style guide updates
> 
> Hi Paul,
> 
> The style guide needs some updates regarding recent changes in
> litmus tests in memory barriers section. (Patch #3)
> Also I recovered the tweaks in table layout. I added another
> option to color rows alternately. (Patch #1 and #2)
> Patch #4 is my attempt to convince you that using commas for
> digit grouping should be regarded as harmful in global POV.
> My suggestion is to use \num{} commands in LaTeX source and
> let a reader to pick a style of his/her choice.
> 
> \num{} command can slow down pdflatex processing somewhat,
> but should be acceptable on modern platforms.
> 
> Thoughts?

Applied and pushed, thank you!

Table D.3 looks fine, but it only has thee columns.  If it had more
columns or was wider or variable-depth rows, it would be hard to read.
Table D.4 looks good to me, but I (intentionally) have not yet looked
at what you had to do in LaTeX to make it happen.  ;-)

							Thanx, Paul

>         Thanks, Akira
> --
> Akira Yokosawa (5):
>   styleguide: Add examples of alternative table layout
>   styleguide: Tweak layout of 'Limitation' table
>   styleguide: Update LaTeX source of code snippet
>   styleguide: Add example of options to \num{} command
>   styleguide: Emphasize source part of epigraph
> 
>  appendix/styleguide/samplecodesnippet.tex    |  19 --
>  appendix/styleguide/samplecodesnippetfig.tex |  19 ++
>  appendix/styleguide/samplecodesnippetlst.tex |  19 ++
>  appendix/styleguide/styleguide.tex           | 375 ++++++++++++++++++---------
>  perfbook.tex                                 |   5 +-
>  5 files changed, 301 insertions(+), 136 deletions(-)
>  delete mode 100644 appendix/styleguide/samplecodesnippet.tex
>  create mode 100644 appendix/styleguide/samplecodesnippetfig.tex
>  create mode 100644 appendix/styleguide/samplecodesnippetlst.tex
> 
> -- 
> 2.7.4
> 

Re: [PATCH 0/5] Style guide updates

[Akira Yokosawa]

On 2017/08/13 10:26:24 -0700, Paul E. McKenney wrote:
> On Sun, Aug 13, 2017 at 12:27:52PM +0900, Akira Yokosawa wrote:
>> >From 24d4de52c8186c1ec1787e76d13e22646d804a53 Mon Sep 17 00:00:00 2001
>> From: Akira Yokosawa <akiyks@gmail.com>
>> Date: Sun, 13 Aug 2017 11:00:48 +0900
>> Subject: [PATCH 0/5] Style guide updates
>>
>> Hi Paul,
>>
>> The style guide needs some updates regarding recent changes in
>> litmus tests in memory barriers section. (Patch #3)
>> Also I recovered the tweaks in table layout. I added another
>> option to color rows alternately. (Patch #1 and #2)
>> Patch #4 is my attempt to convince you that using commas for
>> digit grouping should be regarded as harmful in global POV.
>> My suggestion is to use \num{} commands in LaTeX source and
>> let a reader to pick a style of his/her choice.
>>
>> \num{} command can slow down pdflatex processing somewhat,
>> but should be acceptable on modern platforms.
>>
>> Thoughts?
> 
> Applied and pushed, thank you!
> 
> Table D.3 looks fine, but it only has thee columns.  If it had more
> columns or was wider or variable-depth rows, it would be hard to read.

And I said in the guide, "especially in tables of simple structure."
Large tables need case-by-case tuning, I suppose.

> Table D.4 looks good to me, but I (intentionally) have not yet looked
> at what you had to do in LaTeX to make it happen.  ;-)

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.

         Thanks, Akira

> 
> 							Thanx, Paul
> 
>>         Thanks, Akira
>> --
>> Akira Yokosawa (5):
>>   styleguide: Add examples of alternative table layout
>>   styleguide: Tweak layout of 'Limitation' table
>>   styleguide: Update LaTeX source of code snippet
>>   styleguide: Add example of options to \num{} command
>>   styleguide: Emphasize source part of epigraph
>>
>>  appendix/styleguide/samplecodesnippet.tex    |  19 --
>>  appendix/styleguide/samplecodesnippetfig.tex |  19 ++
>>  appendix/styleguide/samplecodesnippetlst.tex |  19 ++
>>  appendix/styleguide/styleguide.tex           | 375 ++++++++++++++++++---------
>>  perfbook.tex                                 |   5 +-
>>  5 files changed, 301 insertions(+), 136 deletions(-)
>>  delete mode 100644 appendix/styleguide/samplecodesnippet.tex
>>  create mode 100644 appendix/styleguide/samplecodesnippetfig.tex
>>  create mode 100644 appendix/styleguide/samplecodesnippetlst.tex
>>
>> -- 
>> 2.7.4
>>
> 
> 

Re: [PATCH 0/5] Style guide updates

[Paul E. McKenney]

On Mon, Aug 14, 2017 at 08:24:08AM +0900, Akira Yokosawa wrote:
> On 2017/08/13 10:26:24 -0700, Paul E. McKenney wrote:
> > On Sun, Aug 13, 2017 at 12:27:52PM +0900, Akira Yokosawa wrote:
> >> >From 24d4de52c8186c1ec1787e76d13e22646d804a53 Mon Sep 17 00:00:00 2001
> >> From: Akira Yokosawa <akiyks@gmail.com>
> >> Date: Sun, 13 Aug 2017 11:00:48 +0900
> >> Subject: [PATCH 0/5] Style guide updates
> >>
> >> Hi Paul,
> >>
> >> The style guide needs some updates regarding recent changes in
> >> litmus tests in memory barriers section. (Patch #3)
> >> Also I recovered the tweaks in table layout. I added another
> >> option to color rows alternately. (Patch #1 and #2)
> >> Patch #4 is my attempt to convince you that using commas for
> >> digit grouping should be regarded as harmful in global POV.
> >> My suggestion is to use \num{} commands in LaTeX source and
> >> let a reader to pick a style of his/her choice.
> >>
> >> \num{} command can slow down pdflatex processing somewhat,
> >> but should be acceptable on modern platforms.
> >>
> >> Thoughts?
> > 
> > Applied and pushed, thank you!
> > 
> > Table D.3 looks fine, but it only has thee columns.  If it had more
> > columns or was wider or variable-depth rows, it would be hard to read.
> 
> And I said in the guide, "especially in tables of simple structure."
> Large tables need case-by-case tuning, I suppose.

I expect so!

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.

> > Table D.4 looks good to me, but I (intentionally) have not yet looked
> > at what you had to do in LaTeX to make it happen.  ;-)
> 
> 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.

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.

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

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.

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

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?

							Thanx, Paul

>          Thanks, Akira
> 
> > 
> > 							Thanx, Paul
> > 
> >>         Thanks, Akira
> >> --
> >> Akira Yokosawa (5):
> >>   styleguide: Add examples of alternative table layout
> >>   styleguide: Tweak layout of 'Limitation' table
> >>   styleguide: Update LaTeX source of code snippet
> >>   styleguide: Add example of options to \num{} command
> >>   styleguide: Emphasize source part of epigraph
> >>
> >>  appendix/styleguide/samplecodesnippet.tex    |  19 --
> >>  appendix/styleguide/samplecodesnippetfig.tex |  19 ++
> >>  appendix/styleguide/samplecodesnippetlst.tex |  19 ++
> >>  appendix/styleguide/styleguide.tex           | 375 ++++++++++++++++++---------
> >>  perfbook.tex                                 |   5 +-
> >>  5 files changed, 301 insertions(+), 136 deletions(-)
> >>  delete mode 100644 appendix/styleguide/samplecodesnippet.tex
> >>  create mode 100644 appendix/styleguide/samplecodesnippetfig.tex
> >>  create mode 100644 appendix/styleguide/samplecodesnippetlst.tex
> >>
> >> -- 
> >> 2.7.4
> >>
> > 
> > 
>