tldr 别名页机制与 docker stop 完整指南：从保加利亚语别名声明到 docker container stop 实战用法

本文以 tldr 仓库中的别名页 pages.bg/common/docker-stop.md 为切入点，解读 tldr 项目中"别名页"这种特殊文档类型的格式规范与设计意图，并完整展开其指向的原命令 docker container stop 的全部用法，最后结合仓库中的自动化脚本 scripts/set-alias-page.py 说明别名页如何被生成、识别与多语言同步。读完本文，你将掌握 tldr 别名页的解析规则，并能直接使用 docker stop 的等价完整形式 docker container stop 完成容器停止、信号发送与超时控制等操作。

一、关联文档全景：docker stop 别名页的三要素

tldr 仓库中的 pages.bg/common/docker-stop.md 是一份完整的保加利亚语别名页，全文结构如下：

# docker stop

> Тази команда е псевдоним на `docker container stop`.

- Виж документацията за оригиналната команда:

`tldr docker container stop`

虽然只有几行，但它严格遵循 tldr 别名页模板，包含三个核心要素：

1. 页面标题：# docker stop，即被记录的别名命令名；
2. 别名声明：> Тази команда е псевдоним на docker container stop.，保加利亚语意为"此命令是 docker container stop 的别名"，用于点明别名与原始命令之间的映射关系；
3. 文档跳转指引：tldr docker container stop，提示用户通过 tldr 客户端查看原始命令的完整速查手册。

作为对照，仓库中的英文版 pages/common/docker-stop.md 内容完全等价：

# docker stop

> This command is an alias of `docker container stop`.

- View documentation for the original command:

`tldr docker container stop`

两个版本的差异仅在自然语言描述，结构化占位（标题、别名声明、tldr 跳转命令）逐行对应，这正是别名页模板多语言化的直接体现。

二、别名页的设计动机与模板规范

2.1 为什么需要别名页

在 tldr 项目中，大量命令是其他命令的别名或简化写法，例如 docker stop 本质上是 docker container stop 的简写。如果为这类命令单独维护一份完整页面，将产生大量内容重复，且容易与原始命令文档产生不一致。

因此项目在 contributing-guides/translation-templates/alias-pages.md 中定义了"别名页"（alias page）这一轻量文档类型：不重复罗列用法，只声明别名关系并指向原命令文档。该文件是 37 种以上语言别名页模板的汇总清单，每种语言对应一个统一的模板片段。

2.2 模板的结构化占位

以该文件中的英文（en）模板为例：

# example

> This command is an alias of `example`.

- View documentation for the original command:

`tldr example`

保加利亚语（bg）模板（见 alias-pages.md 的 bg 小节）则为：

# example

> Тази команда е псевдоним на `example`.

- Виж документацията за оригиналната команда:

`tldr example`

模板中的 example 是统一占位符，生成页面时会被三个实际值依次替换：页面标题（如 docker stop）、原命令（如 docker container stop）、文档查询命令（同样为 docker container stop）。正是这套机制保证了 pages.bg/common/docker-stop.md 与英文版在结构上的严格一致。

2.3 别名页的平台归类

docker stop 属于跨平台通用命令，因此别名页被放置在 common 分类目录下（对应 pages/common/docker-stop.md）。仓库中为 docker stop 提供了数十种语言的同名别名页（如 pages.zh、pages.fr、pages.de 等语言目录下均有对应文件），语言版本之间仅替换模板中的自然语言描述，核心结构保持一致。

三、原命令 docker container stop 完整用法参考

别名页的落点在于"查看原命令文档"。原命令完整页面为 pages/common/docker-container-stop.md，主题是"停止一个或多个正在运行的容器"，并在顶部附带了指向 Docker 官方 CLI 参考的"更多信息"链接。其全部用法如下。

3.1 停止单个容器

docker {{[stop|container stop]}} {{container}}

其中 {{container}} 是占位符，需替换为实际容器名或容器 ID；[stop|container stop] 表示两种命令形式等价可选——既可以写别名 docker stop，也可以写完整形式 docker container stop。

3.2 发送指定信号停止容器

docker {{[stop|container stop]}} {{[-s|--signal]}} {{signal}} {{container}}

-s/--signal 用于指定发送给容器的信号（如 SIGTERM、SIGINT 等），以便按需触发容器内的优雅退出流程，适用于需要自定义关闭行为的场景。

3.3 设置超时后强制终止

docker {{[stop|container stop]}} {{[-t|--timeout]}} {{seconds}} {{container}}

