tldr/contributing-guides/style-guide.zh.md

格式指导

当你在为 tldr 贡献时，请遵守下面的格式规范。

请注意，下面的规范仅适用于中文翻译的 tldr 页面。

排版

首先，你的页面应该看起来像这样，并且最多只能包含 8 个示例：

# 命令名称

> 简短、精炼的描述。
> 描述最好只有一行；当然，如果需要，也可以是两行。
> 更多信息：<https://example.com>.

- 命令描述：

`命令 -选项 1 -选项 2 -参数 1 {{参数的值}}`

- 命令描述：

`命令 -选项 1 -选项 2`

当你将自己的贡献提交 pull request 时，一个脚本会自动检查你的贡献是否符合上面的格式。

你也可以在提交前在本地测试自己的贡献：

npm install --global tldr-lint
tldr-lint {{page.md}}

关于 tldr-lint 的更多使用方法，例如检查批量检查一整个目录的格式，tldr tldr-lint 是你的不二去处！

如果你用 tldr-pages 的 Node.js 客户端，你可以在命令后加 -f (--render) 来在本地预览自己的页面：

tldr --render path/to/tldr_page.md

PowerShell 特定规则

在记录 PowerShell 命令时，请注意以下命名约定。

• 文件名必须以小写形式书写，例如 invoke-webrequest.md 而不是 Invoke-WebRequest.md。
• 页面标题/标题必须按照原样书写（与 Microsoft 或 PowerShell 模块作者意图一致），例如 Invoke-WebRequest 而不是 invoke-webrequest。
• 示例中的命令名称和选项也应按原样书写，例如 Command-Name {{input}} -CommandParameter {{value}} 而不是 command-name {{input}} -commandparameter {{value}}。

由于各种兼容性差异和在 PowerShell 6.x 中删除的特定于 Windows 的命令，确保命令在 PowerShell 5.1（即安装在 Windows 10 和 11 中的“传统 Windows PowerShell”）和 最新版本的跨平台 PowerShell（以前称为 PowerShell Core）之间可用。如果命令或其选项在每个版本之间不可用或包含不同的行为，请在描述中注明。例如，

# Clear-RecycleBin

> 清空回收站中的项目。
> 此命令仅适用于 PowerShell 版本 5.1 及以下版本，或 7.1 及以上版本。
> 更多信息： <https://learn.microsoft.com/powershell/module/microsoft.powershell.management/clear-recyclebin>.

别名

如果一个命令可以通过其他名称调用（例如 vim 可以通过 vi 调用），可以创建别名页面将用户引导到原始命令名称。

# command_name

> 此命令是 `original-command-name` 的别名。
> 更多信息： <https://example.com/original/command/help/page>.

- 查看原始命令的文档：

`tldr original_command_name`

示例：

# vi

> 这是 `vim` 命令的一个别名。

- 原命令的文档在：

`tldr vim`

预先翻译好的别名模板见这里。

PowerShell 特定别名

某些 PowerShell 命令可能会引入别名，这些别名可以分为以下三类：

1. 替代现有的 Windows 命令提示符 (cmd) 命令，例如 cd 别名为 Set-Location，但带有不同的命令选项。在这种情况下，将以下别名注释添加到原始命令提示符命令的 tldr 描述的第二行中，例如：

   # cd
   
   > 显示当前工作目录或移动到其他目录。
   > 在 PowerShell 中，此命令是 `Set-Location` 的别名。本文档基于命令提示符 (`cmd`) 版本的 `cd`。
   > 更多信息： <https://learn.microsoft.com/windows-server/administration/windows-commands/cd>.
   
   - 原命令的文档在：
   
   `tldr set-location`
   

[!TIP] “查看等效 PowerShell 命令的文档”的示例是可选的，如果页面已经具有 8 条示例，则可以省略。

