[racket] secref & other-doc

Yes!

On Wednesday, April 30, 2014, Matthew Flatt <mflatt at 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 <mflatt at 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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.racket-lang.org/users/archive/attachments/20140430/c9a9f00d/attachment.html>