Re: [NOT YET PULL] Trial of labeling lines in code snippets

["Paul E. McKenney" <paulmck@linux.vnet.ibm.com>]

On Tue, Jul 24, 2018 at 12:12:17AM +0900, Akira Yokosawa wrote:
> 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"

Sounds very good, thank you!!!

							Thanx, Paul

> 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(-)
> >>>>>
> >>>>
> >>>
> >>
> > 
>