textlintを使って校閲を自動化する

textlintのインストール

nodeがインストールされた環境で、次のコマンドを実行するとインストールできます。

$ mkdir textlint-test
$ cd textlint-test
$ npm init # 対話形式で諸々入力を求められるが全てデフォルトでOK
$ npm install textlint

textlint-rule-preset-ja-technical-writingをインストール

textlint-rule-preset-ja-technical-writingは技術文書向けのtextlintルールプリセットです。技術文書に特化して文章を校閲をしてくれます。

次のコマンドを実行してインストールします。

$ npm install textlint-rule-preset-ja-technical-writing

インストールが完了したら、.textlintrc を作成してルールを有効化しましょう。

{
  "rules": {
    "preset-ja-technical-writing": true,
  }
}

textlintを実行する

準備ができたので、textlintを実行してみましょう。

今回はこちらの記事から引用した次の文章を校閲対象とします。

$ cat test.txt
Producer(送信者)がBrokerを経由してConsumer(受信者)にメッセージを送ります。構成だけ見るとMQTTに似ていますね。

Kafkaの特徴の一つに「Brokerがスケーラブルである」という点があります。Brokerがスケールアウトして複数台構成となっても、メッセージの送受信を分散処理することでパフォーマンスを維持します。

Broker間の連携を担うのがZppKeeperの役目です。

ちなみに、数日前に出たこちらの記事によると、KafkaをZookeeperに依存しない形にする計画も始まっているようです。 https://www.confluent.io/blog/removing-zookeeper-dependency-in-kafka/

次のコマンドでtextlintを実行します。

$ ./node_modules/textlint/bin/textlint.js test.txt

/textlint-test/test.txt
  3:10   ✓ error  一つ => 1つ
数量を表現し、数を数えられるものは算用数字を使用します。任意の数に置き換えても通用する語句がこれに該当します。  ja-technical-writing/arabic-kanji-numbers
  7:45   error    一文に二回以上利用されている助詞 "に" がみつかりました。                                                        ja-technical-writing/no-doubled-joshi
  7:131  error    文末が"。"で終わっていません。                                                                                  ja-technical-writing/ja-no-mixed-period

✖ 3 problems (3 errors, 0 warnings)
✓ 1 fixable problem.
Try to run: $ textlint --fix [file]

このように、技術文書としてイマイチな書き方となっている箇所を指摘してくれます。便利ですね。

textlint-rule-prhをインストール

表記揺れを検出するためprhを導入します。今回はtextlintのルールとしてprhを組み込むため、textlint-rule-prhを利用します。

$ npm install textlint-rule-prh

prhを使用するためにはルールを定義する必要があるのですが、今回はこちらを使わせていただきました。

rules/media/WEB+DB_PRESS.yml at master · prh/rules

A collection of prh rules. Contribute to prh/rules development by creating an account on GitHub.

github.com

次のコマンドで取得します。

$ wget https://raw.githubusercontent.com/prh/rules/master/media/WEB%2BDB_PRESS.yml

ルールにprhを追加するため、 .textlintrb を追記します。

{
  "rules": {
    "preset-ja-technical-writing": true,
    "prh": {
      "rulePaths" :["./WEB+DB_PRESS.yml"]
    }
  }
}

textlint+prhを実行する

次はこちらの記事から引用した、次の文章を校閲対象とします。

$ cat test.txt
例えば、弊社オフィスのエアコンをIoT化したいとします。

温度が高いときは自動的にエアコンをOFFに、低いときは自動的にエアコンをONにする簡単なシステムです。この場合、温度は温度センサーを使うことで計測ができます。

一方、エアコンのON/OFFはどのように実現できるでしょうか？ちなみに、弊社のエアコンはこのようなコントローラからしか制御できません。赤外線リモコンもありません。

実行するコマンドはprh追加前と同じです。

$ ./node_modules/textlint/bin/textlint.js test.txt

/Users/yokazaki/src/github.com/yuuu/textlint-test/test.txt
  1:1   ✓ error  例えば => たとえば    prh
  3:62  ✓ error  センサー => センサ    prh
  5:9   ✓ error  ON/OFF => オン／オフ  prh
  5:31  error    Disallow to use "？"  ja-technical-writing/no-exclamation-question-mark

✖ 4 problems (4 errors, 0 warnings)
✓ 3 fixable problems.
Try to run: $ textlint --fix [file]

いかにも表記ゆれが起こりがちな箇所をしっかり指摘してくれています。

そのほかのTips

GitHub ActionsでCIする

執筆原稿をGitHubで構成管理している場合、push時にtextlintを自動実行すると便利です。次のような .github/workflows/lint.yml を作成するとGitHub Actionsが有効となります。

name: Lint
on: [push]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v1
      - name: npm install
        run: npm install
        shell: bash
      - name: textlint
        run: ./node_modules/textlint/bin/textlint.js test.txt
        shell: bash

文書フォーマットがMarkdownの場合の設定

@textlint/textlint-plugin-markdownをインストールすると、Markdown記法を考慮して校閲できます。

執筆ツール Re:VIEW を使う場合の設定

textlint-plugin-reviewをインストールすると、Re:VIEWの記法を考慮して校閲できます。

一部の文章を校閲対象外とする

固有名詞を使っている等、特定の文章に対する指摘を無視したい場合があります。textlint-filter-rule-commentsをインストールすると、コメントを書くことで部分的にtextlintを無効化できます。

まとめ

この記事はtextlintで校閲済みです。(執筆時点では5個の指摘がありました)