[GIT PULL -perfbook] Add checks with regard to punctuation marks

[GIT PULL -perfbook] Add checks with regard to punctuation marks

[Akira Yokosawa]

Hi Paul,

It took a while for me to sort out the spacing width after punctuation
marks.

Previous updates took care of mid-sentence and end-of-sentence
periods.
It turns out that we need to care other punctuation marks in the
same way.  My experiment shows that "!", "?", and ":" behaves in the
same way as ".".

For cleverefcheck to work, we need to make sure end-of-sentence
punctuation marks be at the end of input lines, so periodcheck.pl
now treats "!" and "?" in the same way as ".".

cleverefcheck now checks sentences starting with lower-case words
as well as \cref{} and its variants.

It also checks indents by white spaces now.

All the offending patterns in LaTeX sources have fixed.

Finally "make" will run both periodcheck and cleverefcheck.

As for colons, I'm not sure what is your preference with regard
to capitalization of the next words and the spacing width after
them, so no check is done at the moment.
 
If you have some preference, I can update the scripts to enforce
it.

        Thanks, Akira
--
The following changes since commit a20cf5ebd8605d93bb35876a26907fe294278eb8:

  defer: Fix lack of rcu_register_thread() in singleton_reader() (2021-06-08 14:58:10 -0700)

are available in the Git repository at:

  https://github.com/akiyks/perfbook.git tags/for-paul-2021.06.09a

for you to fetch changes up to f70493ae24172bb73ce4a0560d4c1f958baedd51:

  styleguide: Adjust cleveref macro usage where possible (2021-06-09 11:28:50 +0900)

----------------------------------------------------------------
Akira Yokosawa (11):
      cleverefcheck: Add check of sentences starting with lower-case words
      periodcheck: Check question and exclamation marks as well
      formal/dyntickrcu: Fix unintended paragraph break
      memorder: Move float snippet away of QQA heading
      treewide: Annotate punctuation marks
      treewide: Make end-of-sentence punctuation marks be at end-of-line
      debugging: Move period out of double quotes
      cleverefcheck: Add check of indent by white spaces
      treewide: Fix indents by white spaces
      Makefile: Auto run cleverefcheck on 'make'
      styleguide: Adjust cleveref macro usage where possible

 Makefile                             |  2 ++
 SMPdesign/partexercises.tex          |  3 +-
 advsync/rt.tex                       |  6 ++--
 appendix/styleguide/styleguide.tex   | 23 +++++++-------
 appendix/toyrcu/toyrcu.tex           |  4 +--
 appendix/whymb/whymemorybarriers.tex |  2 +-
 count/count.tex                      |  6 ++--
 cpu/overheads.tex                    |  2 +-
 datastruct/datastruct.tex            |  2 +-
 debugging/debugging.tex              | 44 ++++++++++++++------------
 defer/defer.tex                      |  2 +-
 defer/rcuapi.tex                     |  4 +--
 defer/rcurelated.tex                 |  2 +-
 defer/rcuusage.tex                   |  2 +-
 defer/whichtochoose.tex              |  2 +-
 easy/easy.tex                        |  3 +-
 formal/dyntickrcu.tex                |  2 +-
 formal/ppcmem.tex                    |  2 +-
 formal/spinhint.tex                  | 12 +++----
 locking/locking.tex                  |  4 +--
 memorder/memorder.tex                | 20 ++++++------
 together/refcnt.tex                  |  2 +-
 toolsoftrade/toolsoftrade.tex        |  9 +++---
 utilities/cleverefcheck.pl           | 61 ++++++++++++++++++++++++++----------
 utilities/cleverefcheck.sh           |  1 +
 utilities/periodcheck.pl             | 28 ++++++++++++-----
 26 files changed, 150 insertions(+), 100 deletions(-)

Re: [GIT PULL -perfbook] Add checks with regard to punctuation marks

[Paul E. McKenney]

On Wed, Jun 09, 2021 at 11:59:42AM +0900, Akira Yokosawa wrote:
> Hi Paul,
> 
> It took a while for me to sort out the spacing width after punctuation
> marks.

Thank you very much for doing all of this!

> Previous updates took care of mid-sentence and end-of-sentence
> periods.
> It turns out that we need to care other punctuation marks in the
> same way.  My experiment shows that "!", "?", and ":" behaves in the
> same way as ".".
> 
> For cleverefcheck to work, we need to make sure end-of-sentence
> punctuation marks be at the end of input lines, so periodcheck.pl
> now treats "!" and "?" in the same way as ".".
> 
> cleverefcheck now checks sentences starting with lower-case words
> as well as \cref{} and its variants.
> 
> It also checks indents by white spaces now.
> 
> All the offending patterns in LaTeX sources have fixed.
> 
> Finally "make" will run both periodcheck and cleverefcheck.

Very good!!!

> As for colons, I'm not sure what is your preference with regard
> to capitalization of the next words and the spacing width after
> them, so no check is done at the moment.
>  
> If you have some preference, I can update the scripts to enforce
> it.

In this case, I prefer the simple British approach to that of my
homeland, so please unconditionally capitalize after a colon.

(Instead of the American approach of doing so only if the word following
the colon begins a complete sentence, which is not something I want to
be checking manually, let alone via a script!)

>         Thanks, Akira
> --
> The following changes since commit a20cf5ebd8605d93bb35876a26907fe294278eb8:
> 
>   defer: Fix lack of rcu_register_thread() in singleton_reader() (2021-06-08 14:58:10 -0700)
> 
> are available in the Git repository at:
> 
>   https://github.com/akiyks/perfbook.git tags/for-paul-2021.06.09a
> 
> for you to fetch changes up to f70493ae24172bb73ce4a0560d4c1f958baedd51:

Pulled and pushed, thank you!

							Thanx, Paul

>   styleguide: Adjust cleveref macro usage where possible (2021-06-09 11:28:50 +0900)
> 
> ----------------------------------------------------------------
> Akira Yokosawa (11):
>       cleverefcheck: Add check of sentences starting with lower-case words
>       periodcheck: Check question and exclamation marks as well
>       formal/dyntickrcu: Fix unintended paragraph break
>       memorder: Move float snippet away of QQA heading
>       treewide: Annotate punctuation marks
>       treewide: Make end-of-sentence punctuation marks be at end-of-line
>       debugging: Move period out of double quotes
>       cleverefcheck: Add check of indent by white spaces
>       treewide: Fix indents by white spaces
>       Makefile: Auto run cleverefcheck on 'make'
>       styleguide: Adjust cleveref macro usage where possible
> 
>  Makefile                             |  2 ++
>  SMPdesign/partexercises.tex          |  3 +-
>  advsync/rt.tex                       |  6 ++--
>  appendix/styleguide/styleguide.tex   | 23 +++++++-------
>  appendix/toyrcu/toyrcu.tex           |  4 +--
>  appendix/whymb/whymemorybarriers.tex |  2 +-
>  count/count.tex                      |  6 ++--
>  cpu/overheads.tex                    |  2 +-
>  datastruct/datastruct.tex            |  2 +-
>  debugging/debugging.tex              | 44 ++++++++++++++------------
>  defer/defer.tex                      |  2 +-
>  defer/rcuapi.tex                     |  4 +--
>  defer/rcurelated.tex                 |  2 +-
>  defer/rcuusage.tex                   |  2 +-
>  defer/whichtochoose.tex              |  2 +-
>  easy/easy.tex                        |  3 +-
>  formal/dyntickrcu.tex                |  2 +-
>  formal/ppcmem.tex                    |  2 +-
>  formal/spinhint.tex                  | 12 +++----
>  locking/locking.tex                  |  4 +--
>  memorder/memorder.tex                | 20 ++++++------
>  together/refcnt.tex                  |  2 +-
>  toolsoftrade/toolsoftrade.tex        |  9 +++---
>  utilities/cleverefcheck.pl           | 61 ++++++++++++++++++++++++++----------
>  utilities/cleverefcheck.sh           |  1 +
>  utilities/periodcheck.pl             | 28 ++++++++++++-----
>  26 files changed, 150 insertions(+), 100 deletions(-)

Re: [GIT PULL -perfbook] Add checks with regard to punctuation marks

[Akira Yokosawa]

On Wed, 9 Jun 2021 12:23:47 -0700, Paul E. McKenney wrote:
> On Wed, Jun 09, 2021 at 11:59:42AM +0900, Akira Yokosawa wrote:
>> Hi Paul,
>>
>> It took a while for me to sort out the spacing width after punctuation
>> marks.
> 
> Thank you very much for doing all of this!
> 
[...]
>> All the offending patterns in LaTeX sources have fixed.
>>
>> Finally "make" will run both periodcheck and cleverefcheck.
> 
> Very good!!!
> 
>> As for colons, I'm not sure what is your preference with regard
>> to capitalization of the next words and the spacing width after
>> them, so no check is done at the moment.
>>  
>> If you have some preference, I can update the scripts to enforce
>> it.
> 
> In this case, I prefer the simple British approach to that of my
> homeland, so please unconditionally capitalize after a colon.
> 
> (Instead of the American approach of doing so only if the word following
> the colon begins a complete sentence, which is not something I want to
> be checking manually, let alone via a script!)

Please find a tentative patch below showing you how the changes would
look like.

Does this look reasonable to you?

A couple of notes:

o In epigraph of Alice in Wonderland, I see trailing "\\"s
  can indicate the rule to put ":"s at the end of lines is
  knowingly broken.  I can add a rule to ignore any violations
  on a line who has trailing "\\" (even in a comment area).

o One of the hunks in cpu/hwfreelunch.tex

> @@ -167,8 +167,8 @@ That said, they may be necessary steps on the path to the late Jim Gray's
>  \label{sec:cpu:Novel Materials and Processes}
>  
>  Stephen Hawking is said to have claimed that semiconductor manufacturers
> -have but two fundamental problems: (1) the finite speed of light and
> -(2) the atomic nature of matter~\cite{BryanGardiner2007}.
> +have but two fundamental problems:\@ (1)~the finite speed of light and
> +(2)~the atomic nature of matter~\cite{BryanGardiner2007}.
>  It is possible that semiconductor manufacturers are approaching these
>  limits, but there are nevertheless a few avenues of research and
> development focused on working around these fundamental limits.

keeps lower-case words after (1) and (2) as they are just short
phrases.
And the space after the colon is normal-width.
Do you like capital words and double spacing?

        Thanks, Akira

-----------8<-----------
Subject: [PATCH] howto, intro, cpu: Capitalize words after colon

And make colons at the end of input lines.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
 cpu/cpu.tex         |  5 +++--
 cpu/hwfreelunch.tex | 17 ++++++++++-------
 cpu/overheads.tex   |  5 +++--
 cpu/overview.tex    |  8 +++++---
 howto/howto.tex     |  8 ++++----
 intro/intro.tex     | 28 ++++++++++++++--------------
 6 files changed, 39 insertions(+), 32 deletions(-)

diff --git a/cpu/cpu.tex b/cpu/cpu.tex
index 183feb8c..8a4afc69 100644
--- a/cpu/cpu.tex
+++ b/cpu/cpu.tex
@@ -54,8 +54,9 @@ So, to sum up:
 \begin{enumerate}
 \item	The good news is that multicore systems are inexpensive and
 	readily available.
-\item	More good news:  The overhead of many synchronization operations
-	is much lower than it was on parallel systems from the early 2000s.
+\item	More good news:
+	The overhead of many synchronization operations is much lower
+	than it was on parallel systems from the early 2000s.
 \item	The bad news is that the overhead of cache misses is still high,
 	especially on large systems.
 \end{enumerate}
diff --git a/cpu/hwfreelunch.tex b/cpu/hwfreelunch.tex
index 92f04f16..01d3dddd 100644
--- a/cpu/hwfreelunch.tex
+++ b/cpu/hwfreelunch.tex
@@ -167,8 +167,8 @@ That said, they may be necessary steps on the path to the late Jim Gray's
 \label{sec:cpu:Novel Materials and Processes}
 
 Stephen Hawking is said to have claimed that semiconductor manufacturers
-have but two fundamental problems: (1) the finite speed of light and
-(2) the atomic nature of matter~\cite{BryanGardiner2007}.
+have but two fundamental problems:\@ (1)~the finite speed of light and
+(2)~the atomic nature of matter~\cite{BryanGardiner2007}.
 It is possible that semiconductor manufacturers are approaching these
 limits, but there are nevertheless a few avenues of research and
 development focused on working around these fundamental limits.
@@ -228,8 +228,9 @@ general-purpose CPU will normally use a loop (possibly unrolled)
 with a loop counter.
 Decoding the instructions, incrementing the loop counter, testing this
 counter, and branching back to the
-top of the loop are in some sense wasted effort: the real goal is
-instead to multiply corresponding elements of the two vectors.
+top of the loop are in some sense wasted effort:
+The real goal is instead to multiply corresponding elements of the
+two vectors.
 Therefore, a specialized piece of hardware designed specifically to
 multiply vectors could get the job done more quickly and with less
 energy consumed.
@@ -263,10 +264,12 @@ These hardware accelerators are often used for media decoding,
 so much so that a high-end MP3 player might be able to play audio
 for several minutes---with its CPU fully powered off the entire time.
 The purpose of these accelerators is to improve energy efficiency
-and thus extend battery life: special purpose hardware can often
-compute more efficiently than can a general-purpose CPU\@.
+and thus extend battery life:
+Special purpose hardware can often compute more efficiently than
+can a general-purpose CPU\@.
 This is another example of the principle called out in
-\cref{sec:intro:Generality}: \IX{Generality} is almost never free.
+\cref{sec:intro:Generality}:
+\IX{Generality} is almost never free.
 
 Nevertheless, given the end of \IXaltr{Moore's-Law}{Moore's Law}-induced
 single-threaded performance increases, it seems safe to assume that
diff --git a/cpu/overheads.tex b/cpu/overheads.tex
index 80d60d9d..8cf1e94a 100644
--- a/cpu/overheads.tex
+++ b/cpu/overheads.tex
@@ -500,8 +500,9 @@ cycles, as shown in the ``Global Comms'' row.
 	use several rolls (or multiple cases) of toilet paper to represent
 	the communications latency.
 
-	Important safety tip: make sure to account for the needs of
-	those you live with when appropriating toilet paper, especially
+	Important safety tip:
+	Make sure to account for the needs of those you live with when
+	appropriating toilet paper, especially
 	in 2020 or during a similar time when store shelves are free of
 	toilet paper and much else besides.
 
diff --git a/cpu/overview.tex b/cpu/overview.tex
index d1d23b36..96eecb6f 100644
--- a/cpu/overview.tex
+++ b/cpu/overview.tex
@@ -5,8 +5,9 @@
 \section{Overview}
 \label{sec:cpu:Overview}
 %
-\epigraph{Mechanical Sympathy: Hardware and software working together in
-	  harmony.}{\emph{Martin Thompson}}
+\epigraph{Mechanical Sympathy:
+	  Hardware and software working together in harmony.}
+	{\emph{Martin Thompson}}
 
 Careless reading of computer-system specification sheets might lead one
 to believe that CPU performance is a footrace on a clear track, as
@@ -335,7 +336,8 @@ as illustrated by
 \cref{fig:cpu:CPU Waits for I/O Completion}.
 
 This is one of the differences between shared-memory and distributed-system
-parallelism: shared-memory parallel programs must normally deal with no
+parallelism:
+Shared-memory parallel programs must normally deal with no
 obstacle worse than a cache miss, while a distributed parallel program
 will typically incur the larger network communication latencies.
 In both cases, the relevant latencies can be thought of as a cost of
diff --git a/howto/howto.tex b/howto/howto.tex
index 0f0ba293..54447c4e 100644
--- a/howto/howto.tex
+++ b/howto/howto.tex
@@ -50,7 +50,7 @@ that it has brought to us!
 	  Alice: Which way should I go? \\
 	  Cat: That depends on where you are going. \\
 	  Alice: I don't know. \\
-	  Cat: Then it doesn't matter which way you go.}
+	  Cat: Then it doesn't matter which way you go.} % \\
 	 {\emph{Lewis Carroll, Alice in Wonderland}}
 
 This book is a handbook of widely applicable and heavily
@@ -359,7 +359,7 @@ Fortunately, there are many alternatives available to you:
 	thorough and accessible introduction with a good set of
 	examples.
 \item	If you are interested in C++11, you might like
-	\ppl{Anthony}{Williams}'s ``C++ Concurrency in Action: Practical
+	\ppl{Anthony}{Williams}'s ``C++ Concurrency in Action:\@ Practical
 	Multithreading''~\cite{AnthonyWilliams2012,AnthonyWilliams2019}.
 \item	If you are interested in C++, but in a Windows environment,
 	you might try \ppl{Herb}{Sutter}'s ``Effective Concurrency''
@@ -528,8 +528,8 @@ namely that you are certifying that:
 
 This is quite similar to the Developer's Certificate of Origin (DCO)
 1.1 used by the Linux kernel.
-You must use your real name:  I unfortunately cannot accept pseudonymous or
-anonymous contributions.
+You must use your real name:
+I unfortunately cannot accept pseudonymous or anonymous contributions.
 
 The language of this book is American English, however, the open-source
 nature of this book permits translations, and I personally encourage them.
diff --git a/intro/intro.tex b/intro/intro.tex
index 5f2690fc..6835c107 100644
--- a/intro/intro.tex
+++ b/intro/intro.tex
@@ -23,11 +23,11 @@ However, new technologies that are difficult to use at introduction
 invariably become easier over time.
 For example, the once-rare ability to drive a car is now
 commonplace in many countries.
-This dramatic change came about for two basic reasons: (1)~cars became
-cheaper and more readily available, so that more people had the
-opportunity to learn to drive, and (2)~cars became easier to operate
-due to automatic transmissions, automatic chokes, automatic starters,
-greatly improved reliability,
+This dramatic change came about for two basic reasons:
+(1)~Cars became cheaper and more readily available, so that
+more people had the opportunity to learn to drive,
+and (2)~Cars became easier to operate due to automatic transmissions,
+automatic chokes, automatic starters, greatly improved reliability,
 and a host of other technological improvements.
 
 The same is true for many other technologies, including computers.
