Unresolved Links in scribble/lp document

Question

I'm trying to write a small example program in Racket's scribble/lp. The source for the project is on Github.

The problem I am experiencing is broken links in the woven html. I've provided it as a gh-page. for the project.

When outputting the document using the command 'Sribble LPexample.scrbl' I get the following warning:

2013 blog > scribble LPexample.scrbl
 [Output to LPexample.html]
Warning: some cross references may be broken due to undefined tags:
 (dep ((lib "2htdp/image.rkt") ellipse))
 (mod-path "racket")
 (dep ((lib "2htdp/image.rkt") beside/align))
 (dep ((lib "2htdp/image.rkt") rectangle))
 (mod-path "scribble/lp")

And the output file places red underlines under the broken links.

The file which gets scribbled is LPexample.scrbl. It's pretty simple:

#lang scribble/manual
@require[scribble/lp-include]
@title{Literate Programming Example}
// snip
@lp-include["LPexample.rkt"]

The section of the literate programming document that sources the broken links is lines 69-86:

which weaves to this:

@chunk[<blue_square>
       (rectangle 100 100 "solid" "blue")]

can be composed into other functions this way:
@verbatim|{
@chunk[<blue_square>
(beside/align "bottom"
              (ellipse 20 70 "solid" "lightsteelblue")
              <blue_square>)]}|

which weaves out to:

    @chunk[<example_body>
    (beside/align "bottom"
                  (ellipse 20 70 "solid" "lightsteelblue")
                  <blue_square>)]

I've been digging through the Racket documentation, of course. But there's really no good example for even cross linking documents using straight scribble/core or scribble/manual, never mind scribble/lp.

I've also tried digging through the source for the Racket documentation, but the scribble files for the the Guide and Reference use so many custom functions and macros and dependencies that I just can't get my brain far enough around it, to dig out a simple "Oh so that's how it's done".

Answer 1

If you want to have the identifiers from your source code automatically hyper-linked, you likely need to do two things.

One is that you need to add for-label requires for any libraries that you want Scribble to recognize. For example, you probably want (require (for-label 2htdp/image)). See this subsection of the docs for more on that.

The other is that if you're hosting the Scribble documents online the documentation links need to point somewhere, and you need to specify where. You can do that with a command-line flag. Something like this:

scribble --html +m --redirect-main http://docs.racket-lang.org/ document.scrbl

You can use different documentation URLs. For example, you might instead link to the pre-release snapshot documentation at http://www.cs.utah.edu/plt/snapshots/current/doc/.

---

For more details, there is a subsection of the Scribble documentation about handling cross-references: http://www.cs.utah.edu/plt/snapshots/current/doc/scribble/running.html#%28part._xref-flags%29