Source Browser ?

1\environment interaction-style
2
3\enabletrackers[comments.anchors]
4
5\startcomponent interaction-comments
6
7\setupcomment
8  [location=inmargin]
9
10\startchapter[title={Comments}]
11
12Many \PDF\ viewers support text annotations. These are small notes that can be
13popped up. In \CONTEXT\ we call them comments, because often that's what they are
14used for. Comments evolved from simple ones using a limited encoding into more
15advanced ones with representations. A comment looks like:
16
17\startbuffer
18\startcomment
19  Hello beautiful world!
20\stopcomment
21\stopbuffer
22
23\typebuffer
24
25\getbuffer
26
27When you open a document with comment you will likely see some symbol depicting
28it. But, it's one of those features that is viewer dependent so when it looks odd
29or unexpected, check in \ACROBAT\ first. The position and size can differ per
30viewer and when you zoom in the size can either stay the same or scale. The
31viewer can show the pop up text at the same location or someplace else. Although
32in principle there is control over this, my experience is that viewers (also
33Acrobat) keep changing this (not always for the best). Just assume the worst: it
34will never look good and although for a while we kept up with viewers, the
35inconsistency (and accumulated waste of time) led us to the current minimalistic
36approach.
37
38By default, in \CONTEXT\ comments are placed at the spot a bit raised. In this
39document we put them in the margin, by saying:
40
41\starttyping
42\setupcomment
43  [location=inmargin]
44\stoptyping
45
46Comments can have titles and properties but not all viewers support properties.
47Contrary to other environments, the first argument is not a category but a title.
48This because we are compatible with \MKII.
49
50\startbuffer
51\startcomment[french]
52  In France they use «angle bracket glyphs» in subsentences.
53\stopcomment
54
55\startcomment[accents][color=darkgreen]
56  You can used an àçéñţêð character too.
57\stopcomment
58\stopbuffer
59
60\typebuffer \getbuffer
61
62And normally empty lines are also supported (again this can differ per viewer):
63
64\startbuffer
65\startcomment[lines][color=darkblue]
66  How about an
67
68  empty line?
69\stopcomment
70\stopbuffer
71
72\typebuffer \getbuffer
73
74As we can see here, comments are sort of stacked. These examples also show that
75we can pass an optional title and set up some characteristics. An inline comment
76is defined with \type {\comment}:
77
78\startbuffer
79\comment {How I hate those notes spoiling the layout.} Maybe some day
80I can convince myself to add some features \comment {Think of comment classes
81that can be turned on and off and get their own colors.} related to version
82control.
83\stopbuffer
84
85\typebuffer
86
87\inlinebuffer\ Comments hide part of the text and thereby are to be used with
88care. Until now I never used them. Anyhow, from now on, one can happily use:
89
90You can use other symbols than the default, and a couple are predefined in
91the standard: {\tt \cldcontext {table.concat (lpdf.commentsymbols(), ", ")}}.
92
93\startbuffer
94\startcomment[symbol=Help]
95  Do we want this kind of rubish?
96\stopcomment
97\stopbuffer
98
99You can also use your own symbols:
100
101% \definesymbol [comment-normal][{\externalfigure[cow.pdf]}]
102% \definesymbol [comment-down]  [{\externalfigure[cow.pdf]}]
103%
104% \unexpanded\def\CowSymbol#1#2%
105%   {\scale
106%     [height=#1]
107%     {\startMPcode
108%        loadfigure "cow.mp" number 1 ;
109%        refill currentpicture withcolor #2 ;
110%      \stopMPcode}}
111%
112% \definesymbol [comment-normal] [\CowSymbol{4ex}{darkred}]
113% \definesymbol [comment-down]   [\CowSymbol{4ex}{darkgreen}]
114
115\startbuffer
116\startuniqueMPgraphic{cow}{height,s:color}
117    loadfigure "cow.mp" number 1 ;
118    refill currentpicture withcolor "\MPvar{color}"    ;
119    currentpicture := currentpicture ysized \MPvar{height} ;
120\stopuniqueMPgraphic
121
122\definesymbol
123  [comment-normal]
124  [\uniqueMPgraphic{cow}{height=4ex,color=darkred}]
125\definesymbol
126  [comment-down]
127  [\uniqueMPgraphic{cow}{height=4ex,color=darkgreen}]
128
129\stopbuffer
130
131\typebuffer \getbuffer
132
133\startbuffer
134\startcomment[hello][symbol={comment-normal,comment-down}]
135    oeps
136\stopcomment
137\stopbuffer
138
139\typebuffer \getbuffer
140
141Again the way this shows up depends on the viewer capabilities so there might be
142a fallback on the normal comment symbol. You can influence the size of the image
143(icon):
144
145\startbuffer
146\startcomment[hello]
147    [symbol={comment-normal,comment-down},width=\marginwidth]
148    oeps
149\stopcomment
150\stopbuffer
151
152\typebuffer \getbuffer
153
154There are some options that you can use for finetuning the comments.
155
156\showsetup{setupcomment}
157
158A new instance is defined with:
159
160\showsetup{definecomment}
161
162The default instance is predefined by
163
164\starttyping
165\definecomment[comment]
166\stoptyping
167
168You can define your own instances:
169
170\starttyping
171\definecomment[mycomment]
172\stoptyping
173
174The generated commands have a syntax like:
175
176\showsetup{startcomment:instance}
177
178and:
179
180\showsetup{comment:instance}
181
182Most fields explain themselves. With \type {state} you can disable this feature.
183Comments can be hidden in which there is no icon shown. The \type {nx} and \type
184{ny} fields determine the size of the popup.
185
186In case you wonder where the yellow backgrounds come from, here is the trick:
187
188\starttyping
189\enabletrackers[comments.anchors]
190\stoptyping
191
192\stopchapter
193
194\stopcomponent
195