[racket] secref & other-doc

You just have to know. That is, you can only refer to a specific
document when its main source module's path is somehow publicized, and
you can only refer to a section within a document its suitable tag is
publicized somehow.

We haven't pushed much on this direction, and the only sense that we've
"publicized" document modules and tags is by providing the source ---
so fishing out the ".scrbl" source file is the only answer we have, so
far. Of course, it would be nice to have a better answer in the future.

In the case of the "@ Syntax" page, you've probably already worked out
that you want

 @secref["reader" #:doc '(lib "scribblings/scribble/scribble.scrbl")]

To ensure that links will continue to work, we refrain from moving
document sources in the collection tree, and we refrain from changing
sections tags. So, the `secref` call above should always work in the
future.


At Tue, 29 Apr 2014 15:40:22 -0700, Matthew Butterick wrote:
> + What's the best way to discover the tag argument needed for secref without 
> actually fishing out the .scrbl source file associated with a particular HTML 
> file? (When a #:tag argument is specified in the .scrbl source, it doesn't seem 
> to appear in the HTML.)
> 
> + What's the best way to figure out the '(lib ...) argument needed for secref 
> or other-doc? For instance, I'm trying to use other-doc to link to the "@ 
> Syntax" page in the Scribble docs. [1] I'm probably overlooking something 
> obvious, but I've not come up with a permutation of path elements that works.
> 
> 
> [1] 
> http://docs.racket-lang.org/scribble/reader.html#%28part._.The_.Scribble_.Syntax
> _at_a_.Glance%29____________________
>   Racket Users list:
>   http://lists.racket-lang.org/users