@@ -155,8 +155,8 @@ as discussed in \cref{sec:cpu:Hardware Free Lunch?}.
 	how could a large number of open-source projects, ranging from Apache
 	to MySQL to the Linux kernel, have managed to master it?
 
-	A better question might be: ``Why is parallel programming {\em
-	perceived} to be so difficult?''
+	A better question might be:
+	``Why is parallel programming \emph{perceived} to be so difficult?''
 	To see the answer, let's go back to the year 1991.
 	Paul McKenney was walking across the parking lot to Sequent's
 	benchmarking center carrying six dual-80486 Sequent Symmetry CPU
@@ -311,8 +311,8 @@ Each of these goals is elaborated upon in the following sections.
 \label{sec:intro:Performance}
 
 Performance is the primary goal behind most parallel-programming effort.
-After all, if performance is not a concern, why not do yourself
-a favor:  Just write sequential code, and be happy?
+After all, if performance is not a concern, why not do yourself a favor:
+Just write sequential code, and be happy?
 It will very likely be easier
 and you will probably get done much more quickly.
 
@@ -657,8 +657,8 @@ configuration, or other setup.
 	Those who indulge in excessive generality will therefore fail to set
 	the productivity bar high enough to succeed near the top of the
 	software stack.
-	This fact of life even has its own acronym: YAGNI, or ``You
-	Ain't Gonna Need It.''
+	This fact of life even has its own acronym:
+	YAGNI, or ``You Ain't Gonna Need It.''
 }\QuickQuizEnd
 
 Unfortunately, a system that does the job required by user~1 is
@@ -939,9 +939,9 @@ available hardware and restore performance and scalabilty.
 Although partitioning can greatly improve performance and scalability,
 it can also increase complexity.
 For example, partitioning can complicate handling of global
-errors and events: A parallel
-program may need to carry out non-trivial synchronization in order
-to safely process such global events.
+errors and events:
+A parallel program may need to carry out non-trivial synchronization
+in order to safely process such global events.
 More generally, each partition requires some sort of communication:
 After all, if
 a given thread did not communicate at all, it would have no effect and
-- 
2.17.1

Re: [GIT PULL -perfbook] Add checks with regard to punctuation marks

[Paul E. McKenney]

On Thu, Jun 10, 2021 at 10:28:35AM +0900, Akira Yokosawa wrote:
> On Wed, 9 Jun 2021 12:23:47 -0700, Paul E. McKenney wrote:
> > On Wed, Jun 09, 2021 at 11:59:42AM +0900, Akira Yokosawa wrote:
> >> Hi Paul,
> >>
> >> It took a while for me to sort out the spacing width after punctuation
> >> marks.
> > 
> > Thank you very much for doing all of this!
> > 
> [...]
> >> All the offending patterns in LaTeX sources have fixed.
> >>
> >> Finally "make" will run both periodcheck and cleverefcheck.
> > 
> > Very good!!!
> > 
> >> As for colons, I'm not sure what is your preference with regard
> >> to capitalization of the next words and the spacing width after
> >> them, so no check is done at the moment.
> >>  
> >> If you have some preference, I can update the scripts to enforce
> >> it.
> > 
> > In this case, I prefer the simple British approach to that of my
> > homeland, so please unconditionally capitalize after a colon.
> > 
> > (Instead of the American approach of doing so only if the word following
> > the colon begins a complete sentence, which is not something I want to
> > be checking manually, let alone via a script!)
> 
> Please find a tentative patch below showing you how the changes would
> look like.
> 
> Does this look reasonable to you?
> 
> A couple of notes:
> 
> o In epigraph of Alice in Wonderland, I see trailing "\\"s
>   can indicate the rule to put ":"s at the end of lines is
>   knowingly broken.  I can add a rule to ignore any violations
>   on a line who has trailing "\\" (even in a comment area).

Could the "\\"s could be moved to the beginning of the next line?

> o One of the hunks in cpu/hwfreelunch.tex
> 
> > @@ -167,8 +167,8 @@ That said, they may be necessary steps on the path to the late Jim Gray's
> >  \label{sec:cpu:Novel Materials and Processes}
> >  
> >  Stephen Hawking is said to have claimed that semiconductor manufacturers
> > -have but two fundamental problems: (1) the finite speed of light and
> > -(2) the atomic nature of matter~\cite{BryanGardiner2007}.
> > +have but two fundamental problems:\@ (1)~the finite speed of light and

Now that you mention it, would it work to just put a linebreak after the
":"?

> > +(2)~the atomic nature of matter~\cite{BryanGardiner2007}.
> >  It is possible that semiconductor manufacturers are approaching these
> >  limits, but there are nevertheless a few avenues of research and
> > development focused on working around these fundamental limits.
> 
> keeps lower-case words after (1) and (2) as they are just short
> phrases.

But it would be fine to capitalize those two instances of "the" and
probably simpler all around.

> And the space after the colon is normal-width.
> Do you like capital words and double spacing?

I am not worried about spacing unless it is a monospace font, but
other than comments in code, we should have few if any instances of
end-of-sentence punctuation set in monospace fonts.

>         Thanks, Akira
> 
> -----------8<-----------
> Subject: [PATCH] howto, intro, cpu: Capitalize words after colon
> 
> And make colons at the end of input lines.
> 
> Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
> ---
>  cpu/cpu.tex         |  5 +++--
>  cpu/hwfreelunch.tex | 17 ++++++++++-------
>  cpu/overheads.tex   |  5 +++--
>  cpu/overview.tex    |  8 +++++---
>  howto/howto.tex     |  8 ++++----
>  intro/intro.tex     | 28 ++++++++++++++--------------
>  6 files changed, 39 insertions(+), 32 deletions(-)
> 
> diff --git a/cpu/cpu.tex b/cpu/cpu.tex
> index 183feb8c..8a4afc69 100644
> --- a/cpu/cpu.tex
> +++ b/cpu/cpu.tex
> @@ -54,8 +54,9 @@ So, to sum up:
>  \begin{enumerate}
>  \item	The good news is that multicore systems are inexpensive and
>  	readily available.
> -\item	More good news:  The overhead of many synchronization operations
> -	is much lower than it was on parallel systems from the early 2000s.
> +\item	More good news:
> +	The overhead of many synchronization operations is much lower
> +	than it was on parallel systems from the early 2000s.

Looks good!

>  \item	The bad news is that the overhead of cache misses is still high,
>  	especially on large systems.
>  \end{enumerate}
> diff --git a/cpu/hwfreelunch.tex b/cpu/hwfreelunch.tex
> index 92f04f16..01d3dddd 100644
> --- a/cpu/hwfreelunch.tex
> +++ b/cpu/hwfreelunch.tex
> @@ -167,8 +167,8 @@ That said, they may be necessary steps on the path to the late Jim Gray's
>  \label{sec:cpu:Novel Materials and Processes}
>  
>  Stephen Hawking is said to have claimed that semiconductor manufacturers
> -have but two fundamental problems: (1) the finite speed of light and
> -(2) the atomic nature of matter~\cite{BryanGardiner2007}.
> +have but two fundamental problems:\@ (1)~the finite speed of light and
> +(2)~the atomic nature of matter~\cite{BryanGardiner2007}.

This would be just fine:

	Stephen Hawking is said to have claimed that semiconductor
	manufacturers have but two fundamental problems:
	(1) The finite speed of light and
	(2) the atomic nature of matter~\cite{BryanGardiner2007}.

>  It is possible that semiconductor manufacturers are approaching these
>  limits, but there are nevertheless a few avenues of research and
>  development focused on working around these fundamental limits.
> @@ -228,8 +228,9 @@ general-purpose CPU will normally use a loop (possibly unrolled)
>  with a loop counter.
>  Decoding the instructions, incrementing the loop counter, testing this
>  counter, and branching back to the
> -top of the loop are in some sense wasted effort: the real goal is
> -instead to multiply corresponding elements of the two vectors.
> +top of the loop are in some sense wasted effort:
> +The real goal is instead to multiply corresponding elements of the
> +two vectors.

Looks good!

>  Therefore, a specialized piece of hardware designed specifically to
>  multiply vectors could get the job done more quickly and with less
>  energy consumed.
> @@ -263,10 +264,12 @@ These hardware accelerators are often used for media decoding,
>  so much so that a high-end MP3 player might be able to play audio
>  for several minutes---with its CPU fully powered off the entire time.
>  The purpose of these accelerators is to improve energy efficiency
> -and thus extend battery life: special purpose hardware can often
> -compute more efficiently than can a general-purpose CPU\@.
> +and thus extend battery life:
> +Special purpose hardware can often compute more efficiently than
> +can a general-purpose CPU\@.
>  This is another example of the principle called out in
> -\cref{sec:intro:Generality}: \IX{Generality} is almost never free.
> +\cref{sec:intro:Generality}:
> +\IX{Generality} is almost never free.

