zhlint 0.3.2

automated checker of chinese document.

# zhlint

Note: This project is highly related to Chinese, so the document is writtern in Chinese.

## 简介

一个处理文档风格的工具：

* 支持文档风格的检查（使用 `check` 命令）。
* 支持文档风格的自动修复（使用 `fix` 命令）。

注意：

* 目前仅支持 Markdown 格式文档的检测与修复。

## 安装与使用

### 使用 pip 安装

```
pip install zhlint
```

安装成功后，可执行 `zhlint` 命令行程序处理文档。

### 检查文档风格

`zhlint check SRC` 命令会检查输入 `SRC`，并将检测到的文档风格错误输出到 stdout。参数 `SRC` 可为：

* 文件路径。
* `-`，表示 stdin。

示例如下：

```shell
$ ccat doc.md
只有中文或中英文混排中,一律使用中文全角标点. 英文 **english**与非标点的中文之间需要有一个空格。

支持简单的错误名词检测，如 APP、ios 这类的。
$ zhlint check doc.md
==========================================
E101: 英文与非标点的中文之间需要有一个空格
==========================================
LINE: 1
角标点. 英文 english与非标点的中文之间需
　　　 　　 -－
........................................

==================================================
E201: 只有中文或中英文混排中，一律使用中文全角标点
==================================================
LINE: 1
中文或中英文混排中,一律使用中文全角标
　　　　　　　　　-
.....................................
LINE: 1
律使用中文全角标点.
　　　　　　　　　-
...................

==================
E301: 常用名词错误
==================
LINE: 3
的错误名词检测，如 APP、ios 这类的。
　　　　　　　　　 ---
....................................
LINE: 3
名词检测，如 APP、ios 这类的。
　　　　　　 　---
..............................

```

### 修复文档风格

`zhlint fix SRC [DST]` 命令会尝试修复 `SRC` 中出现的风格错误，参数 `SRC` 可以为文件路径或者 `-`：

* 如果省略 `DST`，修复后的文本将打印到标准输出。
* 如果传入 `DST`，修复后的文本将写入到 `DST`。


示例如下：

```shell
$ zhlint fix doc.md
只有中文或中英文混排中，一律使用中文全角标点。 英文 **english** 与非标点的中文之间需要有一个空格。

支持简单的错误名词检测，如 App、iOS 这类的。
$ zhlint fix doc.md fixed-doc.md
$ colordiff doc.md fixed-doc.md
1c1
< 只有中文或中英文混排中,一律使用中文全角标点. 英文 **english**与非标点的中文之间需要有一个空格。
---
> 只有中文或中英文混排中，一律使用中文全角标点。 英文 **english** 与非标点的中文之间需要有一个空格。
3c3
< 支持简单的错误名词检测，如 APP、ios 这类的。
---
> 支持简单的错误名词检测，如 App、iOS 这类的。
```

## 支持的检查项目

| 错误码 | 检查范围 | 描述 |
| ------ | -------- | ------------------------------------------------------------------------------ |
| E101 | 段落 | 英文与非标点的中文之间需要有一个空格 |
| E102 | 段落 | 数字与非标点的中文之间需要有一个空格 |
| E103 | 段落 | 除了`％`、`℃`、以及倍数单位（如 `2x`、`3n`）之外，其余数字与单位之间需要加空格 |
| E104 | 段落 | 书写时括号中全为数字，则括号用半角括号且首括号前要空一格 |
| E201 | 句子 | 只有中文或中英文混排中，一律使用中文全角标点 |
| E202 | 句子 | 如果出现整句英文，则在这句英文中使用英文、半角标点 |
| E203 | 段落 | 中文标点与其他字符间一律不加空格 |
| E204 | 句子 | 中文文案中使用中文引号`「」`和`『』`，其中`「」`为外层引号 |
| E205 | 段落 | 省略号请使用`……`标准用法 |
| E206 | 段落 | 感叹号请使用`！`标准用法 |
| E207 | 段落 | 请勿在文章内使用`~` |
| E301 | 段落 | 常用名词错误 |

详情见 [写作规范和格式规范，DaoCloud 文档](http://docs-static.daocloud.io/write-docs/format)。

以下是各项错误的简单示例。其中，*触发样例* 是违反规则的实例，*非触发样例* 是符合文档风格的实例。

### E101

描述：英文与非标点的中文之间需要有一个空格。

触发样例：

```
中文english
中文 english
中文\tenglish
```

非触发样例：

```
中文 english
```

### E102

描述：数字与非标点的中文之间需要有一个空格。

触发样例：

```
中文42
中文 42
```

非触发样例：

```
中文 42
```

### E103

描述：除了`％`、`℃`、以及倍数单位（如 `2x`、`3n`）之外，其余数字与单位之间需要加空格。

触发样例：

```
42μ
42 μ
```

非触发样例：

```
42 μ
42x
42n
42％
42%
42℃
Q3
136-4321-1234
word2vec
```

### E104

描述：书写时括号中全为数字，则括号用半角括号且首括号前要空一格。

触发样例：

```
中文(42）
中文（42)
中文（42）
中文(42)
中文 (42)
(42)
```

非触发样例：

```
中文 (42)
(42)
```

### E201

描述：只有中文或中英文混排中，一律使用中文全角标点。

触发样例：

```
有中文, 错误.
中文'测试'
中文"测试"
LaTeX 公式 $$.
LaTeX 公式,$$
LaTeX 公式 \(\).
LaTeX 公式,\(\)
```

非触发样例：

```
有中文，正确。
有中文，正确......
P.S. 这是一行中文。
LaTeX 公式 $$
LaTeX 公式 \(\)
邮箱：[e-mail]
有中文，1.0
有中文，www.google.com
链接地址 http://google.com
```

### E202

描述：如果出现整句英文，则在这句英文中使用英文、半角标点。

触发样例：

```
pure english，nothing wrong。
```

非触发样例：

```
pure english, nothing wrong.
```

### E203

描述：中文标点与其他字符间一律不加空格。

触发样例：

```
中文， 测试
中文 。测试
「 中文」
```

非触发样例：

```
中文，测试
中文；测试
「中文」
```

### E204

描述：中文文案中使用中文引号`「」`和`『』`，其中`「」`为外层引号。

触发样例：

```
中文‘测试’
中文“测试”
```

非触发样例：

```
中文「测试」
```

### E205

描述：省略号请使用`……`标准用法。

触发样例：

```
中文...
中文.......
中文。。。
```

非触发样例：

```
中文......
```

### E206

描述：感叹号请使用`！`标准用法。

触发样例：

```
中文!!
中文！！
中文!！
中文??
中文？？
中文？?
```

非触发样例：

```
中文!
中文！
中文?
中文？
```

### E207

描述：请勿在文章内使用`~`。

触发样例：

```
中文~
```

非触发样例：

```
中文
```

### E301

描述：常用名词错误。

触发样例：

```
APP
app
android
ios
IOS
IPHONE
iphone
AppStore
app store
wifi
Wifi
Wi-fi
E-mail
Email
PS
ps
Ps.
```

非触发样例：

```
App
Android
```