Document Style

Pan Docs document style guide

Document status: DRAFT

Contributors: List here people that commented and joined discussions in the referenced issues, aaaaaa123456789

1. Conventions documentation

A short paragraph introducing and clarifying the conventions used in the document must be placed (and kept updated) in the top of the document.

2. Monospaced text, code snippets, code boxes

• No ligatures

3. Pseudocode

• Assignment: :=
• Comparison: =, ≠, <, >, ≤, ≥
• Arithmetic: +, −, ×, /, mod
• Floor/ceiling: ⌊, ⌋, ⌈, ⌉. a := ⌊b⌋ + ⌈c⌉
• Logical: and, or, not
• Sums, products: Σ Π

References:

1. http://www.cs.cornell.edu/courses/cs482/2003su/handouts/pseudocode.pdf
2. https://blog.usejournal.com/how-to-write-pseudocode-a-beginners-guide-29956242698
3. https://cs.wmich.edu/gupta/teaching/cs3310/sp18cs3310web/lecture%20notes%20cs3310/PseudocodeBasics.pdf
4. https://en.wikipedia.org/wiki/Pseudocode#Mathematical_style_pseudocode

4. Units and prefixes:

Use Binary Prefixes (Ki, Mi) for Bytes. E.g.:

1 MiB = 2^20 bytes = 1,048,576 bytes
1 KiB = 2^10 bytes = 1,024 bytes

• Abbreviate bytes as B when used with a prefix. Spell out bits as bits, even when used with a prefix to avoid ambiguity. 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.)
• Hexadecimal values are uppercase and prefixed with $. E.g. $ABCD. 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.
• Put a space between numbers and their unit (ISO).
• Decimal numbers must be written with a decimal point instead of a comma.
• Binary numbers must be accompanied by the "binary" word.
• Other units (such as Hertz) may use the decimal prefixes (K = 1000, M = 1000000)

References:

• https://superuser.com/questions/938234/size-of-files-in-windows-os-its-kb-or-kb#comment1275467_938259

Discussion:

• #76, #55

5. 8 bits / 8-bit

• "8 bits" and "8-bit" have different usages in the English language. The former is used when talking about the quantity ("a byte has 8 bits"), while the latter is used as an adjective ("8-bit bytes are nowadays standard"). "8bit" is obviously wrong, and "8 bit" is likewise incorrect.

Discussion:

• #102

6. Horizontal Blanking Interval, Vertical Blanking Interval

• VBlank, HBlank

Discussion:

• #94

7. Mentioning models

We use the console codenames, so:

• DMG
• SGB
• MGB
• SGB2
• CGB
• AGB

8. "tile map", not "tilemap"

9. Numerical ranges

Those should either be written out (1 to 42), or use an "n-dash" – (can also be written as the HTML entity –).

Discussion:

• #341 (comment)