[PATCH 0/5] debugging: Trivial fixups

[PATCH 0/5] debugging: Trivial fixups

[SeongJae Park]

From: SeongJae Park <sj38.park@gmail.com>

This patchset contains trivial fixups for debugging/, which found while
doing Korean translation[1].

[1] https://github.com/sjp38/perfbook-ko_KR

SeongJae Park (5):
  debugging: Use \co{} for 'time' output examples
  debugging: Use \co{} for 'git' and 'Fixes:'
  debugging: Use \co{} for rcutorture
  debugging: Remove unnecessary space in a sentence
  debugging/debugging: s/remainder of a section/following sections/

 debugging/debugging.tex | 38 +++++++++++++++++++-------------------
 1 file changed, 19 insertions(+), 19 deletions(-)

-- 
2.17.1

[PATCH 1/5] debugging: Use \co{} for 'time' output examples

[SeongJae Park]

From: SeongJae Park <sj38.park@gmail.com>

A quick quiz answer in debugging.tex is wrapping 'time' example outputs
with `` and ''.  Use \co{} instead.

Signed-off-by: SeongJae Park <sj38.park@gmail.com>
---
 debugging/debugging.tex | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/debugging/debugging.tex b/debugging/debugging.tex
index 4568f90a..3104bb95 100644
--- a/debugging/debugging.tex
+++ b/debugging/debugging.tex
@@ -257,8 +257,8 @@ validation is just job for you.
 		consumed in system mode by a CPU-bound program?
 	\item	Do you have a test case in which all three times
 		are zero?
-	\item	Do you have a test case in which the ``user'' and ``sys''
-		times sum to more than the ``real'' time?
+	\item	Do you have a test case in which the \co{user} and \co{sys}
+		times sum to more than the \co{real} time?
 		(This would of course be completely legitimate in
 		a multithreaded program.)
 	\item	Do you have a set of tests cases in which one of the
@@ -267,7 +267,7 @@ validation is just job for you.
 		times uses more than ten seconds?
 	\item	Do you have a set of test cases in which one of the
 		times has non-zero minutes?
-		(For example, ``15m36.342s''.)
+		(For example, \co{15m36.342s}.)
 	\item	Do you have a set of test cases in which one of the
 		times has a seconds value of greater than 60?
 	\item	Do you have a set of test cases in which one of the
@@ -279,21 +279,21 @@ validation is just job for you.
 		times has a positive minutes value but a negative
 		seconds value?
 	\item	Do you have a set of test cases in which one of the
-		times omits the ``m'' or the ``s''?
+		times omits the \co{m} or the \co{s}?
 	\item	Do you have a set of test cases in which one of the
 		times is non-numeric?
-		(For example, ``Go Fish''.)
+		(For example, \co{Go Fish}.)
 	\item	Do you have a set of test cases in which one of the
 		lines is omitted?
-		(For example, where there is a ``real'' value and
-		a ``sys'' value, but no ``user'' value.)
+		(For example, where there is a \co{real} value and
+		a \co{sys} value, but no \co{user} value.)
 	\item	Do you have a set of test cases where one of the
 		lines is duplicated?
 		Or duplicated, but with a different time value for
 		the duplicate?
 	\item	Do you have a set of test cases where a given line
 		has more than one time value?
-		(For example, ``real 0m0.132s 0m0.008s''.)
+		(For example, \co{real 0m0.132s 0m0.008s}.)
 	\item	Do you have a set of test cases containing random
 		characters?
 	\item	In all test cases involving invalid input, did you
-- 
2.17.1

[PATCH 2/5] debugging: Use \co{} for 'git' and 'Fixes:'

[SeongJae Park]

From: SeongJae Park <sj38.park@gmail.com>

In 'debugging/', 'git' is a command and 'Fixes:' is a string in command
output, which usually enclosed via '\co{}', but those are enclosed with
'\emph{}'.  Use '\co{}' instead for being more consistent.

Signed-off-by: SeongJae Park <sj38.park@gmail.com>
---
 debugging/debugging.tex | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/debugging/debugging.tex b/debugging/debugging.tex
