Registers formatting about pandocs HOT 8 OPEN

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.

from pandocs.

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

from pandocs.

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.

from pandocs.

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.

from pandocs.

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.

from pandocs.

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.

from pandocs.

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.

from pandocs.

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.

from pandocs.