On Jul 25, 2015, at 2:48 PM, Matthew Flatt <mfl...@cs.utah.edu> wrote:
> Do the broken references show up when rendering docs with `raco setup`
> or `raco pkg {install,update}`, or do they show up when running
> `scribble` directly on the ".scrbl" file?The former. > If you're seeing this behavior when using `raco setup` or `raco pkg`, > then it sounds like a bug. Using collection-based paths instead of > relative paths may be a good idea (to enable directly running > `scribble`, for example), but it shouldn't be required. Good to know. I’ve cleared out all the undefined tag warnings, but without a complete understanding of what’s going on. Some further info: The code I’m documenting is all in TR. Some of the undefined-tag warnings I saw resulted from the same identifier being imported (with for-label) from multiple modules. When I discovered the multiple-imports problem, I managed to eliminate most of the warnings, but until minutes ago I was stuck with a few yet: raco setup: 0 running: <pkgs>/jwt/net/jwt/jwt.scrbl raco setup: WARNING: undefined tag in <pkgs>/jwt/net/jwt/jwt.scrbl: raco setup: ((lib "net/jwt.rkt") decode-jwt) raco setup: ((lib "net/jwt.rkt") decode/verify) raco setup: ((lib "net/jwt.rkt") verify-jwt) raco setup: ((lib "typed/json.rkt") JSExpr) I’m ignoring the JSExpr one, since I know JSExpr is not in the Scribble docs yet. (FWIW, about a month ago I put in a pull request that would add that to the TR docs <https://github.com/racket/typed-racket/pull/155>.) Here’s the Scribble file: https://github.com/RenaissanceBug/racket-jwt/blob/master/net/jwt/jwt.scrbl Here’s the net/jwt.rkt file referenced above: https://github.com/RenaissanceBug/racket-jwt/blob/master/net/jwt.rkt It pulls in, and then re-provides, the three offending names from this file: https://github.com/RenaissanceBug/racket-jwt/blob/master/net/jwt/encode-decode.rkt I’ve checked that those names are not being required from any other module by the Scribble file. And then I happened to add this line <https://github.com/RenaissanceBug/racket-jwt/blob/master/net/jwt/jwt.scrbl#L131>, and the undefined-tag errors magically went away. Since there’s no obvious likely connection between that section header and the names being (un)defined, my best guess at what happened is that I discovered the relationship to names imported from two sources, and started adjusting my imports I made some unrelated changes to the Scribble doc I rebuilt the docs and got only the four errors I pasted above I removed the remaining double-imports I rebuilt the docs and saw no change — maybe raco setup wasn’t recompiling the .scrbl file because it hadn’t been edited? I made an unrelated change to jwt.scrbl, causing raco setup to detect jwt.scrbl had changed and do something differently The remaining errors then disappeared (And when I tried removing the section header again, the errors didn’t return.) Still, I’ve no idea what exact connection there might be to multiple imports of the same name, but AFAICT that was related. I hope this info, vague as it is, is still of some help. Best, jmj > > At Fri, 24 Jul 2015 21:56:45 -0700, Matthew Butterick wrote: >> I’ve always found that it’s more reliable to use fully-qualified package >> names with `for-label`, e.g. >> >> (require (for-label jordan/package)) >> >> rather than >> >> (require (for-label "main.rkt")) >> >> Once upon a time I had similar problems, and noticed that fully-qualified >> names is the habit used in many internal Racket packages. The reasons why >> this works are dimly remembered. I presume it has something to do with the >> fact that all Scribble docs are rendered into the main docs directory for >> your installation, thus breaking local paths that wander outside your >> 'scribblings' subdirectory. >> >> On Fri, Jul 24, 2015 at 8:58 AM, Jordan Johnson <j...@fellowhuman.com> wrote: >> >>> Hi all, >>> >>> I have a file *main.scrbl* in the same directory as a file *main.rkt*. In >>> the .scrbl file, I have >>> >>> (require (for-label "main.rkt")) >>> >>> and several *defproc* and *defstruct** forms. For some reason, one of my >>> *defstruct** forms works as expected, while all of the other *defstruct** >>> and >>> *defproc* forms produce undefined-tag warnings (when I build the docs via >>> raco setup), and compile to a red-underlined name in the resulting HTML. >>> >>> In DrRacket, mousing over the struct names in *main.scrbl*, I see a pink >>> arrow with a question mark pointing from the *for-label* line to the >>> struct name, and DrRacket correctly reports that the struct name’s binding >>> is imported from *main.rkt*. >>> >>> What might I be missing, that could be causing undefined-tag errors? >>> >>> Thanks, >>> jmj >>> >>> -- >>> You received this message because you are subscribed to the Google Groups >>> "Racket Users" group. >>> To unsubscribe from this group and stop receiving emails from it, send an >>> email to racket-users+unsubscr...@googlegroups.com. >>> For more options, visit https://groups.google.com/d/optout. >>> >> >> -- >> You received this message because you are subscribed to the Google Groups >> "Racket Users" group. >> To unsubscribe from this group and stop receiving emails from it, send an >> email to racket-users+unsubscr...@googlegroups.com. >> For more options, visit https://groups.google.com/d/optout. -- You received this message because you are subscribed to the Google Groups "Racket Users" group. To unsubscribe from this group and stop receiving emails from it, send an email to racket-users+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout.
