emmercm · emmercm · Aug 30, 2024 · Aug 30, 2024 · Aug 30, 2024 · Aug 30, 2024
diff --git a/README.md b/README.md
@@ -27,19 +27,19 @@
 
 A video of an example use case:
 
-[![asciicast](https://asciinema.org/a/bZHvtbqyQlRfkHIuZXxmtDbiU.svg)](https://asciinema.org/a/bZHvtbqyQlRfkHIuZXxmtDbiU)
+<a href="https://asciinema.org/a/bZHvtbqyQlRfkHIuZXxmtDbiU" target="_blank"><img src="https://asciinema.org/a/bZHvtbqyQlRfkHIuZXxmtDbiU.svg" alt="asciicast" style="width:100%" /></a>
 
 With Igir you can manage a ROM collection of any size:
 
-- 🔍 Scan for DATs, ROMs, and ROM patches - including those in archives (see [scanning](https://igir.io/input/file-scanning) & [archive docs](https://igir.io/input/reading-archives))
+- 🔍 Scan for DATs, ROMs, and ROM patches—including those in archives (see [scanning](https://igir.io/input/file-scanning) & [archive docs](https://igir.io/input/reading-archives))
 - 📂 Organize ROM files by console (see [DAT docs](https://igir.io/dats/overview))
 - 🪄 Name ROM files consistently, including the right extension (see [DAT docs](https://igir.io/dats/overview))
 - ✂️ Filter out duplicate ROMs, or ROMs in languages you don't understand (see [filtering docs](https://igir.io/roms/filtering-preferences))
 - 🗜️ Extract or archive ROMs in mass (see [archive docs](https://igir.io/output/writing-archives))
 - 🩹 Patch ROMs automatically in mass (see [scanning](https://igir.io/input/file-scanning) & [patching docs](https://igir.io/roms/patching))
-- 🎩 Parse ROMs with headers, and optionally remove them (see [header docs](https://igir.io/roms/headers))
+- 🎩 Parse ROMs with headers and optionally remove them (see [header docs](https://igir.io/roms/headers))
 - ↔️ Build & re-build (un-merge, split, or merge) MAME ROM sets (see [arcade docs](https://igir.io/usage/arcade))
-- 🔮 Report on what ROMs are present or missing for each console, and create fixdats for missing ROMs (see [reporting](https://igir.io/output/reporting) & [DAT docs](https://igir.io/dats/overview))
+- 🔮 Report on what ROMs are present or missing for each console and create fixdats for missing ROMs (see [reporting](https://igir.io/output/reporting) & [DAT docs](https://igir.io/dats/overview))
 
 ## How do I run Igir?
 

diff --git a/docs/advanced/logging.md b/docs/advanced/logging.md
@@ -40,7 +40,7 @@ There are additional levels of verbosity that can be enabled with the `-v` flag:
   igir [commands..] [options] -vv
   ```
 
-  This level is helpful to turn on if you want debug why an action didn't take place.
+  This level is helpful to turn on if you want to debug why an action didn't take place.
 
 - **`TRACE` (`-vvv`): print information about actions taken, skipped, and additional information that can be helpful to debug issues.**
 

diff --git a/docs/cli.md b/docs/cli.md
@@ -0,0 +1,40 @@
+# CLI Overview
+
+Igir uses a series of live-updating progress bars to indicate what it is currently working on and how much processing is left to do.
+
+<script src="https://asciinema.org/a/bZHvtbqyQlRfkHIuZXxmtDbiU.js" id="asciicast-bZHvtbqyQlRfkHIuZXxmtDbiU" async="true"></script>
+
+See the [internal operations](advanced/internals.md#order-of-operations) page for more information on every processing that Igir might do.
+
+## Progress bar icons
+
+ASCII symbols are used to indicate what processing is happening. Here is a table of those symbols, in order:
+
+| Symbol (magenta)                                           | Scanning operation                                                                        |
+|------------------------------------------------------------|-------------------------------------------------------------------------------------------|
+| <span style="color:#AA00AA"><b>↻</b></span> (circle arrow) | Files (DATs, ROMs, patches, etc.) are being found/enumerated                              |
+| <span style="color:#AA00AA"><b>↓</b></span> (down arrow)   | [DATs](dats/introduction.md) are being [downloaded](dats/processing.md#scanning-for-dats) |
+| <span style="color:#AA00AA"><b>Σ</b></span> (sigma)        | [DATs](dats/introduction.md) are being parsed                                             |
+| <span style="color:#AA00AA"><b>#</b></span> (hash)         | ROMs are having checksums calculated for [matching](roms/matching.md)                     |
+| <span style="color:#AA00AA"><b>^</b></span> (hat)          | ROMs are being checked for [headers](roms/headers.md)                                     |
+
+| Symbol (cyan)                                                | Per-DAT processing operation                                                                                                                           |
+|--------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|
+| <span style="color:#00AAAA"><b>∩</b></span> (intersection)   | DATs are having parent/clone information [inferred](dats/processing.md#parentclone-inference)                                                          |
+| <span style="color:#00AAAA"><b>↔</b></span> (split arrow)    | DATs are having [merge/split rules](usage/arcade.md#rom-set-merge-types) applied                                                                       |
+| <span style="color:#00AAAA"><b>Σ</b></span> (sigma)          | ROMs are being [matched](roms/matching.md) to the DAT                                                                                                  |
+| <span style="color:#00AAAA"><b>∆</b></span> (delta)          | DAT is being [filtered](roms/filtering-preferences.md#filters), ROM [1G1R rules](roms/filtering-preferences.md#preferences-for-1g1r) are being applied |
+| <span style="color:#00AAAA"><b>.</b></span> (period)         | ROM matches hare having their [extension corrected](output/options.md#fixing-rom-extensions)                                                           |
+| <span style="color:#00AAAA"><b>≟</b></span> (question equal) | ROM matches are being checked for issues                                                                                                               |
+| <span style="color:#00AAAA"><b>∪</b></span> (union)          | ROM matches are being combined into one zip                                                                                                            |
+
+| Symbol (yellow)                                              | Per-DAT writing operation                                                                                                  |
+|--------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------|
+| <span style="color:#AAAA00"><b>#</b></span> (hash)           | Archives are having checksums calculated to [test](commands.md#test) after [writing](commands.md#rom-writing)              |
+| <span style="color:#AAAA00"><b>≟</b></span> (question equal) | Output files are being checked before being [overwritten](output/options.md#overwriting-files), no writing has started yet |
+| <span style="color:#AAAA00"><b>✎</b></span> (pencil)         | Output files are or have been written                                                                                      |
+
+| Symbol                                                | Deleting operation                                                                                          |
+|-------------------------------------------------------|-------------------------------------------------------------------------------------------------------------|
+| <span style="color:#0000AA"><b>♻</b></span> (recycle) | Output directory [cleaned files](output/cleaning.md) are being recycled                                     |
+| <span style="color:#AA0000"><b>✕</b></span> (x)       | Moved ROM matches are being deleted, output directory [cleaned files](output/cleaning.md) are being deleted |
diff --git a/docs/dats/dir2dat.md b/docs/dats/dir2dat.md
@@ -2,7 +2,7 @@
 
 "dir2dat" refers to DATs that have been automatically created based on files in an input directory. [DATs](./introduction.md) generated this way are not typically useful as-is, they usually require some hand editing after creation.
 
-Igir has the ability to create these DATs with the `igir dir2dat` command. Example:
+Igir can create these DATs with the `igir dir2dat` command. Example:
 
 ```shell
 igir dir2dat --input <path> [--input <path>..]

diff --git a/docs/dats/introduction.md b/docs/dats/introduction.md
@@ -46,7 +46,7 @@ And some less popular release groups are:
 
 ## Parent/clone (P/C) DATs
 
-DATs that include "parent" and "clone" information help Igir understand what game releases are actually the same game (are "clones" of each other). Frequently a game will be released in many regions or with different revisions, usually with only language translations and minor bug fixes. For example, No-Intro has 6+ "clones" of Pokémon Blue cataloged.
+DATs that include "parent" and "clone" information help Igir understand what game releases are actually the same game (are "clones" of each other). Frequently, a game will be released in many regions or with different revisions, usually with only language translations and minor bug fixes. For example, No-Intro has 6+ "clones" of Pokémon Blue cataloged.
 
 Being able to know that many releases are actually the same game gives Igir the ability to produce "one game, one ROM" (1G1R) sets with the [`--single` option](../roms/filtering-preferences.md#preferences-for-1g1r). 1G1R sets include only one of these "clone" releases, usually filtered to a language and region, because many people don't care about ROMs they can't understand.
 

diff --git a/docs/dats/processing.md b/docs/dats/processing.md
@@ -4,7 +4,7 @@ Igir has a number of ways it can process [DATs](./introduction.md), and it proce
 
 ## Just tell me what to do
 
-[DATs](./introduction.md) can get fairly complicated, and there are many release groups each with their own focus areas and naming patterns. If all you want to do is organize your ROMs with Igir in some sane way, follow these instructions:
+[DATs](./introduction.md) can get fairly complicated, and there are many release groups, each with their own focus areas and naming patterns. If all you want to do is organize your ROMs with Igir in some consistent way, follow these instructions:
 
 1. Go to the No-Intro DAT-o-MATIC [daily download page](https://datomatic.no-intro.org/index.php?page=download&s=64&op=daily)
 2. Select the "P/C XML" radio option (as opposed to "standard DAT") and download the `.zip` to wherever you store your ROMs

diff --git a/docs/input/reading-archives.md b/docs/input/reading-archives.md
@@ -51,6 +51,6 @@ If for some reason Igir isn't identifying an input file correctly as an archive,
 
 ## Checksum cache
 
-It can be expensive to calculate checksums of files within archives, especially MD5, SHA1, and SHA256. If Igir needs to calculate a checksum that is not easily read from the archive (see above), it will cache the result in a file named `igir.cache`. This cached result will then be used as long as the input file's size and modified timestamp remain the same.
+It can be expensive to calculate checksums of files within archives, especially MD5, SHA1, and SHA256. If Igir needs to calculate a checksum not easily read from the archive (see above), it will cache the result in a file named `igir.cache`. This cached result will then be used as long as the input file's size and modified timestamp remain the same.
 
 The location of this cache file can be controlled with the `--cache-path <path>` option, or caching can be disabled entirely with the `--disable-cache` option. You can safely delete `igir.cache` when Igir isn't running if the file becomes too large for you.
diff --git a/docs/installation.md b/docs/installation.md
@@ -21,7 +21,7 @@ for example:
 npx igir@latest copy extract --dat *.dat --input ROMs/ --output ROMs-Sorted/ --dir-dat-name
 ```
 
-[![asciicast](https://asciinema.org/a/IFU8rU8k800TMVWb9xXv4Jbsv.svg)](https://asciinema.org/a/IFU8rU8k800TMVWb9xXv4Jbsv)
+<script src="https://asciinema.org/a/IFU8rU8k800TMVWb9xXv4Jbsv.js" id="asciicast-IFU8rU8k800TMVWb9xXv4Jbsv" async="true"></script>
 
 !!! tip
 
@@ -49,7 +49,7 @@ npx igir@latest copy extract --dat *.dat --input ROMs/ --output ROMs-Sorted/ --d
 
 ## Via Homebrew (macOS)
 
-[Homebrew](https://brew.sh/) is third-party package manager for macOS. You can install Igir with these simple commands:
+[Homebrew](https://brew.sh/) is a third-party package manager for macOS. You can install Igir with these simple commands:
 
 ```shell
 brew tap emmercm/igir

diff --git a/docs/overview.md → docs/introduction.md b/docs/overview.md → docs/introduction.md
@@ -1,4 +1,4 @@
-# Overview
+# Introduction
 
 ## What is a ROM?
 
@@ -8,7 +8,7 @@ From [Wikipedia](https://en.wikipedia.org/wiki/ROM_image):
 
 ROMs are complete copies of game data stored in cartridges or on discs.
 
-A game may consist of multiple ROMs. For example, arcade cabinets that contain multiple chips, or disc-based games that have multiple tracks on the disc.
+A game may consist of multiple ROMs. For example, arcade cabinets, which contain multiple chips, or disc-based games that have multiple tracks on the disc.
 
 ## What is a ROM manager?
 
@@ -19,9 +19,9 @@ ROM managers are applications that serve two main purposes:
 
 all additional features help serve these two purposes.
 
-Most ROM managers can automatically read & write many different ROM types including those in [archives](input/reading-archives.md) and those with [headers](roms/headers.md) so that you don't have to do much pre-work.
+Most ROM managers can automatically read & write many different ROM types, including those in [archives](input/reading-archives.md) and those with [headers](roms/headers.md) so that you don't have to do much pre-work.
 
-Most ROM managers rely on [DATs](dats/introduction.md), files that catalog every known ROM that exists per game system. DATs are published by release groups dedicated to keeping these catalogs accurate and up-to-date. DATs help ROM collectors name their ROMs in a consistent way as well as understand what ROMs may be missing from their collection.
+Most ROM managers rely on [DATs](dats/introduction.md), files that catalog every known ROM that exists per game system. DATs are published by release groups dedicated to keeping these catalogs accurate and up to date. DATs help ROM collectors name their ROMs consistently as well as understand what ROMs may be missing from their collection.
 
 ## What is Igir?
 

diff --git a/docs/output/cleaning.md b/docs/output/cleaning.md
@@ -47,7 +47,7 @@ See the [Analogue Pocket](../usage/hardware/analogue-pocket.md) page for a pract
 
 ## Backing up cleaned files
 
-By default, Igir will recycle cleaned files, and if recycle fails then it will delete them. This is potentially destructive, so a `--clean-backup <path>` option is provided to instead move files to a backup directory.
+By default, Igir will recycle cleaned files, and if recycle fails, then it will delete them. This is potentially destructive, so a `--clean-backup <path>` option is provided to instead move files to a backup directory.
 
 The input directory structure is not maintained, no subdirectories will be created in the backup directory. Files of conflicting names will have a number appended to their name, e.g. `File (1).rom`.
 

diff --git a/docs/output/reporting.md b/docs/output/reporting.md
@@ -13,7 +13,7 @@ When using DATs (the [`--dat <path>` option](../dats/processing.md#scanning-for-
 
 At least one DAT is required for the `igir report` command to work, otherwise Igir has no way to understand what input files are known ROMs and which aren't. See the [DAT docs](../dats/introduction.md) for more information about DATs.
 
-The `igir report` command can be specified on its own without any [writing command](../commands.md) (i.e. `igir copy`, `igir move`, etc.) in order to report on an existing collection. This causes Igir to operate in a _read-only_ mode, no files will be copied, moved, or deleted. For example:
+The `igir report` command can be specified on its own without any [writing command](../commands.md) (i.e. `igir copy`, `igir move`, etc.) to report on an existing collection. This causes Igir to operate in a _read-only_ mode, no files will be copied, moved, or deleted. For example:
 
 === ":simple-windowsxp: Windows"
 
@@ -48,7 +48,7 @@ See the `igir --help` message for the report's default location.
 
 The output report format is a standard CSV that can be opened in Microsoft Excel, Apple Numbers, Google Sheets, LibreOffice Calc, and other similar spreadsheet applications.
 
-Unlike the report formats of [other ROM managers](../alternatives.md), CSVs allow you to filter rows by column values. For example, you can filter the "Status" column to only "MISSING" to understand what ROMs are missing from your collection, or to "UNUSED" to understand what input files weren't used as the source of any output file. The ability to filter CSVs in spreadsheet applications means that Igir should not need use-case-specific report options to achieve your goal.
+Unlike the report formats of [other ROM managers](../alternatives.md), CSVs allow you to filter rows by column values. For example, you can filter the "Status" column to only "MISSING" to understand what ROMs are missing from your collection, or to "UNUSED" to understand what input files weren't used as the source of any output file. The ability to filter CSVs in spreadsheet applications means that Igir shouldn’t need use-case-specific report options to achieve your goal.
 
 To perform this filtering, most spreadsheet applications have a button or menu item to "create a filter" or "auto filter."
 

diff --git a/docs/rom-dumping.md b/docs/rom-dumping.md
@@ -10,7 +10,7 @@
 
     [Dumping.Guide](https://dumping.guide/start) and [Emulation General Wiki](https://emulation.gametechwiki.com/index.php/Ripping_games) are some of the best resources for legally creating ROM files from games you own.
 
-Here is a condensed version that isn't guaranteed to be up-to-date.
+Here is a condensed version that isn't guaranteed to be up to date.
 
 ## Generation 1-5 cartridge-based consoles