wiki/org/技术文档规范/标点符号.md

id	title	sidebar_position	data
标点符号	标点符号	5	2022年3月8日

常用中文标点符号

技术文档中容易用错的标点符号主要有：句号、逗号、顿号、分号、冒号、引号、括号、书名号、连接号、破折号、省略号、感叹号、斜杠与反斜杠。下文介绍了它们的使用规范。

句号

句号的形式为“。”，表示陈述语气，用于句末停顿。

句号表示一个句子的意思已经完整，技术文档中应善用句号切分语意，帮助用户理清逻辑。

• 【错误示例】原因是 DM 需要保存同步的 binlog position 信息，但是 MySQL binlog position 官方定义使用 uint32 存储，所以超过 4G 部分的 binlog position 的 offset 值会溢出，就会存储的是一个错误的 binlog position，在重启 task 或者 dm-worker 后，需要使用该 binlog position 重新解析 binlog/relay log，进而出现上面的错误。
• 【正确示例】由于 DM 需要保存同步的 binlog position 信息，且 MySQL binlog position 官方定义使用 uint32 存储，因此超过 4G 部分的 binlog position 的 offset 值会溢出。这会导致存储的是一个错误的 binlog position。在重启 task 或者 dm-worker 后，需要使用该 binlog position 重新解析 binlog/relay log，进而出现上面的错误。

逗号

逗号的形式为“，”，表示句子内部的一般性停顿。

逗号使用最为普遍，但不能滥用。技术文档中不要出现“一‘逗’到底”的错误，即整个段落除了段落结尾外，全部停顿都使用逗号。

• 【错误示例】首先判断出错发生在 relay log 写入还是 binlog replication/syncer unit 同步（通过日志出错信息中的 component 信息即可判断），如果错误发生在 relay log 模块，binlog replication/syncer unit 保存的断点都是正确的情况，可以先停止任务，停止 DM-worker，手动调节 relay meta 的 binlog-position 到 4，重启 DM-worker 重新拉取 relay log ，relay log 写入正常后启动任务会自动从断点继续同步。
• 【正确示例】首先通过日志出错信息中的 component 信息，判断是在 relay log 写入阶段还是 binlog replication/syncer unit 同步阶段出错。如果错误发生在 relay log 模块，且 binlog replication/syncer unit 保存的断点都正确，则可以先停止任务和 DM-worker，手动调节 relay meta 的 binlog-position 到 4，再重启 DM-worker 重新拉取 relay log。relay log 写入正常后启动任务会自动从断点继续同步。

顿号

顿号的形式为“、”，表示中文句子内部两个及以上并列成分之间的短暂停顿，这里的并列成分通常指同类的单字、词语或短句。

英文中没有顿号，常用逗号来表示并列词语的停顿。因此对于英汉技术翻译者而言，更应该注意顿号的使用场景。

顿号的常见误用场景：

