基于半角标点符号的中文技术性文档格式化标准 #

本文档中的 "必须" (MUST), "禁止" (MUST NOT), "应该" (SHOULD), "不应该" (SHALL NOT), "可以" (MAY) 等能愿动词依照 RFC 2119 中的叙述进行解释.

摘要 #

本标准是一份适用于中文技术性文档撰写的文本格式化规范, 覆盖于常识性语言文字编排及标点符号使用的习惯及共识之上. 与大部分同类规范性指南不同的一点是, 本标准的所有标点符号由半角标点构成. 从社区的中文技术性文本的符号使用习惯来看, 半角标点已经在少数撰写者中得到采用. 本标准旨在基于半角标点格式化规范的制定, 整合此类撰写者之间其他的排版共识, 构造一份完整的中文技术性文档格式化标准.

目录 #

1. 文档结构 #

a) 一篇文章最高只允许出现四级标题:

一级标题: 文章的标题;
二级标题: 文章主要部分的大标题;
三级标题: 二级标题下面一级的小标题;
四级标题: 三级标题下面某一方面的小标题.

如果四级标题划分的文段篇幅较短, 则建议不使用四级标题, 而是使用段首句等方法来划分部分.

❌ 错误示例:

# 如何使用 FooBar
## 安装
### 使用 Docker 安装
### 使用包管理器安装
#### Arch
#### Debian
##### Debian 10
...

##### Debian 11
...

✔️ 正确示例:

# 如何使用 FooBar
## 安装
### 使用 Docker 安装
### 使用包管理器安装
#### Arch
#### Debian 仓库
- Debian 10: ...
- Debian 11: ...

或

# 如何使用 FooBar
## 安装
### 使用 Docker 安装
### 使用包管理器安装
#### Arch
#### Debian 仓库
Debian 10 用户可以使用...

Debian 11 用户可以使用...

b) 单篇文章的一级标题必须位于文章之首, 且禁止出现超过 1 次.

❌ 错误示例:

# 如何使用 FooBar
# 安装
# 配置

✔️ 正确示例:

# 如何使用 FooBar
## 安装
## 配置

c) 禁止出于强调目的或仅为了创造大号粗体文字而滥用标题样式.

❌ 错误示例:

## 再次声明一下, 本项目生成的文章真的狗屁不通, 只能拿来搞笑, 请不要用于正规用途!
## 再次声明一下, 本项目生成的文章真的狗屁不通, 只能拿来搞笑, 请不要用于正规用途!
## 再次声明一下, 本项目生成的文章真的狗屁不通, 只能拿来搞笑, 请不要用于正规用途!

d) 段落之间必须有 1 个空行的间隔. 每一段的段首禁止缩进.

❌ 错误示例:

	这是第一段.
	这是第二段.

✔️ 正确示例:

这是第一段.
	
这是第二段.

请注意, 这意味着只有空行 (连续 2 个换行符) 才是段落结束的标志. 单个换行符不是段落结束的标志. 例如,

在终端中, 运行
	foobar --port 4800
即可在 4800 端口启动 FooBar.

和

FooBar 的子类包括
- SubFoo,
- SubBar,
- SubFooBar.

都是一个段落.

2. 文字 #

a) 在表意文字和表音文字 (包括数字) 之间, 必须有 1 个半角空格的间隔.

❌ 错误示例:

HTML常与CSS和JavaScript一起被众多网站用于设计网页.

✔️ 正确示例:

HTML 常与 CSS 和 JavaScript 一起被众多网站用于设计网页.

b) 中文句子中的外文单词应该使用原形.

❌ 错误示例:

许多现代 CPUs 都有集成电源管理模块.

✔️ 正确示例:

许多现代 CPU 都有集成电源管理模块.

c) 专有名词应保持规范大小写.

❌ 错误示例:

编译器可以将 typescript 编译为可以在任何 javascript 引擎 (如浏览器) 中执行的标准 js.

✔️ 正确示例:

编译器可以将 TypeScript 编译为可以在任何 JavaScript 引擎 (如浏览器) 中执行的标准 JS.

如果某一专有名词习惯以小写字母开头, 则即使该专有名词位于句首, 也可以使用小写字母开头.

✔️ 正确示例:

systemd 是一个相当重要的组件, 但是它并没有内核 (Linux) 那么重要, 也没有整个系统的基础 (GNU) 那么重要.

d) 禁止将某一特定专有名词用作动词来泛指一类行为.

❌ 错误示例:

你可以 Google 这个问题.

✔️ 正确示例:

你可以使用在搜索引擎上搜索这个问题.

3. 标点符号 #

a) 所有标点符号必须为半角标点符号, 禁止出现全角标点符号.

❌ 错误示例:

