Yes, I think you're arriving at the right conclusions here. If I remember correctly, "external" means "from a different run of `render`", which normally means different documents --- but not if you give multiple documents to `render` at once. Since you want to be able to render blog posts separately, different blog posts should be `render`ed separately, and they'll count as external to each other.
Making mutual references work is the job of info-in and info-out files. Document A's info-out file is the info-in file for any document that needs to reference document A. Yes, you have to run to a fixed point where none of the info-out/info-in files change. That requires a fancy `make` rule, indeed. :) Running individual passes (instead of using the `render` function) is probably *not* the way to go. To distinguish references to your own document and render them differently, I think you're right about overriding `collect-...` methods to generate your own format for entries. That's on the frontier of what we've tried to make configurable, though, so it may or may not work out as intended. At Sun, 17 Nov 2019 10:25:57 -0600, Alexis King wrote: > I’ve been playing on and off with writing a custom scribble renderer for a > blog, and my experiments have mostly been fine, but I am very confused about > xref information. I want to use a URL fragment format for my blog that is > different from the one used by the Racket documentation, but I would also > like > to be able to generate external links to the Racket documentation. My first > idea was to use `resolve-get/ext?` to see if a reference was external and > handle it differently, but I soon realized I have no idea what “external” > means there. > > Initially, I assumed that if I called `render` from `scribble/render` with > multiple parts in the `docs` argument, references between the parts would be > considered external. However, this does not appear to be the case. On the > other hand, if I reference something in The Racket Reference and I pass > `#:xrefs (list (load-collections-xref))`, those references are considered > external. Strictly speaking, that is what I want, so I am not unhappy with > the > result, but that discovery led me to other questions: > > I probably want each of my blog posts to be its own “document,” since they > should have their own namespace of tags, but passing multiple values to > `render` seems to use one namespace. I interpret that to mean that I should > be > doing something else, but in that case, I don’t think I know how to properly > set up a context where two posts can recursively reference one another. Do I > need to invoke `traverse`/`collect`/`resolve`/`render` manually? > > To generate links to the Racket documentation with the right fragment format, > should I use `xref-tag->path+anchor`, using the default value for `#:render` > to use the built-in HTML renderer? And does it make sense to override > `collect-part-tags`/`collect-target-element` to use my own collect info > format > so I can distinguish references to my blog posts from references to the > Racket > docs? > > I would like to avoid re-rendering every single one of my blog posts when > just > one of them changes, which seems possible, since `raco setup` appears to do > dependency tracking. However, I wouldn’t know where to begin if I wanted to > do > that dependency tracking myself. > > I took a look at the code for the part of `raco setup` that renders scribble > documentation, but it seems to do a lot of work, and I don’t really > understand > it. That said, I’m guessing I don’t actually need something nearly that > complicated. I’m mostly just interested in understanding how the pieces fit > together. Is the idea that I could use `#:info-out-file` to serialize > information about provided tags to disk, then just use GNU Make or something > similar to track a dependency on those serialized xref files and pass them to > `#:info-in-file`? And if I wanted to have mutually recursive documents, would > I need to run them until reaching a fixpoint? > > Thanks, > Alexis > > -- > 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/E77B36F9-65E5-4922-AB34-3FE0ECE3 > 689C%40gmail.com. -- 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/5dd1802b.1c69fb81.fcd95.567eSMTPIN_ADDED_MISSING%40gmr-mx.google.com.
