Yes, that sounds right to me.
At Wed, 30 Apr 2014 11:09:54 -0700, Matthew Butterick wrote: > 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 <matth...@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 <mfl...@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 > > > > > ____________________ > Racket Users list: > http://lists.racket-lang.org/users ____________________ Racket Users list: http://lists.racket-lang.org/users