Looks good!

>  Nevertheless, given the end of \IXaltr{Moore's-Law}{Moore's Law}-induced
>  single-threaded performance increases, it seems safe to assume that
> diff --git a/cpu/overheads.tex b/cpu/overheads.tex
> index 80d60d9d..8cf1e94a 100644
> --- a/cpu/overheads.tex
> +++ b/cpu/overheads.tex
> @@ -500,8 +500,9 @@ cycles, as shown in the ``Global Comms'' row.
>  	use several rolls (or multiple cases) of toilet paper to represent
>  	the communications latency.
>  
> -	Important safety tip: make sure to account for the needs of
> -	those you live with when appropriating toilet paper, especially
> +	Important safety tip:
> +	Make sure to account for the needs of those you live with when
> +	appropriating toilet paper, especially
>  	in 2020 or during a similar time when store shelves are free of
>  	toilet paper and much else besides.

Looks good!

> diff --git a/cpu/overview.tex b/cpu/overview.tex
> index d1d23b36..96eecb6f 100644
> --- a/cpu/overview.tex
> +++ b/cpu/overview.tex
> @@ -5,8 +5,9 @@
>  \section{Overview}
>  \label{sec:cpu:Overview}
>  %
> -\epigraph{Mechanical Sympathy: Hardware and software working together in
> -	  harmony.}{\emph{Martin Thompson}}
> +\epigraph{Mechanical Sympathy:
> +	  Hardware and software working together in harmony.}
> +	{\emph{Martin Thompson}}

Looks good!

>  Careless reading of computer-system specification sheets might lead one
>  to believe that CPU performance is a footrace on a clear track, as
> @@ -335,7 +336,8 @@ as illustrated by
>  \cref{fig:cpu:CPU Waits for I/O Completion}.
>  
>  This is one of the differences between shared-memory and distributed-system
> -parallelism: shared-memory parallel programs must normally deal with no
> +parallelism:
> +Shared-memory parallel programs must normally deal with no
>  obstacle worse than a cache miss, while a distributed parallel program
>  will typically incur the larger network communication latencies.

Looks good!

>  In both cases, the relevant latencies can be thought of as a cost of
> diff --git a/howto/howto.tex b/howto/howto.tex
> index 0f0ba293..54447c4e 100644
> --- a/howto/howto.tex
> +++ b/howto/howto.tex
> @@ -50,7 +50,7 @@ that it has brought to us!
>  	  Alice: Which way should I go? \\
>  	  Cat: That depends on where you are going. \\
>  	  Alice: I don't know. \\
> -	  Cat: Then it doesn't matter which way you go.}
> +	  Cat: Then it doesn't matter which way you go.} % \\
>  	 {\emph{Lewis Carroll, Alice in Wonderland}}

Would this work?

	  Alice: Which way should I go? \\
	  \\ Cat: That depends on where you are going.
	  \\ Alice: I don't know.
	  \\ Cat: Then it doesn't matter which way you go.}
	 {\emph{Lewis Carroll, Alice in Wonderland}}

>  This book is a handbook of widely applicable and heavily
> @@ -359,7 +359,7 @@ Fortunately, there are many alternatives available to you:
>  	thorough and accessible introduction with a good set of
>  	examples.
>  \item	If you are interested in C++11, you might like
> -	\ppl{Anthony}{Williams}'s ``C++ Concurrency in Action: Practical
> +	\ppl{Anthony}{Williams}'s ``C++ Concurrency in Action:\@ Practical
>  	Multithreading''~\cite{AnthonyWilliams2012,AnthonyWilliams2019}.

A line break after the colon in the title would be just fine.

>  \item	If you are interested in C++, but in a Windows environment,
>  	you might try \ppl{Herb}{Sutter}'s ``Effective Concurrency''
> @@ -528,8 +528,8 @@ namely that you are certifying that:
>  
>  This is quite similar to the Developer's Certificate of Origin (DCO)
>  1.1 used by the Linux kernel.
> -You must use your real name:  I unfortunately cannot accept pseudonymous or
> -anonymous contributions.
> +You must use your real name:
> +I unfortunately cannot accept pseudonymous or anonymous contributions.

Looks good!

>  The language of this book is American English, however, the open-source
>  nature of this book permits translations, and I personally encourage them.
> diff --git a/intro/intro.tex b/intro/intro.tex
> index 5f2690fc..6835c107 100644
> --- a/intro/intro.tex
> +++ b/intro/intro.tex
> @@ -23,11 +23,11 @@ However, new technologies that are difficult to use at introduction
>  invariably become easier over time.
>  For example, the once-rare ability to drive a car is now
>  commonplace in many countries.
> -This dramatic change came about for two basic reasons: (1)~cars became
> -cheaper and more readily available, so that more people had the
> -opportunity to learn to drive, and (2)~cars became easier to operate
> -due to automatic transmissions, automatic chokes, automatic starters,
> -greatly improved reliability,
> +This dramatic change came about for two basic reasons:
> +(1)~Cars became cheaper and more readily available, so that
> +more people had the opportunity to learn to drive,
> +and (2)~Cars became easier to operate due to automatic transmissions,
> +automatic chokes, automatic starters, greatly improved reliability,
>  and a host of other technological improvements.

Looks good!

>  The same is true for many other technologies, including computers.
> @@ -155,8 +155,8 @@ as discussed in \cref{sec:cpu:Hardware Free Lunch?}.
>  	how could a large number of open-source projects, ranging from Apache
>  	to MySQL to the Linux kernel, have managed to master it?
>  
> -	A better question might be: ``Why is parallel programming {\em
> -	perceived} to be so difficult?''
> +	A better question might be:
> +	``Why is parallel programming \emph{perceived} to be so difficult?''

Looks good!

>  	To see the answer, let's go back to the year 1991.
>  	Paul McKenney was walking across the parking lot to Sequent's
>  	benchmarking center carrying six dual-80486 Sequent Symmetry CPU
> @@ -311,8 +311,8 @@ Each of these goals is elaborated upon in the following sections.
>  \label{sec:intro:Performance}
>  
>  Performance is the primary goal behind most parallel-programming effort.
> -After all, if performance is not a concern, why not do yourself
> -a favor:  Just write sequential code, and be happy?
> +After all, if performance is not a concern, why not do yourself a favor:
> +Just write sequential code, and be happy?

Looks good!

>  It will very likely be easier
>  and you will probably get done much more quickly.
>  
> @@ -657,8 +657,8 @@ configuration, or other setup.
>  	Those who indulge in excessive generality will therefore fail to set
>  	the productivity bar high enough to succeed near the top of the
>  	software stack.
> -	This fact of life even has its own acronym: YAGNI, or ``You
> -	Ain't Gonna Need It.''
> +	This fact of life even has its own acronym:
> +	YAGNI, or ``You Ain't Gonna Need It.''

Looks good!

>  }\QuickQuizEnd
>  
>  Unfortunately, a system that does the job required by user~1 is
> @@ -939,9 +939,9 @@ available hardware and restore performance and scalabilty.
>  Although partitioning can greatly improve performance and scalability,
>  it can also increase complexity.
>  For example, partitioning can complicate handling of global
> -errors and events: A parallel
> -program may need to carry out non-trivial synchronization in order
> -to safely process such global events.
> +errors and events:
> +A parallel program may need to carry out non-trivial synchronization
> +in order to safely process such global events.

Looks good!

							Thanx, Paul

>  More generally, each partition requires some sort of communication:
>  After all, if
>  a given thread did not communicate at all, it would have no effect and
> -- 
> 2.17.1
> 
> 

Re: [GIT PULL -perfbook] Add checks with regard to punctuation marks

[Akira Yokosawa]

On Thu, 10 Jun 2021 14:26:17 -0700, Paul E. McKenney wrote:
> On Thu, Jun 10, 2021 at 10:28:35AM +0900, Akira Yokosawa wrote:
>> On Wed, 9 Jun 2021 12:23:47 -0700, Paul E. McKenney wrote:
>>> On Wed, Jun 09, 2021 at 11:59:42AM +0900, Akira Yokosawa wrote:
>>>> Hi Paul,
>>>>
>>>> It took a while for me to sort out the spacing width after punctuation
>>>> marks.
>>>
>>> Thank you very much for doing all of this!
>>>
>> [...]
>>>> All the offending patterns in LaTeX sources have fixed.
>>>>
>>>> Finally "make" will run both periodcheck and cleverefcheck.
>>>
>>> Very good!!!
>>>
>>>> As for colons, I'm not sure what is your preference with regard
>>>> to capitalization of the next words and the spacing width after
>>>> them, so no check is done at the moment.
>>>>  
>>>> If you have some preference, I can update the scripts to enforce
>>>> it.
>>>
>>> In this case, I prefer the simple British approach to that of my
>>> homeland, so please unconditionally capitalize after a colon.
>>>
>>> (Instead of the American approach of doing so only if the word following
>>> the colon begins a complete sentence, which is not something I want to
>>> be checking manually, let alone via a script!)
>>
>> Please find a tentative patch below showing you how the changes would
>> look like.
>>
>> Does this look reasonable to you?
>>
>> A couple of notes:
>>
>> o In epigraph of Alice in Wonderland, I see trailing "\\"s
>>   can indicate the rule to put ":"s at the end of lines is
>>   knowingly broken.  I can add a rule to ignore any violations
>>   on a line who has trailing "\\" (even in a comment area).
> 
> Could the "\\"s could be moved to the beginning of the next line?

Please see comment below.

> 
>> o One of the hunks in cpu/hwfreelunch.tex
>>
>>> @@ -167,8 +167,8 @@ That said, they may be necessary steps on the path to the late Jim Gray's
>>>  \label{sec:cpu:Novel Materials and Processes}
>>>  
>>>  Stephen Hawking is said to have claimed that semiconductor manufacturers
>>> -have but two fundamental problems: (1) the finite speed of light and
>>> -(2) the atomic nature of matter~\cite{BryanGardiner2007}.
>>> +have but two fundamental problems:\@ (1)~the finite speed of light and
> 
> Now that you mention it, would it work to just put a linebreak after the
> ":"?

OK.

> 
>>> +(2)~the atomic nature of matter~\cite{BryanGardiner2007}.
>>>  It is possible that semiconductor manufacturers are approaching these
>>>  limits, but there are nevertheless a few avenues of research and
>>> development focused on working around these fundamental limits.
>>
>> keeps lower-case words after (1) and (2) as they are just short
>> phrases.
> 
> But it would be fine to capitalize those two instances of "the" and
> probably simpler all around.
> 
>> And the space after the colon is normal-width.
>> Do you like capital words and double spacing?
> 
> I am not worried about spacing unless it is a monospace font, but
> other than comments in code, we should have few if any instances of
> end-of-sentence punctuation set in monospace fonts.

As far as input lines break after colons, and the following words
are capitalized, the spacing will become always wider.

> 
>>         Thanks, Akira
>>
>> -----------8<-----------
>> Subject: [PATCH] howto, intro, cpu: Capitalize words after colon
>>
>> And make colons at the end of input lines.
>>
>> Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
>> ---
>>  cpu/cpu.tex         |  5 +++--
>>  cpu/hwfreelunch.tex | 17 ++++++++++-------
>>  cpu/overheads.tex   |  5 +++--
>>  cpu/overview.tex    |  8 +++++---
>>  howto/howto.tex     |  8 ++++----
>>  intro/intro.tex     | 28 ++++++++++++++--------------
>>  6 files changed, 39 insertions(+), 32 deletions(-)
>>

[...]

>> diff --git a/cpu/hwfreelunch.tex b/cpu/hwfreelunch.tex
>> index 92f04f16..01d3dddd 100644
>> --- a/cpu/hwfreelunch.tex
>> +++ b/cpu/hwfreelunch.tex
>> @@ -167,8 +167,8 @@ That said, they may be necessary steps on the path to the late Jim Gray's
>>  \label{sec:cpu:Novel Materials and Processes}
>>  
>>  Stephen Hawking is said to have claimed that semiconductor manufacturers
>> -have but two fundamental problems: (1) the finite speed of light and
>> -(2) the atomic nature of matter~\cite{BryanGardiner2007}.
>> +have but two fundamental problems:\@ (1)~the finite speed of light and
>> +(2)~the atomic nature of matter~\cite{BryanGardiner2007}.
> 
> This would be just fine:
> 
> 	Stephen Hawking is said to have claimed that semiconductor
> 	manufacturers have but two fundamental problems:
> 	(1) The finite speed of light and
> 	(2) the atomic nature of matter~\cite{BryanGardiner2007}.
> 

OK, I'll stick with this convention.

>>  It is possible that semiconductor manufacturers are approaching these
>>  limits, but there are nevertheless a few avenues of research and
>>  development focused on working around these fundamental limits.
[...]
>>  In both cases, the relevant latencies can be thought of as a cost of
>> diff --git a/howto/howto.tex b/howto/howto.tex
>> index 0f0ba293..54447c4e 100644
>> --- a/howto/howto.tex
>> +++ b/howto/howto.tex
>> @@ -50,7 +50,7 @@ that it has brought to us!
>>  	  Alice: Which way should I go? \\
>>  	  Cat: That depends on where you are going. \\
>>  	  Alice: I don't know. \\
>> -	  Cat: Then it doesn't matter which way you go.}
>> +	  Cat: Then it doesn't matter which way you go.} % \\
>>  	 {\emph{Lewis Carroll, Alice in Wonderland}}
> 
> Would this work?
> 
> 	  Alice: Which way should I go? \\
> 	  \\ Cat: That depends on where you are going.
> 	  \\ Alice: I don't know.
> 	  \\ Cat: Then it doesn't matter which way you go.}
> 	 {\emph{Lewis Carroll, Alice in Wonderland}}
> 

Unfortunately, this is rejected by \epigraph{} macro due to
the empty line caused by the successive "\\ \\" in the first and
second lines.  The error message I see is:

    ! LaTeX Error: There's no line here to end.

    See the LaTeX manual or LaTeX Companion for explanation.
    Type  H <return>  for immediate help.
     ...                                              
                                                  
    l.59 	 {\emph{Lewis Carroll, Alice in Wonderland}}
                                                  
    ? 
    ! Emergency stop.

Also, using "\\" as an exception hint might cause unexpected
false negatives.

So, I'll put line breaks after colons in this epigraph.
 
>>  This book is a handbook of widely applicable and heavily
>> @@ -359,7 +359,7 @@ Fortunately, there are many alternatives available to you:
>>  	thorough and accessible introduction with a good set of
>>  	examples.
>>  \item	If you are interested in C++11, you might like
>> -	\ppl{Anthony}{Williams}'s ``C++ Concurrency in Action: Practical
>> +	\ppl{Anthony}{Williams}'s ``C++ Concurrency in Action:\@ Practical
>>  	Multithreading''~\cite{AnthonyWilliams2012,AnthonyWilliams2019}.
> 
> A line break after the colon in the title would be just fine.

OK.

> 
>>  \item	If you are interested in C++, but in a Windows environment,
>>  	you might try \ppl{Herb}{Sutter}'s ``Effective Concurrency''

>> @@ -939,9 +939,9 @@ available hardware and restore performance and scalabilty.
>>  Although partitioning can greatly improve performance and scalability,
>>  it can also increase complexity.
>>  For example, partitioning can complicate handling of global
>> -errors and events: A parallel
>> -program may need to carry out non-trivial synchronization in order
>> -to safely process such global events.
>> +errors and events:
>> +A parallel program may need to carry out non-trivial synchronization
>> +in order to safely process such global events.
> 
> Looks good!

I'm sending a v2 of the patch soon as a reply to this message.

        Thanks, Akira

> 
> 							Thanx, Paul
> 
>>  More generally, each partition requires some sort of communication:
>>  After all, if
>>  a given thread did not communicate at all, it would have no effect and
>> -- 
>> 2.17.1
>>
>>

[PATCH v2 -perfbook] howto, intro, cpu: Break and capitalize after colon

[Akira Yokosawa]

Fix violations detected by the check scripts at hand.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
 cpu/cpu.tex         |  5 +++--
 cpu/hwfreelunch.tex | 18 +++++++++++-------
 cpu/overheads.tex   |  8 +++++---
 cpu/overview.tex    |  8 +++++---
 cpu/swdesign.tex    |  2 +-
 howto/howto.tex     | 23 ++++++++++++++---------
 intro/intro.tex     | 30 +++++++++++++++---------------
 7 files changed, 54 insertions(+), 40 deletions(-)

diff --git a/cpu/cpu.tex b/cpu/cpu.tex
index 183feb8c..8a4afc69 100644
--- a/cpu/cpu.tex
+++ b/cpu/cpu.tex
@@ -54,8 +54,9 @@ So, to sum up:
 \begin{enumerate}
 \item	The good news is that multicore systems are inexpensive and
 	readily available.
-\item	More good news:  The overhead of many synchronization operations
-	is much lower than it was on parallel systems from the early 2000s.
+\item	More good news:
+	The overhead of many synchronization operations is much lower
+	than it was on parallel systems from the early 2000s.
 \item	The bad news is that the overhead of cache misses is still high,
 	especially on large systems.
 \end{enumerate}
diff --git a/cpu/hwfreelunch.tex b/cpu/hwfreelunch.tex
index 92f04f16..68c6dd5f 100644
--- a/cpu/hwfreelunch.tex
+++ b/cpu/hwfreelunch.tex
@@ -167,8 +167,9 @@ That said, they may be necessary steps on the path to the late Jim Gray's
 \label{sec:cpu:Novel Materials and Processes}
 
 Stephen Hawking is said to have claimed that semiconductor manufacturers
