Yes! On Wednesday, April 30, 2014, Matthew Flatt <mfl...@cs.utah.edu> wrote:
> 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<javascript:;>> > 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 >
____________________ Racket Users list: http://lists.racket-lang.org/users