因为历史原因，我们的文档，即 Graia Document 目前急需改进和完善，如果有意愿，欢迎提起 Pull Request。

✔️ 正确示例:

因为历史原因, 我们的文档, 即 Graia Document 目前急需改进和完善, 如果有意愿, 欢迎提起 Pull Request.

b) 对于除引号和括号外的每一个标点符号, 其后如果有文字或数字, 则必须在这个标点之后增加 1 个半角空格的间隔.

❌ 错误示例:

在 JavaScript 中,被称为 this 的事物,指的是拥有该 JavaScript 代码的对象.

✔️ 正确示例:

在 JavaScript 中, 被称为 this 的事物, 指的是拥有该 JavaScript 代码的对象.

对于引号和括号, 其内两侧禁止增加半角空格; 外两侧应该增加 1 个半角空格.

❌ 错误示例:

GNU's Not Unix(简称 GNU)是一个自由的操作系统.
GNU's Not Unix (简称 GNU)是一个自由的操作系统.
GNU's Not Unix(简称 GNU) 是一个自由的操作系统.
GNU's Not Unix ( 简称 GNU ) 是一个自由的操作系统.

✔️ 正确示例:

GNU's Not Unix (简称 GNU) 是一个自由的操作系统.

c) 对于标点符号的叠加, 同一符号必须只重复 3 次.

❌ 错误示例:

程序崩溃的罪魁祸首竟然是...... 空指针异常!!

✔️ 正确示例:

程序崩溃的罪魁祸首竟然是... 空指针异常!!!

d) 作为前一项的例外, 符号 -- 用于引出人名.

✔️ 正确示例:

我们可以进行意识形态的斗争, 因为我们在这方面占优势.
-- Edward Snowden

4. 数字 #

a) 表示数值, 必须使用半角的阿拉伯数字.

❌ 错误示例: ３０１, ４０４.

✔️ 正确示例: 301, 404.

b) 表示数值范围, 必须使用 - 连接两个数值. 作为第 3 节 b 项的例外, 连接符号前后禁止出现空格.

❌ 错误示例: 0~3, 60 - 90.

✔️ 正确示例: 0-3, 60-90.

c) 在数值中, 文字单位与数字之间必须有 1 个半角空格的间隔.

❌ 错误示例: 2千克, 50ms.

✔️ 正确示例: 2 千克, 50 ms.

非文字单位与数字之间禁止出现空格.

❌ 错误示例: 90 °, 66.67 %, $ 5.

✔️ 正确示例: 90°, 66.67%, $5.

d) 在数值范围中, 文字单位必须只出现在第二个数字后, 除非两个数字的单位不同.

❌ 错误示例: 300ms-1000ms.

✔️ 正确示例: 300-1000 ms, 300 ms-1 s.

非文字单位必须在每个数字都出现一次.

❌ 错误示例: 45-60°, 80-90%, $5-10.

✔️ 正确示例: 45°-60°, 80%-90%, $5-$10.

A. 常见全角标点符号对应的半角形式 #

全角	，	。	、	：	；	？	！	（）	“ ”	‘ ’
半角	,	.	､	:	;	?	!	( )	"	'

注:

半角顿号确实存在, 但是本标准不使用之.
实际上, 表中列出的 "全角" 引号并非真正的全角. 第一行中的引号称为弯引号, 前后符号不同. 第二行中的引号称为直引号, 不区分前后. 弯引号看起来是全宽还是半宽, 取决于字体的设计. 因此, 在中文字体中, 弯引号看起来才会像是全角符号. 在英文中, 弯引号有时也会被使用, 并且看起来是半宽的. 本标准不限制你使用弯引号还是直引号.

B. 常见疑难解答 #

1. 不使用书名号, 如何引用作品名? #

由于本标准不会向全角符号妥协, 以下是一些解决方案.

a) 避免直接使用该专有名词.

✔️ 正确示例:

余光中在[这篇文章][1]中说, 目前中文的一大危机是西化.
	
[1]: https://open.leancloud.cn/improve-chinese/

b) 如果某一专有名词有惯用的英文名或由类似的表音文字组成的名称, 则可以直接使用该名称.

✔️ 正确示例:

Genshin Impact 成瘾性强, 不断迫使玩家花钱, 用战利品箱压制游戏体验.

c) 如果某一专有名词在被引用时习惯不附带书名号, 则可以避免使用书名号.

d) 如果上述方案都没有捕获问题的情况, 则直接使用双引号嵌套.

2. 不使用顿号, 如何并列多个成分? #

把逗号用作顿号.

参考 #

Hyphen vs. Dashes: When to Use and How to Type by Kevin Pollock
How to Write About Ranges by Mark Nichol
https://www.zhihu.com/question/19616011?rf=20602829

本页面以 CC0 1.0 发布至公有领域.