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

From: Robby Findler (robby at eecs.northwestern.edu)
Date: Sat Aug 18 21:46:24 EDT 2012

Oh, I completely misunderstood what you'd said in the previous
message. I've pushed another attempt to fix the docs.

Thanks for your patience!


On Sat, Aug 18, 2012 at 2:46 PM, Greg Hendershott
<greghendershott at gmail.com> wrote:
> 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

Posted on the users mailing list.