'undefined tag' when building package scribble

Questions & Answers
, ,
1

Long time, first time.

I've posted my first package('circular-layout') to pkgs.racket-lang.org, and the process was very easy -- except I get some cross-reference errors when the documentation is built by 'raco pkg install'. The documentation looks fine, except all the references to functions/structs in the module are underlined in red. By searching I've found some reports of this sort of problem in the past, but not a solution -- or at least not a solution I understand.

There are only a few structs and procedures documented in the source .rkt files, and provided out by proc-doc/names and struct*-doc like so:

(provide

(proc-doc/names make-cl-edge (->* (#:source string? #:target string?) (#:label string? #:width number? #:directed boolean?) cledge?)
                (( source  target)( [label ""]  [width 1]  [directed #t]))
                @{ An convenience constructor for a  @racket[cledge], with default width of 1, no label, and 'directed' by default (i.e., an arrow is drawn at the target end). }))

The one scribble file at 'circular-layout/scribblings/circular-layout.scrbl' references the parent module and extracts from the source file at 'circular-layout/circular-layout.rkt'

#lang scribble/manual
@(require scribble/extract)

...

@section[#:tag "reference"]{Reference}

@defmodule["circular-layout"]

@include-extracted["../circular-layout.rkt"]

The info.rkt file includes the line:

(define scribblings '(("scribblings/circular-layout.scrbl" ())))

However, installing the package gives the following warnings to all the module tags referenced by @racket[<tag>]:

raco setup: 0 running: <pkgs>/circular-layout/scribblings/circular-layout.scrbl
raco setup: WARNING: undefined tag in <pkgs>/circular-layout/scribblings/circular-layout.scrbl:
raco setup:  ((lib "circular-layout/circular-layout.rkt") cledge)
raco setup:  ((lib "circular-layout/circular-layout.rkt") make-cl-edge)
...

And in the final html all the 'undefined tags' are underlined in red.

I suspect I haven't specified the 'module-paths' properly, or need another form of require or defmodule, but can't figure out what's missing.

1 Like
2

Never used srcdoc before but I am confused by the part of your first code block that looks like @{ An convenience ...} . That doesn’t seem like correct @ syntax. Is it a typo?

Also, what is the #lang line for this .rkt file — is it #lang at-exp racket, or just #lang racket?

Even with #lang at-exp racket, if you try to do something like (define x @{foo}) you will get an error complaining that the string "foo" is not a procedure.

3

Sorry, I should have clarified that I use #lang at-exp racket for my source code, just so it is easier to write the srcdoc (i.e. the description of proc-doc/names) in Scribble.

The @{<text body>} is just syntactic sugar for ("<test body>"), but makes it clearer when embedding Scribble formatting like @itemlist[]in the text body. Can't remember where I picked that habit up.

In any case, I don't think that factors into the cross ref linking issue, but I'll try rewriting without at-exp.