// include macro definitions shared by all basic tag docs \INCLUDE{type=pp file="basic-tag-macros.pp" smart=1} =REF This is a very general and highly configurable reference. It can be used both to make linked and unlinked references, it can fallback to alternative references if necessary, and it can finally be that optional that the specified reference does not even has to exist. \B \\REF{options} \\REF{options} \B This tag supports various options. Several of them are optional and default to values mentioned in their descriptions. :\B: specifies the name of the target anchor. A missing link is an error unless \C is set to a true value or an \Cternative address can be found. :\B: configures which way the result should be produced. > * \I<\C:> The result is made a link to the referenced object. * \I<\C:> This is the default formatting and means that the result is supplied as plain text. < :\B: If the anchor specified by \C cannot be found, the tag will try all entries of a comma separated list specified by this options value. (For readability, commata may be surrounded by whitespaces.) Trials follow the listed link order, the first valid address found will be used. :\B: If the tag cannot find a valid address (either by \C or by trying \), usually an error occurs. By setting this option to a true value a missing link will be ignored. The result is equal to a \I \C<\\REF> tag. \B If there's a body, the resulting text will be built by the body content, otherwise by the \I of the referenced object. The value of a referenced object highly depends on its construction method. Please refer to the specific elements documentation for details or just find it out be a trial. Headline anchors made by the parser have an value of the "headline string", which means the pure title without any included tags. Sequence numers made by \C<\\SEQ> are evaluated with the respective numbers. The body is optional as long as formatting is not set to \C because in this case there would be two concurrencing result texts - the reference value \I the body content. That's why a body is \I if option \C is set to \C. \B \B<\\REF> is part of the \I supported by \I PerlPoint translators. The results may vary depening on the target format capabilities. \B Here are several sequence numbers, partially declared in a conditional document part: ? $slides and $longShow \\SEQ{type=image name=mountains} ? $slides \\SEQ{type=image name=hills} The numbers produced may be \C<1> and \C<2>. And here are various ways to reference one of them: @| use | result \C<\\REF{name=mountains}> | \C<1>, plain text \C<\\REF{name=mountains type=plain}> | \C<1>, plain text \C<\\REF{name=mountains type=linked}> | \C<1>, a link to the "mountains" number \C<\\REF{name=mountains type=linked}> | \C, a link to the "mountains" number \C<\\REF{name=mountains alt="hills"}> | \C<1>, plain text, in any case \C<\\REF{name=mountains alt="hills" type=linked}> | \C, a link to the "mountains" number if $slides and $longShow are set, a link to the "hills" number if only $slides is set, and an error otherwise \C<\\REF{name=mountains alt="hills" type=linked occasion=1}> | \C, a link to the "mountains" number if $slides and $longShow are set, a link to the "hills" number if only $slides is set, and just \C otherwise \B More basic set tags: \OTHER_BASIC_TAGS{current=REF}.