search

gbdev / pandocs

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

Registers formatting #11

Open avivace opened 4 years ago

avivace commented 4 years ago

Feedback by @Bananattack on Discord:

Hmm, I noticed the formatting for registers on the new pandocs is a funky right now:

1) It's currently inconsistent about whether a hardware register lists its hex address, a symbolic name, or its descriptive "full name". It should probably do all 3, in the order of "hex address - symbolic name - full name" 2) LCDC is missing its hex address, and is only called LCD Controller Register in the header. 3) Hexadecimal values should probably start with a $ to more clearly call out the numeric base. 4) The convention for indicating read/write of a register is inconsistent, sometimes it's (R/W), sometimes it's (Read/Write)

@endrift 's gbdoc (https://github.com/mgba-emu/gbdoc/blob/gh-pages/index.md#mmio) has a very nice way of documenting registers

ghost commented 3 years ago

I offer to prefix all hexadecimal numbers with 0x and following with uppercase letters, like: 0xFE9F. This will remove the mental load to figure out which base a number in. Currently h suffix is used, like 10h. The assembly style $ prefix is doesn't tell much about the base for those never touch the assembly. Even worse some numbers have no prefix or suffix, but just the way it's written shows its base like: FF03.

Same way we can also prefix binaries with 0b, as in 0b0000'1111 or 0b11.

ISSOtm commented 3 years ago

Wasn't it decided elsewhere to use RGBDS notation? ($c0de, %0010_1010)

aaaaaa123456789 commented 3 years ago

The decision was to use $ for hex and just explicitly mentioning that numbers are binary when they are: https://github.com/gbdev/pandocs/wiki/Document-Style#units-and-prefixes

Something like 0b11 is extremely confusing for someone who hasn't seen the notation before (as it can be rightfully mistaken for a hexadecimal number); that notation should never be used in any form of documentation that doesn't target a specific programming language (or family of languages) that already uses that notation.

ghost commented 3 years ago

Adapting notation from a programming language doesn't necessarily a bad thing IMO. And current notation already adapted from assembly.

The PanDocs needs much more bold and concrete notation, statements, wording and details on overall document. Current state is far from useful to help inspired emulator developers. Lots of the time new emulators ended up implementing others emulator, which effectively being a port of another emulator. Because the ambiguities on the docs here and there make creative emulators impossible. PanDocs can be good candidate to do original jobs because lots of experiences people are interested in it someway. Creating road map can be useful.

0b11 might be confusing, but 0b0000'0011 would be sufficiently understandable.

ISSOtm commented 3 years ago

Pan Docs does not try to be a resource for emulator developers, but for homebrew developers. gb-ctr is much better suited to emu dev.

ghost commented 3 years ago

Unfortunately PPU part is incomplete, which is one of the core part of emulators. I can appreciate how difficult constructing a factually correct sentence on a technical matter though. Different docs are has different depth on subsystems. The gb-ctr does good job on CPU instructions and timing.

I would like to see some kind of merger with the PanDocs, some kind of pipeline that offer complete documentation that render pdf from every tag. Such a merger and crediting authors in proper way, will be helpful for community and history preservation.

avivace commented 3 years ago

Adapting notation from a programming language doesn't necessarily a bad thing IMO. And current notation already adapted from assembly.

I agree. But before anything, we need to put workflows and standards in place, since the document is still very inconsistent. We already had the discussion for hex strings, but you're welcome to open another issue to change the decision.

From what I've seen, binary strings are (or can be made) very clear from the context anyway, so I don't we think we need another prefix.

The PanDocs needs much more bold and concrete notation, statements, wording and details on overall document.

This is true and every PR directed at improving this is welcome. Stating these guidelines will be very useful too.

PanDocs can be good candidate to do original jobs because lots of experiences people are interested in it someway. Creating road map can be useful.

I agree and this kind of stuff should be discussed (roadmap is a good idea), but this is not currently our goal and there's a lot work just to standardise, correct and format the current information, let alone add o restructure stuff (just take a look at the issues). gb-ctr is much more suited at the moment.

ISSOtm commented 3 years ago

What's the status on this? 1. and 4. are covered by #163, 2. has been fixed, and 3. is now part of the style guide, so it's "just" general cleanup now.