错误示例	正确示例	解释
此操作会关闭 TiDB，Pump，TiKV，PD 服务，并清空 Pump，TiKV，PD 数据目录。	此操作会关闭 TiDB、Pump、TiKV 和 PD 服务，并清空 Pump、TiKV 和 PD 的数据目录	TiDB、Pump、TiKV、PD 是并列词语，使用顿号作短暂停顿即可，不需要用逗号。
多角度、多侧面地观察分析事物，全方位，透视性地进行报道。	多角度、多侧面地观察分析事物，全方位、透视性地进行报道。	逗号虽然也可表示并列，但其停顿时间较长，如果并列词语之间顿号误用为逗号，会使语句松散，不便于语义的表述和朗读。
如何进一步增强政府的危机意识、增强政府应对突发事件的透明度，提高应对突发事件的能力，真正做到处变不惊、处置有序，需要完善有关的制度。	如何进一步增强政府的危机意识，增强政府应对突发事件的透明度，提高应对突发事件的能力，真正做到处变不惊、处置有序，需要完善有关的制度。	“增强政府的危机意识”和“增强政府应对突发事件的透明度”是分句，分句之间停顿时间较长，不能用顿号，应改为逗号。
我们学习茅盾先生，就应该像他那样，坚持为人民写作，深入社会实践，反映社会生活的创作原则，与时代同步、与人民同心。	我们学习茅盾先生，就应该像他那样，坚持为人民写作，深入社会实践，反映社会生活的创作原则，与时代同步，与人民同心。	顿号前后并非并列词语，而是分句，因此顿号要改为逗号。
资源等级结构（一次、二次、三次资源）比例失调，学科、地区分布不均衡、重复率过高等问题。	资源等级结构（一次、二次、三次资源）比例失调，学科、地区分布不均衡，重复率过高等问题。	这里误用顿号后，“学科、地区分布不均衡”与“重复率过高”成了并列词语，造成句子歧义。因此，要把“均衡”后的顿号改为逗号，使句子成为两个分句组成的复句。
在我们现代化建设面临人口、资源、环境的承受力趋向极限、以及国际竞争力更趋激烈的双重挑战的形势下，教育理应发挥促进社会、环境与经济可持续发展的功能。	在我们现代化建设面临人口、资源、环境的承受力趋向极限以及国际竞争力更趋激烈的双重挑战的形势下，教育理应发挥促进社会、环境与经济可持续发展的功能。	顿号的作用相当于“和”“跟”“及”“或者”等连词。如果并列词语较长，最后一项可用“和”“跟”“及”“或者”等连词连接，连词前可以加逗号。此时的逗号，不仅表示停顿，而且也是为了行文疏朗有间隔。但连词前不能使用顿号。因为在并列词语中，连词的作用等同于顿号。如果在连词前使用顿号，就等于连用了两个顿号。
任何教学大纲、教学方法、或者评估方法的不同，都可能培养出创新的思维。	任何教学大纲、教学方法或者评估方法的不同，都可能培养出创新的思维。	同上
通过 TiUP cluster 组件就可以进行日常的运维工作，包括部署、启动、关闭、销毁、弹性扩缩容、升级 TiDB 集群、管理 TiDB 集群参数。	通过 TiUP cluster 组件就可以进行日常的运维工作，包括部署、启动、关闭、销毁、弹性扩缩容、升级 TiDB 集群，以及管理 TiDB 集群参数。	有的并列词语内部又包含并列词语，形成多层次的并列词语。如果在多层次并列词语之间全用顿号，就使得并列词语之间的层次混乱，不利于理解。
在二十世纪六、七十年代，有关跨国公司向发展中国家收取了过高的技术转移费和向发展中国家转移了大量不适合发展中国家适用的技术的指责不绝于耳。	在二十世纪六七十年代，有关跨国公司向发展中国家收取了过高的技术转移费和向发展中国家转移了大量不适合发展中国家适用的技术的指责不绝于耳。	相邻的两个数字并列连用表示概数，必须使用汉字，连用的两个数字之间不得用顿号‘、’隔开。（来自《GB/T 15835―1995《出版物上数字用法的规定》》）
加强政府、企业、科研机构和学术团体的密切合作，以实现产、学、研的有机结合。	加强政府、企业、科研机构和学术团体的密切合作，以实现产学研的有机结合。	**有些简短的并列词语各项之间的联系很紧密，没有停顿，已成为不可分的整体，其内部不用顿号，并已约定俗成。**如“马列主义”“中小学生”“字词句”“产学研”“酸甜苦辣”等。
3、行政文明建设中的依法行政将直接推动我国依法治国方略的实现。	3. 行政文明建设中的依法行政将直接推动我国依法治国方略的实现。	阿拉伯数字作为序数词，如“1”后用点号而不用顿号；汉字“一”后用顿号，“第一”后面用逗号。这些是约定俗成的用法。
- “日”、“月”构成“明”字。 - 店里挂着“顾客就是上帝”、“质量就是生命”等横幅。 - 《红楼梦》、《三国演义》、《西游记》、《水浒传》，是我国长篇小说的四大名著。 - 李白的“白发三千丈”（《秋浦歌》）“朝如青丝暮成雪”（《将进酒》）都是脍炙人口的诗句。	**标有引号的并列成分之间、标有书名号的并列成分之间通常不用顿号。**若有其他成分插在并列的引号之间或并列的书名号之间（如引语或书名号之后还有括注），宜用顿号。	- “日”“月”构成“明”字。 - 店里挂着“顾客就是上帝”“质量就是生命”等横幅。 - 《红楼梦》《三国演义》《西游记》《水浒传》，是我国长篇小说的四大名著。 - 李白的“白发三千丈”（《秋浦歌》）、“朝如青丝暮成雪”（《将进酒》）都是脍炙人口的诗句。
- 我走之后，你要不断进步、识字、生产。 - 这个故事讲得美丽、动人。	- 我走之后，你要不断进步，识字，生产。 - 这个故事讲得美丽，动人。	并列的谓语，补语之间不用顿号，用逗号。

