[plt-dev] guide vs reference

From: Robby Findler (robby at eecs.northwestern.edu)
Date: Wed Dec 16 23:29:14 EST 2009

On Wed, Dec 16, 2009 at 10:23 PM, Geoffrey S. Knauth <geoff at knauth.org> wrote:
> On Mon, Dec 14, 2009 at 1:34 PM, Jon Rafkind <rafkind at cs.utah.edu> wrote:
>> Ok, then taking Matthew's point into account how about a long term solution
>> of adding little links next to every function in the reference to its
>> corresponding guide text? [...]
> Later, on Dec 16, 2009, at 21:53, Robby Findler wrote:
>> If someone wanted to do this, probably what you'd do is change the
>> reference so all the uses of defproc there collaborate with some
>> annotations that are put into the guide.
> Is there a chicken-and-egg problem?  The guide (I think) already refers to the reference.  Now the reference will be pointing to the guide.  Maybe what's needed are two new optional arguments:  (1) which guide and (2) a tag within the guide.  If the tag's already in the guide, auto-generated in some standard way, then the only argument need would be (1).

I believe they already both point to each other actually. Scribble is
designed to make this kind of thing work.

> Changing all the defprocs sounds like a lot of work.  Maybe one expression at the top of a scribl file could essentially declare, "All defprocs in this file should guide-ref a tag in such and such guide by default."

Yes, you'd do it like that.

> Or there could be an expression at the top of a scribl file that said:
> - defprocs of (A B C) should guide-ref X
> - defprocs of (D E F G) should guide-ref Y
> - defprocs of everything else should guide-ref Z

That's the information I imagined would go into the guide. Ie, in the
guide you'd write (something like):

  @explains[car cdr cons]

and then the defprocs that define car, cdr, and cons all would point
to that use of @explains[].

> I suppose someone may need:
> - defproc of (P Q) should guide-ref #f
> - don't guide-ref anything in this scribl
> Maybe some day there will be multiple guides available for every proc set, guides for left-brains, guides for right-brains, guides for kids, guides for businessfolk, guides for hackers, guides for retirees, guides in foreign languages, lions tigers and bears...

Additional guides would mean that the defprocs would just
(automatically) point to multiple places (if one wanted to do that).


Posted on the dev mailing list.