[plt-dev] guide vs reference

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

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

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

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