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
