• 文档
• 教程
• 知识库

本文以 tldr 仓库中的别名页 pages.bg/linux/pw-midirecord.md 为核心，剖析 tldr 别名命令页（alias page）的结构规范、多语言模板机制与自动化维护脚本，并延伸讲解其指向的原命令pw-cat --record --midi在 PipeWire 下的 MIDI 录制实战用法。读完本文，你将掌握别名页的编写规则、仓库内的生成工具链，以及如何在 Linux 上通过pw-cat完成 MIDI 录音。

一、别名页是什么：pw-midirecord 页面解析

在 tldr 仓库中，pw-midirecord属于 PipeWire 提供的一个便捷命令。它的 tldr 页面不是一份完整的命令速查表，而是一个典型的"别名页"（alias page），其英文原版位于 pages/linux/pw-midirecord.md，内容如下：

# pw-midirecord > This command is an alias of `pw-cat --record --midi`. - View documentation for the original command: `tldr pw-cat`

而本文指定的保加利亚语版本 pages.bg/linux/pw-midirecord.md 内容完全相同，只是语言不同：

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

由此可见，别名页承担的是"指路牌"功能：当用户对pw-midirecord感到陌生时，tldr 客户端不会重复维护一份与pw-cat雷同的说明，而是直接告知"这是pw-cat --record --midi的别名"，并引导用户执行tldr pw-cat查看完整文档。

从仓库结构看，该别名页在所有语言目录中都有对应翻译（如 pages.zh/linux/pw-midirecord.md、pages.ja/linux/pw-midirecord.md、pages.ko/linux/pw-midirecord.md 等共 39 个版本），这恰好印证了 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指向vim的完整示例。别名页严格由三部分组成：

1. 标题行：# pw-midirecord，与文件名保持一致；
2. 别名声明：以>开头的引用行，写明"此命令是某某的别名"；
3. 文档跳转：一个列表项与一条`tldr pw-cat`命令，告诉用户如何查看原命令文档。

这套结构被刻意设计得极简，因为它不承载功能细节，只负责正确跳转。这也是为什么 tldr 项目用脚本而非人工维护别名页——格式高度模板化，完全适合程序化生成。

三、多语言别名页模板与同步机制

为了在几十种语言中保持一致，仓库在 contributing-guides/translation-templates/alias-pages.md 中存放了所有语言的预翻译模板。以本文相关的保加利亚语（bg）模板为例：

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

该文件完整收录了 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、ta、th、tr、uk、uz、zh、zh_TW 共 40 种语言的模板。对比可见，pages.bg/linux/pw-midirecord.md正是把模板中的占位符example依次替换为实际命令名pw-midirecord、原命令pw-cat --record --midi与文档命令pw-cat后的产物。

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

仓库提供了一套完整的别名页生成与同步工具，位于 scripts/set-alias-page.py，其核心流程可从源码结构清晰梳理出来：

4.1 页面内容的数据结构

脚本用两个 dataclass 描述别名页：

• AliasPageContent（scripts/set-alias-page.py）：承载title（标题）、original_command（原命令）、documentation_command（文档跳转命令）与full_page（完整页面文本）；
• AliasPage（scripts/set-alias-page.py）：绑定页面相对路径与其内容。

4.2 模板占位符替换

generate_alias_page_content（scripts/set-alias-page.py）负责把语言模板中的占位符example依次替换为真实内容：

template_command = "example" result = template_content.replace(template_command, page_content.title, 1) result = result.replace(template_command, page_content.original_command, 1) result = result.replace(template_command, page_content.documentation_command)

注意三次replace分别使用替换计数 1、1、默认全部，确保标题、别名声明、tldr跳转三处各就各位。

4.3 已有页面的识别与比对

get_alias_command_in_page（scripts/set-alias-page.py）通过正则解析已有页面中的标题行、别名声明行与tldr行，将抽取出的字段与英文模板比对，据此判断页面是否"已经是标准的别名页"；set_alias_page（scripts/set-alias-page.py）则在内容一致时跳过写入，内容变化时才执行 "added"/"updated" 写盘。

4.4 批量同步入口

