概要
tomio2480/blog-private および tomio2480/blog-pipeline での textlint 適用過程で,preset-ja-spacing および preset-ja-technical-writing の各ルールについて採用根拠を調査した.特にユーザー目線で多く問い合わせを受けやすい ja-no-space-around-parentheses について,中央リポジトリの README や docs に根拠を明示しておくと利用者の納得性が上がるため, その提案と prh.yml の小さな不具合報告を 1 つの Issue にまとめて起票する.
1. ja-no-space-around-parentheses の採用根拠(提案:README または docs に記述)
調査結果は以下のとおり.根拠としての強度は上から順.
2. README または docs への追記の提案
中央リポジトリの README には現在,per-repo override の方法は記載されているが,「なぜそのルールセットを採用しているか」 の根拠が無い.以下のような節を追加することで,利用者が JTF 準拠の意図を理解しやすくなる.
## 設定の根拠
本テンプレートに含まれる textlint ルールは [JTF日本語標準スタイルガイド](https://www.jtf.jp/pdf/jtf_style_guide.pdf) を踏襲する.以下を主な根拠とする.
- 業界の事実上の標準として JTF スタイルガイドが定着している
- 日本語組版の慣習に沿うことで紙面・画面の読みやすさが揃う
- スクリーンリーダーで冗長な読み上げが発生しにくい
- データの冗長性が無く整合性が高い
カスタマイズが必要な場合は per-repo override で対応する.
3. prh.yml の JS パターン誤マッチ(不具合報告)
templates/prh.yml の JavaScript ルールには以下のように JS 単独パターンが含まれる.
- expected: JavaScript
patterns:
- Javascript
- javascript
- JAVASCRIPT
- JS # ← prh の既定では substring マッチ
prh の既定挙動では substring マッチが効くため,JSON の文字列中の JS も検出されてしまい,意図せず prh が「JS => JavaScript」 と発火する.本文中の JSON 化 ・ JSON 形式 などが誤検出される.
提案する修正
word boundary を要求する正規表現に変更する.既存 specs に JSON を含めて回帰テストを兼ねる.
- expected: JavaScript
patterns:
- Javascript
- javascript
- JAVASCRIPT
- /\bJS\b/
specs:
- from: JS
to: JavaScript
- from: JSON
to: JSON
tomio2480/blog-private PR #1 でも同様の対応をローカル prh.yml に入れた(5b19f3e).中央側を直すことで,per-repo override 不要で利用者全員に修正が行き渡る.
関連
概要
tomio2480/blog-privateおよびtomio2480/blog-pipelineでの textlint 適用過程で,preset-ja-spacing および preset-ja-technical-writing の各ルールについて採用根拠を調査した.特にユーザー目線で多く問い合わせを受けやすいja-no-space-around-parenthesesについて,中央リポジトリの README や docs に根拠を明示しておくと利用者の納得性が上がるため, その提案と prh.yml の小さな不具合報告を 1 つの Issue にまとめて起票する.1. ja-no-space-around-parentheses の採用根拠(提案:README または docs に記述)
調査結果は以下のとおり.根拠としての強度は上から順.
2. README または docs への追記の提案
中央リポジトリの README には現在,per-repo override の方法は記載されているが,「なぜそのルールセットを採用しているか」 の根拠が無い.以下のような節を追加することで,利用者が JTF 準拠の意図を理解しやすくなる.
3. prh.yml の
JSパターン誤マッチ(不具合報告)templates/prh.ymlの JavaScript ルールには以下のようにJS単独パターンが含まれる.prh の既定挙動では substring マッチが効くため,
JSONの文字列中のJSも検出されてしまい,意図せず prh が「JS=>JavaScript」 と発火する.本文中のJSON 化・JSON 形式などが誤検出される.提案する修正
word boundary を要求する正規表現に変更する.既存 specs に
JSONを含めて回帰テストを兼ねる.tomio2480/blog-privatePR #1 でも同様の対応をローカル prh.yml に入れた(5b19f3e).中央側を直すことで,per-repo override 不要で利用者全員に修正が行き渡る.関連