Rewrite RGBFIX

- Make it work inside pipelines
- Add RGBFIX tests to the suite
- Be more flexible in accepted MBC names
- Add warnings for dangerous or nonsensical input params
- Improve man page

src/fix/rgbfix.1

@@ -24,39 +24,48 @@
 .Op Fl p Ar pad_value
 .Op Fl r Ar ram_size
 .Op Fl t Ar title_str
-.Ar file
+.Op Ar
 .Sh DESCRIPTION
 The
 .Nm
-program changes headers of Game Boy ROM images.
+program changes headers of Game Boy ROM images, typically generated by
+.Xr rgblink 1 ,
+though it will work with
+.Em any
+Game Boy ROM.
 It also performs other correctness operations, such as padding.
+.Nm
+only changes the fields for which it has values specified.
+Developers are advised to fill those fields with 0x00 bytes in their source code before running
+.Nm ,
+and to have already populated whichever fields they don't specify using
+.Nm .
 .Pp
 Note that options can be abbreviated as long as the abbreviation is unambiguous:
-.Fl Fl verb
+.Fl Fl color-o
 is
-.Fl Fl verbose ,
+.Fl Fl color-only ,
 but
-.Fl Fl ver
+.Fl Fl color
 is invalid because it could also be
-.Fl Fl version .
-The arguments are as follows:
+.Fl Fl color-compatible .
+Options later in the command line override those set earlier.
+Accepted options are as follows:
 .Bl -tag -width Ds
 .It Fl C , Fl Fl color-only
