[racket] secref & other-doc

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 <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
> 
> 
> ____________________
>   Racket Users list:
>   http://lists.racket-lang.org/users