# 为什么做 Crib

> 放在手边的手册应该离线、分版本、中英文对得上，还能记下自己的结论。

---

LLMS 索引： [llms.txt](/llms.txt)

---

PostgreSQL 的手册写得好，但查起来常常不顺手。Crib 想解决的是几个反复出现的小麻烦，而不是再做一个文档网站。

## 版本要对得上 {#versions}

线上跑着 9.6、12、14 的人很多。搜索引擎给的往往是最新版的页面，参数默认值、视图的列、函数的签名都可能已经变了。
要查旧版本，就得记住 URL 规则，或者翻到页面角落去切换。

Crib 收录 6.3 到 20devel 共 31 条版本线，每条固定到一个确切的内容版本。搜索时在前面写上 `PG96:`，
结果就只来自 9.6 的手册和 Wiki；同一个概念在多个版本里出现时，结果折叠成一组，展开就能逐版对比。
`pg18` 这样的别名总是解析到一个确切的发布，比如 18.6；目标版本没装，就直接说没装，不拿 18.4 冒充。

## 中英文要对得上 {#bilingual}

中文手册降低了阅读门槛，但译文总有拿不准的地方，这时需要看英文原文的同一段。
在两个网站之间来回翻目录，十几秒就过去了，思路也断了。

Crib 把每条版本线的中英文手册打成一个双语包，构建时从手册源码里找出两种语言共同的章节标识，
只有两边都能唯一确定时才建立对应。阅读时一键切到另一种语言的同一节，或者两栏并排对照。
62 套手册之间有 77,580 对这样的章节对应；没有对应的地方，就回到父节并告诉你，不靠标题去猜。

## 断网也要能用 {#offline}

机房、内网、飞机上，在线文档打不开，下载的 PDF 又没法跨版本搜。Crib 的手册、Wiki 和搜索索引都随应用安装，
第一次打开就能断网阅读和搜索，不需要先下载、先建索引。完整离线版随附全部内容；Core 版只带 18.6，
其余版本需要时再从签名目录下载，下载、校验和重建索引都在后台完成，验证通过才切换。

## 符号和中文都要搜得到 {#search}

`->>`、`@@`、`\dC`、`23505` 这类写法是 PostgreSQL 用户最常查的东西，也是通用搜索最容易丢掉的东西。
中文又没有空格分词，“锁”“索引”这样的短词很难搜准。Crib 先按精确名称查，再搜正文；中文按双字切分，
单个汉字走名称索引。细节见[另一篇文章](/blog/post/search/)。

## 自己的结论要留得住 {#notes}

排障时查到的结论、发现的译文问题，记在别处很快就和原文脱节了。Crib 的笔记、书签和本地更正挂在具体章节上，
存在独立的个人资料库里，官方原文不动。内容更新后，笔记按原来的锚点重新定位，找不到就列出来等你处理；本地更正则暂停显示，列入“待重新定位”。
所有个人资料都可以导出成 Markdown 加 JSON。

## 为什么是原生 macOS 应用 {#native}

需要的是原生窗口和标签页、系统服务菜单、可靠的输入法处理和键盘操作，以及不依赖本地 HTTP 服务的离线阅读。
所以界面用 SwiftUI 和少量 AppKit，正文用 WKWebView 通过受限的内部地址读取资料包，搜索用 SQLite FTS5。
构建端用 Go 生产和验证资料包，两边共用同一套格式合同和测试样例。

## 现在到哪一步了 {#status}

功能已经实现，正在做最终候选的验收、许可核对和正式签名的准备，还没有公开安装包。
进展会写在[开发日志](/blog/devlog/)，当前清单见[发布状态](/docs/intro/status/)。