ewdernaandClaude Opus 5
5b671976d5
未確認事項が「現在の仕様が答えに依存するもの」と「答えが出なくても進められる もの」を混ぜて抱えていた。後者を backlog/README.md へ移し、仕様書の未確認事項を 前者だけに絞る。移す際は保留中の対応範囲・暫定仕様を仕様書本文に明記し、 backlogへの移動が仮説の採用を意味しないようにする。 PHY・ELC・IDXの10件を移し、3ファイルとも未確認事項が空になった。 ルール4では、事実確認の「格上げ条件」と意思決定の「完了条件」を区別する。 仕様書側の保留課題はbacklogの区分へのリンク箇条書きだけに固定し、 末尾は保留課題 → 検討済み・非採用 → 未確認事項の順に置く。 doc-lintをルール5に対応させ、backlogを検査対象に加えた。回帰テストを追加。 Journal: journal/2026-09-22-document-backlog.md Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DKW58HEg8zAQoLrkWByPfD
139 lines
7.7 KiB
Markdown
139 lines
7.7 KiB
Markdown
# IDXレイヤー
|
|
|
|
## 概要
|
|
|
|
IDXレイヤーは、全バリアントにわたるPHYのキーの並び順を持つ。
|
|
番号を使う形式への出力時に、選択したバリアントで使うキーだけを残し、0から連続するキー番号を与える。
|
|
保存した並びの位置と、選択後の出力でのキー番号は区別する。
|
|
|
|
並び順は他のどの情報からも導出できない。設計者が決める情報なので、IDXが正本として持つ。
|
|
ELCのrow/colが「配線から決まるので出力時に導出する」のと、理由が裏返しの関係にある。
|
|
|
|
IDXが持つのは、番号を振る対象のキーと、その並び順だけとする。バリアントの選択は保存しない。
|
|
|
|
## キー番号は公開インターフェース
|
|
|
|
基板を公開すると、他人が書いたキーマップが、出力したレイアウトのキー番号に依存する。
|
|
同じレイアウトで番号を振り直すと、既存のキーマップが別のキーを指す。
|
|
|
|
そのため並び順は正本として保存し、出力のたびに幾何や配線から生成し直さない。
|
|
同じ並びと同じバリアント選択からは、同じ出力番号を得る。
|
|
番号の互換性は出力レイアウトごとに扱い、異なるバリアントの同じ番号が同じキーを指すとは限らない。
|
|
並びへの挿入・削除・並べ替えでは、影響する出力レイアウトの番号が変わることを考慮する。
|
|
|
|
## 幾何から導出しない
|
|
|
|
PHYの座標・ツリー順をキー番号に使わない。
|
|
|
|
クラスターは幾何の編集単位であって論理的な行ではない。親指キーをまとめて回転させるために
|
|
クラスターへ出し入れすると、ツリー順が変わる。ツリー順が番号なら、そこでキーマップがずれる。
|
|
|
|
座標から行を判定する方法は、カラムスタッガードや曲線配列で破綻する。これはKLEの問題点として
|
|
`keyboard-design-layers.md` に挙げたものと同じ性質の話である。
|
|
|
|
## 配線から導出しない
|
|
|
|
ELCのマトリクス位置をキー番号に使わない。
|
|
|
|
- マトリクスの並びとキー番号の並びは一致しない。分割キーボードでは、マトリクスは片方の半身の行を
|
|
並べてからもう片方の行を並べるが、キー番号は視覚的な行ごとに左右を交互に取るのが通例である
|
|
- マトリクスには欠番がある。キー番号は実在するキーに対して連続だが、マトリクスは疎である
|
|
- 基板リビジョンでピンを差し替えたときに、キー番号が動いてはならない
|
|
|
|
row / col 自体がELCの正本ではなく出力時の派生情報である。派生情報から番号を導くと二重に不安定になる。
|
|
|
|
## 出力先が要求する形
|
|
|
|
3つの処理系はいずれも「マトリクス位置の順序付きリスト」を要求し、その並びの位置をキー番号とする。
|
|
どれも人手で書かれており、他の情報から導出されていない。Firmware Generatorはこれらを出力する。
|
|
|
|
| 処理系 | キー番号を決めているもの |
|
|
| --- | --- |
|
|
| QMK | `LAYOUT` マクロの引数順 / `keyboard.json` の `layouts.<NAME>.layout[]` の配列順 |
|
|
| ZMK | matrix transform の `map` の並び順 |
|
|
| KMK | `coord_mapping` の並び順 |
|
|
|
|
## レイアウトバリアント
|
|
|
|
IDXは、番号を振る対象のキーを全バリアントにわたって1つの `order` に持つ。
|
|
各PHYキーIDを別々の要素として並べ、同じIDは重複させない。同じ接続先に配線された排他キーも
|
|
別々の要素にする。物理キーごとに、出力先が要求する並びの中の位置を与えられるようにするため。
|
|
|
|
出力時は、PHYのVariantGroupごとにバリアントを選び、次の手順で出力用の並びを得る。
|
|
|
|
1. 選択したバリアントの配下と、バリアントに属さない共通のキーを対象にする。
|
|
入れ子の場合は、祖先のバリアントも選択されているキーだけを対象にする
|
|
2. `order` から対象外のキーを除く。残ったキー同士の順序は変えない
|
|
3. 残った並びの位置を、0から連続する出力用のキー番号とする
|
|
|
|
保存した `order` は書き換えない。レイアウトごとに独立したIDXや並び順も保存しない。
|
|
同じ接続先の排他キーは選択後に同時には残らないため、別々の要素でも出力の対応表に重複しない。
|
|
番号を使う形式への出力は、バリアントを選択した構成を単位とする。
|
|
|
|
例えば、ANSIのバックスラッシュとISOの `#` が同じ接続先を使う場合も、次のように並べられる。
|
|
QとAは共通キー、バックスラッシュと `#` は排他キーとする。
|
|
|
|
| キー | 保存したorderでの位置 | ANSI出力の番号 | ISO出力の番号 |
|
|
| --- | --- | --- | --- |
|
|
| Q | 0 | 0 | 0 |
|
|
| バックスラッシュ | 1 | 1 | — |
|
|
| A | 2 | 2 | 1 |
|
|
| # | 3 | — | 2 |
|
|
|
|
全体の並びは `Q → バックスラッシュ → A → #`、ANSI出力は `Q → バックスラッシュ → A`、
|
|
ISO出力は `Q → A → #` になる。
|
|
|
|
既存コミュニティレイアウトとの互換出力は、要求順を再現できることを確認したものを対象とする。
|
|
単一の `order` で既存レイアウト全般を再現できることは、現行仕様の前提にしない。
|
|
|
|
## 他レイヤーとの関係
|
|
|
|
IDXはPHYのキーIDだけを参照する。ELCを参照しない。
|
|
|
|
MAPはIDXを参照しない。MAPもキーの参照にPHYのキーIDを使う。
|
|
キーマップを配列として出力するとき、バリアント選択後のIDXの並び順で並べ替える。
|
|
ELCから作るキー番号と接続先の対応表にも、同じ選択後の並びを使う。
|
|
これにより、IDXの編集やバリアント選択で出力番号が変わっても、MAP内のキーIDへの割り当ては書き換えずに済む。
|
|
PHYのIDで参照するELC・MAPの保存データ自体には、番号を詰める処理はない。
|
|
|
|
MAPが番号を持たないキーにキーコードを割り当てていた場合、そのキーは出力に現れない。
|
|
IDXの `order` と突き合わせて検出できる。`order` に含まれていても、選ばれなかったバリアントの
|
|
キーへの割り当ては、その出力には含めない。
|
|
|
|
## 持たないもの
|
|
|
|
- マトリクス座標 (row / col)。ELCの配線から出力時に割り当てる
|
|
- LEDの識別番号。ELCが正本を持つ
|
|
- キーコード (MAPが持つ)
|
|
- キーの物理的な位置とサイズ (PHYが持つ)
|
|
|
|
## 保存形式
|
|
|
|
```ts
|
|
type IDX = {
|
|
order: string[] // 全バリアントの対象キーのPHY ID。各IDは1回だけ現れる。
|
|
// 出力時に対象外のキーを除き、残った並びの位置をキー番号とする
|
|
}
|
|
```
|
|
|
|
番号は個別のフィールドとして持たず、出力時の並びの位置で表すため、出力番号に欠番や飛びは生じない。
|
|
キーIDの重複は許さない。
|
|
|
|
出力番号の対象は `order` に挙げたキーに限る。PHYの部品ノードと `decal` のキーは対象にならない。
|
|
|
|
## 保留課題
|
|
|
|
- [IDXの保留課題](backlog/README.md#idx)
|
|
|
|
## 検討済み・非採用
|
|
|
|
- PHYのツリー順をキー番号とする (journal/2026-09-21-idx-necessity.md)
|
|
- ELCのマトリクス順からキー番号を導出する (journal/2026-09-21-idx-necessity.md)
|
|
- 排他キーで番号を共有し、選択後も番号を詰めない (journal/2026-09-22-idx-variant-output.md)
|
|
- MAPがキー番号を参照する (journal/2026-09-21-idx-necessity.md)
|
|
- レイアウトごとに別のIDXを持つ (journal/2026-09-21-multi-layout.md)
|
|
|
|
## 未確認事項
|
|
|
|
(なし)
|