Trouble documenting a form with Scribble

Simon Haines

unread,

Jun 25, 2019, 10:30:48 PM6/25/19

to Racket Users

I'm porting the PLaneT package 'packrat' to the new package catalog and I'm having trouble documenting a syntax form.

Here is the relevant snippet from the scribble documentation:

@defform/subs[#:literals (! / := |@| quote)
              (parse id (nonterminal-id (sequence body body0 ...) ...) ...)
              ([sequence (part ...)]
               [part (! part ...)
                     (/ sequence ...)
                     (? expr)
                     (code:line id := (quote kind))
                     (code:line id := |@|)
                     (code:line id := nonterminal-id)
                     (code:line id := (? expr))
                     (code:line nonterminal-id)])]{
Documentation here...
}

When compiling the documentation, 'raco setup packrat' complains with:

raco setup: WARNING: undefined tag in <pkgs>/packrat/scribblings/packrat.scrbl:
raco setup: ((lib "packrat/main.rkt") parse)

The form is rendered with a red underline and is not correctly linked. It is correctly provided by 'main.rkt' and later in the documentation, an example containing the syntax runs OK. I've ensured the syntax is available through the REPL, and have required the module with 'for-label' in the scribble file as well. All other exports are linked OK. The previous documentation had this issue as well, see here.

I think this is a simple mistake I have made, but I can't spot it and have run out of ideas. Many thanks.

Simon.

Ben Greenman

unread,

Jun 26, 2019, 10:05:51 AM6/26/19

to Simon Haines, Racket Users

Here's a small package that gets the link right (attached).

If the example doesn't help, can you share your code?

aaa.tar.gz

Simon Haines

unread,

Jun 26, 2019, 9:08:49 PM6/26/19

to Ben Greenman, Racket Users

Thanks Ben! Took me a while to track this one down using your example as a guide. Because the macro was provided by a submodule of the collection, I needed a (require (for-syntax packrat/parse)) in there as well, otherwise the @defform/subs would not link when it occurred under a @defmodule[packrat/parse], but would link OK when it occurred under a @defmodule[packrat].