Source Browser ?

1% language=us
2
3% author    : Hans Hagen
4% copyright : ConTeXt Development Team
5% license   : Creative Commons Attribution ShareAlike 4.0 International
6% reference : pragma-ade.nl | contextgarden.net | texlive (related) distributions
7% origin    : the ConTeXt distribution
8%
9% comment   : Because this manual is distributed with TeX distributions it comes with a rather
10%             liberal license. We try to adapt these documents to upgrades in the (sub)systems
11%             that they describe. Using parts of the content otherwise can therefore conflict
12%             with existing functionality and we cannot be held responsible for that. Many of
13%             the manuals contain characteristic graphics and personal notes or examples that
14%             make no sense when used out-of-context.
15%
16% comment   : Some chapters might have been published in TugBoat, the NTG Maps, the ConTeXt
17%             Group journal or otherwise. Thanks to the editors for corrections. Also thanks
18%             to users for testing, feedback and corrections.
19
20\usemodule[mag-01,abr-02]
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 it's 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               %% first \bf test
335                         %% second \sl test
336    | test
337    | somethingverylong  %% third \it test
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. Let's start with the delimited variant:
350
351\startbuffer[setup]
352\defineprocessor
353  [escape_a]
354  [style=bold,
355   color=darkred,
356   left=(,
357   right=)]
358
359\defineprocessor
360  [escape_b]
361  [style=bold,
362   color=darkgreen,
363   left=(,
364   right=)]
365
366\setuptyping
367  [annotatedtyping]
368  [escape={escape_a->{[[,]]},escape_b->{[(,)]}},
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  [annotated_bf]
398  [style=\rm\bf,
399   color=darkred]
400
401\defineprocessor
402  [annotated_bs]
403  [style=\rm\bs,
404   color=darkyellow]
405
406\setuptyping
407  [annotatedtyping]
408  [escape={annotated_bf->{!bf,},annotated_bs->{!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