第2回　RedPenを利用した文書の継続的検査への取り組み

今回はRedPenを利用して文書を継続的に検査する方法について解説します。文書の継続的検査環境では、執筆中の文書をGitなどのバージョン管理システムで管理します。著者が行った変更が、サーバにあるバージョン管理システムにプッシュされるたびに自動でRedPenが適用されます。

本稿では、はじめにGitなどのバージョン管理システムで文書を管理するメリットについて述べます。その後継続的インテグレーションの説明を行い、RedPenと組み合わせて文書の管理に利用してみます。

文書をGitで管理

最近は文書の管理にGitなどのバージョン管理システムを利用する人が多いのではないかと思います。私もある程度の大きさの文書はすべてGitで管理しています。昔の状態に簡単に戻れるという以外にも、文書管理にバージョン管理システムを利用すると次のようなメリットを享受できます。

マージ処理

バージョン管理システムを利用することで、共同執筆者から送られてくる変更要求をマージする作業がシンプルに行えます。さらに執筆メンバーがプルリクエストを送る形で執筆すると、各変更のレビューを行った上でマージするという流れが徹底できます。レビューが徹底されることで、文書の変更に関する知見がグループメンバに自然に共有されます。

バージョン群の管理

バージョンごとに少しづつ異なるマニュアルや仕様書には、バージョン管理システムが提供するタグやブランチが利用できます。さらにマニュアルに新しく間違いが見つかった場合でも、過去の各バージョンにも同様に存在する該当箇所を修正する（マージ）させる処理も簡単に行えます。

継続的インテグレーション

継続的インテグレーションはソフトウェア開発で近年利用されている手法の一つです。Wikipediaでは継続的インテグレーション（CI）について次のように説明されています（2014年11月時点⁠）⁠。

継続的インテグレーション、CI（英: continuous integration）とは、主にプログラマーのアプリケーション作成時の品質改善や納期の短縮のための習慣のことである。エクストリーム・プログラミング（XP）のプラクティスの一つで、狭義にはビルドやテスト、インスペクションなどを継続的に実行していくことを意味する。特に、1990年代後半以降の開発においては、継続的インテグレーションをサポートするソフトウェアを使用する傾向が強まってきた。

継続的インテグレーションを実践するツールが多数提案されています。特に有名なCIサーバとしてJenkinsがあります。CIサーバを導入することで、プッシュごとのテストを自動化し、バグや不具合が混入した場合にいち早く発見できます。バグや不具合は混入して時間がたつほど修正するコストが増大します。バグの早期発見により開発コストが低減できることが知られています。

継続的インテグレーションと文書執筆

ハードの製品のように一度作って終わりという代物ではなく、ソフトウェアは日々改善、修正を行い徐々に形を変えていきます。日々少しづつ変わることで、簡単に不具合やバグが混入します。そこで継続的インテグレーションが提供する不具合の早期発見が力を発揮してくれます。

日々形が変わり簡単に不具合が混入するという性質は文書の執筆でも同じだと感じています。ベンダが販売している製品のマニュアルは製品が利用されるあいだ、ずっと利用されます。さらに、製品のバージョンごとに少しづつ修正が加えられ続けます。もともとなかった機能が追加さたり、一部機能は提供を中止されるごとに製品のマニュアルは変更を強いられるのです。

ソフトウェアと同様に修正が加えられつづける文書が一定の品質を担保するには、先に述べたようにソフトウェアを管理する一部のツールが役に立ちます。Gitなどのバージョン管理システムはまさに好例ですが、私は継続的インテグレーションも文書の品質管理に寄与するのではいかと感じています。

コラム：研究論文の思い出

研究の論文なども長く苦しい推敲が必要です。たとえば私がデータマイニングの研究をしているとき執筆した論文は、最初の国際会議に受理されるまでに約3年かかりました。最終的に完成した論文は、はじめに書いた論文とは扱っているトピックは同一です。しかし語彙や段落構成、実験、論理展開など、ほとんどすべての部分が何度も書き直されています。恐ろしいことに、書き直されているあいだに何度もミス（語彙の変更が一部反映されていない、単純な文法ミスなど）が混入されてしまうのです。

