Scribble cross-references to user-scope libraries

[Eric Griffis]

Exports from installation-scope packages link to docs.racket-lang.org, but exports from user-scope packages link to relative paths in the local filesystem.

Given a post in scribble format:

#lang scribble/manual

Title: scribble-xrefs
Date: 2018-10-08T14:37:03
Tags: scribble, xref

@(require (for-label event markdown/parse datalog data/enumerate))

Installation links:

datalog: @racket[make-theory]

data/enumerate: @racket[enum?]

User-specific, version-specific links:

event: @racket[bind]

markdown/parse: @racket[parse-markdown]

The links produced are, in order:

http://docs.racket-lang.org/datalog/interop.html#%28def._%28%28lib._datalog%2Fmain..rkt%29._make-theory%29%29

http://docs.racket-lang.org/data/Enumerations.html#%28def._%28%28lib._data%2Fenumerate..rkt%29._enum~3f%29%29

../../../home/eric/work/racket-event-lang/doc/event-lang/index.html#%28def._%28%28lib._event%2Fmain..rkt%29._bind%29%29

../../../home/eric/work/racket-event-lang/doc/event-lang/index.html#%28def._%28%28lib._event%2Fmain..rkt%29._bind%29%29

The first two are fine. The last two should be:

http://docs.racket-lang.org/event-lang/index.html?q=bind#%28def._%28%28lib._event%2Fmain..rkt%29._bind%29%29

http://docs.racket-lang.org/markdown/index.html?q=parse-markdown#%28def._%28%28lib._markdown%2Fparse..rkt%29._parse-markdown%29%29

This appears to be a problem with how scribble interprets the --redirect-main flag. I'm opening an issue for frog anyways, because this is where I first ran into the problem and it's not yet clear if there's a one-size-fits-all solution.

[Greg Hendershott]

Matthew Flatt's message sounds to me like using --redirect instead of (or in addition to??) --redirect-main might work? Is that something you could try changing in private/read-scribble.rkt?

[Eric Griffis]

Per mflatt's advice, adding --redirect https://docs.racket-lang.org/local-redirect/ to scribble flags in frog/private/read-scribble.rkt pretty much works.

For maybe 1 second before the javascript kicks in, the Redirections page is shown with the following message:

This page is intended to redirect to the result of a search request. Since you’re reading this, it seems that the redirection did not work.

But the redirect does eventually point to the right page in docs.racket-lang.org.

The trailing slash on the --redirect URL is necessary, otherwise the browser stays on the Redirections page.

[Eric Griffis]

FTR- I left --redirect-main in place, as is.

[Eric Griffis]

For future reference, the local-redirect mechanism is described in section 12.3 of the Package Management in Racket doc.