mirror of https://github.com/CrimsonTome/tldr.git
4.7 KiB
4.7 KiB
格式指导
当你在为 tldr
贡献时,请遵守下面的格式规范。
请注意,下面的规范仅适用于中文翻译的 tldr
页面。
排版
首先,你的页面应该看起来像这样:
# 命令名称
> 短小精悍的描述。
> 描述最好只有一行;当然,如果需要,也可以是两行。
> 更多信息:<https://example.com>.
- 命令描述:
`命令 -选项1 -选项2 -参数1 {{参数的值}}`
- 命令描述:
`命令 -选项1 -选项2`
当你将自己的贡献提交 pull request 时,一个脚本会自动检查你的贡献是否符合上面的格式。
你也可以在提交前在本地测试自己的贡献:
npm install tldr-lint
tldrl -f {{page.md}}
关于 tldrl
的更多使用方法,例如检查批量检查一整个目录的格式,tldr tldrl
是你的不二去处!
如果你用 tldr-pages 的 Node.js 客户端,你可以在命令后加 -f
(--render
) 来在本地预览自己的页面:
tldr --render {{page.md}}
占位符 (token) 语法
当命令涉及用户自己提供的值时,请用 {{token}}
语法来使 tldr
客户端自动高亮它们:
tar -cf {{目标.tar}} {{文件1}} {{文件2}} {{文件3}}
翻译时,请尽量翻译原文中的西文占位符。下面是命名占位符的规则:
- 占位符需要短小精悍,
例如
{{源文件}}
或者{{钱包.txt}}
- 如果占位符是西文,请用
snake_case
来分词。 - 当占位符涉及文件路径时,请用
{{目录/子目录/<占位符>}}
的格式。 例如:ln -s {{目录/子目录/源文件}} {{目录/子目录/链接}}
如果占位符提到的文件也可能是目录,请用{{目录/子目录/文件或目录}}
- 除非文件是特定的,上述
{{目录/子目录/<占位符>}}
的文件路径格式应用于所有包含路径的命令。 - 如果命令需要的文件扩展名是固定的,请在占位符里加上文件格式。
例如:
unrar x {{压缩包.rar}}
如果文件 必须 有一个扩展名,请用{{.ext}}
。 例如,在find {{起始目录}} -name '{{*.ext}}'
的例子里, 这样做简单地演示了查找一个特定文件扩展名的方法。 但是,在wc -l {{file}}
的例子里,用不加扩展名的{{file}}
就足够了。 - 如果用实际的值比描述这个占位符更加明了,请举一个值做例子。
例如:
iostat {{2}}
比iostat {{以秒为单位的间隔}}
更清晰。 - 如果一个命令可能对文件系统或设备造成不可逆的影响,请在示例命令中注意改写,使其不能被盲目复制粘贴运行。
例如,
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
.
中西文混排规则
中文、西文、阿拉伯数字写在同一个句子时,需要注意排版。
以下规则适用于中文(zh)和繁体中文(zh_TW):
- 在西文单词和数字前后放置一个空格。
例如:
列出所有 docker 容器
而不是列出所有docker容器
。 例如:宽度为 50 个字
而不是宽度为50个字
。 - 除了度数和百分比,在数字和单位之间留一个空格。
例如:
容量 50 MB
而不是容量 50MB
。 对于度数和百分比:使用50°C
和50%
而不是50 °C
和50 %
. - 不要在全角标点符号前后放置空格。
例如:
开启 shell,进入交互模式
而不是开启 shell ,进入交互模式
。 - 除了西文長句,一律使用全角标点符号。
例如:
嗨,你好。
而不是嗨, 你好.
。 - 当最句子最后一个字符是半角时,使用半角标点符号来结束句子。
例如:
将代码转化为 Python 3.
而不是将代码转化为 Python 3。
。 - 使用精准的专有名词,不要使用非官方的中文缩写。
例如:
Facebook
而非facebook
、fb
或脸书
。
为保持可读性和一致性,将页面翻译成中文时,请尽可能遵守以上 6 条规则。
有关更多中西文混排规则的资讯,请参考《中文文案排版指北》。