New suggested convention for formatting numbers, units and prefixes

[nitro2k01]

Inspired by PR #54 I would like to suggest the following guidelines for how to write numbers and units:

1. These conventions should be documented near the top of the document, as needed.
2. Use the binary prefix ki (kibi) prefix when referring to 1024, and Mi (mebi) prefix when referring to 1024*1024. (Feel free to argue against this point, however. Note: binary prefixes are currently almost not used.)
3. Capitalize prefixes according to either SI or IEC standards: kilo=k, mega=M, kibi=ki, mebi=Mi. (Note: currently, kilo is fairly consistently capitalized (K) across the document.)
4. Abbreviate bytes as B when used with a prefix. Spell out bits as bits, even when used with a prefix to avoid ambiguity. (Note: currently byte is fairly consistently written as a full word.)
5. Find a suitable prefix or suffix to use for hexadecimal numbers. I'm undecided which format should be used, but I'm personally leaning toward standardizing on $ prefix which is used by RGBDS. But either way, let's decide on one and stick with it. (Note: currently it's a mix between Martin's convention of the suffix h, assembler centrix $, c-centrix 0x, and even sometimes x formatted as multiplication # running text, which to me just looks very wrong.)
6. To prevent clutter, don't use a prefix for hex numbers when it's clear from the context that a number is hexadecimal. For example addresses and lists of opcodes. In those cases, zero pad, even for smaller number. (Eg: 0000-3FFF instead of 0-3FFF. Note: Currently the document pretty much follows this guideline.)
7. Put a space between numbers and their unit. (Note: Currently, memory sizes are often written as 4KB or similar.)
8. Decimal numbers should be written with a decimal point instead of a comma. (I'm only bringing this up because the physical screen sizes are currently written with a decimal comma.)
9. Binary numbers: I suspect that it's sufficiently clear from context when a binary number is used. But when/if a prefix is needed, I suggest %, which is what RGBDS is using.

Feel free to discuss or add more suggestions in case I've forgotten some corner case.

[aaaaaa123456789]

1. OK
2. Binary prefixes are clutter. Outside of standards bodies, the only people who care about decimal units are storage manufacturers. There's absolutely no good reason to quote the maximum ROM size as 8.4 MB, nor would anyone be confused by the (much more obvious) value of 8 MB. I'd recommend using regular prefixes for binary superunits, as is standard practice pretty much everywhere.
3. Makes sense. I'm not that strongly against KB, but whatever is chosen, consistency matters.
4. Agreed, with a few comments: when used as a unit suffix, unit names are always singular, so it should be "20 kbit", not "20 kbits". (Also, "bytes" as a word is fine, just like "30 meters" is a valid way of talking about that length. But "Mbyte" and the like should go away.)
5. $ABCD seems to be the most common format in the community. (Always uppercase is better than always lowercase for documentation.)
6. OK
7. As unusual as this might be in some contexts, this is consistent with ISO standards and clear enough, so agreed.
8. OK, but make sure to avoid using commas as thousand separators.
9. Binary numbers are so unusual that I'd recommend adding the word "binary" explicitly in surrounding text. Assuming familiarity with RGBDS might be a misstep. And unlike the $ convention, this is not as obvious.

[avivace]

1. OK, I suggest to add a preliminary section in which we can explain and describe conventions we'll use in the document.
2. No, I agree with @aaaaaa123456789
3. Agree with @aaaaaa123456789
4. Agree
5. Agree. RGBDS Syntax.
6. Agree.
7. I don't have a strong opinion on this
8. OK
9. Agree with @aaaaaa123456789

Please note that we'll need additional issue to track the consistency of these rules, I'd start with the onest already "almost consistent" (e.g. 6).

[avivace]

This discussion has been incorporated into the Pan Docs document style. Points 2 and 3 are currently held by #76 .