1. 提供一个新的别名，但只能在 PowerShell 中执行，例如 ni 代表 New-Item。在这种情况下，使用标准别名模板，但添加说明“在 PowerShell 中”，或表示该命令仅限于 PowerShell。例如，

   # ni
   
   > 在 PowerShell 中，此命令是 `New-Item` 的别名。
   > 更多信息： <https://learn.microsoft.com/powershell/module/microsoft.powershell.management/new-item>.
   
   - 查看原始命令的文档：
   
   `tldr new-item`
   

2. 与其他程序冲突时 PowerShell 会提供一个新的别名，最为突出的是将 curl 和 wget 作为 Invoke-WebRequest 的别名（带有不兼容的命令选项集）。请注意，此类别的 PowerShell 系统别名通常仅限于 Windows。

在这种情况下，提供一个说明，并提供一种方法来确定命令当前是否引用了 PowerShell 命令（通过别名）或其他程序。例如，

# curl

> 在 PowerShell 中，当原始的 `curl` 程序 (<https://curl.se>) 未正确安装时，此命令可能是 `Invoke-WebRequest` 的别名。
> 更多信息： <https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/invoke-webrequest>.

- 通过打印其版本号来检查 `curl` 是否已正确安装。如果此命令导致错误，则 PowerShell 可能已将此命令替换为 `Invoke-WebRequest`：

`curl --version`

- 查看原始 `curl` 命令的文档：

`tldr curl -p common`

- 查看 PowerShell 的 `Invoke-WebRequest` 命令的文档：

`tldr invoke-webrequest`

选项语法

• 对于常用命令（例如 grep、tar 等），我们更推荐在占位符中使用简短选项以及助记符。
• 对于在命令中同时突出长选项和短选项（而不是使用助记符），将它们组合在占位符中，即 {{-o|--output}}。
• 为了用户友好，在 common 目录下的页面中，当它们在跨平台（在多个平台上都可以正常工作）时，我们更推荐使用GNU 风格的长选项（例如 --help 而不是 -h)。
• 在记录 PowerShell 命令时，使用PowerShell 风格的长选项（例如 -Help 而不是 -H）。
• 我们更推荐使用空格而不是等号 (=) 来分隔选项和其参数（即使用 --opt arg 而不是 --opt=arg），除非程序不支持此方法。

短选项助记符

短选项助记符是可选的提示，可以添加以帮助用户理解这些短选项的含义。分配的助记符应与命令的官方文档（例如来自 man 或 Get-Help）中的内容相匹配。例如：

- [d]isplay the ins[t]allation [i]D for the current device. Useful for offline license activation:

`slmgr.vbs /dti`

Display the current license's e[xp]i[r]ation date and time:

`slmgr.vbs /xpr`

请注意，在第一个示例中，[d]、[t] 和 [i] 字符被方括号括起来，以指示命令的 /dti 选项分别是 "display"、"installation" 和 "ID" 的组合。连续的助记符字符可以在同一方括号下进行分组，例如 e[xp]i[r]ation 而不是 e[x][p]i[r]ation。

助记符字符必须以区分大小写的方式编写，即使它放在句子的第一个字符位置（例如使用 [d]isplay 而不是 [D]isplay）。这是为了避免与 GNU 风格命令选项产生冲突，GNU 风格命令选项可能会以不同于小写的方式解释大写选项，例如 -v 用于显示命令的 [v]ersion 号码，而 -V 则用于以 [V]erbose 模式运行命令。

选项助记符也可以在翻译中使用，只要突出显示的单词与命令所用语言（通常为英语）中的单词具有相似的含义即可。例如，英语中的 [d]ownload 可以翻译为西班牙语中的 [d]escargar，英语中的 [i]nstall 可以翻译为德语中的 [i]nstallieren，而英语中的 [a]pp 可以翻译为印尼语和马来语中的 [a]plikasi。

可选地，在翻译和特定页面中，助记符及其包含的术语可以用括号与描述的其余部分分开（即 ([a]ll)），以提供额外的上下文或提及描述中不存在的单词。

