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.
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
