Re-provided identifiers are not tracked across submodules
Nobody has claimed this yet.
- Dominant language
- Racket
- Stars
- 250
- Forks
- 102
- Avg merge
- 11d 11h
- Merged PRs (30d)
- 1
Description
When a library requires and re-provides an identifier without modification, it is normally linked back to the original in documentation for files that require the library for-label. This behaviour is however broken when the chain of require and re-provide is going through a submodule. To test this, install the following package (I guessed the issue number wrong when naming the github repo…):
raco pkg install https://github.com/jsmaniac/example-bug-track-submodule-issue43.git#40c26708c8bec0041a1df444775d6f55161b9e5a
The package consists of three files:
other.rkt:
#lang racket/base
(module m racket/base
(require syntax/stx)
(provide (all-from-out syntax/stx)))
main.rkt:
#lang racket/base
(require (submod "other.rkt" m))
(provide (all-from-out (submod "other.rkt" m)))
scribblings/example-bug-track-submodule.scrbl:
#lang scribble/manual
@(require (for-label example-bug-track-submodule
racket/base))
@title{example-bug-track-submodule}
@author{georges}
@defmodule[example-bug-track-submodule]
The @racket[stx-map] function is re-provided from @racketmodname[syntax/stx].
On the last line of the scribble file, the @racket[stx-map] is not linked to the syntax/stx library's documentation, and causes the following warning:
raco: --- building documentation ---
raco: 1 running: <pkgs>/example-bug-track-submodule/scribblings/example-bug-track-submodule.scrbl
raco: WARNING: undefined tag in <pkgs>/example-bug-track-submodule/scribblings/example-bug-track-submodule.scrbl:
raco: ((lib "example-bug-track-submodule/main.rkt") stx-map)
If the code in other.rkt is moved out of the submodule, and main.rkt is adjusted accordingly, then the warning disappears and the @racket[stx-map] becomes a link to the syntax/stx library's documentation. This can be tested using the without-submod branch of that package:
raco pkg remove example-bug-track-submodule-issue43
raco pkg install https://github.com/jsmaniac/example-bug-track-submodule-issue43.git#9747adce0f66bf2a60b58f86b51a0d39c24c0d4b
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Install the example-bug-track-submodule package at the supplied commit and run the documented raco documentation build to reproduce the undefined-tag warning. Start by tracing how the require/provide chain through other.rkt's submodule and main.rkt is handled for documentation links. Done means stx-map links to syntax/stx without the warning, while the without-submod comparison remains working.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100