[prev in list] [next in list] [prev in thread] [next in thread]
List: racket-users
Subject: Re: [racket] secref & other-doc
From: Robby Findler <robby () eecs ! northwestern ! edu>
Date: 2014-04-30 22:05:48
Message-ID: CAL3TdOONapWoXEKNXnEGM2jAZhEFaF6RsP1zLgAp3j723=R-dw () mail ! gmail ! com
[Download RAW message or body]
[Attachment #2 (multipart/alternative)]
Yes!
On Wednesday, April 30, 2014, Matthew Flatt <mflatt@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@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
>
[Attachment #5 (text/html)]
Yes!<span></span><br><br>On Wednesday, April 30, 2014, Matthew Flatt <<a \
href="mailto:mflatt@cs.utah.edu">mflatt@cs.utah.edu</a>> wrote:<br><blockquote \
class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc \
solid;padding-left:1ex"> It would make sense for a document to be accompanied by a \
library that<br> exports the document's module path and tag names, so that the \
path and<br> tags could change. Even better, the module could export \
`secref`-like<br> functions to refer to various sections of the document, where \
the<br> functions map to the same or different sections, and the mapping could<br>
change over time.<br>
<br>
So, we can support a spectrum of less-to-more abstract approaches, and<br>
maybe we should build Scribble libraries that help with the more<br>
abstract end of the spectrum.<br>
<br>
I think your larger point is that Racket modules tend encourage the<br>
less abstract end, and I agree. But I also think that's the right<br>
choice, along the same lines that structs should have been made<br>
transparent by default (and it took me a long time to arrive at that<br>
conclusion).<br>
<br>
At Wed, 30 Apr 2014 12:17:08 -0400, Matthias Felleisen wrote:<br>
><br>
> I think we are discovering a weakness in our language-oriented programming<br>
> approach.<br>
><br>
> Scribble benefits from linguistic inheritance from modules but our interface<br>
> story for modules is under-developed. We don't write down provides for \
sections<br> > and their references, which we should if others should be able to \
link into<br> > sections, and we also don't have tools that show us what we \
expose.<br> ><br>
> -- Matthias<br>
><br>
><br>
><br>
><br>
><br>
><br>
><br>
><br>
> On Apr 29, 2014, at 8:21 PM, Matthew Flatt <<a href="javascript:;" \
onclick="_e(event, 'cvml', \
'mflatt@cs.utah.edu')">mflatt@cs.utah.edu</a>> wrote:<br> ><br>
> > You just have to know. That is, you can only refer to a specific<br>
> > document when its main source module's path is somehow publicized, \
and<br> > > you can only refer to a section within a document its suitable tag \
is<br> > > publicized somehow.<br>
> ><br>
> > We haven't pushed much on this direction, and the only sense that \
we've<br> > > "publicized" document modules and tags is by \
providing the source ---<br> > > so fishing out the ".scrbl" source \
file is the only answer we have, so<br> > > far. Of course, it would be nice to \
have a better answer in the future.<br> > ><br>
> > In the case of the "@ Syntax" page, you've probably already \
worked out<br> > > that you want<br>
> ><br>
> > @secref["reader" #:doc '(lib \
"scribblings/scribble/scribble.scrbl")]<br> > ><br>
> > To ensure that links will continue to work, we refrain from moving<br>
> > document sources in the collection tree, and we refrain from changing<br>
> > sections tags. So, the `secref` call above should always work in the<br>
> > future.<br>
> ><br>
> ><br>
> > At Tue, 29 Apr 2014 15:40:22 -0700, Matthew Butterick wrote:<br>
> >> + What's the best way to discover the tag argument needed for \
secref without<br> > >> actually fishing out the .scrbl source file \
associated with a particular<br> > HTML<br>
> >> file? (When a #:tag argument is specified in the .scrbl source, it \
doesn't<br> > seem<br>
> >> to appear in the HTML.)<br>
> >><br>
> >> + What's the best way to figure out the '(lib ...) argument \
needed for<br> > secref<br>
> >> or other-doc? For instance, I'm trying to use other-doc to link to \
the "@<br> > >> Syntax" page in the Scribble docs. [1] I'm \
probably overlooking something<br> > >> obvious, but I've not come up \
with a permutation of path elements that works.<br> > >><br>
> >><br>
> >> [1]<br>
> >><br>
> <a href="http://docs.racket-lang.org/scribble/reader.html#%28part._.The_.Scribble_.Syntax" \
target="_blank">http://docs.racket-lang.org/scribble/reader.html#%28part._.The_.Scribble_.Syntax</a><br>
> >> _at_a_.Glance%29____________________<br>
> >> Racket Users list:<br>
> >> <a href="http://lists.racket-lang.org/users" \
target="_blank">http://lists.racket-lang.org/users</a><br> > > \
____________________<br> > > Racket Users list:<br>
> > <a href="http://lists.racket-lang.org/users" \
target="_blank">http://lists.racket-lang.org/users</a><br> ><br>
><br>
> ____________________<br>
> Racket Users list:<br>
> <a href="http://lists.racket-lang.org/users" \
target="_blank">http://lists.racket-lang.org/users</a><br> ____________________<br>
Racket Users list:<br>
<a href="http://lists.racket-lang.org/users" \
target="_blank">http://lists.racket-lang.org/users</a><br> </blockquote>
____________________
Racket Users list:
http://lists.racket-lang.org/users
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic