doc: clean up Descriptors section

README.md

@@ -127,10 +127,10 @@ not the contents of the corresponding NVRAM file.
 The map file contains objects describing sections of the `.nv` file and
 how to interpret them.  They're comprised of the following key/value pairs:
 
-- **label**: A label describing this collection of bytes in the `.nv` file. 
-- **short_label**: An optional, abbreviated label for use when space is
-  limited (like in a game launcher on a DMD). 
-- **encoding** _(required)_:  One of the following:
+- **_note**: A note for someone maintaining the file; not displayed when
+  processing an NVRAM file.
+
+- **encoding** _(required)_ must be one of the following:
   - `"enum"`: An enumerated type where the byte at `start` is used as an
     index into a list of strings provided in `values`.
   - `"int"`: A (possibly) multibyte integer, where each byte is multiplied
@@ -152,6 +152,7 @@ how to interpret them.  They're comprised of the following key/value pairs:
     from a WPC game, stored as a sequence of 7 bytes.  Starts with a
     two-byte year (2015 is `0x07 0xDF`), month (1-12), day of month (1-31),
     day of the week (0-6, 0=Sunday), hour (0-23) and minute (0-59).
+
 - You must specify the location of data in the file using one or more of the
   following directives:
   - **start**: Offset into the `.nv` file of the first byte to
@@ -163,55 +164,67 @@ how to interpret them.  They're comprised of the following key/value pairs:
   - **offsets**: Alternative to using start/end or start/length when bytes
     aren't contiguous.  List of offsets to use.  Either `start` or `offsets`
     are required.