[!NOTE] 在翻译的单词中如果缺少字符，您可以在等效词的前面或旁边突出显示选项，或您可以在括号内的翻译旁边添加英文单词。例如，英语中的 E[x]tract 可以翻译为印尼语中的 [x] ekstrak 或 ekstrak [x] 或 ekstrak (E[x]tract)。

占位符语法

当命令涉及用户自己提供的值时，请用 {{token}} 语法来使 tldr 客户端能自动高亮它们：

tar -cf {{目标.tar}} {{文件 1}} {{文件 2}} {{文件 3}}

翻译时，请尽量翻译原文中的西文占位符。下面是命名占位符的规则：

1. 占位符需要短小精悍， 例如 {{源文件}} 或者 {{钱包.txt}}
2. 如果占位符是西文，请用 snake_case 来分词。
3. 当占位符涉及文件路径时，请用 {{目录/子目录/《占位符》}} 的格式。 例如：ln -s {{目录/子目录/源文件}} {{目录/子目录/链接}} 如果占位符提到的文件也可能是目录，请用 {{目录/子目录/文件或目录}}
4. 除非文件是特定的，上述 {{目录/子目录/《占位符》}} 的文件路径格式应用于所有包含路径的命令。
5. 如果命令需要的文件扩展名是固定的，请在占位符里加上文件格式。 例如：unrar x {{压缩包.rar}} 如果文件 必须 有一个扩展名，请用 {{.ext}} 。 例如，在 find {{起始目录}} -name '{{*.ext}}' 的例子里， 这样做简单地演示了查找一个特定文件扩展名的方法。 但是，在 wc -l {{file}} 的例子里，用不加扩展名的 {{file}} 就足够了。
6. 如果用实际的值比描述这个占位符更加明了，请举一个值做例子。 例如：iostat {{2}} 比 iostat {{以秒为单位的间隔}} 更清晰。
7. 如果一个命令可能对文件系统或设备造成不可逆的影响，请在示例命令中注意改写，使其不能被盲目复制粘贴运行。 例如，ddrescue --force --no-scrape /dev/sda /dev/sdb 被盲目复制粘贴时可能对系统造成毁灭性的打击；ddrescue --force --no-scrape {{/dev/sdX}} {{/dev/sdY}} 则更安全。 因此，请用 {{/dev/sdXY}} 而不是 {{/dev/sda1}} 来表示一个 块设备 。

占位符应该尽可能简单明了，让人一眼就能看出应该替换它的值。

路径

• 当只期望文件名时，请使用 {{filename}}。
• 对于文件或目录路径的任何引用，请使用格式 {{path/to/<placeholder>}}，除非位置是隐含的。
• 当路径不能是相对路径，而必须从文件系统的根目录开始时，请使用斜杠作为前缀，例如 get {{/path/to/remote_file}}。
• 如果可能引用文件或目录，请使用 {{path/to/file_or_directory}}。

[!NOTE] 如果命令专用于 Windows，请使用反斜杠（\），例如 {{path\to\file_or_directory}}。驱动器号（如 C:）是可选的，除非命令输入要求绝对路径或特定的驱动器号范围，例如 cd /d {{C}}:{{path\to\directory}}。

扩展名

• 如果文件有特定的扩展名，请写出来。 例如，unrar x {{path/to/compressed.rar}}。
• 如果需要通用的扩展名，请使用 {{.ext}}，但只有在需要扩展名时才使用。 例如，在 find.md 的示例“按扩展名查找文件”中（find {{path/to/root}} -name '{{*.ext}}'）， 使用 {{*.ext}} 可以解释命令而不必过于具体； 而在 wc -l {{path/to/file}} 中，使用 {{path/to/file}}（不带扩展名）就足够了。

分组占位符

• 如果命令可以接受相同类型的 0 个或多个参数，请使用省略号：{{placeholder1 placeholder2 ...}}。 例如，期望多个路径，则可以使用 {{path/to/directory1 path/to/directory2 ...}}。
• 如果命令可以接受不同类型的 0 个或多个参数，请使用竖线和省略号：{{placeholder1|placeholder2|...}}。 如果可能值超过 5 个，则可以在最后一项后面使用 |...。
• 无法通过省略号限制占位符的最小或最大数量。

特殊情况

• 如果一个命令可能对文件系统或设备进行不可逆转的更改， 请以一种不会被轻易复制粘贴的方式编写每个示例。 例如，不要写成 ddrescue --force --no-scrape /dev/sda /dev/sdb， 而是写成 ddrescue --force --no-scrape {{/dev/sdX}} {{/dev/sdY}}， 并且对于*块设备*，使用 {{/dev/sdXY}} 占位符，而不是 /dev/sda1。

通常情况下，占位符应尽可能直观，以便于理解如何使用命令并填入相应的值。

在命令描述中，如果出现了技术性的专有名词，请用 反引号 括起来：

• 路径，例如 package.json，/etc/package.json。
• 扩展名，例如 .dll。
• 命令，例如 ls。
• 标准流：stdout，stdin，stderr。不要使用完整的名称（例如标准输出）。
• 压缩算法，例如 zip，7z，xz。

描述

祈使句

• 所有描述必须以祈使句表达。

如果你担心命令在不同平台或操作系统之间可能不同（例如 Windows 对比 macOS），大多数 tldr 页面客户端 将选择最适合的命令版本。

在这种情况下，默认将显示 Windows 版本的 cd 信息（存储在 pages/windows/cd.md 中）给 Windows 用户，并为 Linux、macOS 和其他平台显示一个通用版本（存储在 pages/common/cd.md 中）。

在为命令示例编写描述时，检查任何语法错误。例如，应该使用 前往指定目录 而不是：

• 正前往指定目录（不应使用现在分词形式）
• 该命令将前往指定目录（很明显此示例适用于 此 命令）
• 让我们前往指定目录！
• 目录被更改为（如果可能，应使用主动形式而不是被动形式）

例如，可以使用 列出所有文件： 的描述，下面是示例的描述可以使用 列出所有文件：。

- 列出所有文件：

`ls`

措辞

• 所有描述必须简洁。
• 避免在描述中使用页面标题（例如，使用 为数字艺术家设计的素描和绘画程序，而不是 Krita 是为数字艺术家设计的素描和绘画程序），除非程序名称与可执行文件名称不同（例如 rg 和 Ripgrep）。
• 避免提及程序是在命令行上使用的（例如，使用 Ripgrep 是一个递归的面向行的搜索工具，而不是 Ripgrep 是一个递归的面向行的 CLI 搜索工具）。

• 例如，在为 cd 编写文档时，一个用于在终端或命令提示符中更改当前工作目录的工具，不要写出像这样冗长的描述：

  > `cd` 是一个系统工具，在 Windows、macOS 和 Linux 中可用，用于在命令提示符、终端和 PowerShell 中更改当前工作目录以完成任务。
  

它应该简化以使每个人都能更轻松地阅读：

> 更改当前工作目录。

格式

• 在描述中，应该对专有名词进行大写（例如，使用 用于与 Git 仓库交互的工具。，而不是 用于与 `git` 仓库交互的工具。）。
• 首字母缩写（即协议、工具等）在没有本地同类物时不应进行翻译。
• 当编写包含键盘按键或键盘快捷键时，建议将它们用反引号括起来，以突出显示在描述中（即 打印给定文件的最后几行，并一直读取直到按下 `Ctrl + C`：）。 或者，您可以将它们记录为单独的命令，然后选择性地将它们突出显示为占位符（即 :wq{{Enter}} 或 :wq<Enter> 或 :wq(Enter)）。

斜体和粗体

请不要在页面上使用 *斜体*、粗体 或任何其他文本样式。这些样式被用于客户端对占位符的修饰。

