Documentation
¶
Overview ¶
Command firstlink links each glossary term once, the first time it is mentioned, and leaves alone any term the page already links.
"Once" and "already linked" are two different problems and only one of them can be solved as the document streams.
Once is easy: link the first mention and remember the term. The state is a set, the decision is local, and it needs nothing the rewriter has not already reported.
Already linked is not. If the page links "streaming" to its own glossary somewhere, adding a second link is worse than adding none - and that link may be anywhere, including after the mention this program would otherwise take. A one-pass version links the mention and then meets the existing link, with the insertion already emitted and nothing to take back. So the first pass collects three things: the terms, the terms the page already links, and nothing else.
The rest is the same discipline as examples/gip/glossary: the exclusions are depth counters, because no selector says "not inside an existing link"; text is matched over the accumulated node, because a term can be split across chunks; and the node is written back whether or not anything changed, because accumulating it means removing the chunks it arrived in.
Source Files