LWN：改进英文文档质量的工具！

关注了就能看到更多这么棒的文章哦～

Tools to improve English text

June 16, 2020
This article was contributed by Martin Michlmayr
原文来自：https://lwn.net/Articles/822969/

Open-source开发者非常重视质量，并创造了许多工具来改进源代码，如各种linter工具和各种代码格式化工具。而另一方面，文档却没有得到应有的重视。早在2016年，LWN就对几个语法和风格检查工具进行了评测。现在似乎是时候再来评估一下这一领域的进展了。

spell checker（spell checker）看起来似乎是个太基本的工具了，都不值得一提。但是，考虑到我在开源文档中见到过的错别字的数量，其实很是值得好好看看spell checker的。技术文档都有一个特点，英文字句经常与会导致拼写检查报错的代码或URL混在一个文件中。Aspell提供了几种过滤模式（0.60.8版本还支持了Markdown），但Hunspell工具认为应该是让其他工具（如编辑器editor）来做区分代码和文本的工作。这里PySpelling就有用武之地了。它提供了过滤器（filter），使其能够轻松地在格式化文本（如Markdown）或编程语言（从Python代码中提取docstrings）上运行拼写检查程序而不受干扰。PySpelling在创建时的一个目标就是能将拼写检查加入到持续集成（CI，continuous integration）系统中，这个目标会非常受欢迎。

说到spell check和编辑器，写这篇文章的时候倒提醒我了，尽管我经常使用spell checker，但我从来没有在我的编辑器中配置打开拼写检查。Vim内置拼写检查程序已经有很长一段时间了。不过一个小缺陷是，Vim依赖自己的单词列表，而不是使用Aspell和Hunspell的系统全局的字典。通过下面的配置，Vim会在Markdown文本和Git commit message中对拼写错误和未知的单词使用下划线标注出来：

set spelllang=en autocmd FileType markdown setlocal spell autocmd FileType gitcommit setlocal spell

尽管我将本文中的几个工具集成到了我的工作流程中，但我对会有多大帮助其实抱有疑虑。同样，Vim的异步Lint引擎(ALE，Asynchronous Lint Engine)插件(见下图)在我打字的时候也会调用本文中的几个语法工具。其中一些工具其实一直会有一些误报，所以还需要观察一段时间来看看它们是否真的会改善我的写作，或者是会不断分散我的注意力去处理工具误报问题。

虽然spell checker很有用，但检查文档是非常耗时的，而且一些拼写错误的单词很容易被忽略。Debian 软件包检查程序 lintian 提供了一个经常拼写错误的单词列表，spellintian 脚本就会利用这些单词来帮助检查。这非常有效，几乎没有误报 (除了重复词的检查，主要是因为代码和段落的开头与此前紧挨着的标题（heading）是用相同的词而导致的)。根据我的经验，即使在运行了另一个拼写检查程序之后，再使用spellintian也经常能发现一些拼写错误的单词。Linux 内核已经在它的 checkpatch.pl 脚本中采用了这个单词列表的某个版本，在我看来， spellintian 很有可能可以集成到 CI 的工作流程中去。

Beyond words

单词（word）只是一个基本构件，重要的是我们如何将它们组合在一起。许多英文文章linter工具都有的一个问题是，它们很难区分客观错误（objective mistakes, 如真正的语法问题）和有关写作风格的主观问题（subjective matters）。前者有个常见的例子就是错误地使用不定冠词（a和an）。虽然这些都是有明确规则的，但无法用简单的正则表达式来检测出问题，因为正确的不定冠词取决于单词的发音，而不是它的书写方式。我开始调查自然语言工具箱（NLTK，Natural Language Toolkit）是否可以帮助人们解决这个问题。但后来我看到Jakub Wilk多年前就有这样的想法，他创建了anorack（见下图），利用eSpeak将单词分解成音素（phonemes，声音单位）来识别不定冠词的使用错误。

小编的脾气不太好，在2016年对proselint进行评测的时候将其比作 "世界上最糟糕的小学老师之一，当着全班同学的面批评你的一些无关紧要的细节"。我现在也想看看这位老师是否已经成长了，但很可惜，这个项目从2018年之后就一直不再活跃了。不过有好几个其他工具跟它很像。一个是alex，它的目的是把文章中insensitive（不敏感）和incosiderate（不体贴）的写法挑出来。虽然alex在某些情况下很有用（例如，将 "chairman "改为 "chair "或 "chairperson "是一个很好的改进，不会让部分人介意），但我发现这个工具太嘈杂了。在技术文章中，它会报出许多 "simple math "和 "invalid characters"的错误（尽管 "basic math"检查可能确实是有好处的）。计算机擅长模式匹配，但语言总是有其上下文context的。文档中提到 "alex不是很聪明"，我也赞同这个看法（有趣的是，alex并不觉得这句话会冒犯它）。

另一个工具是write good，它可以标记 "weasel"词（比如 "very"这种词）和被动语态（passive voice）。LWN曾经研究过Emacs的writegood-mode。就我个人而言，我并不觉得write-good的反馈有多大用处，但在被动语态方面还是挺好的。

RedPen看起来是proselint的一个可靠替代品。它特别注重了技术文档，并且支持几种常见的标记格式，包括Markdown、Textile、AsciiDoc、reStructuredText和LaTeX。安装步骤就碰到了麻烦。我找不到Debian或RPM包，也没有Flatpak，而且Snap镜像是2016年的（而这个工具在今年早些时候还发布了新版本）。