脚本支持两种操作模式：

• 交互式创建单个别名页：python3 scripts/set-alias-page.py -p linux/pw-midirecord（对应-p/--page参数，会启动向导依次询问标题、原命令、文档命令，scripts/set-alias-page.py）；
• 批量同步所有翻译：python3 scripts/set-alias-page.py -S（对应--sync，会遍历英文页目录找出全部别名页，再逐一同步到各语言目录，scripts/set-alias-page.py）。

此外还支持-l LANGUAGE限定单一语言（如-l pt_BR）、-n/--dry-run预览变更、-s/--stage对 Git 变更暂存。需要说明的是，脚本文档中明确提示同步模式会产生不少误报，建议仅暂存并人工核对改动（scripts/set-alias-page.py）。

五、追本溯源：pw-cat 原命令与 MIDI 录制实战

别名页只是入口，真正的功能实现位于原命令pw-cat。其英文文档见 pages/linux/pw-cat.md，概述为 "Play and record audio files through PipeWire"，并给出相关命令提示：wpctl、pw-cli，以及官方手册链接指向 PipeWire 文档站点。

5.1 pw-cat 的核心能力

pw-cat是 PipeWire 自带的音频播放/录制命令行工具，支持 WAV、MIDI、DSD、压缩编码等多种媒体格式。以下是文档中覆盖的主要用法：

命令中的大括号写法（如{{[-p|--playback]}}）是 tldr 的占位符约定，表示可选项-p或等价的--playback。

5.2 pw-midirecord 的实际等价形式

从别名声明pw-cat --record --midi可以明确：执行pw-midirecord file.mid等价于执行：

pw-cat --record --midi file.mid

即启动 PipeWire 的 MIDI 录制，将捕获到的 MIDI 事件写入指定的.mid文件。若想深入了解完整参数，遵循别名页指引运行：

tldr pw-cat

5.3 录制参数的深化理解

结合原命令文档（pages/linux/pw-cat.md），录制场景下还有两个实用参数：

• --volume 1.25：设置采样录制的音量级别为 125%，适用于需要增益补偿的录制场景；
• --rate 6000：以 6000 Hz 的自定义采样率录制，适合对采样率有特定要求的采集任务。

两者均以--record模式为前提，与--midi可自由组合使用。

六、别名页在客户端中的实际体验

别名页的价值最终体现在 tldr 客户端的使用体验上。当用户在终端输入：

tldr pw-midirecord

tldr 客户端会从对应平台与语言的目录中读取页面。以当前仓库为例，Linux 平台下系统会优先展示与语言环境匹配的翻译版本（如保加利亚语用户看到 pages.bg/linux/pw-midirecord.md，中文用户看到 pages.zh/linux/pw-midirecord.md），没有匹配翻译时回退到英文原版 pages/linux/pw-midirecord.md。

随后用户按页面提示执行tldr pw-cat，即可获得关于播放与录制的完整速查信息。这种"别名页 + 原命令页"的两级跳转设计，既避免了重复内容的维护负担，又保证用户始终能定位到权威的功能文档——这正是 tldr 协作式速查手册项目在命令数量庞大、别名纷杂场景下的核心组织策略。

七、小结

本文从一份仅有三行的别名页出发，串起了 tldr 项目的完整机制：

• 规范层面：别名页遵循 contributing-guides/style-guide.md 定义的三行式模板；
• 模板层面：多语言预翻译模板集中在 contributing-guides/translation-templates/alias-pages.md，pw-midirecord的保加利亚语版本正是其中 bg 模板的直接产物；
• 工具层面：scripts/set-alias-page.py 提供了交互创建、多语言批量同步、dry-run 预览与 Git 暂存的一站式维护能力；
• 功能层面：pw-midirecord等价于pw-cat --record --midi，其完整播放/录制能力、质量与采样率参数详见 pages/linux/pw-cat.md。

理解了别名页的设计哲学与工具链，无论是为 tldr 贡献新命令页、审阅多语言翻译，还是在 Linux 上借助 PipeWire 完成 MIDI 录制，你都将有据可依、有例可循。

• 文档
• 教程
• 知识库