tldr 仓库中的 dnf deplist 别名页：从阿拉伯语文档看 tldr 别名页面机制

本篇技术指南以 tldr 仓库中的 dnf-deplist.md 为切入点，讲解 tldr 项目中"别名页面"（alias pages）的设计理念、阿拉伯语翻译模板、底层自动化脚本与配套的 PR 校验机制。读完本文，你将理解 tldr 如何用一行命令的页面优雅解决"命令别名"的文档冗余问题，并掌握别名页从编写、同步到质量检查的完整链路。

一、为什么要为别名命令单独建页

在 Linux 生态中，很多命令只是另一个命令的"马甲"。例如 Fedora/RHEL 系发行版中，dnf deplist 本质上就是 dnf repoquery --deplist 的一个快捷别名。如果为这类别名复制一份完整的命令文档，会带来两个问题：

• 内容重复：同一命令的功能说明、示例会在多个页面里反复出现，维护时极易产生不一致；
• 维护成本高：原命令的行为一旦变化，所有别名页都必须同步更新。

tldr 项目给出的解法是别名页面：不重复撰写功能文档，而是建一个极简页面，明确指出"本命令是 XX 的别名"，并给出 tldr XX 的跳转指引，把读者引导到原命令的完整文档。仓库中的 dnf-deplist.md 正是这一设计的阿拉伯语示例，其英文母版位于 pages/linux/dnf-deplist.md。

二、逐行解读阿拉伯语别名页 dnf-deplist.md

完整内容只有三部分：

# dnf deplist

> هذا الأمر هو اسم مستعار لـ `dnf repoquery --deplist`.

- إعرض التوثيقات للأمر الأصلي:

`tldr dnf repoquery`

对照英文母版 pages/linux/dnf-deplist.md：

# dnf deplist

> This command is an alias of `dnf repoquery --deplist`.

- View documentation for the original command:

`tldr dnf repoquery`

可以拆解出别名页的四个标准要素：

1. H1 标题：# dnf deplist，必须与文件名（dnf-deplist.md）指向的命令完全一致。样式指南特别强调：页面文件名一律小写，而标题可以保持命令的真实大小写（style-guide.ar.md 中"يجب أن يتطابق اسم ملف الصفحة والعنوان مع اسم الأمر تمامًا"一节即对此作了规定）；
2. 描述行：以 > 开头，声明"此命令是 dnf repoquery --deplist 的别名"，阿拉伯语描述行明确指认了原始命令；
3. 示例描述：一行祈使句"إعرض التوثيقات للأمر الأصلي"（查看原命令的文档）；
4. 命令体：tldr dnf repoquery，即调用 tldr 客户端查看原命令文档的命令。

被指认的"原命令"页面是 pages/linux/dnf-repoquery.md，它才是真正的功能文档所在——查询软件包的依赖信息，其中 --deplist 选项正是列出包依赖清单的用法：

`dnf {{[rq|repoquery]}} --deplist {{package}}`

由此可见，别名页与原命令页互为表里：别名页负责"指路"，原命令页负责"答疑"。

三、别名页的翻译模板体系

阿拉伯语别名页并非手工随意编写，而是严格遵循社区定义的翻译模板。仓库的 alias-pages.md 集中维护了 40 余种语言的别名页模板，其中阿拉伯语模板为：

# example

> هذا الأمر هو اسم مستعار لـ `example`.

- إعرض التوثيقات للأمر الأصلي:

`tldr example`

对比 dnf-deplist.md 的实际内容可以看到，页面正是把模板中的三个 example 占位符依次替换为 dnf deplist、dnf repoquery --deplist 和 dnf repoquery 的结果。这正是自动化脚本工作的核心逻辑（详见下一节）。

模板化翻译有几个直接好处：

• 多语言一致性：所有语言版本结构、示例数量完全对齐，不会出现"某个语言的页面多一个示例"的漂移；
• 便于批量生成：脚本可以精确识别模板占位符并替换，实现跨语言同步；
• 便于机器校验：PR 检查脚本可以对比模板，检测出不符合规范的别名页。

四、源码级的别名页生成与同步机制

tldr 仓库不仅定义了模板，还提供了完整的自动化工具链。核心脚本是 scripts/set-alias-page.py，其工作原理与 dnf-deplist.md 这类页面直接相关：

4.1 占位符替换生成页面

脚本核心函数 generate_alias_page_content 会从模板文件中读取对应语言的模板文本，并依序完成三次替换（set-alias-page.py）：

1. 第一次替换把模板标题行的 example 换成别名命令名（如 dnf deplist）；
2. 第二次替换把描述行 `example` 换成原始命令（如 dnf repoquery --deplist）；
3. 第三次替换把命令行的 example 换成文档跳转命令（如 dnf repoquery）。

之所以按顺序替换，是因为模板中三处 example 位置不同，脚本利用第一次替换后字符串中 example 的剩余位置来完成后续替换。

4.2 支持两种工作模式

脚本提供两种使用方式（set-alias-page.py）：

• 交互式创建（-p）：针对单个页面启动向导，逐项询问标题、原始命令、文档跳转命令，并预览将要生成的页面后确认写入。例如新增 osx/gsum 这类别名页时可运行 python3 scripts/set-alias-page.py -p linux/dnf-deplist；
• 批量同步（-S）：扫描英文 pages/ 目录下所有别名页，把每个别名页同步到所有语言目录（pages.ar/、pages.fr/、pages.zh/ 等）中已存在的对应页面。只同步单语言时可配合 -l 参数，例如 python3 scripts/set-alias-page.py -S -l ar。

此外还有 -n（dry-run 预览变更）、-s（将修改 git add 暂存）、-i（非精确模板匹配）等选项。get_alias_command_in_page 函数则会反向解析已有页面：读取标题、从描述行提取原始命令、从 tldr ... 行提取文档命令，用于判断某页面是否已是标准别名页（set-alias-page.py）。

4.3 语言目录的自动识别

同步时脚本通过 _common.py 中的 get_locale 函数，从路径推断语言代码：pages.ar/ 这类带后缀目录解析出 ar，不带后缀的 pages/ 则视为英文 en（_common.py）。get_templates 函数则负责解析 alias-pages.md 模板文件中各语言标记（### ar、### en 等）下的 markdown 片段（_common.py），而 get_pages_dirs 会收集根目录下所有以 pages 开头且非符号链接的目录作为同步目标。

五、别名页的自动化质量保障

别名页虽小，同样受到 PR 阶段的严格检查：

5.1 tldr-lint 静态检查

每个 PR 都会运行 npx tldr-lint（test-tldr-lint.sh）。对不同语言会启用不同的检查项组合：阿拉伯语（*ar*）等语言除默认的 TLDR104 外，还会额外启用 TLDR003、TLDR004、TLDR015 等检查；英文则不加任何忽略项、全量检查。这些规则确保页面标题、描述行、示例数量等符合模板规范。

5.2 check-pr.sh 的多维校验

check-pr.sh 在 PR 上执行更细粒度的检查（该脚本明确要求必须从仓库根目录运行），与别名页相关的主要有：

• 缺失英文母版检查（check_missing_english_page）：翻译页必须存在对应的英文页面，pages.ar/linux/dnf-deplist.md 对应英文 pages/linux/dnf-deplist.md，若英文页缺失会被标记；
• 过时检测（check_outdated_page）：对比翻译页与英文页的命令行数、命令内容（经 strip_commands 归一化处理占位符后比较）以及 > 描述行数，任何不一致都会提示页面过时；
• 复制页检测：通过 git diff --find-copies-harder 检测"直接 cp 出来的页面"。

这套机制保证了翻译别名页始终与英文母版同步演化，不会因为语言版本差异而失真。

5.3 手动验证方式

贡献者在本地即可用社区维护的 linter 自检（参见 style-guide.ar.md）：

npm install --global tldr-lint
tldr-lint path/to/tldr_page.md

也可借助 tldr 客户端的渲染预览：

tldr --render path/to/tldr_page.md

六、把别名页放在哪个平台目录

dnf-deplist.md 位于 pages.ar/linux/，而不是 pages.ar/common/。这是因为 dnf 是 Fedora/RHEL 系的包管理器，命令行为与具体发行版平台强相关，属于 Linux 平台专属命令。对应地，英文母版也存放在 pages/linux/dnf-deplist.md。

tldr 的客户端会根据用户的操作系统自动选择最合适的页面版本：Windows 用户看到 pages.ar/windows/ 下的版本，Linux/macOS 用户看到 pages.ar/linux/ 或 pages.ar/common/ 下的通用版本（style-guide.ar.md 的"اختلافات المنصات"一节对此有明确说明）。因此，判断一个命令是否应该建别名页，以及建在哪个平台目录，需要先确认该命令的平台归属。

七、从一页到一体系：别名页的设计思想总结

回到 dnf deplist 这个例子，可以提炼出 tldr 别名页面机制的完整闭环：

1. 识别：dnf deplist 是 dnf repoquery --deplist 的别名，无需重复文档；
2. 建页：遵循 alias-pages.md 模板，创建仅含"指路信息"的极简页面；
3. 翻译：各语言维护者按各自语言模板同步翻译，内容结构完全对齐；
4. 自动化：set-alias-page.py 可批量生成、同步全部语言的别名页；
5. 质控：tldr-lint 与 check-pr.sh 在 PR 阶段自动拦截格式不符、与英文母版不同步的页面。

这一机制的价值在于：用户用 tldr dnf deplist 查询时，能够迅速获得"这是别名，原命令见 dnf repoquery"的准确指引，而不是被重复文档淹没；维护者则只需维护原命令一份完整文档，从根源上避免了多页面内容漂移。