Docs: output path options (#904)

emmercm · Feb 1, 2024 · ef93dac · ef93dac
1 parent 24491f3
commit ef93dac
Show file tree

Hide file tree

Showing 8 changed files with 515 additions and 12 deletions.
diff --git a/docs/output/path-options.md b/docs/output/path-options.md
diff --git a/docs/output/tokens.md b/docs/output/tokens.md
@@ -2,24 +2,35 @@
 
 When specifying a ROM [writing command](../commands.md) you have to specify an `--output <path>` directory. `igir` has a few replaceable "tokens" that can be referenced in the `--output <path>` directory value. This can aid in sorting ROMs into a more complicated directory structure.
 
+See [output path tokens](./path-options.md) for other options that will further sort your ROMs into subdirectories.
+
 For example, if you want to group all ROMs based on their region, you would specify:
 
 === ":simple-windowsxp: Windows"
 
     ```batch
-    igir copy extract --dat *.dat --input ROMs\ --output "ROMs-Sorted\{gameRegion}\"
+    igir copy extract ^
+      --dat *.dat ^
+      --input ROMs\ ^
+      --output "ROMs-Sorted\{gameRegion}\"
     ```
 
 === ":simple-apple: macOS"
 
     ```shell
-    igir copy extract --dat *.dat --input ROMs/ --output "ROMs-Sorted/{gameRegion}/"
+    igir copy extract \
+      --dat *.dat \
+      --input ROMs/ \
+      --output "ROMs-Sorted/{gameRegion}/"
     ```
 
 === ":simple-linux: Linux"
 
     ```shell
-    igir copy extract --dat *.dat --input ROMs/ --output "ROMs-Sorted/{gameRegion}/"
+    igir copy extract \
+      --dat *.dat \
+      --input ROMs/ \
+      --output "ROMs-Sorted/{gameRegion}/"
     ```
 
 This might result in an output structure such as:
@@ -47,8 +58,8 @@ ROMs-Sorted/
 
 When using [DATs](../dats/overview.md), you can make use of console & game information contained in them:
 
-- `{datName}` the matching DAT's name, similar to how the `--dir-dat-name` option works
-- `{datDescription}` the matching DAT's description, similar to how the `--dir-dat-description` option works
+- `{datName}` the matching DAT's name, similar to how the [`--dir-dat-name` option](./path-options.md) works
+- `{datDescription}` the matching DAT's description, similar to how the [`--dir-dat-description` option](./path-options.md) works
 - `{gameRegion}` each of the ROM's region(s) (e.g. `USA`, `EUR`, `JPN`, `WORLD`)
 - `{gameLanguage}` each of the ROM's language(s) (e.g. `EN`, `ES`, `JA`)
 

diff --git a/docs/usage/handheld/minui.md b/docs/usage/handheld/minui.md
@@ -29,7 +29,7 @@ MinUI supports many many systems and ROM formats. Check the folders [here (base)
 
 MinUI uses the names unter /Roms on the SD card in a more creative way than most other frontends. The folder names consist of a *UI name* and a *PAK name*. The *UI name* is used as the name shown in the User interface as a list item name, while the *PAK name* controls which software pack is used to open the files within. Files with the same *UI name* but different *PAK name* are listed in the same list in the UI but are opened with different PAKs. `igir` uses the vendor recommendations for the folder names with some exceptions.
 
-MinUI requires multi-file releases to be grouped into subfolders (bin/cue releases of the PS1 for example). It is recommended to use `--dir-game-subdir=multiple` - which is the default at this time.
+MinUI requires multi-file releases to be grouped into subdirectories (bin/cue releases of the PS1 for example). It is recommended to use the [`--dir-game-subdir multiple` option](../../output/path-options.md), which is the default at this time.
 
 More details about these features can be found [here](https://github.com/shauninman/MinUI/tree/main/skeleton/BASE) under the sections `Roms` and `Disc-based games`.
 

diff --git a/docs/usage/hardware/analogue-pocket.md b/docs/usage/hardware/analogue-pocket.md
@@ -68,11 +68,15 @@ This token can be used to reference each core's specific directory in the SD car
 
 !!! note
 
-    The `--clean-exclude <path>` option in the above examples is so we don't accidentally "clean" (delete) the BIOS files for each core.
+    The `--dat-name-regex-exclude "/headerless/i"` option in the above examples is to exclude any "headered" No-Intro DATs. Some consoles such as NES have separate "headered" and "headerless" DATs, and they have duplicated ROM filenames, so we want to avoid writing different input files to the same output location.
 
 !!! note
 
-    The `--dat-name-regex-exclude "/headerless/i"` option in the above examples is to exclude any "headered" No-Intro DATs. Some consoles such as NES have separate "headered" and "headerless" DATs, and they have duplicated ROM filenames, so we want to avoid writing different input files to the same output location.
+    The `--dir-letter-limit 1000` option in the above example is because some cores won't read more than a certain number of files in one directory. See [output path options](../../output/path-options.md) for other options available.
+
+!!! note
+
+    The `--clean-exclude <path>` option in the above examples is so we don't accidentally "clean" (delete) the BIOS files for each core.
 
 Your SD card should look like this, likely with more cores:
 

diff --git a/docs/usage/hardware/everdrive.md b/docs/usage/hardware/everdrive.md
@@ -42,7 +42,7 @@ Because flash carts are specific to a specific console, you can provide specific
       --no-bios
     ```
 
-you can then add some other output options such as `--dir-letter`, if desired.
+you can then add some other output options such as the [`--dir-letter` option](../../output/path-options.md), if desired.
 
 Alternatively, `igir` supports [Hardware Target Game Database SMDB files](https://github.com/frederic-mahe/Hardware-Target-Game-Database/tree/master/EverDrive%20Pack%20SMDBs) as [DATs](../../dats/overview.md). Unlike typical DATs, Hardware Target Game Database SMDBs typically have an opinionated directory structure to help sort ROMs by language, category, genre, and more. Example usage:
 

diff --git a/docs/usage/hardware/ezflash.md b/docs/usage/hardware/ezflash.md
@@ -42,7 +42,7 @@ Because flash carts are specific to a specific console, you can provide specific
       --no-bios
     ```
 
-you can then add some other output options such as `--dir-letter`, if desired.
+you can then add some other output options such as the [`--dir-letter` option](../../output/path-options.md), if desired.
 
 !!! warning
 

diff --git a/docs/usage/personal.md b/docs/usage/personal.md
@@ -38,7 +38,7 @@ The file tree in that hard drive looks like this:
 └── igir_library_sync.sh
 ```
 
-The root directory has a DAT zip and subdirectory for each [DAT](../dats/overview.md) release group. This helps separate differing quality of DATs and different DAT group ROM naming schemes. I then have one subdirectory for each game console, using the `--dir-dat-name` option.
+The root directory has a DAT zip and subdirectory for each [DAT](../dats/overview.md) release group. This helps separate differing quality of DATs and different DAT group ROM naming schemes. I then have one subdirectory for each game console, using the [`--dir-dat-name` option](../output/path-options.md).
 
 The `igir_library_sync.sh` script helps me keep this collection organized and merge new ROMs into it. The complete source is:
 

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -89,8 +89,9 @@ nav:
           - roms/headers.md
           - roms/patching.md
       - File Outputs:
-          - output/writing-archives.md
+          - output/path-options.md
           - output/tokens.md
+          - output/writing-archives.md
           - output/reporting.md
           - output/cleaning.md
       - Advanced: