[plt-scheme] DrScheme tool development practices

On Wed, Sep 17, 2008 at 12:03 PM, Stephen De Gabrielle
<spdegabrielle at gmail.com> wrote:
> On Wed, Sep 17, 2008 at 4:35 PM, Carl Eastlund <cce at ccs.neu.edu> wrote:
>>
>> > ; when ready to release; (use sake to automate this? )
>> > planet unlink [dev-id] foo.plt 1 4  ;; remove the link
>> > planet create foo ;; create foo.plt file for test installation  [Will -
>> > is
>> > there a reason to compile a temporary copy?]
>> > planet fileinject [dev-id] foo.plt 1 4  ;; install for testing
>>
>> You do not want to unlink the package at this point.  If you take
>> Will's (good) advice and test/build from a temporary copy, in fact,
>> make sure to unlink the original and link the copy.
>
> I thought that link-ing or fileinject the copy were functionally equivalent?
> - provided you remembered to unlink the original - so linking is probably
> safer?

Linking is not equivalent to fileinjecting for all purposes.  A
development link tells Planet to use your source directory for the
planet package.  When you use fileinject, it tells Planet to extract
the contents of a .plt file, install them in a new directory in the
Planet cache, and use that for the planet package.

Regardless, I meant not to unlink during the planet create, at which
point you don't yet have a .plt file to inject.  Move the unlink to
after the create, then fileinject.  Sorry for the confusion; you do
need to unlink, you were just doing it too early.

>> When you run
>> planet create, Planet attempts to build your Scribble documentation so
>> it can include a rendered HTML file that will be readable on the
>> Planet server.  If you unlink your package, any internal references to
>> (planet <dev-id>/foo:1:4/...) will be broken and planet create may
>> fail.
>
> I don't understand -  I thought the [planet]create-ed/fileinject-ed copy
> would have the documentation included?

Yes, but only if the package was linked at time of creation.

>> Leave your development links intact and functioning while using planet
>> create.
>
> (because create builds the documentation?)

Yes.

> I think I'm missing something in my understanding of building scribble
> documentation.
> Does scribble documentation need to be built in-place (via planet link) to
> work? [if it references other documentation?]

Scribble documentation is built in-place when you run planet create.
If you have any references to the package from itself (e.g. a
defmodule in its documentation, or one file including another via a
planet require spec instead of a local path), you will need the
development link in place while you run planet create.

If there are no such self-references, it won't matter whether you
unlink before or after running planet create.

I hope that clarifies the matter.  Sorry for the confusion, before I
said not to planet unlink, when I should have said do it after planet
create but before planet fileinject.

-- 
Carl Eastlund