从 docker ps 看 tldr 别名页：阿拉伯文页面逐行解析与别名页生成机制

docker ps 是 Docker 容器列表现代子命令 docker container ls 的别名。tldr 仓库通过独立的"别名页"（alias page）来记录这类关系，pages.ar/common/docker-ps.md 就是阿拉伯文版本的别名页实例。本文以该页面为主线，逐行解析其内容结构，并借助仓库中的翻译模板、生成脚本、CI 校验与风格指南，完整讲解 tldr 别名页从模板翻译到自动生成的全链路机制，读完后你将理解别名页为何存在、如何书写、如何被脚本批量维护，以及如何通过 tldr docker container ls 获取 Docker 容器列表的全部用法。

一、别名页是什么：为什么 docker ps 需要一页文档

tldr 的定位是"协作式控制台命令速查表"。当一个命令只是另一个命令的别名（例如 vi 之于 vim、docker ps 之于 docker container ls）时，为它单独编写一整套示例显然是重复劳动。tldr 的解决方案是别名页：一个极简页面，只说明"此命令是某命令的别名"，并指引用户去查看原命令的完整文档。

这一点在英文风格指南 contributing-guides/style-guide.md 中有明确规范：

If a command can be called with alternative names (like vim can be called by vi), alias pages can be created to point the user to the original command name.

"如果一个命令可以被替代名称调用（如 vim 可由 vi 调用），就可以创建别名页，将用户指向原始命令名。"

docker ps 正是典型场景：Docker CLI 将历史上惯用的 docker ps 保留为 docker container ls 的别名。仓库英文页 pages/common/docker-ps.md 仅用三行就完成了这一说明：

# docker ps

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

- View documentation for the original command:

`tldr docker container ls`

而在原命令页 pages/common/docker-container-ls.md 中，示例语法直接写成 docker {{<a href="https://link.gitcode.com/i/d19bb99d27d03480f903472a26cbb748" target="_blank">ps|container ls]}}，明确告诉读者 ps 与 container ls 两种拼写等价。据当前仓库，[docker-ps.md 这样的别名页共存在于 39 个语言目录下，全部基于同一套翻译模板生成，结构完全一致。

二、逐行解剖 pages.ar/common/docker-ps.md（阿拉伯文别名页）

关联文档 pages.ar/common/docker-ps.md 全文共 7 行，是阿拉伯语（ar）别名页的标准形态，完整内容如下：

# docker ps

> هذا الأمر هو اسم مستعار لـ `docker container ls`.

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

`tldr docker container ls`

逐行解析：

1. H1 标题行：# docker ps。页面文件名与命令名一致，遵循风格指南"文件名尽量与所调用命令匹配"的原则。这是脚本识别页面标题的依据（脚本会提取以 # 开头的行作为 title）。
2. 别名描述行：> هذا الأمر هو اسم مستعار لـ docker container ls.。以 > 开头的引用行是 tldr 页面的固定第二行，此处是阿拉伯语"此命令是 docker container ls 的别名"。"docker container ls"是原命令，也就是用户真正应该查阅的完整命令名。这一行是别名页的判据行——生成/校验脚本正是靠它识别某个页面是否为别名页、别名指向谁。
3. 操作提示行：- إعرض التوثيقات للأمر الأصلي:。阿拉伯语"查看原命令的文档"。tldr 页面统一采用"- 破折号 + 描述 + 空行 + 反引号命令"的示例格式，别名页只有这一条示例。
4. 命令行：`tldr docker container ls`。给出可复制的完整命令：用户执行 tldr docker container ls 即可获得原命令的完整速查页。

与英文页 pages/common/docker-ps.md 对照可见，二者除语言外结构逐行一一对应，这正是翻译模板机制想要保证的效果。

三、别名页背后的翻译模板与生成脚本

3.1 四十多种语言的统一模板

所有语言别名页的"标准答案"存放在 contributing-guides/translation-templates/alias-pages.md 中。该文件以 ### 语言代码 为分节，收录了 en、ar、bg、bn、zh、zh_TW 等 40 余种语言的完整别名页模板。其中阿拉伯语（### ar）模板如下：

# example

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

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

`tldr example`

模板中的 example 是占位符，分别代表"别名命令标题""原命令名""用于 tldr 查询的命令"。CONTRIBUTING 贡献指南 CONTRIBUTING.md 也明确指向了这套预翻译模板："A list of translated templates for alias pages can be found here。"

顺带一提：仓库的阿拉伯文风格指南 style-guide.ar.md 的 Aliases 示例中使用了措辞相近但略有差异的 "لقب"（如 هذا الأمر هو لقب لـ \vim`.`），而生成脚本依赖的模板则统一采用 "اسم مستعار"；两处文档措辞不完全一致，但以模板为生成基准。

3.2 生成与同步脚本 scripts/set-alias-page.py

别名页的创建与批量维护由 scripts/set-alias-page.py 完成，其 docstring 明确了五种典型用法：

# 交互式创建/更新单个别名页（例如 osx/gsum）
python3 scripts/set-alias-page.py -p osx/gsum

# 将英文别名页同步到所有语言目录
python3 scripts/set-alias-page.py -S

# 只同步巴西葡萄牙语（pt_BR）
python3 scripts/set-alias-page.py -S -l pt_BR

# 同步并 git stage 改动
python3 scripts/set-alias-page.py -Ss

# 试运行，只预览将产生的改动
python3 scripts/set-alias-page.py -Sn

脚本核心逻辑值得展开：

• 模板占位符替换：generate_alias_page_content()（scripts/set-alias-page.py）对模板中的 example 依次做三次替换：第一次替换为别名页标题（docker ps），第二次替换为原命令名（docker container ls），第三次替换为 tldr 查询命令（docker container ls）。这解释了为什么一页文档能同时携带"别名是什么"和"去哪看原文档"两重信息。
• 按语言提取判据短语：get_locale_alias_pattern()（scripts/set-alias-page.py）从模板中正则提取 > … \example`` 一行的描述短语（阿拉伯语即 "هذا الأمر هو اسم مستعار لـ"），用于后续按语言识别别名页。
• 别名页识别与内容回读：get_alias_command_in_page()（scripts/set-alias-page.py）要求一个标准别名页恰好包含两条命令行——一条以 > +判据短语开头（携带原命令名），一条以 `tldr 开头（携带文档查询命令）；行数或标题缺失即判定"不是别名页"。这也是 CI 对页面格式最核心的机器校验。
• 同步管线：get_english_alias_pages() 遍历英文页目录收集全部别名页，sync_alias_page_to_locale() 再将其逐一套用到各语言目录；模板解析则由 _common.py 的 get_templates()（scripts/_common.py）完成，它会读取翻译模板文件并跳过 "Not translated yet." 的未翻译语言。

四、查看原命令文档：docker container ls 页面全解

通过别名页的指引，tldr docker container ls 会展示真正的完整页面 pages/common/docker-container-ls.md，该页覆盖了 Docker 容器列表的 8 种常用场景，本文全部继承如下：

# docker container ls

> List Docker containers.

- List currently running Docker containers:

`docker {{[ps|container ls]}}`

- List all Docker containers (running and stopped):

`docker {{[ps|container ls]}} {{[-a|--all]}}`

- Show the latest created container (includes all states):

`docker {{[ps|container ls]}} {{[-l|--latest]}}`

- Filter containers that contain a substring in their name:

`docker {{[ps|container ls]}} {{[-f|--filter]}} "name={{name}}"`

- Filter containers that share a given image as an ancestor:

`docker {{[ps|container ls]}} {{[-f|--filter]}} "ancestor={{image}}:{{tag}}"`

- Filter containers by exit status code:

`docker {{[ps|container ls]}} {{[-f|--filter]}} "exited={{code}}" {{[-a|--all]}}`

- Filter containers by status (created, running, removing, paused, exited, and dead):

`docker {{[ps|container ls]}} {{[-f|--filter]}} "status={{status}}"`

- Filter containers that mount a specific volume or have a volume mounted in a specific path:

`docker {{[ps|container ls]}} {{[-f|--filter]}} "volume={{path/to/directory}}" --format "table \{\{.ID\}\}\t\{\{.Image\}\}\t\{\{.Names\}\}\t\{\{.Mounts\}\}"`

几点对 tldr 语法与 Docker 用法的深度说明：

• {{[ps|container ls]}} 双拼写占位符：方括号内用 | 分隔的两个值表示"两者等价"，即 docker ps 与 docker container ls 语义一致——这与别名页的结论互为印证。读者可以按习惯任选一种拼写执行。
• {{<a href="https://link.gitcode.com/i/9aa79a0a21684afd2273aed72e19bed5" target="_blank">-a|--all]}} 这类占位符：-a 与 --all 是同一选项的短、长两种写法，tldr 用 | 分隔展示。-l|--latest、-f|--filter 同理；这是 tldr 页面统一的可选项表示法，见[通用参数模板。
• --filter 过滤器取值：页面示例覆盖了 name（按容器名子串）、ancestor（按祖先镜像 <镜像>:<标签>）、exited（按退出码，常与 -a 配合以列出已停止容器）、status（created / running / removing / paused / exited / dead）、volume（按挂载卷或挂载路径）五类过滤维度。
• --format "table \{\{.ID\}\}\t\{\{.Image\}\}\t\{\{.Names\}\}\t\{\{.Mounts\}\}"：Go 模板格式化输出的典型用法，将默认表格裁剪为 ID、镜像、名称、挂载点四列，适合在脚本中做二次解析。

另外，英文原命令页首部还带有一条 More information: <https://docs.docker.com/reference/cli/docker/container/ls/> 的官方文档链接，符合 tldr 的 更多信息链接模板；而别名页模板刻意不含该行，因为原命令页已承担全部信息承载职责。

五、风格指南中的别名页书写规范

英文风格指南 contributing-guides/style-guide.md 给出了别名页的通用范式（以 vi/vim 为例）：

# vi

> This command is an alias of `vim`.

- View documentation for the original command:

`tldr vim`

并指出预翻译模板可从 contributing-guides/translation-templates/alias-pages.md 获取，贡献者不应自行翻译措辞，而应直接套用对应语言的模板，保证全球 40 余种语言页面结构一致。阿拉伯文版规范见 style-guide.ar.md。

此外，风格指南还专门规定了 PowerShell 别名的三类特殊处理：

1. 替换现有 cmd 命令（如 cd → Set-Location）：不建别名页，而是在原命令页第二行加"在 PowerShell 中，此命令是 Set-Location 的别名"注释；
2. 仅 PowerShell 可用的新别名（如 ni → New-Item）：使用标准别名模板，但描述中加"在 PowerShell 中"前缀；
3. 与其他程序冲突的别名（如 curl/wget → Invoke-WebRequest）：需附带说明如何判断当前调用的是 PowerShell 别名还是同名外部程序。

docker ps 这类跨平台、无歧义的经典别名则走标准模板路线。

六、CI 校验与贡献流程中的别名页

仓库的持续集成脚本 scripts/test.sh 会在每次推送时运行 black、flake8、pytest 与 tldr-lint 等检查；其中 scripts/test-tldr-lint.sh 针对阿拉伯语等 RTL/非拉丁字母语言，固定忽略 TLDR104,TLDR003,TLDR004,TLDR015 四项 lint 检查（*ar*|*bn*|*fa*|… 分支命中 ar），并对其余语言目录执行 npx tldr-lint。别名页的机器可读性依赖 scripts/set-alias-page.py 中的"恰好两条命令行"判定逻辑，偏离模板的页面会被识别失败。

在贡献流程上，CONTRIBUTING.md 要求新增页面的提交信息遵循 命令名: add page / 命令名: add alias page 的约定，其示例即 docker-container-rm: add alias page——与本文讨论的 docker-ps 别名页属于同一类提交。脚本 docstring 也提示：-S 同步选项会因模板匹配产生大量误报，建议仅使用 -l LANGUAGE 限定语言并只提交人工核对过的改动。

七、实战小结

围绕 docker ps 这个别名页，完整的查阅链路是：

# 1. 用户查询 docker ps，客户端返回别名页（阿拉伯语环境显示阿拉伯文版本）
tldr docker ps

# 2. 别名页提示查看原命令文档
tldr docker container ls

# 3. 在容器列表页中，ps 与 container ls 两种拼写均可直接使用
docker ps -a
docker container ls -a

对于 tldr 仓库的维护者而言，理解别名页机制意味着掌握三件事：写——按 alias-pages.md 翻译模板 套用对应语言模板；改——用 scripts/set-alias-page.py 的 -p 交互式创建或 -S/-l 批量同步；验——确保页面保持"标题 + 别名描述 + tldr 指引命令"的标准三要素，通过 test-tldr-lint.sh 的 lint 校验。理解这些之后，再遇到任何一个"某某命令是另一个命令的别名"的场景，你都能立即判断：它该有一页别名页，指向原命令页即可。