aboutsummaryrefslogtreecommitdiffstats
path: root/doc/user/dia_labe
diff options
context:
space:
mode:
Diffstat (limited to 'doc/user/dia_labe')
-rw-r--r--doc/user/dia_labe433
1 files changed, 433 insertions, 0 deletions
diff --git a/doc/user/dia_labe b/doc/user/dia_labe
new file mode 100644
index 0000000..c449367
--- /dev/null
+++ b/doc/user/dia_labe
@@ -0,0 +1,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