Re: [PATCH] styleguide: Update code snippet section

["Paul E. McKenney" <paulmck@linux.ibm.com>]

On Sun, Nov 11, 2018 at 08:03:37AM -0800, Paul E. McKenney wrote:
> On Sun, Nov 11, 2018 at 11:44:54PM +0900, Akira Yokosawa wrote:
> > >From c821c6c678197b760a4c08c7bfdba370bdd31a71 Mon Sep 17 00:00:00 2001
> > From: Akira Yokosawa <akiyks@gmail.com>
> > Date: Mon, 11 Nov 2018 23:30:04 +0900
> > Subject: [PATCH] styleguide: Update code snippet section
> > 
> > Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
> > ---
> > Hi Paul,
> > 
> > This updates Style Guide to describe new scheme of code snippet.
> > Although there still remain rough edges, hopefully it would cover
> > essential info.
> 
> Very good, thank you!  I was unaware of some of the restrictions for
> comments in litmus tests, so this is very welcome documentation.  ;-)
> 
> Queued, will be pushed soon.

And of course when reading it, I could not resist the urge to make
a couple of edits.  Please note that your use of "obsolescent" is not
wrong, just a bit unusual, hence my substitution of "obsolete".
Please see below for a delta patch which I merged into your original,
and please let me know if I messed anything up.

Oh, and \qco{} looks handy!  ;-)

							Thanx, Paul

------------------------------------------------------------------------

diff --git a/appendix/styleguide/samplecodesnippetlst.tex b/appendix/styleguide/samplecodesnippetlst.tex
index 65a1f489587d..b18922e763b3 100644
--- a/appendix/styleguide/samplecodesnippetlst.tex
+++ b/appendix/styleguide/samplecodesnippetlst.tex
@@ -14,6 +14,6 @@ int main(void)
 }
 \centering
 \theverbbox
-\caption{Sample Code Snippet (Obsolescent)}
-\label{lst:app:styleguide:Sample Code Snippet (Obsolesc)}
+\caption{Sample Code Snippet (Obsolete)}
+\label{lst:app:styleguide:Sample Code Snippet (Obsolete)}
 \end{listing}
diff --git a/appendix/styleguide/samplecodesnippetlstlbl.tex b/appendix/styleguide/samplecodesnippetlstlbl.tex
index 8ee8b5d4acf2..d3e4a9533d89 100644
--- a/appendix/styleguide/samplecodesnippetlstlbl.tex
+++ b/appendix/styleguide/samplecodesnippetlstlbl.tex
@@ -14,6 +14,6 @@ int main(void)
 }
 \centering
 \theverbbox			%lnlbl@theverbbox$
-\caption{Sample Code Snippet (Obsolescent)}
-\label{lst:app:styleguide:Sample Code Snippet (Obsolesc)}
+\caption{Sample Code Snippet (Obsolete)}
+\label{lst:app:styleguide:Sample Code Snippet (Obsolete)}
 \end{listing}
diff --git a/appendix/styleguide/styleguide.tex b/appendix/styleguide/styleguide.tex
index 0a94c1c93555..058789803f59 100644
--- a/appendix/styleguide/styleguide.tex
+++ b/appendix/styleguide/styleguide.tex
@@ -322,7 +322,7 @@ This section explains the use cases of such macros and environments.
 \subsubsection{Code Snippet}
 \label{sec:app:styleguide:Code Snippet}
 
-Although the \qco{verbatim} environment is a primitve way to include
+Because the \qco{verbatim} environment is a primitve way to include
 listings, we are transitioning to a new scheme which uses
 the \qco{fancyvrb} package for code snippets.
 
@@ -351,7 +351,7 @@ They are defined in the preamble as shown below:
 
 We used to use the \qco{verbbox} environment provided
 by the \qco{verbatimbox} package. As will be described later in
-Section~\ref{sec:app:styleguide:Code Snippet (Obsolesc)},
+Section~\ref{sec:app:styleguide:Code Snippet (Obsolete)},
 \co{verbbox} has the capability of automatic
 line numbering. However, it is not possible to embed labels on lines
 in the snippet to refer from the text.
