@Section
    @Tag { dia_link }
    @Title { Links }
@Begin
@PP
@Code "@Diag" has one basic symbol for creating links, called
diagrams. @RawIndex { diagrams }
diagrams.link @SubIndex { @Code "@Link" symbol }
link.diagrams @Index { @Code "@Link" symbol (diagrams) }
{@Code "@Link"}.  It draws a link between two points or nodes
given by {@Code from} and {@Code to} options, along a path
diagrams. @RawIndex { diagrams }
diagrams.from @SubIndex { @Code "from" option }
from.diagrams @Index { @Code "from" option (diagrams) }
diagrams. @RawIndex { diagrams }
diagrams.to @SubIndex { @Code "to" option }
to.diagrams @Index { @Code "to" option (diagrams) }
given by a {@Code path} option:
diagrams. @RawIndex { diagrams }
diagrams.path @SubIndex { @Code "path" option }
path.diagrams @Index { @Code "path" option (diagrams) }
@ID @OneRow @Code @Verbatim {
@Link
    path { ... }
    from { ... }
    to { ... }
}
Unlike {@Code "@Node"}, {@Code "@Link"} has no following object.
@PP
The @Code "path" option may be used to produce a link of any shape, as
Section {@NumberOf dia_defi} explains.  There are also values
that produce standard paths.  These are listed in full in the summary
(Section {@NumberOf dia_summ}).  Here is a sample:
@ID @Tab
    @Fmta { @Col @Code { path "{" A "}" } ! @Col ! @Col B !
    @Col 0.5c @Wide ! @Col @Code { path "{" C "}" } ! @Col ! @Col D
    }
{

@Rowa
    A { line }
    B {
@Diag {
A:: @Circle //1c ||2c B:: @Circle
// @Link from { A } to { B } path { line } arrow { yes }
}
}
    C { acurve }
    D {
@Diag {
A:: @Circle //1c ||2c B:: @Circle
// @Link from { A } to { B } path { acurve } arrow { yes }
}
}

@Rowa
    A { rvlcurve }
    B {
@Diag {
A:: @Circle //1c ||2c B:: @Circle
// @Link from { A } to { B } path { rvlcurve } arrow { yes }
}
}
    C { ccurve }
    D {
@Diag {
A:: @Circle //1c ||2c B:: @Circle
// @Link from { A } to { B } path { ccurve } arrow { yes }
}
}

}
The name @Code rvlcurve is a reminder that the curve goes right, then
vertically, then left, with curved corners.  The @Code acurve and
@Code ccurve values produce circular arcs, anticlockwise or clockwise,
lying on the circle passing through the endpoints, or through the
centres of the endpoints when they are tags denoting nodes.  There
is also @Code "curve" which is an abbreviation for {@Code "acurve"}.
All these standard paths are defined in a way that makes sense no matter
where the two nodes are relative to each other, except that no promise
of a sensible result is made for two nodes very close together.
@PP
@Code "@Link" has two options, @Code bias and {@Code radius}, that may be
diagrams. @RawIndex { diagrams }
diagrams.bias @SubIndex { @Code "bias" option }
bias.diagrams @Index { @Code "bias" option (diagrams) }
diagrams. @RawIndex { diagrams }
diagrams.radius @SubIndex { @Code "radius" option }
radius. @RawIndex { @Code "radius" option }
radius.in.diagrams @SubIndex { in diagrams }
used to fine-tune the path.  The @Code "bias" option determines the
maximum distance that a curve is permitted to stray:
@CD @Tab
    @Fmta { @Col A ! @Col ! @Col B }
{

@Rowa

    A { @Diag vstrut { no } margin { 0.5c } {
A:: @Circle //1.5c ||2c B:: @Circle
//
LA:: @Line pathstyle { cdashed } from { A } to { B }
LB:: @Curve from { A } to { B }
@Line arrow { both } from { LA@LMID } to { LB@LMID }
    ylabel { @I bias } # ylabeladjust { 0.15c 0 }
} }

    B { @Diag vstrut { no } margin { 0.5c } {
A:: @Circle //1.5c ||2c B:: @Circle
//
LA:: @RVLCurve from { A } to { B }
LB:: @Line pathstyle { cdashed } from { B@E } to { B@E ++ {0 2.5c} }
@Line arrow { both } from { LB@LMID } to { LA@LMID }
     ylabel { @I bias } ylabeladjust { 0 0.05c }
} }

}
The @Code radius option does @I not apply to @Code acurve and
{@Code ccurve}; rather, it determines the radius of the arcs at
the corners of @Code rvlcurve and its kin.  A very large radius will be
reduced to the largest reasonable value, which provides a way to get
a semicircle at the right in an {@Code rvlcurve}.
@PP
Lout has no idea where the path is wandering, and cannot take it into
account when placing a diagram on the page:
@ID {
@Code @Verbatim {
@Link
    path { acurve }
    bias { 2c }
}
||7ct
@Diag vstrut { no } {
A:: @Circle &3c B:: @Circle
//
@Link path { acurve } bias { 2c } from { A } to { B }
}
}
In such cases you have to arrange for the extra space yourself, by adding
an extra paragraph symbol, blank row or column in a table, or whatever.
@PP
As with {@Code "@Node"} options, {@Code "@Link"} options may all be
given to {@Code "@Diag"} as well, where they apply to every link in
the diagram, unless overridden in the usual way.  They also appear
in the setup file, where they apply to every link in every diagram
of the document, unless overridden.
@PP
There are {@Code pathstyle}, {@Code pathdashlength}, {@Code pathwidth},
and {@Code pathcolour} (alternative name {@Code pathcolor})
diagrams. @RawIndex { diagrams }
diagrams.pathstyle @SubIndex { @Code "pathstyle" option }
pathstyle.diagrams @Index { @Code "pathstyle" option (diagrams) }
diagrams. @RawIndex { diagrams }
diagrams.pathdashlength @SubIndex { @Code "pathdashlength" option }
pathdashlength.diagrams @Index { @Code "pathdashlength" option (diagrams) }
diagrams. @RawIndex { diagrams }
diagrams.pathwidth @SubIndex { @Code "pathwidth" option }
pathwidth.diagrams @Index { @Code "pathwidth" option (diagrams) }
diagrams.pathcolour @SubIndex { @Code "pathcolour" option }
pathcolour.diagrams @Index { @Code "pathcolour" option (diagrams) }
options which affect the path's appearance like the
{@Code outlinestyle}, {@Code outlinedashlength}, {@Code outlinewidth},
and {@Code outlinecolour} options of {@Code "@Node"} affect its outline.
Here they are with their default values:
@ID {
@Code @Verbatim {
@Link
    pathstyle { solid }
    pathdashlength { 0.2f }
    pathwidth { thin }
    pathcolour { nochange }
}
}
When {@Code pathstyle} contains just one value (as opposed to a sequence
of values) @Code "@Diag" tries to divide the path into fewer segments
than it would otherwise, to make dashed and dotted paths look as good
as possible.  There is also a {@Code pathgap} option which affects only
@Code doubleline paths; it
diagrams. @RawIndex { diagrams }
diagrams.pathgap @SubIndex { @Code "pathgap" option }
pathgap.diagrams @Index { @Code "pathgap" option (diagrams) }
determines the gap between the centres of the two lines.
@PP
The @Code "@Link" symbol has an @Code arrow option, which adds an
diagrams. @RawIndex { diagrams }
diagrams.arrow.opt @SubIndex { @Code "arrow" option }
arrow.opt.diagrams @Index { @Code "arrow" option (diagrams) }
arrowhead to the end of the link:
@ID {
@Code @Verbatim {
@Link
    arrow { yes }
}
||7ct
@Diag {
1c @High 3c @Wide
//
@Link
    from { 0,0 }
    to { 1,1 }
    arrow { yes }
}
}
Its value may be {@Code no} (the default), {@Code yes}, {@Code forward}
(which is the same as {@Code yes}), {@Code back}, or {@Code both}:
@ID {
@Code @Verbatim {
@Link
    arrow { both }
    pathcolour { green }
}
||7ct
@Diag {
1c @High 3c @Wide
//
@Link
    from { 0,0 }
    to { 1,1 }
    arrow { both }
    pathcolour { green }
}
}
To colour the arrowheads differently you need {@Code fromlabel} and
{@Code tolabel}, described in Section {@NumberOf dia_labe}.  Colouring
a link using `{@Code "green @Colour @Link ..."}' works too; it also
colours the link's labels.
@PP
@Code "@Link" offers {@Code arrowstyle}, {@Code arrowwidth}, and
{@Code arrowlength} options for changing the appearance of the
arrowheads.  For
diagrams. @RawIndex { diagrams }
diagrams.arrowstyle @SubIndex { @Code "arrowstyle" option }
arrowstyle.diagrams @Index { @Code "arrowstyle" option (diagrams) }
diagrams. @RawIndex { diagrams }
diagrams.arrowwidth @SubIndex { @Code "arrowwidth" option }
arrowwidth.diagrams @Index { @Code "arrowwidth" option (diagrams) }
diagrams. @RawIndex { diagrams }
diagrams.arrowlength @SubIndex { @Code "arrowlength" option }
arrowlength.diagrams @Index { @Code "arrowlength" option (diagrams) }
consistency it is usually best to set the corresponding options to
the @Code "@Diag" symbol, which applies them to every arrow in the
diagram:
@ID @OneRow @Code @Verbatim {
@Diag
    arrowstyle { solid }
    arrowwidth { 0.3f }
    arrowlength { 0.5f }
{
    ...
}
}
This shows the default values:  a solid arrowhead like the ones above,
@Code "0.3f" wide (across) and @Code "0.5f" long.  The @Code "arrowwidth"
and @Code "arrowlength" options may be any length; it may be necessary to
decrease @Code "arrowwidth" when many arrows enter one node.  The full list
of possible values for @Code "arrowstyle" is
@ID @Tab
    @Fmta { @Col @Code { "arrowstyle {" A "}" } ! @Col B  }
    vmargin { 1.0vx }
{
@Rowa
    A { solid }
    B { @Diag vstrut { no } { A:: @Circle  |2c B:: @Circle 
	// @Link from { A } to { B } arrow { yes } arrowstyle { solid } } }
@Rowa
    A { solidwithbar }
    B { @Diag vstrut { no } { A:: @Circle  |2c B:: @Circle 
	// @Link from { A } to { B } arrow { yes } arrowstyle { solidwithbar } } }
@Rowa
    A { halfopen }
    B { @Diag vstrut { no } { A:: @Circle  |2c B:: @Circle 
	// @Link from { A } to { B } arrow { yes } arrowstyle { halfopen } } }
@Rowa
    A { open }
    B { @Diag vstrut { no } { A:: @Circle  |2c B:: @Circle 
	// @Link from { A } to { B } arrow { yes } arrowstyle { open } } }
@Rowa
    A { curvedsolid }
    B { @Diag vstrut { no } { A:: @Circle  |2c B:: @Circle 
	// @Link from { A } to { B } arrow { yes } arrowstyle { curvedsolid } } }
@Rowa
    A { curvedhalfopen }
    B { @Diag vstrut { no } { A:: @Circle  |2c B:: @Circle 
	// @Link from { A } to { B } arrow { yes } arrowstyle { curvedhalfopen } } }
@Rowa
    A { curvedopen }
    B { @Diag vstrut { no } { A:: @Circle  |2c B:: @Circle 
	// @Link from { A } to { B } arrow { yes } arrowstyle { curvedopen } } }
@Rowa
    A { circle }
    B { @Diag vstrut { no } { A:: @Circle  |2c B:: @Circle 
	// @Link from { A } to { B } arrow { yes } arrowstyle { circle } } }
@Rowa
    A { box }
    B { @Diag vstrut { no } { A:: @Circle  |2c B:: @Circle 
	// @Link from { A } to { B } arrow { yes } arrowstyle { box } } }
@Rowa
    A { many }
    B { @Diag vstrut { no } { A:: @Circle  |2c B:: @Box 
	// @Link from { A } to { B } arrow { yes } arrowstyle { many } } }
}
The reader is invited to admire the beautifully sharp points on these
arrowheads.
@FootNote {
The outlines of all nodes and arrowheads are drawn on the inside of the
geometrical curve defining them, not centred over the curve as is common in
PostScript documents.  Hence, the arrowheads and node outlines intersect at
a true geometrical point; they do not overlap by one line width.  Furthermore,
the standard link paths terminate at the base of the arrowhead, not at
the point; the arrowhead itself is responsible for continuing the link
path, at the appropriate width (although never dashed or dotted), from its
base to its point, and hence can and does ensure that the link path does
not overstrike and thicken the point of the arrow.
} &2s
The arrow with style @Code solidwithbar has a bar at the tip of the
arrowhead, whose length equals the width of the arrow and whose
width is {@Code pathwidth}, like this:
@ID @Diag {
A:: @Box margin { 0i } outlinestyle { noline } 3c @Wide
//
@Link from { A@W } to { A@CTR } arrow { forward } arrowstyle { solidwithbar }
@Link from { A@CTR } to { A@E } arrow { back } backarrowstyle { solidwithbar }
}
This example shows that half of the bar extends beyond the area
allocated to the arrow, so that if two of these arrows meet from
opposite directions, their bars will exactly overstrike.
@PP
Corresponding with {@Code arrowstyle}, {@Code arrowwidth}, and
{@Code arrowlength}, there are {@Code backarrowstyle},
{@Code backarrowwidth}, and {@Code backarrowlength} options which
diagrams. @RawIndex { diagrams }
diagrams.backarrowstyle @SubIndex { @Code "backarrowstyle" option }
backarrowstyle.diagrams @Index { @Code "backarrowstyle" option (diagrams) }
diagrams. @RawIndex { diagrams }
diagrams.backarrowwidth @SubIndex { @Code "backarrowwidth" option }
backarrowwidth.diagrams @Index { @Code "backarrowwidth" option (diagrams) }
diagrams. @RawIndex { diagrams }
diagrams.backarrowlength @SubIndex { @Code "backarrowlength" option }
backarrowlength.diagrams @Index { @Code "backarrowlength" option (diagrams) }
determine the style and size of the back arrow; it doesn't have
to be the same style or size as the forward arrow:
@ID {
@Code @Verbatim {
@Link
    arrow { both }
    backarrowstyle { circle }
}
||7ct
@Diag {
1c @High 3c @Wide
//
@Link
    from { 0,0 }
    to { 1,1 }
    arrow { both }
    backarrowstyle { circle }
}
}
It is also possible to place an arbitrary object at the beginning or
end of a link, using the @Code "fromlabel" and @Code "tolabel" options
of Section {@NumberOf dia_labe}.
@PP
@Code "@Diag" offers link symbols which are just @Code "@Link" with
one of the standard paths already set:  {@Code "@Line"},
{@Code "@Curve"}, {@Code "@CCurve"},
diagrams. @RawIndex { diagrams }
diagrams.line @SubIndex { @Code "@Line" symbol }
line.diagrams @Index { @Code "@Line" symbol (diagrams) }
diagrams. @RawIndex { diagrams }
diagrams.curve @SubIndex { @Code "@Curve" symbol }
curve.diagrams @Index { @Code "@Curve" symbol (diagrams) }
{@Code "@RVLCurve"}, and so on.  There are also symbols in which
the @Code "arrow" option is set to @Code yes as well:  {@Code "@Arrow"},
diagrams. @RawIndex { diagrams }
diagrams.arrow.sym @SubIndex { @Code "@Arrow" symbol }
arrow.sym.diagrams @Index { @Code "@Arrow" symbol (diagrams) }
{@Code "@CurveArrow"}, {@Code "@CCurveArrow"}, {@Code "@RVLCurveArrow"},
and so on.  See the summary (Section {@NumberOf dia_summ}) for the
full list of these symbols.  You will still need the @Code "arrow" option
to get backward arrows and double-ended arrows.
@End @Section