Update documentation and readme

Author: Ben-Kerman

README.md

@@ -1,11 +1,10 @@
 # Immersive
 
 Immersive is an mpv script for improving language immersion, with a special
-focus on sentence mining. It can automatically generate Anki cards including a
-dictionary definition of the target word, an audio clip of the sentence(s), a
-screenshot of the video, and pronunciation audio from
-[Forvo](https://forvo.com/). The script is highly configurable and supports
-many possible workflows.
+focus on sentence mining. It can automatically generate Anki cards with
+dictionary definitions of the target word, sentence audio clips, screenshots
+from the video, and pronunciation audio taken from [Forvo](https://forvo.com/).
+The script is highly configurable and supports many possible workflows.
 
 This is a short video walking through the full process of creating a card with
 Immersive: https://youtu.be/FrTcu4ZO92w. It's possible to skip parts of the
@@ -38,13 +37,19 @@ Immersive supports all major desktop operating systems:
 	</tr>
 	<tr>
 		<td colspan="3">curl</td>
-		<td>web requests (Forvo, AnkiConnect). Already present by default on most systems.<br>Included in Windows 10 since April 2018</td>
+		<td>
+			web requests (Forvo, AnkiConnect). Already present by default on most systems.
+			Part of Windows 10 since April 2018
+		</td>
 	</tr>
 	<tr>
 		<td>socat</td>
 		<td>-</td>
 		<td>netcat (<code>nc</code>)</td>
-		<td>background playback (audio preview and Forvo). <code>nc</code> is included in macOS 10.13 and later.</td>
+		<td>
+			background playback (sentence and Forvo audio preview).
+			<code>nc</code> is included with macOS 10.13 and later.
+		</td>
 	</tr>
 	<tr>
 		<td>xclip</td>
@@ -63,30 +68,39 @@ The basic process for creating cards is as follows:
 
 1. Bring up the subtitle selection menu (`a`)
 2. Select the subtitles that should be on the card using `a` or the autoselect
-(toggle with `A`). If there are no subtitles or if they are badly timed, set
-the start/end time for the audio export manually using `Q` and `E`. If you
-wish to take a screenshot at a specific time instead of the current frame, set
-it using `s`.
+   (toggle with `A`). If there are no subtitles or if they are badly timed, set
+   the start/end time for the audio export manually using `Q` and `E`. If you
+   wish to take a screenshot at a specific time instead of the current frame,
+   set it using `s`.
 3. Enter target word selection mode using `d`. Select the target word with
-(`Ctrl`+)`⇧`+`←`/`→` and confirm it using (`⇧`+)`⏎`. It's possible to search
-for an external word from the clipboard using `v` if there are no text
-subtitles or if a word can't be found.
-4. Optionally add Forvo audio by pressing `a` after adding a target word.
-5. Export to Anki using `f`.
+   (`Ctrl`+)`⇧`+`←`/`→` and confirm it using (`⇧`+)`⏎`. It's possible
+   to search for an external word from the clipboard using `v` if there are no
+   text subtitles or if a word can't be found.
+4. Choose a definition from the dictionary entries with `↑`/`↓` and `⏎`. Switch
+   between dictionaries with `←`/`→` if you have more than one configured.
+5. Optionally add Forvo audio by pressing `a` after adding a target word.
+6. Export to Anki using `f`.
 
 The card creation process is highly customizable. For further information read
 [this](/doc/card-export.md).
 
 ### Dictionary Lookup in mpv
 
-You can look up words in your configured dictionaries. Bring up the word
+You can look up words in your configured dictionaries at any time. Open the word
 selection menu by pressing `k` and search for the selection using (`⇧`+)`⏎`.
 
+### Automatic Deinflection
+
+Immersive supports automatic deinflection (deconjugation) based on the same
+tables that the Migaku Dictionary addon for Anki uses in addition to a
+simpler Japanese-specific deinflector.
+Read [this page](/doc/lookup-transformations.md) for details.
+
 ### Subtitle Copying
 
 Immersive can copy subtitles to the clipboard. Use `c` to manually copy the
 active line at any time, or toggle automatic copying with `C`. You can
-partially copy a line in the menu for selecting text from the active line.
+partially copy lines from the active line menu (`k`).
 
 
 ## Installation & Setup
@@ -102,19 +116,21 @@ config files to match it as well.
 All necessary files can be downloaded as a ZIP file from the latest
 [release](https://github.com/Ben-Kerman/immersive/releases). When installing
 Immersive from a release archive, it only needs to be extracted into the mpv
-config directory for the full release, or `scripts` directory for the
-script-only release. The above directory is already contained in the archive.
+config directory for the full release, or `scripts` directory for the script-only
+release. The `immersive` directory is already contained in the archive.
 
 If you want the most up-to-date version possible, use the "Code" button at the
 top of the repo's start page. Simply extract the contents of the file into
 your mpv scripts folder and remove the branch name (most likely `-master`)
 from the name of the extracted directory.
 
+---
+
 The script is configured in several different files. These need to be placed
 in a directory called `script-opts` that is located next to your `mpv.conf`
 and `scripts` folder. For a description of the general config syntax, see [this
 document](/doc/config.md). Except for `immersive-dictionaries.conf` all config
-files can be reloaded from the global menu (`Ctrl+a`) at runtime.
+files can be reloaded from the global menu (`Ctrl`+`a`) at runtime.
 
 In order to use the main feature of generating Anki cards with included
 definitions, these config files need to be present:
@@ -123,9 +139,9 @@ definitions, these config files need to be present:
 
 The following config files are optional:
 - [`immersive.conf`](/doc/script-config.md): general configuration of the script
-- [`immersive-keys.conf`](/doc/keys.md): reassign menu key bindings
-- [`immersive-series.conf`](/doc/series.md): use custom series IDs and titles
-- [`immersive-style.conf`](/doc/style.md): change the appearance of the interface
+- [`immersive-keys.conf`](/doc/keys.md): reassign key bindings
+- [`immersive-series.conf`](/doc/series.md): custom series IDs and titles
+- [`immersive-style.conf`](/doc/style.md): appearance of the interface
 
 Documentation that is not about specific config files:
 - [Config Syntax](/doc/config.md)
@@ -135,7 +151,7 @@ Documentation that is not about specific config files:
 
 ### Updating
 
-To update Immersive, delete the script's folder in your mpv config directory
+To update Immersive, delete the script's folder in your `scripts` directory
 and replace it with the one from the latest release's script-only ZIP file.
 Also check if there were any changes to config entries that you have used in
 the [change log](/CHANGELOG.md).
@@ -152,8 +168,8 @@ the [change log](/CHANGELOG.md).
    `profile`, `deck`, `note_type`, and the `field:` values so that they match
    your Anki setup.
 5. Open `immersive-dictionaries.conf` and set up your dictionaries as
-   explained [here](/doc/dictionaries.md). If you are learning Japanese and using
-   the Yomichan version of JMdict, you will most likely only have to change
+   explained [here](/doc/dictionaries.md). If you are learning Japanese and are
+   using the Yomichan version of JMdict, you will most likely only have to change
    `location` so it is set to the path of a directory containing the unzipped
    contents of `jmdict_english.zip` from the Yomichan website.
 
@@ -176,7 +192,7 @@ script-opts/
     immersive.conf
 ```
 
-You can now start mpv and open the main menu of Immersive using `Ctrl+a` or
+You can now start mpv and open the main menu of Immersive using `Ctrl`+`a` or
 begin creating a card with `a`.
 
 
@@ -185,7 +201,7 @@ begin creating a card with `a`.
 If Immersive crashes at any point (when this happens, the interface suddenly
 disappears and all keybindings stop working), open the console using `ˋ`/`~`,
 take a screenshot of it and report the issue to me. If you started mpv from
-the command line the output there is preferable.
+the command line the output there is preferred.
 
 
 ## Suggestions & Reporting Issues

doc/card-export.md

@@ -9,22 +9,22 @@ of the screen. Information on timing is at the bottom left, and a help menu
 listing all available key bindings is at the top left.
 
 Pressing `a` again adds the current subtitle to the selection. By default all
-subtitles are automatically added to the selection. This can be toggled with
-`A`, or disabled by default in the script config.
+subtitles are added automatically. This behavior can be toggled with `A`, or
+disabled in the script config.
 
 `q` and `e` can be used to set the timing of the exported audio clip manually
-to the start or end of the currently visible subtitle. `Q` and `E` do the same
+to the start or end of the currently active subtitle. `Q` and `E` do the same
 but using the current playback time instead. `s` sets the screenshot time to
 the current frame. Pressing the timing keys again while a time is set resets
 the corresponding time if the keypress would have set it to the same value.
 For example, if the screenshot time is set to `15:00.000` and the current
 timestamp in the video is also `15:00.000`, pressing `s` will unset the
 screenshot time.
 
-If no times are set, the clip will begin at the start of the first subtitle
-and end at the end of the last subtitle. The screenshot will be the frame
-that's visible when the export happens. Screenshots can be toggled with `s` in
-the global menu.
+If no times are set, the clip will begin at the start of the first selected
+subtitle and end at the end of the last one. The screenshot will be the frame
+that's visible when the export happens. Screenshots can be toggled with `s`
+in the global menu.
 
 `y` resets the selection and times. `p` plays the audio that would be exported
 with the current selection/times. `d` ends the subtitle selection and begins
@@ -36,9 +36,9 @@ first.
 ## Single Subtitle Export
 
 By pressing `K`, line selection is skipped and the target word selection is
-started immediately with the current subtitle. `Ctrl+k` skips the entirety of
+started immediately with the current subtitle. `Ctrl`+`k` skips the entirety of
 the card creation process and instantly exports a card of the active subtitle
-including an audio clip and screenshot. `Ctrl+K` opens the export menu first.
+including an audio clip and screenshot. `Ctrl`+`K` opens the export menu first.
 
 
 ## Target Word Selection
@@ -52,24 +52,27 @@ Unneeded parts of the text are deletable using the bindings described in
 [keys.md](/doc/keys.md#text_select).
 
 The word can be selected with the usual key combinations for selecting text:
-(`Ctrl+`)(`⇧+`)`←`/`→`. `↑` and `↓` switch between subtitles and `DEL` removes
-the current one from the selection. Once you have chosen some text, you can
-look up any dictionary entries that match it exactly using `⏎` and any entries
-starting with it using `⇧+⏎`. Any whitespace characters (according to Unicode
-properties, including zero width spaces (U+200B)) before or after the word are
-automatically removed before searching.
+(`Ctrl`+)(`⇧`+)`←`/`→`. `↑` and `↓` switch between subtitles and `Alt`+`DEL`
+removes the current one from the selection.
+
+Once you have chosen some text, you can look up any dictionary entries that
+match it exactly using `⏎` and any entries starting with it using `⇧`+`⏎`. If
+you have lookup transformations configured you can use those with `Ctrl`+`⏎`.
+Any whitespace characters (according to Unicode properties, including zero
+width spaces (U+200B)) before or after the word are automatically removed
+before searching.
 
 If the search has any results, a new menu will open that allows you to choose
-one of them with `↑`/`↓` and `⏎`, or `Ctrl+⏎` to add multiple definitions
+one of them with `↑`/`↓` and `⏎`, or `Ctrl`+`⏎` to add multiple definitions
 without returning to the previous menu. `←`/`→` can be used to switch between
 dictionaries (in the current group, if more than one is configured).
 
 After selecting a definition, the word will be shown at the bottom right of
-the screen. If you want, you can then add pronunciation audio from Forvo using
-`a` (see below).
+the screen. If you want, you can now add
+pronunciation audio from Forvo using `a` (see below).
 
 Like during subtitle selection, you can preview the selection audio with `p`.
-`⌫` removes the last selected word.
+`Alt`+`⌫` removes the newest selected word.
 
 When you are ready to export the card, you can do so using `f`, or `F` if you
 want to open the export menu first.
@@ -86,7 +89,7 @@ playing. If you want to load all audio files automatically set
 Once you have selected a pronunciation that you are happy with, confirm it
 using `⏎`.
 
-If your target language is not Japanese you will have to change `forvo_language`
+If your target language is not Japanese you have to change `forvo_language`
 in the script config. The language code can be found on the Forvo website, for
 example on [this page](https://forvo.com/word/%E6%97%A5%E6%9C%AC/) at the right of:
 
@@ -95,15 +98,15 @@ example on [this page](https://forvo.com/word/%E6%97%A5%E6%9C%AC/) at the right
 
 ## Export Menu
 
-The export menu allows exporting a card using Anki's 'Add' GUI (`g`) and
+The export menu allows exporting a card using Anki's 'Add' GUI (`g`), and
 adding the export to an existing note.
 
 The candidates for adding are found using the following query: `"deck:<target
 deck>" "note:<target note type>" is:new`, so all new cards of the target note
 type from the target deck.
 
 `s` exports by adding to the most recently added candidate. `a` allows
-selecting a note from the list of candidates first. You can pick a note with
+selecting a note from a list of candidates first. You can pick a note with
 `↑`/`↓` and `⏎`. If you want to change how notes are displayed, you can use
 the target config entry `note_template`:
 
@@ -148,8 +151,8 @@ configured to be.
 
 Then the following template is applied to each field of the target note type,
 as configured by the `field:...` entries of the target config, as well as to
-all tags in the target's `tags` entry (additionally, spaces are replaced by
-underscores in tags):
+all tags in the target's `tags` entry (any spaces in variable values are
+replaced by underscores in tags):
 
 <table>
 	<tr>
@@ -158,7 +161,7 @@ underscores in tags):
 		<th>Description</th>
 	</tr>
 	<tr>
