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 racket-users+unsubscr...@googlegroups.com. 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.
