[racket] secref & other-doc

Seems like the most straightforward way would be to expose cross-reference hooks within the rendered docs themselves. So when you find something you want to cross-reference, you can immediately click & pick up the information you need to embed that cross-reference into your own .scrbl source.


On Apr 30, 2014, at 9:17 AM, Matthias Felleisen <matthias at ccs.neu.edu> wrote:

> 
> I think we are discovering a weakness in our language-oriented programming approach. 
> 
> Scribble benefits from linguistic inheritance from modules but our interface story for modules is under-developed. We don't write down provides for sections and their references, which we should if others should be able to link into sections, and we also don't have tools that show us what we expose. 
> 
> -- Matthias
> 
> 
> 
> 
> 
> 
> 
> 
> On Apr 29, 2014, at 8:21 PM, Matthew Flatt <mflatt at cs.utah.edu> wrote:
> 
>> 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
>> ____________________
>> Racket Users list:
>> http://lists.racket-lang.org/users
>