Skip to content

Commit

Permalink
Docs: update (#550)
Browse files Browse the repository at this point in the history
  • Loading branch information
emmercm authored Aug 6, 2023
1 parent 6056738 commit ed1224c
Show file tree
Hide file tree
Showing 31 changed files with 474 additions and 128 deletions.
11 changes: 7 additions & 4 deletions .github/workflows/pages.yml
Original file line number Diff line number Diff line change
Expand Up @@ -14,17 +14,20 @@ on:
- published

jobs:
markdown-lint:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- run: docker run -v $PWD:/workdir ghcr.io/igorshubovych/markdownlint-cli:latest --disable MD013 MD033 MD046 -- "**/*.md"

mkdocs-build:
build:
if: github.event_name == 'pull_request'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
with:
# the `git-revision-date-localized` plugin needs full history to find page creation date
fetch-depth: 0
- uses: actions/setup-python@v4
with:
python-version: 3.x
Expand All @@ -43,8 +46,8 @@ jobs:
pages-status-check:
if: github.event_name == 'pull_request'
needs:
- markdown-lint
- mkdocs-build
- lint
- build
runs-on: ubuntu-latest
steps:
- uses: re-actors/alls-green@release/v1
Expand Down
1 change: 1 addition & 0 deletions .markdownlintignore
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
docs/license.md
66 changes: 39 additions & 27 deletions docs/alternatives.md

Large diffs are not rendered by default.

10 changes: 5 additions & 5 deletions docs/commands.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,9 +18,9 @@ Files in the input directories will be left alone, they will _not_ be modified o

### `move`

Move ROMs from an input directory to the output directory. The same directory can be specified for both input & output, resulting in ROMs being renamed as their names change in [DATs](dats.md).
Move ROMs from an input directory to the output directory. The same directory can be specified for both input & output, resulting in ROMs being renamed as their names change in [DATs](input/dats.md).

ROMs will be deleted from their input directory after _all_ ROMs for _every_ [DAT](dats.md) have been written.
ROMs will be deleted from their input directory after _all_ ROMs for _every_ [DAT](input/dats.md) have been written.

### `symlink`

Expand All @@ -36,7 +36,7 @@ If no archive command is specified, files will be left as-is. If they are alread

!!! note

See the [archives page](archives.md) for more information on supported archive types.
See the [archives page](input/archives.md) for more information on supported archive types.

### `extract`

Expand All @@ -63,12 +63,12 @@ After performing one of the ROM writing commands, verify that the file was writt

### `clean`

Files in the output directory that do not match any ROM in any [DAT](dats.md) will be deleted.
Files in the output directory that do not match any ROM in any [DAT](input/dats.md) will be deleted.

## ROM reporting

### `report`

A report will be generated of what input files were matched by what DAT, and what games in what [DATs](dats.md) have missing ROMs.
A report will be generated of what input files were matched by what DAT, and what games in what [DATs](input/dats.md) have missing ROMs.

See the [reporting page](output/reporting.md) for more information.
2 changes: 1 addition & 1 deletion docs/archives.md → docs/input/archives.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@

`igir` only supports creating `.zip` archives, which is why the command is `igir zip`.

`.zip` archives store CRC32 information in the file table (see below) which helps drastically speed up file scanning, and they are easy to create without proprietary tools (e.g. Rar).
`.zip` archives store CRC32 information in their "file table" (see below) which helps drastically speed up `igir`'s file scanning, and they are easy to create without proprietary tools (e.g. Rar).

## Supported archive types for reading

Expand Down
14 changes: 8 additions & 6 deletions docs/dats.md → docs/input/dats.md
Original file line number Diff line number Diff line change
Expand Up @@ -79,12 +79,6 @@ Being able to know that many releases are actually the same game gives `igir` th

If you have the option to download "parent/clone" or "P/C" versions of DATs, you should always choose those.

## Aren't DATs primarily for MAME?

That's where DATs started. The [Logiqx XML](http://www.logiqx.com/DatFAQs/) DAT format can include information in [clrmamepro](https://mamedev.emulab.it/clrmamepro/) or [Romcenter](http://www.romcenter.com/) formats on how to handle MAME-specific settings such as [merging](https://docs.mamedev.org/usingmame/aboutromsets.html#parents-clones-splitting-and-merging) (non-merged vs. merged vs. split) and packing (zip vs. not). `igir` doesn't use any of this information, but it helps paint a picture of why DATs are structured the way they are.

These days, depending on what type of emulation you're interested in, non-MAME DATs such as No-Intro's may be more common than MAME DATs. See the [DAT groups](#dat-groups) section above for some of the popular DAT release groups.

## Fixdats

"Fixdats" are DATs that contain only ROMs that are missing from your collection. Fixdats are derived from some other DAT (see above for obtaining DATs), containing only a subset of the ROMs. Fixdats are specific to the state of each person's ROM collection, so they aren't necessarily meaningful to other people.
Expand Down Expand Up @@ -113,3 +107,11 @@ ROMs-Sorted/
├── Nintendo - Game Boy Advance (20230414-173400) fixdat.dat
└── Nintendo - Game Boy Color (20230414-173400) fixdat.dat
```

## FAQ

### Aren't DATs primarily for MAME?

That's where DATs started. The [Logiqx XML](http://www.logiqx.com/DatFAQs/) DAT format can include information in [clrmamepro](https://mamedev.emulab.it/clrmamepro/) or [Romcenter](http://www.romcenter.com/) formats on how to handle MAME-specific settings such as [merging](https://docs.mamedev.org/usingmame/aboutromsets.html#parents-clones-splitting-and-merging) (non-merged vs. merged vs. split) and packing (zip vs. not). `igir` doesn't use any of this information, but it helps paint a picture of why DATs are structured the way they are.

These days, depending on what type of emulation you're interested in, non-MAME DATs such as No-Intro's may be more common than MAME DATs. See the [DAT groups](#dat-groups) section above for some of the popular DAT release groups.
2 changes: 1 addition & 1 deletion docs/file-scanning.md → docs/input/file-scanning.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

- ROMs: `--input` (required), `--input-exclude`
- [DATs](dats.md): `--dat`, `--dat-exclude`
- [ROM patches](rom-patching.md): `--patch`, `--patch-exclude`
- [ROM patches](../rom-patching.md): `--patch`, `--patch-exclude`

## Archive files

Expand Down
6 changes: 4 additions & 2 deletions docs/installation.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
# Installation

A few different installation options are offered for `igir`.
`igir` is supported on :simple-windowsxp: Windows, :simple-apple: macOS, :simple-linux: Linux, and every other operating system that [Node.js](https://nodejs.org) supports.

There are a few different installation options offered for `igir` with varying levels of technical complexity. Every option will require some baseline understanding of command-line interfaces (CLIs).

## Via Node.js

Expand Down Expand Up @@ -49,6 +51,6 @@ docker run --interactive --tty \

!!! warning

Make sure to quote all of your [file globs](file-scanning.md)!
Make sure to quote all of your [file globs](input/file-scanning.md)!

[![asciicast](https://asciinema.org/a/5OAVbSXXoosTr0WyBvjQGBqRp.svg)](https://asciinema.org/a/5OAVbSXXoosTr0WyBvjQGBqRp)
27 changes: 15 additions & 12 deletions docs/internals.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,15 +6,18 @@ Information about the inner workings of `igir`.

`igir` runs these steps in the following order:

1. Scans each DAT input path for every file and parses them, if provided (`--dat`)
2. Scans each ROM input path for every file (`--input`)
- Then detects headers in those files, if applicable (see [header docs](rom-headers.md))
3. Scans each patch input path for every file (`--patch`) (see [patching docs](rom-patching.md))
4. ROMs are matched to the DATs, if provided
- Then ROMs are matched to any applicable patches, creating multiple versions from the same ROM
- Then filtering and sorting options are applied (see [filtering docs](rom-filtering.md))
- Then ROMs are written to the output directory, if specified (`copy`, `move`)
- Then written ROMs are tested for accuracy, if specified (`test`)
- Then input ROMs are deleted, if specified (`move`)
5. Unknown files are recycled from the output directory, if specified (`clean`)
6. An output report is written to the output directory, if specified (`report`)
1. Scan each DAT input path for every file and parse them, if provided (`--dat`)
2. Scan each ROM input path for every file (`--input`)
- Detect headers in those files, if applicable (see [header docs](rom-headers.md))
3. Scan each patch input path for every file (`--patch`) (see [patching docs](rom-patching.md))
4. Then for each DAT:
- ROMs in the DAT are filtered to only those desired (see [filtering & preference docs](rom-filtering.md))
- Input files are matched to ROMs in the DAT
- Patch files are matched to ROMs in the DAT
- ROM preferences are applied (`--single`, see [filtering & preference docs](rom-filtering.md))
- ROMs are written to the output directory, if specified (`copy`, `move`, `symlink`)
- Written ROMs are tested for accuracy, if specified (`test`)
- A "fixdat" is created, if specified (`--fixdat`)
5. "Moved" input ROMs are deleted (`move`)
6. Unknown files are recycled from the output directory, if specified (`clean`)
7. An output report is written to the output directory, if specified (`report`)
1 change: 1 addition & 0 deletions docs/license.md
18 changes: 10 additions & 8 deletions docs/output/reporting.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,30 +9,32 @@ When using DATs (the `--dat` option), the `igir report` command can report on:
- What input files didn't match to any ROM
- What output files were cleaned (`igir clean` command)

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.md) for more information about DATs.
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](../input/dats.md) for more information about DATs.

The `igir report` can be specified on its own without any [writing command](../commands.md) in order to report on an existing collection, e.g.:
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:

```shell
$ igir report --dat *.dat --input ROMs/

$ ls ROMs/*.csv
ROMs/igir_2023-03-29T18;26;00-04;00.csv
$ ls *.csv
igir_2023-03-29T18;26;00-04;00.csv
```

See the `igir --help` message for the report's default location.

## Format & filtering

The output report format is a standard CSV which can be opened in Microsoft Excel, Apple Numbers, Google Sheets, LibreOffice Calc, and similar spreadsheet applications.
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 tools, 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 "UNMATCHED" to understand what input files aren't recognized as a known ROM. The ability to filter CSVs in spreadsheet applications means that `igir` should not need use-case-specific 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 "UNMATCHED" to understand what input files aren't recognized as a known ROM. The ability to filter CSVs in spreadsheet applications means that `igir` should not 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."

## Output location

The `--report-output` options is provided to configure where the `igir report` report is written. See the `igir --help` message for the report's default location.
The `--report-output` options is provided to configure where the `igir report` CSV is written. See the `igir --help` message for the report's default location.

The report output filename supports a version of [Moment.js symbols](https://momentjs.com/docs/#/displaying/) for date and time. To make it clearer what is a replaceable symbol, `%` is prepended to symbols. This is _non-standard_ for Moment.js - but the `%` format should feel more familiar to more people as it resembles [Python's `date.strftime()`](https://docs.python.org/3/library/datetime.html#datetime.date.strftime), [PHP's `strftime()`](https://www.php.net/manual/en/function.strftime.php), [C++'s `strftime()`](https://cplusplus.com/reference/ctime/strftime/), and more.
The report output filename supports a version of [Moment.js symbols](https://momentjs.com/docs/#/displaying/) for date and time. To make it clearer what is a replaceable symbol, `%` is prepended to symbols. This is _non-standard_ for Moment.js, but the `%` format should feel more familiar to more people as it resembles [Python's `date.strftime()`](https://docs.python.org/3/library/datetime.html#datetime.date.strftime), [PHP's `strftime()`](https://www.php.net/manual/en/function.strftime.php), [C++'s `strftime()`](https://cplusplus.com/reference/ctime/strftime/), and more.

!!! info

Expand Down
12 changes: 9 additions & 3 deletions docs/output/tokens.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,13 @@ When specifying a ROM [writing command](../commands.md) you have to specify an `

For example, if you want to group all ROMs based on their region, you would specify:

=== "Windows"
=== ":simple-windowsxp: Windows"

```batch
igir.exe copy extract --dat *.dat --input ROMs/ --output "ROMs-Sorted/{datReleaseRegion}/"
```

=== "macOS"
=== ":simple-apple: macOS"

```shell
igir copy extract --dat *.dat --input ROMs/ --output "ROMs-Sorted/{datReleaseRegion}/"
Expand Down Expand Up @@ -39,13 +39,19 @@ ROMs-Sorted/

## DAT information

When using [DATs](../dats.md), you can make use of console & game information contained in them:
When using [DATs](../input/dats.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
- `{datReleaseLanguage}` each of the ROM's language(s) (e.g. `EN`, `ES`, `JA`)
- `{datReleaseRegion}` each of the ROM's region(s) (e.g. `USA`, `EUR`, `JPN`, `WORLD`)

## Game information

You can use some information about each game:

- `{gameType}` the game's "type," one of: `Aftermarket`, `Alpha`, `Bad`, `Beta`, `BIOS`, `Demo`, `Device`, `Fixed`, `Hacked`, `Homebrew`, `Overdump`, `Pending Dump`, `Pirated`, `Prototype`, `Retail` (most games will be this), `Sample`, `Test`, `Trained`, `Translated`, `Unlicensed`

## File information

You can use some information about the input and output file's name & location:
Expand Down
4 changes: 2 additions & 2 deletions docs/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -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](archives.md) and those with [headers](rom-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/archives.md) and those with [headers](rom-headers.md) so that you don't have to do much pre-work.

Most ROM managers rely on [DATs](dats.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](input/dats.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.

## What is `igir`?

Expand Down
2 changes: 2 additions & 0 deletions docs/rom-dumping.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,8 @@

Emulators are generally _legal_, as long as they don't include copyrighted software such as a console BIOS. Downloading ROM files that you do not own is piracy which is _illegal_ in many countries.

!!! info

[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.
Expand Down
Loading

0 comments on commit ed1224c

Please sign in to comment.