racket - scribble/lp 文档中未解析的链接

Question

我正在尝试在 Racket 的 scribble/lp 中编写一个小示例程序。该项目的来源在 Github .

我遇到的问题是编织 html 中的链接断开。我已将其作为 gh-page. 提供为项目。

使用命令“Sribble LPexample.scrbl”输出文档时，我收到以下警告:

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")

输出文件在断开的链接下放置红色下划线。

被涂写的文件是 LPexample.scrbl。这很简单:

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

文学编程文档中提供断开链接的部分是第 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>)]

当然，我一直在研究 Racket 文档。但是，对于使用直接涂鸦/核心或涂鸦/手册交叉链接文档来说，真的没有很好的例子，更不用说涂鸦/lp了。

我也尝试过挖掘 Racket 文档的源代码，但是 Guide 和 Reference 的涂鸦文件使用了如此多的自定义函数、宏和依赖项，以至于我无法深入了解它，无法挖掘出来一个简单的“哦，原来是这样的”。

Answer 1

如果您希望源代码中的标识符自动超链接，您可能需要做两件事。

一是需要加for-label需要您希望 Scribble 识别的任何库。例如，您可能想要 (require (for-label 2htdp/image)) .见 this subsection有关更多信息的文档。

另一个是，如果您在线托管 Scribble 文档，则文档链接需要指向某个位置，并且您需要指定位置。您可以使用命令行标志来做到这一点。像这样的东西:

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

您可以使用不同的文档 URL。例如，您可以改为链接到 http://www.cs.utah.edu/plt/snapshots/current/doc/ 上的预发布快照文档。 .

有关更多详细信息，Scribble 文档中有一个关于处理交叉引用的小节: http://www.cs.utah.edu/plt/snapshots/current/doc/scribble/running.html#%28part._xref-flags%29