pandocs
pandocs copied to clipboard
gbdev
Styling for "bit explanation" tables/diagrams
In this discussion: https://github.com/gbdev/pandocs/pull/310#discussion_r670237566
It came up that the current standard for explaining the function of individual bits in a control register is less than readable and/or is ugly.
Lets decide on something better.
Using this section as an example: https://gbdev.io/pandocs/STAT.html#ff41---stat-lcd-status-rw
Old Pandocs style: (ugly)
Bit 6 - LYC=LY STAT Interrupt source (1=Enable) (Read/Write)
Bit 5 - Mode 2 OAM STAT Interrupt source (1=Enable) (Read/Write)
Bit 4 - Mode 1 VBlank STAT Interrupt source (1=Enable) (Read/Write)
Bit 3 - Mode 0 HBlank STAT Interrupt source (1=Enable) (Read/Write)
Bit 2 - LYC=LY Flag (0=Different, 1=Equal) (Read Only)
Bit 1-0 - Mode Flag (Mode 0-3, see below) (Read Only)
0: In HBlank
1: In VBlank
2: Searching OAM
3: Transferring Data to LCD Controller
Current style guide (same thing but as a table): (wall of text)
| Bits | Name/Function | Value | Read/Write |
|---|---|---|---|
| Bit 6 | LYC=LY STAT Interrupt source | 1=Enable | Read/Write |
| Bit 5 | Mode 2 OAM STAT Interrupt source | 1=Enable | Read/Write |
| Bit 4 | Mode 1 VBlank STAT Interrupt source | 1=Enable | Read/Write |
| Bit 3 | Mode 0 HBlank STAT Interrupt source | 1=Enable | Read/Write |
| Bit 2 | LYC=LY Flag | 0=Different, 1=Equal | Read Only |
| Bit 1-0 | Mode Flag | Mode 0-3, see below | Read Only |
| Mode | Name/Function |
|---|---|
| 0 | In HBlank |
| 1 | In VBlank |
| 2 | Searching OAM |
| 3 | Transferring Data to LCD Controller |
"Diagram" style (based on tauwasser's MMM01 docs): https://wiki.tauwasser.eu/view/MMM01#RAM_Enable_Register
Bits: X 6 5 4 3 2 1 0
| | | | | \_/
| | | | | \----- Bits 0-1: Current Mode (Read Only)
| | | | \-------- Bit 2: LYC=LY Flag (Read Only)
| | | \---------- Bit 3: Enable HBlank STAT Interrupt Source (Read/Write)
| | \------------ Bit 4: Enable VBlank STAT Interrupt Source (Read/Write)
| \-------------- Bit 5: Enable OAM STAT Interrupt Source (Read/Write)
\---------------- Bit 6: Enable LYC=LY STAT Interrupt Source (Read/Write)
"Diagram" style using unicode box drawing symbols:
Bits: X 6 5 4 3 2 1 0
│ │ │ │ │ └─┘┄ Bits 0-1: Current Mode (Read Only)
│ │ │ │ └────┄ Bit 2: LYC=LY Flag (Read Only)
│ │ │ └──────┄ Bit 3: Enable HBlank STAT Interrupt Source (Read/Write)
│ │ └────────┄ Bit 4: Enable VBlank STAT Interrupt Source (Read/Write)
│ └──────────┄ Bit 5: Enable OAM STAT Interrupt Source (Read/Write)
└────────────┄ Bit 6: Enable LYC=LY STAT Interrupt Source (Read/Write)
(GitHub doesn't seem to join up the vertical ones, which is a shame)
Hybrid "diagram table" style?: (not keen on this one myself)
6 5 4 3 2 1 0 |
Bits | Name/Function | Read/Write |
|---|---|---|---|
│ │ │ │ │ └─┘ |
Bits 0-1 | Current Mode | Read Only |
│ │ │ │ └───── |
Bit 2 | LYC=LY Flag | Read Only |
│ │ │ └─────── |
Bit 3 | Enable HBlank STAT Interrupt Source | Read/Write |
│ │ └───────── |
Bit 4 | Enable VBlank STAT Interrupt Source | Read/Write |
│ └─────────── |
Bit 5 | Enable OAM STAT Interrupt Source | Read/Write |
└───────────── |
Bit 6 | Enable LYC=LY STAT Interrupt Source | Read/Write |
Separate svg diagram? (probably best, but I've not authored one of these myself before)
I think my order of preference is probably svg diagram followed by diagram style using unicode box drawing symbols (even though it uses a code block).
However neither can have xlinks embedded, which is unfortunate.
Anyone got any better ideas?
Monospaced text should not be used for this, as it does not scale on small devices, and lacks accessibility.
Monospaced text and/or diagrams draw with unicode symbols are excluded for the reasons @ISSOtm mentioned.
We should not use images and/or graphical diagrams if not stricly needed, as they don't scale very good anyway.
As long as we don't have an high number of columns the "table" rending is indeed the best one for me, as it scales the best: the browser can redraw text inside cells, the table can be 100% wide on small devices, ...
The table loses the "visual" aspect of it.
Why? What you are losing listing the bytes by rows instead of by columns? If you think that can help, you can draw something like this
| 0x | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
|---|---|---|---|---|---|---|---|---|
| $RR |
before the table, but I don't see how giving up the clarity of a table in favour of a diagram to explain a registry can help in any way.
On the other hand, something like this can go in a "preliminary" chapter on how to read the document
Bits: X 6 5 4 3 2 1 0
| | | | | \_/
| | | | | \----- Bits 0-1: Current Mode (Read Only)
| | | | \-------- Bit 2: LYC=LY Flag (Read Only)
| | | \---------- Bit 3: Enable HBlank STAT Interrupt Source (Read/Write)
| | \------------ Bit 4: Enable VBlank STAT Interrupt Source (Read/Write)
| \-------------- Bit 5: Enable OAM STAT Interrupt Source (Read/Write)
\---------------- Bit 6: Enable LYC=LY STAT Interrupt Source (Read/Write)
The table loses the "visual" aspect of it.
Why? What you are losing listing the bytes by rows instead of by columns? If you think that can help, you can draw something like this
0x 7 6 5 4 3 2 1 0 $RR before the table, but I don't see how giving up the clarity of a table in favour of a diagram to explain a registry can help in any way.
That style is similar to the diagrams used in the official Nintendo manual, and IMO is nice enough. That said, we may wish to use some colspans for emphasizing fields, and some custom styling for "unused" bits.
Generating those tables via HTML seems like the only real option, but this could be done with custom syntax dealt with by a mdBook preprocessor for convenience.
The table loses the "visual" aspect of it.
Why? What you are losing listing the bytes by rows instead of by columns? If you think that can help, you can draw something like this
0x 7 6 5 4 3 2 1 0 $RR before the table, but I don't see how giving up the clarity of a table in favour of a diagram to explain a registry can help in any way.
That style is similar to the diagrams used in the official Nintendo manual, and IMO is nice enough. That said, we may wish to use some
colspans for emphasizing fields, and some custom styling for "unused" bits.Generating those tables via HTML seems like the only real option, but this could be done with custom syntax dealt with by a mdBook preprocessor for convenience.
The problem of that approach is it becomes completely unreadable if you want to put anything longer than some words in each of the cell - it just ends up being break into 2-3 lines
Nintendo's diagrams handle this by putting the long explanations outside of the table. For example, the fields could be given names, and then explained below.
| Bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
|---|---|---|---|---|---|---|---|---|
| NR14 | Restart | Len enable | 1 | 1 | 1 | Freq high | ||
- Restart (write-only): when this bit is set, the channel is restarted.
- Length enable (read/write): if this bit is set, the channel is stopped when the length in NR11 expires.
- Freq high (write-only): the upper 3 bits of the channel's frequency.
Only with manually-written HTML tables, but as I mentioned further above, I can whip up a mdBook preprocessor that would generate those from more convenient syntax.
Do we support column spanning like that?
Yes, we do. There are examples of "markdown can't do that, let's fall back to HTML" around the document and I don't see it as a bad thing. If it becomes a more frequent feature we can work on a preprocessor to provide us a markdown-syntax for that
Nintendo's diagrams handle this by putting the long explanations outside of the table. For example, the fields could be given names, and then explained below. Bit 7 6 5 4 3 2 1 0 NR14 Restart Len enable 1 1 1 Freq high
* **Restart** (write-only): when this bit is set, the channel is restarted. * **Length enable** (read/write): if this bit is set, the channel is stopped when the length in NR11 expires. * **Freq high** (write-only): the upper 3 bits of the channel's frequency.
This is something I like, which ultimately reduces to what we are already doing, just removing the "bit" column
Yes, we do. There are examples of "markdown can't do that, let's fall back to HTML" around the document and I don't see it as a bad thing. If it becomes a more frequent feature we can work on a preprocessor to provide us a markdown-syntax for that
Given how many "register bit descriptions" we have, I'd work on preprocessed syntax straight away :P
I'm a fan of either the table format or the table + description format; I'm explicitly opposed to using SVG for this.
Given that this seems to have at least some consensus and no opposition, I'm beginning work on this.
Before actually starting to apply this style, we should formalize it https://github.com/gbdev/pandocs/wiki/Document-Style
I opened #334 to allow for a live preview.
Source:
{{#bits 8 Attributes 7:"Priority" 6:"Y flip" 5:"X flip" 4:"DMG palette" 3:"Bank" 0-2:"CGB palette"}}
Result:
I would say the numbered columns need to be all the same width, and with clearer dividing lines.
Otherwise, that's beginning to look fantastic!
Hm, I don't know if I can distribute the column widths evenly while leaving "auto" space for the row name... I don't know how manually setting a width affects tables, unfortunately.
Another criticism I have is that the [Non CGB Mode only] info, as well as the (Read / Write) if it were present, are harder to read since they are misaligned... I'm not sure how to remedy that. A table could work, but it may look jarring to have two tables back to back like that, and manually aligning elements in the list description doesn't sound like a good idea.
Maybe that kind of info should be styled differently; I suggest either italics, or monospace font. (I don't think underlining would work well for this.)
There doesn't seem to be a way in html/css to specify some columns as being equal without specifying their exact size.
We could specify it in em? 8em?
Not great, there's a max width too. Hardcoding the width manually is also imo too fragile, I'd prefer avoiding it.
I think a css grid layout can do it. But that does require different html. And a flexbox might achieve this as well, and potentially could be made more responsive where the table will be vertical on mobile.
So, here is the formalism I'm currently suggesting:
- **Field name** [*Usage notes ("CGB Mode only")*] (*R/W*): Description...
Related question: what about Read/Write? Imo, they shouldn't be kept in section titles, unless there is no bit description table, as they are otherwise redundant.
Alright, I think this should be wrapped up. I uploaded a live preview, and documented the syntax and preferred style as per https://github.com/gbdev/pandocs/issues/318#issuecomment-885256706.
I don't want to convert any other tables until there seems to be no more opposition. [EDIT] Turns out I had some more tables converted in my git stash, so I'm cleaning that up (read: rebasing) and pushing it. At least it'll provide more material to bikeshed on!