チームの表記ルールを決める

学会の執筆要項や社内の決まりのように、チームには守りたい書き方があります。 chaff では、その決まりを chaff.yaml に書いて、機械で確かめられます。プログラムは要りません。この手引きの機能は、0.18.0 から使えます。

決め方は 3 つあります。

したいこと書く所例
よく知られた決まりを丸ごと使うstyle:電子情報通信学会の書き方
一つのルールの向きを決めるoptions:カタカナ語の語末の「ー」は省く
チームだけのルールを足すcustom_rules:「下さい」ではなく「ください」

決まった書き方を名前で選ぶ

style: に名前を書くと、その決まりのとおりにルールが動きます。たとえば IEICE の論文では、3 音以上のカタカナ語は語末の「ー」を省きます（コンピュータ、プリンタ）。

style: ieice

これだけで、語末に「ー」を付けた語を見つけます。

  3:7     warning 「サーバー」は語末の「ー」を省いて「サーバ」と書きます（3 音以上の語）
                  katakana-long-vowel

いま選べる名前は次の 5 つです。名前を間違えると、chaff は動く前に止まり、選べる名前を並べます。

名前決めること出典
ieice3 音以上の語は語末の「ー」を省く電子情報通信学会「和文論文誌 投稿のしおり」2.4
jis-z8301-2011同じ（2019 年版はこの決まりを外しました）JIS Z 8301:2011 表 G.3
bunkacho語末の「ー」を付ける（コンピューター）外来語の表記（平成 3 年内閣告示）
jis-z8301-2019規定の文末に「すべきである」と、文末の「できる」を使わない。番号を付けた図・表・箇条を「上記の図」「以下の箇条」と指さないJIS Z 8301:2019 7.3〜7.5、10.6
koyobun和文の一文は 60 字まで。です・ますとであるを混ぜない。語末の「ー」を付ける文化審議会「公用文作成の考え方」（2022）Ⅲ－3 ア、Ⅲ－1 イ、Ⅰ－3 エ

音は語末の「ー」を除いて「コ・ン・ピュ・ー・タ」と数えます（JIS Z 8301:2011 表 G.3 の数え方）。小さい「ャュョ」は前の字と合わせて 1 音です。「ー」の前が 2 音以下の語（カー、カバー、シャワー）には、どの決まりでも「ー」を付けます。 ieice と jis-z8301-2011 が省くのは英語の -er、-or、-ar に当たる「ー」（ア段の字の後ろ）だけで、ュー・エー・イーで終わる語（メニュー、グレー、コピー）は見ません。

プラグインもスタイルを持てます。plugins: に入れたプラグインのスタイルは、名前の前にプラグインの名前を付けて選びます（style: example/careful）。作り方は プラグインを作る にあります。

一つのルールの向きを決める

スタイルを選ばずに、ルールの向きだけを決めることもできます。 options: に、ルールの名前と決めたいことを書きます。

rules:
  katakana-long-vowel: normal
options:
  katakana-long-vowel:
    ending: drop      # 省く。付けるなら keep
    min_morae: 3      # 何音の語から見るか
    except: [カー]     # 見ない語

ending を書かなければ、chaff はどちらが正しいかを決めません。同じ語が両方で書かれた所（「サーバー」と「サーバ」）だけを指摘します。

chaff.yaml の設定がいちばん強く、次にスタイル、最後にジャンルの既定です。どの値がどこから来たかは、explain で確かめられます。

npx chaffjs explain katakana-long-vowel     このルールの設定と、決めた場所を見る
  オプション（chaff.yaml の options で決めます）:
    ending: drop   (style: ieice から)
      語末の「ー」をどちらに寄せるか
        consistent 決めない。文書の中でそろっているかだけを見る
      → drop       min_morae 音以上の語の語末の「ー」を省く（電子情報通信学会、JIS Z 8301:2011 まで）

チームだけのルールを足す

custom_rules: に、チームのルールを並べます。種類は 3 つです。

type:見つけるもの向いている決まり
words決めた語「下さい」は「ください」と書く
pattern正規表現に当たる所「TBD」を残さない
tokens品詞と原形の並び「〜を行う」は「〜する」で足りる

どのルールにも、名前・理由・直し方・例を書きます。指摘を読む人が、なぜ直すのかを分かるようにするためです。

style: ieice

