页面风格指南

页面布局和结构

TLDR 页面的基本格式遵循特定的结构，以保持项目的一致性。每页最多应包含 8 个命令示例。

基本格式和组成部分

页面的文件名和标题必须与命令名完全匹配，文件名应为小写。一个 linter 会强制执行此格式，并在每次拉取请求时自动运行。

来源：contributing-guides/style-guide.md16-66 contributing-guides/style-guide.md67-71

使用 tldr-lint 进行验证

在提交之前在本地验证页面

要 lint 整个目录，您可以使用

要在本地预览页面

来源：contributing-guides/style-guide.md72-86

页面类型和组织

特定于平台的页面

TLDR 页面按平台组织，以适应不同操作系统之间的命令差异。

如果一个命令在所有平台上的行为都完全相同，则将其放在 common 目录中。如果它在一个平台上行为略有不同，则将主版本放在 common 中，并将特定于平台的变体放在该平台的目录中。

来源：contributing-guides/style-guide.md112-120 CLIENT-SPECIFICATION.md142-172

别名页面

对于可以用其他名称调用的命令（例如 vi 对应 vim），请创建别名页面

来源：contributing-guides/style-guide.md122-147

PowerShell 特定的别名

PowerShell 别名分为三类

替换现有的 Windows 命令提示符命令：向原始命令添加注释
仅限 PowerShell 的别名：创建标准别名页面，并包含 PowerShell 特定的指示
与其他程序冲突：提供检测方法以确定引用的命令

来源：contributing-guides/style-guide.md149-207

歧义消除

当多个命令共享同一个名称时，创建歧义消除页面

来源：contributing-guides/style-guide.md209-227

命令分组

对于通常一起使用的命令，您可以将它们放在同一页面上，或将用户指向一个主命令页面。

来源：contributing-guides/style-guide.md229-244

书写风格指南

文本格式化

在页面中切勿使用斜体、粗体或其他文本样式。这些保留给客户端用于强调占位符。

来源：contributing-guides/style-guide.md248-250

祈使句

所有描述都必须使用祈使句——给出指令而不是描述

✅ 正确（祈使句）	❌ 错误
列出所有文件	列出所有文件
显示当前目录	此命令显示当前目录
创建新文件	文件创建

来源：contributing-guides/style-guide.md252-271

序列逗号

为 3 个或更多项目的列表使用序列（牛津）逗号，以避免歧义

Delete the Git branches, tags, and remotes.  # Clear with comma

来源：contributing-guides/style-guide.md273-288

特殊情况和技术术语

对于可能具有破坏性的命令，请使用占位符而不是真实值

ddrescue --force --no-scrape {{/dev/sdX}} {{/dev/sdY}}  # Safe

为技术术语使用反引号

路径：package.json，/etc/package.json
扩展名：.dll
命令：ls
标准流：stdout，stdin，stderr
压缩算法：zip，7z

来源：contributing-guides/style-guide.md294-315

页面元素

命令描述

保持描述简洁明了

避免在描述中使用页面标题
避免提及命令行用法（这是隐含的）
如果程序名称与可执行文件不同，可以在开头注明

> A sketching and painting program designed for digital artists.  # Good
> Krita is a sketching and painting program designed for digital artists.  # Avoid

来源：contributing-guides/style-guide.md319-333

另请参阅部分

参考相关命令，使用

> See also: `command1`, `command2`, `command3`.

或添加简短描述

> See also: `date` for Unix information, `uname` for system information.

来源：contributing-guides/style-guide.md373-390

示例格式

简短选项助记符

通过突出显示的含义帮助用户理解缩写选项

示例

- [d]isplay the ins[t]allation [i]D for the current device:

`slmgr.vbs /dti`

来源：contributing-guides/style-guide.md394-421

命令选项语法

来源：contributing-guides/style-guide.md425-433

占位符语法

使用 {{placeholder}} 语法表示用户提供的值

注意：对于 Windows，请使用反斜杠：{{path\to\file}}。

来源：contributing-guides/style-guide.md435-482

按键语法

对于键盘输入，请使用尖括号

语法	含义
`<a>`	单个字符
`<Ctrl>`	特殊键（PascalCase）
`<Ctrl c>`	同时按下按键
`<Esc><u>`	连续按键

对于同时按下按键，保持顺序：<Ctrl Super Windows Alt AltGr Shift everything_else>

来源：contributing-guides/style-guide.md490-502

帮助和版本命令

将帮助和版本命令作为最后两个示例，使用标准措辞

- Display help:

`command --help`

- Display version:

`command --version`

来源：contributing-guides/style-guide.md504-507

语言和翻译规则

不同的语言有特定的格式规则，以确保正确的语法和可读性。

英语规则

使用普通连字符（-）而不是长横线（–）或破折号（—）。

来源：contributing-guides/style-guide.md517-528

中文特定规则

指南包括中文和拉丁字母单词之间的空格、标点规则以及带有单位的数字格式。

来源：contributing-guides/style-guide.md530-566

其他语言特定的规则

印尼语：避免使用带 ber- 和 me- 前缀的动词主动形式
法语：使用第三人称单数现在时直陈式
Portuguese: 以第三人称单数现在时直陈式动词开头

来源: contributing-guides/style-guide.md568-648

TLDR 页面流程：从源到显示

下图说明了 TLDR 页面如何从创建到显示

来源: contributing-guides/style-guide.md16-86 CLIENT-SPECIFICATION.md142-172 CONTRIBUTING.md196-228 contributing-guides/maintainers-guide.md56-103

总结

遵循这些样式指南可确保所有 TLDR 页面的一致性，使文档对每个人来说都更易于访问和使用。自动化的 linter (tldr-lint) 有助于强制执行这些规则，但理解其背后的原因有助于贡献者从一开始就创建更好的页面。

有关提交贡献的更多信息，请参阅为 TLDR 页面做贡献。