論文は受理されるまでのあいだ、不受理された理由（コメント）に対するディフェンスを行いつづけます。関連論文との違いがわからないというコメントであれば、反論を追加するだけですのでそれほど大変ではありません。内容を読み違ったレビューア（査読者）がいる場合には、大手術が必要です。読み手が内容を読み間違わないように論理の展開を大きく構成し直す必要があります。一つずつ小さな改善を積み重ねることで、きちんとした会議や論文誌に通る可能性が上がります。

本連載の第4回ではLaTeXで書かれた文書に対してRedPenを適用してみます。

ちなみに私が先日テキストマイニングシンポジウムで書いた論文はRedPenを使って検査しながら作成しました。後日とある方から論文のフォーマットエラーをご指摘していただき恥ずかしい思いをしましたが、同時に指摘していただいた箇所にはRedPenに取り込めそうな機能が含まれていました。論文もプログラムも指摘（レビュー）していただくのはとてもありがたいですね :-)

継続的インテグレーションサービス

CIサーバの導入により多くの利益が得られることが知られていましたが、残念ながらCIサーバは通常インストールしたうえで運用する必要があります。そのため個人や小規模な組織では、運用コストがかかってしまい導入を見送る、もしくはせっかく導入してもうまく稼働していない場合がありました。

しかし近年、TravisやWercker等のCI機能を提供するサービスが誕生したことにより、だれでも簡単に継続的インテグレーション環境が利用できるようになりました。ちなみに本稿ではCIサービスの一つ、Travisを利用して継続的な文書検査環境を作ってみます。

上述のCIサービスはGitHub上に存在するプロジェクトにCI機能を提供します。GitHubはGitシステムを利用したソフトウェアの開発、公開をサポートするサービスです。紙面の都合上GitHubの利用方法については本稿では解説しません。Web上にGitHubに関する多数のブログ記事が存在しますのでそれらを参照してください。

Travis

TravisはGitHubで管理されているプロジェクトに対して継続的インテグレーション環境を提供します。Travisを利用する際には、GitHubで管理されているプロジェクトのルートディレクトリに.travis.ymlという設定ファイルを保存します。

RedPenプロジェクトでもTravisを利用してテストの自動実行を行っています。以下ちょっと前のバージョンですが、RedPenで利用されていた.travis.ymlとなります。

language: java
jdk:
    - openjdk7

.travis.ymlにはいくつか設定項目がありますが、小規模のプロジェクトであればプロジェクトで使用している言語を指定するだけで最低限のテストを行ってくれます。上記の例ではlanguageとjdkブロックでそれぞれ記述言語（Java）とJVMのバージョンを指定しています。

RedPenをTravis上で動作させる

ではGitHubで管理されている文書に対してTravisを介して自動でRedPenを適用します。

利用するGitHubプロジェクト

例として使用する文書をGithubのレポジトリにおきました。レポジトリは次の構成となっています。

sampledoc-ja.md ー検査対象のMarkdownフォーマット文書。
repden-conf-ja.xml ー RedPen の設定ファイル。content.md を検査する項目が列挙されています。
.travis.yml ー Travis の設定ファイル。RedPen を配備して、検査を実行する手順が記載されています。

Travisの設定

本プロジェクトで利用する.travis.ymlは、次のとおりです。

language: text

jdk:
  - oraclejdk8

env:
  - URL=https://github.com/recruit-tech/redpen/releases/download/v1.0-experimental-1

install:
  - wget $URL/redpen-cli-1.0-assembled.tar.gz
  - tar xvf redpen-cli-1.0-assembled.tar.gz

script:
  - redpen-cli-1.0/bin/redpen -c redpen-conf-ja.xml -f markdown -r xml sampledoc-ja.md

上記のファイルを見るとinstallブロックでRedPenパッケージをダウンロードし、scriptでRedPenを対象文書に適用しているのがわかります。詳しいTravisの文法についてはTravisのマニュアルを参照してください。またGitHubのプロジェクトをTravisでテストするには、プロジェクトをTravisに登録する必要もあります。

今回サンプルとして利用する文書（sampledoc-ja.md）の内容は次のとおりです。実は文書にはいくつか悪い点が存在します。

# 分散処理
最近利用されているソフトウェアの中には複数の計算機上で動作（分散）するものが多く存在し、このような分散ソフトウェアは複数の計算機で動作することで大量のデータを扱えたり、高負荷な状況に対処できたりします。
本稿では,複数の計算機（クラスタ）でで動作する各サーバーをインスタンスと呼びまます。
たとえば検索エンジンやデータベースではインデックスを複数のインスタンスで分割して保持します。
このような場合、各インデクスの結果をマージしてclientプログラムに渡す機構が必要となります。

