1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20\usemodule[mag01,abr02]
21
22\startbuffer[abstract]
23 A not so widely known feature of the verbatim handler in \CONTEXT\ is the
24 ability to add comments in another style and \MKIV\ even offers a bit more.
25 Here some examples are shown.
26\stopbuffer
27
28\startdocument
29 [title={Annotated Verbatim},
30 author=Hans Hagen,
31 affiliation=PRAGMA ADE,
32 date=July 2011,
33 number=1102 \MKIV]
34
35\definetextbackground
36 [example]
37 [frame=on,
38 framecolor=darkblue,
39 location=paragraph,
40 leftoffset=1ex,
41 topoffset=1ex,
42 bottomoffset=1ex]
43
44Annotating verbatim content is done using a mechanism called escaping. For such
45special cases its often best to define a specific instance.
46
47\startbuffer[define]
48\definetyping
49 [annotatedtyping]
50 [escape=,
51 color=darkblue,
52 before=,
53 after=]
54\stopbuffer
55
56\startbuffer[example]
57\startannotatedtyping
58bla = test bgroup sl oeps egroup
59 bgroup bf some more egroup
60 another test
61 somethingverylong bgroup it oeps egroup
62\stopannotatedtyping
63\stopbuffer
64
65\typebuffer[define,example][option=TEX] \getbuffer[define]
66
67\starttextbackground[example]
68 \getbuffer[example]
69\stoptextbackground
70
71In this example the \type {} now serves as an escape character. Of course you
72can also use the normal backslash but then you need to use a command to specify
73it.
74
75\startbuffer[setup]
76\setuptyping
77 [annotatedtyping]
78 [escape=\letterbackslash]
79\stopbuffer
80
81\typebuffer[setup][option=TEX] \getbuffer[setup]
82
83Now we can say:
84
85\startbuffer[example]
86\startannotatedtyping
87bla = test \bgroup \sl oeps \egroup
88 \bgroup \bf some more \egroup
89 another test
90 somethingverylong \bgroup \it oeps \egroup
91\stopannotatedtyping
92\stopbuffer
93
94\typebuffer[example][option=TEX]
95
96and get:
97
98\starttextbackground[example]
99 \getbuffer[example]
100\stoptextbackground
101
102You can also define an end symbol:
103
104\startbuffer[setup]
105\setuptyping
106 [annotatedtyping]
107 [escape={,*},
108 color=darkblue]
109
110\definestartstop
111 [cmt]
112 [style=\rm\bf]
113\stopbuffer
114
115\typebuffer[setup][option=TEX] \getbuffer[setup]
116
117Here the \type {} starts the annotation and \type {*} ends it.
118
119\startbuffer[example]
120\startannotatedtyping
121bla = test \black \cmt{oeps} *
122 \black \cmt{some more} *
123 another test
124 somethingverylong \black \cmt{oeps} *
125\stopannotatedtyping
126\stopbuffer
127
128\typebuffer[example][option=TEX]
129
130Contrary to the first example, all text in the annotation is treated as \TEX\
131input:
132
133\starttextbackground[example]
134 \getbuffer[example]
135\stoptextbackground
136
137You can consider using more balanced tagging, as in:
138
139\startbuffer[setup]
140\setuptyping
141 [annotatedtyping]
142 [escape={<<,>>},
143 color=darkblue]
144\stopbuffer
145
146\typebuffer[example][option=TEX]
147
148Watch how we limit the annotation to part of the text:
149
150\startbuffer[example]
151\startannotatedtyping
152bla = test << \rm\bf first >> test
153 << \rm\bf second >> test
154 test
155 somethingverylong << \rm\bf fourth >> test
156\stopannotatedtyping
157\stopbuffer
158
159\typebuffer[example][option=TEX]
160
161The \type {test} a the end of the lines is verbatim again.
162
163\starttextbackground[example]
164 \getbuffer[example]
165\stoptextbackground
166
167If no end symbol is given, the end of the line is used instead:
168
169\startbuffer[setup]
170\setuptyping
171 [annotatedtyping]
172 [escape={,},
173 color=darkblue]
174\stopbuffer
175
176\typebuffer[setup][option=TEX] \getbuffer[setup]
177
178Watch out: here we use \type {{,}} and not just \type {} (which would trigger
179the escaped variant).
180
181\definestartstop[cmt][style=\rm\bf]
182
183\startbuffer[example]
184\startannotatedtyping
185bla = test \black \cmt{oeps}
186 \black \cmt{some more}
187 test
188 somethingverylong \black \cmt{oeps}
189\stopannotatedtyping
190\stopbuffer
191
192\typebuffer[example][option=TEX]
193
194The result is:
195
196\starttextbackground[example]
197 \getbuffer[example]
198\stoptextbackground
199
200This can also be done easier by abusing the \type {style} option of \type {cmt}:
201
202\startbuffer[setup]
203\definestartstop
204 [cmt]
205 [color=black,
206 style=\black \rm\bf\space]
207\stopbuffer
208
209\typebuffer[setup][option=TEX] \getbuffer[setup]
210
211When we give:
212
213\startbuffer[example]
214\startannotatedtyping
215bla = test \cmt{oeps}
216 \cmt{some more}
217 test
218 somethingverylong \cmt{oeps}
219\stopannotatedtyping
220\stopbuffer
221
222\typebuffer[example][option=TEX]
223
224We get:
225
226\starttextbackground[example]
227 \getbuffer[example]
228\stoptextbackground
229
230For cases like this, where we want to specify a somewhat detailed way to deal
231with a situation, we can use processors: \footnote {More mechanisms in \CONTEXT\
232\MKIV\ will use that feature.}
233
234\startbuffer[setup]
235\defineprocessor
236 [escape]
237 [style=bold,
238 color=black,
239 left=(,right=)]
240\stopbuffer
241
242\typebuffer[setup][option=TEX] \getbuffer[setup]
243
244The previous definition of the annotation now becomes:
245
246\startbuffer[setup]
247\setuptyping
248 [annotatedtyping]
249 [escape=escape>{,},
250 color=darkblue]
251\stopbuffer
252
253\typebuffer[setup][option=TEX] \getbuffer[setup]
254
255This time no commands are needed in the annotation:
256
257\startbuffer[example]
258\startannotatedtyping
259bla = test first
260 second
261 test
262 somethingverylong fourth
263\stopannotatedtyping
264\stopbuffer
265
266\typebuffer[example][option=TEX]
267
268The processor is applied to all text following the \type {}. Spaces before the
269text are stripped.
270
271\starttextbackground[example]
272 \getbuffer[example]
273\stoptextbackground
274
275As some characters are special to \TEX, sometimes you need to escape the boundary
276sequence:
277
278\startbuffer[setup]
279\defineprocessor
280 [myescape]
281 [style=\rm\tf,
282 color=black]
283
284\setuptyping
285 [annotatedtyping]
286 [escape=myescape>{\letterhash\letterhash,},
287 color=darkgreen]
288\stopbuffer
289
290\typebuffer[setup][option=TEX] \getbuffer[setup]
291
292All text between the double hashes and the end of the line is now treated as
293annotation:
294
295\startbuffer[example]
296\startannotatedtyping
297bla = test ## first \bf test
298 ## second \sl test
299 test
300 somethingverylong ## third \it test
301\stopannotatedtyping
302\stopbuffer
303
304\typebuffer[example][option=TEX]
305
306So we get:
307
308\starttextbackground[example]
309 \getbuffer[example]
310\stoptextbackground
311
312We can beautify \TEX\ commenting as follows:
313
314\startbuffer[setup]
315\defineprocessor
316 [comment]
317 [style=\rm,
318 color=black,
319 left={\tttf\letterpercent\space}]
320
321\setuptyping
322 [annotatedtyping]
323 [escape=comment>{\letterpercent\letterpercent,},
324 color=darkblue]
325\stopbuffer
326
327\typebuffer[setup][option=TEX] \getbuffer[setup]
328
329Here the double comments are turned into a single one and the text after it is
330typeset in a regular font:
331
332\startbuffer[example]
333\startannotatedtyping
334bla = test
335
336 test
337 somethingverylong
338\stopannotatedtyping
339\stopbuffer
340
341\typebuffer[example][option=TEX]
342
343This gives:
344
345\starttextbackground[example]
346 \getbuffer[example]
347\stoptextbackground
348
349It is possible to define several escapes. Lets start with the delimited variant:
350
351\startbuffer[setup]
352\defineprocessor
353 [escapea]
354 [style=bold,
355 color=darkred,
356 left=(,
357 right=)]
358
359\defineprocessor
360 [escapeb]
361 [style=bold,
362 color=darkgreen,
363 left=(,
364 right=)]
365
366\setuptyping
367 [annotatedtyping]
368 [escape={escapea>{[[,]]},escapeb>{[(,)]}},
369 color=darkblue]
370\stopbuffer
371
372\typebuffer[setup][option=TEX] \getbuffer[setup]
373
374We can now alternate comments:
375
376\startbuffer[example]
377\startannotatedtyping
378bla = test [[ first ]] test [( first )]
379 [[ second ]] test [( second )]
380 test
381 somethingverylong [[ fourth ]] test [( fourth )]
382\stopannotatedtyping
383\stopbuffer
384
385\typebuffer[example][option=TEX]
386
387When typeset this looks as follows:
388
389\starttextbackground[example]
390 \getbuffer[example]
391\stoptextbackground
392
393The line terminated variant can also have multiple escapes.
394
395\startbuffer[setup]
396\defineprocessor
397 [annotatedbf]
398 [style=\rm\bf,
399 color=darkred]
400
401\defineprocessor
402 [annotatedbs]
403 [style=\rm\bs,
404 color=darkyellow]
405
406\setuptyping
407 [annotatedtyping]
408 [escape={annotatedbf>{!bf,},annotatedbs>{!bs,}},
409 color=darkblue]
410\stopbuffer
411
412\typebuffer[setup][option=TEX] \getbuffer[setup]
413
414So this time we have two ways to enter regular \TEX\ mode:
415
416\startbuffer[example]
417\startannotatedtyping
418bla = test !bf one {\em again}
419 !bs two {\em again}
420 test
421 somethingverylong !bf three {\em again}
422\stopannotatedtyping
423\stopbuffer
424
425\typebuffer[example][option=TEX]
426
427These somewhat meaningful tags result in:
428
429\starttextbackground[example]
430 \getbuffer[example]
431\stoptextbackground
432
433\stopdocument
434 |