# Scribble/srcdoc's for-doc with submod issue

**URL:** <https://racket.discourse.group/t/scribble-srcdocs-for-doc-with-submod-issue/459>\
**Category:** Questions & Answers\
**Created:** [December 21, 2021, 11:18am UTC](https://racket.discourse.group/t/scribble-srcdocs-for-doc-with-submod-issue/459 "2021-12-21T11:18:58Z")\
**Posts on this page:** 2\
**Page:** 1

<div class="post-metadata">

**Author:** ![dominik.pantucek](https://yyz2.discourse-cdn.com/free1/user_avatar/racket.discourse.group/dominik.pantucek/32/144_2.png) [@dominik.pantucek](https://racket.discourse.group/u/dominik.pantucek)\
**Post date:** [December 21, 2021, 11:18am UTC](https://racket.discourse.group/t/scribble-srcdocs-for-doc-with-submod-issue/459/1 "2021-12-21T11:18:59Z")

</div>

Using scribble/srcdoc with at-exp reader allows you to write module documentation within the provide form ensuring all the provided symbols are somehow (preferably properly) documented. In certain situations, you want to include the actual values of the symbols you provide or values used for computation when the symbol is a procedure or syntax form. I use this approach in uni-table documentation[1] to make sure the documentation lists all valid color names and other things as they are used in the module itself.

Here's a minimal example of a module `for-doc-test1.rkt` using scribble/srcdoc for providing the documentation of provided procedure:

```scheme
#lang at-exp racket/base

(require scribble/srcdoc
         (for-doc scribble/manual
                  racket/base
                  (submod ".." my-constants)
                  )
         racket/contract)

(provide
 (proc-doc
  return-a-number
  (-> number?)
  @{

    Returns @racket[a-number]: @racket[#,a-number].

    }))

(module my-constants racket/base
  (provide a-number)
  (define a-number 1) )

(require 'my-constants)

(define (return-a-number)
  a-number)

```

In order to render the documentation, a small `for-doc-test1.scrbl` file may read:

```scheme
#lang scribble/manual

@require[scribble/extract]

@title{for-doc test 1}

@defmodule[for-doc-test1]
@include-extracted["for-doc-test1.rkt"]

```

Creating the documentation is then just a matter of running `scribble for-doc-test1.scrbl` and it generates a nice HTML documentation which properly states "Returns a-number: 1." in the procedure description.  
If you use this module in a program it works like charm. Take the following ```for-doc-test1-usage.rkt" as an example:

```scheme
#lang at-exp racket/base

(require "for-doc-test1.rkt")

(define (test-a-number)
  (displayln (return-a-number)))

(module+ main
  (test-a-number))

```

This program can be run using `racket for-doc-test1-usage.rkt`, it can be compiled using `raco make for-doc-test1-usage.rkt` and no problems show up.  
However if the usage program is a module that is intended to be used elsewhere and scribble/srcdoc provides are present, something strange happens. The updated usage example is as follows:

```scheme
#lang at-exp racket/base

(require scribble/srcdoc
         (for-doc scribble/manual
                  racket/base)
         "for-doc-test1.rkt"
         racket/contract)

(provide
 (proc-doc
  test-a-number
  (-> void?)
  @{

    Prints a-number.

    }))

(define (test-a-number)
  (displayln (return-a-number)))

(module+ main
  (test-a-number))

```

Trying to run this program yields:

```scheme
car: contract violation
  expected: pair?
  given: #<path:/home/joe/Projects/Programming/uni-table/for-doc/..>
  context...:
   /usr/share/racket/collects/racket/require-transform.rkt:190:2: convert-relative-module-path
   /usr/share/racket/collects/racket/private/reqprov.rkt:72:2: check-lib-form
   /usr/share/racket/collects/racket/private/reqprov.rkt:80:13: t
   /usr/share/racket/collects/racket/require-transform.rkt:266:2: expand-import
   /usr/share/racket/collects/racket/private/reqprov.rkt:607:22
   /usr/share/racket/collects/racket/private/reqprov.rkt:603:5
   /usr/share/racket/collects/racket/require-transform.rkt:266:2: expand-import
   [repeats 1 more time]
   /usr/share/racket/collects/racket/private/reqprov.rkt:285:21: try-next
   /usr/share/racket/collects/racket/private/reqprov.rkt:256:2
   /usr/share/racket/collects/syntax/wrap-modbeg.rkt:46:4

```

Of course, trying to compile it produces the same result. I found a rather simple workaround, just remove the submod from the for-doc form and use begin-for-doc. The updated module then looks like this:

```scheme
#lang at-exp racket/base

(require scribble/srcdoc
         (for-doc scribble/manual
                  racket/base)
         racket/contract)

(begin-for-doc
  (require (submod ".." my-constants)))

(provide
 (proc-doc
  return-a-number
  (-> number?)
  @{

    Returns @racket[a-number]: @racket[#,a-number].

    }))

(module my-constants racket/base
  (provide a-number)
  (define a-number 1))

(require 'my-constants)

(define (return-a-number)
  a-number)

```

Now it compiles and runs fine - that's what I actually used in affected module of uni-table[2].

The question is: is there something missing in my understanding of how require subforms (for-doc especially) work or is it a bug in Racket?

[1] [https://docs.racket-lang.org/uni-table/Styles.html#(part.\_.S.G.R\_.Styles)](https://docs.racket-lang.org/uni-table/Styles.html#%28part._.S.G.R_.Styles%29)  
[2] [https://gitlab.com/racketeer/uni-table/-/blob/master/private/sgr-style.rkt](https://gitlab.com/racketeer/uni-table/-/blob/master/private/sgr-style.rkt)

---

<div class="post-metadata">

**Author:** ![mflatt](https://yyz2.discourse-cdn.com/free1/user_avatar/racket.discourse.group/mflatt/32/6_2.png) [@mflatt](https://racket.discourse.group/u/mflatt)\
**Post date:** [December 23, 2021, 5:35pm UTC](https://racket.discourse.group/t/scribble-srcdocs-for-doc-with-submod-issue/459/2 "2021-12-23T17:35:33Z")

</div>

There are two layers of bugs here: problems with `relative-in`, and a problem with the `relative-in` that `for-doc` eventually builds. I'll push repairs for both.