企业官网建设流程全解析

• 文档
• 教程
• 知识库

tldr 是一个由社区协作维护的命令行速查手册仓库，当某个命令只是另一个命令的别名时，仓库并不重复撰写完整文档，而是创建一种轻量的"别名页面"（alias page），直接指引用户查看原始命令的文档。本文以 pages.ar/linux/compose.md 这份阿拉伯语别名页面为切入点，完整解读它的文档结构、它指向的原命令run-mailcap --action=compose的实际用途，以及 tldr 仓库中别名页面从模板规范、翻译模板到客户端解析、自动化校验的完整技术链路。

一、别名页面文档本体：结构与含义

pages.ar/linux/compose.md是compose命令在 Linux 平台下的阿拉伯语 tldr 页面，全文只有标题、说明行和一条示例，结构如下：

# compose > هذا الأمر هو اسم مستعار لـ `run-mailcap --action=compose`. - إعرض التوثيقات للأمر الأصلي: `tldr run-mailcap`

逐行解读其技术含义：

• # compose：页面标题，必须与文件名一致（该约定由仓库脚本强制校验，详见下文"文件名一致性检查"一节）。
• > هذا الأمر هو اسم مستعار لـ \run-mailcap --action=compose`.：说明行，阿拉伯语，翻译为"This command is an alias ofrun-mailcap --action=compose."，即compose只是run-mailcap --action=compose` 的别名。
• - إعرض التوثيقات للأمر الأصلي:：示例的描述行，阿拉伯语，意为"查看原命令的文档"。
• `tldr run-mailcap`：示例的命令行，告诉用户用tldr run-mailcap去查阅真正命令的速查页。

这一结构并非阿拉伯语版本独有，它在英文主仓库 pages/linux/compose.md 中完全对应：

# compose > This command is an alias of `run-mailcap --action=compose`. - View documentation for the original command: `tldr run-mailcap`

也就是说，阿拉伯语页面是英文页面的忠实翻译，除第二行的说明句与示例描述被翻译为阿拉伯语外，页面骨架、命令名与参数全部保持一致。compose页面同时存在于英文主目录与阿拉伯语翻译目录，这与 tldr 的多语言页面组织方式有关（详见下文"客户端如何解析页面"）。

二、原命令run-mailcap：compose 别名的真实指向

要真正理解compose别名的用途，需要看它指向的原命令文档 pages/linux/run-mailcap.md。该页面说明run-mailcap的作用是"通过 mailcap 文件中的条目执行程序"（Execute programs via entries in the mailcap file），即它依据系统mailcap配置，为不同 MIME 类型的文件分配合适的处理程序。

--action=compose只是run-mailcap支持的多种动作之一，原命令页面完整列出了其余动作，全部围绕"用 mailcap 中登记的工具对文件执行某种操作"：

• 编辑已有文件或新建文件：run-mailcap --action=compose {{path/to/file}}，这正是compose别名所指向的默认编辑工具调用。
• 查看文件：run-mailcap --action=edit {{path/to/file}}。
• 打印文件：run-mailcap --action=print {{path/to/file}}。
• 预览文件（通常用于图片）：run-mailcap --action=view {{path/to/file}}。
• 指定任意动作：run-mailcap --action={{view|cat|compose|composetyped|edit|print}} {{path/to/file}}，可选动作包括view、cat、compose、composetyped、edit、print。
• 开启额外信息输出：run-mailcap --action={{action}} --debug {{path/to/file}}。
• 忽略 copiousoutput 指令并直接输出到 stdout：run-mailcap --action={{action}} --nopager {{path/to/file}}。
• 只显示将执行的命令而不真正执行：run-mailcap --action={{action}} --norun {{path/to/file}}。

由此可见，compose别名在 Linux 桌面/命令行环境中用于"以系统 mailcap 登记的默认编辑器撰写或编辑文件"，而 tldr 的别名页面做法是把这条命令的完整能力统一收敛到原命令run-mailcap的页面中，避免重复维护两份内容。

三、别名页面的仓库级规范：何时创建、如何书写

tldr 对"什么时候该建别名页、怎么建"有明确的书写规范，记录在 contributing-guides/style-guide.md 的 "Aliases" 一节。

规范的核心规则是：如果一个命令可以用其他名字调用（例如vim可以写作vi），就可以创建别名页面，将用户引导到原始命令名。其推荐模板为：

# command_name > This command is an alias of `original-command-name`. - View documentation for the original command: `tldr original_command_name`

规范给出的实例是vi页面：

# vi > This command is an alias of `vim`. - View documentation for the original command: `tldr vim`

对照可见，pages/linux/compose.md及其阿拉伯语版本正是完全按照此模板撰写的：标题行写别名命令名，第二行说明其真实身份，示例则调用tldr <原命令名>。之所以示例使用tldr run-mailcap而非直接给出run-mailcap --action=compose的完整用法，正是为了让别名页面保持极简，所有参数细节只维护在原命令页面中。

除了标准别名，style-guide.md 还专门规定了 PowerShell 命令别名的三种处理情形（替换 cmd 命令的别名、仅在 PowerShell 中生效的新别名、与其他程序冲突的别名），但compose属于 Linux 平台的标准别名，不涉及这些特例。

四、翻译模板：阿拉伯语别名页面的来源

为了让所有语言保持一致，tldr 在 contributing-guides/translation-templates/alias-pages.md 中维护了所有语言的别名页面翻译模板。该文件为每种语言提供一份可直接套用的占位模板（# example+ 别名说明 + 查看原命令示例），其中阿拉伯语（### ar）模板为：

# example > هذا الأمر هو اسم مستعار لـ `example`. - إعرض التوثيقات للأمر الأصلي: `tldr example`

将模板中的example替换为run-mailcap --action=compose与run-mailcap，就得到pages.ar/linux/compose.md的正文——这正是阿拉伯语别名页面的直接生成依据。该文件同时收录了 en、ar、bg、bn、bs、ca、cs、da、de、el、es、fa、fi、fr、hi、id、it、ja、ko、lo、ml、nb、ne、nl、no、pl、pt_BR、pt_PT、ro、ru、si、sr、sv、sw、ta、th、tr、uk、uz、zh、zh_TW 共 40 余种语言的模板，是翻译别名词条时的一站式参考。

五、客户端如何解析页面：平台与语言回退机制

别名页面之所以能正确生效，依赖 tldr 客户端遵循 CLIENT-SPECIFICATION.md 中定义的页面解析规则。这份规范与别名页面直接相关的关键机制有三点：

1. 平台分组与common平台：页面按操作系统分组（linux、windows、osx等），特殊的common平台存放跨平台一致的命令。如果某命令在特定平台行为不同，则在该平台目录下放一份定制副本。compose被归入linux平台，即属于 Linux 专属命令（依赖 mailcap 机制）。
2. 平台回退顺序：客户端默认显示当前运行平台的页面；若该平台没有此页面，则回退到common；若common也没有，才尝试其他平台并给出提示。对compose而言，Linux 用户会命中linux平台下的页面（或该语言的对应翻译）。
3. 语言优先于平台之外的分层查找：规范建议在查找页面时，平台优先于语言——即先在首选语言下按平台找，再切换到下一优先语言。因此阿拉伯语用户请求compose时，客户端会优先查找pages.ar/linux/compose.md；若该语言目录下没有此页面，则回退到英文pages/linux/compose.md。

这一机制同时解释了pages/linux/run-mailcap.md的英文原命令页为何存在于主目录，而pages.ar/下没有对应的阿拉伯语run-mailcap页面——用户执行tldr run-mailcap时，客户端会按语言回退规则自动展示英文原命令页。

六、自动化质量保障：别名页面的双重校验

tldr 仓库通过持续集成脚本保证包括别名页面在内的所有页面合规，对pages.ar/linux/compose.md这类页面主要有两道校验：

• Lint 校验：scripts/test.sh 与 scripts/test-tldr-lint.sh 驱动的 tldr-lint 会检查页面格式是否符合 contributing-guides/style-guide.md（包括标题行、说明行>前缀、示例数量等），确保别名页模板被正确使用。
• 文件名一致性检查：scripts/wrong-filename.py 遍历所有pages*目录下的.md文件，将文件名与首行标题规范化（小写、-转空格等）后比对。对compose.md而言，文件名compose必须与标题# compose一致，否则脚本会写入不一致报告。该脚本同样验证别名页指向的原命令页面是否存在对应的英文主页面（通过pages/*/通配检查），从机制上防止别名指向不存在的页面。

因此，pages.ar/linux/compose.md能合入仓库，意味着它同时通过了模板格式与文件名/标题一致性两类自动化检查。

七、使用与验证

要在终端中实际体验这一别名页面，可按以下步骤操作：

1. 安装任意 tldr 客户端（例如官方 Python 客户端：pipx install tldr，或 Rust 客户端 tlrc）。
2. 执行tldr compose，客户端会展示别名页面，提示compose是run-mailcap --action=compose的别名。
3. 执行tldr run-mailcap，即可查看原命令的完整速查页，包括--action=compose|edit|print|view、--debug、--nopager、--norun等全部用法。
4. 在阿拉伯语环境（或通过-L ar语言参数）下重复上述命令，可看到pages.ar/linux/compose.md的阿拉伯语内容。

如果需要在本地仓库中直接阅读，可对照 pages.ar/linux/compose.md、pages/linux/compose.md 与 pages/linux/run-mailcap.md 三个文件，完整观察"别名页 → 原命令页"的对应关系。

结语

compose的别名页面虽然只有三行，却是 tldr 内容组织哲学的一个缩影：用最轻量的方式消除命令别名的信息重复，通过tldr <原命令>的引导把用户带到真正的知识源头。而它的背后，是 style-guide.md 的规范约束、translation-templates/alias-pages.md 的 40 余语言模板支撑、CLIENT-SPECIFICATION.md 的平台/语言回退解析，以及 scripts/wrong-filename.py 的自动化校验。理解了这条链路，就理解了 tldr 仓库中上千个别名页面（从((→let、arch→uname --machine到batcat→bat等）的统一工作机制。

• 文档
• 教程
• 知识库