Refer to this, or well, to that ...

Optional references allow us to refer to targets that might be missing. The result will be a link in case the target is found, or plain text otherwise.

Now let's say in our document concept we have two chapters about a certain theme. One is an introduction and rather short, while the other is very detailled. Because the intro is so short it is quickly written and available in the very first version of our document ("publish early and often"), while the detailled chapter remains a future plan for a longer time.

Now, if in the first versions (lacking the detailled chapter) we want to refer to a chapter about that theme, for a valid link we would need to use a reference to the intro chapter. Later on, when all the work is done and the detailled chapter is available, we would have to replace such links by those to the then existing detail chapter.

Or we could build a reference that switches automatically as soon as the detailled chapter becomes available. And this is done by \REF option alt.

The alt option takes a comma separated list of possible targets. If the original target (set by name) cannot be found, \REF looks for alt and tries all the targets that are listed there. The first target it finds is used.

      \REF{type=linked name=Invisible
      alt="Visible\, or sometimes not, Visible"
      }<link text>

    \REF{type=linked name=Invisible
    alt="Perhaps visible, Probably visible, Visible"
    }<link text>

Links like these are not only for prestructured documents in early versions. Chapters can always be hidden by using conditional parts - and multi target links are a way to deal with that. Point to the chapter that is actually included.