以上规范来自 8 例顿号误用解析 - 中国编辑校对网 以及顿号（标点符号）- 百度百科 等。

分号

分号的形式为“；”，表示复句内部并列分句之间的停顿。一般情况下，并列分句有三句或超过三句时，建议使用分号表示停顿。

【示例】Placement Driver（简称 PD）是整个集群的管理模块，其主要工作有三个：一是存储集群的元信息（某个 Key 存储在哪个 TiKV 节点）；二是对 TiKV 集群进行调度和负载均衡（如数据的迁移、Raft group leader 的迁移等）；三是分配全局唯一且递增的事务 ID。

冒号

冒号的形式为“：”。在技术文档中常用在需要解释的词语后边，表示引出解释和说明。

冒号在技术文档中常用来引出列表。

【示例】冯·诺依曼体系计算机的硬件系统分为五个部分：

• 运算器
• 控制器
• 存储器
• 输入设备
• 输出设备

一个句子内建议不要连续套用冒号。

• 【错误示例】计数系统：逻辑表示：1，计数器加一；0，计数器不变。
• 【正确示例】计数系统：1 表示计数器加一，0 表示计数器不变。

引号

引号分为直角引号和弯引号。直角引号为「」，弯引号有双引号和单引号两种形式。一般而言，技术文档中可以使用直角引号或弯引号，但必须保证所有文档的统一，禁止混用。

本节只讨论弯引号使用的一些规范，下文中使用的“引号”均表示“弯引号”。

• 引号内套用引号时，外面一层用双引号，里面一层用单引号。
• 技术文档出现报错信息、特定操作或名称、缩略语提示、特殊名词、引用文档的节选等时，建议使用引号。
  • 【正确示例一】启动集群或者升级集群过程中出现”Timeout when waiting for search string 200 OK”是什么原因？
  • 【正确示例二】Sysbench 按照“建表->插入数据->创建索引”的顺序导入数据。
  • 【正确示例三】如果 tidb-lightning 曾经异常退出，集群可能仍留在“导入模式” (import mode)，不适合在生产环境工作。此时需要强制切换回“普通模式” (normal mode)。
  • 【正确示例四】作为 NewSQL 数据库，TiDB 兼顾了传统关系型数据库的优秀特性以及 NoSQL 数据库可扩展性，以及跨数据中心（下文简称“中心”）场景下的高可用。
  • 【正确示例五】以下操作可能会形成一个“关系环”。
• 技术文档的正文中若涉及特定参数名称、字段名、界面字段等，建议使用引号（也可使用反引号）包裹。
  • 【正确示例一】在参数表中规定了 TMN 接口与支持这些接口的物理构件的关系，其中“M”表示必备，“O”表示可选。
  • 【正确示例二】具体命令请参见《Quidway S8016 路由交换机安装手册》中“1.2.1 安装步骤”的内容。
  • 【正确示例三】请设置如下三个参数：“Card Number”、“Password”、“Discount Rate”。

