注意
本文書は RedPen v1.8 の利用を想定して書かれています。
はじめに
RedPen をインストールして同梱されている設定ファイルで文書を検査すると、相当な量のエラーが出現してしまい少々ゲンナリしてしまいます。大量のエラーが出現してしまうのは、個人や執筆グループによって異なることが多い検査も、デフォルトの設定ファイルに追加されているためです。
今まで RedPen の利用方法や設定方法について記事を書いたのですが、具体的な設定をどうするのかについてあまり触れてませんでした。本記事は RedPen のおすすめ設定に関するまとめとなっています。また、RedPen が提供する各機能が作られた意図について書かれた記事「文書執筆の指南書で解説されている問題点を RedPen で発見する」があります。本稿を読む前に一読しておくとよいでしょう。
はじめの設定（文長まわり）
はじめて RedPen を利用するユーザにおすすめしたいのは文長関係の検査だけを追加する設定です。実は文長を検査したいというのが RedPen を開発した理由です。文書執筆でなぜ文長が重要かといえば、文が長いと読者が理解するのが難しくなるためです。
長い文は単純に読みにくいという以外の問題も引き起こします。文書を読んでいて理解できない箇所があったとします。このとき文が長いと、読者が内容を理解できないのは”解説がたりないのか”、それとも”文が複雑すぎるのか”切り分けできないという状態がおこります。
技術文書執筆の目的は読者に記述した内容をはやく精確に読者に伝えるという点に集約されます。文書執筆の目的を考えれば内容が理解しづらくなる長い文はできるかぎり早く取り除きたい問題です。私がマニュアルやメールのレビューを頼まれた時には、まずはじめのリファクタリングとして文を短くそろえます。一度文を短くしておくと、著者は文やパラグラフのつながりなどもう少し大きな粒度の問題に集中できるのです。
そこで、はじめて RedPen を使って日本語文書を検査したい人には以下の設定がおすすめです。
<redpen-conf lang="ja">
<validators>
<validator name="SentenceLength">
<property name="max_len" value="100"/>
</validator>
<validator name="CommaNumber" />
</validators>
</redpen-conf>
上の設定では二つの機能が登録されています。
- SentenceLength 文の長さ自体を検査する機能。上記の設定では文の最大長を100文字に設定している。
- CommaNumber 文中のコンマの数を検査。デフォルトでは最大四つ。
上の設定はどれも文の長さに関連する検査です。たとえばコンマの数や同一単語の複数回の利用は文が長ければ検査に引っかかる可能性が増えます（注: DoubledWord は削除しました 2016/05/11）。先に述べたように一度文を短く揃えてからが、本格的な文書の校正の開始です。文が短く揃っているために文書が頭に入ってくるスピードが増して校正作業がスムーズにすすみます。
表現に関する設定
次に文書内の表現に関する機能を加えてみます。
<redpen-conf lang="ja">
<validators>
<validator name="SentenceLength">
<property name="max_len" value="100"/>
</validator>
<validator name="CommaNumber" />
<validator name="SuccessiveWord" />
<validator name="KatakanaEndHyphen"/>
<validator name="KatakanaSpellCheck"/>
<validator name="InvalidExpression"/>
<validator name="JapaneseStyle"/>
<validator name="DoubleNegative" />
<validator name="FrequentSentenceStart" />
<validator name="JapaneseAmbiguousNounConjunction" />
<validator name="JapaneseNumberExpression" />
<validator name="LongKanjiChain" />
<validator name="SuccessiveSentence" />
<validator name="DoubledConjunctiveParticleGa" />
</validators>
</redpen-conf>
残念ながら日本語でつかえる表現に関する検査項目は多くありません。現状ですと以下の機能が利用できます。
- SuccessiveWord 同一の単語が連続して使用されていないかを検査する
- KatakanaEndHyphen カタカナ単語末尾の長音検査します。
- KatakanaSpellCheck カタカナ単語のゆらぎ検査します。
- InvalidExpression 顔文字や感情的な表現など技術文書で利用するべきでない句の使用を検査します。
- JapaneseStyle ですます調、である調が混じっていないかを検査します
- DoubleNegative 二重否定を検知します。
- FrequentSentenceStart 同じ文頭表現が過度に利用されていないか検査。たとえばどの文も”私は〜〜”からはじまるなど。
- JapaneseAmbiguousNounConjunction 格助詞の「の」+名詞連続+格助詞の「の」というパターンを発見するとエラーを出力します。
- JapaneseNumberExpression 日本語の数値表現を検査する機能です。「ひとつ、ふたつ」、「１つ、２つ」などのゆらぎを検知します。
- LongKanjiChain 長過ぎる漢字の連続をみつけるとエラーを出力します。
- SuccessiveSentence 同一内容の文が連続して出現するとエラーを出力します。
- DoubledConjunctiveParticleGa 一文に二回以上、接続助詞の「が」が出現するとエラーを出力します。
ClearCode さんのブログ記事で紹介していただいたように、RedPen では JavaScript を利用して簡単に機能追加ができます。特に不正表現は人によって検査したい箇所や表現が異なります。是非自分用の機能を追加してみましょう。
より大きな文書を書くときの設定
RedPen では製品のマニュアルなど長い文書を書くために便利な機能もいくつか提供しています。以下の設定に節やパラグラフまわりの機能を追加したサンプル設定となります。
<redpen-conf lang="ja">
<validators>
<validator name="SentenceLength">
<property name="max_len" value="100"/>
</validator>
<validator name="CommaNumber" />
<validator name="SuccessiveWord" />
<validator name="KatakanaEndHyphen"/>
<validator name="KatakanaSpellCheck"/>
<validator name="InvalidExpression"/>
<validator name="JapaneseStyle"/>
<validator name="DoubleNegative" />
<validator name="FrequentSentenceStart" />
<validator name="JapaneseAmbiguousNounConjunction" />
<validator name="JapaneseNumberExpression" />
<validator name="LongKanjiChain" />
<validator name="SuccessiveSentence" />
<validator name="DoubledConjunctiveParticleGa" />
<validator name="ParagraphNumber" />
<validator name="SectionLength" />
<validator name="DuplicatedSection" />
<validator name="EmptySection" />
<validator name="SectionLevel" />
</validators>
</redpen-conf>
- ParagraphNumber 節内のパラグラフ数が指定した値よりも多いとエラーを出力します。
- SectionLength 節の長さが指定した値よりも多いとエラーを出力します。
- DuplicatedSection 類似した節が存在するかを検査。節の場所を移動させた際に、元の場所の節の削除を忘れた場合にエラーを出力します。
- EmptySection 中身が無い節に（章）対してエラーを出力します。節の中に文がなく、小節から始まるときにもエラーを出力します。
- SectionLevel 環境によっては小さな小節を利用できないことがあります。SectionLevelは節が細かすぎるとエラーを出力します。
文字に関する設定
文書の文字に関する設定は最も、執筆者によって規約が異なる部分だと感じています。たとえば、本文書では句点として”。”を利用しています。しかし人によっては”．”を利用しますし、半角ピリオド(”.”)を日本語文の句点として利用している人もいます。
句点の設定
RedPen は句点の設定を利用して文を切り出しています。そのため句点の設定が文書の内容と異なるとパラグラフ全体が一文として切りだされてしまいます。
RedPen では”。”を句点として使用する設定となっています。別の句点を利用するには設定を書きかえる必要があります。句読点はよく利用するため、RedPen では句読点の部分だけは手軽に設定を上書きできます。
日本語文書の句読点部分の設定を上書きするには redpen-conf ブロックに variant 要素を追加します。以下設定例です。
<redpen-conf lang="ja" variant="zenkaku2">
</redpen-conf>
上の例では variant は zenkaku2 です。この設定は句点に全角ピリオド（．）、読点に全角カンマ（，）を利用します。また日本語の variant には hankaku もあります。 hankaku は句点に半角ピリオド、読点に半角カンマを利用する文書用の設定となります。
文字（シンボル）周りに関する機能の設定追加
複数人数で文書を執筆すると、どうしても句読点およびその他のシンボルが一致しません。たとえば著者の一人はクエスチョンマークとして半角を利用しますが、別の著者は全角を利用するという事態がおこります。シンボルの不一致は文長関係などの読みやすさに関係する部分ではないのですが、商用製品のマニュアルなどでは品質をアピールするためにも一致させておきたい部分です。
RedPen ではシンボルの一致を目指すための設定、機能が用意されています。以下文字まわりの機能を追加した設定ファイルです。
<redpen-conf lang="ja">
<validators>
<validator name="SentenceLength">
<property name="max_len" value="100"/>
</validator>
<validator name="CommaNumber" />
<validator name="SuccessiveWord" />
<validator name="KatakanaEndHyphen" />
<validator name="KatakanaSpellCheck" />
<validator name="InvalidExpression" />
<validator name="JapaneseStyle" />
<validator name="DoubleNegative" />
<validator name="FrequentSentenceStart" />
<validator name="JapaneseAmbiguousNounConjunction" />
<validator name="JapaneseNumberExpression" />
<validator name="LongKanjiChain" />
<validator name="SuccessiveSentence" />
<validator name="DoubledConjunctiveParticleGa" />
<validator name="ParagraphNumber" />
<validator name="SectionLength" />
<validator name="DuplicatedSection" />
<validator name="VoidSection" />
<validator name="SectionLevel" />
<validator name="InvalidSymbol" />
<validator name="ParenthesizedSentence">
<property name="max_count" value="3"/>
<property name="max_nesting_level" value="1"/>
<property name="max_length" value="10"/>
</validator>
<validator name="SpaceBetweenAlphabeticalWord" />
</validators>
</redpen-conf>
上の例では文字周りの検査項目として以下、三つの機能が追加されています。
- InvalidSymbol 不正なシンボルを発見するとエラーを出力します。
- ParenthesizedSentence 括弧に関する規約を検査します。
- SpaceBetweenAlphabeticalWord アルファベット単語の前後にスペースを加えているか検査する
高度な設定
ただし文字周りの機能はデフォルトの文字設定を上書きしないとうまく動作しない恐れがあります。RedPen では各シンボルは五つの設定項目をもちます。以下各設定項目となります。
- name （シンボル名）
- value （シンボルの値）
- before-space （シンボルの前にスペースが必要か）
- after-space （シンボルの後ろにスペースが必要か）
- invalid-chars （不正な文字群）
RedPen のマニュアルに各文字がどのようなデフォルト設定なっているかについて記載があります。
たとえばデフォルトの設定エクスクラメーションマークは全角を使用し、半角は不正な文字として追加されています。シンボルまわりの機能を追加したしたばあい、デフォルトの設定に基づいて検査が行われます。たとえば InvalidSymbol を設定に追加した場合、半角のエクスクラメーションマークが文書内で発見されると、RedPen はエラーを出力します。
執筆者が半角エクスクラメーションマークを使用する規約を採用する場合には、symbolsブロックを追加します。以下半角エクスクラメーションマークを使用する設定例です。
<redpen-conf lang="ja">
<validators>
<validator name="SentenceLength">
<property name="max_len" value="100"/>
</validator>
<validator name="CommaNumber" />
<validator name="SuccessiveWord" />
<validator name="KatakanaEndHyphen" />
<validator name="KatakanaSpellCheck" />
<validator name="InvalidExpression" />
<validator name="JapaneseStyle" />
<validator name="DoubleNegative" />
<validator name="FrequentSentenceStart" />
<validator name="JapaneseAmbiguousNounConjunction" />
<validator name="JapaneseNumberExpression" />
<validator name="LongKanjiChain" />
<validator name="SuccessiveSentence" />
<validator name="DoubledConjunctiveParticleGa" />
<validator name="ParagraphNumber" />
<validator name="SectionLength" />
<validator name="DuplicatedSection" />
<validator name="VoidSection" />
<validator name="SectionLevel" />
<validator name="InvalidSymbol" />
<validator name="ParenthesizedSentence">
<property name="max_count" value="3"/>
<property name="max_nesting_level" value="1"/>
<property name="max_length" value="10"/>
</validator>
<validator name="SpaceBetweenAlphabeticalWord" />
</validators>
<symbols>
<symbol name="EXCLAMATION_MARK" value="!" invalid-chars="！" after-space="true" />
</symbols>
</redpen-conf>
上の例では symbols ブロック内に上書きしたいシンボル用の設定を含んだブロック（symbol）を追加しています。
まとめ
RedPen で利用する機能とその背景について解説しました。残念ながら現状の機能は十分ではありません。今後ゆっくりと機能を強化してゆきたいと考えています。