using nested-referents action

A new set of referent definitions can be created for the duration of an action by prefixing it with using nested-referents. When the new set is created, the current referent set is saved until the new action has run its course. The new referent will be used for all actions and rules up to the end of that action.

The new set initially has no definitions. At the end of the new action,

1. the referents are resolved
2. the referent set is discarded
3. the saved referent set is restored

Referents are resolved by replacing the referent with its final value in every stream that it was written to. If a referent written to a stream has no value when it is resolved, then OmniMark signals a fatal error.

If any stream was opened within the scope of a using nested-referents prefix, then the stream is "flushed" after the referent resolution. That is, the text in the stream is written to its final destination (buffer, referent, file, or externally defined output stream), maximum line-length checking is performed, and the referents-allowed modifier is removed from the stream.

It is an error for a stream attached to a referent to be open when the referent is resolved. (Streams are automatically closed when the scope in which they were declared ends. If the end of the stream's scope occurs before the end of the referent's scope, then the stream will automatically be closed before the referent is resolved. Otherwise, it is the programmer's responsibility to close the stream before the referent resolution.)

This example is a simple case of using a nested referent set. An element "link" is found in an SGML document, and the program's response is to parse and output a document described by the "link" element's attribute.

The input and output files' names are based on the attribute's value, and a special group of (element) rules is used to process the other document (which may very well require different processing than the document containing the "link" element). using nested-referents informs OmniMark that, by the end of the parsing of the linked document, the output file should have all of its referents processed and replaced by their definition values.

  element link
     ; An element that links to another document that needs processing.
     do sgml-parse document with scan file "%v(docname).doc"
        using nested-referents
           using group linked-doc
              set file "%v(docname).out" with referents-allowed
                  to "%c"
     done
     suppress