括号

括号的常用形式包括圆括号()、方括号[ ]、方头括号【】、尖括号<>（也称单书名号）以及花括号{}。其中技术文档中常用的是圆括号、方括号以及尖括号。

中文文档中一个词语或句子后紧跟的注释性文字，用圆括号进行注解。注释句子里某些词语时，圆括号放在被注释词语之后；注释整个句子时，圆括号放在句末标点之后。

• 【正确示例一】TiDB 使用周期性运行的 GC（Garbage Collection，垃圾回收）来进行清理。
• 【正确示例二】需要编辑配置文件以调整参数的值。（该方式不推荐使用）

一般来说，方括号和尖括号在技术文档中有以下几种特定用法。

• 方括号“[ ]”表示窗口名、菜单名等，如“弹出[新建任务]窗口”、“[显示/外观/全屏]多级菜单”。
• 带尖括号“< >”表示按钮名、键名等，如“点击<取消>按钮”、“<Tab> 表示制表键”。

书名号

书名号的形式为“《》”。书籍名、报刊名等名称需要用书名号标示。英文手册名称用中文双引号或斜体表示，不用书名号标示。

• 【示例一】《小王子》这本书有很多种语言版本。
• 【示例二】详情见“TiDB-Lightning 表库过滤”一文。

书名号中的文档名称建议使用全称，不使用简称。

• 【错误示例】具体操作请参见《表库过滤》。
• 【正确示例】具体操作请参见《TiDB Lightning 表库过滤》。

连接号

连接号表示某些相关联成分的连接关系。连接号的常见形式包括一字线“—”（占一个汉字的宽度）、短横线“-”（占半个汉字的宽度）和浪纹线“～”（占一个汉字的宽度）。

几种连接号的作用及用法示例如下表所示。

符号	用法举例
一字线 —	- 标示时间起止、空间起止或走向、序数起止等，如鲁迅（1881—1936）、2016—2020 年、1—3 月、北京—上海特快列车、秦岭—淮河线、13—15 号楼、第 50—100 条 - 在标准编号中连接顺序号与年号，如 GB/T 15835—2011 《出版物上数字用法》
短横线 -	- 在电话号码、门牌号、图表编号、阿拉伯数字年月日等各种复合名词中起连接作用，如学院路 15 号 2-1-201 室、图 2-1、表 3-4、2020-09-30、吐鲁番-哈密盆地 - 在外来语内部成分中起连接作用，如让-雅各·卢梭、盎格鲁-撒克逊人 - 表示某些产品的名称和型号，如 GC-50 型号设备
浪纹线 ～	标示数值范围：1～3 g、2～4 米、3～7 年内

粗略记忆方式：表示起止用一字线（—），表示范围用浪纹线（～），复合名词用短横线（-）。

破折号

破折号的形式为“——”，占两个汉字的宽度。技术文档中破折号常用于引出注释和说明部分。

【示例】于是新的数据库概念——NewSQL 数据库应运而生。

破折号前后不空格。

• 【错误示例】于是新的数据库概念 —— NewSQL 数据库应运而生。
• 【正确示例】于是新的数据库概念——NewSQL 数据库应运而生。

省略号

中文省略号的形式为“……”，有六个小圆点，占两个汉字的宽度。一般而言，中文语境中禁止使用英文省略号，即三个小圆点“…”（占一个汉字的宽度），必须使用六个小圆点“……”。

省略号主要在以下两种场景中使用。

• 引文的省略，用省略号标明。

  【示例】中文写作规范中要求：“句号常用于陈述句末尾的停顿。在产品资料中常用于简单句和复合句的结尾，表示句子意思已完整……”

• 列举的省略，用省略号标明。

  【示例】分支选择支持所有类型的分区表，无论是 range 分区或是 hash 分区等。对于 hash 分区，如果没有指定分区名，会自动使用 p0、p1、p2、……、或 pN-1 作为分区名。

感叹号

技术文档中使用感叹号建议遵循以下规范。

