Next: SECTIONREF   Previous: READY   Contents: Contents

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.

Syntax

\REF{options}

\REF{options}<body>

Options

This tag supports various options. Several of them are optional and default to values mentioned in their descriptions.

name
specifies the name of the target anchor. A missing link is an error unless occasion is set to a true value or an altternative address can be found.
type
configures which way the result should be produced.
alt
If the anchor specified by name 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.
occasion
If the tag cannot find a valid address (either by name or by trying <alt>), usually an error occurs. By setting this option to a true value a missing link will be ignored. The result is equal to a non specified \REF tag.

Body

If there's a body, the resulting text will be built by the body content, otherwise by the value 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 \SEQ are evaluated
  with the respective numbers.

The body is optional as long as formatting is not set to plain because in this case there would be two concurrencing result texts - the reference value and the body content. That's why a body is forbidden if option type is set to plain.

Notes

\REF is part of the basic tag set supported by all PerlPoint translators. The results may vary depening on the target format capabilities.

Example

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 1 and 2. And here are various ways to reference one of them:

useresult
\REF{name=mountains}1, plain text
\REF{name=mountains type=plain}1, plain text
\REF{name=mountains type=linked}1, a link to the "mountains" number
\REF{name=mountains type=linked}<Mountains>Mountains, a link to the "mountains" number
\REF{name=mountains alt="hills"}1, plain text, in any case
\REF{name=mountains alt="hills" type=linked}<Mountains>Mountains, 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
\REF{name=mountains alt="hills" type=linked occasion=1}<Mountains>Mountains, 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 Mountains otherwise

See also

More basic set tags: B, C, EMBED, FORMAT, HIDE, I, IMAGE, INCLUDE, LOCALTOC, READY, SEQ, STOP and TABLE.

Next: SECTIONREF   Previous: READY   Contents: Contents