Document Style

Pan Docs document style guide

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.

Monospaced text, code snippets, code boxes

• No ligatures

Pseudocode

• Assignment: :=
• Comparison: =, ≠, <, >, ≤, ≥
• Arithmetic: +, −, ×, /, mod
• Floor/ceiling: ⌊, ⌋, ⌈, ⌉. a := ⌊b⌋ + ⌈c⌉
• Logical: and, or
• 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

Units and prefixes:

• Use ?? prefixes. E.g.:

TODO

• 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.

References:

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

Discussion:

• #76, #55