gbdev / pandocs

The single, most comprehensive Game Boy technical reference.
https://gbdev.io/pandocs/
Creative Commons Zero v1.0 Universal
618 stars 93 forks source link

The big cycle unit rework #534

Closed SonoSooS closed 9 months ago

SonoSooS commented 10 months ago

I've read all pages, searching for instances where clock units in particular were either confusing, ambiguous, misleading, or simply just used wrong. This PR aids to fix all of these.

Notes:

TODO (perhaps for other PRs if these are outside of the scope of this PR):

avivace commented 10 months ago

What's left is explaining those two terms somewhere, but that would be part of a "overview"/"introduction" PR, so it's fine not to deal with it here.

This should go in the "Glossary" (see: https://github.com/gbdev/pandocs/issues/194)

ISSOtm commented 10 months ago

Those are, indeed, hand-written. No editing tool I'm aware of supports "themed" SVGs. I understand the theoretical maintenance loss, but hear me out:

All of these are why I personally consider the tradeoff acceptable when weighed against the gains, chiefly in accessibility and hackability.

[^fallbacks]: Existing SVGs did not have that until 5eaf6f82e6d3fb2d5b23fa3cad10d047708898b9 because I did not think of providing "fallback" values to the var() directives; a few diagrams in outstanding PRs do not yet have this, though; I'll have to get to that.

ISSOtm commented 10 months ago

Also, there are lot of useless arrow "diversion" caused by elements not aligned, such as:

I paid a lot of attention trying to avoid bending the arrows, which required a lot of tweaking overall. Both of these are actually intentional, so I will lay out my rationale for you to judge.

image

This is actually so that the "Timer tick" bubble lies at the same place on both the DMG and CGB diagrams. This mattered more in a tentative design I made where the two diagrams were shown on separate (responsive) columns, side by side. Now that this design has been dropped (the diagrams are too horizontal, they were terribly squished), I guess the bubble can be moved down a little?

image

This was done because the two elements the arrows originate from are too close, necessitating at least one bend. Then, I felt that having only a single bend looked awkward, and made the two actions look asymmetrical, and thus having different priority. (Am I reading too much into it?)

I considered another workaround in making one of the arrows arrive to the register from the top or bottom instead of the side; but looking at the diagrams, vertical arrows designate single bits of registers, whereas horizontal ones designate the register as a whole... which made such a workaround impractical.

Another design I considered was pointing either of the two arrows (probably the "Reset" one) at the register title itself; only problem is, DIV specifically resists such a design, since the low bits are really unnamed[^sys_counter], so there's nothing to point to. That said, now that I thought more about it, it seems possible to perhaps convey that name within the diagram itself (making the right slanted edge of DIV dotted, and otherwise extending the grouping to all 14 bits and inserting the name). What do you think?

[^sys_counter]: The "main text" calls them and DIV "System counter", though I think "M-cycle counter" is more appropriate due to what it's counting; cc @SonoSooS for opinion. Scratch that, it would make too many sentences awkward. "System counter" is fitting if arbitrary, but what name isn't that?

ISSOtm commented 10 months ago

And to answer a question that was asked on IM: yes, I'd say this PR should be considered content-complete; there is one last diagram not converted on the "Timer Obscure Behavior" page, but during the conversion process I realised that it is plain wrong, and fell into a rabbit hole of researching and correcting behaviour.

Which is to say, I'd rather keep those corrections to a separate PR, working on it after this one is deemed acceptable. And I'd rather not expend the effort to convert a diagram before modifying it into something correct, even if it means temporarily having a style discrepancy and keeping some wrong info. (We already have many differing styles throughout the document anyway; big whoop.)