基于半角标点符号的中文技术性文档格式化标准
本文档由 Peaksol 撰写, 并以 CC0 1.0 通用 (CC0 1.0 Universal) 发布至公有领域.
本文档中的 "必须" (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 Snowden4. 数字
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
To the extent possible under law, the person who associated CC0 with this work has waived all copyright and related or neighboring rights to this work.