docs: consolidate music routing tables into music.md; DMWeb no-music corrections #61

Merged
jqueuniet merged 0 commits from refs/pull/61/head into main 2026-05-14 13:52:03 +02:00
Owner

Summary

Three-part editorial pass on the music documentation:

Part A — Merge docs/formats/md-dat.md into docs/formats/music.md

md-dat.md was named after Mac US's filename (md.dat), but the doc covered all three structural variants of the on-disc music routing table (Format 1 / 2 / 3) including the Format-1 CD.DAT (Sega CD / Mac JP / FM-Towns / PC-9821), Format-2 md.dat (Mac US) and CD.DAT (Amiga), and Format-3 songlist.dat (DOS). The Mac-specific filename in the doc title and path was misleading.

  • Merged the full content into a new ## Music routing tables section in music.md with three Format subsections.
  • Preserved every factual element: per-record layouts, hex dumps, MD5s, the iMapNumber positional-indexing finding, the skcore.cpp:7611 defensive-fallback citation, the 'ckid' MPW Projector resource decode with all field values (Skull_Keep.rcs / MacDMFiles / Kirk Baker / "Music fixes"), the cross-port 'ckid' sweep table, the 10-record Sega CD CD.DAT fully-decoded table, the Amiga music-ID distribution table, and the "Why this rules out the SoundMusicSys-companion theory" subsection.
  • Deleted docs/formats/md-dat.md.
  • Updated 14 cross-references across docs/sources/*.md, docs/external-references.md, ROADMAP.md, and crates/dm2-music/src/{md_dat,songlist,lib}.rs doc comments to point at music.md.

Out of scope: Rust filename / module / type renames (crates/dm2-music/src/md_dat.rs, dm2_music::md_dat, MdDat, MdRecord, formats/dm2_md_dat.ksy). Rename is invasive (public API change, kaitai spec rename, ~30 files) and deserves its own focused PR.

Part B — Deduplicate music.md ↔ overview.md

Selective dedup of port-enumeration prose in music.md against the canonical port-to-format mapping in docs/sources/overview.md § "Cross-port audio routing". Each per-format section's "ports that use this format" enumeration collapsed to a one-line pointer where the port list was pure restatement; port mentions carrying real information (track counts, byte-identity between regions, CDDA-vs-resource-fork distinctions, Mac-US-is-data-only-no-Red-Book-session) preserved.

Part C — Factual corrections per DMWeb

Per DMWeb research, three ports were previously documented with hedge language ("no audio fixtures shipped" — sounds like we don't have a fixture) but are actually confirmed to have no music at all:

  • DOS Beta v0.9: none (per [DMWEB]; sound playback broken on contemporary hardware) — DMWeb notes the game produces "strange noises with the DOSBox emulator", consistent with the absence of music data.
  • IBM PS/V JP: none (port has no music per [DMWEB]) — port confirmed silent.
  • PC-9801 JP retail: none (port has no music per [DMWEB]) — port confirmed silent.
  • PC-9801 JP demo: none (port has no music per [DMWEB]) — port confirmed silent.

Applied to:

  • docs/sources/overview.md — both the attribute matrix (L34-51) and the cross-port audio routing table (L92-104) updated for all four ports with matching language.
  • docs/sources/dos-en-beta.md, docs/sources/ibm-psv-jp.md, docs/sources/pc9801-jp.md, docs/sources/pc9801-jp-demo.md — DMWeb citation added per port.

Net delta

File Before After Δ
docs/formats/music.md 268 587 +319 (Part A merge target)
docs/formats/md-dat.md 311 deleted −311
docs/sources/overview.md 120 120 0 (prettier-reformatted table widths)
docs/sources/amiga-eu.md 317 317 0 (prettier-reformatted table widths for Notes column)
Per-port doc DMWeb additions — — +2 to +3 lines each (4 files)
Cross-ref updates — — small per-file
ROADMAP cross-ref updates — — small

Commit footprint: 18 files changed, 433 insertions, 408 deletions.

Test plan

  • cargo test --workspace — 339 tests pass (unchanged; pure docs).
  • cargo clippy --workspace --all-targets — clean.
  • cargo doc --workspace --no-deps --locked — clean (Rust doc-comment cross-refs in md_dat.rs, songlist.rs, lib.rs updated).
  • prettier --check docs/formats/music.md docs/sources/*.md ROADMAP.md docs/external-references.md — All matched files use Prettier code style!
  • Editorial reviewer (sonnet) verified all 7 content elements from md-dat.md are preserved in the new music.md § "Music routing tables" section, Part B deduplication was appropriate (no over-stripping), Part C DMWeb corrections applied consistently across all four target ports and both overview.md tables, all cross-references resolve, and the high-churn diffs on amiga-eu.md and overview.md are explained by prettier widening table column widths after the longer corrected DMWeb strings were inserted.
  • grep -rn 'md-dat\|md_dat\.md' docs/ ROADMAP.md crates/ — only the intentional historical note in ROADMAP.md:180 remains; Rust filename / module references are out of scope for this PR.

Out of scope

  • Rust-side rename of md_dat.rs / dm2_music::md_dat / MdDat / MdRecord / dm2_md_dat.ksy — separate PR to bikeshed the name (format2_routing vs music_routing vs other).
  • Music routing decoder implementations for Format 1 (CD.DAT) and Format 3 (songlist.dat) — already tracked under Phase 3 ROADMAP bullets.
## Summary Three-part editorial pass on the music documentation: ### Part A — Merge `docs/formats/md-dat.md` into `docs/formats/music.md` `md-dat.md` was named after Mac US's filename (`md.dat`), but the doc covered all three structural variants of the on-disc music routing table (Format 1 / 2 / 3) including the Format-1 `CD.DAT` (Sega CD / Mac JP / FM-Towns / PC-9821), Format-2 `md.dat` (Mac US) and `CD.DAT` (Amiga), and Format-3 `songlist.dat` (DOS). The Mac-specific filename in the doc title and path was misleading. - Merged the full content into a new `## Music routing tables` section in `music.md` with three Format subsections. - Preserved every factual element: per-record layouts, hex dumps, MD5s, the `iMapNumber` positional-indexing finding, the `skcore.cpp:7611` defensive-fallback citation, the `'ckid'` MPW Projector resource decode with all field values (Skull_Keep.rcs / MacDMFiles / Kirk Baker / "Music fixes"), the cross-port `'ckid'` sweep table, the 10-record Sega CD CD.DAT fully-decoded table, the Amiga music-ID distribution table, and the "Why this rules out the SoundMusicSys-companion theory" subsection. - Deleted `docs/formats/md-dat.md`. - Updated 14 cross-references across `docs/sources/*.md`, `docs/external-references.md`, `ROADMAP.md`, and `crates/dm2-music/src/{md_dat,songlist,lib}.rs` doc comments to point at `music.md`. **Out of scope:** Rust filename / module / type renames (`crates/dm2-music/src/md_dat.rs`, `dm2_music::md_dat`, `MdDat`, `MdRecord`, `formats/dm2_md_dat.ksy`). Rename is invasive (public API change, kaitai spec rename, ~30 files) and deserves its own focused PR. ### Part B — Deduplicate music.md ↔ overview.md Selective dedup of port-enumeration prose in music.md against the canonical port-to-format mapping in `docs/sources/overview.md § "Cross-port audio routing"`. Each per-format section's "ports that use this format" enumeration collapsed to a one-line pointer where the port list was pure restatement; port mentions carrying real information (track counts, byte-identity between regions, CDDA-vs-resource-fork distinctions, Mac-US-is-data-only-no-Red-Book-session) preserved. ### Part C — Factual corrections per DMWeb Per DMWeb research, three ports were previously documented with hedge language ("no audio fixtures shipped" — sounds like we don't have a fixture) but are actually confirmed to have **no music at all**: - **DOS Beta v0.9**: `none (per [DMWEB]; sound playback broken on contemporary hardware)` — DMWeb notes the game produces "strange noises with the DOSBox emulator", consistent with the absence of music data. - **IBM PS/V JP**: `none (port has no music per [DMWEB])` — port confirmed silent. - **PC-9801 JP retail**: `none (port has no music per [DMWEB])` — port confirmed silent. - **PC-9801 JP demo**: `none (port has no music per [DMWEB])` — port confirmed silent. Applied to: - `docs/sources/overview.md` — both the attribute matrix (L34-51) and the cross-port audio routing table (L92-104) updated for all four ports with matching language. - `docs/sources/dos-en-beta.md`, `docs/sources/ibm-psv-jp.md`, `docs/sources/pc9801-jp.md`, `docs/sources/pc9801-jp-demo.md` — DMWeb citation added per port. ## Net delta | File | Before | After | Δ | |---|---:|---:|---:| | `docs/formats/music.md` | 268 | 587 | +319 (Part A merge target) | | `docs/formats/md-dat.md` | 311 | deleted | −311 | | `docs/sources/overview.md` | 120 | 120 | 0 (prettier-reformatted table widths) | | `docs/sources/amiga-eu.md` | 317 | 317 | 0 (prettier-reformatted table widths for `Notes` column) | | Per-port doc DMWeb additions | — | — | +2 to +3 lines each (4 files) | | Cross-ref updates | — | — | small per-file | | ROADMAP cross-ref updates | — | — | small | Commit footprint: 18 files changed, 433 insertions, 408 deletions. ## Test plan - [x] `cargo test --workspace` — 339 tests pass (unchanged; pure docs). - [x] `cargo clippy --workspace --all-targets` — clean. - [x] `cargo doc --workspace --no-deps --locked` — clean (Rust doc-comment cross-refs in `md_dat.rs`, `songlist.rs`, `lib.rs` updated). - [x] `prettier --check docs/formats/music.md docs/sources/*.md ROADMAP.md docs/external-references.md` — `All matched files use Prettier code style!` - [x] Editorial reviewer (sonnet) verified all 7 content elements from `md-dat.md` are preserved in the new `music.md § "Music routing tables"` section, Part B deduplication was appropriate (no over-stripping), Part C DMWeb corrections applied consistently across all four target ports and both overview.md tables, all cross-references resolve, and the high-churn diffs on `amiga-eu.md` and `overview.md` are explained by prettier widening table column widths after the longer corrected DMWeb strings were inserted. - [x] `grep -rn 'md-dat\|md_dat\.md' docs/ ROADMAP.md crates/` — only the intentional historical note in `ROADMAP.md:180` remains; Rust filename / module references are out of scope for this PR. ## Out of scope - Rust-side rename of `md_dat.rs` / `dm2_music::md_dat` / `MdDat` / `MdRecord` / `dm2_md_dat.ksy` — separate PR to bikeshed the name (`format2_routing` vs `music_routing` vs other). - Music routing decoder implementations for Format 1 (CD.DAT) and Format 3 (songlist.dat) — already tracked under Phase 3 ROADMAP bullets.
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
jqueuniet/dm2-tools!61
No description provided.