規定の表現形式の検査
本標準は、何が要求事項で、何がそうでないかを、文面から識別できるように書きます。決まりの正本は第1章 1.5・1.7です。本ページは、その決まりを機械で確かめる検査の書式と運用を定めます。判断の根拠は ADR-0063によります。
何を検査するか
Section titled “何を検査するか”npm run check が scripts/check-provisions.mjs を実行します。単独では npm run lint:provisions で実行します。
| # | 検査 | 対象 | 検出するもの |
|---|---|---|---|
| 1 | 附属書の種別の宣言 | 附属書9編と第1章 1.5 の表 | 表題の「(規定)」「(参考)」と、1.5 の表の「種別」が、登録簿と一致しない |
| 2 | 規定の文末 | 本文8章と規定の附属書 | 依頼の形(「〜ください」)と「〜すべき」の文末 |
| 3 | 表の升の語 | 本文8章と規定の附属書 | 升が「省略可」「任意」「どちらでもよい」である。「省略可」は地の文でも検出する |
| 4 | 附属書の引き方 | 本文8章と規定の附属書 | 参考の附属書を「〜による」で引いている |
| 5 | 参考の附属書 | 参考の附属書 | 要求・禁止の文末(「〜なければなりません」「〜てはなりません」)と、実装マーク |
| 6 | 廃した言い回し | 公開ドキュメント、規則データ、準拠テンプレート | 登録簿に載せた句 |
検出が1件でもあれば、検査は失敗します。警告にとどめる区分はありません。
機械が確かめないこと
Section titled “機械が確かめないこと”次の3つは、機械で判定できません。人が読んで確かめます。
| 確かめないこと | 理由 |
|---|---|
| 「〜できます」が許容か、能力・可能性か | 同じ文末が2つの意味を持つ。文脈を読まないと分からない |
| 平叙の動詞文(「〜します」)が要求か説明か | 文末の形が同じである。第1章 1.7.2 は、迷う文を要求として読むと定める |
| 言い回しを変えた写し | 廃した言い回しの検査は、登録した句をそのままの文字列で探す |
検査が通ることは、書き分けが正しいことを意味しません。検査が確かめるのは、使わないと決めた形が残っていないことだけです。
登録簿は src/data/provision-forms.yaml です。
| キー | 内容 |
|---|---|
documents |
検査の対象のページと種別。normative(本文と規定の附属書)または informative(参考の附属書)。附属書は記号を annex に書く |
retiredCellWords |
表の升に使わない語 |
retiredWordsAnywhere |
地の文でも検出する語 |
retiredPhrases |
廃した言い回し。句、廃した日、廃した決定、代わりに書くこと |
retiredScan |
廃した言い回しを探す置き場と、探さない置き場 |
フェーズ5 とフェーズ6 のページは、documents に登録していません。ページごとの種別を定めていないためです(第1章 1.8)。
廃した言い回しの登録
Section titled “廃した言い回しの登録”条項を改めて古い言い回しを廃したときは、その言い回しの特徴的な句を retiredPhrases へ登録します。同じ事項を書くほかの箇所に古い文が残ると、読み手が古い側で済ませるためです。
- 登録する句は、古い言い回しにだけ現れる短い句にする。一般の語を登録しない
- 登録したら
npm run lint:provisionsを実行し、検出された箇所を、改める・所在を引く形へ替える・対象外として除外する、のいずれかで処理する - 決定の記録(
adr/)は探さない。廃した言い回しを経緯として引くためである - 自動生成の台帳は探さない
zenn/は探さない。派生物の置き場であり、別の査読の経路で改めるためである。廃した言い回しが派生物に残ることを、この検査は検出しない
正当な使用は、行に印を書いて除外します。理由を必ず書きます。理由の無い印は無効です。
| 印 | 効く検査 | 書く場所 |
|---|---|---|
<!-- provision-ok: 理由 --> |
2〜5 | 対象の行 |
retired-ok: 理由 |
6 | 対象の行。Markdown では HTML コメントの中、YAML とスクリプトではコメントの中に書く |
旧版が「〇〇」と呼んだ条件は、この決定によって廃しました。<!-- retired-ok: 廃した旧称を示す -->附属書の種別を変えるとき
Section titled “附属書の種別を変えるとき”附属書の種別(規定・参考)は、あとから変えにくい決定です。変えるときは、次の順で行います。
- 変更を ADR として起票する
- 第1章 1.5 の表、附属書の表題と冒頭の宣言、登録簿の
documentsを改める - 参考へ変える場合は、要求・禁止の文と実装マークを、本文か規定の附属書へ移す。規定へ変える場合は、本文からの引き方を「〜による」へ改める
準拠テンプレートのスキルの文
Section titled “準拠テンプレートのスキルの文”準拠テンプレートのスキルの文のうち、要求と禁止の文末を持つものには、本標準の所在か、テンプレート独自の印を付けます。この検査は別のスクリプト(npm run lint:skills)が行います。書式は実装マークの規約「準拠テンプレートのスキルの文」によります。