-have but two fundamental problems: (1) the finite speed of light and
-(2) the atomic nature of matter~\cite{BryanGardiner2007}.
+have but two fundamental problems:
+(1)~The finite speed of light and
+(2)~the atomic nature of matter~\cite{BryanGardiner2007}.
 It is possible that semiconductor manufacturers are approaching these
 limits, but there are nevertheless a few avenues of research and
 development focused on working around these fundamental limits.
@@ -228,8 +229,9 @@ general-purpose CPU will normally use a loop (possibly unrolled)
 with a loop counter.
 Decoding the instructions, incrementing the loop counter, testing this
 counter, and branching back to the
-top of the loop are in some sense wasted effort: the real goal is
-instead to multiply corresponding elements of the two vectors.
+top of the loop are in some sense wasted effort:
+The real goal is instead to multiply corresponding elements of the
+two vectors.
 Therefore, a specialized piece of hardware designed specifically to
 multiply vectors could get the job done more quickly and with less
 energy consumed.
@@ -263,10 +265,12 @@ These hardware accelerators are often used for media decoding,
 so much so that a high-end MP3 player might be able to play audio
 for several minutes---with its CPU fully powered off the entire time.
 The purpose of these accelerators is to improve energy efficiency
-and thus extend battery life: special purpose hardware can often
-compute more efficiently than can a general-purpose CPU\@.
+and thus extend battery life:
+Special purpose hardware can often compute more efficiently than
+can a general-purpose CPU\@.
 This is another example of the principle called out in
-\cref{sec:intro:Generality}: \IX{Generality} is almost never free.
+\cref{sec:intro:Generality}:
+\IX{Generality} is almost never free.
 
 Nevertheless, given the end of \IXaltr{Moore's-Law}{Moore's Law}-induced
 single-threaded performance increases, it seems safe to assume that
diff --git a/cpu/overheads.tex b/cpu/overheads.tex
index 80d60d9d..4aeae6cd 100644
--- a/cpu/overheads.tex
+++ b/cpu/overheads.tex
@@ -500,8 +500,9 @@ cycles, as shown in the ``Global Comms'' row.
 	use several rolls (or multiple cases) of toilet paper to represent
 	the communications latency.
 
-	Important safety tip: make sure to account for the needs of
-	those you live with when appropriating toilet paper, especially
+	Important safety tip:
+	Make sure to account for the needs of those you live with when
+	appropriating toilet paper, especially
 	in 2020 or during a similar time when store shelves are free of
 	toilet paper and much else besides.
 
@@ -584,7 +585,8 @@ exceedingly efficiently, and is the subject of
 \begin{figure}
 \centering
 \resizebox{3in}{!}{\includegraphics{cartoons/Data-chasing-light-wave}}
-\caption{Hardware and Software: On Same Side}
+\caption{Hardware and Software:
+				On Same Side}
 \ContributedBy{Figure}{fig:cpu:Hardware and Software: On Same Side}{Melissa Broussard}
 \end{figure}
 
diff --git a/cpu/overview.tex b/cpu/overview.tex
index d1d23b36..33918e49 100644
--- a/cpu/overview.tex
+++ b/cpu/overview.tex
@@ -5,8 +5,9 @@
 \section{Overview}
 \label{sec:cpu:Overview}
 %
-\epigraph{Mechanical Sympathy: Hardware and software working together in
-	  harmony.}{\emph{Martin Thompson}}
+\epigraph{Mechanical Sympathy:
+	  Hardware and software working together in harmony.}
+	 {\emph{Martin Thompson}}
 
 Careless reading of computer-system specification sheets might lead one
 to believe that CPU performance is a footrace on a clear track, as
@@ -335,7 +336,8 @@ as illustrated by
 \cref{fig:cpu:CPU Waits for I/O Completion}.
 
 This is one of the differences between shared-memory and distributed-system
-parallelism: shared-memory parallel programs must normally deal with no
+parallelism:
+Shared-memory parallel programs must normally deal with no
 obstacle worse than a cache miss, while a distributed parallel program
 will typically incur the larger network communication latencies.
 In both cases, the relevant latencies can be thought of as a cost of
diff --git a/cpu/swdesign.tex b/cpu/swdesign.tex
index 63b6222f..75541229 100644
--- a/cpu/swdesign.tex
+++ b/cpu/swdesign.tex
@@ -82,7 +82,7 @@ be extremely infrequent and to enable very large quantities of processing.
 }\QuickQuizEnd
 
 The lesson should be quite clear:
-parallel algorithms must be explicitly designed with these hardware
+Parallel algorithms must be explicitly designed with these hardware
 properties firmly in mind.
 One approach is to run nearly independent threads.
 The less frequently the threads communicate, whether by \IX{atomic} operations,
diff --git a/howto/howto.tex b/howto/howto.tex
index 0f0ba293..8bc9e8e5 100644
--- a/howto/howto.tex
+++ b/howto/howto.tex
@@ -46,11 +46,16 @@ that it has brought to us!
 \section{Roadmap}
 \label{sec:howto:Roadmap}
 %
