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

On Wed, 27 Dec 2023 16:30:35 +0800, Zhouyi Zhou wrote:
> On Wed, Dec 27, 2023 at 3:50 PM Akira Yokosawa <[email protected]> wrote:
>>
>> On Wed, 27 Dec 2023 14:39:20 +0800, [email protected] wrote:
>>> From: Zhouyi Zhou <[email protected]>
>>>
>>> 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<[email protected]>
>>> ---
>>> 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 <[email protected]>
> 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
>>