On 2018/07/24 00:09:37 +0900, Akira Yokosawa wrote:
> On 2018/07/22 15:49:06 -0700, Paul E. McKenney wrote:
>> On Mon, Jul 23, 2018 at 12:43:05AM +0900, Akira Yokosawa wrote:
>>> On 2018/07/21 09:51:03 -0700, Paul E. McKenney wrote:
>>>> On Sat, Jul 21, 2018 at 09:19:53AM +0900, Akira Yokosawa wrote:
>>>>> Hi Paul,
>>>>>
>>>>> So, an experimental branch to label particular lines in code
>>>>> snippets is ready for review.
>>>>> The branch is based on current master of yours.
>>>>>
>>>>> I've converted 4 code snippets in Section 4.2. and updated
>>>>> corresponding code samples (sans forkjoin.c because it is
>>>>> quite simplified in Listing 4.1).
>>>>>
>>>>> Does this approach look reasonable to you?
>>>>
>>>> This does look promising, thank you! Please give me some time to think
>>>> this over a bit. My normal approach would end up with very long labels
>>>> in the code, which might be OK. The argument against is that tying the
>>>> listing caption to the actual code might not be a great thing.
>>>
>>> One idea is to embed meta labels in code samples.
>>> When converting them to a proper Verbatim sources, short labels such
>>> as " //\lnlbl{foo}" can be converted to long ones such as
>>> "%lnlbl[ln:<chapter>:<basename of snippet file>:foo]" in the script
>>> to remove " //".
>>>
>>> To do this, we need to embed extra meta data as comments in sample
>>> code.
>>>
>>> For example, the source of waitall() function (in api-pthread.h) can be
>>> written as the following (in the form of \lnlbl{}):
>>>
>>> ----
>>> /*
>>> * Wait on all child processes.
>>> */
>>> static __inline__ void waitall(void)
>>> {
>>> // \begin{snippet}[chapter=toolsoftrade,name=waitall,commandchars=[\%\[\]]
>>> int pid;
>>> int status;
>>>
>>> for (;;) { //\lnlbl{loopa}
>>> pid = wait(&status); //\lnlb{wait}
>>> if (pid == -1) {
>>> if (errno == ECHILD) //\lnlb{ECHILD}
>>> break; //\lnlbl{break}
>>> perror("wait"); //\lnlbl{perror}
>>> exit(EXIT_FAILURE); //\lnlbl{exit}
>>> }
>>> poll(NULL, 0, 1);
>>> } //\lnlbl{loopb}
>>> }
>>> // \end{snippet}
>>> ...
>>> ----
>>>
>>> , and it can be extracted and converted into CodeSamples/api-pthread/waitall.tex
>>> in the following way (including substitution of escape charactors):
>>>
>>> \begin{Verbatim}[commandchars=[\%\[\]]
>>> int pid;
>>> int status;
>>>
>>> for (;;) {%lnlbl[ln:toolsoftrade:waitall:loopa]
>>> pid = wait(&status);%lnlbl[ln:toolsoftrade:waitall:wait]
>>> if (pid == -1) {
>>> if (errno == ECHILD)%lnlbl[ln:toolsoftrade:waitall:ECHILD]
>>> break;%lnlbl[ln:toolsoftrade:break]
>>> perror("wait");%lnlbl[ln:toolsoftrade:perror]
>>> exit(EXIT_FAILURE);%lnlbl[ln:toolsoftrade:exit]
>>> }
>>> poll(NULL, 0, 1);
>>> }%lnlbl[ln:toolsoftrade:loopb]
>>> }
>>> \end{Verbatim}
>>>
>>> This file can be read in toolsoftrade.tex in the following way:
>>>
>>> ---
>>> \begin{listing}[tbp]
>>> \input{CodeSamples/api-pthread/waitall}
>>> \caption{Using the \tco{wait()} Primitive}
>>> \label{lst:toolsoftrade:Using the wait() Primitive}
>>> \end{listing}
>>> ---
>>>
>>> The conversion script should not be so hard to implement.
>>> Update of build scripts should also be possible to automate these
>>> conversions.
>>>
>>> If you'd like to use the caption of the listing in the final labels,
>>> the caption should also be given in the meta \begin{snippet} command.
>>> But for lines in code snippets, using file names as labels sounds
>>> reasonable to me.
>>
>> I believe that your scheme is pretty close. My thought is directory,
>> file, function, label. You have all but file already. That allows
>> captions to change without changing the line label, which seems like a
>> good thing.
>
> In the end, "chapter=foo,name=bar,func=baz" can be expressed as
> "labelprefix=foo:bar:baz in the option to meta \begin{snippet} command.
I meant:
"labelprefix=foo:bar:baz"
Akira
> So you can put any string you like there.
>
> I'll do v2 of the trial branch along this scheme, hopefully
> including build script/Makefile updates. Maybe in a week or so.
>
> Thanks, Akira
>
>>
>> Seem reasonable?
>>
>> Thanx, Paul
>>
>>> Thoughts?
>>>
>>> Thanks, Akira
>>>
>>>>
>>>> Again, looks promising, thank you!
>>>>
>>>> Thanx, Paul
>>>>
>>>>> Thanks, Akira
>>>>>
>>>>> ---
>>>>> The following changes since commit e3191997557e0d33b862e267fb4d5971e879ca07:
>>>>>
>>>>> utilities: Provide scripts instead of broken symlinks (2018-07-18 11:40:57 -0700)
>>>>>
>>>>> are available in the git repository at:
>>>>>
>>>>> https://github.com/akiyks/perfbook trial-fancyvrb
>>>>>
>>>>> for you to fetch changes up to 2154a175e469e6238c89d4c494d204a9ddbaa20a:
>>>>>
>>>>> [EXP] Update hyphen2endash (2018-07-21 09:17:34 +0900)
>>>>>
>>>>> ----------------------------------------------------------------
>>>>> Akira Yokosawa (3):
>>>>> [EXP] toolsoftrade: Add labels in code samples as comments
>>>>> [EXP] toolsoftrade: Reference line in code snippets by label
>>>>> [EXP] Update hyphen2endash
>>>>>
>>>>> CodeSamples/api-pthreads/api-pthreads.h | 14 +-
>>>>> CodeSamples/toolsoftrade/forkjoinvar.c | 10 +-
>>>>> CodeSamples/toolsoftrade/pcreate.c | 5 +-
>>>>> perfbook.tex | 6 +
>>>>> toolsoftrade/toolsoftrade.tex | 221 +++++++++++++++++---------------
>>>>> utilities/hyphen2endash.sh | 3 +
>>>>> 6 files changed, 141 insertions(+), 118 deletions(-)
>>>>>
>>>>
>>>
>>
>
--
To unsubscribe from this list: send the line "unsubscribe perfbook" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