• 尽量使用平静的语气叙述，避免使用感叹号。
• 禁止多个感叹号连用，比如“！！”等。

斜杠与反斜杠

斜杠（slash 或 forward slash）的符号是“/”，表示分隔符。反斜杠 (backslash) 的符号是“\”，表示转义字符。反斜杠一般只出现在代码中，因此本节主要讨论斜杠的使用。

斜杠有如下几种用法。

• 表示除法，如 120/60 = 2
• 表示单位（除法的变形），如 60 km/h
• 表示“或”，如他/她。注意：如果需要表示多个并列项，不建议使用“/”连接，建议使用顿号连接。
  • 【错误示例】高可用是 TiDB 的另一大特点，TiDB/TiKV/PD 这三个组件都能容忍部分实例失效，不影响整个集群的可用性。
  • 【正确示例】高可用是 TiDB 的另一大特点，TiDB、TiKV 和 PD 这三个组件都能容忍部分实例失效，不影响整个集群的可用性。

斜杠的两旁不建议加空格。

• 【错误示例】do / ignore 规则
• 【正确示例】do/ignore 规则

反引号

注：本节只讨论出现在 Markdown 文档中的反引号情况。

反引号 (backtick) 的符号是“`”，一般在英文输入法下由键盘左上角 Tab 键上方的按键键入。

反引号有如下两种用法。

用法种类	单个反引号包裹单行元素	三个反引号包裹多行元素
作用	强调包裹的部分，与正文内容区分	- 便于展示多行代码 - 强调包裹的部分，与正文内容区分 - 在 Markdown 语法中，前面的 ``` 后若指明代码块中的语法，可高亮代码块
示例	time_zone` 的默认值是 `System	<三个反引号> create table t (ts timestamp, dt datetime); SELECT * FROM t1; <三个反引号>
适用情况	以下元素需要使用单个反引号包裹： - 变量名 - 变量的值 - 语法名称 - 命令或代码 - 配置项名 - 字段名 - 其他需要强调的名称，如文件名、表名、列名、库名、数据类型名称等	以下元素需要使用三个反引号包裹： - 多行代码块（多行 SQL 语句、多行 bash 命令等） - 代码执行结果 - 配置文件中的多行配置

中文标点使用

使用中文标点符号建议遵循以下规范。

• 中文语境下的标点符号一律使用全角形式（即中文输入法下的标点符号），不得使用半角形式（即英文输入法下的标点符号）。

• 中文全角标点符号两旁禁止空半角空格。示例：

  • 【错误示例】如果 CPU 设有限额 （从 K8S 指定的上限） ，则需要手动调整。
  • 【正确示例】如果 CPU 设有限额（从 K8S 指定的上限），则需要手动调整。

• 句号、问号、叹号、逗号、顿号、分号、冒号、结束引号、结束括号等标点不能出现在一行的开头。

  • 【错误示例】

    排版时注意某些
    符号不能在行首
    ，别弄错了。
    

  • 【正确示例】

    排版时注意某些
    符号不能在行首，
    别弄错了。
    

• 开始引号、开始括号、开始双书名号等标点不能出现在一行的结尾。

  • 【错误示例】

    她对我们说：“
    这书太赞了。”
    

  • 【正确示例】

    她对我们说：
    “这书太赞了。”
    

中英文混用时标点符号用法

中文技术文档中有时会出现英文，此时，不仅会使用全角形式的中文标点，也可能使用半角形式的英文标点，因此在中英文混用时应着重注意标点符号的用法。

本节介绍中英文交接处使用标点符号的建议规范。

根本原则

中文技术文档主要服务的是中文文本，应该以中文标点符号为主，以英文标点符号为辅。

基本规范

1. 中文句子内夹用英文单词或词组时：
   • 夹用的英文单词或词组可不用中文引号包裹。
   • 如果夹用的英文单词或词组本身带有英文标点，保留其英文标点。
   • 中文句子句末均以中文标点符号结尾。
