[plt-scheme] Red links in scribble documentation

On Mon, Oct 19, 2009 at 12:02 PM, Laurent <laurent.orseau at gmail.com> wrote:
> The package and the .ss files (btw, .scm files cannot be used in packages??)
> are in the "..../lazy-doc" directory,
> and the scrbl files are in "..../lazy-doc/reference".
>
> Here is common.scrbl header:
> ---------------
> #lang scribble/manual
>
> @(require (for-label scheme
>                      "../common.ss"))
>
> @defmodule[(planet orseau/lazy-doc:1:0/common)]
> ---------------
>
> There is no warning when I use "planet create ...." and all the
> documentation looks fine except for the red links.
> I also set a hard link with "add-hard-link" and when I test my package with
> (require (planet orseau/lazy-doc:1:0/common))
> in another file in another directory all is fine.
>
> I did not use directly setup-plt or any install command. Should I have?
>
> Thanks,
> Laurent

Ah ha.  I see the problem.  You have required "../common.ss"
for-label, but you have declared your documentation to describe
(planet orseau/lazy-doc:1:0/common).  Scribble is not smart enough to
know those are the same thing.  You want to use a planet path for both
positions.

I also recommend you replace the require spec with (this-packagin-in
common), and the defmodule with (defmodule/this-package common).  Both
bindings are available from (planet cce/scheme), and you can find the
online documentation here:

http://planet.plt-scheme.org/package-source/cce/scheme.plt/6/0/planet-docs/manual/Modules.html#(part._planet)
http://planet.plt-scheme.org/package-source/cce/scheme.plt/6/0/planet-docs/manual/scribble.html

(It only occurs to me now that I should have those documented in the
same section for just this reason... oops.)

If you use them, your code will continue to work even when you release
1.1, 1.2, 2.0, etc., without having to update the version numbers.

--Carl