gihyo.jpサイトのロゴ

RedPenを使って技術文書を手軽に校正しよう

第1回自動文書検査ツールRedPenとは？

2014-11-17

はじめに

本連載ではRedPenという自動文書検査ツールの紹介とRedPenを利用した技術文書の校正方法について説明します。RedPenはオープンソースプロジェクトで、現在もゆっくりと開発が続いています。RedPenのホームページは次のとおりです。

RedPenは技術文書をターゲットにした文書の自動検査ツールです。技術文書にはマニュアルやチュートリアル、論文、仕様書等が含まれます。この記事のようなソフトウェアツールの紹介文書はもちろん技術文書の一つといえます。第1回の今回は、はじめに技術文書の特徴を解説し、その後RedPenを開発した動機について紹介します。記事の後半では、RedPenの特徴と利用方法について解説します。

技術文書の特徴

RedPenが対象とする技術文書ですが、作文や日記、文学作品等とは大きく異なる特徴をもちます。

最大の違いは、技術文書にはわかりやすさが求められる点です。詩や歌謡曲の歌詞にはわかりやすさを放棄し、わざと曖昧な部分を残すことでより心に響く作品となる場合があります。しかしわかりやすさが第一に求められる技術文書には余韻や深みは必要ありません。

技術文書に求められるわかりやすさとは単純には内容が理解しやすいことを意味します。拡大解釈すると、対象となるすべての読者が同一の意図を読み取れるといえるかもしれません。

日記等と違って技術文書は自分以外の第三者が読むため、恥ずかしくない文書を書く必要があります。恥ずかしい文書は利用する特殊文字や専門用語が揃っていなかったり、"彼がが行く" のように明らかな文法間違いが多数存在します。また"すごい"や"っていうか"などの口語が混じってしまっていると、文書のみならず、文書が扱う製品の品質までにあらぬ疑いをもたれてしまいます。

RedPenを開発した動機

ソフトウェアエンジニアはプログラムだけではなく、たくさんの技術文書を書いていると思います。私の場合、プログラムとほぼ分量の文書（チュートリアルやマニュアルなど）を書いてきました。ただプログラムを書いている時ほど安心して文書を書けないという悩みをもっていました。

ソフトウェアツールを開発する際には多くのテストを書きます。またCheckStyleやlintなどの静的解析ツールを利用してフォーマットのエラーを自動で検知する環境を整えます。テストを整備したり静的解析ツールを導入することで、プログラムを変更する際に新たな問題（バグ）が発生しないという安心感を得られます。

一方私が文書を書いている時には安心感はありません。技術文書の執筆環境にはテストもありませんし、静的解析ツールも存在しないためです。ちょっとした変更でも、誤りをやフォーマットミスを引き起こしたのではないかと常に不安な気持ちで作業することになります。結果文書を変更をするのが億劫になってしまい、なかなか文書の質が向上しませんでした。

このような状況に対して、RedPenは一部の静的解析ツール（CheckStyleやlint）に相当する機能を文書の執筆環境に提供します。私はこのツールを、文書作成でも最低限の検査を自動で行いたいという動機で開発しています。

以下、RedPenの特徴を紹介し実際に使ってみます。

RedPenの特徴

前項で述べたようにRedPenはプログラムの静的解析ツールに相当する機能を技術文書に対して提供します。具体的には文長のチェックや不正な表現を検知などわかりやすさに寄与する機能と、登録された以外の記号が出現した時にエラーを出力するようにフォーマットの不統一を検出する機能が提供されます。主なRedPenの特徴は次のとおりです。

言語非依存

RedPenはどの自然言語（英語や日本語、中国語など）で記述された文書にも適用できます（注：一部機能は特定の言語でしか動作しないものがあります⁠）⁠。本連載の第4回では英語の文書にRedPenを適用してみます。

柔軟な設定

RedPenが対象とする技術文書の規約は所属組織によって大きく異なります。RedPenは組織の規約に対応できるように設定が柔軟に行える仕様となっています。

コマンド実行

RedPenは単一コマンドで実行できます。そのため、他のシステムの中に組み入れることが比較的容易です。第2回ではCI環境でRedPenを使用して自動チェックを実現します。

RedPenを使ってみる

ではRedPenを使用してみましょう。RedPenはUnix系のOSとWindowsで動作します。今回はUnix系のOS（Mac）を利用します。

必要なソフトウェア

RedPenは次のソフトウェアを必要とします。

  • Java（バージョン 8）

ダウンロードと解凍

RedPenをダウンロードします。RedPenのリリースページからダウンロードできます。

ダウンロードされたファイルを次のコマンドで解凍します。

$tar xvf redpen-cli-1.0-assembled.tar.gz
x redpen-cli-1.0/lib/redpen-core-1.0.jar
x redpen-cli-1.0/lib/kuromoji-0.7.7.jar
x redpen-cli-1.0/lib/commons-io-2.2.jar
...

結果、redpen-cli-1.0というディレクトリが生成されます。

インストール

RedPenをインストールします。インストールと言ってもRedPenのソースファイルをコピーするだけです。たとえばRedPenを/usr/localにインストールするには次のコマンドを実行します。

$cp -r redpen-cli-1.0 /usr/local/redpen

続いてRedPenのインストールディレクトリを環境変数PATHに追加します。次のようにredpen/binを.bashrcに追加してください。

export PATH=$PATH:/usr/local/redpen/bin

他のシェルを利用している場合も同様にPATHにredpenディレクトリを追加してください。以上でインストールは完了しました。

実行

早速RedPenを使ってみましょう。redpenというコマンドを利用して実行します。redpenコマンドは次のようなパラメタを持ちます。

redpen -c <CONF FILE> <INPUT FILE> [<INPUT FILE>]
    -c,--conf <CONF FILE>                設定ファイル
    -f,--format <FORMAT>                 インプットファイルフォーマット
    -h,--help                            ヘルプメッセージを表示
    -r,--result-format <RESULT FORMAT>   出力フォーマット (プレーンテキストか XML)
    -v,--version                         バージョンを表示

パラメタ"-c"で設定ファイルを指定した後、入力ファイル名（複数可）を追加します。

ではRedPenを実行しましょう。入力データと設定ファイルは、先ほどインストールしたRedPenパッケージに同梱されているものを利用します。

$redpen -c /usr/local/redpen/conf/redpen-conf-ja.xml /usr/local/redpen/doc/txt/ja/sampledoc-ja.txt
19:49:45.707 [main] INFO  cc.redpen.ConfigurationLoader - Succeeded to load configuration file
19:49:45.723 [main] INFO  cc.redpen.ConfigurationLoader - More than one "symbol " blocks in the configuration
19:49:46.467 [main] INFO  cc.redpen.parser.BasicDocumentParser - "。" is added as a end of sentence character
19:49:46.468 [main] INFO  cc.redpen.parser.BasicDocumentParser - "？" is added as a end of sentence character
....
ValidationError[SentenceLength][/usr/local/redpen/doc/txt/ja/sampledoc-ja.txt : 0 (文長が最大値 "101" を超えています)] at line: 最近利用されているソフトウェアの中には複数の計算機上で動作（分散）するものが多く存在し、このような分散ソフトウェアは複数の計算機で動作することで大量のデータを扱えたり、高負荷な状況に対処できたりします。
ValidationError[InvalidSymbol][/usr/local/redpen/doc/txt/ja/sampledoc-ja.txt : 1 (不正なシンボル "," がみつかりました)] at line: 本稿では,複数の計算機（クラスタ）で動作する各サーバーを「インスタンス」と呼びまます。
ValidationError[KatakanaEndHyphen][/usr/local/redpen/doc/txt/ja/sampledoc-ja.txt : 1 (カタカナ単語 "サーバー" に不正なハイフンが見つかりました)] at line: 本稿では,複数の計算機（クラスタ）で動作する各サーバーを「インスタンス」と呼びまます。

設定方法

RedPenにはXMLフォーマットの設定ファイルが一つあります。設定ファイルには大きく分けて3つの指定する項目があります。一つは機能の追加です。機能の追加はRedPenを利用する上で必須の設定となります。2つ目は入力言語の指定です。日本語文書の場合には"ja"を指定します。最後は文書内で使用する記号（文字）の設定です。記号の設定はデフォルト設定では満足できない場合だけ記述する必要があります。

RedPenの設定例は次のとおりです。

<redpen-conf lang="ja">
    <validators>
        <validator name="SentenceLength">
            <property name="max_len" value="100"/>
        </validator>
        <validator name="InvalidSymbol"/>
        <validator name="KatakanaEndHyphen"/>
        <validator name="KatakanaSpellCheck"/>
        <validator name="SectionLength">
             <property name="max_num" value="1500"/>
        </validator>
        <validator name="ParagraphNumber"/>
    </validators>
</redpen-conf>

設定ファイルの最上位ブロックredpen-confのアトリビュートlangでターゲットとなる言語を指定します。入力文書が日本語の時には上の例と同じく"ja"を指定してください。言語を設定することで利用されるシンボルがロードされます。現在のところ、英語"en"と日本語"ja"が指定できます。

RedPenが提供する機能

RedPenは現在、次の機能を提供します。詳しくは第3回で紹介しますが、現状提供されているほとんどの表層的なフォーマットに関する機能で高度な言語情報（構文、品詞情報等）を利用した機能はありません。

  • SentenceLength ー 文長を検査します。
  • InvalidExpression ー 不正な表現が利用されていないか検査します。
  • SpaceAfterPeriod ー 句点の後にスペースがあるか検査します。
  • CommaNumber ー 各文内のカンマ数を検査します。
  • WordNumber ー 単語数を検査します。
  • SuggestExpression ー 不正な表現が利用されている場合、別表現を提案します。
  • InvalidSymbol ー 不正なシンボルが使用されていないか検査します。
  • SpaceWithSymbol ー シンボルの前後にスペースが存在するかを検査します。
  • KatakanaEndHyphen ー カタカナ単語の語尾に使用されるハイフンの有無を検査します。
  • KatakanaSpellCheck ー カタカナ単語のスペルチェックを行います。
  • SectionLength ー セクション内の文字数を検査します。
  • SpaceBetweenAlphabeticalWord ー アルファベット単語の前後にスペースがあるかをチェックします。
  • ParagraphNumber ー セクション内のパラグラフ数を検査します。
  • ParagraphStartWith ー パラグラフの開始部分が規約に従っているかを検査します。
  • Contraction ー 英語の省略形が利用されているかを検査します。
  • Spelling ー 単語のスペルを検査します（現状英単語のみに対応⁠）⁠。
  • DoubledWord ー 一文に同一の単語が複数利用されているかを検査します。
  • SuccessiveWord ー 連続して同一単語が利用されているかを検査します。

RedPenは設定ファイルに追加された機能を適用します。

文字設定

言語を指定すると、指定言語のデフォルト記号設定がロードされます。言語毎のデフォルト文字は次のとおりです。

文字 デフォルト値（英語） デフォルト値（日本語）
ピリオド（FULL_STOP） .（0x002E） 。（⁠0x3002）
カンマ（COMMA） ,（0x002C） 、（⁠0x3001）
クエスチョンマーク（QUESTION_MARK） ?（0x003F） ？（0xFF1F）

特に利用されている文末文字（ピリオド、クエスチョンマーク、エクスクラメーションマーク）が入力文書で利用されているものと異なると大きな問題になります。具体的にはRedPenが文を抽出できないためにパラグラフ全体が単一の文として抽出されてしまします。そこでRedPenではピリオドやカンマなど入力文書で利用する文字が標準の設定と異なるときには文字設定を上書きできます。

記号（文字）の設定は特に文書が日本語で書かれている場合に必要になります。日本語の文書では著者や所属組織によって利用される記号（文字）が大きく異なるためです。たとえば私は文末の句点として"．（⁠0xFF0E）"を利用しますが多くのIMEでデフォルトとなっている"。（⁠0x3002）"を利用している人も多いのではないかと思います（注：本連載ではgihyo.jpの句読点のスタイルに合わせています⁠）⁠。また半角ピリオド".（0x002E）"も日本語文書の句点として多くの人に好んで利用されています。

文字の設定を変更したいときには設定ファイルのredpen-confの中にsymbolsを追加します。symbolsにはsymbolのリストを追加します。symbolには文字の名前と値を登録します。RedPenに登録されている文字名とその値の一覧はドキュメントに記載されています。

<redpen-conf lang="ja">
    <validators>
        <validator name="SentenceLength" />
    </validators>
    <symbols>
        <symbol name="FULL_STOP" value="．"/>
        <symbol name="COMMA" value="、" />
    <symbols>
</redpen-conf>

上記の設定では句点（FULL_STOP）を"．（⁠0x3002）"に、COMMAを"、（⁠0xFF0C）"に設定しています。

まとめ

今回は技術文書の特徴とRedPenの利用法と基本的な設定方法について説明しました。

本連載は全6回を予定しています。

  • 第2回では継続的インテグレーション環境でのRedPenの利用法と文書執筆について説明します。
  • 第3回では、文書の執筆で気をつけることと、RedPenを使った予防方法について説明します。
  • 第4回ではRedPenの多様な利用方法について説明します。具体的には英語文書やLaTeX文書等を多様な文書への適用方法について解説します。
  • 第5回ではRedPenの内部の解説を行います。
  • 第6回ではRedPenの理解を元に、RedPenの拡張方法と開発のロードマップについて説明します。

次回以降もどうぞよろしくお願いたします。

おすすめ記事

記事・ニュース一覧