[WIP] Switch to new "bit explanation" format

CONTRIBUTING.md

@@ -35,7 +35,6 @@ In any case, maintainers will chime in, reviewing what you changed and if necess
 
 ## Document Style
 
-
 ### 1. Pseudocode
 
 - Assignment: :=
@@ -71,7 +70,6 @@ References:
 Discussion:
 - [#76](https://github.com/gbdev/pandocs/issues/76), [#55](https://github.com/gbdev/pandocs/issues/55)
 
-
 ### 3. 8 bits / 8-bit
 
 - "8 bits" and "8-bit" have different usages in the English language. The former is used when talking about the quantity ("a byte has 8 bits"), while the latter is used as an adjective ("8-bit bytes are nowadays standard"). "8bit" is obviously wrong, and "8 bit" is likewise incorrect.
@@ -139,6 +137,45 @@ 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

preproc/Cargo.toml

@@ -7,10 +7,13 @@ edition = "2018"
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]
+anyhow = "1.0.42"
 clap = "2.33.3"
+lazy_static = "1.4.0"
 # mdbook here is only used as a lib, so no need for the extra features
 mdbook = { version = "0.4.8", default-features = false }
 pulldown-cmark = "0.8.0"
 pulldown-cmark-to-cmark = "6.0.1"
-termcolor = "1.1.2"
+regex = "1.5.4"
 serde_json = "1.0.59"
+termcolor = "1.1.2"

preproc/src/main.rs

@@ -62,7 +62,7 @@ fn handle_preprocessing(pre: &dyn Preprocessor) -> Result<(), Error> {
 
 fn handle_supports(pre: &dyn Preprocessor, sub_args: &ArgMatches) -> ! {
     let renderer = sub_args.value_of("renderer").expect("Required argument");
-    let supported = pre.supports_renderer(&renderer);
+    let supported = pre.supports_renderer(renderer);
 
     // Signal whether the renderer is supported by exiting with 1 or 0.
     if supported {