Version 3.1.0: voice lines linked across all languages from the game data

docs/user-guide.md

@@ -27,10 +27,14 @@ game is set to (Steam > game properties > Language) and applies to everything yo
 Changing it reloads the lists; the next start is again in the game's language.
 
 ## Names
-Voice lines carry the game's own line names (e.g. `Speech_TAPE_JOKER_1_04`), the same in every language and the
-same as in the Subtitles tab. Inside a WAD entry the game stores the variations of a line in a different order
-in each language, so the position-based name is kept only as a second name (`Speech_TAPE_JOKER_1#4` = the 4th
-WEM of that entry in this language; search finds both).
+Every voice line has one name in every language, taken from the game itself (e.g. `Speech_TAPE_JOKER_1_04`, the
+same as in the Subtitles tab): the line `Speech_X` in Italian is the same line `Speech_X` in English, French,
+German and Spanish. Inside a WAD entry the game stores the variations of a line in a different order in each
+language, so the position-based name is kept only as a second name (`Speech_TAPE_JOKER_1#4` = the 4th WEM of
+that entry in this language; search finds both). When the game plays one of two versions of a line, the
+second is shown as `NAME#2`. About 6 % of the lines are named by no game event; they take the name of their
+English recording in every language. A few recordings are stored twice in the game files: both rows belong to
+the same line and are changed and reverted together.
 
 ## Find a sound
 - Type in the **search box** (Ctrl+F): words can be parts of the name, a category, a character, your own
@@ -77,8 +81,9 @@ than the original, since the game may cut it off.
 - Right-click rows → **Revert selected**; toolbar **Revert all** puts every original back.
 - Originals are kept in your user data folder (`%APPDATA%\UnheardCity` on Windows,
   `~/.local/share/unheardcity` on Linux), so reverting works after updating or reinstalling the app too.
-  Uninstalling keeps this folder; use **Revert all** before uninstalling if you want the game back to original. Before the first
-  change to an audio archive, one full copy of it is also kept there as a fallback (Settings).
+  Uninstalling keeps this folder; use **Revert all** before uninstalling if you want the game back to original.
+  Before the first change to a game file, a full copy of it is kept there too: optional for the WAD archives
+  (Settings), always for soundbanks, packages and text files (they are rebuilt from that copy).
 - If Steam "Verify integrity of game files" or an update undoes your changes, a bar offers **Re-apply my
   changes** or **Forget them**. Do not use "verify" to undo mods; use Revert all.
 
@@ -90,11 +95,13 @@ The **Subtitles** tab lists the subtitle of every speech line in the selected la
   shows *used / room* characters). Latin-1 subtitles accept Latin-1 characters only (accents are fine);
   Russian, Polish, Japanese and Korean subtitles accept any character.
 - **Go to the sound** opens the speech line in the Sounds tab. In the Sounds tab, the editor of a speech line
-  shows its subtitle under the audio: edit both side by side and use **Apply subtitle**, or **Show in
-  Subtitles** to jump back.
+  shows its subtitle in the **Subtitle** column next to the audio: edit both side by side, **Apply** /
+  **Revert** the subtitle there, or **Show in list** to jump back to the Subtitles tab.
 - **Find and replace…** works on the rows the filters show (texts that would not fit are listed and skipped).
 - **Revert** / **Revert all texts here** put the original text back (every copy in every game file).
-- About 8 % of the subtitles belong to lines the game never plays (placeholders); they have no linked sound.
+- About 30 subtitles per language have no sound in the game (texts such as the Arkham City Stories, unused
+  radio reports); they have no linked sound. A subtitle of a line the game plays in two versions belongs to
+  both. The game itself has no subtitles for efforts and grunts and for most combat barks and cutscene lines.
 
 ## Menu text
 The **Menu text** tab lists every menu, HUD, bio, riddle and credits string of the selected language (about
@@ -107,10 +114,14 @@ Right-click → **Notes & tags…** (F2): free text and comma-separated tags, se
 Click the **★** column to mark favorites. These are stored in your user data folder, not in the game.
 
 ## Share your changes (mods)
-- **Export mod…**: choose which changed sounds to include and save a `.acmod` file (the exact game data plus
-  the audio, so it also works for another language whose original has a different size).
+- **Export mod…**: choose which changed sounds and texts to include and save a `.acmod` file (the exact game
+  data plus the audio, so it also works for another language whose original has a different size).
 - **Import mod…**: shows which sounds match this game, then installs them. You can revert them like any change.
-- Changed subtitles and menu texts are exported and imported with the sounds (listed as *Text*).
+- Changed subtitles and menu texts are exported and imported with the sounds (listed as *Text*); a text stays
+  in its language (an Italian subtitle edit changes the Italian subtitle).
+- In another language, voice lines are matched by the game's own identity of the line, so the same line is
+  replaced even where its position differs. Voice lines from packages made with versions before 3.1 carry no
+  such identity: the import lists them instead of guessing (export the mod again with this version).
 
 ## Settings
 ![Settings](img/settings.png)
@@ -125,6 +136,7 @@ The editor panel opens tall enough to show all its controls; drag the divider ab
 | "Cannot write … close the game" | quit Arkham City (and anything else using the file) and try again |
 | "not a Batman: Arkham City folder" | pick the folder that contains `BmGame` and `Binaries` |
 | "audio is too long for this sound" | shorten the audio (see the original's length) |
+| "the text is … characters long but this subtitle has room for …" | shorten the subtitle (the counter shows the room) |
 | "Cannot read … Supported: WAV, FLAC, …" | convert the file to WAV/MP3/FLAC, or install ffmpeg |
 | "changed outside this tool" | the game files were changed by an update or another tool; revert or confirm to overwrite |
 | no sound when playing | choose another playback device in Settings |