-		<th colspan="3"><code>field:&lt;field name&gt;</code></th>
+		<th colspan="3"><code>field:&lt;field name&gt;</code>/<code>tags</code></th>
 	</tr>
 	<tr>
 		<td><code>word</code></td>
@@ -283,14 +286,14 @@ The card is exported with the resulting fields and tags.
 ### Substitutions
 
 The variables `definitions` and `sentences` can be filtered through
-substitutions before being exported. These are defined in the entries
-`definition_substitutions` and `sentence_substitutions` of the target config.
+substitutions before being exported. These are defined in the target config
+entries `definition_substitutions` and `sentence_substitutions`.
 
 `sentence_substitutions` are applied when selecting a subtitle line,
-`definition_substitutions` before the definition is added to the note
+`definition_substitutions` as the definition is added to the note
 immediately before it is sent to Anki.
 
-Both those entries expect a multiline value, with each line representing a
+Both entries expect a multiline value, with each line representing a
 substitution, e.g. this is what the default value of `sentence_substitutions`
 would look like in a config file:
 
@@ -304,19 +307,19 @@ sentence_substitutions=[[
 Each line is split at the first `<`. Everything to the left of it becomes the
 replacement and everything to the right becomes the pattern. If you want to
 use a `<` in the replacement string, you can escape it as `\<`. Other common
-escapes like `\n` or `\t` work as well, both in the replacement and pattern.
+escapes like `\n` or `\t` work as well, in both the replacement and pattern.
 
 The pattern is a [Lua pattern](https://www.lua.org/manual/5.1/manual.html#5.4.1),
 which means that the following characters need to be escaped by placing a `%`
 before them if you want to use them literally: `^$()%.[]*+-?`.
 
 All occurrences of the pattern are replaced by the replacement string, or
-deleted if the string is empty (i.e. the `<` is the first character of the
+deleted if the string is empty (i.e. `<` is the first character of the
 substitution definition). The patterns are applied one after the other in the
 order they are defined in.
 
 The default value of `sentence_substitutions` contains the patterns `（.-）` and
-`%(.-%)`, both with an empty replacement. They delete character names and
+`%(.-%)` (both with an empty replacement), which delete character names and
 kanji readings from Japanese subtitles. If you want to disable them, simply
 put this line in the global section of `immersive-targets.conf`:
 

doc/config.md

@@ -39,7 +39,7 @@ bar
 ]]
 ```
 
-If there should be a line containing `]]`, a string can be added between the
+If there needs to be a line containing `]]`, a string can be added between the
 `[` of the opening token, which then has to be present in the closing token as
 well, like this: