Skip to content

docs: ja-no-space-around-parentheses 採用根拠の明文化と prh.yml の JS パターン誤マッチ修正 #13

@tomio2480

Description

@tomio2480

概要

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 に記述)

調査結果は以下のとおり.根拠としての強度は上から順.

観点 内容 出典
業界慣習(翻訳・出版) JTF日本語標準スタイルガイドが全角カッコの内外スペース禁止を規定.preset-ja-spacing もこの方針を踏襲 textlint-rule-preset-JTF-style
日本語組版 全角カッコは前後の文字幅に合わせて字面を縮める前提で設計されている(プロポーショナル・メトリクス).半角スペースを入れると本来不要な余白が二重化する textlint-rule-preset-ja-spacing
アクセシビリティ 直接の研究文献は限定的だが,多くのスクリーンリーダーは句読点・記号を文字として読み上げる(Deque: Screen Readers and Punctuation).冗長なスペースは「スペース」と読み上げる実装もあり,冗長になる懸念
データ量 1 スペース = 1 バイト UTF-8.影響は軽微だが,整合性の観点では「無し」 の方が一貫

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/github-workflows#8:v1 の self-detection / preset / filter 未同梱 各バグ(v2 で解消済み).本 Issue は v2 後の追補にあたる

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions