tldr 别名页实战：以保加利亚语 llvm-gcc 别名页为例读懂 clang 命令文档-开发者社区

文档
教程
知识库

【免费下载链接】tldr

Collaborative cheatsheets for console commands 📚.

项目地址：https://gitcode.com/GitHub_Trending/tl/tldr

本篇文章围绕 tldr 仓库中的 pages.bg/common/llvm-gcc.md 展开，解读别名页（alias page）这一 tldr 核心机制：为什么llvm-gcc被标记为clang的别名、别名页的保加利亚语模板结构、如何通过tldr clang快速获取原命令用法，以及仓库脚本如何批量生成与同步各语言别名页。读完本文，你既能读懂这一份具体页面，也能掌握 tldr 别名页的通用解析方法与维护流程。

一、页面原文：一行话揭示命令别名关系

pages.bg/common/llvm-gcc.md全文只有 7 行，是标准 tldr 别名页的保加利亚语翻译：

# llvm-gcc > Тази команда е псевдоним на `clang`. - Виж документацията за оригиналната команда: `tldr clang`

逐行拆解其含义：

行内容	保加利亚语含义	在别名页中的角色
`# llvm-gcc`	llvm-gcc	H1 标题，必须与命令名一致
`> Тази команда е псевдоним на \`clang`.`\| 此命令是`clang`的别名 \| 描述行（以`>` 开头），标明被别名指向的原命令
`- Виж документацията за оригиналната команда:`	查看原命令的文档：	示例描述，用祈使句引导
`tldr clang`	tldr clang	可执行示例命令

这份页面没有任何具体的编译参数，因为别名页的职责只有一个：告诉用户"你输入的命令其实是另一个命令的别名，去看原命令的文档"。这与 pages/common/llvm-gcc.md 英文版内容一一对应（This command is an alias of \clang`.），也与仓库中其他 38 个语言版本的llvm-gcc.md`（如 pages.zh/common/llvm-gcc.md、pages.ko/common/llvm-gcc.md）保持完全一致的语义。

二、为什么 llvm-gcc 是 clang 的别名

从 tldr 文档的角度看，llvm-gcc并非独立命令，而是clang的别名。这一判定基于命令生态的实际历史关系：llvm-gcc曾是 LLVM 项目早期基于 GCC 前端构建的实验性编译器入口，而clang是 LLVM 项目自家的 C/C++/Objective-C 编译器前端，如今已完全取代前者成为 LLVM 默认工具链。tldr 仓库选择将其记录为别名页，正是为了帮助用户在遇到llvm-gcc这类历史遗留命令名时，能迅速被引导到仍然活跃、文档完整的clang页面，而不是为已废弃的命令重复维护一套完整示例。

这一点在 tldr 的维护指南中也有明确定义。contributing-guides/style-guide.md 的 "Aliases" 一节指出：当一个命令可以用替代名称调用时（如vim可写作vi），就可以创建别名页，把用户指向原命令名。别名页的本质是"重定向页"，因此内容被刻意压缩到最少。

三、别名页模板机制：一份模板，多语言复用

保加利亚语别名页并不是手写的自由文本，而是基于统一的翻译模板生成。模板集中存放在 contributing-guides/translation-templates/alias-pages.md 中，每种语言一小节，例如：

### bg # example > Тази команда е псевдоним на `example`. - Виж документацията за оригиналната команда: `tldr example`

模板用占位符example标记三个关键位置：标题、描述行中的原命令名、tldr命令行中的文档命令名。脚本在生成真实页面时，会按顺序把example替换为实际命令名。以llvm-gcc页面为例，替换后的结果就是：

标题：llvm-gcc
描述行：Тази команда е псевдоним на \clang`.`
命令行：`tldr clang`

这种"模板 + 占位符替换"的设计保证了全球各语言版本的结构高度一致，任何客户端都能以相同方式解析，也让维护者无需逐语言手写。

四、底层实现：set-alias-page.py 如何生成与同步别名页

别名页的生成与批量同步由仓库脚本 scripts/set-alias-page.py 承担。从源码看，其核心流程分为三块：

模板解析：_common.py中的get_templates(root, "alias-pages.md")会扫描 contributing-guides/translation-templates/alias-pages.md，把每个###语言块下的 markdown 内容提取成{locale: template}字典（见 scripts/_common.py）。
占位符替换：generate_alias_page_content依次把模板中的example替换为页面标题、原命令名、文档命令名（scripts/set-alias-page.py），一次调用同时完成标题、描述、命令三处写入。
识别与同步：get_alias_command_in_page通过正则从已有页面中提取别名指向的原命令（如从> ... \clang`.中提取出clang），get_english_alias_pages遍历英文pages/common目录找出所有别名页，再由sync_alias_page_to_locale` 把每个别名页同步到各语言目录（scripts/set-alias-page.py）。

脚本同时支持交互式创建单页与全量同步两种模式：

# 交互式创建或更新一个别名页 python3 scripts/set-alias-page.py -p common/llvm-gcc # 将英文别名页同步到所有翻译语言 python3 scripts/set-alias-page.py -S # 仅同步到保加利亚语，且只做演练不写盘 python3 scripts/set-alias-page.py -S -l bg -n

其中-l bg对应保加利亚语（locale 标签bg），-n/--dry-run用于预览将要产生的改动而不实际修改文件。正是这套机制，保证了像llvm-gcc.md这样 39 个语言版本的内容能够长期保持一致。

五、实战：用 tldr clang 查阅原命令完整文档

别名页指向的 pages/common/clang.md 才是真正承载编译用法的主体页面。执行`tldr clang`后，你会得到 8 条核心示例，覆盖日常编译的绝大多数场景：

场景	命令示例
多源文件编译为可执行文件	`clang {{path/to/source1.c path/to/source2.c ...}} {{[-o\|--output]}} {{path/to/output_executable}}`
输出全部错误与警告	`clang {{path/to/source.c}} -Wall {{[-o\|--output]}} {{output_executable}}`
常规警告 + 调试符号 + 不牺牲调试性的优化	`clang {{path/to/source.c}} -Wall {{[-g\|--debug]}} -Og {{[-o\|--output]}} {{path/to/output_executable}}`
从其他路径引入库	`clang {{path/to/source.c}} {{[-o\|--output]}} {{path/to/output_executable}} -I{{path/to/header}} -L{{path/to/library}} -l{{library_name}}`
编译为 LLVM 中间表示（IR）	`clang {{[-S\|--assemble]}} -emit-llvm {{path/to/source.c}} {{[-o\|--output]}} {{path/to/output.ll}}`
只编译不链接生成目标文件	`clang {{[-c\|--compile]}} {{path/to/source.c}}`
为性能优化编译	`clang {{path/to/source.c}} -O{{1\\|2\\|3\\|fast}} {{[-o\|--output]}} {{path/to/output_executable}}`
显示版本	`clang --version`

注意命令中的{{[-o|--output]}}是 tldr 的"选项占位符"语法：客户端可以根据平台习惯选择展示短选项-o或长选项--output，用户无需记忆两种写法。占位符{{...}}则会在客户端中高亮，提示这是需要用户替换的值。这也解释了别名页里`tldr clang`为什么没有加任何选项——它本身就是一条完整可用的命令。

六、保加利亚语页面的本地化要点

对比 contributing-guides/translation-templates/alias-pages.md 中的### bg模板与 pages.bg/common/llvm-gcc.md 成品，可以发现保加利亚语本地化遵循两条重要约定：

祈使句语气：示例描述使用命令式Виж документацията за оригиналната команда:（"查看原命令的文档"），与 contributing-guides/style-guide.md 中"所有描述必须使用祈使语气"的通用规则一致。
命令名与占位符不翻译：clang、tldr等命令名原样保留在反引号中，只有描述文字被翻译，避免破坏可执行命令的可复制性。

同样遵循该模板的还有 pages.bg/common/clang-cpp.md（clang++的别名页），说明同一套模板在保加利亚语下稳定复用了多次。

七、小结

pages.bg/common/llvm-gcc.md虽然只有寥寥数行，却是 tldr 项目"别名页"机制的完整缩影：它用模板约束结构、用脚本保证多语言一致、用指向tldr clang的命令完成知识重定向。理解这份页面，你就同时理解了 tldr 别名页的阅读方法、翻译模板的组织方式，以及仓库脚本 scripts/set-alias-page.py 的自动化维护思路——下次在终端遇到任何"某命令是另一命令的别名"的场景，都可以用同样的思路快速定位到真正的原命令文档。