Re-write bit ranges in the docs
diff --git a/doc/note/base38-and-fourcc.md b/doc/note/base38-and-fourcc.md
index dc3c83f..dc51351 100644
--- a/doc/note/base38-and-fourcc.md
+++ b/doc/note/base38-and-fourcc.md
@@ -33,7 +33,7 @@
instead of 32 bits. This is achieved by using a smaller alphabet of 38 possible
values (space, 0-9, ? or a-z), so that it cannot distinguish between e.g. an
upper case 'X' and a lower case 'x'. There's also the happy coincidence that
-`38 ** 4` is slightly smaller than `2 ** 21`.
+`38 ** 4`, `2085136`, is slightly smaller than `2 ** 21`, `2097152`.
The base38 encoding of `"JPEG"` is `0x122FF6`, which is `1191926`, which is
`((21 * (38 ** 3)) + (27 * (38 ** 2)) + (16 * (38 ** 1)) + (18 * (38 ** 0)))`.
@@ -45,9 +45,9 @@
packages (assuming that there aren't e.g. two `"JPEG"` Wuffs packages in the
same library). The conventional `uint32_t` packing is:
-- Bit 31 is reserved (zero).
-- Bits 30 .. 10 are the base38 value, shifted by 10.
-- Bits 9 .. 0 are the enumeration value.
+- Bit `31` (1 bit) is reserved (zero).
+- Bits `10 ..= 30` (21 bits) are the base38 value, shifted by 10.
+- Bits `0 ..= 9` (10 bits) are the enumeration value.
For example, [quirk values](/doc/note/quirks.md) use this `((base38 << 10) |
enumeration)` scheme.
diff --git a/doc/note/pixel-formats.md b/doc/note/pixel-formats.md
index bc6f26a..9eca00e 100644
--- a/doc/note/pixel-formats.md
+++ b/doc/note/pixel-formats.md
@@ -3,27 +3,27 @@
`wuffs_base__pixel_format` is a `uint32_t` that encodes the format of the bytes
that constitute an image frame's pixel data. Its bits:
-- bit 31 is reserved.
-- bits 30 .. 28 encodes color (and channel order, in terms of memory).
-- bit 27 is reserved.
-- bits 26 .. 24 encodes transparency.
-- bits 23 .. 21 are reserved.
-- bit 20 indicates big-endian/MSB-first (as opposed to little/LSB).
-- bit 19 indicates floating point (as opposed to integer).
-- bit 18 indicates palette-indexed. The number-of-planes (the next
- field) will be 0, as the format is considered interleaved,
- but the 8-bit N-BGRA color data is stored in plane 3.
-- bits 17 .. 16 are the number of planes, minus 1. Zero means interleaved.
-- bits 15 .. 12 encodes the number of bits (depth) in the 3rd channel.
-- bits 11 .. 8 encodes the number of bits (depth) in the 2nd channel.
-- bits 7 .. 4 encodes the number of bits (depth) in the 1st channel.
-- bits 3 .. 0 encodes the number of bits (depth) in the 0th channel.
+- Bit `31` is reserved.
+- Bits `28 ..= 30` encodes color (and channel order, in terms of memory).
+- Bit `27` is reserved.
+- Bits `24 ..= 26` encodes transparency.
+- Bits `21 ..= 23` are reserved.
+- Bit `20` indicates big-endian/MSB-first (instead of little/LSB).
+- Bit `19` indicates floating point (instead of integer).
+- Bit `18` indicates palette-indexed. The number-of-planes (the next
+ field) will be 0, as the format is considered interleaved,
+ but the 8-bit N-BGRA color data is stored in plane 3.
+- Bits `16 ..= 17` are the number of planes, minus 1. Zero means interleaved.
+- Bits `12 ..= 15` encodes the number of bits (depth) in the 3rd channel.
+- Bits `8 ..= 11` encodes the number of bits (depth) in the 2nd channel.
+- Bits `4 ..= 7` encodes the number of bits (depth) in the 1st channel.
+- Bits `0 ..= 3` encodes the number of bits (depth) in the 0th channel.
The bit fields of a `wuffs_base__pixel_format` are not independent. For
example, the number of planes should not be greater than the number of
-channels. Similarly, bits 15..4 are unused (and should be zero) if bits 31..24
-(color and transparency) together imply only 1 channel (gray, no alpha) and
-floating point samples should mean a bit depth of 16, 32 or 64.
+channels. Similarly, bits `4 ..= 15` are unused (and should be zero) if bits
+`24 ..= 31` (color and transparency) together imply only 1 channel (gray, no
+alpha) and floating point samples should mean a bit depth of 16, 32 or 64.
Formats hold between 1 and 4 channels. For example: Y (1 channel: gray), YA (2
channels: gray and alpha), BGR (3 channels: blue, green, red) or CMYK (4
@@ -77,7 +77,7 @@
Bit depth is encoded in 4 bits:
- 0 means the channel or index is unused.
-- x means a bit depth of x, for x in the range 1..8.
+- x means a bit depth of x, for x in the range `1 ..= 8`.
- 9 means a bit depth of 10.
- 10 means a bit depth of 12.
- 11 means a bit depth of 16.
diff --git a/doc/note/tokens.md b/doc/note/tokens.md
index 5577f2d..5e26d27 100644
--- a/doc/note/tokens.md
+++ b/doc/note/tokens.md
@@ -36,9 +36,9 @@
A token is just a `uint64_t`. The broad divisions are:
-- Bits 63 .. 17 (47 bits) is the value.
-- Bits 16 .. 16 (1 bit) is the `continued` bit.
-- Bits 15 .. 0 (16 bits) is the length.
+- Bits `17 ..= 63` (47 bits) are the value.
+- Bit `16` (1 bit) is the `continued` bit.
+- Bits `0 ..= 15` (16 bits) are the length.
The `continued` bit is whether that the token chain for this token also
contains the next token. The final token in a token chain, including
@@ -56,12 +56,12 @@
The value bits can be sub-divided in multiple ways. First, the high bit:
-- Bits 63 .. 63 (1 bit) denote an extended (1) or simple (0) token.
+- Bit `63` (1 bit) denotes an extended (1) or simple (0) token.
### Extended Tokens
-- Bits 62 .. 17 (46 bits) is the bitwise-not (~) of the `value_extension`.
+- Bits `17 ..= 62` (46 bits) are the bitwise-not (~) of the `value_extension`.
Extended tokens are typically part of a multi-token chain whose first token is
a simple token that provides the semantics for each `value_extension`.
@@ -69,8 +69,8 @@
### Simple Tokens
-- Bits 62 .. 42 (21 bits) is the `value_major`.
-- Bits 41 .. 17 (25 bits) is the `value_minor`.
+- Bits `42 ..= 62` (21 bits) are the `value_major`.
+- Bits `17 ..= 41` (25 bits) are the `value_minor`.
The `value_major` is a 21-bit [Base38](doc/note/base38-and-fourcc.md) number.
For example, an HTML tokenizer might produce a combination of "base" tokens
@@ -87,8 +87,8 @@
A zero `value_major` is reserved for Wuffs' built-in "base" package. The
`value_minor` is further sub-divided:
-- Bits 41 .. 38 (4 bits) is the `VBC` (`value_base_category`).
-- Bits 37 .. 17 (21 bits) is the `VBD` (`value_base_detail`).
+- Bits `38 ..= 41` (4 bits) are the `VBC` (`value_base_category`).
+- Bits `17 ..= 37` (21 bits) are the `VBD` (`value_base_detail`).
The high 47 bits (bits 63 .. 17) only have `VBC` and `VBD` semantics when the
high 22 bits (the `extended` and `value_major` parts) are all zero. An
@@ -132,8 +132,8 @@
The [example/jsonfindptrs](/example/jsonfindptrs/jsonfindptrs.cc) program
demonstrates creating a traditional DOM-like node tree from a SAX-like token
stream. The [example/jsonptr](/example/jsonptr/jsonptr.cc) program demonstrates
-a different, lower-level approach that works directly on tokens, where the
-entire program (not just the Wuffs library) never calls `malloc`.
+a lower-level approach that works directly on tokens, where the entire program
+(not just the Wuffs library) never calls `malloc`.
## Example Token Stream