@@ -516,7 +516,7 @@ exists (0:r1=0)  // comment after test body
 \end{VerbatimN}
 \end{linelabel}
 
-To avoid parse error, meta commands in litmus tests (C flavour) are embedded
+To avoid parse errors, meta commands in litmus tests (C flavour) are embedded
 in the following way.
 
 \begin{linelabel}[ln:app:styleguide:Sample Source of Litmus Test]
@@ -601,14 +601,14 @@ Note that each litmus test's source file can contain at most one
 pair of \co{\\begin[snippet]} and \co{\\end[snippet]} because of
 the restriction of comments.
 
-\subsubsection{Code Snippet (Obsolescent)}
-\label{sec:app:styleguide:Code Snippet (Obsolesc)}
+\subsubsection{Code Snippet (Obsolete)}
+\label{sec:app:styleguide:Code Snippet (Obsolete)}
 
 Sample \LaTeX\ source of a code snippet coded using
 the \qco{verbatimbox} package is shown in
-Listing~\ref{lst:app:styleguide:LaTeX Source of Sample Code Snippet (Obsolesc)}
+Listing~\ref{lst:app:styleguide:LaTeX Source of Sample Code Snippet (Obsolete)}
 and is typeset as shown in
-Listing~\ref{lst:app:styleguide:Sample Code Snippet (Obsolesc)}.
+Listing~\ref{lst:app:styleguide:Sample Code Snippet (Obsolete)}.
 
 \begin{listing}[tb]
 \begin{linelabel}[ln:app:styleguide:samplecodesnippetlstlbl]
@@ -616,8 +616,8 @@ Listing~\ref{lst:app:styleguide:Sample Code Snippet (Obsolesc)}.
 \VerbatimInput{appendix/styleguide/samplecodesnippetlstlbl.tex}
 \end{linelabel}
 \vspace*{-9pt}
-\caption{\LaTeX\ Source of Sample Code Snippet (Obsolescent)}
-\label{lst:app:styleguide:LaTeX Source of Sample Code Snippet (Obsolesc)}
+\caption{\LaTeX\ Source of Sample Code Snippet (Obsolete)}
+\label{lst:app:styleguide:LaTeX Source of Sample Code Snippet (Obsolete)}
 \end{listing}
 
 \input{appendix/styleguide/samplecodesnippetlst.tex}
@@ -625,7 +625,7 @@ Listing~\ref{lst:app:styleguide:Sample Code Snippet (Obsolesc)}.
 The auto\-/numbering feature of \co{verbbox} is enabled by
 the ``\verb|\LstLineNo|'' macro specified in the option to verbbox
 (line~\ref{ln:app:styleguide:samplecodesnippetlstlbl:lineno} in
-Listing~\ref{lst:app:styleguide:LaTeX Source of Sample Code Snippet (Obsolesc)}).
+Listing~\ref{lst:app:styleguide:LaTeX Source of Sample Code Snippet (Obsolete)}).
 The macro is defined in the preamble of \path{perfbook.tex}
 as follows:
 
@@ -865,7 +865,7 @@ Example with a simple dash:
 \begin{quote}
 \begin{lineref}[ln:app:styleguide:samplecodesnippetlstlbl]
   Lines~\lnref{b}\=/\lnref{e} in
-  Listing~\ref{lst:app:styleguide:LaTeX Source of Sample Code Snippet (Obsolesc)}
+  Listing~\ref{lst:app:styleguide:LaTeX Source of Sample Code Snippet (Obsolete)}
   are the contents of the verbbox environment. The box is output
   by the \co{\\theverbbox} macro on line~\lnref{theverbbox}.
 \end{lineref}
@@ -876,7 +876,7 @@ Example with an en dash:
 \begin{quote}
 \begin{lineref}[ln:app:styleguide:samplecodesnippetlstlbl]
   Lines~\lnref{b}\==\lnref{e} in
-  Listing~\ref{lst:app:styleguide:LaTeX Source of Sample Code Snippet (Obsolesc)}
+  Listing~\ref{lst:app:styleguide:LaTeX Source of Sample Code Snippet (Obsolete)}
   are the contents of the verbbox environment. The box is output
   by the \co{\\theverbbox} macro on line~\lnref{theverbbox}.
 \end{lineref}