语法和标点符号

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

Ansible

• 书写“Ansible”。不要写“Ansible, Inc.”或“AnsibleWorks”。唯一例外是在撰写法律或财务报表时。

• 切勿在正文中单独使用徽标。始终保持与句子其余部分相同的字体。

• 在美国，公司是单数。换句话说，Ansible是“它”，而不是“它们”。

大写

如果不是Ansible的真实产品、服务或部门，则不要大写。即使看起来很重要也不要大写。标题中只大写首字母。

冒号

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

但如果列表是句子中某个元素的补充或宾语，则不用冒号：- 出发度假前，请务必（1）设置闹钟，（2）取消报纸订阅，（3）请邻居代收邮件。

如果相关的列表紧跟其后，则在“如下”和“以下”之后使用冒号：改变目录的步骤如下：

1. 打开终端。

2. 输入cd…

使用冒号来引入项目符号列表（或破折号，或您选择的图标/符号）

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

• 连接名称

• 计数

• 每件商品成本

逗号

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

• “项目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.

感叹号（!）

不要在句尾使用它们。在引用命令（例如感叹号 (!) 命令）时可以使用感叹号。

性别指代

在文档中不要使用特定性别的代词。使用“他们”和“他们的”比使用“他/她”和“他的/她的”更不容易产生歧义。

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

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

在写作时不要使用“我们”。“我们”在用户方面没有做任何事情。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

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

列表

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

大写每个项目的首字母。除非很明显它只是一系列项目，例如：* 电脑 * 显示器 * 键盘 * 鼠标

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

在某些情况下，例如海报或主页推广中，项目符号独立出现，则不需要句点。

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

月份和州

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

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

州：(此处应列出美国州名的缩写，建议参考美联社风格指南)

数字

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

电话号码

电话号码格式：1 (919) 555-0123 分机002 和 1 888-GOTTEXT

引号（使用引号和书写引语）

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

除极少数情况外，只使用“said”或“says”，因为其他任何词语都会妨碍引语本身，并且也倾向于进行评论。

在引语之后直接放置姓名

“我喜欢以第一人称写作，因为我喜欢成为我正在写作的角色，”沃利·兰姆说。

而不是

“我喜欢以第一人称写作，因为我喜欢成为我正在写作的角色，”沃利·兰姆说道。

分号

如果项目包含逗号，则使用分号分隔一系列项目

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

在关联副词（但是、因此、否则、即、例如等等）之前使用分号：- 我思故我在。

句子间距

句子之后只使用一个空格。

时间

• 一天中的时间写作“下午4点”。