-\epigraph{Cat: Where are you going? \\
-	  Alice: Which way should I go? \\
-	  Cat: That depends on where you are going. \\
-	  Alice: I don't know. \\
-	  Cat: Then it doesn't matter which way you go.}
+\epigraph{Cat:
+		Where are you going? \\
+	  Alice:
+		Which way should I go? \\
+	  Cat:
+		That depends on where you are going. \\
+	  Alice:
+		I don't know. \\
+	  Cat:
+		Then it doesn't matter which way you go.}
 	 {\emph{Lewis Carroll, Alice in Wonderland}}
 
 This book is a handbook of widely applicable and heavily
@@ -359,8 +364,8 @@ Fortunately, there are many alternatives available to you:
 	thorough and accessible introduction with a good set of
 	examples.
 \item	If you are interested in C++11, you might like
-	\ppl{Anthony}{Williams}'s ``C++ Concurrency in Action: Practical
-	Multithreading''~\cite{AnthonyWilliams2012,AnthonyWilliams2019}.
+	\ppl{Anthony}{Williams}'s ``C++ Concurrency in Action:
+	Practical Multithreading''~\cite{AnthonyWilliams2012,AnthonyWilliams2019}.
 \item	If you are interested in C++, but in a Windows environment,
 	you might try \ppl{Herb}{Sutter}'s ``Effective Concurrency''
 	series in
@@ -528,8 +533,8 @@ namely that you are certifying that:
 
 This is quite similar to the Developer's Certificate of Origin (DCO)
 1.1 used by the Linux kernel.
-You must use your real name:  I unfortunately cannot accept pseudonymous or
-anonymous contributions.
+You must use your real name:
+I unfortunately cannot accept pseudonymous or anonymous contributions.
 
 The language of this book is American English, however, the open-source
 nature of this book permits translations, and I personally encourage them.
diff --git a/intro/intro.tex b/intro/intro.tex
index 5f2690fc..b185a7f7 100644
--- a/intro/intro.tex
+++ b/intro/intro.tex
@@ -23,11 +23,11 @@ However, new technologies that are difficult to use at introduction
 invariably become easier over time.
 For example, the once-rare ability to drive a car is now
 commonplace in many countries.
-This dramatic change came about for two basic reasons: (1)~cars became
-cheaper and more readily available, so that more people had the
-opportunity to learn to drive, and (2)~cars became easier to operate
-due to automatic transmissions, automatic chokes, automatic starters,
-greatly improved reliability,
+This dramatic change came about for two basic reasons:
+(1)~Cars became cheaper and more readily available, so that
+more people had the opportunity to learn to drive,
+and (2)~Cars became easier to operate due to automatic transmissions,
+automatic chokes, automatic starters, greatly improved reliability,
 and a host of other technological improvements.
 
 The same is true for many other technologies, including computers.
@@ -155,8 +155,8 @@ as discussed in \cref{sec:cpu:Hardware Free Lunch?}.
 	how could a large number of open-source projects, ranging from Apache
 	to MySQL to the Linux kernel, have managed to master it?
 
-	A better question might be: ``Why is parallel programming {\em
-	perceived} to be so difficult?''
+	A better question might be:
+	``Why is parallel programming \emph{perceived} to be so difficult?''
 	To see the answer, let's go back to the year 1991.
 	Paul McKenney was walking across the parking lot to Sequent's
 	benchmarking center carrying six dual-80486 Sequent Symmetry CPU
@@ -311,8 +311,8 @@ Each of these goals is elaborated upon in the following sections.
 \label{sec:intro:Performance}
 
 Performance is the primary goal behind most parallel-programming effort.
-After all, if performance is not a concern, why not do yourself
-a favor:  Just write sequential code, and be happy?
+After all, if performance is not a concern, why not do yourself a favor:
+Just write sequential code, and be happy?
 It will very likely be easier
 and you will probably get done much more quickly.
 
@@ -657,8 +657,8 @@ configuration, or other setup.
 	Those who indulge in excessive generality will therefore fail to set
 	the productivity bar high enough to succeed near the top of the
 	software stack.
-	This fact of life even has its own acronym: YAGNI, or ``You
-	Ain't Gonna Need It.''
+	This fact of life even has its own acronym:
+	YAGNI, or ``You Ain't Gonna Need It.''
 }\QuickQuizEnd
 
 Unfortunately, a system that does the job required by user~1 is
@@ -928,7 +928,7 @@ each of which is covered in the following sections.
 \label{sec:intro:Work Partitioning}
 
 Work partitioning is absolutely required for parallel execution:
-if there is but one ``glob'' of work, then it can be executed by at
+If there is but one ``glob'' of work, then it can be executed by at
 most one CPU at a time, which is by definition sequential execution.
 However, partitioning the work requires great care.
 For example, uneven partitioning can result in sequential execution
@@ -939,9 +939,9 @@ available hardware and restore performance and scalabilty.
 Although partitioning can greatly improve performance and scalability,
 it can also increase complexity.
 For example, partitioning can complicate handling of global
-errors and events: A parallel
-program may need to carry out non-trivial synchronization in order
-to safely process such global events.
+errors and events:
+A parallel program may need to carry out non-trivial synchronization
+in order to safely process such global events.
 More generally, each partition requires some sort of communication:
 After all, if
 a given thread did not communicate at all, it would have no effect and
-- 
2.17.1

Re: [PATCH v2 -perfbook] howto, intro, cpu: Break and capitalize after colon

[Paul E. McKenney]

On Sat, Jun 12, 2021 at 03:14:52PM +0900, Akira Yokosawa wrote:
> Fix violations detected by the check scripts at hand.
> 
> Signed-off-by: Akira Yokosawa <akiyks@gmail.com>

I have pulled this in, thank you very much!

There is one mistake I made in my previous reply, and I have fixed
this.  Please see below.

> ---
>  cpu/cpu.tex         |  5 +++--
>  cpu/hwfreelunch.tex | 18 +++++++++++-------
>  cpu/overheads.tex   |  8 +++++---
>  cpu/overview.tex    |  8 +++++---
>  cpu/swdesign.tex    |  2 +-
>  howto/howto.tex     | 23 ++++++++++++++---------
>  intro/intro.tex     | 30 +++++++++++++++---------------
>  7 files changed, 54 insertions(+), 40 deletions(-)
> 
> diff --git a/cpu/cpu.tex b/cpu/cpu.tex
> index 183feb8c..8a4afc69 100644
> --- a/cpu/cpu.tex
> +++ b/cpu/cpu.tex
> @@ -54,8 +54,9 @@ So, to sum up:
>  \begin{enumerate}
>  \item	The good news is that multicore systems are inexpensive and
>  	readily available.
> -\item	More good news:  The overhead of many synchronization operations
> -	is much lower than it was on parallel systems from the early 2000s.
> +\item	More good news:
> +	The overhead of many synchronization operations is much lower
> +	than it was on parallel systems from the early 2000s.
>  \item	The bad news is that the overhead of cache misses is still high,
>  	especially on large systems.
>  \end{enumerate}
> diff --git a/cpu/hwfreelunch.tex b/cpu/hwfreelunch.tex
> index 92f04f16..68c6dd5f 100644
> --- a/cpu/hwfreelunch.tex
> +++ b/cpu/hwfreelunch.tex
> @@ -167,8 +167,9 @@ That said, they may be necessary steps on the path to the late Jim Gray's
>  \label{sec:cpu:Novel Materials and Processes}
>  
>  Stephen Hawking is said to have claimed that semiconductor manufacturers
> -have but two fundamental problems: (1) the finite speed of light and
> -(2) the atomic nature of matter~\cite{BryanGardiner2007}.
> +have but two fundamental problems:
> +(1)~The finite speed of light and
> +(2)~the atomic nature of matter~\cite{BryanGardiner2007}.

I should have capitalized the "the" in this last line.  I did so before
applying your patch.

							Thanx, Paul

>  It is possible that semiconductor manufacturers are approaching these
>  limits, but there are nevertheless a few avenues of research and
>  development focused on working around these fundamental limits.
> @@ -228,8 +229,9 @@ general-purpose CPU will normally use a loop (possibly unrolled)
>  with a loop counter.
>  Decoding the instructions, incrementing the loop counter, testing this
>  counter, and branching back to the
> -top of the loop are in some sense wasted effort: the real goal is
> -instead to multiply corresponding elements of the two vectors.
> +top of the loop are in some sense wasted effort:
> +The real goal is instead to multiply corresponding elements of the
> +two vectors.
>  Therefore, a specialized piece of hardware designed specifically to
>  multiply vectors could get the job done more quickly and with less
>  energy consumed.
> @@ -263,10 +265,12 @@ These hardware accelerators are often used for media decoding,
>  so much so that a high-end MP3 player might be able to play audio
>  for several minutes---with its CPU fully powered off the entire time.
>  The purpose of these accelerators is to improve energy efficiency
> -and thus extend battery life: special purpose hardware can often
> -compute more efficiently than can a general-purpose CPU\@.
> +and thus extend battery life:
> +Special purpose hardware can often compute more efficiently than
> +can a general-purpose CPU\@.
>  This is another example of the principle called out in
> -\cref{sec:intro:Generality}: \IX{Generality} is almost never free.
> +\cref{sec:intro:Generality}:
> +\IX{Generality} is almost never free.
>  
>  Nevertheless, given the end of \IXaltr{Moore's-Law}{Moore's Law}-induced
>  single-threaded performance increases, it seems safe to assume that
> diff --git a/cpu/overheads.tex b/cpu/overheads.tex
> index 80d60d9d..4aeae6cd 100644
> --- a/cpu/overheads.tex
> +++ b/cpu/overheads.tex
> @@ -500,8 +500,9 @@ cycles, as shown in the ``Global Comms'' row.
>  	use several rolls (or multiple cases) of toilet paper to represent
>  	the communications latency.
>  
> -	Important safety tip: make sure to account for the needs of
> -	those you live with when appropriating toilet paper, especially
> +	Important safety tip:
> +	Make sure to account for the needs of those you live with when
> +	appropriating toilet paper, especially
>  	in 2020 or during a similar time when store shelves are free of
>  	toilet paper and much else besides.
>  
> @@ -584,7 +585,8 @@ exceedingly efficiently, and is the subject of
>  \begin{figure}
>  \centering
>  \resizebox{3in}{!}{\includegraphics{cartoons/Data-chasing-light-wave}}
> -\caption{Hardware and Software: On Same Side}
> +\caption{Hardware and Software:
> +				On Same Side}
>  \ContributedBy{Figure}{fig:cpu:Hardware and Software: On Same Side}{Melissa Broussard}
>  \end{figure}
>  
> diff --git a/cpu/overview.tex b/cpu/overview.tex
> index d1d23b36..33918e49 100644
> --- a/cpu/overview.tex
> +++ b/cpu/overview.tex
> @@ -5,8 +5,9 @@
>  \section{Overview}
>  \label{sec:cpu:Overview}
>  %
> -\epigraph{Mechanical Sympathy: Hardware and software working together in
> -	  harmony.}{\emph{Martin Thompson}}
> +\epigraph{Mechanical Sympathy:
> +	  Hardware and software working together in harmony.}
> +	 {\emph{Martin Thompson}}
>  
>  Careless reading of computer-system specification sheets might lead one
>  to believe that CPU performance is a footrace on a clear track, as
> @@ -335,7 +336,8 @@ as illustrated by
>  \cref{fig:cpu:CPU Waits for I/O Completion}.
>  
>  This is one of the differences between shared-memory and distributed-system
> -parallelism: shared-memory parallel programs must normally deal with no
> +parallelism:
> +Shared-memory parallel programs must normally deal with no
>  obstacle worse than a cache miss, while a distributed parallel program
>  will typically incur the larger network communication latencies.
>  In both cases, the relevant latencies can be thought of as a cost of
> diff --git a/cpu/swdesign.tex b/cpu/swdesign.tex
> index 63b6222f..75541229 100644
> --- a/cpu/swdesign.tex
> +++ b/cpu/swdesign.tex
> @@ -82,7 +82,7 @@ be extremely infrequent and to enable very large quantities of processing.
>  }\QuickQuizEnd
>  
>  The lesson should be quite clear:
> -parallel algorithms must be explicitly designed with these hardware
> +Parallel algorithms must be explicitly designed with these hardware
>  properties firmly in mind.
>  One approach is to run nearly independent threads.
>  The less frequently the threads communicate, whether by \IX{atomic} operations,
> diff --git a/howto/howto.tex b/howto/howto.tex
> index 0f0ba293..8bc9e8e5 100644
> --- a/howto/howto.tex
> +++ b/howto/howto.tex
> @@ -46,11 +46,16 @@ that it has brought to us!
>  \section{Roadmap}
>  \label{sec:howto:Roadmap}
>  %
> -\epigraph{Cat: Where are you going? \\
> -	  Alice: Which way should I go? \\
> -	  Cat: That depends on where you are going. \\
> -	  Alice: I don't know. \\
> -	  Cat: Then it doesn't matter which way you go.}
> +\epigraph{Cat:
> +		Where are you going? \\
> +	  Alice:
> +		Which way should I go? \\
> +	  Cat:
> +		That depends on where you are going. \\
> +	  Alice:
> +		I don't know. \\
> +	  Cat:
> +		Then it doesn't matter which way you go.}
>  	 {\emph{Lewis Carroll, Alice in Wonderland}}
>  
>  This book is a handbook of widely applicable and heavily
> @@ -359,8 +364,8 @@ Fortunately, there are many alternatives available to you:
>  	thorough and accessible introduction with a good set of
>  	examples.
>  \item	If you are interested in C++11, you might like
> -	\ppl{Anthony}{Williams}'s ``C++ Concurrency in Action: Practical
> -	Multithreading''~\cite{AnthonyWilliams2012,AnthonyWilliams2019}.
> +	\ppl{Anthony}{Williams}'s ``C++ Concurrency in Action:
> +	Practical Multithreading''~\cite{AnthonyWilliams2012,AnthonyWilliams2019}.
>  \item	If you are interested in C++, but in a Windows environment,
>  	you might try \ppl{Herb}{Sutter}'s ``Effective Concurrency''
>  	series in
> @@ -528,8 +533,8 @@ namely that you are certifying that:
>  
>  This is quite similar to the Developer's Certificate of Origin (DCO)
>  1.1 used by the Linux kernel.
> -You must use your real name:  I unfortunately cannot accept pseudonymous or
> -anonymous contributions.
> +You must use your real name:
> +I unfortunately cannot accept pseudonymous or anonymous contributions.
>  
>  The language of this book is American English, however, the open-source
>  nature of this book permits translations, and I personally encourage them.
> diff --git a/intro/intro.tex b/intro/intro.tex
> index 5f2690fc..b185a7f7 100644
> --- a/intro/intro.tex
> +++ b/intro/intro.tex
> @@ -23,11 +23,11 @@ However, new technologies that are difficult to use at introduction
>  invariably become easier over time.
>  For example, the once-rare ability to drive a car is now
>  commonplace in many countries.
> -This dramatic change came about for two basic reasons: (1)~cars became
> -cheaper and more readily available, so that more people had the
> -opportunity to learn to drive, and (2)~cars became easier to operate
> -due to automatic transmissions, automatic chokes, automatic starters,
> -greatly improved reliability,
> +This dramatic change came about for two basic reasons:
> +(1)~Cars became cheaper and more readily available, so that
> +more people had the opportunity to learn to drive,
> +and (2)~Cars became easier to operate due to automatic transmissions,
> +automatic chokes, automatic starters, greatly improved reliability,
>  and a host of other technological improvements.
>  
>  The same is true for many other technologies, including computers.
> @@ -155,8 +155,8 @@ as discussed in \cref{sec:cpu:Hardware Free Lunch?}.
>  	how could a large number of open-source projects, ranging from Apache
>  	to MySQL to the Linux kernel, have managed to master it?
>  
> -	A better question might be: ``Why is parallel programming {\em
> -	perceived} to be so difficult?''
> +	A better question might be:
> +	``Why is parallel programming \emph{perceived} to be so difficult?''
>  	To see the answer, let's go back to the year 1991.
>  	Paul McKenney was walking across the parking lot to Sequent's
>  	benchmarking center carrying six dual-80486 Sequent Symmetry CPU
> @@ -311,8 +311,8 @@ Each of these goals is elaborated upon in the following sections.
>  \label{sec:intro:Performance}
>  
>  Performance is the primary goal behind most parallel-programming effort.
> -After all, if performance is not a concern, why not do yourself
> -a favor:  Just write sequential code, and be happy?
> +After all, if performance is not a concern, why not do yourself a favor:
> +Just write sequential code, and be happy?
>  It will very likely be easier
>  and you will probably get done much more quickly.
>  
> @@ -657,8 +657,8 @@ configuration, or other setup.
>  	Those who indulge in excessive generality will therefore fail to set
>  	the productivity bar high enough to succeed near the top of the
>  	software stack.
> -	This fact of life even has its own acronym: YAGNI, or ``You
> -	Ain't Gonna Need It.''
> +	This fact of life even has its own acronym:
> +	YAGNI, or ``You Ain't Gonna Need It.''
>  }\QuickQuizEnd
>  
>  Unfortunately, a system that does the job required by user~1 is
> @@ -928,7 +928,7 @@ each of which is covered in the following sections.
>  \label{sec:intro:Work Partitioning}
>  
>  Work partitioning is absolutely required for parallel execution:
> -if there is but one ``glob'' of work, then it can be executed by at
> +If there is but one ``glob'' of work, then it can be executed by at
>  most one CPU at a time, which is by definition sequential execution.
>  However, partitioning the work requires great care.
>  For example, uneven partitioning can result in sequential execution
> @@ -939,9 +939,9 @@ available hardware and restore performance and scalabilty.
>  Although partitioning can greatly improve performance and scalability,
>  it can also increase complexity.
>  For example, partitioning can complicate handling of global
> -errors and events: A parallel
> -program may need to carry out non-trivial synchronization in order
> -to safely process such global events.
> +errors and events:
> +A parallel program may need to carry out non-trivial synchronization
> +in order to safely process such global events.
>  More generally, each partition requires some sort of communication:
>  After all, if
>  a given thread did not communicate at all, it would have no effect and
> -- 
> 2.17.1
> 
> 

Re: [PATCH v2 -perfbook] howto, intro, cpu: Break and capitalize after colon

[Akira Yokosawa]

On Sun, 13 Jun 2021 08:57:25 -0700, Paul E. McKenney wrote:
> On Sat, Jun 12, 2021 at 03:14:52PM +0900, Akira Yokosawa wrote:
>> Fix violations detected by the check scripts at hand.
>>
>> Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
> 
> I have pulled this in, thank you very much!
> 
> There is one mistake I made in my previous reply, and I have fixed
> this.  Please see below.
> 
[...]
>> diff --git a/cpu/hwfreelunch.tex b/cpu/hwfreelunch.tex
>> index 92f04f16..68c6dd5f 100644
>> --- a/cpu/hwfreelunch.tex
>> +++ b/cpu/hwfreelunch.tex
>> @@ -167,8 +167,9 @@ That said, they may be necessary steps on the path to the late Jim Gray's
>>  \label{sec:cpu:Novel Materials and Processes}
>>  
>>  Stephen Hawking is said to have claimed that semiconductor manufacturers
>> -have but two fundamental problems: (1) the finite speed of light and
>> -(2) the atomic nature of matter~\cite{BryanGardiner2007}.
>> +have but two fundamental problems:
>> +(1)~The finite speed of light and
>> +(2)~the atomic nature of matter~\cite{BryanGardiner2007}.
> 
> I should have capitalized the "the" in this last line.  I did so before
> applying your patch.

Well, I'm afraid this pattern is well beyond the capability of the dumb
perl script.  (Hint: It only looks at the next input line of colon.)

Anyway, I'll update the other chapters in the same manner.

        Thanks, Akira

> 
> 							Thanx, Paul
> 
>>  It is possible that semiconductor manufacturers are approaching these
>>  limits, but there are nevertheless a few avenues of research and
>>  development focused on working around these fundamental limits.
[...]

Re: [PATCH v2 -perfbook] howto, intro, cpu: Break and capitalize after colon

[Paul E. McKenney]

On Mon, Jun 14, 2021 at 07:58:59AM +0900, Akira Yokosawa wrote:
> On Sun, 13 Jun 2021 08:57:25 -0700, Paul E. McKenney wrote:
> > On Sat, Jun 12, 2021 at 03:14:52PM +0900, Akira Yokosawa wrote:
> >> Fix violations detected by the check scripts at hand.
> >>
> >> Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
> > 
> > I have pulled this in, thank you very much!
> > 
> > There is one mistake I made in my previous reply, and I have fixed
> > this.  Please see below.
> > 
> [...]
> >> diff --git a/cpu/hwfreelunch.tex b/cpu/hwfreelunch.tex
> >> index 92f04f16..68c6dd5f 100644
> >> --- a/cpu/hwfreelunch.tex
> >> +++ b/cpu/hwfreelunch.tex
> >> @@ -167,8 +167,9 @@ That said, they may be necessary steps on the path to the late Jim Gray's
> >>  \label{sec:cpu:Novel Materials and Processes}
> >>  
> >>  Stephen Hawking is said to have claimed that semiconductor manufacturers
> >> -have but two fundamental problems: (1) the finite speed of light and
> >> -(2) the atomic nature of matter~\cite{BryanGardiner2007}.
> >> +have but two fundamental problems:
> >> +(1)~The finite speed of light and
> >> +(2)~the atomic nature of matter~\cite{BryanGardiner2007}.
> > 
> > I should have capitalized the "the" in this last line.  I did so before
> > applying your patch.
> 
> Well, I'm afraid this pattern is well beyond the capability of the dumb
> perl script.  (Hint: It only looks at the next input line of colon.)

I cannot complain, given that you have taken the checking scripts far
beyond what I expected.  Having a few manual checks still required
is no dishonor.  ;-)

> Anyway, I'll update the other chapters in the same manner.

Thank you very much!

							Thanx, Paul