Move "bit explanation" table syntax to DEPLOY.md

CONTRIBUTING.md

@@ -137,45 +137,6 @@ For example, `[sample link text](<#014B — Old licensee code>)` will automatica
 References to missing sections will be left as-is, and ambiguous references resolved arbitrarily (this should eventually change).
 (Note that the use of angle brackets `<>` here is [a CommonMark feature](https://spec.commonmark.org/0.30/#link-destination) to allow spaces in the link destination.)
 
-### 9. Bit breakdown tables
-
-Quite often, a single byte's various bits encode different information.
-(For example, the "attributes" byte in OAM, all APU registers, and so on.)
-To describe those cases, we use a mix of custom syntax and a list:
-
-```markdown
-{{#bits 8
-  "Attributes"  7:"Priority" 6:"Y flip" 5:"X flip" 4:"DMG palette" 3:"Bank" 2-0:"CGB palette";
-}}
-
-- **Priority**: `0` = No, `1` = BG and Window colors 1-3 over this OBJ
-- **Y flip**: `0` = Normal, `1` = Entire OBJ is vertically mirrored
-- **X flip**: `0` = Normal, `1` = Entire OBJ is horizontally mirrored
-- **DMG palette** *\[Non CGB Mode only\]*: `0` = OBP0, `1` = OBP1
-- **Bank** *\[CGB Mode Only\]*: `0` = Fetch tile in VRAM bank 0, `1` = Fetch tile in VRAM bank 1
-- **CGB palette** *\[CGB Mode Only\]*: Use OBP0-7
-```
-
-- The `{{#bits}}` tag can span several lines for readability, and must contain first its "width", i.e. how many bits (columns) there should be; then a list of rows, separated by semicolons `;` (a trailing one is allowed).
-
-  Each row begins by its name, which must be surrounded by double quotes (to allow whitespace in it).
-Then, there's a list of *fields*, separated by whitespace: first its bit range (where e.g. `3` is equivalent to `3-3`), then its name, also surrounded by double quotes.
-
-  Field names should be succinct, otherwise the table may overflow, particularly on phones.
-
-  (Note: the tag can be escaped by putting a backslash in front of the first brace: `\{{#bits ...}}`; this makes the tag not be processed.)
-
-- The list must document all of the fields with a name.
-  Each entry must first contain the name, then any "usage notes" (typically availability, or "ignored if ..." notes) between brackets `[]`, then the read/writability between parentheses.
-  Then a colon, and a description of the field.
-
-  Regarding the formatting:
-  - The name must be in **bold**, since it's really important information.
-  - Anything before the initial colon, except for the name, must be in *italics*.
-  - Any values for the field should be put in `monospace/code blocks`; this ensures they stand out.
-  - The usage notes can be omitted if there are none.
-  - For the sake of readability, if the read/writability of all fields is the same, then it must omitted in the list, but indicated e.g. in the section name, or in main text.
-
 ## SVG 
 
 ### Rationale

DEPLOY.md

@@ -130,33 +130,50 @@ Note that the angle brackets [are only required if there are spaces in the URL](
 
 In effect, this means that linking to a section is as simple as copy-pasting its name in the URL field, prepending a `#`, and wrapping everything in `<>` if the name contains a space.
 
-### Bit descriptions
+### Bit breakdown tables
+
+Quite often, a single byte's various bits, or various bytes in a collection, encode different information.
+(For example, the "attributes" byte in OAM, all APU registers, and so on.)
+To describe those cases, we use a mix of custom syntax and a list:
 
 ```markdown
-{{#bits 8 > SB 7-0:"Serial data"; SC 7:"Transfer start" 1:"Clock speed" 0:"Clock source"}}
+{{#bits 8
+  "Attributes"  7:"Priority" 6:"Y flip" 5:"X flip" 4:"DMG palette" 3:"Bank" 2-0:"CGB palette";
+}}
+
+- **Priority**: `0` = No, `1` = BG and Window colors 1-3 over this OBJ
+- **Y flip**: `0` = Normal, `1` = Entire OBJ is vertically mirrored
+- **X flip**: `0` = Normal, `1` = Entire OBJ is horizontally mirrored
+- **DMG palette** *\[Non CGB Mode only\]*: `0` = OBP0, `1` = OBP1
+- **Bank** *\[CGB Mode Only\]*: `0` = Fetch tile in VRAM bank 0, `1` = Fetch tile in VRAM bank 1
+- **CGB palette** *\[CGB Mode Only\]*: Use OBP0-7
 ```
 
-Pan Docs describes a lot of hardware registers, and [it has been agreed upon that tables are the best format for this](https://github.com/gbdev/pandocs/issues/318).
-However, the best formatting requires `colspan`, which requires HTML tables, which are quite tedious to write; hence, a shorthand syntax was developed.
-This is typically used for bit descriptions (hence the name), but is generic enough to work e.g. for byte descriptions as well.
+- The `{{#bits}}` tag can span several lines for readability.
+  It must begin with its "width", i.e. how many bits (columns) there should be, and "direction", i.e. whether columns should be in ascending `<` or descending `>` order.
+  Then is a list of *rows*, separated by semicolons `;` (a trailing one is allowed).
+
+  Each row begins by its name, which must be surrounded by double quotes (to allow whitespace in it).
+  If the name is empty, then all rows' names must be empty; this will remove the "heading" column entirely.
 
-The first argument is the number of columns (not counting the title one).
+  Then, there's a list of *fields*, separated by whitespace: first its bit range (where e.g. `3` is equivalent to `3-3`), then its name, also surrounded by double quotes.
 
-The second argument is the direction of the indices: `<` for increasing, `>` for decreasing.
-Decreasing is preferred for bit descriptions, and increasing for byte descriptions.
+  Field names should be succinct, otherwise the table may overflow, particularly on phones.
 
-The following arguments can be repeated for as many rows as desired, separated by semicolons `;`:
-- One argument (which may not start with a digit) names the row; if exactly "\_", it will be ignored.
-- Any amount of arguments (even zero) name the individual fields, which must be ordered as in the example. Fields may span several bits, as shown above.
+  (Note: the tag can be escaped by putting a backslash in front of the first brace: `\{{#bits ...}}`; this makes the tag not be processed.)
 
-Note: these are usually followed by more detailed descriptions of the fields.
-The format of those is documented [in the style guide](https://github.com/gbdev/pandocs/wiki/Document-Style#ANCHOR_FOR_ADDITION_BELOW).
+- The list must document all of the fields with a name.
+  Each entry must first contain the name, then any "usage notes" (typically availability, or "ignored if ..." notes) between brackets `[]`, then the read/writability between parentheses.
+  Then a colon, and a description of the field.
 
-\[THIS WILL NOT BE ADDED TO THE PR, BUT TO THE STYLE GUIDE ON THE WIKI. IT'S MERELY HERE FOR REVIEW.\]
+  Regarding the formatting:
+  - The name must be in **bold**, since it's really important information.
+  - Anything before the initial colon, except for the name, must be in *italics*.
+  - Any values for the field should be put in `monospace/code blocks`; this ensures they stand out.
+  - The usage notes can be omitted if there are none.
+  - For the sake of readability, if the read/writability of all fields is the same, then it must omitted in the list, but indicated e.g. in the section name, or in main text.
 
-The format of bit description lists is as follows: `- **Field name** [*Additional notes*] (*Read/Write*): Description`.
-Additional notes are, for example, to note CGB exclusivity; they are not required.
-The "Read/Write" part may be omitted if all fields within the byte are readable and writable; otherwise, it must be indicated for all fields, and both words must be fully spelled out, or spelled exactly "Read-only"/"Write-only".
+Tables [were agreed upon](https://github.com/gbdev/pandocs/issues/318) as the best way to represent this, but Markdown does not support `colspan`, so a shorthand syntax was developed.
 
 ## Syntax highlighting
 

src/Audio_Registers.md

@@ -89,7 +89,7 @@ Bit 2-0 - Right output volume       (0-7)
 This register controls CH1's period sweep functionality.
 
 {{#bits 8 >
-  "NR10" 6-4:"Pace" 3:"Direction" 2-0:"Individual step";
+  "NR10"  6-4:"Pace" 3:"Direction" 2-0:"Individual step";
 }}
 
 - **Pace**: This dictates how often sweep "iterations" happen, in units of 128 Hz ticks[^div_apu] (7.8 ms).

src/LCDC.md

@@ -6,8 +6,8 @@
 elements are displayed on the screen, and how.
 
 {{#bits 8 >
-  "" 7:"LCD & PPU enable" 6:"Window tile map" 5:"Window enable" 4:"BG & Window tiles"
-     3:"BG tile map" 2:"OBJ size" 1:"OBJ enable" 0:"BG & Window enable / priority";
+  ""  7:"LCD & PPU enable" 6:"Window tile map" 5:"Window enable" 4:"BG & Window tiles"
+      3:"BG tile map" 2:"OBJ size" 1:"OBJ enable" 0:"BG & Window enable / priority";
 }}
 
 - **[LCD & PPU enable](<#LCDC.7 — LCD enable>)**: `0` = Off; `1` = On

src/Palettes.md

@@ -8,7 +8,7 @@
 This register assigns gray shades to the [color IDs](./Tile_Data.md) of the BG and Window tiles.
 
 {{#bits 8 >
-  "Color for..." 7-6:"ID 3" 5-4:"ID 2" 3-2:"ID 1" 1-0:"ID 0";
+  "Color for..."  7-6:"ID 3" 5-4:"ID 2" 3-2:"ID 1" 1-0:"ID 0";
 }}
 
 Each of the two-bit values map to a color thusly:
@@ -45,7 +45,7 @@ BGP1 color number 0, and so on. Thus, address $03 allows accessing the second (u
 byte of BGP0 color #1 via BCPD, which contains the color's blue and upper green bits.
 
 {{#bits 8 >
-  "BCPS / OCPS" 7:"Auto-increment" 5-0:"Address";
+  "BCPS / OCPS"  7:"Auto-increment" 5-0:"Address";
 }}
 
 - **Auto-increment**: `0` = Disabled; `1` = Increment "Address" field after **writing** to
@@ -63,7 +63,7 @@ This register allows to read/write data to the CGBs background palette memory, a
 Each color is stored as little-endian RGB555:
 
 {{#bits 16 <
-  "One color" 0-4:"Red intensity" 5-9:"Green intensity" 10-14:"Blue intensity";
+  "One color"  0-4:"Red intensity" 5-9:"Green intensity" 10-14:"Blue intensity";
 }}
 
 Much like VRAM, data in palette memory cannot be read or written during the time

src/STAT.md

@@ -21,7 +21,7 @@ is set, and (if enabled) a STAT interrupt is requested.
 ## FF41 — STAT: LCD status
 
 {{#bits 8 >
-  "" 6:"LYC int select" 5:"Mode 2 int select" 4:"Mode 1 int select" 3:"Mode 0 int select" 2:"LYC == LY" 1-0:"PPU mode";
+  ""  6:"LYC int select" 5:"Mode 2 int select" 4:"Mode 1 int select" 3:"Mode 0 int select" 2:"LYC == LY" 1-0:"PPU mode";
 }}
 
 - **LYC int select** (*Read/Write*): If set, selects the `LYC` == `LY` condition for [the STAT interrupt](<#INT $48 — STAT interrupt>).

src/Tile_Maps.md

@@ -24,7 +24,9 @@ In CGB Mode, an additional map of 32×32 bytes is stored in VRAM Bank 1
 entry in VRAM Bank 0, that is, 1:9800 defines the attributes for the tile at
 0:9800):
 
-{{#bits 8 > "BG attributes" 7:"Priority" 6:"Y flip" 5:"X flip" 3:"Bank" 2-0:"Color palette"}}
+{{#bits 8 > 
+  "BG attributes"  7:"Priority" 6:"Y flip" 5:"X flip" 3:"Bank" 2-0:"Color palette";
+}}
 
 - **Priority**: `0` = No; `1` = Colors 1–3 of the corresponding BG/Window tile are drawn over OBJ, regardless of [OBJ priority](<#Byte 3 — Attributes/Flags>)
 - **Y flip**: `0` = Normal; `1` = Tile is drawn vertically mirrored