-- **null**: Used for `"ch"` encodings to specify null (0x00) byte handling.
-    For `truncate` and `terminate`, ignore all bytes after the null.
-  - `"ignore"`: Ignore (skip over) null bytes.
-  - `"truncate"`: A null can shorten the string, but won't be present for
-    strings that fill the allotted space.
-  - `"terminate"`: Null bytes are always present and terminate the string.
-- **min** and **max**: Used for adjustments to specify the valid range of
-  values.
-- **default**: Used for adjustments to specify the factory default value.
-  Used for the **initials** entry of a high score to indicate the value
-  for an empty entry (e.g., `"   "` on WPC, `"\u0000\u0000\u0000"` on
-  Gottlieb System 80).  Defaults to `0` unless specified.
-- **values**: A list of strings used for the `enum` encoding, starting at index 0.
-  Also used for the `bits` encoding, as values for bit 0, 1, 2, etc.
-- **special_values**: A set of key/value pairs for numeric field where some
-  values have special meaning (for example, `{"0": "OFF"}`).
-- **units**: Used to indicate that a field contains a time value as either a
-  number of `"seconds"` or `"minutes"`, and should be displayed as `HH:MM:SS`.
-- **suffix**: A string to append to the value (e.g., `"M"` if the value
-  represents millions).
-- **scale**: A numeric multiplier for a decoded `int`, `bcd`, or `bits`.
-- **offset**: A numeric value to add to a decided `int`, `bcd`, or `bits`
-  value before displaying it.  Applied after `scale`.
-- **mask**: A mask to apply to each byte before processing.  For example, a
-  mask of `"0x5F"` converts lowercase initials to uppercase and a mask of
-  `"0x0F"` clears the upper four bits.
-- **nibble**: Replacement for `packed` attribute for `ch` and `bcd` types.
-  Defaults to `both` (previously `packed=true`) indicating use of the full
-  8 bits/byte.  Set to `low` (previously `packed=false`) to use the lower
-  4 bits of the byte or `high` to use the upper 4 bits of the byte. 
-  The `bcd` sequence `0x12 0x34 0x56` translates to `123456` when `nibble` is
-  `both`, `246` when `nibble` is `low` and `135` when `nibble` is `high`.
-  Robowars has an example of a `nibble=low` `ch` field, where the sequence
-  `0x04 0x01 0x04 0x02 0x04 0x03` translates to `0x41 0x42 0x43` which is the
-  string `"ABC"`.
-  Stern Dracula and Wild Fyre (identical ROM) have examples of `nibble=high`.
-- **packed**: Deprecated in favor of `nibble`.  Remove `packed=true` and
-  replace `packed=false` with `nibble=low`.  
-- **_note**: A note for someone maintaining the file; not displayed when
-  processing an NVRAM file.
+
+- These properties provide additional encoding details.
+  - **endian**: Set to either `"big"` or `"little"` to indicate the byte
+    order of multi-byte values.  Defaults to the `_endian` setting for the
+    file (which defaults to `"big"`).
+  - **nibble**: Replacement for `packed` attribute for `ch` and `bcd` types.
+    Defaults to `both` (previously `packed=true`) indicating use of the full
+    8 bits/byte.  Set to `low` (previously `packed=false`) to use the lower
+    4 bits of the byte or `high` to use the upper 4 bits of the byte. 
+    The `bcd` sequence `0x12 0x34 0x56` translates to `123456` when `nibble` is
+    `both`, `246` when `nibble` is `low` and `135` when `nibble` is `high`.
+    Robowars has an example of a `nibble=low` `ch` field, where the sequence
+    `0x04 0x01 0x04 0x02 0x04 0x03` translates to `0x41 0x42 0x43` which is the
+    string `"ABC"`.
+    Stern Dracula and Wild Fyre (identical ROM) have examples of `nibble=high`.
+  - **null**: Used for `"ch"` encodings to specify null (0x00) byte handling.
+      For `truncate` and `terminate`, ignore all bytes after the null.
+    - `"ignore"`: Ignore (skip over) null bytes.  Default setting.
+    - `"truncate"`: A null can shorten the string, but won't be present for
+      strings that fill the allotted space.
+    - `"terminate"`: Null bytes are always present and terminate the string.
+  - **packed**: Deprecated in favor of `nibble`.  Remove `packed=true` and
+    replace `packed=false` with `nibble=low`.
+
+- These properties are only related to displaying the value, independently of
+  how it's actually stored in memory or a `.nv` file.
+  - **label**: A label describing this collection of bytes in the `.nv` file. 
+  - **short_label**: An optional, abbreviated label for use when space is
+    limited (like in a game launcher on a DMD). 
+  - **values**: A list of strings used for the `enum` encoding, starting at index 0.
+    Also used for the `bits` encoding, as values for bit 0, 1, 2, etc.
+  - **special_values**: A set of key/value pairs for a numeric field where some
+    values have special meaning (for example, `{"0": "OFF"}`).
+  - **units**: Used to indicate that a field contains a time value as either a
+    number of `"seconds"` or `"minutes"`, and should be displayed as `HH:MM:SS`.
+  - **suffix**: A string to append to the value (e.g., `"M"` if the value
+    represents millions).
+  - **scale**: A numeric multiplier for a decoded `int`, `bcd`, or `bits`.
+  - **offset**: A numeric value to add to a decoded `int`, `bcd`, or `bits`
+    value before displaying it.  Applied after `scale`.
+  - **mask**: A mask to apply to each byte before processing.  For example, a
+    mask of `"0x5F"` converts lowercase initials to uppercase and a mask of
+    `"0x0F"` clears the upper four bits.
+
+- Encodings can include properties that describe limitations imposed on
+  adjustments in the service menu, or just ranges that the ROM considers
+  invalid.  These all pertain to the stored value, exclusive of any `scale`
+  or `offset`.
+  - **default**: The factory default value.
+    Used for the **initials** entry of a high score to indicate the value
+    for an unused entry (e.g., `"   "` on WPC, `"\u0000\u0000\u0000"` on
+    Gottlieb System 80).  Defaults to `0` unless specified.
+  - **min** and **max**: The valid range of values.
+  - **multiple_of**: Enforce a subset of values between `min` and `max`.
+    Defaults to `1` (all values allowed) unless specified.
 
 ### File Map
 
 Keys that don't start with an underscore typically have groups of
 **descriptors** as their values.
 
-- **endian**: Set to either `"big"` or `"little"` to indicate the byte
-  order of multi-byte values in the ROM file.  Defaults to the `_endian`
-  setting for the file (which defaults to `"big"`).
 - **last_played**: A descriptor (likely with a `wpc_rtc` encoding) with a
   date stamp of when PinMAME last saved the file.
 - **last_game**: An array of up to four descriptors representing scores