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

105 lines
4.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

# 格式指导
当你在为 `tldr` 贡献时,请遵守下面的格式规范。
请注意,下面的规范仅适用于中文翻译的 `tldr` 页面。
## 排版
首先,你的页面应该看起来像这样:
```
# 命令名称
> 短小精悍的描述。
> 描述最好只有一行;当然,如果需要,也可以是两行。
> 更多信息:<https://example.com>.
- 命令描述:
`命令 -选项1 -选项2 -参数1 {{参数的值}}`
- 命令描述:
`命令 -选项1 -选项2`
```
当你将自己的贡献提交 pull request 时,一个脚本会自动检查你的贡献是否符合上面的格式。
你也可以在提交前在本地测试自己的贡献:
```
npm install tldr-lint
tldrl -f {{page.md}}
```
关于 `tldrl` 的更多使用方法,例如检查批量检查一整个目录的格式,[`tldr tldrl`](https://github.com/tldr-pages/tldr/blob/master/pages/common/tldrl.md) 是你的不二去处!
如果你用 tldr-pages 的 Node.js 客户端,你可以在命令后加 `-f` (`--render`) 来在本地预览自己的页面:
```
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)。