-t/--timeout 指定等待秒数：容器在该时间内未正常退出时会被强制杀死。该参数用于控制从"请求停止"到"强制终止"之间的宽限期长度。

3.4 一次停止多个容器

docker {{[stop|container stop]}} {{container1 container2 ...}}

将多个容器名或 ID 以空格分隔依次传入，可在一个命令中批量停止若干容器。

3.5 查看帮助信息

docker {{[stop|container stop]}} --help

通过 --help 输出该子命令的完整参数说明，便于在终端内即时查阅。

这些用法同样适用于别名形式：上述每条命令中的 [stop|container stop] 都可替换为 stop，即 docker stop container1 container2 ...、docker stop -s SIGTERM myapp 等，效果与完整形式完全一致。

四、别名页的自动化维护：set-alias-page.py 源码解析

别名页虽然简短，但数量大、语言多，人工维护极易出错。仓库为此提供了专门的生成与同步脚本 scripts/set-alias-page.py，从源码层面印证了上述模板机制。

4.1 占位符替换的核心逻辑

脚本通过 generate_alias_page_content 完成页面内容生成：读取指定语言的模板后，将模板中的 example 占位符依次替换为标题、原命令、文档查询命令，最终输出完整的 Markdown 页面。这与 pages.bg/common/docker-stop.md 中"标题 → 别名声明 → tldr 跳转命令"的成文顺序完全对应。

4.2 别名页的识别与校验

get_alias_command_in_page 负责判断某个页面是否为标准别名页：它解析 # 开头的标题、> 开头的别名声明（提取反引号内的原命令）以及 tldr ... 行的文档查询命令，并通过剥除模板与页面差异的方式校验页面是否严格遵循模板。任何偏离模板结构的页面都会被判定为"非别名页"或触发更新。

4.3 多语言同步与命令行用法

脚本支持交互式创建与全量同步两种模式。创建单个别名页时（如 docker stop 类命令），可运行：

python3 scripts/set-alias-page.py -p common/docker-stop -l en

其中 -p/--page 指定别名页路径（格式为"平台/命令名.md"），脚本会进入交互式向导，依次提示输入标题、原命令与文档查询命令，并预览将生成的页面结构。

若要一次性将英文别名页同步到所有语言版本：

python3 scripts/set-alias-page.py -S

只同步某一语言（例如保加利亚语）时，配合 -l 参数：

python3 scripts/set-alias-page.py -S -l bg

其他常用选项还包括：-n/--dry-run（仅预览改动而不写盘）、-s/--stage（同步后暂存改动）、-i/--inexact（允许匹配非严格模板的别名页）。脚本文档字符串特别提醒：-S 同步模式会产生较多误报，建议逐语言配合 -l 使用并人工核对变更。

从实现上看，脚本的同步流程为：先从 pages 英文目录遍历各平台子目录，借助 get_english_alias_pages 识别全部别名页；再对每个语言目录调用 sync_alias_page_to_locale，用该语言的模板重新生成页面；若目标语言页面已存在且内容一致，则跳过写入。这保证了类似 docker stop 的别名页在多语言仓库中始终保持模板一致。

五、docker stop 周边命令页面速览

为了在实际使用中形成完整闭环，可以顺带查阅仓库中与容器启停相关的其他页面：

• pages/common/docker.md：docker 命令总览，包含"启动或停止已存在容器"等常用操作，并指出 container、image 等子命令各自拥有独立文档；
• pages/common/docker-start.md 与 pages/common/docker-container-start.md：与 docker stop 配对的"启动已停止容器"别名页及原命令页，支持 -a/--attach 附加标准输出与信号转发，可对比理解 tldr 中"别名页 + 原命令页"这一对文档组合的完整形态；
• pages/common/docker-ps.md：配合 docker stop 使用，先列出运行中的容器以获取容器名或 ID。

结语

以 pages.bg/common/docker-stop.md 为代表的 tldr 别名页，是"轻量文档 + 结构化跳转"设计思想的具体落地：模板规范（alias-pages.md）定义了跨语言一致的页面骨架，自动化脚本（set-alias-page.py）保证了成百上千个别名页的格式统一，而真正的技术细节则由原命令页（pages/common/docker-container-stop.md）承载。理解这条"别名声明 → 原命令查阅"的链路，既能帮助你快速使用 docker stop / docker container stop 完成容器停止、自定义信号与超时控制，也能让你看懂 tldr 仓库在文档组织与工程化维护上的完整思路。