On Mon, Nov 12, 2018 at 11:39:03PM +0900, Akira Yokosawa wrote:
> 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.
That is the usual situation. ;-)
> >> 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!
Interestingly enough, non-native feedback is similarly valuable for me.
Smooth wording can hide mistakes from native speakers. ;-)
Thanx, Paul
> > 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}
> >
>