この文書（sampledoc-ja.md）をGithubのレポジトリにプッシュしたところ、Travisから報告が得られました。

Travisが出力したログのうち、次の行：

The number of errors "12" is larger than specified (limit is "1").

から、文書には12件のエラーが存在したことがわかります。ではエラーの内容を詳しく検査してみましょう。

エラー分析

まず2行目が長すぎるというエラーが出ています。また同じく2行目で、複数の単語“⁠分散⁠”⁠、“⁠ソフトウェア⁠”等が一文中に2回以上利用されているというエラーも出ています。これらのエラーは文が長すぎるために起こってしまっています。後ほど修正しましょう。

3行目で半角のカンマが利用されていることが報告されています。RedPenのデフォルト設定ではカンマは全角のものとなっているため、全角カンマを利用するか、シンボル設定を変更する必要があります。また3行目で、カタカナ単語“⁠サーバー⁠”の末尾長音が必要ないというエラーも出ました。KatakanaEndHyphn機能はJIS Z831にもとづいてカタカナ単語の末尾の使用の正しさを検査します。その他、3行目には“⁠（クラスタ）でで⁠”と助詞“⁠で⁠”が重なってしまっているという単純なミスも存在します。

5行目でアルファベット単語（client）の前後に半角スペースが存在しないというエラーが出力されました。これはSpaceBetweenAlphabeticalWord機能から出力されたエラーです。SpaceBetweenAlphabeticalWord機能はアルファベット単語の前後にスペースがあるかを検査してくれます。私は通常アルファベット単語の前後にスペースを入れるという規約にもとづいて文書を書きますが、ここでは入れるのを忘れてしまいました。ちなみに本稿（gihyo.jp）はアルファベット単語の前後にスペースを入れないという規約のため、文書内のスペースは取り除かれています。

エラーを修正する

では早速エラーを修正していきましょう。まず2文目が長すぎるためにエラーを出力されてしまっているのが気になります。2文目の文は次のとおりです。

最近利用されているソフトウェアの中には複数の計算機上で動作（分散）するものが多く存在し、このような分散ソフトウェアは複数の計算機で動作することで大量のデータを扱えたり、高負荷な状況に対処できたりします。

この文は長すぎ、つまり多くの仕事を背負ってしまっています。そこで、次のように分割します。文を分割することで一文に“⁠分散⁠”⁠、“⁠ソフトウェア⁠”といった単語が2回利用されているというエラーも一緒に修正されます。

最近利用されているソフトウェアの中には複数の計算機上で動作（分散）するものが多く存在します。
分散ソフトウェアは複数の計算機で動作することで大量のデータを扱えたり、高負荷な状況に対処できます。

第3文で利用されている半角カンマを全角に変更します。また、カタカナ単語“⁠サーバー⁠”の不正な長音を取り除きます。第5文ではアルファベット単語clientの前後スペースを追加します。

これらの修正を反映させた文書は次のとおりです。

# 分散処理
最近利用されているソフトウェアの中には複数の計算機上で動作（分散）するものが多く存在します。
分散ソフトウェアは複数の計算機で動作することで大量のデータを扱えたり、高負荷な状況に対処できます。
本稿では、複数の計算機（クラスタ）で動作する各サーバをインスタンスと呼びまます。
たとえば検索エンジンやデータベースではインデックスを複数のインスタンスで分割して保持します。
このような場合、各インデクスの結果をマージして client プログラムに渡す機構が必要となります。

この内容をコミットした上で、GitHubにプッシュします。プッシュするとTravisが自動で動作します。Travisより送られてきた修正報告の内容から、検査が無事パスしたことがわかりました。次図は結果の内容を一部キャプチャしたものです。

文書の継続的検査の今後

今回、RedPenとTravisを使って文書をプッシュするたびに検査が走る環境を作ってみました。しかし残念ながら未だ不満があります。Travisで利用した場合、今回使用した例のようにRedPenのリリースページからwgetやcurlコマンドでRedPenのパッケージをダウンロードする必要があります。結果的に.travis.ymlファイルが大きくなってしまいました。

今後はRedPenのサーバ機能（REST API）を強化し、URLと設定を指定しただけで簡単に検査が行えるように拡張していく予定です。