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-3FE0ECE3689C%40gmail.com.