更多信息链接

• 在更多信息链接行上，我们更推荐链接到作者提供的命令行参考文档或 man 手册。如果没有提供，请使用 https://manned.org 作为所有系统（除 osx 和除了 FreeBSD 之外的 BSD 平台）的默认链接。或者，如果命令没有文档页面，您也可以链接到作者的网站或教程页面。

• 对于 osx：苹果在 Xcode 中分发内置的 man 手册 在这里。对于那里记录的命令，我们建议使用 https://keith.github.io/xcode-man-pages/, 这是 Xcode 捆绑的所有苹果 man 手册的 HTML。

• 所有链接必须放在尖括号（< 和 >）中，以便在客户端中正确呈现。

• 我们更倾向于在翻译页面中直接使用英文页面的更多信息链接。

版本化链接

当一个应用程序或发行版的包具有版本化链接时，我们更倾向于链接到文档的最新版本（即 latest），或者如果网站自动重定向到文档的最新版本，则不用链接到任何版本。

例如，使用：

• https://manpages.debian.org/latest/apt/apt.8.html 而不是 https://manpages.debian.org/bookworm/apt/apt.8.en.html。
• https://docs.aws.amazon.com/cdk/latest/guide/cli.html 而不是 https://docs.aws.amazon.com/cdk/v2/guide/cli.html。

Microsoft Learn 链接

当链接到 Microsoft Learn 页面时，请删除地址中的语言环境，因为网站会自动重定向到读者的首选语言环境。例如，使用 https://learn.microsoft.com/windows-server/administration/windows-commands/cd 而不是 https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/cd。

此外，如果链接与 PowerShell 命令文档相关，请删除文档版本指示符（即文档来源的 PowerShell/module 版本），即地址中以 ?view= 开头的部分。

• 使用 https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/select-string 而不是 https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/select-string?view=powershell-7.4。
• 使用 https://learn.microsoft.com/powershell/module/powershellget/install-module 而不是 https://learn.microsoft.com/en-us/powershell/module/powershellget/install-module?view=powershellget-1.x。

帮助和版本命令

• 通常我们将帮助命令和版本命令按照这个顺序放在页面的最后两个示例中，以突出页面开头更实用的命令。如果需要，它们可以被替换为其他有用的示例。
• 为了保持一致性，我们更推荐使用通用的术语 显示帮助 和 显示版本 来描述这些命令。
• 如果命令在 Windows 等平台中使用了不同的标志，建议记录下帮助和版本示例。

特定语言规则

以下部分包含了用于翻译页面的额外的特定语言规则：

中西文混排规则

中文、西文、阿拉伯数字写在同一个句子时，需要注意排版。

以下规则适用于中文（zh）和繁体中文（zh_TW）：

1. 在西文单词和数字前后放置一个空格。 例如：列出所有 docker 容器 而不是 列出所有docker容器。 例如：宽度为 50 个字 而不是 宽度为50个字。
2. 除了度数和百分比，在数字和单位之间留一个空格。 例如：容量 50 MB 而不是 容量 50MB。 对于度数和百分比：使用 50°C 和 50% 而不是 50 °C 和 50 %.
3. 不要在全角标点符号前后放置空格。 例如：开启 shell，进入交互模式 而不是 开启 shell ，进入交互模式。
4. 除了西文长句，一律使用全角标点符号。 例如：嗨，你好。 而不是 嗨，你好.。
5. 当最句子最后一个字符是半角时，使用半角标点符号来结束句子。 例如：将代码转化为 Python 3. 而不是 将代码转化为 Python 3。。
6. 使用精准的专有名词，不要使用非官方的中文缩写。 例如：Facebook 而非 facebook、fb 或 脸书。

为保持可读性和一致性，将页面翻译成中文时，请尽可能遵守以上 6 条规则。

有关更多中西文混排规则的信息，请参考 《中文文案排版指北》。