@Section
   @Title { "@LinkSource", "@LinkDest", and "@URLLink" }
   @Tag { link_source }
@Begin
@PP
The two symbols @@LinkSource and @@LinkDest
link.source.sym @Index { @@LinkSource symbol }
link.dest.sym @Index { @@LinkDest symbol }
work together to create @I { cross links } in a document, that is, points
where a user viewing the document on screen can click and be transported to
another point in the document.  We call the point where the user
clicks the @I source of the link, and the point where the user
arrives the @I destination of the link.
@PP
To create a source point, place
@ID { @I tag @Code "@LinkSource" @I object }
at some point in the document, where the value of @I tag is a legal
cross reference tag, and @I object is an arbitrary Lout object.  The
result of this is just {@I object}, but if the user of a screen
viewer clicks on any point within the rectangular bounding box
of that object, a link will be entered.
@PP
At present, @I object above is treated as though it were enclosed
in @@OneCol.  This means that a long link source or destination point
will not break over two lines as part of an enclosing paragraph.
@PP
To create a destination point, place
@ID { @I tag @Code "@LinkDest" @I object }
at some point in the document.  Again, @I tag must evaluate to a
legal cross reference tag, and @I object may be any Lout
object.  All @Code "@LinkSource" symbols whose
tag is equal to this one are linked to this destination point.
@PP
For every source point there must be exactly one destination point with
the same tag, otherwise it will not be clear where the link is
supposed to take the user.  Lout will print a warning if this
condition is violated anywhere; it will refuse to insert a
destination point with the same name as a previous one, but it is not
able to refrain from inserting a source point with no corresponding
destination point, and such points must cause errors of some kind when
viewed (exactly what error will depend on the viewer).
@PP
The @@URLLink symbol is similar to @@LinkSource in being the
source point of a link, but instead of a tag you supply a URL
to some other document altogether:
@ID @Code {
"\"http://snark.ptc.spbu.ru/~uwe/lout/lout.html\" @URLLink { Lout Home Page }"
}
The URL will need to be enclosed in quotes, because of the "/"
characters which are otherwise taken to be concatenation operations.  As
for @@LinkSource, the result is just the object to the right, like this:
@ID { "http://snark.ptc.spbu.ru/~uwe/lout/lout.html" @URLLink { Lout Home Page } }
but if the user clicks on this object on the screen they enter a
link that takes them to the given URL location, assuming that
the software which they are using to display the document is
clever enough to do this.
@PP
For the purposes of @@Common, @@Rump, and @@Meld, two @@LinkSource
objects are considered to be equal if their right parameters are
equal; the left parameters are not considered.  This behaviour is
needed, for example, to make index entries look reasonable when
melded.  If two @@LinkSource objects with equal right parameters but
different left parameters are melded into one, one of the two will
be the result, but which one is undefined.  Notice that melding
cannot produce an undefined link, since the worst it can do is
delete a @@LinkSource.
@PP
Practically speaking, the right parameters of @@LinkSource
and @@URLLink need to be non-null, non-empty objects, since
otherwise there is nothing visible for the user to click on.
(This condition is not checked or enforced by Lout.)  However,
the right parameter of @@LinkDest could reasonably be empty
or null.  Usually, when @@Null lies inside a non-concatenation
object, for example
@ID "@OneCol @Null"
the effect of the @@Null is lost -- the result in this example
is equivalent to an empty object.  However, when the right
parameter of @@LinkDest is @@Null:
@ID "@LinkDest @Null"
or when it is some object treated like @@Null by Lout (e.g.
a @@Tagged symbol), then the @@LinkDest itself has the effect
on surrounding concatentation operators that @@Null has,
allowing it to be made effectively invisible in the printed
document, though still really there.
@End @Section