[PATCH 0/5] Convert to "description" list

[PATCH 0/5] Convert to "description" list

[Akira Yokosawa]

From e4a223315e3db9ffe303a95e15ee662935baaea9 Mon Sep 17 00:00:00 2001
From: Akira Yokosawa <akiyks@gmail.com>
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
-- 
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'

[Akira Yokosawa]

From 477bc66e66a08506ca04c456348d04dff877ea37 Mon Sep 17 00:00:00 2001
From: Akira Yokosawa <akiyks@gmail.com>
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".

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
 howto/howto.tex | 2 +-
 perfbook.tex    | 4 +++-
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/howto/howto.tex b/howto/howto.tex
index 2f1b0fc..91a8563 100644
--- a/howto/howto.tex
+++ b/howto/howto.tex
@@ -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
diff --git a/perfbook.tex b/perfbook.tex
index d532e65..a999705 100644
--- a/perfbook.tex
+++ b/perfbook.tex
@@ -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}
-- 
2.7.4

[PATCH 2/5] intro: Move ':' to tail of 'description' label

[Akira Yokosawa]

From de0da3d0e4ae3ee76c56672295b9cfefc0c61a2c Mon Sep 17 00:00:00 2001
From: Akira Yokosawa <akiyks@gmail.com>
Date: Thu, 9 Mar 2017 23:51:37 +0900
Subject: [PATCH 2/5] intro: Move ':' to tail of 'description' label

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
 intro/intro.tex | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/intro/intro.tex b/intro/intro.tex
index 413525b..0b8659e 100644
--- a/intro/intro.tex
+++ b/intro/intro.tex
@@ -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)
-- 
2.7.4

[PATCH 3/5] debugging: Convert to 'description'

[Akira Yokosawa]

From 138b82d8fee707c43874095711887e912a9a92a7 Mon Sep 17 00:00:00 2001
From: Akira Yokosawa <akiyks@gmail.com>
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.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
 debugging/debugging.tex | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/debugging/debugging.tex b/debugging/debugging.tex
index 86b1118..6797c2f 100644
--- a/debugging/debugging.tex
+++ b/debugging/debugging.tex
@@ -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}
-- 
2.7.4

[PATCH 4/5] formal: Convert to 'description'

[Akira Yokosawa]

From 040963d9bd65a17500a5ccff5603505decc1e513 Mon Sep 17 00:00:00 2001
From: Akira Yokosawa <akiyks@gmail.com>
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.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
 formal/dyntickrcu.tex | 14 +++++++-------
 formal/spinhint.tex   | 12 ++++++------
 2 files changed, 13 insertions(+), 13 deletions(-)

diff --git a/formal/dyntickrcu.tex b/formal/dyntickrcu.tex
index 50e87d8..16d1f73 100644
--- a/formal/dyntickrcu.tex
+++ b/formal/dyntickrcu.tex
@@ -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
diff --git a/formal/spinhint.tex b/formal/spinhint.tex
index 906de31..eb029ca 100644
--- a/formal/spinhint.tex
+++ b/formal/spinhint.tex
@@ -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}
-- 
2.7.4

[PATCH 5/5] together: Covert to 'description'

[Akira Yokosawa]

From e4a223315e3db9ffe303a95e15ee662935baaea9 Mon Sep 17 00:00:00 2001
From: Akira Yokosawa <akiyks@gmail.com>
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.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
 together/refcnt.tex | 30 +++++++++++++++---------------
 1 file changed, 15 insertions(+), 15 deletions(-)

diff --git a/together/refcnt.tex b/together/refcnt.tex
index e7884a4..626c375 100644
--- a/together/refcnt.tex
+++ b/together/refcnt.tex
@@ -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
-- 
2.7.4

Re: [PATCH 0/5] Convert to "description" list

[Paul E. McKenney]

On Fri, Mar 10, 2017 at 12:18:19AM +0900, Akira Yokosawa wrote:
> >From e4a223315e3db9ffe303a95e15ee662935baaea9 Mon Sep 17 00:00:00 2001
> From: Akira Yokosawa <akiyks@gmail.com>
> 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.

Nice improvements, thank you!  Queued and pushed.

							Thanx, Paul

> 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
> -- 
> 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
>