[plt-dev] Scribble errors in Dracula distribution

At Fri, 13 Feb 2009 13:28:18 -0500, Carl Eastlund wrote:
> The pre-built documentation I uploaded with Dracula 8.1 has some
> broken internal links.  You can see an example in the first paragraph
> at:
> 
> http://planet.plt-scheme.org/package-source/cce/dracula.plt/8/1/planet-
> docs/reference/index.html
> 
> These links work fine in the Dracula package itself.  Does anyone know
> why they wouldn't work in the version created for the .plt file?  I
> didn't see any errors reported when I built the package, or I would
> have copied them and reported this problem then.
> 
> Have any other planet package maintainers seen problems like this?

I've finally looked into this.

A file like "expressions.scrbl" in the Dracula document source has a
`for-label' import of "../../lang/dracula.ss" instead of `(planet
cce/dracula:8:1/lang/dracula))'. The relative path overlaps with the
Planet package after its installed, so that's why the installed docs
work. While building for the ".plt" file, though, Scribble doesn't know
that "../../lang/dracula.ss" in the source directory for the new
package corresponds to a Planet package.

One solution is to use

 (require (for-label (planet cce/dracula:8:1/lang/dracula)))

instead of relative-path `for-label' requires in the doc sources. Or
maybe add something like to `require-this-package-for-label' to the set
of documentation macros currently provided by `(planet
cce/scheme:3:0)'.


But this highlights the fact that building the docs for a new Planet
package requires that the package is installed at build time.
Otherwise, the `planet create' command seems to be set up to avoid that
requirement. Maybe `planet create' should set up a temporary
development link while building a package? Or should `planet create'
work in terms of an installed package instead of a given source
directory (in which case the docs could be built by running out of the
installation, which solves the relative-path problem)?