aboutsummaryrefslogtreecommitdiffstats
path: root/doc/user/dia_labe
blob: c449367a63d1b3b202564e2035df9b37101f5a78 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
@Section
    @Tag { dia_labe }
    @Title { Labels }
@Begin
@PP
Diagrams often contain small @I labels adjacent to their nodes and links:
@CD @Diag
    nodelabelformat { @I @Body }
{
@Tab
    @Fmta { @Col A ! @Col ! @Col ! @Col B ! @Col ! @Col ! @Col C }
{
@Rowa
    B { B:: @Circle alabel { b } }
@Rowa
    A { A:: @Circle alabel { a } }
@Rowa
    C { C:: @Circle dlabel { c } }
}
//
@Arrow from { A } to { B } ylabel { 10 }
@Arrow from { A } to { C } ylabel { 15 }
@Arrow from { B } to { C } ylabel { 20 }
}
Each node may have up to four labels, called {@Code alabel}, {@Code blabel},
label.  @Index { label options in @Code "@Diag" }
alabel. @Index { @Code alabel option in @Code "@Diag" }
blabel. @Index { @Code blabel option in @Code "@Diag" }
clabel. @Index { @Code clabel option in @Code "@Diag" }
dlabel. @Index { @Code dlabel option in @Code "@Diag" }
{@Code clabel}, and {@Code dlabel}:
@ID {
@Code {
"@Ellipse"
"    alabel { a }"
"    blabel { b }"
"    clabel { c }"
"    dlabel { d }"
"{ Hello, world }"
}
||7ct
@VContract @Diag {
@Ellipse
    alabel { a }
    blabel { b }
    clabel { c }
    dlabel { d }
{ Hello, world }
}
}
Links also have labels, five in fact:
@ID {
@Code {
"@Link"
"    fromlabel { f }"
"    xlabel { x }"
"    ylabel { y }"
"    zlabel { z }"
"    tolabel { t }"
}
||7ct
@VContract @Diag {
3c @Wide 1c @High
//
@Link
    from { 0 0 }
    to { 1,1 }
    fromlabel { f }
    xlabel { x }
    ylabel { y }
    zlabel { z }
    tolabel { t }
}
}
The {@Code fromlabel} and {@Code tolabel} options are positioned directly
over the endpoints of the link, and {@Code fromlabel} is by default printed
at a funny angle, because these labels are the means of attaching
arrowheads to links:
@ID {
@Code {
"@Link"
"    tolabel { @SolidArrowHead }"
}
||7ct
@VContract @Diag {
3c @Wide 1c @High
//
@Link
    from { 0 0 }
    to { 1,1 }
    tolabel { @SolidArrowHead }
}
}
@Code "@SolidArrowHead" is a symbol available for use anywhere whose value
is an object in the shape of a small solid arrowhead.  The arrowhead
options of Section {@NumberOf dia_link} work by setting {@Code fromlabel}
and {@Code tolabel} in exactly this way.  Usually it is best to forget
about {@Code fromlabel} and {@Code tolabel}, and think of links as having
three labels:  {@Code xlabel} near the start, {@Code ylabel} in the
middle, and {@Code zlabel} near the end.
@PP
Adding a label will not change the size of the diagram or the position
of any node, link, or other label.  Although a label may be an arbitrary
object, it is treated as having zero size and will overstrike anything
that happens to be where it wants to go.
@PP
There are options for controlling the appearance and position of
labels.  These are described below mainly for {@Code alabel}, but there
are corresponding options for all nine labels.
@PP
The {@Code alabelfont} and {@Code alabelbreak} options determine the
font and paragraph breaking style of the label:
@ID {
@Code {
"@Ellipse"
"    alabel { a }"
"    alabelfont { -2p }"
"    alabelbreak { ragged nohyphen }"
"{ Hello, world }"
}
||7ct
@VContract @Diag {
@Ellipse
    alabel { a }
    alabelfont { -2p }
    alabelbreak { ragged nohyphen }
{ Hello, world }
}
}
This example shows the default values of these two options; @Code "-2p"
explains why the labels in earlier examples were printed in a smaller
font size.  There is also an {@Code alabelformat} option which allows
for more radical changes in appearance:
@ID {
@Code {
"@Ellipse"
"    alabel { a }"
"    alabelformat { @Box @I @Body }"
"{ Hello, world }"
}
||7ct
@Diag {
//0.5c
@Ellipse
    alabel { a }
    alabelformat { @Box @I @Body }
{ Hello, world }
}
}
The value attached to the ellipse will be the value of {@Code alabelformat},
with any @Code "@Body" symbol within it replaced by the value of the
{@Code alabel} option.  This example produces boxed italic labels.
@PP
Nodes also have {@Code nodelabelfont}, {@Code nodelabelbreak}, and
{@Code nodelabelformat} options which work in the same way but affect all
of the node labels, not just one:
@ID {
@Code {
"@Ellipse"
"    nodelabelformat"
"        { @Box @I @Body }"
"    alabel { a }"
"    blabel { b }"
"{ Hello, world }"
}
||7ct
@Diag {
//0.5c
@Ellipse
    nodelabelformat { @Box @I @Body }
    alabel { a }
    blabel { b }
{ Hello, world }
}
}
Links similarly have {@Code linklabelfont}, {@Code linklabelbreak}, and
{@Code linklabelformat} options which affect all the link labels
(except {@Code fromlabel} and {@Code tolabel}, since that would produce
results that people do not expect.)  The @Code "@Diag" symbol also has
these options, in the usual way, and they are extremely useful there:
@ID {
@Code {
"@Diag"
"    nodelabelfont { Slope -2p }"
"    linklabelformat { \"/\"@Body\"/\" }"
"    hsize { 1.8c }"
"{"
"    A:: @Ellipse alabel { a } { OK }"
"    @DP"
"    @DP"
"    B:: @Ellipse alabel { b } { FAULT }"
"    //"
"    @Arrow from { A } to { B } ylabel { sig }"
"}"
}
||7ct
@VContract @Diag
    nodelabelfont { Slope -2p }
    linklabelformat { "/"@Body"/" }
    hsize { 1.8c }
{
    A:: @Ellipse alabel { a } { OK }
    @DP
    @DP
    B:: @Ellipse alabel { b } { FAULT }
    //
    @Arrow  from { A } to { B } ylabel { sig }
}
}
These settings specify that every node label will be set in italics,
two points smaller than the surrounding text, and that every link label
will appear between two @Code "/" characters, also two points smaller
because the default value of @Code "linklabelfont" still applies.  Of
course, it remains open to any node or link to override these settings
by supplying its own label options.
@PP
The remaining five label options, {@Code alabelpos}, {@Code alabelangle},
{@Code alabelprox}, {@Code alabelmargin}, {@Code alabelctr}, and
{@Code alabeladjust},
affect the position of the label.  Don't be daunted by the number of
options.  As previous examples have shown, they all have sensible
default values and thus need to be set only rarely.
@PP
Each label inhabits its own characteristic region of the node or
link:  {@Code alabel} in the north-east corner of the node,
{@Code ylabel} halfway along the link, and so on.  This general
location of the label is defined by the {@Code alabelpos} option.  Here
are the default values for all nine labels:
@IL
@LI {
@Code {
"@Node"
"    alabelpos { NE }"
"    blabelpos { NW }"
"    clabelpos { SW }"
"    dlabelpos { SE }"
}
||7ct
@VContract @Diag {
//0.5f
@ShowTags @Ellipse { 3c @Wide 2c @High }
}
}
@LI {
@Code {
"@Link"
"    fromlabelpos { FROM }"
"    xlabelpos { LFROM }"
"    ylabelpos { LMID }"
"    zlabelpos { LTO }"
"    tolabelpos { TO }"
}
||7ct
@VContract @Diag {
//1.0f
2c @Wide 2.2c @High
//
@ShowTags @Link
    from { 0,0.7 }
    to { 1,0 }
    # tolabel { @SolidArrowHead }
}
}
@EL
Thus, by changing @Code clabelpos to @Code S you can move the position
of the @Code clabel label to beneath the node.  You can do this for every
node by setting this option in the @Code "@Diag" symbol, as was done for
the formatting options above.
@PP
In a similar vein, there is an @Code { xindent } option which controls how
far from the start of the link the @Code "LFROM" tag, and hence the
{@Code xlabel}, will appear.  A similar option, @Code { zindent }, determines
how far from the end of the link the @Code "LTO" tag and hence the
{@Code zlabel} will appear:
@ID {
@Code {
"@Link"
"    xindent { 1f }"
"    zindent { 2f }"
}
||7ct
@VContract @Diag {
//1f
2c @Wide 1.2c @High
//
@ShowTags @Link
    xindent { 1f }
    zindent { 2f }
    from { 0,0.7 }
    to { 1,0 }
}
}
Both options have default value {@Code 0.8f}.
@PP
The @Code alabelangle option determines the angle at which the label is
printed:
@ID @Tab
    @Fmta { @Col @Code A ! @Col B }
{
@Rowa
    A { "alabelangle { horizontal }" }
    B { Horizontal (the default) }
@Rowa
    A { "alabelangle { aligned }" }
    B { Aligned with the node outline or link path }
@Rowa
    A { "alabelangle { perpendicular }" }
    B { Perpendicular to the outline or link path }
}
The @Code "alabelprox" option determines where in the proximity of
@Code alabelpos the label is printed:
@ID @Tab
    @Fmta { @Col @Code A ! @Col B }
{
@Rowa
    A { "alabelprox { above }" }
    B { Above the node outline or link path (the default for link labels) }
@Rowa
    A { "alabelprox { below }" }
    B { Below the node outline or link path }
@Rowa
    A { "alabelprox { left }" }
    B { To the left of the node outline or link path }
@Rowa
    A { "alabelprox { right }" }
    B { To the right of the node outline or link path }
@Rowa
    A { "alabelprox { inside }" }
    B { Inside the node outline or on the left of the link path
going from @Code from to @Code to }
@Rowa
    A { "alabelprox { outside }" }
    B { Outside the node outline or on the right of the link path
going from @Code from to @Code to (the default for node labels) }
}
The {@Code alabelmargin} option adds a margin around all four sides of
the label, thereby moving it away from {@Code alabelpos} irrespective of
which direction it happens to lie in:
@ID {
@Code {
"@Ellipse"
"    alabel { a }"
"    alabelmargin { 0f }"
"{ Hello, world }"
}
||7ct
@VContract @Diag {
@Ellipse
    alabel { a }
    alabelmargin { 0f }
{ Hello, world }
}
}
The default value is {@Code 0.2f}, and so there is scope for some
reduction as well as increase.
@PP
@@Diag takes careful account of the @Code alabelangle option, the
@Code alabelprox option, the direction that the node outline or link
path is heading, and which label it is, and places the label in a way
that looks good nearly always.  When it doesn't, the remainder of this
section should help.
@PP
The @Code alabelangle option may be given an arbitrary angle, and then
the label will be printed at that angle.  There are also the special
values @Code parallel and {@Code antiparallel}, which give the direction
that the node outline or link path is going at that point and its
opposite.  These are the default values for @Code tolabelangle and
@Code fromlabelangle respectively, which explains why arrowheads point the
right way.  The @Code aligned value above is one of these two angles,
the one closest to {@Code 0d}.
@PP
The @Code alabelprox option may be {@Code N},
{@Code S}, {@Code E}, {@Code W}, {@Code NE}, {@Code SE}, {@Code NW},
{@Code SW}, or {@Code CTR}:
@CD @Diag {
//1f
@ShowTags @Box margin { 0.5c } { 24p @Font grey @Colour @I label }
}
meaning that the indicated point of the label will coincide with
{@Code alabelpos}.  These points lie on the outside of the margins
added by {@Code alabelmargin}.
@PP
The six values of @Code alabelprox given earlier (@Code { above },
@Code { below }, etc.) all produce one of {@Code N}, {@Code S} etc. for
their ultimate result; which one they produce depends on the direction
the outline or link is going at that point.  For example, @Code { above }
produces @Code { SE } when the outline or link is going from northeast
to southwest or vice versa, @Code { SW } when the outline or link is
going from northwest to southeast and vice versa, and @Code { S } when
it happens to be exactly horizontal.  There is also a dependence
on which label it is:  for example, if it is @Code "xlabel" and the
direction happens to be vertical, the result is {@Code "NW"}.
@PP
The preceding discussion is all under the assumption that the
@Code "alabelctr" option is {@Code no}.  When it is {@Code "yes"},
a small adjustment is made to the position of the label.  The selected
corner or side midpoint of the label will no longer coincide with
{@Code alabelpos}, although it will still lie on the straight line passing
through {@Code alabelpos} at the angle of {@Code alabelpos}.  The corner
or side midpoint slides up or down this line to the point which
minimises the distance from {@Code alabelpos} to the centre of the
label.  Only @Code ylabelctr has @Code "yes" for its default value; the
@Code y label often looks better centred when this adjustment is made,
particularly on lines with shallow but non-zero slope:
@CD @Tab
    @Fmta { @Col @CC A ! @Col ! @Col @CC B }
{
@Rowa
    A { @Code "ylabelctr { no }" }
    B { @Code "ylabelctr { yes }" }
@Rowa
@Rowa
@Rowa
    A { @Diag ylabelctr { no } {
        A:: @Square //0.5c &3c B:: @Square
        //
        @Link from { A } to { B } ylabel { @I { ylabel } }
      } }
    B { @Diag ylabelctr { yes } {
        A:: @Square //0.5c &3c B:: @Square
        //
        @Link from { A } to { B } ylabel { @I { ylabel } }
      } }
}
since it is then the centre of the label which is centred on the link,
rather than one of its corners.
@PP
Finally, when all else fails there is an {@Code alabeladjust} option
which translates the label by an arbitrary amount:
@ID @Code "alabeladjust { -0.5c 1.5c }"
causes the label to appear 0.5 centimetres to the left of and 1.5 centimetres
above the point where it otherwise would have done.
@End @Section