On 2018/11/11 08:45:00 -0800, Paul E. McKenney wrote:
> 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@xxxxxxxxx>
>>> Date: Mon, 11 Nov 2018 23:30:04 +0900
>>> Subject: [PATCH] styleguide: Update code snippet section
>>>
>>> Signed-off-by: Akira Yokosawa <akiyks@xxxxxxxxx>
>>> ---
>>> 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. ;-)
There might be other restrictions I'm not aware of.
>>
>> 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.
Thank you for looking into this. Yes, "obsolete" sounds a common
word choice. Native review is the most precious feedback for me!
>
> 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.
Ah, this is much closer to what I had in mind.
Anyway, the introduction of new scheme needs further polishing.
The goal of embedding line labels in code samples should come first.
And we need to fix the typo of "primitve", ugh...
I'll send a patch soon.
Thanks, Akira
>
> @@ -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}
>