custom_rules:
  - id: team-kudasai
    type: words
    words:
      下さい: ください
      致します: いたします
    name: 補助動詞はひらがなで書く
    why: 「ご確認下さい」の「下さい」は補助動詞です。社内の書き方では、補助動詞はひらがなで書くと決めています。
    how_to_fix: 「{preferred}」に直してください。
    example:
      before: ご確認下さい。
      after: ご確認ください。

  - id: team-tbd
    type: pattern
    pattern: 'TBD|未定'
    level: error
    name: 決まっていないことが残っている
    why: 「TBD」「未定」が残ったまま配ると、読み手は決まったものとして動きます。
    how_to_fix: 決める人と期限を書いてください。本当に未定なら、いつ決まるかを書きます。
    example:
      before: 公開日は TBD です。
      after: 公開日は 10 月 1 日です（佐藤が 9 月 20 日までに確定します）。

  - id: team-wo-okonau
    type: tokens
    tokens:
      - pos: 名詞
      - surface: を
      - base: 行う
    level: info
    name: 「〜を行う」は「〜する」で足りる
    message: 「{matched}」は「〜する」で書けます
    why: 「調査を行う」は「調査する」と同じ意味で、語が二つ増えるだけです。
    how_to_fix: 「〜する」に書き換えてください。
    example:
      before: 来週、調査を行います。
      after: 来週、調査します。

level は指摘の重さで、error・warning・info から選びます。書かなければ warning です。 tokens は語の形を見るので、「行いました」「行います」のどれにも当たります。

次の連絡文を notice.md に保存して、かけてみます。

# 新サーバー導入の連絡

来週、新しいサーバーの動作確認を行います。

公開日は TBD です。決まり次第お知らせ致しますので、ご確認下さい。
$ npx chaffjs notice.md --compact

notice.md   blog/tech · 日本語   ジャンルは既定から

  3:7     warning 「サーバー」は語末の「ー」を省いて「サーバ」と書きます（3 音以上の語）
                  katakana-long-vowel
  3:14    info    「確認を行い」は「〜する」で書けます
                  team-wo-okonau
  5:6     error   決まっていないことが残っている:「TBD」
                  team-tbd
  5:22    warning 「致します」は「いたします」と書きます
                  team-kudasai
  5:32    warning 「下さい」は「ください」と書きます
                  team-kudasai

指摘 5 件、動いていない rule 60 件

この例の chaff.yaml は style: ieice も選んでいるので、1 件目はスタイルからの指摘です。

チームのルールは、chaff のルールと同じように扱えます。 explain には、書いた理由と例がそのまま出ます。

npx chaffjs explain team-tbd     チームのルールの意図と例を読む
  決まっていないことが残っている   (team-tbd)

  「TBD」「未定」が残ったまま配ると、読み手は決まったものとして動きます。

  直しかた: 決める人と期限を書いてください。本当に未定なら、いつ決まるかを書きます。

  例:  公開日は TBD です。
      →  公開日は 10 月 1 日です（佐藤が 9 月 20 日までに確定します）。

  このルールはチームが chaff.yaml の custom_rules で決めたものです。

npx chaffjs relax team-tbd で指摘を一段軽くでき、<!-- stet: team-tbd — 理由 --> で一か所だけ黙らせられます。

書き間違えたとき

ルールに足りないものがあると、chaff は文書を見る前に止まり、何が足りないかを言います。黙って動かないと、きれいな文書に見えてしまうためです。

chaff: …/chaff.yaml: custom_rules の team-tbd: example.before がありません
chaff: …/chaff.yaml: custom_rules の team-tbd: example.after がありません

画面のパスは短くしてあります。

正規表現は、動かす前に確かめます。(a+)+ のように繰り返しの中に繰り返しがある形は断ります。長い行で止まらなくなることがあるからです。* や + を 4 つ以上使う形と、後方参照（\1）も断ります。それでも 1 文書に 1 秒以上かかったルールは止めて、「動いていない」一覧に理由と一緒に出します。

品詞の書き方

tokens の pos には、名詞・動詞・形容詞・副詞・助詞・助動詞のような名前を書けます。英語の文書なら noun・verb のような名前か、NOUN・VERB のような記号です。 base は原形（行う）、surface は書かれたままの形（を）です。一つの語に、いくつ書いても構いません。

数える・比べるなど、ここにある書き方で言えないルールは、Node の関数（type: module）で書けます（0.19.0 から）。書き方はルールを足すに、パッケージにして配る方法はプラグインを作るにあります。