[plt-dev] Scribble errors in Dracula distribution

From: Matthew Flatt (mflatt at cs.utah.edu)
Date: Mon Mar 9 13:52:49 EDT 2009

At Mon, 9 Mar 2009 11:43:36 -0600, Matthew Flatt wrote:
> At Mon, 9 Mar 2009 13:36:59 -0400, Carl Eastlund wrote:
> > On Mon, Mar 9, 2009 at 11:47 AM, Matthew Flatt <mflatt at cs.utah.edu> wrote:
> > > At Mon, 9 Mar 2009 11:30:58 -0400, Carl Eastlund wrote:
> > >>  If I make a require expander that generates
> > >> a (planet ...) spec with appropriate version number, will Scribble
> > >> "understand" that?
> > >
> > > Yes. Scribble just looks at `for-label' bindings, leaving it to the
> > > module+macro system to create those bindings.
> > 
> > What is different about the result of (planet ...) bindings from
> > relative bindings that gives Scribble a clue as to when to provide
> > links, given that both should refer to the same file at the time the
> > documentation is built?
> The "given" isn't actually given.
> When you say
>  planet create <dir>
> then even if <dir> and a package installation happen to be the same on
> the filesystem, `planet create' doesn't access <dir> through a `planet'
> path, so relative paths in <dir> are unrelated to Planet paths at the
> level of module paths.

On further thought, it may not be because of the way that <dir> is
accessed, but because `planet create' creates a directory to stage the
package and then builds the docs out of that directory, instead of
using the existing directory. (The coincidence of files accessed
directly and through `planet' and `lib' paths is a little fragile,
since there's no reliable way to normalize paths, but I think that's
not the issue after all.)

That is, `planet create' doesn't currently require the <dir> to be an
installation, but if it does happen to be one, maybe that coincidence
would be enough --- if the documentation were rendered using the
existing document module, instead of a staged copy.

Even so, we may not want to rely on that coincidence.

Posted on the dev mailing list.