racket / racket/scribble

Re-provided identifiers are not tracked across submodules

Open
#44 0 comments 0 reactions 0 assignees View on GitHub

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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.