>From e0403ba8882761c59d52e8d65e5c65ab6e85ca29 Mon Sep 17 00:00:00 2001
From: Akira Yokosawa <akiyks@xxxxxxxxx>
Date: Wed, 19 Jul 2017 19:36:36 +0900
Subject: [PATCH 01/10] appendix: Add style guide
In response to Paul's suggestion, add style guide in Appendix.
This is the first draft with no additional package used.
Signed-off-by: Akira Yokosawa <akiyks@xxxxxxxxx>
---
appendix/appendix.tex | 1 +
appendix/styleguide/samplecodesnippet.tex | 19 +
appendix/styleguide/styleguide.tex | 682 ++++++++++++++++++++++++++++++
3 files changed, 702 insertions(+)
create mode 100644 appendix/styleguide/samplecodesnippet.tex
create mode 100644 appendix/styleguide/styleguide.tex
diff --git a/appendix/appendix.tex b/appendix/appendix.tex
index dc80e17..d246a7f 100644
--- a/appendix/appendix.tex
+++ b/appendix/appendix.tex
@@ -4,6 +4,7 @@
\include{appendix/questions/questions}
\include{appendix/toyrcu/toyrcu}
\include{appendix/whymb/whymemorybarriers}
+\include{appendix/styleguide/styleguide}
\QuickQuizAnswers
\input{glossary.tex}
\IfTwoColumn{
diff --git a/appendix/styleguide/samplecodesnippet.tex b/appendix/styleguide/samplecodesnippet.tex
new file mode 100644
index 0000000..9020805
--- /dev/null
+++ b/appendix/styleguide/samplecodesnippet.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/styleguide.tex b/appendix/styleguide/styleguide.tex
new file mode 100644
index 0000000..72b8ca0
--- /dev/null
+++ b/appendix/styleguide/styleguide.tex
@@ -0,0 +1,682 @@
+% appendix/styleguide/styleguide.tex
+% SPDX-License-Identifier: CC-BY-SA-3.0
+
+\chapter{Style Guide}
+\label{chp:app:styleguide:Style Guide}
+
+This appendix is a collection of style guides which is intended
+as a reference to improve consistency in perfbook. It also contains
+several suggestions and their experimental examples.
+
+Section~\ref{sec:app:styleguide:Paul's Conventions} describes basic
+punctuation and spelling rules.
+Section~\ref{sec:app:styleguide:NIST Style Guide} explains rules
+related to unit symbols.
+Section~\ref{sec:app:styleguide:LaTeX Conventions} summarizes
+\LaTeX-specific conventions.
+
+\section{Paul's Conventions}
+\label{sec:app:styleguide:Paul's Conventions}
+
+Following is the list of Paul's conventions assembled from his
+answers to Akira's questions regarding perfbook's punctuation policy.
+
+\begin{itemize}
+\item (On punctuations and quotations)
+ Despite being American myself, for this sort of book, the UK approach
+ is better because it removes ambiguities like the following:
+ \begin{quote}
+ Type ``\nbco{ls -a},'' look for the file ``\co{.},''
+ and file a bug if you don't see it.
+ \end{quote}
+
+ The following is much more clear:
+ \begin{quote}
+ Type ``\nbco{ls -a}'', look for the file ``\co{.}'',
+ and file a bug if you don't see it.
+ \end{quote}
+\item American English spelling: ``color'' rather than ``colour''.
+\item Oxford comma: ``a, b, and~c'' rather than ``a, b and~c''.
+ This is arbitrary. Cases where the Oxford comma results in ambiguity
+ should be reworded, for example, by introducing numbering: ``a,
+ b, and c and~d'' should be ``(1)~a, (2)~b, and (3)~c and~d''.
+\item Italic for emphasis. Use sparingly.
+\item \verb|\co{}| for identifiers, \verb|\url{}| for URLs,
+ \verb|\path{}| for filenames.
+\item Dates should use an unambiguous format. Never ``mm/dd/yy''
+ or ``dd/mm/yy'', but rather ``July 26, 2016'' or ``26 July 2016''
+ or ``26-Jul-2016'' or ``2016/07/26''. I tend to use
+ \path{yyyy.mm.ddA} for filenames, for example.
+\item North American rules on periods and abbreviations.
+ For example neither of the following can reasonably be interpreted
+ as two sentences:
+ \begin{itemize}
+ \item Say hello, to Mr. Jones.
+ \item If it looks like she sprained her ankle, call Dr. Smith and
+ then tell her to keep the ankle iced and elevated.
+ \end{itemize}
+
+ An ambiguous example:
+ \begin{quote}
+ If I take the cow, the pig, the horse, etc. George will be upset.
+ \end{quote}
+ can be written with more words:
+ \begin{quote}
+ If I take the cow, the pig, the horse, or much of anything else,
+ George will be upset.
+ \end{quote}
+ or:
+ \begin{quote}
+ If I take the cow, the pig, the horse, etc., George will be upset.
+ \end{quote}
+\item I don't like ampersand (``\&'') in headings, but will sometimes
+ use it if doing so prevents a line break in that heading.
+\item When mentioning words, I use quotations. When introducing
+ a new word, I use \verb|\emph{}|.
+\end{itemize}
+
+\section{NIST Style Guide}
+\label{sec:app:styleguide:NIST Style Guide}
+
+\subsection{Unit Symbol}
+\label{sec:app:styleguide:Unit Symbol}
+
+\subsubsection{SI Unit Symbol}
+\label{sec:app:styleguide:SI Unit Symbol}
+
+NIST style guide\footnote{
+ \url{https://www.nist.gov/pml/nist-guide-si-chapter-7-rules-and-style-conventions-expressing-values-quantities}}
+states the following rules (rephrased for perfbook).
+% cite: https://www.nist.gov/pml/nist-guide-si-chapter-7-rules-and-style-conventions-expressing-values-quantities
+
+\begin{itemize}
+\item When SI unit symbols such as ``ns'', ``MHz'', and ``K'' (kelvin)
+are used behind numerical values, narrow spaces should be placed between
+the values and the symbols.
+
+A narrow space can be coded in \LaTeX{} by the sequence of
+\qco{\\,}.
+For example,
+\begin{quote}
+ ``2.4\,GHz'', rather then ``2.4GHz''.
+\end{quote}
+
+\item Even when the value is used in adjectival sense, a narrow space
+should be placed. For example,
+\begin{quote}
+ ``a~10\,ms interval'', rather than ``a~10\=/ms interval'' nor
+ ``a~10ms interval''.
+\end{quote}
+\end{itemize}
+
+The symbol of micro (\micro :$10^{-6}$) can be typeset easily by
+the help of ``gensymb'' \LaTeX\ package.
+A macro \qco{\\micro} can be used in both text and
+math modes. To typeset the symbol of ``microsecond'', you can do
+so by \qco{\\micro s}. For example,
+\begin{quote}
+ 10\,\micro s
+\end{quote}
+
+Note that math mode \qco{\\mu} is italic by default and should not
+be used as a prefix. An improper example:
+\begin{quote}
+ 10\,$\mu $s (math mode \qco{\\mu})
+\end{quote}
+
+\subsubsection{Non-SI Unit Symbol}
+\label{sec:app:styleguide:Non-SI Unit Symbol}
+
+Although NIST style guide does not cover non-SI unit symbols
+such as ``KB'', ``MB'', and ``GB'', the same rule should be followed.
+
+Example:
+
+\begin{quote}
+ ``A~240\,GB hard drive'', rather than ``a~240\=/GB hard drive''
+ nor ``a~240GB hard drive''.
+\end{quote}
+
+Strictly speaking, NIST guide requires us to use the binary prefixes
+``Ki'', ``Mi'', or ``Gi'' to represent powers of~$2^{10}$.
+However, we accept the JEDEC conventions to use ``K'', ``M'',
+and ``G'' as binary prefixes in describing memory capacity.\footnote{
+ \url{https://www.jedec.org/standards-documents/dictionary/terms/mega-m-prefix-units-semiconductor-storage-capacity}}
+
+An acceptable example:
+\begin{quote}
+ ``8\,GB of main memory'', meaning ``8\,GiB of main memory''.
+\end{quote}
+
+Also, it is acceptable to use just ``K'', ``M'', or ``G'' as abbreviations
+appended to a numerical value, e.g., ``4K~entries''. In such cases, no space
+before an abbreviation is required. For example,
+
+\begin{quote}
+ ``8K entries'', rather than ``8\,K entries''.
+\end{quote}
+
+If you put a space in between, the symbol looks like a unit symbol and
+is confusing.
+Note that ``K'' and ``k'' represent $2^{10}$ and $10^3$, respectively.
+``M'' can represent either $2^{20}$ or $10^6$, and ``G'' can represent
+either $2^{30}$ or $10^9$. These ambiguities should not be confusing
+in discussing approximate order.
+
+\subsubsection{Degree Symbol}
+\label{sec:app:styleguide:Degree Symbol}
+
+The angular-degree symbol (\degree) does not require any space in front
+of it. NIST style guide clearly states so.
+
+The symbol of degree can also be typeset easily by the help of gensymb
+package.
+A macro \qco{\\degree} can be used in both text and math modes.
+
+Example:
+
+\begin{quote}
+ $45\degree$, rather than $45\,\degree$.
+\end{quote}
+
+\subsection{NIST Guide Yet To Be Followed}
+\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.
+
+\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.
+
+\begin{quote}
+\begin{tabular}{ll}
+ NIST guide:& 50\,\% possibility\\
+ Our conventions:& 50\% possibility\\
+\end{tabular}
+\end{quote}
+
+\subsubsection{Font Style}
+\label{sec:app:styleguide:Font Style}
+
+Quote from NIST check list:\footnote{
+ \#6 in \url{https://physics.nist.gov/cuu/Units/checklist.html}
+}
+
+\begin{quote}
+ Variables and quantity symbols are in italic type. Unit symbols
+ are in roman type. Numbers should generally be written in roman
+ type. These rules apply irrespective of the typeface used in
+ the surrounding text.
+\end{quote}
+
+For example,
+\begin{quote}
+ {\textit e} (elementary charge)
+\end{quote}
+
+On the other hand, mathematical constants such as the base
+of natural logarithms should be roman.\footnote{
+ \url{https://physics.nist.gov/cuu/pdf/typefaces.pdf}
+}
+For example,
+
+\begin{quote}
+ $\mathrm{e}^x$
+\end{quote}
+
+In this textbook, this rule is not much considered as of this writing.
+Most letters in math mode are italic regardless of what they
+represent. Exceptions are uppercase Greek letters, which are upright
+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
+\section{\LaTeX\ Conventions}
+\label{sec:app:styleguide:LaTeX Conventions}
+
+Good looking \LaTeX\ documents require further considerations
+on proper use of font styles, line break exceptions, etc.
+This section summarizes guidelines specific to \LaTeX.
+
+\subsection{Monospace Font}
+\label{sec:app:styleguide:Monospace Font}
+
+Monospace font (or typewriter font) is heavily used in this textbook.
+First policy regarding monospace font in perfbook is to avoid
+directly using \qco{\\texttt} or \qco{\\tt} macro.
+It is highly recommended to use a macro or an environment
+indicating the reason why you want the font.
+
+This section explains the use cases of such macros and environments.
+
+\subsubsection{Code Snippet}
+\label{sec:app:styleguide:Code Snippet}
+
+Although the ``verbatim'' environment is commonly used to include
+listings, we use the ``verbbox'' environment provided by the
+``verbatimbox'' package for most code snippets to enable the
+centering layout.
+
+% Another option would be the ``lstlisting'' environment provided
+% by the ``listings'' package. We are already using its ``lstinline''
+% command in the definition of \co{\\co\{\}} macro.
+
+\begin{figure}[tbh]
+{ \scriptsize
+\verbfilebox[{\makebox[5ex][r]{\arabic{VerbboxLineNo}:\hspace{2ex}}}]
+ {appendix/styleguide/samplecodesnippet.tex}
+}
+\centering
+\theverbbox
+\caption{\LaTeX\ Source of Sample Code Snippet}
+\label{fig:app:styleguide:LaTeX Source of Sample Code Snippet}
+\end{figure}
+
+\input{appendix/styleguide/samplecodesnippet}
+
+The \LaTeX\ source of a sample code snippet is shown in
+Figure~\ref{fig:app:styleguide:LaTeX Source of Sample Code Snippet}
+and is typeset as show in
+Figure~\ref{fig:app:styleguide:Sample Code Snippet}.
+
+Note that the verbbox environment is placed inside the figure 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.
+
+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. See the source of this Section
+ in \path{appendix/styleguide/styleguide.tex}
+ if you are interested.}
+
+The verbatim environment is used for listings with too many lines
+to fit in a column. It is also used to avoid overwhelming
+\LaTeX\ with a lot of floating objects.
+
+\subsubsection{Identifier}
+\label{sec:app:styleguide:Identifier}
+
+We use ``\verb|\co{}|'' macro for inline identifiers.
+(``co'' stands for ``code''.)
+
+By putting them into \verb|\co{}|, underscore characters in
+their names are free of escaping in \LaTeX\ source. It is convenient
+to search them in source files. Also, \verb|\co{}|
+macro has a capability to permit line breaks at particular
+sequences of letters. Current definition permits a line break at
+an underscore (\tco{_}), two consecutive underscores (\tco{__}),
+a white space, or an operator \tco{->}.
+
+\subsubsection{Identifier inside Table and Heading}
+\label{sec:app:styleguide:Identifier inside Table and Heading}
+
+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
+estimation of those environments.
+Furthermore, \verb|\co{}| can not be safely used in section headings nor
+description headings.
+
+As a workaround, we use ``\verb|\tco{}|'' command
+inside tables and headings. It has no capability of line break
+at particular sequences, but still frees us from escaping
+underscores.
+
+When used in text, \verb|\tco{}| permits line breaks at
+white spaces.
+
+\subsubsection{Other Use Cases of Monospace Font}
+\label{sec:app:styleguide:Other Use Cases of Monospace Font}
+
+For URLs, we use ``\verb|\url{}|'' command provided by the
+``hyperref'' package. It will generate hyper references to the
+URLs.
+
+For path names, we use ``\verb|\path{}|'' command. It won't
+generate hyper references.
+
+Both \verb|\url{}| and \verb|\path{}| permit line breaks
+at \qco{/}, \qco{-}, and \qco{.}.\footnote{
+ Overfill can be a problem if the URL or the path name contains
+ long runs of unbreakable characters.
+}
+
+For short monospace statements not to be line broken, we use
+the ``\verb|\nbco{}|'' (non-breakable co) macro.
+
+\subsubsection{Limitations}
+\label{sec:app:styleguide:Limitations}
+
+There are a few cases where macros introduced in this section
+do not work as expected.
+Table~\ref{tab:app:styleguide:Limitation of Monospace Macro}
+lists such limitations.
+
+\begin{table}[tbh]
+\centering\footnotesize
+\begin{tabular}{lll}
+ Macro & Need Escape & Should Avoid \\
+ \hline
+ \co{\\co}, \co{\\nbco} & \co{\\}, \%, \{, \} & \\
+ \co{\\tco} & \# & \%, \{, \}, \co{\\} \\
+\end{tabular}
+\caption{Limitation of Monospace Macro}
+\label{tab:app:styleguide:Limitation of Monospace Macro}
+\end{table}
+
+While \verb|\co{}| requires some characters to be escaped,
+it can contain any character.
+
+On the other hand, \verb|\tco{}| can not handle
+\qco{\%}, \qco{\{}, \qco{\}}, nor \qco{\\} properly.
+If they are escaped by a~\qco{\\},
+they appear in the end result with the escape character.
+The \qco{\\verb} macro can be used in running text if you
+need to use monospace font for a string which contains
+many characters to escape.\footnote{
+ \co{\\verb} is not almighty though. For example, you can't use it
+ within a footnote nor table inside ``floatrow'' environment mentioned
+ later. If you do so, you will see a fatal latex error.
+ There are several workarounds of this problem, but as for perfbook,
+ \co{\\co\{\}} should suffice.}
+
+\subsection{Non Breakable Spaces}
+\label{sec:app:styleguide:Non Breakable Spaces}
+
+In \LaTeX\ conventions, proper use of non-breakable white spaces
+is highly recommended. They can prevent widowing and orphaning
+of single digit numbers or short variable names, which would
+cause the text to be confusing at first glance.
+
+The thin space mentioned earlier to be placed in front of a unit
+symbol is non breakable.
+
+Other cases to use a non-breakable space (``\verb|~|'' in \LaTeX\
+source, often referred to as ``nbsp'')
+are the following (inexhaustive).
+
+\begin{itemize}
+\item Reference to a Chapter or a Section:
+ \begin{quote}
+ Please refer to Section~\ref{sec:app:styleguide:NIST Style Guide}.
+ \end{quote}
+\item Calling out CPU number or Thread name:
+ \begin{quote}
+ After they load the pointer, CPUs~1 and~2 will see the stored
+ value.
+ \end{quote}
+\item Short variable name:
+ \begin{quote}
+ The results will be stored in variables~\co{a} and~\co{b}.
+ \end{quote}
+\end{itemize}
+
+\subsection{Hyphenation and Dashes}
+\label{sec:app:styleguide:Hyphenation and Dashes}
+
+\subsubsection{Hyphenation in Compound Word}
+\label{sec:app:styleguide:Hyphenation in Compound Word}
+
+In plain \LaTeX, compound words such as ``high-frequency''
+can be hyphenated only at the hyphen. This sometimes results
+in poor typesetting. For example:
+
+\begin{center}\begin{minipage}{2.55in}\vspace{0.6\baselineskip}
+ High-frequency radio wave, high-frequency radio wave,
+ high-frequency radio wave, high-frequency radio wave,
+ high-frequency radio wave, high-frequency radio wave.
+\vspace{0.6\baselineskip}\end{minipage}\end{center}
+
+By using a shortcut \qco{\\-/} provided by the
+``extdash'' package, hyphenation in elements of compound
+words is enabled in perfbook.\footnote{
+ In exchange for enabling the shortcut, we can't use plain
+ \LaTeX's shortcut \qco{\\-} to specify hyphenation points.
+ Use \path{pfhyphex.tex} to add such exceptions.
+}
+
+Example with \qco{\\-/}:
+
+\begin{center}\begin{minipage}{2.55in}\vspace{0.6\baselineskip}
+ High\-/frequency radio wave, high\-/frequency radio wave,
+ high\-/frequency radio wave, high\-/frequency radio wave,
+ high\-/frequency radio wave, high\-/frequency radio wave.
+\vspace{0.6\baselineskip}\end{minipage}\end{center}
+
+\subsubsection{Non Breakable Hyphen}
+\label{sec:app:styleguide:Non Breakable Hyphen}
+
+We want hyphenated compound terms such as ``x\=/coordinate'',
+``y\=/coordinate'', etc. not to be broken at the hyphen
+following a single letter.
+
+To make a hyphen unbreakable, we can use a short cut
+\qco{\\=/} also provided by the ``extdash'' package.
+
+Example without a shortcut:
+
+\begin{center}\begin{minipage}{2.55in}\vspace{0.6\baselineskip}
+x-, y-, and z-coordinates; x-, y-, and z-coordinates;
+x-, y-, and z-coordinates; x-, y-, and z-coordinates;
+x-, y-, and z-coordinates; x-, y-, and z-coordinates;
+\vspace{0.6\baselineskip}\end{minipage}\end{center}
+
+Example with \qco{\\-/}:
+
+\begin{center}\begin{minipage}{2.55in}\vspace{0.6\baselineskip}
+x-, y-, and z\-/coordinates; x-, y-, and z\-/coordinates;
+x-, y-, and z\-/coordinates; x-, y-, and z\-/coordinates;
+x-, y-, and z\-/coordinates; x-, y-, and z\-/coordinates;
+\vspace{0.6\baselineskip}\end{minipage}\end{center}
+
+Example with \qco{\\=/}:
+
+\begin{center}\begin{minipage}{2.55in}\vspace{0.6\baselineskip}
+x-, y-, and z\=/coordinates; x-, y-, and z\=/coordinates;
+x-, y-, and z\=/coordinates; x-, y-, and z\=/coordinates;
+x-, y-, and z\=/coordinates; x-, y-, and z\=/coordinates;
+\vspace{0.6\baselineskip}\end{minipage}\end{center}
+
+Note that \qco{\\=/} enables hyphenation in elements
+of compound words as the same as \qco{\\-/} does.
+
+\subsubsection{Em Dash}
+\label{sec:app:styleguide:Em Dash}
+
+Em dashes are used to indicate parenthetic expression. In perfbook,
+em dashes are placed without spaces around it. In \LaTeX\ source,
+an em dash is represented by \qco{---}.
+
+Example (quote from Section~\ref{sec:app:whymb:Cache Structure}):
+\begin{quote}
+ This disparity in speed---more than two orders of magnitude---has
+ resulted in the multi-megabyte caches found on modern CPUs.
+\end{quote}
+
+\subsubsection{En Dash}
+\label{sec:app;styleguide:En Dash}
+
+In \LaTeX\ convention, en~dashes (\==) are used for a range of (mostly)
+numbers.
+However, this is not followed in perfbook at all.
+Because of the heavy use of dashes (\=/) for such cases
+in plain-text communication, to make the \LaTeX\ sources compatible
+with them, plain dashes are kept unmodified in the sources.
+
+As a compromise, for those who are accustomed to en~dashes representing
+ranges, there is a script to substitute en~dashes for plain dashes.
+
+If you have the git repository of perfbook, by using a script
+\path{utilities/dohyphen2endash.sh}, you can do the substitutions.
+The script works only when you are in a clean git repository.
+Otherwise it will just abort to prevent you from losing local
+changes.
+
+Example with a simple dash:
+
+\begin{quote}
+ Lines~4\=/12 in
+ Figure~\ref{fig:app:styleguide:LaTeX Source of Sample Code Snippet}
+ are the contents of the verbbox environment. The box is output
+ by the \co{\\theverbbox} macro on line~16.
+\end{quote}
+
+Example with an en dash:
+
+\begin{quote}
+ Lines~4\==12 in
+ Figure~\ref{fig:app:styleguide:LaTeX Source of Sample Code Snippet}
+ are the contents of the verbbox environment. The box is output
+ by the \co{\\theverbbox} macro on line~16.
+\end{quote}
+
+\subsubsection{Numerical Minus Sign}
+\label{sec:app:styleguide:Numerical Minus Sign}
+
+Numerical minus signs should be coded as math mode minus signs,
+namely \qco{$-$}. For example,
+
+\begin{quote}
+ $-30$, rather than -30.
+\end{quote}
+
+\subsection{Improvement Candidates}
+\label{sec:app:styleguide:Improvement Candidates}
+
+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 ``floatrow'' package would be of help.
+
+% TODO: Add example
+
+\subsubsection{Position of Caption}
+\label{sec:app:styleguide:Position of Caption}
+
+In \LaTeX\ conventions, captions of tables should be 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 floatrow package mentioned above also has the capability
+to adjust layout of caption.
+
+% TODO: Add example
+
+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.
+
+\subsubsection{Grouping Related Figures/Listings}
+\label{sec:app:styleguide:Grouping Related Figures/Listings}
+
+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 environment.
+The floatrow package provides the features to do so.\footnote{
+ Note that the ``subfigure'' package currently declared in the
+ preamble is not used any more.
+ The floatrow package is the choice to group floating environments
+ these days.
+ One problem of grouping figures might be the learning curve
+ to do so.}
+
+% TODO: Add example
+
+\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.
+
+% TODO: Add example
+
+\subsubsection{Miscellaneous Candidates}
+\label{sec:app:styleguide:Miscellaneous Candidates}
+
+Other improvement candidates are listed in the source of this
+section as comments.
+
+% Capitalize initialism:
+% Gnu Compiler Collection = GCC
+% gcc should be used as a command name in \co{gcc}
+% When mentioning GCC's C language, use `GNU C'
+%
+% 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.
+%
+% Power or POWER?
+% IBM's trademark page at https://www.ibm.com/legal/us/en/copytrade.shtml#section-P
+% lists the following.
+% PowerPC
+% Power Architecture
+% Power
+% POWER
+% POWER5
+% POWER6
+%
+% not Power5, POWER 5, nor Power-5
+%
+% Ugly line break by \co{}
+% __
+% atomic_store()
+%
+% seqlock_
+% t
+%
+% Is there any way to prevent these breaks?
+% Maybe we need an on-the-fly script to convert such \co{}s
+% to couples of \co{}s.
+% Example:
+% \co{__atomic_store()} -> \co{__}\co{atomic_store()}
+% \co{seqlock_t} -> \co{seqlock_}\co{t}
--
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
