At Sun, 17 Nov 2019 12:12:15 -0600, Alexis King wrote: > I do have two related followup questions, though. First, how does > `raco setup` know what the dependencies are in the first place, so it > knows what it needs to rerender? I’ve noticed it seems to do things > in at least two passes—“running” the documentation before “rendering” > it—is that somehow involved?
Yes, more or less. Unless I've forgotten something, it would be ok to start with "rendering" and then use as many "re-rendering" passes as needed. But when starting from scratch, it's typically going to take a couple of passes to get cross-references resolved, in which case actually rendering the documentation the first time around would take even longer. There's probably room for improvement through heuristics that choose whether to use a "running" pass or not. Dependencies are determined by keeping track of what searches the cross-reference database are made and keeping track of which documents end up supplying results for those searches. For example, if a document links to `cons` from `racket/base`, then that's supplied by the Reference, so that means a dependency for the document on the Reference. Those dependencies are recorded by `raco setup` in "in.sxref" files. > Second, I’d like to better understand how “tag prefixes” work, [...] > What part of the pipeline implements this prefix-sensitive lookup behavior? > Is it the `resolve-get` family of functions, so I can just put things > in the `tag-prefixes` field of a `part` during the collect phase and > everything else will happen automatically? Yes, that's right. Some searches can involve multiples tries until there's a hit. That happens with the search implemented in `scribble/racket` for linking to bindings, where searching tries a module, then the module that the first re-exports from (if any), and so on. In that case, there's a way of recording all the keys that were tried, so that dependencies can be updated when something starts supplying one of the intermediate keys. > Also, I don’t completely understand the way the resolution works… is > it possible for there to be some kind of “ambiguous match,” where two > different tag definitions are equally-specific matches for a given > reference? If so, what happens in that scenario? (And if not, why > not?) A warning is reported by `raco setup` when the same key is defined by multiple documents; it inspects cross-reference information specifically to look for those duplicates. The Scribble layer by itself only warns about multiple definitions of a key within a document. (Like many warnings, it would have been better to make that one an error at the `raco setup` level, but it seemed too stringent originally.) -- You received this message because you are subscribed to the Google Groups "Racket Users" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To view this discussion on the web visit https://groups.google.com/d/msgid/racket-users/5dd1b51c.1c69fb81.d796b.dc20SMTPIN_ADDED_MISSING%40gmr-mx.google.com.
