It would make sense for a document to be accompanied by a library that exports the document's module path and tag names, so that the path and tags could change. Even better, the module could export `secref`-like functions to refer to various sections of the document, where the functions map to the same or different sections, and the mapping could change over time.
So, we can support a spectrum of less-to-more abstract approaches, and maybe we should build Scribble libraries that help with the more abstract end of the spectrum. I think your larger point is that Racket modules tend encourage the less abstract end, and I agree. But I also think that's the right choice, along the same lines that structs should have been made transparent by default (and it took me a long time to arrive at that conclusion). At Wed, 30 Apr 2014 12:17:08 -0400, Matthias Felleisen 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
