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 [email protected]. To view this discussion on the web visit https://groups.google.com/d/msgid/racket-users/E77B36F9-65E5-4922-AB34-3FE0ECE3689C%40gmail.com.
