はじめに
本連載ではRedPenという自動文書検査ツールの紹介とRedPenを利用した技術文書の校正方法について説明します。RedPenはオープンソースプロジェクトで、
RedPenは技術文書をターゲットにした文書の自動検査ツールです。技術文書にはマニュアルやチュートリアル、
技術文書の特徴
RedPenが対象とする技術文書ですが、
最大の違いは、
技術文書に求められるわかりやすさとは単純には内容が理解しやすいことを意味します。拡大解釈すると、
日記等と違って技術文書は自分以外の第三者が読むため、
RedPenを開発した動機
ソフトウェアエンジニアはプログラムだけではなく、
ソフトウェアツールを開発する際には多くのテストを書きます。またCheckStyleやlintなどの静的解析ツールを利用してフォーマットのエラーを自動で検知する環境を整えます。テストを整備したり静的解析ツールを導入することで、
一方私が文書を書いている時には安心感はありません。技術文書の執筆環境にはテストもありませんし、
このような状況に対して、
以下、
RedPenの特徴
前項で述べたようにRedPenはプログラムの静的解析ツールに相当する機能を技術文書に対して提供します。具体的には文長のチェックや不正な表現を検知などわかりやすさに寄与する機能と、
言語非依存
RedPenはどの自然言語
柔軟な設定
RedPenが対象とする技術文書の規約は所属組織によって大きく異なります。RedPenは組織の規約に対応できるように設定が柔軟に行える仕様となっています。
コマンド実行
RedPenは単一コマンドで実行できます。そのため、
RedPenを使ってみる
ではRedPenを使用してみましょう。RedPenはUnix系のOSとWindowsで動作します。今回はUnix系のOS
必要なソフトウェア
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をインストールします。インストールと言ってもRedPenのソースファイルをコピーするだけです。たとえばRedPenを/usr/
$cp -r redpen-cli-1.0 /usr/local/redpen
続いてRedPenのインストールディレクトリを環境変数PATHに追加します。次のようにredpen/
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 -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"を指定してください。言語を設定することで利用されるシンボルがロードされます。現在のところ、
RedPenが提供する機能
RedPenは現在、
- SentenceLength ー 文長を検査します。
- InvalidExpression ー 不正な表現が利用されていないか検査します。
- SpaceAfterPeriod ー 句点の後にスペースがあるか検査します。
- CommaNumber ー 各文内のカンマ数を検査します。
- WordNumber ー 単語数を検査します。
- SuggestExpression ー 不正な表現が利用されている場合、
別表現を提案します。 - InvalidSymbol ー 不正なシンボルが使用されていないか検査します。
- SpaceWithSymbol ー シンボルの前後にスペースが存在するかを検査します。
- KatakanaEndHyphen ー カタカナ単語の語尾に使用されるハイフンの有無を検査します。
- KatakanaSpellCheck ー カタカナ単語のスペルチェックを行います。
- SectionLength ー セクション内の文字数を検査します。
- SpaceBetweenAlphabeticalWord ー アルファベット単語の前後にスペースがあるかをチェックします。
- ParagraphNumber ー セクション内のパラグラフ数を検査します。
- ParagraphStartWith ー パラグラフの開始部分が規約に従っているかを検査します。
- Contraction ー 英語の省略形が利用されているかを検査します。
- Spelling ー 単語のスペルを検査します
(現状英単語のみに対応)。 - DoubledWord ー 一文に同一の単語が複数利用されているかを検査します。
- SuccessiveWord ー 連続して同一単語が利用されているかを検査します。
RedPenは設定ファイルに追加された機能を適用します。
文字設定
言語を指定すると、
文字 | デフォルト値 |
デフォルト値 |
---|---|---|
ピリオド |
.(0x002E) | 。(0x3002) |
カンマ |
,(0x002C) | 、(0x3001) |
クエスチョンマーク |
?(0x003F) | ? |
特に利用されている文末文字
記号
文字の設定を変更したいときには設定ファイルの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>
上記の設定では句点
まとめ
今回は技術文書の特徴とRedPenの利用法と基本的な設定方法について説明しました。
本連載は全6回を予定しています。
- 第2回では継続的インテグレーション環境でのRedPenの利用法と文書執筆について説明します。
- 第3回では、
文書の執筆で気をつけることと、 RedPenを使った予防方法について説明します。 - 第4回ではRedPenの多様な利用方法について説明します。具体的には英語文書やLaTeX文書等を多様な文書への適用方法について解説します。
- 第5回ではRedPenの内部の解説を行います。
- 第6回ではRedPenの理解を元に、
RedPenの拡張方法と開発のロードマップについて説明します。
次回以降もどうぞよろしくお願いたします。