[plt-dev] guide vs reference

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).

Robby