refactor: review 0.14 for duplication, deprecated calls and plain docs

docs/engine/cd-player.md

@@ -24,19 +24,18 @@ player, and the driver runs its loop (`Driver.listen` in
 **Improvements:**
 
 - RANDOM TRACK MODE draws the next piece from `std.Random`, among the page's other pieces. The game
-  draws `rand() % 12` up to 20 times for one other than the piece that ended, and plays that piece
-  again where none is.
+  draws `rand() % 12` up to 20 times to find a piece other than the one that ended, and plays the
+  same piece again if it finds none.
 - Mods can change the lists: a load script sets which piece each row plays and its name, and adds
   tracks after the last, up to 96 in all
   ([The CD player's tracks](../guide/scripting.md#the-cd-players-tracks)). The game's are fixed.
-- The lists are pages of the records' tracks, twelve to a page: the Reliant's, the Yamato's, then
-  the tracks mods add, the last page holding what's left. A menu script can turn the page
-  ([The rooms](../guide/scripting.md#the-rooms)). The rows are then numbered as the records number
-  the tracks, 13 to 24 on the Yamato's page and on from 25 after it, and a page's rows without a
-  piece hold nothing to choose. The player keeps the piece chosen
-  by its place among all the tracks rather than by its row, so the pieces that follow it come from
-  its own page, and it shows lit only there. The game keeps the row alone, and numbers each list
-  01 to 12.
+- The lists are pages of the records' tracks, twelve per page: the Reliant's, the Yamato's, then
+  the tracks that mods add, with the rest on the last page. A menu script can turn the page
+  ([The rooms](../guide/scripting.md#the-rooms)). The rows are numbered as in the records: 13 to 24
+  on the Yamato's page, and from 25 on after it. Rows without a piece can't be chosen. The player
+  remembers the chosen piece by its position among all the tracks rather than by its row, so the
+  pieces that follow it come from its own page, and it is lit only on that page. The game only
+  remembers the row, and numbers each list 01 to 12.
 - The pointer is drawn after what scripts draw over the player, so that it stays on top.
 
 ## The screen

docs/engine/radio.md

@@ -348,11 +348,11 @@ instructor speaks in the reminders and the launch's words, and answers PERMISSIO
 A line plays through the speech sample ([Sound](sound.md#speech)), its peaks rounded off and in
 the cockpit's cabin unless `--original`.
 
-**Improvement:** a mod's recording of a line, named after it in any of the formats that
-[Lines](../guide/modding.md#lines) lists, plays in its place as recorded, at its own rate and in its
-own channels, in the same room and matched to the same loudness. The radio looks for a recording
-before a line in the game's codec (`recordings.Source.read`), and FFmpeg's decoders decode one that
-isn't a WAV file, as they decode the crew's lines.
+**Improvement:** a mod's recording of a line, named after the line and in any of the formats that
+[Lines](../guide/modding.md#lines) lists, replaces it and plays as recorded: at its own rate and in
+its own channels, with the same reverb, and matched to the same loudness. The radio looks for a
+recording before it reads a line in the game's codec (`recordings.Source.read`), and FFmpeg decodes
+a recording that isn't a WAV file, as it decodes the crew's lines.
 
 Without a speech sample, as with `--no-sound`, a line still lasts as long as it would play, so its
 face shows and a mission's script that waits for it waits as long ([Speech](sound.md#speech)).

docs/engine/rooms.md

@@ -6,7 +6,7 @@ The hub a single-player campaign comes back to between missions: the Reliant's r
 
 [`game/interface/rooms.zig`](../../src/engine/game/interface/rooms.zig) holds the rooms and the news report, [`rooms/views.zig`](../../src/engine/game/interface/rooms/views.zig) their views, which `tablegen rooms` reads out of the executable (`make room-tables`), and [`rooms/crew.zig`](../../src/engine/game/interface/rooms/crew.zig) the crew ([The crew](#the-crew)). [`induction.zig`](../../src/engine/game/interface/induction.zig) holds the induction, [`in_game_options.zig`](../../src/engine/game/interface/in_game_options.zig) the in-game options, [`restart.zig`](../../src/engine/game/interface/restart.zig) the restart screen, [`game/winmain.zig`](../../src/engine/game/winmain.zig) what `WinMain` does as a campaign starts (`CampaignStart`) and after each mission (`afterMission`), and [`game/gameflow.zig`](../../src/engine/game/gameflow.zig) the campaign it carries from one mission to the next. The driver runs each in a loop of its own ([`openreliant/rooms.zig`](../../src/openreliant/rooms.zig)), and plays the movies between them as the game plays them ([Movies](movies.md)).
 
-The pilot roster's START GAME leads into the rooms, through the induction for mission 1; its LOAD GAME, into the rooms before the loaded game's mission, as START GAME would, through the induction where that is mission 1 ([Front end](front-end.md#the-saved-games)). The briefing room's door leads to the briefing ([Briefing](briefing.md)), and then to the mission, after the hangar's movie. Use ITAC opens the ITAC ([The ITAC](itac.md)), Enter Simulator Pod the pod ([The simulator pod](simulator-pod.md)), Open Locker the locker ([The locker](locker.md)), and Use CD player the CD player ([The CD player](cd-player.md)). The in-game options' MAIN MENU leads back to the main menu, and QUIT quits. After the mission the campaign goes on through the rooms to the next briefing, or through the restart screen to the same mission ([After a mission](#after-a-mission)). While the window is away, the rooms pause the music and the voices, as the message pump does. The game's pump also waits for the window to come back, but the rooms keep running, and the paused music counts as playing, so the CD player doesn't take it for the end of a track ([Output](../port/sound.md#output)).
+The pilot roster's START GAME leads into the rooms, through the induction for mission 1; its LOAD GAME, into the rooms before the loaded game's mission, as START GAME would, through the induction where that is mission 1 ([Front end](front-end.md#the-saved-games)). The briefing room's door leads to the briefing ([Briefing](briefing.md)), and then to the mission, after the hangar's movie. Use ITAC opens the ITAC ([The ITAC](itac.md)), Enter Simulator Pod the pod ([The simulator pod](simulator-pod.md)), Open Locker the locker ([The locker](locker.md)), and Use CD player the CD player ([The CD player](cd-player.md)). The in-game options' MAIN MENU leads back to the main menu, and QUIT quits. After the mission the campaign goes on through the rooms to the next briefing, or through the restart screen to the same mission ([After a mission](#after-a-mission)). While the window is inactive, the rooms pause the music and the voices, as the message pump does. The game's pump also blocks until the window is active again. In OpenReliant the rooms keep running, and the paused music counts as playing, so the CD player doesn't take the pause for the end of a track ([Output](../port/sound.md#output)).
 
 As the rooms open, they write the pilot's profile with the call sign ([The pilot's profile](../formats/profile.md)).
 
@@ -26,7 +26,7 @@ As the rooms open, they write the pilot's profile with the call sign ([The pilot
 - The loudest peaks of Enriquez's scenes are rounded off, as the radio's lines' are ([Radio](radio.md)). `--original` cuts them flat.
 - The rooms' sounds, the hum, the steps, the doors and the crew's lines, ring subtly in a small room of the ship, and Enriquez's scenes on the television and the monitors as the radio's voices do, in the cockpit's cabin, as over a speaker ([Sound](../port/sound.md#openal-soft)); the game plays them dry. `--no-reverb` and `--original` leave the rooms out.
 - Mods can change the views: a load script sets their movies, labels, exits, hotspots, actions and sounds ([The rooms' views](../guide/scripting.md#the-rooms-views)), which the rooms read from the records (`rooms.install`). The game's are fixed.
-- Mods' scripts can tell which view the player is in and which place's screen shows, and draw over the rooms and the places' screens ([The rooms](../guide/scripting.md#the-rooms)). The pointer of the rooms, the ITAC, the simulator pod, the locker and the CD player is drawn after what scripts draw, so that it stays on top.
+- Mods' scripts can read which view the player is in and which place's screen is showing, and draw over the rooms and the places' screens ([The rooms](../guide/scripting.md#the-rooms)). The pointer of the rooms, the ITAC, the simulator pod, the locker and the CD player is drawn after what scripts draw, so that it stays on top.
 
 ## The carrier
 

docs/engine/sound.md

@@ -149,12 +149,12 @@ it; it keeps its full volume half as far again (`sound3d.MissileSound.follows`).
 
 **Improvement:** the game's rates are made for its 3D sounds, which are recorded at 22,050 Hz, so a
 mod's sound at another rate would play at another pitch: an octave low at 44,100 Hz. OpenReliant
-scales the rates a mod's sound plays at by its own rate over 22,050 (`sound3d.rateScale`), whether
-it replaces one of the bank's sounds or is a ship type's or a gun's own. The game's own sounds play
-at the game's rates, including `CLOAK01`'s, which is recorded at 44,100 Hz and plays an octave low.
-A voice is freed once its sound has played at the rate it plays at: its frames over 22,050, scaled
-for a mod's sound, so that a mod's sound at another rate or in stereo isn't stopped early or held
-on (`hog_snd.Sound.update3D`).
+scales the rates a mod's sound plays at by the sound's own rate divided by 22,050
+(`sound3d.rateScale`), whether it replaces one of the bank's sounds or belongs to a ship type or a
+gun. The game's own sounds play at the game's rates, including `CLOAK01`, which is recorded at
+44,100 Hz and plays an octave low. A voice is freed once its sound has finished at the rate it
+plays at: its frames divided by 22,050, scaled for a mod's sound, so a mod's sound at another rate
+or in stereo isn't cut short or kept too long (`hog_snd.Sound.update3D`).
 
 ### The player's engine
 
@@ -216,7 +216,7 @@ the pieces of its lists, and turns their level ([The CD player](cd-player.md)).
 
 ## Script sounds
 
-Not the game's: player and menu scripts play sounds on the game's voices
+Added by OpenReliant: player and menu scripts play sounds on the game's voices
 ([Sound](../guide/scripting.md#sound)). Each script sound gets an ID, which its voice stores
 (`hog_snd.Starter`). A game sound that takes the voice clears the ID.
 

docs/formats/fat.md

@@ -66,22 +66,22 @@ The payload loads these banks by name:
 
 | Bank | What it holds |
 |---|---|
-| `stdsmp.fat` | The menus' and the flight display's sounds, which scripts play by number too, and the sounds of a frame placed around the camera ([Sound](../engine/sound.md#positional-sounds-of-a-frame)) |
+| `stdsmp.fat` | The sounds of the menus and the flight display, which scripts can also play by number, and the sounds of a frame placed around the camera ([Sound](../engine/sound.md#positional-sounds-of-a-frame)) |
 | `smp3d.fat` | The 3D sounds: guns, missiles, explosions, engines, jumps and more, which `sltool fat ls` names ([3D sounds](../engine/sound.md#3d-sounds)) |
 | `betty.fat` | Betty's warnings in the cockpit |
-| `ldsmp.fat` | The loadout's |
-| `inter\itac\itacsnd.fat` | The ITAC's |
-| `vrsnd.fat`, `wlksmp.fat` | A carrier's rooms': the ship's hum and the ways into some views; the player's steps and the doors |
-| `vrsfx.fat`, `waitloop.fat` | The briefing's: the way in's doors and the room's chatter; the sound that plays while it loads |
-| `newsloop.fat`, `rlanda.fat` to `rlande.fat`, `ylanda.fat` to `ylande.fat` | The landings': the news reports' loop, and a sound for each outcome of a landing on the Reliant or the Yamato |
+| `ldsmp.fat` | The loadout's sounds |
+| `inter\itac\itacsnd.fat` | The ITAC's sounds |
+| `vrsnd.fat`, `wlksmp.fat` | A carrier's rooms: the ship's hum and the ways into some views; the player's steps and the doors |
+| `vrsfx.fat`, `waitloop.fat` | The briefing: the doors on the way in and the room's chatter; the sound that plays while it loads |
+| `newsloop.fat`, `rlanda.fat` to `rlande.fat`, `ylanda.fat` to `ylande.fat` | The landings: the news reports' loop, and a sound for each outcome of a landing on the Reliant or the Yamato |
 
 ## Mods' sounds
 
 A mod's sound replaces one of a bank's sounds. It's named after the bank and the sound's number, as
 `sltool fat extract` saves it (`fat.soundName`), and is a WAVE, FLAC, MP3, Ogg Vorbis or Opus file
-([Sounds](../guide/modding.md#sounds)). As OpenReliant reads a bank, it makes a new one in memory
-with the mods' sounds in place of the bank's own, each entry keeping its priority (`fat.rebuild`,
-`hog_snd.BankFile.of`), so the game plays them as it plays its own. A sound the drivers can't play
-stays the bank's own, and the log says so.
+([Sounds](../guide/modding.md#sounds)). When OpenReliant reads a bank, it builds a new one in
+memory with the mods' sounds instead of the bank's own, each entry keeping its priority
+(`fat.rebuild`, `hog_snd.BankFile.of`), so the game plays them like its own. If the drivers can't
+play a mod's sound, the bank's own sound stays, and the log says so.
 
 **Improvement:** the original plays only its banks' own sounds.

docs/formats/flac.md

@@ -27,8 +27,8 @@ The first block is always the STREAMINFO, 34 bytes long:
 file's rate and channels, which a voice or the music plays (`bink.AudioDecoding`). The whole file
 goes to the decoder as one packet: the decoder reads the marker and the metadata, then decodes one
 frame at a time. Samples of more than 16 bits keep their top 16 bits, as FFmpeg's own conversion
-does. A line of speech decodes all at once, and a piece of music a few seconds of music each frame
-of the game, starting once it's decoded ([The driver](../port/sound.md#the-driver)).
+does. A line of speech is decoded all at once, and a piece of music a few seconds at a time, once a
+frame, starting once it is fully decoded ([The driver](../port/sound.md#the-driver)).
 
-Where a mod has a recording in more than one format, OpenReliant takes the first in the order that
+If a mod has a recording in more than one format, OpenReliant uses the first in the order that
 [Music](../guide/modding.md#music) gives (`recordings.Source.find`).

docs/formats/mp3.md

@@ -11,9 +11,9 @@ file the discs hold is MPEG-2 audio, Layer III, at 22,050 Hz in joint stereo, 64
 [`formats/mp3.zig`](../../src/formats/mp3.zig) reads a file's frames, and FFmpeg's MP3 decoder
 ([Platform](../port/platform.md#movies)) decodes them one at a time into a WAVE file of 16-bit PCM
 at the first frame's rate and channels, which a voice or the music plays (`bink.AudioDecoding`). A
-crew's line decodes all at once (`bink.Codec.decodeMp3`), and so does a mod's line of speech in MP3
-([Lines](../guide/modding.md#lines)). A mod's piece of music in MP3 decodes a few seconds of music
-each frame of the game, and starts once it's decoded ([Music](../guide/modding.md#music)).
+crew's line is decoded all at once (`bink.Codec.decodeMp3`), and so is a mod's line of speech in MP3
+([Lines](../guide/modding.md#lines)). A mod's piece of music in MP3 is decoded a few seconds at a
+time, once a frame, and starts once it is fully decoded ([Music](../guide/modding.md#music)).
 
 ## Frames
 

docs/formats/ogg.md

@@ -23,7 +23,7 @@ A file is a series of pages (RFC 3533), each with a header of 27 bytes:
 | 26 | 1 | Number of segments |
 
 The lengths of the segments follow, one byte each, and then the segments. A segment shorter than
-255 bytes ends its packet, so a packet runs over as many segments, and pages, as it needs. The
+255 bytes ends its packet, so a packet spans as many segments, and pages, as it needs. The
 checksum is a CRC-32 with the polynomial `0x04C11DB7`, starting at 0, neither reflected nor
 inverted, over the whole page with the checksum's own bytes as 0.
 
@@ -48,15 +48,15 @@ samples that were encoded.
 
 ## In OpenReliant
 
-[`formats/ogg.zig`](../../src/formats/ogg.zig) reads the pages and checks their checksums, puts
-together the packets of the file's first stream, and reads the stream's headers. It passes over
-bytes that start no page, pages that are cut short or damaged, and any packet that a missing page
-cuts. FFmpeg's Vorbis and Opus decoders ([Platform](../port/platform.md#movies)) then decode the
+[`formats/ogg.zig`](../../src/formats/ogg.zig) reads the pages and checks their checksums,
+reassembles the packets of the file's first stream, and reads the stream's headers. It skips bytes
+that don't start a page, pages that are truncated or damaged, and any packet that a missing page
+cuts off. FFmpeg's Vorbis and Opus decoders ([Platform](../port/platform.md#movies)) then decode the
 packets into a WAVE file of 16-bit PCM at the stream's rate and channels (`bink.AudioDecoding`).
 The Vorbis decoder takes the three headers laced together: the byte 2, the lengths of the first two
 headers in the way a page gives its segments' lengths, then all three headers. The Opus decoder
 takes the identification header, drops the pre-skip and applies the output gain. OpenReliant then
-cuts the samples past the stream's end, the last page's granule position less the pre-skip, so that
-a sound or a piece of music loops without a gap. A line of speech or a sound decodes all at once,
-and a piece of music a few seconds of music each frame of the game, starting once it's decoded
+cuts the samples past the stream's end, the last page's granule position minus the pre-skip, so
+that a sound or a piece of music loops without a gap. A line of speech or a sound is decoded all at
+once, and a piece of music a few seconds at a time, once a frame, starting once it is fully decoded
 ([The driver](../port/sound.md#the-driver)).