语法和标点符号

常用风格和用法，以及常见错误

Ansible

写 “Ansible”。不要写 “Ansible, Inc.” 或 “AnsibleWorks”。唯一的例外是当我们撰写法律或财务报表时。
永远不要在正文中使用单独的徽标。始终保持与句子其余部分相同的字体。
在美国，公司是单数。换句话说，Ansible 是 “it”，而不是 “they”。

大小写

如果它不是 Ansible 的真实产品、服务或部门，则不要大写。即使它看起来很重要也不要大写。仅大写标题中第一个单词的第一个字母。

冒号

冒号通常在列表或系列之前使用：- 三角地区由三个城市组成：罗利、达勒姆和教堂山。

但如果列表是句子中元素的补语或宾语，则不使用：- 在度假前，请务必 (1) 设置闹钟，(2) 取消报纸，以及 (3) 请邻居收你的邮件。

如果相关列表紧随其后，则在 “如下所示” 和 “以下” 之后使用冒号：楔子更改目录的步骤如下所示

打开终端。

输入 cd…

使用冒号引入项目符号列表（或短划线，或您选择的图标/符号）

在“属性”对话框中，您将找到以下条目

连接名称

计数

每个项目的成本

逗号

使用序列逗号，即在三个或更多项目的系列中，“和” 之前的逗号

“项目 1、项目 2 和项目 3。”

这样更容易阅读，并有助于避免混淆。您会看到的主要例外情况是在公关中，因为这通常是新闻记者的风格，所以传统上不使用序列逗号。

逗号始终很重要，考虑到以下两个语句的含义差异很大。

我们吃饭吧，奶奶
我们吃奶奶吧。

正确的标点符号可以挽救奶奶的生命。

如果这不能说服您，也许这个可以

缩写

不要在 Ansible 文档中使用缩写。

长破折号

在可能的情况下，使用两边都没有空格的长破折号。当没有完整的长破折号时，请使用两边都没有空格的双破折号——像这样。

可以使用一对长破折号代替逗号来增强可读性。但是请注意，破折号总是比逗号更强调。

一对长破折号可以代替一对括号。破折号被认为比括号更不正式；它们也更具侵入性。如果您想引起人们对括号内容的注意，请使用破折号。如果您想更微妙地包含括号内容，请使用括号。

注意

当使用破折号代替括号时，应省略周围的标点符号。比较以下示例。

Upon discovering the errors (all 124 of them), the publisher immediately recalled the books.

Upon discovering the errors—all 124 of them—the publisher immediately recalled the books.

当在句末使用破折号代替括号时，仅使用单个破折号。

After three weeks on set, the cast was fed up with his direction (or, rather, lack of direction).

After three weeks on set, the cast was fed up with his direction—or, rather, lack of direction.

感叹号 (!)

不要在句末使用它们。当引用命令时，可以使用感叹号，例如 bang (!) 命令。

性别引用

请勿在文档中使用特定性别的代词。阅读使用 “they” 和 “their” 的句子比使用 “he/she” 和 “his/hers” 的句子要自然得多。

在给出指示时使用 “you” 可以，在更一般的解释中使用 “用户”、“新用户” 等等也可以。

在编写技术文档时，切勿使用 “one” 代替 “you”。使用 “one” 太正式了。

编写时切勿使用 “we”。“We” 在用户端不做任何事情。Ansible 的产品会根据用户的要求执行工作。

连字符

连字符的主要功能是形成某些复合词。除非它有作用，否则不要使用连字符。如果复合形容词不会被误读，或者像许多心理学术语一样，其含义已确定，则无需使用连字符。

使用连字符以避免歧义或混淆

a little-used car
a little used-car

cross complaint
cross-complaint

high-school girl
high schoolgirl

fine-tooth comb (most people do not comb their teeth)

third-world war
third world war

在专业印刷材料（特别是书籍、杂志和报纸）中，连字符用于在一行的末尾和下一行的开头之间分割单词。这允许均匀对齐的右边距，而没有高度可变（且分散注意力）的单词间距。

列表

保持项目符号列表的结构等效且一致。如果一个项目符号是动词短语，那么它们都应该是动词短语。如果一个是完整的句子，那么它们都应该是完整的句子，依此类推。

大写每个项目符号的第一个单词。除非它显然只是一个项目列表，例如项目列表：* 电脑 * 显示器 * 键盘 * 鼠标

当项目符号列表出现在其他文本的上下文中时，（除非它是像前面示例那样的直接列表）添加句点，即使项目符号是句子片段。这背后的部分原因是每个项目符号都被认为完成了原始句子。

在某些情况下，当项目符号独立出现时，例如在海报或主页促销中，它们不需要句点。

在给出指导步骤时，请使用编号列表而不是项目符号列表。

月份和州

根据 AP 缩写月份和州。只有当月份与日期一起使用时才缩写。示例：“总统于 1999 年 1 月访问。”或“总统于 1 月 12 日访问。”

月份：一月、二月、三月、四月、五月、六月、七月、八月、九月、十一月、十二月。

州：阿拉巴马州、亚利桑那州、阿肯色州、加利福尼亚州、科罗拉多州、康涅狄格州、特拉华州、佛罗里达州、佐治亚州、伊利诺伊州、印第安纳州、堪萨斯州、肯塔基州、路易斯安那州、马里兰州、马萨诸塞州、密歇根州、明尼苏达州、密西西比州、密苏里州、蒙大拿州、内布拉斯加州、内华达州、新罕布什尔州、新泽西州、新墨西哥州、纽约州、北卡罗来纳州、北达科他州、俄克拉荷马州、俄勒冈州、宾夕法尼亚州、罗德岛州、南卡罗来纳州、南达科他州、田纳西州、佛蒙特州、弗吉尼亚州、华盛顿州、西弗吉尼亚州、威斯康星州、怀俄明州。

数字

一到九之间的数字用文字写出。10 及以上的数字用数字表示。例外情况是写“400 万”或“4 GB”。在表格和图表中也接受使用数字。

电话号码

电话号码样式：1 (919) 555-0123 x002 和 1 888-GOTTEXT

引言（使用引号和书写引言）

“将标点符号放在引号内，”编辑说。

除了极少数情况外，仅使用“said”或“says”，因为其他任何内容都会妨碍引言本身，并且也倾向于发表评论。

将姓名放在引言之后: “我喜欢写第一人称，因为我喜欢成为我正在写的角色，”沃利·兰姆说。
不是: “我喜欢写第一人称，因为我喜欢成为我正在写的角色，”沃利·兰姆说。

分号

如果项目包含逗号，请使用分号分隔系列中的项目

每天我早餐吃咖啡、吐司和水果；午餐吃沙拉；晚餐吃花生酱三明治、饼干、冰淇淋和巧克力蛋糕。

在连接副词（例如 however、therefore、otherwise、namely、for example 等）之前使用分号：- 我思故；我在。

句子后的空格

句子后只使用一个空格。

时间

时间应写为“下午 4 点”。