跳到主要内容

一个 flag,一个新读者:raco setup --doc-markdown

原石
原石

· 阅读约 5 分钟

Racket 9.3 出了,8 月 13 号的公告。我猜大部分人扫 release notes 会先看性能那条——racket/base 减少了内部模块的加载和实例化数量。那条确实值得看,启动路径上的东西,砍一个模块是一个模块。

但我来回读了三遍的,是这一行:

raco setup 增加了 --doc-markdown 选项

就一个命令行 flag。生成 Markdown 格式的文档。

为什么一个 flag 值得写一篇

先交代背景,一段讲完。Racket 的文档系统是 Scribble,源文件 .scrbl,渲染出来是 HTML,带交叉引用、带索引、带搜索。这套东西做文档是真好,我见过的大多数语言文档在它面前都显得寒碜。问题不在质量,在出口:输出绑死在它自己的渲染管线里。

你要把一段 Racket 文档塞进一个普通 Markdown 仓库——给内部工具写个 README,或者喂给一个只吃 Markdown 的东西——以前的路很别扭。要么手抄一遍,然后两份开始漂移;要么写脚本从 HTML 里刮。两条路我都走过,都不想再走。

--doc-markdown 把这条路铺平了。一个 flag,输出换格式。

有人会说,加个导出格式而已,值得单独立论?我觉得值得。因为这类改动背后有一个判断:承认文档要有第二个消费者。文档不只是给人开浏览器看的,它还要被 diff、被 grep、被塞进 context window。一个只往 HTML 一条路上走的文档系统,等于默认了文档只有一个用途。这个假设十年前成立,现在不成立了。

说句题外话——LLM 吃 Markdown 这件事,正在悄悄改一堆工具的输出格式优先级。以前是“HTML 是给人看的,别的格式是衍生物”;现在 Markdown 自己成了第一等公民,因为它同时是给人看的和给模型看的。Racket 这种老牌社区能在这个版本把这个 flag 落下来,我猜是嗅到了这件事。也可能就是有人自己烦了想 grep 文档。动机不重要,方向对了。

顺手批一个反方向

反方向的方案我也见过:在文档系统之上再封一层“文档中台”,统一管理多格式输出,接一堆渲染后端,卖点是“任何源格式、任何目标格式”。听起来很强。

实际后果是:你为了写一份函数文档,得先理解一整个渲染抽象。源文件里开始出现条件编译式的标记——这段只在 HTML 输出,那段只在 PDF 输出。半年后没人记得哪段去哪了。文档和代码一样烂掉,但代码有测试兜底,文档没有。

他们想要的:  源文件 → 抽象层 → 后端A/后端B/后端C → 各自的输出
一个 flag:   源文件 → 渲染 → 输出格式

一个 flag 解决的事,别上框架。抽象税不因为收税对象是文档就变便宜。

这个版本里另外几刀

挑着说,不铺开。

DrRacket 的后台扩展过程现在禁用错误跟踪注解,语法检查变快。这种改动不起眼——不是加功能,是把一个“为了标错误位置而付出的代价”在不需要的时候砍掉。砍掉不需要的代价,比加新功能难,因为没人会为“变快了”写博客吹自己。但每个开着 DrRacket 教课的人每天都受益。

file/zip 支持内存中的文件源和单文件压缩控制。贴段伪调用感受一下:

(zip "out.zip"
     (list "a.txt" "b.txt")
     #:system 'unix)

具体参数我不逐个背了,公告里有。关键是“内存中的源”——你可以从字节流直接打 zip,不用先落盘。这种 API 的判据很简单:它有没有逼你为了用它而多干一件事。没有,就是好 API。

还有 (tcp-listen 0) 遇到 "address in use" 会自动重试。一行行为改动,救的是每一个写“帮我随便找个端口”的脚本。以前这种脚本是概率性失败的,现在不是了。概率性失败最讨人厌——它让你怀疑人生而不是怀疑代码。

ffi/unsafe 里那个 define-runtime-lib,定位相对于源文件的库文件,思路和 define-runtime-path 对齐。FFI 我最近没怎么碰,这条只记一笔,不装懂。

一处我持保留意见的

教学语言(BSL、ISL 那些)在语言对话框里和版本对齐,并成为推荐方式。我理解动机——教学生的时候环境一致性值钱,学生机器上跑的东西和教材对不上,一节课就毁在排环境上。

但“推荐使用的方式”这个措辞让我警惕。工具链开始替你做推荐,下一步往往就是推荐变默认,默认变唯一。教学语言的价值恰恰在它砍掉了东西——没有 lambda 的 BSL 是故意的残缺。残缺是好东西,别让“对齐版本”顺手把残缺补齐了。这个担心可能多余,先立此存照。

9.3 是个不大的版本。没有大新闻,一堆小刀,每刀都砍在具体的地方——一个 flag、一次重试、一份少加载的模块。

我越来越喜欢这种版本。大版本发布像开业庆典,锣鼓一响,复杂度进场;小版本像老师傅磨刀,一下一下,听不见响,上手就知道快了。这个版本里我最看好的还是 --doc-markdown:文档的读者名单上多了一个不吃 HTML 的读者,而 Racket 是用一行命令行选项承认的这件事——不是用一个新子系统。

一行,就是它该有的体量。

原石
原石

把代码当文章写的系统工程师,以源码立论、单线程式拒绝复杂度。

查看主页 →