-Set the Game Boy Color\(enonly flag:
-.Ad 0x143
-= 0xC0.
-If both this and the
+Set the Game Boy Color\(enonly flag
+.Pq Ad 0x143
+to 0xC0.
+This overrides
 .Fl c
-flag are set, this takes precedence.
+if it was set prior.
 .It Fl c , Fl Fl color-compatible
 Set the Game Boy Color\(encompatible flag:
-.Ad 0x143
-= 0x80.
-If both this and the
-.Fl C
-flag are set,
-.Fl C
-takes precedence.
+.Pq Ad 0x143
+to 0x80.
+This overrides
+.Fl c
+if it was set prior.
 .It Fl f Ar fix_spec , Fl Fl fix-spec Ar fix_spec
 Fix certain header values that the Game Boy checks for correctness.
 Alternatively, intentionally trash these values by writing their binary inverse instead.
@@ -83,55 +92,63 @@ Trash the global checksum.
 .It Fl i Ar game_id , Fl Fl game-id Ar game_id
 Set the game ID string
 .Pq Ad 0x13F Ns \(en Ns Ad 0x142
-to a given string of exactly 4 characters.
-If both this and the title are set, the game ID will overwrite the overlapping portion of the title.
+to a given string.
+If it's longer than 4 chars, it will be truncated, and a warning emitted.
 .It Fl j , Fl Fl non-japanese
-Set the non-Japanese region flag:
-.Ad 0x14A
-= 1.
+Set the non-Japanese region flag
+.Pq Ad 0x14A
+to 0x01.
 .It Fl k Ar licensee_str , Fl Fl new-licensee Ar licensee_str
 Set the new licensee string
 .Pq Ad 0x144 Ns \(en Ns Ad 0x145
-to a given string, truncated to at most two characters.
+to a given string.
+If it's longer than 2 chars, it will be truncated, and a warning emitted.
 .It Fl l Ar licensee_id , Fl Fl old-licensee Ar licensee_id
-Set the old licensee code,
-.Ad 0x14B ,
+Set the old licensee code
+.Pq Ad 0x14B
 to a given value from 0 to 0xFF.
 This value is deprecated and should be set to 0x33 in all new software.
 .It Fl m Ar mbc_type , Fl Fl mbc-type Ar mbc_type
-Set the MBC type,
-.Ad 0x147 ,
+Set the MBC type
+.Pq Ad 0x147
 to a given value from 0 to 0xFF.
 This value may also be an MBC name from the Pan Docs.
 .It Fl n Ar rom_version , Fl Fl rom-version Ar rom_version
-Set the ROM version,
-.Ad 0x14C ,
+Set the ROM version
+.Pq Ad 0x14C
 to a given value from 0 to 0xFF.
 .It Fl p Ar pad_value , Fl Fl pad-value Ar pad_value
-Pad the image to a valid size with a given pad value from 0 to 0xFF.
+Pad the ROM image to a valid size with a given pad value from 0 to 255 (0xFF).
 .Nm
 will automatically pick a size from 32 KiB, 64 KiB, 128 KiB, ..., 8192 KiB.
 The cartridge size byte
 .Pq Ad 0x148
 will be changed to reflect this new size.
+The recommended padding value is 0xFF, to speed up writing the ROM to flash chips, and to avoid "nop slides" into VRAM.
 .It Fl r Ar ram_size , Fl Fl ram-size Ar ram_size
-Set the RAM size,
-.Ad 0x149 ,
+Set the RAM size
+.Pq Ad 0x149
 to a given value from 0 to 0xFF.
 .It Fl s , Fl Fl sgb-compatible
-Set the SGB flag:
-.Ad 0x146
-= 3. This flag will be ignored by the SGB unless the old licensee code is 0x33!
+Set the SGB flag
+.Pq Ad 0x146
+to 0x03.
+This flag will be ignored by the SGB unless the old licensee code is 0x33!
+If this is given as well as
+.Fl l ,
+but is not set to 0x33, a warning will be printed.
 .It Fl t Ar title , Fl Fl title Ar title
 Set the title string
 .Pq Ad 0x134 Ns \(en Ns Ad 0x143
-to a given string, truncated to at most 16 characters.
-It is recommended to use 15 characters instead, to avoid clashing with the CGB flag
-.Po Fl c
+to a given string.
+If the title is longer than the max length, it will be truncated, and a warning emitted.
+The max length is 11 characters if the game ID
+.Pq Fl i
+is specified, 15 characters if the CGB flag
+.Fl ( c
 or
-.Fl C
-.Pc .
-If both this and the game ID are set, the game ID will overwrite the overlapping portion of the title.
+.Fl C )
+is specified but the game ID is not, and 16 characters otherwise.
 .It Fl V , Fl Fl version
 Print the version of the program and exit.
 .It Fl v , Fl Fl validate
@@ -139,7 +156,7 @@ Equivalent to
 .Fl f Cm lhg .
 .El
 .Sh EXAMPLES
-Most values in the ROM header are only cosmetic.
+Most values in the ROM header do not matter to the actual console, and most are seldom useful anyway.
 The bare minimum requirements for a workable program are the header checksum, the Nintendo logo, and (if needed) the CGB/SGB flags.
 It is a good idea to pad the image to a valid size as well
 .Pq Do valid Dc meaning a power of 2, times 32 KiB .
@@ -152,14 +169,13 @@ a valid size:
 The following will make a SGB-enabled, color-enabled game with a title of
 .Dq foobar ,
 and pad it to a valid size.
-.Po
-The Game Boy itself does not use the title, but some emulators or ROM managers do.
-.Pc
+.Pq The Game Boy itself does not use the title, but some emulators or ROM managers do.
 .Pp
 .D1 $ rgbfix -vcs -l 0x33 -p 255 -t foobar baz.gb
 .Pp
-The following will duplicate the header (sans global checksum) of the game
-.Dq Survival Kids :
+The following will duplicate the header of the game
+.Dq Survival Kids ,
+sans global checksum:
 .Pp
 .D1 $ rgbfix -cjsv -k A4 -l 0x33 -m 0x1B -p 0xFF -r 3 -t SURVIVALKIDAVKE \
 SurvivalKids.gbc