mirror of https://github.com/CrimsonTome/tldr.git
103 lines
4.8 KiB
Markdown
103 lines
4.8 KiB
Markdown
# 格式指导
|
||
|
||
当你在为 `tldr` 贡献时，请遵守下面的格式规范。
|
||
|
||
请注意，下面的规范仅适用于中文翻译的 `tldr` 页面。
|
||
|
||
## 排版
|
||
|
||
首先，你的页面应该看起来像这样：
|
||
|
||
```md
|
||
# 命令名称
|
||
|
||
> 短小精悍的描述。
|
||
> 描述最好只有一行；当然，如果需要，也可以是两行。
|
||
> 更多信息：<https://example.com>.
|
||
|
||
- 命令描述：
|
||
|
||
`命令 -选项1 -选项2 -参数1 {{参数的值}}`
|
||
|
||
- 命令描述：
|
||
|
||
`命令 -选项1 -选项2`
|
||
```
|
||
|
||
当你将自己的贡献提交 pull request 时，一个脚本会自动检查你的贡献是否符合上面的格式。
|
||
|
||
你也可以在提交前在本地测试自己的贡献：
|
||
|
||
```sh
|
||
npm install --global tldr-lint
|
||
tldr-lint {{page.md}}
|
||
```
|
||
|
||
关于 `tldr-lint` 的更多使用方法，例如检查批量检查一整个目录的格式，[`tldr tldr-lint`](https://github.com/tldr-pages/tldr/blob/master/pages/common/tldr-lint.md) 是你的不二去处！
|
||
|
||
如果你用 tldr-pages 的 Node.js 客户端，你可以在命令后加 `-f` (`--render`) 来在本地预览自己的页面：
|
||
|
||
```sh
|
||
tldr --render {{page.md}}
|
||
```
|
||
|
||
## 占位符（token）语法
|
||
|
||
当命令涉及用户自己提供的值时，请用 `{{token}}` 语法来使 `tldr` 客户端自动高亮它们：
|
||
|
||
`tar -cf {{目标.tar}} {{文件1}} {{文件2}} {{文件3}}`
|
||
|
||
翻译时，请尽量翻译原文中的西文占位符。下面是命名占位符的规则：
|
||
|
||
1. 占位符需要短小精悍，
|
||
例如 `{{源文件}}` 或者 `{{钱包.txt}}`
|
||
2. 如果占位符是西文，请用 [`snake_case`](https://en.wikipedia.org/wiki/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}}` 来表示一个 **块设备** 。
|
||
|
||
占位符应该尽可能简单明了，让人一眼就能看出应该替换它的值。
|
||
|
||
在命令描述中，如果出现了技术性的专有名词，请用 `反引号` 括起来：
|
||
|
||
1. 路径，例如 `package.json`，`/etc/package.json`.
|
||
2. 扩展名，例如 `.dll`.
|
||
3. 命令，例如 `ls`.
|
||
|
||
## 中西文混排规则
|
||
|
||
中文、西文、阿拉伯数字写在同一个句子时，需要注意排版。
|
||
|
||
以下规则适用于中文（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 条规则。
|
||
|
||
有关更多中西文混排规则的信息，请参考 [《中文文案排版指北》](https://github.com/sparanoid/chinese-copywriting-guidelines)。
|