[racket] long-term urls for parts of manuals

At Sat, 09 Jun 2012 16:32:03 -0400, Neil Van Dyke wrote:
> What's the best way to link to the documentation for a symbol in one of 
> the Racket manuals?
> 
> Linking into the latest release public copy of the manuals on 
> "doc.racket-lang.org", here are three options, none of which seems ideal:
> 
> 1. This works at the moment, but it's big and ugly, and I don't know 
> whether it will still work a few months from now:
> 
> http://doc.racket-lang.org/planet/Developing_Packages_for_PLaneT.html?q=can-be-loade
> d-with#%28idx._%28gentag._16._%28lib._planet/planet..scrbl%29%29%29

As long as the section tag, identifier name, and exporting module name
stay the same, that link is stable (by design, not by accident).

The section tag looks to be derived from the section title in the above
example. If the section title needs to change for some reason, the old
title can be used for the tag to preserve old references, but that
makes some attention by the document author.

The original plan included setting up a server to find documentation
for a binding in the same way that DrRacket finds documentation, but I
think we never got to that.

> 2. This does not jump to "can-be-loaded-with" (the "?q=" query part of 
> the URL doesn't seem to be used for anything):
> 
> http://doc.racket-lang.org/planet/Developing_Packages_for_PLaneT.html?q=can-be-loade
> d-with

Right --- doesn't work.

> 3. The following one works well enough in this particular case, since 
> there's only one "can-be-loaded-with", but it's not as good if I want to 
> link to something that gives multiple search hits.  Nor is it very good 
> if I wanted to direct people to a particular discussion, such as in the 
> Reference rather than the Guide, or vice versa.
> 
> http://doc.racket-lang.org/search/index.html?q=can-be-loaded-with

Yep.

> My immediate motivation is for when McFly points users to documentation 
> they need to look at, such as if McFly adds a missing problematic 
> "can-be-loaded-with" to "info.rkt" (see below).  But long-term URLs are 
> also good for things like linking to Racket documentation from Web 
> sites, printed materials, etc. that might have longevity.
> 
>      ;; TODO: See 
> http://doc.racket-lang.org/search/index.html?q=can-be-loaded-with
>      (define can-be-loaded-with 'all)

So far, we have mostly relied on option 1. The last two Racket blog
posts, for example, include lots of links of that form.