From 150de96b649701824fa98ba7facf93e0b0923d46 Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Mon, 8 Oct 2018 19:14:28 -0600 Subject: [PATCH] update docs with a working URL for `--redirect` --- scribble-doc/scribblings/scribble/renderer.scrbl | 4 +++- scribble-doc/scribblings/scribble/running.scrbl | 14 ++++++++------ 2 files changed, 11 insertions(+), 7 deletions(-) diff --git a/scribble-doc/scribblings/scribble/renderer.scrbl b/scribble-doc/scribblings/scribble/renderer.scrbl index 45e5613d..ce7241fd 100644 --- a/scribble-doc/scribblings/scribble/renderer.scrbl +++ b/scribble-doc/scribblings/scribble/renderer.scrbl @@ -3,7 +3,8 @@ "utils.rkt" (for-label racket/class scribble/render - scribble/xref)) + scribble/xref + setup/dirs)) @(define-syntax-rule (defmodule/local lib . content) (begin @@ -354,6 +355,7 @@ Configures the renderer to redirect links to external documents via @racket[url], adding a @tt{tag} query element to the end of the URL that contains the Base64-encoded, @racket[print]ed, serialized original tag (in the sense of @racket[link-element]) for the link. +The result of @racket[get-doc-search-url] is intended for use as @racket[url]. If the link is based on a cross-reference entry that has a document-identifying string (see @racket[load-xref] and its diff --git a/scribble-doc/scribblings/scribble/running.scrbl b/scribble-doc/scribblings/scribble/running.scrbl index 2817394c..cf47d16c 100644 --- a/scribble-doc/scribblings/scribble/running.scrbl +++ b/scribble-doc/scribblings/scribble/running.scrbl @@ -148,7 +148,7 @@ information for all installed documentation, and @PFlag{m} or setup/xref load-collections-xref}. The @DFlag{redirect-main} flag for HTML output redirects links to the local -installation's documentation to a given URL, such as +installation's documentation (not user-scope documentation) to a given URL, such as @tt{http://docs.racket-lang.org/}. Beware that documentation links sometimes change (although Scribble generates HTML paths and anchors in a relatively stable way), so @@ -156,11 +156,13 @@ in a relatively stable way), so more reliable when building with an installation for @italic{version}. The @DFlag{redirect-main} flag is ignored for non-HTML output. -The @DFlag{redirect} flag is like @DFlag{redirect-main}, except -that it builds on the given URL to indicate a cross-reference tag that -is more stable than an HTML path and anchor (in case the documentation -for a function changes sections, for example). No server currently -exists to serve such tag requests, however. +The @DFlag{redirect} flag is like @DFlag{redirect-main}, except that +it builds on the given URL to indicate a cross-reference tag that is +more stable than an HTML path and anchor (in case the documentation +for a function changes sections, for example), and it can generate +redirected linked for documentation that is installed in user scope. +The URL @tt{https://docs.racket-lang.org/local-redirect/index.html} can +work for these redirections. For cross-references among documentation that is not part of the Racket installation, use @DFlag{info-out} to save information from a