index 3104bb95..3ce74469 100644
--- a/debugging/debugging.tex
+++ b/debugging/debugging.tex
@@ -862,8 +862,8 @@ by the author's invalid assumptions, and who might also test the code.
 	hackers of harboring???
 }\QuickQuizAnswer{
 	Those wishing a complete answer to this question are encouraged
-	to search the Linux kernel \emph{git} repository for commits
-	containing the string ``Fixes:''.
+	to search the Linux kernel \co{git} repository for commits
+	containing the string \co{Fixes:}.
 	There were many thousands of them just in the year 2020, including
 	fixes for the following invalid assumptions:
 
-- 
2.17.1

[PATCH 3/5] debugging: Use \co{} for rcutorture

[SeongJae Park]

From: SeongJae Park <sj38.park@gmail.com>

Some sentences in debugging.tex encloses 'rcutorture' with while some
others don't.  Use \co{} consistently.

Signed-off-by: SeongJae Park <sj38.park@gmail.com>
---
 debugging/debugging.tex | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/debugging/debugging.tex b/debugging/debugging.tex
index 3ce74469..1903c5db 100644
--- a/debugging/debugging.tex
+++ b/debugging/debugging.tex
@@ -697,7 +697,7 @@ what it knows is almost always way more than your head can hold.
 For this reason, high-quality test suites normally come with sophisticated
 scripts to analyze the voluminous output.
 But beware---scripts will only notice what you tell them to.
-My rcutorture scripts are a case in point:
+My \co{rcutorture} scripts are a case in point:
 Early versions of those scripts were quite satisfied with a test run
 in which RCU \IXpl{grace period} stalled indefinitely.
 This of course resulted in the scripts being modified to detect RCU
@@ -1252,14 +1252,14 @@ of time you spent testing.
 Functional tests tend to be discrete.
 
 On the other hand, if my patch involved RCU, I would probably run
-rcutorture, which is a kernel module that, strangely enough, tests RCU\@.
+\co{rcutorture}, which is a kernel module that, strangely enough, tests RCU\@.
 Unlike booting the kernel, where the appearance of a login prompt
-signals the successful end of a discrete test, rcutorture will happily
+signals the successful end of a discrete test, \co{rcutorture} will happily
 continue torturing RCU until either the kernel crashes or until you
 tell it to stop.
-The duration of the rcutorture test is usually of more
+The duration of the \co{rcutorture} test is usually of more
 interest than the number of times you started and stopped it.
-Therefore, rcutorture is an example of a continuous test, a category
+Therefore, \co{rcutorture} is an example of a continuous test, a category
 that includes many stress tests.
 
 Statistics for discrete tests are simpler and more familiar than those
@@ -1845,7 +1845,7 @@ If the program is structured such that it is difficult or impossible
 to apply much stress to a subsystem that is under suspicion,
 a useful anti-heisenbug is a stress test that tests that subsystem in
 isolation.
-The Linux kernel's rcutorture module takes exactly this approach with RCU\@:
+The Linux kernel's \co{rcutorture} module takes exactly this approach with RCU\@:
 Applying more stress to RCU than is feasible in a production environment
 increases the probability that RCU bugs will be found during testing
 rather than in production.\footnote{
@@ -1918,7 +1918,7 @@ delay might be counted as a near miss.\footnote{
 \end{figure}
 
 For example, a low-probability bug in RCU priority boosting occurred
-roughly once every hundred hours of focused rcutorture testing.
+roughly once every hundred hours of focused \co{rcutorture} testing.
 Because it would take almost 500 hours of failure-free testing to be
 99\,\% certain that the bug's probability had been significantly reduced,
 the \co{git bisect} process
-- 
2.17.1

[PATCH 4/5] debugging: Remove unnecessary space in a sentence

[SeongJae Park]

From: SeongJae Park <sj38.park@gmail.com>

Two spaces are usually used between sentences, but a sentence in
debugging is using two spaces inside a sentence.  Make it uses only one
space for consistency.

Signed-off-by: SeongJae Park <sj38.park@gmail.com>
---
 debugging/debugging.tex | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/debugging/debugging.tex b/debugging/debugging.tex
index 1903c5db..53c7fb94 100644
--- a/debugging/debugging.tex
+++ b/debugging/debugging.tex
@@ -2153,7 +2153,7 @@ serve four major purposes:
 	against your competitors' offerings.
 \end{enumerate}
 
-Of course,  the only completely fair framework is the intended
+Of course, the only completely fair framework is the intended
 application itself.
 So why would anyone who cared about fairness in benchmarking
 bother creating imperfect benchmarks rather than simply
-- 
2.17.1

[PATCH 5/5] debugging/debugging: s/remainder of a section/following sections/

[SeongJae Park]

From: SeongJae Park <sj38.park@gmail.com>

A sectence in 'Microbenchmarking' section is mentioning the remainder of
the section will look at ways for dealing with conflicts in measurement
error advices, but those are not dealt in the remainder of the section
but its following sections.  Fix the sentence.

Signed-off-by: SeongJae Park <sj38.park@gmail.com>
---
 debugging/debugging.tex | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/debugging/debugging.tex b/debugging/debugging.tex
index 53c7fb94..225a4184 100644
--- a/debugging/debugging.tex
+++ b/debugging/debugging.tex
@@ -2302,7 +2302,7 @@ to creep in, including:
 
 The first and fourth sources of interference provide conflicting advice,
 which is one sign that we are living in the real world.
-The remainder of this section looks at ways of resolving this conflict.
+The following sections look at ways of resolving this conflict.
 
 \QuickQuiz{
 	But what about other sources of error, for example, due to
-- 
2.17.1

Re: [PATCH 1/5] debugging: Use \co{} for 'time' output examples

[Akira Yokosawa]

Hi SeongJae,

On Sun,  5 Feb 2023 10:21:24 -0800, SeongJae Park wrote:
> From: SeongJae Park <sj38.park@gmail.com>
> 
> A quick quiz answer in debugging.tex is wrapping 'time' example outputs
> with `` and ''.  Use \co{} instead.
> 
> Signed-off-by: SeongJae Park <sj38.park@gmail.com>
> ---
>  debugging/debugging.tex | 16 ++++++++--------
>  1 file changed, 8 insertions(+), 8 deletions(-)
> 
> diff --git a/debugging/debugging.tex b/debugging/debugging.tex
> index 4568f90a..3104bb95 100644
> --- a/debugging/debugging.tex
> +++ b/debugging/debugging.tex
> @@ -257,8 +257,8 @@ validation is just job for you.
>  		consumed in system mode by a CPU-bound program?
>  	\item	Do you have a test case in which all three times
>  		are zero?
> -	\item	Do you have a test case in which the ``user'' and ``sys''
> -		times sum to more than the ``real'' time?
> +	\item	Do you have a test case in which the \co{user} and \co{sys}
> +		times sum to more than the \co{real} time?
>  		(This would of course be completely legitimate in
>  		a multithreaded program.)
>  	\item	Do you have a set of tests cases in which one of the
> @@ -267,7 +267,7 @@ validation is just job for you.
>  		times uses more than ten seconds?
>  	\item	Do you have a set of test cases in which one of the
>  		times has non-zero minutes?
> -		(For example, ``15m36.342s''.)
> +		(For example, \co{15m36.342s}.)
>  	\item	Do you have a set of test cases in which one of the
>  		times has a seconds value of greater than 60?
>  	\item	Do you have a set of test cases in which one of the
> @@ -279,21 +279,21 @@ validation is just job for you.
>  		times has a positive minutes value but a negative
>  		seconds value?
>  	\item	Do you have a set of test cases in which one of the
> -		times omits the ``m'' or the ``s''?
> +		times omits the \co{m} or the \co{s}?
>  	\item	Do you have a set of test cases in which one of the
>  		times is non-numeric?
> -		(For example, ``Go Fish''.)
> +		(For example, \co{Go Fish}.)

My preference is to enclose \co{Go Fish} by quotation marks.
That is easier for me to see it as a string.
There is a convenient macro \qco{} for this purpose. You can say:

  +             (For example, \qco{Go Fish}.)

>  	\item	Do you have a set of test cases in which one of the
>  		lines is omitted?
> -		(For example, where there is a ``real'' value and
> -		a ``sys'' value, but no ``user'' value.)
> +		(For example, where there is a \co{real} value and
> +		a \co{sys} value, but no \co{user} value.)
>  	\item	Do you have a set of test cases where one of the
>  		lines is duplicated?
>  		Or duplicated, but with a different time value for
>  		the duplicate?
>  	\item	Do you have a set of test cases where a given line
>  		has more than one time value?
> -		(For example, ``real 0m0.132s 0m0.008s''.)
> +		(For example, \co{real 0m0.132s 0m0.008s}.)

Ditto.

With them taken care of,

Reviewed-by: Akira Yokosawa <akiyks@gmail.com>

        Thanks, Akira

>  	\item	Do you have a set of test cases containing random
>  		characters?
>  	\item	In all test cases involving invalid input, did you

Re: [PATCH 2/5] debugging: Use \co{} for 'git' and 'Fixes:'

[Akira Yokosawa]

On Sun,  5 Feb 2023 10:21:25 -0800, SeongJae Park wrote:
> From: SeongJae Park <sj38.park@gmail.com>
> 
> In 'debugging/', 'git' is a command and 'Fixes:' is a string in command
> output, which usually enclosed via '\co{}', but those are enclosed with
> '\emph{}'.  Use '\co{}' instead for being more consistent.
> 
> Signed-off-by: SeongJae Park <sj38.park@gmail.com>
> ---
>  debugging/debugging.tex | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/debugging/debugging.tex b/debugging/debugging.tex
> index 3104bb95..3ce74469 100644
> --- a/debugging/debugging.tex
> +++ b/debugging/debugging.tex
> @@ -862,8 +862,8 @@ by the author's invalid assumptions, and who might also test the code.
>  	hackers of harboring???
>  }\QuickQuizAnswer{
>  	Those wishing a complete answer to this question are encouraged
> -	to search the Linux kernel \emph{git} repository for commits

I often see "Linux kernel git repository" everywhere, and in this case,
I suppose emphasizing "git" was the author's intention. Paul might have
a different opinion, though.

> -	containing the string ``Fixes:''.
> +	to search the Linux kernel \co{git} repository for commits
> +	containing the string \co{Fixes:}.

As this is mentioned as a "string", \qco{} might be a better choice.

        Thanks, Akra

>  	There were many thousands of them just in the year 2020, including
>  	fixes for the following invalid assumptions:
>  

Re: [PATCH 3/5] debugging: Use \co{} for rcutorture

[Akira Yokosawa]

On Sun,  5 Feb 2023 10:21:26 -0800, SeongJae Park wrote:
> From: SeongJae Park <sj38.park@gmail.com>
> 
> Some sentences in debugging.tex encloses 'rcutorture' with while some
> others don't.  Use \co{} consistently.

Ya, that's also the convention in defer/rcurelated.tex.

> 
> Signed-off-by: SeongJae Park <sj38.park@gmail.com

Reviewed-by: Akira Yokosawa <akiyks@gmail.com>

> ---
>  debugging/debugging.tex | 14 +++++++-------
>  1 file changed, 7 insertions(+), 7 deletions(-)
> 
> diff --git a/debugging/debugging.tex b/debugging/debugging.tex
> index 3ce74469..1903c5db 100644
> --- a/debugging/debugging.tex
> +++ b/debugging/debugging.tex
> @@ -697,7 +697,7 @@ what it knows is almost always way more than your head can hold.
>  For this reason, high-quality test suites normally come with sophisticated
>  scripts to analyze the voluminous output.
>  But beware---scripts will only notice what you tell them to.
> -My rcutorture scripts are a case in point:
> +My \co{rcutorture} scripts are a case in point:
>  Early versions of those scripts were quite satisfied with a test run
>  in which RCU \IXpl{grace period} stalled indefinitely.
>  This of course resulted in the scripts being modified to detect RCU
> @@ -1252,14 +1252,14 @@ of time you spent testing.
>  Functional tests tend to be discrete.
>  
>  On the other hand, if my patch involved RCU, I would probably run
> -rcutorture, which is a kernel module that, strangely enough, tests RCU\@.
> +\co{rcutorture}, which is a kernel module that, strangely enough, tests RCU\@.
>  Unlike booting the kernel, where the appearance of a login prompt
> -signals the successful end of a discrete test, rcutorture will happily
> +signals the successful end of a discrete test, \co{rcutorture} will happily
>  continue torturing RCU until either the kernel crashes or until you
>  tell it to stop.
> -The duration of the rcutorture test is usually of more
> +The duration of the \co{rcutorture} test is usually of more
>  interest than the number of times you started and stopped it.
> -Therefore, rcutorture is an example of a continuous test, a category
> +Therefore, \co{rcutorture} is an example of a continuous test, a category
>  that includes many stress tests.
>  
>  Statistics for discrete tests are simpler and more familiar than those
> @@ -1845,7 +1845,7 @@ If the program is structured such that it is difficult or impossible
>  to apply much stress to a subsystem that is under suspicion,
>  a useful anti-heisenbug is a stress test that tests that subsystem in
>  isolation.
> -The Linux kernel's rcutorture module takes exactly this approach with RCU\@:
> +The Linux kernel's \co{rcutorture} module takes exactly this approach with RCU\@:
>  Applying more stress to RCU than is feasible in a production environment
>  increases the probability that RCU bugs will be found during testing
>  rather than in production.\footnote{
> @@ -1918,7 +1918,7 @@ delay might be counted as a near miss.\footnote{
>  \end{figure}
>  
>  For example, a low-probability bug in RCU priority boosting occurred
> -roughly once every hundred hours of focused rcutorture testing.
> +roughly once every hundred hours of focused \co{rcutorture} testing.
>  Because it would take almost 500 hours of failure-free testing to be
>  99\,\% certain that the bug's probability had been significantly reduced,
>  the \co{git bisect} process

Re: [PATCH 4/5] debugging: Remove unnecessary space in a sentence

[Akira Yokosawa]

On Date:   Sun,  5 Feb 2023 10:21:27 -0800, SeongJae Park wrote:
> From: SeongJae Park <sj38.park@gmail.com>
> 
> Two spaces are usually used between sentences, but a sentence in
> debugging is using two spaces inside a sentence.  Make it uses only one
> space for consistency.

FWIW, in perfbook's .tex source files, sentence ending periods must
be at the end of lines. Violation to this rule is flagged by
"make punctcheck" now a days.

        Thanks, Akira

> 
> Signed-off-by: SeongJae Park <sj38.park@gmail.com>
> ---
>  debugging/debugging.tex | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/debugging/debugging.tex b/debugging/debugging.tex
> index 1903c5db..53c7fb94 100644
> --- a/debugging/debugging.tex
> +++ b/debugging/debugging.tex
> @@ -2153,7 +2153,7 @@ serve four major purposes:
>  	against your competitors' offerings.
>  \end{enumerate}
>  
> -Of course,  the only completely fair framework is the intended
> +Of course, the only completely fair framework is the intended
>  application itself.
>  So why would anyone who cared about fairness in benchmarking
>  bother creating imperfect benchmarks rather than simply

Re: [PATCH 5/5] debugging/debugging: s/remainder of a section/following sections/

[Akira Yokosawa]

On Sun,  5 Feb 2023 10:21:28 -0800, SeongJae Park wrote:
> From: SeongJae Park <sj38.park@gmail.com>
> 
> A sectence in 'Microbenchmarking' section is mentioning the remainder of
> the section will look at ways for dealing with conflicts in measurement
> error advices, but those are not dealt in the remainder of the section
> but its following sections.  Fix the sentence.
> 
> Signed-off-by: SeongJae Park <sj38.park@gmail.com>
> ---
>  debugging/debugging.tex | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/debugging/debugging.tex b/debugging/debugging.tex
> index 53c7fb94..225a4184 100644
> --- a/debugging/debugging.tex
> +++ b/debugging/debugging.tex
> @@ -2302,7 +2302,7 @@ to creep in, including:
>  
>  The first and fourth sources of interference provide conflicting advice,
>  which is one sign that we are living in the real world.
> -The remainder of this section looks at ways of resolving this conflict.
> +The following sections look at ways of resolving this conflict.

If you interpret "The remainder of this section" as "The remainder of
Section 11.6.4 'Hunting Heisenbugs'", there is nothing to fix.

We call all of section, subsection, and subsubsection as "Section",
which might be confusing sometimes, but I don't have any idea what
should be done here.

        Thanks, Akira

>  
>  \QuickQuiz{
>  	But what about other sources of error, for example, due to

Re: [PATCH 5/5] debugging/debugging: s/remainder of a section/following sections/

[Paul E. McKenney]

On Mon, Feb 06, 2023 at 12:01:57PM +0900, Akira Yokosawa wrote:
> On Sun,  5 Feb 2023 10:21:28 -0800, SeongJae Park wrote:
> > From: SeongJae Park <sj38.park@gmail.com>
> > 
> > A sectence in 'Microbenchmarking' section is mentioning the remainder of
> > the section will look at ways for dealing with conflicts in measurement
> > error advices, but those are not dealt in the remainder of the section
> > but its following sections.  Fix the sentence.
> > 
> > Signed-off-by: SeongJae Park <sj38.park@gmail.com>
> > ---
> >  debugging/debugging.tex | 2 +-
> >  1 file changed, 1 insertion(+), 1 deletion(-)
> > 
> > diff --git a/debugging/debugging.tex b/debugging/debugging.tex
> > index 53c7fb94..225a4184 100644
> > --- a/debugging/debugging.tex
> > +++ b/debugging/debugging.tex
> > @@ -2302,7 +2302,7 @@ to creep in, including:
> >  
> >  The first and fourth sources of interference provide conflicting advice,
> >  which is one sign that we are living in the real world.
> > -The remainder of this section looks at ways of resolving this conflict.
> > +The following sections look at ways of resolving this conflict.
> 
> If you interpret "The remainder of this section" as "The remainder of
> Section 11.6.4 'Hunting Heisenbugs'", there is nothing to fix.
> 
> We call all of section, subsection, and subsubsection as "Section",
> which might be confusing sometimes, but I don't have any idea what
> should be done here.

One approach would be to say something like this:

	The remainder of this section (Section 11.6.4) looks at ways of
	resolving this conflict.

I am not sure whether or not this is a good idea, but perhaps either
way it will inspire better ideas.

							Thanx, Paul

>         Thanks, Akira
> 
> >  
> >  \QuickQuiz{
> >  	But what about other sources of error, for example, due to

Re: [PATCH 3/5] debugging: Use \co{} for rcutorture

[Paul E. McKenney]

On Mon, Feb 06, 2023 at 11:48:50AM +0900, Akira Yokosawa wrote:
> On Sun,  5 Feb 2023 10:21:26 -0800, SeongJae Park wrote:
> > From: SeongJae Park <sj38.park@gmail.com>
> > 
> > Some sentences in debugging.tex encloses 'rcutorture' with while some
> > others don't.  Use \co{} consistently.
> 
> Ya, that's also the convention in defer/rcurelated.tex.
> 
> > 
> > Signed-off-by: SeongJae Park <sj38.park@gmail.com
> 
> Reviewed-by: Akira Yokosawa <akiyks@gmail.com>

Good eyes!  Queued and pushed, thank you both!

							Thanx, Paul

> > ---
> >  debugging/debugging.tex | 14 +++++++-------
> >  1 file changed, 7 insertions(+), 7 deletions(-)
> > 
> > diff --git a/debugging/debugging.tex b/debugging/debugging.tex
> > index 3ce74469..1903c5db 100644
> > --- a/debugging/debugging.tex
> > +++ b/debugging/debugging.tex
> > @@ -697,7 +697,7 @@ what it knows is almost always way more than your head can hold.
> >  For this reason, high-quality test suites normally come with sophisticated
> >  scripts to analyze the voluminous output.
> >  But beware---scripts will only notice what you tell them to.
> > -My rcutorture scripts are a case in point:
> > +My \co{rcutorture} scripts are a case in point:
> >  Early versions of those scripts were quite satisfied with a test run
> >  in which RCU \IXpl{grace period} stalled indefinitely.
> >  This of course resulted in the scripts being modified to detect RCU
> > @@ -1252,14 +1252,14 @@ of time you spent testing.
> >  Functional tests tend to be discrete.
> >  
> >  On the other hand, if my patch involved RCU, I would probably run
> > -rcutorture, which is a kernel module that, strangely enough, tests RCU\@.
> > +\co{rcutorture}, which is a kernel module that, strangely enough, tests RCU\@.
> >  Unlike booting the kernel, where the appearance of a login prompt
> > -signals the successful end of a discrete test, rcutorture will happily
> > +signals the successful end of a discrete test, \co{rcutorture} will happily
> >  continue torturing RCU until either the kernel crashes or until you
> >  tell it to stop.
> > -The duration of the rcutorture test is usually of more
> > +The duration of the \co{rcutorture} test is usually of more
> >  interest than the number of times you started and stopped it.
> > -Therefore, rcutorture is an example of a continuous test, a category
> > +Therefore, \co{rcutorture} is an example of a continuous test, a category
> >  that includes many stress tests.
> >  
> >  Statistics for discrete tests are simpler and more familiar than those
> > @@ -1845,7 +1845,7 @@ If the program is structured such that it is difficult or impossible
> >  to apply much stress to a subsystem that is under suspicion,
> >  a useful anti-heisenbug is a stress test that tests that subsystem in
> >  isolation.
> > -The Linux kernel's rcutorture module takes exactly this approach with RCU\@:
> > +The Linux kernel's \co{rcutorture} module takes exactly this approach with RCU\@:
> >  Applying more stress to RCU than is feasible in a production environment
> >  increases the probability that RCU bugs will be found during testing
> >  rather than in production.\footnote{
> > @@ -1918,7 +1918,7 @@ delay might be counted as a near miss.\footnote{
> >  \end{figure}
> >  
> >  For example, a low-probability bug in RCU priority boosting occurred
> > -roughly once every hundred hours of focused rcutorture testing.
> > +roughly once every hundred hours of focused \co{rcutorture} testing.
> >  Because it would take almost 500 hours of failure-free testing to be
> >  99\,\% certain that the bug's probability had been significantly reduced,
> >  the \co{git bisect} process

Re: [PATCH 1/5] debugging: Use \co{} for 'time' output examples

[SeongJae Park]

Hi Akira,


Sorry for late response.

On Mon, 6 Feb 2023 11:31:55 +0900 Akira Yokosawa <akiyks@gmail.com> wrote:

> Hi SeongJae,
> 
> On Sun,  5 Feb 2023 10:21:24 -0800, SeongJae Park wrote:
> > From: SeongJae Park <sj38.park@gmail.com>
> > 
> > A quick quiz answer in debugging.tex is wrapping 'time' example outputs
> > with `` and ''.  Use \co{} instead.
> > 
> > Signed-off-by: SeongJae Park <sj38.park@gmail.com>
> > ---
> >  debugging/debugging.tex | 16 ++++++++--------
> >  1 file changed, 8 insertions(+), 8 deletions(-)
> > 
> > diff --git a/debugging/debugging.tex b/debugging/debugging.tex
> > index 4568f90a..3104bb95 100644
> > --- a/debugging/debugging.tex
> > +++ b/debugging/debugging.tex
> > @@ -257,8 +257,8 @@ validation is just job for you.
> >  		consumed in system mode by a CPU-bound program?
> >  	\item	Do you have a test case in which all three times
> >  		are zero?
> > -	\item	Do you have a test case in which the ``user'' and ``sys''
> > -		times sum to more than the ``real'' time?
> > +	\item	Do you have a test case in which the \co{user} and \co{sys}
> > +		times sum to more than the \co{real} time?
> >  		(This would of course be completely legitimate in
> >  		a multithreaded program.)
> >  	\item	Do you have a set of tests cases in which one of the
> > @@ -267,7 +267,7 @@ validation is just job for you.
> >  		times uses more than ten seconds?
> >  	\item	Do you have a set of test cases in which one of the
> >  		times has non-zero minutes?
> > -		(For example, ``15m36.342s''.)
> > +		(For example, \co{15m36.342s}.)
> >  	\item	Do you have a set of test cases in which one of the
> >  		times has a seconds value of greater than 60?
> >  	\item	Do you have a set of test cases in which one of the
> > @@ -279,21 +279,21 @@ validation is just job for you.
> >  		times has a positive minutes value but a negative
> >  		seconds value?
> >  	\item	Do you have a set of test cases in which one of the
> > -		times omits the ``m'' or the ``s''?
> > +		times omits the \co{m} or the \co{s}?
> >  	\item	Do you have a set of test cases in which one of the
> >  		times is non-numeric?
> > -		(For example, ``Go Fish''.)
> > +		(For example, \co{Go Fish}.)
> 
> My preference is to enclose \co{Go Fish} by quotation marks.
> That is easier for me to see it as a string.
> There is a convenient macro \qco{} for this purpose. You can say:
> 
>   +             (For example, \qco{Go Fish}.)
> 
> >  	\item	Do you have a set of test cases in which one of the
> >  		lines is omitted?
> > -		(For example, where there is a ``real'' value and
> > -		a ``sys'' value, but no ``user'' value.)
> > +		(For example, where there is a \co{real} value and
> > +		a \co{sys} value, but no \co{user} value.)
> >  	\item	Do you have a set of test cases where one of the
> >  		lines is duplicated?
> >  		Or duplicated, but with a different time value for
> >  		the duplicate?
> >  	\item	Do you have a set of test cases where a given line
> >  		has more than one time value?
> > -		(For example, ``real 0m0.132s 0m0.008s''.)
> > +		(For example, \co{real 0m0.132s 0m0.008s}.)
> 
> Ditto.
> 
> With them taken care of,
> 
> Reviewed-by: Akira Yokosawa <akiyks@gmail.com>

Thank you for nice suggestions.  I will revise as you suggested.


Thanks,
SJ

> 
>         Thanks, Akira
> 
> >  	\item	Do you have a set of test cases containing random
> >  		characters?
> >  	\item	In all test cases involving invalid input, did you

Re: [PATCH 2/5] debugging: Use \co{} for 'git' and 'Fixes:'

[SeongJae Park]

Hi Akira,

On Mon, 6 Feb 2023 11:38:58 +0900 Akira Yokosawa <akiyks@gmail.com> wrote:

> On Sun,  5 Feb 2023 10:21:25 -0800, SeongJae Park wrote:
> > From: SeongJae Park <sj38.park@gmail.com>
> > 
> > In 'debugging/', 'git' is a command and 'Fixes:' is a string in command
> > output, which usually enclosed via '\co{}', but those are enclosed with
> > '\emph{}'.  Use '\co{}' instead for being more consistent.
> > 
> > Signed-off-by: SeongJae Park <sj38.park@gmail.com>
> > ---
> >  debugging/debugging.tex | 4 ++--
> >  1 file changed, 2 insertions(+), 2 deletions(-)
> > 
> > diff --git a/debugging/debugging.tex b/debugging/debugging.tex
> > index 3104bb95..3ce74469 100644
> > --- a/debugging/debugging.tex
> > +++ b/debugging/debugging.tex
> > @@ -862,8 +862,8 @@ by the author's invalid assumptions, and who might also test the code.
> >  	hackers of harboring???
> >  }\QuickQuizAnswer{
> >  	Those wishing a complete answer to this question are encouraged
> > -	to search the Linux kernel \emph{git} repository for commits
> 
> I often see "Linux kernel git repository" everywhere, and in this case,
> I suppose emphasizing "git" was the author's intention. Paul might have
> a different opinion, though.
> 
> > -	containing the string ``Fixes:''.
> > +	to search the Linux kernel \co{git} repository for commits
> > +	containing the string \co{Fixes:}.
> 
> As this is mentioned as a "string", \qco{} might be a better choice.

Thanks, I will revise so in the next spin.

> 
>         Thanks, Akra
> 
> >  	There were many thousands of them just in the year 2020, including
> >  	fixes for the following invalid assumptions:
> >  

Re: [PATCH 4/5] debugging: Remove unnecessary space in a sentence

[SeongJae Park]

Hi Akira,

On Mon, 6 Feb 2023 11:53:54 +0900 Akira Yokosawa <akiyks@gmail.com> wrote:

> On Date:   Sun,  5 Feb 2023 10:21:27 -0800, SeongJae Park wrote:
> > From: SeongJae Park <sj38.park@gmail.com>
> > 
> > Two spaces are usually used between sentences, but a sentence in
> > debugging is using two spaces inside a sentence.  Make it uses only one
> > space for consistency.
> 
> FWIW, in perfbook's .tex source files, sentence ending periods must
> be at the end of lines. Violation to this rule is flagged by
> "make punctcheck" now a days.

Thank you for letting me know that.  So, this is just a note rather than a
change request to this patch, right?  I will make no change for this patch on
the next spin if so.


Thanks,
SJ

> 
>         Thanks, Akira
> 
> > 
> > Signed-off-by: SeongJae Park <sj38.park@gmail.com>
> > ---
> >  debugging/debugging.tex | 2 +-
> >  1 file changed, 1 insertion(+), 1 deletion(-)
> > 
> > diff --git a/debugging/debugging.tex b/debugging/debugging.tex
> > index 1903c5db..53c7fb94 100644
> > --- a/debugging/debugging.tex
> > +++ b/debugging/debugging.tex
> > @@ -2153,7 +2153,7 @@ serve four major purposes:
> >  	against your competitors' offerings.
> >  \end{enumerate}
> >  
> > -Of course,  the only completely fair framework is the intended
> > +Of course, the only completely fair framework is the intended
> >  application itself.
> >  So why would anyone who cared about fairness in benchmarking
> >  bother creating imperfect benchmarks rather than simply

Re: [PATCH 5/5] debugging/debugging: s/remainder of a section/following sections/

[SeongJae Park]

Hi Paul,

On Mon, 6 Feb 2023 09:33:44 -0800 "Paul E. McKenney" <paulmck@kernel.org> wrote:

> On Mon, Feb 06, 2023 at 12:01:57PM +0900, Akira Yokosawa wrote:
> > On Sun,  5 Feb 2023 10:21:28 -0800, SeongJae Park wrote:
> > > From: SeongJae Park <sj38.park@gmail.com>
> > > 
> > > A sectence in 'Microbenchmarking' section is mentioning the remainder of
> > > the section will look at ways for dealing with conflicts in measurement
> > > error advices, but those are not dealt in the remainder of the section
> > > but its following sections.  Fix the sentence.
> > > 
> > > Signed-off-by: SeongJae Park <sj38.park@gmail.com>
> > > ---
> > >  debugging/debugging.tex | 2 +-
> > >  1 file changed, 1 insertion(+), 1 deletion(-)
> > > 
> > > diff --git a/debugging/debugging.tex b/debugging/debugging.tex
> > > index 53c7fb94..225a4184 100644
> > > --- a/debugging/debugging.tex
> > > +++ b/debugging/debugging.tex
> > > @@ -2302,7 +2302,7 @@ to creep in, including:
> > >  
> > >  The first and fourth sources of interference provide conflicting advice,
> > >  which is one sign that we are living in the real world.
> > > -The remainder of this section looks at ways of resolving this conflict.
> > > +The following sections look at ways of resolving this conflict.
> > 
> > If you interpret "The remainder of this section" as "The remainder of
> > Section 11.6.4 'Hunting Heisenbugs'", there is nothing to fix.
> > 
> > We call all of section, subsection, and subsubsection as "Section",
> > which might be confusing sometimes, but I don't have any idea what
> > should be done here.
> 
> One approach would be to say something like this:
> 
> 	The remainder of this section (Section 11.6.4) looks at ways of
> 	resolving this conflict.
> 
> I am not sure whether or not this is a good idea, but perhaps either
> way it will inspire better ideas.

Thank you for nice suggestion.  Will follow your idea in the next spin.


Thanks,
SJ

> 
> 							Thanx, Paul
> 
> >         Thanks, Akira
> > 
> > >  
> > >  \QuickQuiz{
> > >  	But what about other sources of error, for example, due to