当我在等待下载150MB的文件时，我发现了一个RedPen的在线服务（http://redpen.herokuapp.com/ ），可以将文本复制到其中来检查。这个在线版本特别有用，因为这样一来就可以很轻松地禁用语法检查。人们不需要了解配置文件，只需勾选一些复选框即可。显然，如果文本内容非常私人，或者有太多令人尴尬的错误的话，在线服务并不非常适合。我还看到一个PyRedPen，这是一套Python脚本，可以将文件发送到RedPen的这个在线服务进行分析。用pip安装PyRedPen后，可以这样运行：

redpen-flymake -e -m guide.md.

马上就给我一个不太满意的结果：3500 字的文档中有 600 多个问题。

当我下载完RedPen后，我发现不用担心它没有现成的Linux发行版的软件包。RedPen主要是由JAR文件、一些配置文件和脚本（包括bin/redpen）组成的，我用了-f markdown参数来调用bin/redpen。从这600多个结果来看，如果排除拼写问题的话就只剩280个，这还是可以让人愿意进行一些处理的。有几个建议是真的很有用。例如RedPen 会突出显示句子中重复的短语。虽然这会导致一些误报，但它可能会有帮助，例如指出 "a lot "在一个句子中被多次使用。

RedPen还指出我另一个文档中有35%的句子是以相同的短语开始的，这是一个很好的改进建议。尽管RedPen支持各种markup format，但相关检查还不够智能。例如，一个技术文档中的code element SUM(COST(position))导致了两个警告："word"") "重复了两次，以及"括号内的句子嵌套太深"。不过总的来说，RedPen看起来很有前途，我也许可以通过关闭一些检查来改善结果。

之前LWN的一篇文章介绍了LanguageTool。它支持20多种语言，鉴于每种语言都可能要用不同的规则，能支持这么多种语言是很惊艳的。它还有Firefox和LibreOffice的插件。LanguageTool是多个JAR文件组成的，只需启动languagetool-commandline.jar即可，非常方便。我第一次运行该工具时，系统的表现就像我在同一时刻打开Chromium和Firefox一样。在随后的使用过程中，资源使用状况一直很好，尽管确实有点慢。

LanguageTool不支持markup format，几乎所有的警告都跟相关的Markdown内容有关。不幸的是，即使是纯文本内容会有许多假警报，例如抱怨有些单词中间包含了下划线（这对于像变量名称这样的标识符来说很常见）。尽管如此，LanguageTool还是注意到了文本内容的一些真正问题。它突出显示了一个以连词开头的句子，这个句子本应与前一个句子用逗号分开的。它还指出了一些通常用连字符（-符号）来拼写的单词。

LanguageTool真正强大的地方在于它的数据集。如上所述，语言取决于上下文。它有一个针对英语的8GB的可选数据包，这能让LanguageTool找到额外的错误，比如建议 "Don't forget to put on the breaks"中的最后一个词应该是 "brakes"。与RedPen一样，我认为LanguageTool还是挺有希望的，可以整合到个人写作过程中。这两款工具看起来都太嘈杂了，不适合随时检查，但它们很适合在写完一篇文章后对重点部分进行检查。

Open-source uniformity

最后，我发现了Vale，这是一个有趣的工具，因为它并不关注语法正确性本身，而是关注写作的风格。Vale的介绍文章（https://medium.com/@jdkato/introducing-vale-an-nlp-powered-linter-for-prose-63c4de31be00 ）展示了个人作者使用proselint和write-good这类工具在协作撰写文档中改进他们写出来的内容，而使用Vale确保遵循组织特有的风格、语气和品牌特性。

open source的魅力在于它的天性——协作性，它是基于许多贡献者的输入信息。不幸的是，这常常会导致文档中出现不一致的地方，例如不同的写作风格或大写字母使用习惯。Vale允许定义一个特定的风格规范（style guide），并确保执行。Vale提供了微软写作风格指南和谷歌开发者文档风格指南。它使用了一个YAML文件，从而非常易于定制配置。

Vale在markup format上的表现也非常好。当大多数工具利用markup的语法规则来忽略文本的某些部分（如代码元素）时，Vale会认出这些语法标记，并对某些语法结构来使用规则。例如，Vale可以用来确保标题中的所有单词都以大写字母开头。除了markup支持和可扩展性以外，Vale还强调它的性能是一个关键优势，我的初步测试也证实了这一点。

检查普通文章部分是很困难的，部分原因是人类语言很复杂，取决于上下文，但也有部分原因是，其实人们对什么是 "right "和 "wrong "还有很多分歧。这里介绍的工具提供了一些有见地的反馈，但所有的结果往往是有很多噪声的，以至于需要花费很多时间才能找到真正关心的东西。我已经将spellintian和anorack加入了我的工具箱，并对我从GitHub下载的几乎所有仓库都会执行一下这两个工具。

在语法工具方面，我打算利用一下RedPen和LanguageTool。由于Vim的ALE插件在我写作时会实时运行这些工具来检查，在我的编辑过程中不断得到各种提醒、报警。我的结论是，这些反馈太让人分心了。更好的方法是在写好初稿后将它们作为抽查（spot check）工具。Vale看起来很有希望改善开源文档的一致性，这也是我想更详细探索的工具。

在过去的几年里，我们已经看到了在代码合入之前对代码质量的检查方面都有重大进步。如今，很少看到提交之后几分钟再来提出一个commit来修复编译问题的情况了。我希望能看到类似的系统在文档质量检查方面应用起来：错别字、语法问题、留白，还有style风格。它们必须能对大家达成一致的问题给出确定的反馈，这样它们才能被集成到continuous integration持续集成系统中，而不是总是产生报告之后被人忽略。

全文完

LWN文章遵循CC BY-SA 4.0许可协议。

欢迎分享、转载及基于现有协议再创作～

长按下面二维码关注，关注LWN深度文章以及开源社区的各种新近言论～