Convert to "description" list
cover Convert to "description" list
From e4a223315e3db9ffe303a95e15ee662935baaea9 Mon Sep 17 00:00:00 2001
From: Akira Yokosawa <[email protected]>
Date: Thu, 9 Mar 2017 23:57:00 +0900
Subject: [PATCH 0/5] Convert to "description" list
Hi Paul,
This is the follow-up set of patches. It includes:
o Use "enumitem" instead of "enumerate"
o Convert to "description"
Conversion to "description" looks reasonable changes for me. Let me know what you think.
There are other candidates of similar conversions in Appendix B, But as you mentioned earlier that the appendix needs update (or replacement by a newer article you posted the other day), I'm not sure if it is worthwhile to do changes there, and stopped short of posting patches for the appendix.
Thanks, Akira
Signature · 18 lines
Akira Yokosawa (5): Use 'enumitem' package instead of 'enumerate' intro: Move ':' to tail of 'description' label debugging: Convert to 'description' formal: Convert to 'description' together: Covert to 'description' debugging/debugging.tex | 10 +++++----- formal/dyntickrcu.tex | 14 +++++++------- formal/spinhint.tex | 12 ++++++------ howto/howto.tex | 2 +- intro/intro.tex | 10 +++++----- perfbook.tex | 4 +++- together/refcnt.tex | 30 +++++++++++++++--------------- 7 files changed, 42 insertions(+), 40 deletions(-) -- 2.7.4
PATCH 1/5 Use 'enumitem' package instead of 'enumerate'
From 477bc66e66a08506ca04c456348d04dff877ea37 Mon Sep 17 00:00:00 2001
From: Akira Yokosawa <[email protected]>
Date: Thu, 9 Mar 2017 23:50:51 +0900
Subject: [PATCH 1/5] Use 'enumitem' package instead of 'enumerate'
For more flexibility of list environment customization, use "enumitem" package instead of "enumerate".
We need to modify enumeration header style specification added in commit 4dd83b8e1aca ("howto: Specify style of enumerate header") to work with "enumitem".
--- howto/howto.tex | 2 +- perfbook.tex | 4 +++- 2 files changed, 4 insertions(+), 2 deletions(-)
howto/howto.tex +1 -1
@@ -453,7 +453,7 @@ patch containing a \co{Signed-off-by:} line. It is important to note that the \co{Signed-off-by:} line has a very specific meaning, namely that you are certifying that: -\begin{enumerate}[(a)] +\begin{enumerate}[label={(\alph*)}] \item The contribution was created in whole or in part by me and I have the right to submit it under the open source license indicated in the file; or
perfbook.tex +3 -1
@@ -21,7 +21,9 @@ % \usepackage{breakurl} \usepackage{graphicx} \usepackage{rotating} -\usepackage{enumerate} +\usepackage{enumitem} +\setlist[description]{style=unboxed} +%\usepackage{enumerate} \usepackage{ifthen} \usepackage{xcolor} \usepackage[shortcuts]{extdash}
Signature · 1 line
2.7.4
PATCH 2/5 intro: Move ':' to tail of 'description' label
In reply to Akira YokosawaFrom de0da3d0e4ae3ee76c56672295b9cfefc0c61a2c Mon Sep 17 00:00:00 2001
From: Akira Yokosawa <[email protected]>
Date: Thu, 9 Mar 2017 23:51:37 +0900
Subject: [PATCH 2/5] intro: Move ':' to tail of 'description' label
--- intro/intro.tex | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-)
intro/intro.tex +5 -5
@@ -524,32 +524,32 @@ To see this more generally, consider the following popular parallel programming environments: \begin{description} -\item[C/C++ ``Locking Plus Threads'']: This category, which includes +\item[C/C++ ``Locking Plus Threads'':] This category, which includes POSIX Threads (pthreads)~\cite{OpenGroup1997pthreads}, Windows Threads, and numerous operating-system kernel environments, offers excellent performance (at least within the confines of a single SMP system) and also offers good generality. Pity about the relatively low productivity. -\item[Java]: This general purpose and inherently multithreaded +\item[Java:] This general purpose and inherently multithreaded programming environment is widely believed to offer much higher productivity than C or C++, courtesy of the automatic garbage collector and the rich set of class libraries. However, its performance, though greatly improved in the early 2000s, lags that of C and C++. -\item[MPI]: This Message Passing Interface~\cite{MPIForum2008} powers +\item[MPI:] This Message Passing Interface~\cite{MPIForum2008} powers the largest scientific and technical computing clusters in the world and offers unparalleled performance and scalability. In theory, it is general purpose, but it is mainly used for scientific and technical computing. Its productivity is believed by many to be even lower than that of C/C++ ``locking plus threads'' environments. -\item[OpenMP]: This set of compiler directives can be used +\item[OpenMP:] This set of compiler directives can be used to parallelize loops. It is thus quite specific to this task, and this specificity often limits its performance. It is, however, much easier to use than MPI or C/C++ ``locking plus threads.'' -\item[SQL]: Structured Query Language~\cite{DIS9075SQL92} is +\item[SQL:] Structured Query Language~\cite{DIS9075SQL92} is specific to relational database queries. However, its performance is quite good as measured by the Transaction Processing Performance Council (TPC)
Signature · 1 line
2.7.4
PATCH 3/5 debugging: Convert to 'description'
In reply to Akira YokosawaFrom 138b82d8fee707c43874095711887e912a9a92a7 Mon Sep 17 00:00:00 2001
From: Akira Yokosawa <[email protected]>
Date: Thu, 9 Mar 2017 23:52:35 +0900
Subject: [PATCH 3/5] debugging: Convert to 'description'
This list looks better in "description" environment. Again, \tco{} is safer than \co{} for option names in labels. Note that ":" at the end of each label is enclosed by \nf{} to avoid confusing impression that the ":" belongs to the option.
--- debugging/debugging.tex | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-)
debugging/debugging.tex +5 -5
@@ -2191,16 +2191,16 @@ and output consists of one line for each input line, with fields as follows: This script takes three optional arguments as follows: -\begin{itemize} -\item \co{--divisor}: Number of segments to divide the list into, +\begin{description} +\item [\tco{--divisor}\nf{:}] Number of segments to divide the list into, for example, a divisor of four means that the first quarter of the data elements will be assumed to be good. This defaults to three. -\item \co{--relerr}: Relative measurement error. The script assumes +\item [\tco{--relerr}\nf{:}] Relative measurement error. The script assumes that values that differ by less than this error are for all intents and purposes equal. This defaults to 0.01, which is equivalent to 1\%. -\item \co{--trendbreak}: Ratio of inter-element spacing constituting +\item [\tco{--trendbreak}\nf{:}] Ratio of inter-element spacing constituting a break in the trend of the data. For example, if the average spacing in the data accepted so far is 1.5, then if the trend-break ratio is 2.0, then if the next
@@ -2208,7 +2208,7 @@ This script takes three optional arguments as follows: constitutes a break in the trend. (Unless of course, the relative error is greater than 3.0, in which case the ``break'' will be ignored.) -\end{itemize} +\end{description} Lines~1-3 of Figure~\ref{fig:count:Statistical Elimination of Interference}
Signature · 1 line
2.7.4
PATCH 4/5 formal: Convert to 'description'
In reply to Akira YokosawaFrom 040963d9bd65a17500a5ccff5603505decc1e513 Mon Sep 17 00:00:00 2001
From: Akira Yokosawa <[email protected]>
Date: Thu, 9 Mar 2017 23:54:32 +0900
Subject: [PATCH 4/5] formal: Convert to 'description'
These lists look better in "description" environment with "nextline" style. The style is good because of variation of label lengths. Note that colons at the tails of labels are removed.
--- formal/dyntickrcu.tex | 14 +++++++------- formal/spinhint.tex | 12 ++++++------ 2 files changed, 13 insertions(+), 13 deletions(-)
formal/dyntickrcu.tex +7 -7
@@ -1890,33 +1890,33 @@ the NMI code path will also reference (but not modify) the \co{dynticks_nesting} variable. These variables are used as follows: -\begin{itemize} -\item \co{dynticks_nesting}: +\begin{description}[style=nextline] +\item [\tco{dynticks_nesting}] This counts the number of reasons that the corresponding CPU should be monitored for RCU read-side critical sections. If the CPU is in dynticks-idle mode, then this counts the irq nesting level, otherwise it is one greater than the irq nesting level. -\item \co{dynticks}: +\item [\tco{dynticks}] This counter's value is even if the corresponding CPU is in dynticks-idle mode and there are no irq handlers currently running on that CPU, otherwise the counter's value is odd. In other words, if this counter's value is odd, then the corresponding CPU might be in an RCU read-side critical section. -\item \co{dynticks_nmi}: +\item [\tco{dynticks_nmi}] This counter's value is odd if the corresponding CPU is in an NMI handler, but only if the NMI arrived while this CPU was in dyntick-idle mode with no irq handlers running. Otherwise, the counter's value will be even. -\item \co{dynticks_snap}: +\item [\tco{dynticks_snap}] This will be a snapshot of the \co{dynticks} counter, but only if the current RCU grace period has extended for too long a duration. -\item \co{dynticks_nmi_snap}: +\item [\tco{dynticks_nmi_snap}] This will be a snapshot of the \co{dynticks_nmi} counter, but again only if the current RCU grace period has extended for too long a duration. -\end{itemize} +\end{description} If both \co{dynticks} and \co{dynticks_nmi} have taken on an even value during a given time interval, then the corresponding CPU has
formal/spinhint.tex +6 -6
@@ -389,10 +389,10 @@ elaborate examples. Given a source file \path{qrcu.spin}, one can use the following commands: -\begin{itemize} -\item \co{spin -a qrcu.spin} +\begin{description}[style=nextline] +\item [\tco{spin -a qrcu.spin}] Create a file \path{pan.c} that fully searches the state machine. -\item \co{cc -DSAFETY -o pan pan.c} +\item [\tco{cc -DSAFETY -o pan pan.c}] Compile the generated state-machine search. The \co{-DSAFETY} generates optimizations that are appropriate if you have only assertions (and perhaps \co{never} statements). If you have
@@ -405,7 +405,7 @@ Given a source file \path{qrcu.spin}, one can use the following commands: An example situation where you cannot use \co{-DSAFETY} is when checking for livelocks (AKA ``non-progress cycles'') via \co{-DNP}. -\item \co{./pan} +\item [\tco{./pan}] This actually searches the state space. The number of states can reach into the tens of millions with very small state machines, so you will need a machine with large memory.
@@ -431,13 +431,13 @@ Given a source file \path{qrcu.spin}, one can use the following commands: you will also need the \co{-a} argument. % forward reference to model: formal.2009.02.19a in % /home/linux/git/userspace-rcu/formal-model. -\item \co{spin -t -p qrcu.spin} +\item [\tco{spin -t -p qrcu.spin}] Given \co{trail} file output by a run that encountered an error, output the sequence of steps leading to that error. The \co{-g} flag will also include the values of changed global variables, and the \co{-l} flag will also include the values of changed local variables. -\end{itemize} +\end{description} \subsubsection{Promela Peculiarities} \label{sec:formal:Promela Peculiarities}
Signature · 1 line
2.7.4
PATCH 5/5 together: Covert to 'description'
In reply to Akira YokosawaFrom e4a223315e3db9ffe303a95e15ee662935baaea9 Mon Sep 17 00:00:00 2001
From: Akira Yokosawa <[email protected]>
Date: Thu, 9 Mar 2017 23:55:30 +0900
Subject: [PATCH 5/5] together: Covert to 'description'
This list looks better in "description" environment with "nextline" style.
The long label is properly line broken by the help of "enumitem" package.
Note that ";" is preserved in the labels.
--- together/refcnt.tex | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-)
together/refcnt.tex +15 -15
@@ -563,40 +563,40 @@ summarized in the following list. so a brief overview with citations is included in Section~\ref{sec:together:Background on RCU}.} -\begin{itemize} -\item \co{atomic_t} +\begin{description}[style=nextline] +\item [\tco{atomic_t}] Type definition for 32-bit quantity to be manipulated atomically. -\item \co{void atomic_dec(atomic_t *var);} +\item [\tco{void atomic_dec(atomic_t *var);}] Atomically decrements the referenced variable without necessarily issuing a memory barrier or disabling compiler optimizations. -\item \co{int atomic_dec_and_test(atomic_t *var);} +\item [\tco{int atomic_dec_and_test(atomic_t *var);}] Atomically decrements the referenced variable, returning \co{true} (non-zero) if the result is zero. Issues a memory barrier and disables compiler optimizations that might otherwise move memory references across this primitive. -\item \co{void atomic_inc(atomic_t *var);} +\item [\tco{void atomic_inc(atomic_t *var);}] Atomically increments the referenced variable without necessarily issuing a memory barrier or disabling compiler optimizations. -\item \co{int atomic_inc_not_zero(atomic_t *var);} +\item [\tco{int atomic_inc_not_zero(atomic_t *var);}] Atomically increments the referenced variable, but only if the value is non-zero, and returning \co{true} (non-zero) if the increment occurred. Issues a memory barrier and disables compiler optimizations that might otherwise move memory references across this primitive. -\item \co{int atomic_read(atomic_t *var);} +\item [\tco{int atomic_read(atomic_t *var);}] Returns the integer value of the referenced variable. This need not be an atomic operation, and it need not issue any memory-barrier instructions. Instead of thinking of as ``an atomic read'', think of it as ``a normal read from an atomic variable''. -\item \co{void atomic_set(atomic_t *var, int val);} +\item [\tco{void atomic_set(atomic_t *var, int val);}] Sets the value of the referenced atomic variable to ``val''. This need not be an atomic operation, and it is not required to either issue memory barriers or disable compiler optimizations. Instead of thinking of as ``an atomic set'', think of it as ``a normal set of an atomic variable''. -\item \co{void call_rcu(struct rcu_head *head, void (*func)(struct rcu_head *head));} +\item [\tco{void call_rcu(struct rcu_head *head, void (*func)(struct rcu_head *head));}] Invokes \co{func(head)} some time after all currently executing RCU read-side critical sections complete, however, the \co{call_rcu()} primitive returns immediately.
@@ -607,24 +607,24 @@ summarized in the following list. the invocation of \co{func} is termed a ``grace period''. Any interval of time containing a grace period is itself a grace period. -\item \co{type *container_of(p, type, f);} +\item [\tco{type *container_of(p, type, f);}] Given a pointer \co{p} to a field \co{f} within a structure of the specified type, return a pointer to the structure. -\item \co{void rcu_read_lock(void);} +\item [\tco{void rcu_read_lock(void);}] Marks the beginning of an RCU read-side critical section. -\item \co{void rcu_read_unlock(void);} +\item [\tco{void rcu_read_unlock(void);}] Marks the end of an RCU read-side critical section. RCU read-side critical sections may be nested. -\item \co{void smp_mb__before_atomic_dec(void);} +\item [\tco{void smp_mb__before_atomic_dec(void);}] Issues a memory barrier and disables code-motion compiler optimizations only if the platform's \co{atomic_dec()} primitive does not already do so. -\item \co{struct rcu_head} +\item [\tco{struct rcu_head}] A data structure used by the RCU infrastructure to track objects awaiting a grace period. This is normally included as a field within an RCU-protected data structure. -\end{itemize} +\end{description} \QuickQuiz{} An \co{atomic_read()} and an \co{atomic_set()} that are
Signature · 1 line
2.7.4
Quoted 7 lines · Akira Yokosawa
Quoted 1 line
From
e4a223315e3db9ffe303a95e15ee662935baaea9Mon Sep 17 00:00:00 2001From: Akira Yokosawa <[email protected]>
Date: Thu, 9 Mar 2017 23:57:00 +0900
Subject: [PATCH 0/5] Convert to "description" listHi Paul,
Quoted 7 lines
This is the follow-up set of patches. It includes:
o Use "enumitem" instead of "enumerate"
o Convert to "description"Conversion to "description" looks reasonable changes for me. Let me know what you think.
Nice improvements, thank you! Queued and pushed.
Thanx, Paul
Quoted 27 lines
There are other candidates of similar conversions in Appendix B, But as you mentioned earlier that the appendix needs update (or replacement by a newer article you posted the other day), I'm not sure if it is worthwhile to do changes there, and stopped short of posting patches for the appendix.
Thanks, Akira
Signature · 18 lines
Akira Yokosawa (5): Use 'enumitem' package instead of 'enumerate' intro: Move ':' to tail of 'description' label debugging: Convert to 'description' formal: Convert to 'description' together: Covert to 'description' debugging/debugging.tex | 10 +++++----- formal/dyntickrcu.tex | 14 +++++++------- formal/spinhint.tex | 12 ++++++------ howto/howto.tex | 2 +- intro/intro.tex | 10 +++++----- perfbook.tex | 4 +++- together/refcnt.tex | 30 +++++++++++++++--------------- 7 files changed, 42 insertions(+), 40 deletions(-) -- 2.7.4