[PATCH -perfbook v3] howto: make ref to git archive explicit

[PATCH -perfbook v3] howto: make ref to git archive explicit

[zhouzhouyi]

From: Zhouyi Zhou <zhouzhouyi@gmail.com>

Make "git archive" in answer to Quick Quiz 1.3 more explicit, so that reader can easily know where
"git archive" is.

Signed-off-by: Zhouyi Zhou<zhouzhouyi@gmail.com>
---
Hi Akira

This is version 3 of my patch "make ref to git archive explicit".

I fixed the problem of version 1 under your guidance.

The idea is originally proposed by our Chinese version editor Yunjing Li, but 
she was too modest to be a patch author.

I have forget to add "Signed-off-by" in version 2 of my patch, sorry for the inconvenience that I brought.

Thanks again

Zhouyi
--
 bib/syncrefs.bib | 8 ++++++++
 howto/howto.tex  | 2 +-
 2 files changed, 9 insertions(+), 1 deletion(-)

diff --git a/bib/syncrefs.bib b/bib/syncrefs.bib
index 6ee50e3b..63a7a8bc 100644
--- a/bib/syncrefs.bib
+++ b/bib/syncrefs.bib
@@ -2025,3 +2025,11 @@ Parallel Server on UNIX",
  Month="September",
  Note="Linux Plumbers Conference \url{https://lpc.events/event/16/contributions/1226/}",
 }