2. 中文句子内夹用英文句子时：
   • 用中文引号包裹引用该英文句子。
   • 如果夹用的英文句子本身带有英文标点，保留其英文标点。
   • 中文句子句末均以中文标点符号结尾。

基于上面的基本规范，下表给出不同标点符号用法的例句：

标点符号	【中文句子内夹用英文单词或词组时】标点用法例句	【中文句子内夹用英文句子时】标点用法例句
句号	- change 和 transform 意义不同。 - 建议叫上 Jane。	- “I like you.（我喜欢你。）”与“I love you.（我爱你。）”的份量不一样。 - 他说的是“Jane, you can do it.”。
逗号	这个数据库的官方描述是“open-source, distributed SQL database”。	他们的官方文档上写着“Try it out, and you will get a 10% discount.”。
问号	distributed SQL 在这里是什么意思？	他伸出手说“Need a hand?”，这句话的意思是“Do you need help?”？
叹号	不要总是对女孩说“Pretty!”！	他站在那，感叹了句“What a beautiful scene!”。
顿号	be 动词包括 is、are、were、was 等。	“He is man.”、“He is a man.”和“He is the man”的区别是什么？
分号	如果想表示更礼貌的语气，用 might；反之，用 may。	官方文档上说“To deploy the database, use the TiUP tool; to migrate data, use the DM tool.”。
冒号	- 官网有个首页按钮失效了：Newsletter。 - TiDB: The Future of Databases 是一篇主题分享博客。	- 文档站的右上角写着：Try it now。 - Bilibili: How We Use a Distributed SQL Database 是一篇案例分享。
引号	将来时态一般由“will + 动词原形”组成。	这篇文章里有句话比较难理解：“The saint said, 'Follow your fear.'”。
破折号	这个符号表示禁止——stop。	“Well—emm, I don't know how to say—but I hope you can understand my position.”他纠结地说。
省略号	使用 so...that... 句型表示结果，意思是“如此……以致……”。	“I don't know how to say this...”的意思是“我不知道该怎么说了……”。

补充规范

除了两条基本规范外，本节介绍一些补充规范。

英文标题或引文中的结尾符号

• 英文标题或引文中的结尾问号必须保留
  • 【示例一】这篇文档的标题“How to Migrate Data from MySQL?”可以改为“How Do You Migrate Data from MySQL?”。
  • 【示例二】这个推文的第一句“Why do you migrate data from MySQL?”问得不够清楚。
• 英文标题或引文中的结尾叹号必须保留
  • 【示例一】“A little book of language!”一文受到了很多好评。
  • 【示例二】“加勒比海盗”的电影中的海盗总是说“Aye! Aye!”。

中英文括号的使用

中英文混用时使用括号建议遵循以下规范。

• 括号里全为英文时建议使用半角括号，并在括号前后各空一个半角空格，括号和括号内的英文之间不需要空格。
  • 【错误示例一】数据定义语言（DDL）是一种……（使用了全角括号）
  • 【错误示例二】数据定义语言(DDL)是一种……（半角括号前后未空格）
  • 【错误示例三】数据定义语言 ( DDL ) 是一种……（半角括号和半角括号内的英文之间空了一格）
  • 【正确示例】数据定义语言 (DDL) 是一种……
• 括号里既有中文又有英文（即只要括号内包含任何中文）时建议使用全角括号，括号前后不空格。
  • 【错误示例】斜杠 (slash 或 forward slash) 和反斜杠 (backslash) 是两种符号。
  • 【正确示例】斜杠（slash 或 forward slash）和反斜杠 (backslash) 是两种符号。

英文书籍、报刊、标题的引用方法

• 中文句子中夹用英文书籍或报刊名时，不能使用中文书名号《》，而应使用斜体字表示，如果无法使用斜体字，建议使用中文引号包裹引用。
• 英文文章的标题用中文引号包裹引用。

【示例】New York Times 发布了一篇新文章，标题是“Cloud is Eating the World”。