2.4 Document Passes
A Scribble document is processed in four passes:
The traverse pass traverses the document content in document order so that information from one part of a document can be communicated to other parts of the same document. The information is transmitted through a symbol-keyed mapping that can be inspected and extended by TraverseElements and TraverseBlocks in the document. The traverse pass iterates the traversal until it obtains a fixed point (i.e., the mapping from one iteration is unchanged from the previous iteration).
The collect pass globally collects information in the document that can span documents that are built at separate times, such as targets for hyperlinking. A PartRelativeElement or CollectElement participates directly in this pass.
The resolve pass matches hyperlink references with targets and expands delayed elements (where the expansion should not contribute new hyperlink targets). A DelayedElement or DelayedBlock participates directly in this pass.
The render pass generates the result document. A RenderElement participates directly in this pass.
None of the passes mutate the document representation. Instead, the traverse pass, collect pass, and resolve pass accumulate information in a side CollectInfo map and ResolveInfo map. The collect pass and resolve pass are effectively specialized version of traverse pass that work across separately built documents.
2.4.1 Cross-Reference Tags
Cross-reference information that is gathered during the collect pass and used during the [resolve pass] can make use of tags as keys. A tag is represented by a list (or pair list) that starts with a symbol or as GeneratedTag object. The symbol effectively identifies the type of the tag, such as #'part for a tag that links to a section, or #'def for a function definition. The symbol also effectively determines the interpretation of the remainder of the tag.
A part can have a tag prefix, which is effectively added onto the second item within each tag whose first item is #'part, #'tech, or #'cite, or whose second item is a list that starts with #'prefixable:
The prefix is added to a string second item by creating a list containing the prefix and string.
The prefix is added to a list second item after #'part, #'tech, or #'cite using List.cons.
The prefix is added to a second item that starts #'prefixable by adding it to the list after #'prefixable.
A prefix is not added to a GeneratedTag item.
A tag prefix is used for reference outside its part, including the use of tags in the Part.tags property. Typically, a document’s main part has a tag prefix that applies to the whole document; references to sections and defined terms within the document from other documents must include the prefix, while references within the same document omit the prefix. Part prefixes can be used within a document as well, to help disambiguate references within the document.
Some procedures accept a “tag” that is just the string part of the full tag, where the symbol part is supplied automatically. For example, section and secref both accept a string “tag”, where #'part is implicit.
2.4.2 Part Context
During the collect pass and resolve pass, part context information is accumulated from enclosing parts. The context starts as an empty map. When Part.tag_prefix reports a map, then for each key in the table, the value in the table is merged with the context from enclosing parts. A value is merged by adding the key and value to the accumulation if the key is not yet present, or by consing the new value to the context’s current value when the key is present. Use Part.context_accumulation during the collect pass or resolve pass to retrieve the value that has been accumulated from enclosing parts.