+
+@unpublished{PaulmckPerfbookGit,
+ author="Paul E. McKenney",
+ title="Is Parallel Programming Hard, And, If So, What Can You Do About It? Git Archive",
+ year="2023",
+ note={\url{git://git.kernel.org/pub/scm/linux/kernel/git/paulmck/perfbook.git}},
+ lastchecked="December 27, 2023",
+}
diff --git a/howto/howto.tex b/howto/howto.tex
index 55270cba..e7cd5f3c 100644
--- a/howto/howto.tex
+++ b/howto/howto.tex
@@ -226,7 +226,7 @@ Here are a few possible strategies:
 	only a blank sheet of paper.
 \item	If you find the Quick Quizzes distracting but impossible
 	to ignore, you can always clone the \LaTeX{} source for
-	this book from the git archive.
+	this book from the git archive~\cite{PaulmckPerfbookGit}.
 	You can then run the command \co{make nq}, which will
 	produce a \co{perfbook-nq.pdf}.
 	This PDF contains unobtrusive boxed tags where the Quick Quizzes
-- 
2.34.1

Re: [PATCH -perfbook v3] howto: make ref to git archive explicit

[Akira Yokosawa]

On Wed, 27 Dec 2023 14:39:20 +0800, zhouzhouyi@gmail.com wrote:
> From: Zhouyi Zhou <zhouzhouyi@gmail.com>
> 
> Make "git archive" in answer to Quick Quiz 1.3 more explicit, so that reader can easily know where
> "git archive" is.
> 
> Signed-off-by: Zhouyi Zhou<zhouzhouyi@gmail.com>
> ---
> Hi Akira
> 
> This is version 3 of my patch "make ref to git archive explicit".
> 
> I fixed the problem of version 1 under your guidance.
> 
> The idea is originally proposed by our Chinese version editor Yunjing Li, but 
> she was too modest to be a patch author.

In that case, a Reported-by: or Suggested-by tag should work, that is
if Yunjing Li is OK with her reachable email address exposed.

> 
> I have forget to add "Signed-off-by" in version 2 of my patch, sorry for the inconvenience that I brought.
> 
> Thanks again
> 
> Zhouyi
> --
>  bib/syncrefs.bib | 8 ++++++++
>  howto/howto.tex  | 2 +-
>  2 files changed, 9 insertions(+), 1 deletion(-)
> 
> diff --git a/bib/syncrefs.bib b/bib/syncrefs.bib
> index 6ee50e3b..63a7a8bc 100644
> --- a/bib/syncrefs.bib
> +++ b/bib/syncrefs.bib
> @@ -2025,3 +2025,11 @@ Parallel Server on UNIX",
>   Month="September",
>   Note="Linux Plumbers Conference \url{https://lpc.events/event/16/contributions/1226/}",
>  }
> +
> +@unpublished{PaulmckPerfbookGit,
> + author="Paul E. McKenney",
> + title="Is Parallel Programming Hard, And, If So, What Can You Do About It? Git Archive",
> + year="2023",
> + note={\url{git://git.kernel.org/pub/scm/linux/kernel/git/paulmck/perfbook.git}},
> + lastchecked="December 27, 2023",
> +}
> diff --git a/howto/howto.tex b/howto/howto.tex
> index 55270cba..e7cd5f3c 100644
> --- a/howto/howto.tex
> +++ b/howto/howto.tex
> @@ -226,7 +226,7 @@ Here are a few possible strategies:
>  	only a blank sheet of paper.
>  \item	If you find the Quick Quizzes distracting but impossible
>  	to ignore, you can always clone the \LaTeX{} source for
> -	this book from the git archive.
> +	this book from the git archive~\cite{PaulmckPerfbookGit}.

Alternatively, you can put a footnote instead. For example:

  See \cref{sec:howto:Whose Book Is This?} for instructions to do this.

should also suffice.

Generally speaking, citations are suitable when you want readers
to read the referenced document/code and the like.  In this case,
presenting just the URL of Git repo won't give readers sufficient
info.

QQz 1.3 belongs to Section 1.2, while the instructions are in
Section 1.5.  So putting a footnote as a (kind-of) "forward reference"
looks more reasonable to me.

Can you try this alternative in v4 ?

If you are OK with it, please use

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

    Thanks, Akira
    
>  	You can then run the command \co{make nq}, which will
>  	produce a \co{perfbook-nq.pdf}.
>  	This PDF contains unobtrusive boxed tags where the Quick Quizzes

Re: [PATCH -perfbook v3] howto: make ref to git archive explicit

[Zhouyi Zhou]

On Wed, Dec 27, 2023 at 3:50 PM Akira Yokosawa <akiyks@gmail.com> wrote:
>
> On Wed, 27 Dec 2023 14:39:20 +0800, zhouzhouyi@gmail.com wrote:
> > From: Zhouyi Zhou <zhouzhouyi@gmail.com>
> >
> > Make "git archive" in answer to Quick Quiz 1.3 more explicit, so that reader can easily know where
> > "git archive" is.
> >
> > Signed-off-by: Zhouyi Zhou<zhouzhouyi@gmail.com>
> > ---
> > Hi Akira
> >
> > This is version 3 of my patch "make ref to git archive explicit".
> >
> > I fixed the problem of version 1 under your guidance.
> >
> > The idea is originally proposed by our Chinese version editor Yunjing Li, but
> > she was too modest to be a patch author.
>
> In that case, a Reported-by: or Suggested-by tag should work, that is
> if Yunjing Li is OK with her reachable email address exposed.
Ok, I am try to ask her for her email address.
>
> >
> > I have forget to add "Signed-off-by" in version 2 of my patch, sorry for the inconvenience that I brought.
> >
> > Thanks again
> >
> > Zhouyi
> > --
> >  bib/syncrefs.bib | 8 ++++++++
> >  howto/howto.tex  | 2 +-
> >  2 files changed, 9 insertions(+), 1 deletion(-)
> >
> > diff --git a/bib/syncrefs.bib b/bib/syncrefs.bib
> > index 6ee50e3b..63a7a8bc 100644
> > --- a/bib/syncrefs.bib
> > +++ b/bib/syncrefs.bib
> > @@ -2025,3 +2025,11 @@ Parallel Server on UNIX",
> >   Month="September",
> >   Note="Linux Plumbers Conference \url{https://lpc.events/event/16/contributions/1226/}",
> >  }
> > +
> > +@unpublished{PaulmckPerfbookGit,
> > + author="Paul E. McKenney",
> > + title="Is Parallel Programming Hard, And, If So, What Can You Do About It? Git Archive",
> > + year="2023",
> > + note={\url{git://git.kernel.org/pub/scm/linux/kernel/git/paulmck/perfbook.git}},
> > + lastchecked="December 27, 2023",
> > +}
> > diff --git a/howto/howto.tex b/howto/howto.tex
> > index 55270cba..e7cd5f3c 100644
> > --- a/howto/howto.tex
> > +++ b/howto/howto.tex
> > @@ -226,7 +226,7 @@ Here are a few possible strategies:
> >       only a blank sheet of paper.
> >  \item        If you find the Quick Quizzes distracting but impossible
> >       to ignore, you can always clone the \LaTeX{} source for
> > -     this book from the git archive.
> > +     this book from the git archive~\cite{PaulmckPerfbookGit}.
>
> Alternatively, you can put a footnote instead. For example:
>
>   See \cref{sec:howto:Whose Book Is This?} for instructions to do this.
>
> should also suffice.
OK, I will do it.
>
> Generally speaking, citations are suitable when you want readers
> to read the referenced document/code and the like.  In this case,
> presenting just the URL of Git repo won't give readers sufficient
> info.
>
> QQz 1.3 belongs to Section 1.2, while the instructions are in
> Section 1.5.  So putting a footnote as a (kind-of) "forward reference"
> looks more reasonable to me.
But the 'git archive' belongs to the Answer to QQz 3.1 which is in
Appendix E, do we still need "forward reference".
If the answer is yes,  will  "See \cref{sec:howto:Whose Book Is This?}
(forward reference) for instructions to do this." be good ?
>
> Can you try this alternative in v4 ?
Ok, I am very glad to try this.
>
> If you are OK with it, please use
>
>   Suggested-by: Akira Yokosawa <akiyks@gmail.com>
OK,
>
>     Thanks, Akira
Thanks, Zhouyi
>
> >       You can then run the command \co{make nq}, which will
> >       produce a \co{perfbook-nq.pdf}.
> >       This PDF contains unobtrusive boxed tags where the Quick Quizzes
>

Re: [PATCH -perfbook v3] howto: make ref to git archive explicit

[Akira Yokosawa]

On Wed, 27 Dec 2023 16:30:35 +0800, Zhouyi Zhou wrote:
> On Wed, Dec 27, 2023 at 3:50 PM Akira Yokosawa <akiyks@gmail.com> wrote:
>>
>> On Wed, 27 Dec 2023 14:39:20 +0800, zhouzhouyi@gmail.com wrote:
>>> From: Zhouyi Zhou <zhouzhouyi@gmail.com>
>>>
>>> Make "git archive" in answer to Quick Quiz 1.3 more explicit, so that reader can easily know where
>>> "git archive" is.
>>>
>>> Signed-off-by: Zhouyi Zhou<zhouzhouyi@gmail.com>
>>> ---
>>> Hi Akira
>>>
>>> This is version 3 of my patch "make ref to git archive explicit".
>>>
>>> I fixed the problem of version 1 under your guidance.
>>>
>>> The idea is originally proposed by our Chinese version editor Yunjing Li, but
>>> she was too modest to be a patch author.
>>
>> In that case, a Reported-by: or Suggested-by tag should work, that is
>> if Yunjing Li is OK with her reachable email address exposed.
> Ok, I am try to ask her for her email address.
>>
>>>
>>> I have forget to add "Signed-off-by" in version 2 of my patch, sorry for the inconvenience that I brought.
>>>
>>> Thanks again
>>>
>>> Zhouyi
>>> --
>>>  bib/syncrefs.bib | 8 ++++++++
>>>  howto/howto.tex  | 2 +-
>>>  2 files changed, 9 insertions(+), 1 deletion(-)
>>>
>>> diff --git a/bib/syncrefs.bib b/bib/syncrefs.bib
>>> index 6ee50e3b..63a7a8bc 100644
>>> --- a/bib/syncrefs.bib
>>> +++ b/bib/syncrefs.bib
>>> @@ -2025,3 +2025,11 @@ Parallel Server on UNIX",
>>>   Month="September",
>>>   Note="Linux Plumbers Conference \url{https://lpc.events/event/16/contributions/1226/}",
>>>  }
>>> +
>>> +@unpublished{PaulmckPerfbookGit,
>>> + author="Paul E. McKenney",
>>> + title="Is Parallel Programming Hard, And, If So, What Can You Do About It? Git Archive",
>>> + year="2023",
>>> + note={\url{git://git.kernel.org/pub/scm/linux/kernel/git/paulmck/perfbook.git}},
>>> + lastchecked="December 27, 2023",
>>> +}
>>> diff --git a/howto/howto.tex b/howto/howto.tex
>>> index 55270cba..e7cd5f3c 100644
>>> --- a/howto/howto.tex
>>> +++ b/howto/howto.tex
>>> @@ -226,7 +226,7 @@ Here are a few possible strategies:
>>>       only a blank sheet of paper.
>>>  \item        If you find the Quick Quizzes distracting but impossible
>>>       to ignore, you can always clone the \LaTeX{} source for
>>> -     this book from the git archive.
>>> +     this book from the git archive~\cite{PaulmckPerfbookGit}.
>>
>> Alternatively, you can put a footnote instead. For example:
>>
>>   See \cref{sec:howto:Whose Book Is This?} for instructions to do this.
>>
>> should also suffice.
> OK, I will do it.
>>
>> Generally speaking, citations are suitable when you want readers
>> to read the referenced document/code and the like.  In this case,
>> presenting just the URL of Git repo won't give readers sufficient
>> info.
>>
>> QQz 1.3 belongs to Section 1.2, while the instructions are in
>> Section 1.5.  So putting a footnote as a (kind-of) "forward reference"
>> looks more reasonable to me.
> But the 'git archive' belongs to the Answer to QQz 3.1 which is in

                                       you mean  QQz 1.3?
				       
> Appendix E, do we still need "forward reference".

That's why I used double quotes and (kind-of), meaning it is not
actually a forward reference.  Only for the first time readers
who read the answer to QQz 1.3 before reading Section 1.5, it works
as a forward reference  :-)

> If the answer is yes,  will  "See \cref{sec:howto:Whose Book Is This?}
> (forward reference) for instructions to do this." be good ?

I don't think you need to say (forward reference) in the footnote.
Just saying:

    See \cref{sec:howto:Whose Book Is This?} for instructions to do this.

should be good enough, I guess.

    Thanks, Akira

>>
>> Can you try this alternative in v4 ?
> Ok, I am very glad to try this.
>>
>> If you are OK with it, please use
>>
>>   Suggested-by: Akira Yokosawa <akiyks@gmail.com>
> OK,
>>
>>     Thanks, Akira
> Thanks, Zhouyi
>>
>>>       You can then run the command \co{make nq}, which will
>>>       produce a \co{perfbook-nq.pdf}.
>>>       This PDF contains unobtrusive boxed tags where the Quick Quizzes
>>