[racket] Scribble: "Warning: some cross references may be broken due to undefined tags"

Actually I did already have a development link set up.

Since posting, I also learned that I must have the dev link in place
to build the PLT. Otherwise, `raco planet create' would fail on any
@(require (for-label (this-package-in X))). To know X, it seems to
need the dev link.

As a result, the practical steps turned out to be:

1. raco planet link ...
2. raco planet create ...  # needs 1 to work!
3. raco planet unlink ...  # only now OK
4. raco planet fileinject ...
5. raco planet remove ...
6. Upload the .PLT to PLaneT

Which was not at all clear to me from the otherwise great instructions.
Maybe it's obvious to people who are smarter and/or more experienced than me.


On a different topic, I'd used an evaluator for code examples, but the
examples do I/O (HTTP requests). It didn't really sink in that this
would run *on install for each user*. Doing so in this case was slow,
not appropriate, and/or plain wouldn't work (needed a dot file with
AWS access keys to be configured). Upon doing a test run on a fresh
machine, I watched in horror at the install time and log file. I did a
fire-drill to get 1.1 versions of packages up, which use simple
@racket[] text for the examples.

BTW the two packages I'm referring to are:
http://planet.racket-lang.org/display.ss?package=aws.plt&owner=gh
http://planet.racket-lang.org/display.ss?package=http.plt&owner=gh

On Github:
https://github.com/greghendershott/aws
https://github.com/greghendershott/http

On Sat, Aug 18, 2012 at 10:04 AM, Robby Findler
<robby at eecs.northwestern.edu> wrote:
> I think you just want to set up a development link (from an earlier step), no?
>
> Robby
>
> On Thu, Aug 16, 2012 at 1:59 PM, Greg Hendershott
> <greghendershott at gmail.com> wrote:
>> Thank you Matthias and Danny.
>>
>> In the instructions at
>> <http://docs.racket-lang.org/planet/Developing_Packages_for_PLaneT.html>,
>> I was on the early step "6.2.2 Create Documentation". Instead of
>> trying to get the docs "perfect" at this step, it sounds like I should
>> have forged ahead a few steps to the sort of activities in "6.3 Build
>> a Distribution Archive".
>>
>> If today were the "docathon" Sunday in October, I'd take a stab at
>> reordering the steps, or, adding at 6.2 a sidebar with Matthias' tip.
>>
>>
>>>     raco setup -P gregh my-little-planet-package.plt 1 0
>>>
>>> (or whatever your username and planet package may be...)
>>
>> Although I had another name in mind, I think you've convinced me
>> instead to call it, "My Little Planet Package: Friendship is Magic".
>> Let the brony jokes commence.
>>
>> On Thu, Aug 16, 2012 at 12:24 PM, Danny Yoo <dyoo at hashcollision.org> wrote:
>>> On Thu, Aug 16, 2012 at 10:36 AM, Greg Hendershott
>>> <greghendershott at gmail.com> wrote:
>>>> Working on Scribble docs for first PLaneT package. Can't reference
>>>> Racket symbols using `@racket[]'. Probably doing something dumb, but
>>>> I've compared my .scrbl to a few on PLaneT and can't see what I'm
>>>> doing wrong/differently.
>>>
>>>
>>> Ah!  If you use the 'raco setup' command, you may be able to avoid this.
>>>
>>>     raco setup -P gregh my-little-planet-package.plt 1 0
>>>
>>> (or whatever your username and planet package may be...)
>>>
>>> should build your PLaneT package.  The use of 'raco setup -P ...' will
>>> also run Scribble on your documentation and provide it with the right
>>> cross-referencing to other parts of the Racket documentation.
>>>
>>>
>>> However, if you run 'scribble' directly, Scribble won't automatically
>>> know about that cross-referencing information provided by the rest of
>>> the environment.  Matthias's suggested command line ("--xref-in
>>> setup/xref load-collections-xref") will provide that cross-referencing
>>> information to Scribble.
>> ____________________
>>   Racket Users list:
>>   http://lists.racket-lang.org/users