Return-Path: DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=to:cc:from:subject:message-id:date:user-agent:mime-version :content-language:content-transfer-encoding; bh=jfAXy/Ld3CU9M/XiBI2c8h2Q8GBAnleHLwlb547LE2A=; b=W2onQ34hzH/N1FIBygjzbV7AD11PnX55r+BrA5R5Y2aadhqwD934xnYv5MLUTn2pZM KyzDnSTqVm1MvmdGVoQlaF9o/SFrB4dnqT3qXNVA2Qdz1Y6m3MX82LQSbeXzSbxOoKBK ENc6bn94KtWjIGr9LSRCtBnbaktsW//zxAUlXijOdO224joSkXVCF3OWET0layUtOswD SKEHibDb5ahvWA9q2w4spWp4uwS4oSuvKZZDTfkgV9LWPy2/8/KYw01A9pb3h5TD6WJl UbhMypUVu8qI14dUsT78C8aY/8EMZXoHGNKYd6Pw9qLqySDmlHr67mHzqIuHfE+u6Iu0 DJ4w== From: Akira Yokosawa Subject: [PATCH] styleguide: Update code snippet section Message-ID: <8c68ad49-6c54-6ff1-e50d-09337be505c2@gmail.com> Date: Sun, 11 Nov 2018 23:44:54 +0900 MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Language: en-US Content-Transfer-Encoding: 7bit To: "Paul E. McKenney" Cc: perfbook@vger.kernel.org, Akira Yokosawa List-ID: From c821c6c678197b760a4c08c7bfdba370bdd31a71 Mon Sep 17 00:00:00 2001 From: Akira Yokosawa Date: Mon, 11 Nov 2018 23:30:04 +0900 Subject: [PATCH] styleguide: Update code snippet section Signed-off-by: Akira Yokosawa --- 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. Thanks, Akira -- appendix/styleguide/samplecodesnippet.c | 11 + appendix/styleguide/samplecodesnippetfcv.tex | 17 + appendix/styleguide/samplecodesnippetlst.tex | 4 +- appendix/styleguide/samplecodesnippetlstlbl.tex | 19 ++ appendix/styleguide/styleguide.tex | 399 ++++++++++++++++++------ 5 files changed, 359 insertions(+), 91 deletions(-) create mode 100644 appendix/styleguide/samplecodesnippet.c create mode 100644 appendix/styleguide/samplecodesnippetfcv.tex create mode 100644 appendix/styleguide/samplecodesnippetlstlbl.tex diff --git a/appendix/styleguide/samplecodesnippet.c b/appendix/styleguide/samplecodesnippet.c new file mode 100644 index 0000000..f58f656 --- /dev/null +++ b/appendix/styleguide/samplecodesnippet.c @@ -0,0 +1,11 @@ +//\begin{snippet}[labelbase=ln:base1,commandchars=\$\[\]] +/* + * Sample Code Snippet + */ +#include +int main(void) +{ + printf("Hello world!\n"); //\lnlbl{printf} + return 0; //\lnlbl{return} +} +//\end{snippet} diff --git a/appendix/styleguide/samplecodesnippetfcv.tex b/appendix/styleguide/samplecodesnippetfcv.tex new file mode 100644 index 0000000..4e03b2a --- /dev/null +++ b/appendix/styleguide/samplecodesnippetfcv.tex @@ -0,0 +1,17 @@ +\begin{listing}[tb] +\begin{linelabel}[ln:base1] %lnlbl~linelabel^ +\begin{VerbatimL}[commandchars=\$\[\]] +/* + * Sample Code Snippet + */ +#include +int main(void) +{ + printf("Hello world!\n"); $lnlbl[printf] + return 0; $lnlbl[return] +} +\end{VerbatimL} +\end{linelabel} +\caption{Sample Code Snippet} +\label{lst:app:styleguide:Sample Code Snippet} +\end{listing} diff --git a/appendix/styleguide/samplecodesnippetlst.tex b/appendix/styleguide/samplecodesnippetlst.tex index 06df5cc..65a1f48 100644 --- a/appendix/styleguide/samplecodesnippetlst.tex +++ b/appendix/styleguide/samplecodesnippetlst.tex @@ -14,6 +14,6 @@ int main(void) } \centering \theverbbox -\caption{Sample Code Snippet} -\label{lst:app:styleguide:Sample Code Snippet} +\caption{Sample Code Snippet (Obsolescent)} +\label{lst:app:styleguide:Sample Code Snippet (Obsolesc)} \end{listing} diff --git a/appendix/styleguide/samplecodesnippetlstlbl.tex b/appendix/styleguide/samplecodesnippetlstlbl.tex new file mode 100644 index 0000000..8ee8b5d --- /dev/null +++ b/appendix/styleguide/samplecodesnippetlstlbl.tex @@ -0,0 +1,19 @@ +\begin{listing} +{ \scriptsize +\begin{verbbox}[\LstLineNo] %lnlbl@lineno$ +/* %lnlbl@b$ + * Sample Code Snippet + */ +#include +int main(void) +{ + printf("Hello world!\n"); + return 0; +} %lnlbl@e$ +\end{verbbox} +} +\centering +\theverbbox %lnlbl@theverbbox$ +\caption{Sample Code Snippet (Obsolescent)} +\label{lst:app:styleguide:Sample Code Snippet (Obsolesc)} +\end{listing} diff --git a/appendix/styleguide/styleguide.tex b/appendix/styleguide/styleguide.tex index f375f77..0a94c1c 100644 --- a/appendix/styleguide/styleguide.tex +++ b/appendix/styleguide/styleguide.tex @@ -322,106 +322,322 @@ 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. +Although 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. + +Three customized environments of \qco{Verbatim} are defined +for perfbook. + +\qco{VerbatimL} is for floating snippets within the \qco{listing} +environment. \qco{VerbatimN} is for inline snippets with line count +enabled. \qco{VerbatimU} is for inline snippets without line count. +They are defined in the preamble as shown below: + +\begin{VerbatimU} +\DefineVerbatimEnvironment{VerbatimL}{Verbatim}% + {fontsize=\scriptsize,numbers=left,numbersep=5pt,% + xleftmargin=9pt,obeytabs=true,tabsize=2} +\AfterEndEnvironment{VerbatimL}{\vspace*{-9pt}} +\DefineVerbatimEnvironment{VerbatimN}{Verbatim}% + {fontsize=\scriptsize,numbers=left,numbersep=3pt,% + xleftmargin=5pt,xrightmargin=5pt,obeytabs=true,% + tabsize=2,frame=single} +\DefineVerbatimEnvironment{VerbatimU}{Verbatim}% + {fontsize=\scriptsize,numbers=none,xleftmargin=5pt,% + xrightmargin=5pt,obeytabs=true,tabsize=2,% + samepage=true,frame=single} +\end{VerbatimU} + +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)}, +\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. + +The \co{fancyvrb} package allows us to do that by the help of +escaping feature. +And the \LaTeX\ sources of snippets can be extracted from code samples under +the \path{CodeSamples} directory of perfbook tree. + +Conversion to the new scheme is currently underway. % 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{listing}[tbh] -{ \scriptsize -\verbfilebox[{\makebox[5ex][r]{\arabic{VerbboxLineNo}:\hspace{2ex}}}] - {appendix/styleguide/samplecodesnippetlst.tex} -} -\centering -\theverbbox +\begin{listing}[tb] +\fvset{fontsize=\scriptsize,numbers=left,numbersep=5pt,xleftmargin=9pt,obeytabs=true,tabsize=8,commandchars=\%\~\^} +\begin{linelabel}[ln:app:styleguide:LaTeX Source of Sample Code Snippet (Current)] +\VerbatimInput{appendix/styleguide/samplecodesnippetfcv.tex} +\end{linelabel} +\vspace*{-9pt} \caption{\LaTeX\ Source of Sample Code Snippet (Current)} \label{lst:app:styleguide:LaTeX Source of Sample Code Snippet (Current)} \end{listing} -\input{appendix/styleguide/samplecodesnippetlst} +\input{appendix/styleguide/samplecodesnippetfcv.tex} The \LaTeX\ source of a sample code snippet is shown in Listing~\ref{lst:app:styleguide:LaTeX Source of Sample Code Snippet (Current)} -and is typeset as show in +and is typeset as shown in Listing~\ref{lst:app:styleguide:Sample Code Snippet}. -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. +Labels to lines are specified in \qco{$lnlbl[]} command. The characters +specified by \qco{commandchars} option to \co{VarbatimL} environment are +used by the \co{fancyvrb} package to substitute \qco{\\lnlbl\{\}} +for \qco{$lnlbl[]}. Those characters should be selected so that they +don't appear elsewhere in the code snippet. -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}. +Labels \qco{printf} and \qco{return} in +Listing~\ref{lst:app:styleguide:Sample Code Snippet} +can be referred to as shown below: -\begin{listing}[tbh] -{ \scriptsize -\verbfilebox[{\makebox[5ex][r]{\arabic{VerbboxLineNo}:\hspace{2ex}}}] - {appendix/styleguide/samplecodesnippetfig.tex} +\begin{VerbatimU} +\begin{lineref}[ln:base1] +Lines~\lnref{printf} and~\lnref{return} can be referred +to from text. +\end{lineref} +\end{VerbatimU} + +Above code results in the paragraph below: + +\begin{quote} +\begin{lineref}[ln:base1] +Lines~\lnref{printf} and~\lnref{return} can be referred +to from text. +\end{lineref} +\end{quote} + +\LaTeX\ source shown in +Listing~\ref{lst:app:styleguide:LaTeX Source of Sample Code Snippet (Current)} +can be extracted from a code sample of +Listing~\ref{lst:app:styleguide:Source of Code Sample} by a perl script +\path{utilities/fcvextract.pl}. All the relevant rules of extraction +are described as recipes in the top level \path{Makefile} and +a script to generate dependencies (\path{utilities/gen_snippet_d.pl}). + +\begin{listing}[tb] +\fvset{fontsize=\scriptsize,numbers=left,numbersep=5pt,xleftmargin=9pt,obeytabs=true,tabsize=8} +\VerbatimInput{appendix/styleguide/samplecodesnippet.c} +\vspace*{-9pt} +\caption{Source of Code Sample with ``snippet'' meta command} +\label{lst:app:styleguide:Source of Code Sample} +\end{listing} + +As you can see, Listing ~\ref{lst:app:styleguide:Source of Code Sample} +has meta commands in comments of C (C++ style). These meta commands +are interpreted by \path{utilities/fcvextract.pl}, which distinguishes +the type of comment style by the suffix of code sample's file name. + +Meta commands which can be used in code samples are shown below: + +\begin{VerbatimU} +\begin{snippet}[option] +\end{snippet} +\lnlbl{