All human beings are born free and equal in dignity and rights. They are endowed with reason and conscience and should act towards one another in a spirit of brotherhood.
第 12 章。写作风格
目录
12.1。提示
技术文档可以通过一致地使用几个原则来改进。大多数这些原则可以归类为三个目标：*清晰明了*、*完整*和*简洁*。这些目标可能相互冲突。优秀的写作在于它们之间的平衡。
12.1.1。清晰明了
清晰度极其重要。读者可能是新手，或者用第二语言阅读文档。力求使用简单明了的文字来解释概念。
避免使用华丽或修饰性的语言、笑话或口语表达。尽可能简单明了地写作。简单的文字更容易理解和翻译。
尽可能简短、简单、清晰地进行解释。避免使用诸如“为了”之类的空洞短语，它们通常只是表示“为了”。避免使用诸如“基本上”之类的可能带有轻蔑意味的词语。避免使用诸如“即”或“参见”之类的拉丁语词语，这些词语在学术或科学群体之外可能不为人知。
使用正式风格。避免将读者称为“您”。例如，说“将文件复制到 /tmp”而不是“您可以将文件复制到 /tmp”。
提供清晰、正确、*经过测试*的示例。一个微不足道的示例总比没有示例好。一个好的示例更好。不要提供错误的示例，这些示例可以通过道歉或诸如“但实际上不应该那样做”之类的句子来识别。错误的示例比没有示例更糟糕。提供好的示例，因为*即使被警告不要按照示例所示使用*，读者通常也会按照示例所示使用。
避免使用诸如“应该”、“可能”、“尝试”或“可以”之类的*含糊词语*。这些词语暗示说话者对事实并不确定，并给读者带来怀疑。
同样，将指令作为命令性命令给出：不是“您应该这样做”，而是仅仅“这样做”。
12.2。指南
为了促进 FreeBSD 文档无数作者之间的一致性，已为作者制定了一些指南供他们遵循。
- 使用美式英语拼写
英语有几种变体，对同一个词的拼写方式不同。在拼写方式不同的情况下，使用美式英语变体。“color”，而不是“colour”，“rationalize”，而不是“rationalise”，等等。
在贡献文章的情况下，可以使用英式英语，但是整个文档中拼写必须一致。其他文档，如书籍、网站、手册页等，必须使用美式英语。
- 不要使用缩略词
不要使用缩略词。始终完整拼出短语。“不要使用缩略词”是错误的。
避免使用缩略词可以营造更正式的语调，更精确，并且翻译起来稍微容易一些。
- 使用串行逗号
在段落中列出项目时，用逗号将每个项目与其他项目隔开。用逗号和单词“and”将最后一个项目与其他项目隔开。
例如
这是一个包含一个、两个和三个项目的列表。
这是一个包含三个项目的列表，“一个”、“两个”和“三个”，还是一个包含两个项目的列表，“一个”和“两个和三个”？
明确使用串行逗号会更好
这是一个包含一个、两个和三个项目的列表。
- 避免使用冗余短语
不要使用冗余短语。特别是，“命令”、“文件”和“man 命令”通常是冗余的。
例如，命令
错误：使用
git命令更新源代码。正确：使用
git更新源代码。文件名
错误：… 在文件名 /etc/rc.local 中…
正确：… 在 /etc/rc.local 中…
手册页引用（第二个示例使用
man:[]以及 csh(1) 实体）错误：有关更多信息，请参阅
man csh。正确：请参阅 csh(1)。
有关写作风格的更多信息，请参阅威廉·斯特朗克的 《风格要素》。
12.4。每行一句
在文档中使用语义换行符，这是一种名为“每行一句”的技术。这种技术的理念是帮助用户编写和阅读文档。有关此技术的更多信息，请阅读 语义换行符 页面。
这是一个没有使用“每行一句”的示例。
这是一个使用这种技术的示例。
All human beings are born free and equal in dignity and rights. They are endowed with reason and conscience and should act towards one another in a spirit of brotherhood.
12.5。缩略语
缩略语应该在文档中首次出现时定义，例如：“网络时间协议 (NTP)”。在定义缩略语后，使用缩略语本身，除非在上下文中使用完整术语更有意义。缩略语通常每个章节或每个文档只定义一次。
所有缩略语都应使用 ` 字符括起来。
12.6。特殊字符列表
此特殊字符列表显示了在 FreeBSD 文档中使用时的正确语法和输出。 如果列表中没有某个字符，请在 FreeBSD 文档项目邮件列表 上询问。
| 名称 | 语法 | 渲染 |
|---|---|---|
版权 | (C) | © |
注册 | (R) | ® |
商标 | (TM) | ™ |
长破折号 | -- | — |
省略号 | ... | … |
单向右箭头 | -> | → |
双向右箭头 | => | ⇒ |
单向左箭头 | <- | ← |
双向左箭头 | <= | ⇐ |
12.7. 使用 Vale 进行代码风格检查
为了在所有文档和网站页面上保持清晰度和一致性，在文档树中引入了 Vale 风格。 Vale 是一款功能强大的代码风格检查器，用于编写自定义规则，并且可以在多种场景中使用。 目前，Vale 可以用作命令行工具，用于 CI/CD 管道，并集成到选择的编辑器中。
下表描述了当前的规则名称及其各自的严重程度。
| 名称 | 严重程度 |
|---|---|
FreeBSD.BrandTerms | 错误 |
FreeBSD.ConsciousLanguage | 警告 |
FreeBSD.Contractions | 建议 |
FreeBSD.EOLSpacing | 警告 |
FreeBSD.Hang | 警告 |
FreeBSD.Hyphens | 警告 |
FreeBSD.Spacing | 错误 |
FreeBSD.SuperfluousOptArgInLinks | 建议 |
Vale.Avoid | 错误 |
Vale.Repetition | 错误 |
Vale.Spelling | 错误 |
Vale.Terms | 错误 |
12.7.1. 当前的 Vale 规则
FreeBSD.BrandTerms：根据 FreeBSD 基金会的版权规则，freebsd 应写为 FreeBSD。 同样，每个主要供应商和公司都有特定的规则来编写其品牌名称和商标。 应注意尊重他人的品牌价值，并花时间写 PostgreSQL、Node.js、Let’s Encrypt 等。 缺少的品牌名称应添加到
doc存储库中的 .vale/styles/FreeBSD/BrandTerms.yml 中。FreeBSD.ConsciousLanguage：此规则建议使用有意识的语言，以便在可能的情况下避免使用指向人们的颜色、年龄、种族或性取向的敏感词。
FreeBSD.Contractions：不应使用缩略词。 此规则避免所有缩略词，并建议使用完整词语。
FreeBSD.EOLSpacing：在大多数文档中，存在 EOL 间距，这不是理想情况。
FreeBSD.Hang：
Hang通常用于表示应用程序已停止响应。 此规则建议使用更好的措辞。FreeBSD.Hyphens：通常，以 'ly' 结尾的副词会加上连字符，这是错误的。
FreeBSD.Spacing：通常，双空格很难用肉眼捕捉到，这里解决了这个问题。
FreeBSD.SuperfluousOptArgInLinks：建议在
link:宏中使用空方括号，当显示文本与 URL 一致时。Vale.Avoid：强制执行 FreeBSD 项目的不使用词汇术语。 如果发现任何不应出现在文档中的词语，应将其添加到
doc存储库中的 .vale/styles/Vocab/Terms/reject.txt 中。 目前该列表为空。Vale.Repetition：在离开键盘并重新加入工作时，通常会重复键入相同的词语两次。 此规则会查找重复的词语并警告用户。
Vale.Spelling：目前，文档和网站中混合了 en_US 和 en_GB 拼写。 Vale 附带了一个内置字典，它严格使用 en_US，不接受任何词语的 en_GB 变体。
Vale.Terms：强制执行 FreeBSD 项目的首选词汇术语。 目前，术语列表为空，FreeBSD 特定术语将逐步添加。 如果发现任何词语是正确的并且在字典中不可用，则应将其添加到
doc存储库中的 .vale/styles/Vocab/Terms/accept.txt 中。
在需要时，将在未来几天内引入更多规则。
12.7.2. 使用 Vale
Vale 可以从命令行和编辑器或 IDE 中使用。 可以按如下方式安装 textproc/vale
$ pkg install vale12.7.2.1. 在命令行中使用 Vale
假设 doc 存储库已克隆到 ~/doc 中，则需要运行以下命令。
% cd ~/doc
% vale .Vale 由于应用程序的性质，是一个 CPU 和内存密集型程序，可能需要一段时间才能在屏幕上显示任何输出。 运行应用程序的更好方法是在特定文件夹或文件上运行，而不是整个 |
12.7.2.2. 在编辑器中使用 Vale
Vale 支持主要的流行编辑器，如 editors/vim、editors/emacs、editors/vscode。 目前，editors/vim 的必要配置在 Vim 中进行了描述。 正在开发 editors/emacs 的配置。
最后修改于：2024 年 3 月 9 日，作者 Danilo G. Baio