|
| 1 | +# Contributing |
| 2 | + |
| 3 | +Everyone is welcome to contribute opening issues, expressing feedback, adding and improving content or share new findings. In this document you'll find a series of guidelines on how to do so. |
| 4 | + |
| 5 | +## Issues |
| 6 | + |
| 7 | +The issue tracker is where we discuss what needs to be worked on, and how. You can also browse them [by label](https://github.com/gbdev/pandocs/labels). |
| 8 | + |
| 9 | +### [Board](https://github.com/gbdev/pandocs/projects/1) |
| 10 | + |
| 11 | +We use a "Kanban" board on the Project tab of this repository to organize and prioritize the issues. |
| 12 | + |
| 13 | +Some notes on how the task are organised: |
| 14 | + |
| 15 | +**Triage**: the issues here are still in the "request for comments" phase. The discussion is on-going or not enough information is available to progress. You're welcome to join the discussion, provide references and propose solutions. |
| 16 | + |
| 17 | +**To Do**: stuff here is ready to be worked on. There should be all the information needed to work on a PR to implement a solution for those issues. Anyone can take on those issues and send a PR for those tasks. |
| 18 | + |
| 19 | +## Deploy |
| 20 | + |
| 21 | +Check the [DEPLOY](DEPLOY.MD) document to learn how to run a local copy of Pan Docs. |
| 22 | + |
| 23 | +## Community |
| 24 | + |
| 25 | +There are [various community channels](https://gbdev.io/chat.html) where we you can chat directly with maintainers and other contributors. |
| 26 | + |
| 27 | +## Git |
| 28 | + |
| 29 | +Try to follow these guidelines: |
| 30 | + |
| 31 | +- Commit messages should be meaningful, avoid "Update XXX.md". Please describe what you changed, how, and **why**. You can also use the PR message to add details. |
| 32 | +- Maintainers: rebase or squash PRs, please do not create merge commits. Avoid leaving formatting/typos/etc. commits in `master`'s history. |
| 33 | + |
| 34 | +In any case, maintainers will chime in, reviewing what you changed and if necessary commit on your branch to help you through the process of preparing the PR. |
| 35 | + |
| 36 | +## Document Style |
| 37 | + |
| 38 | + |
| 39 | +### 1. Pseudocode |
| 40 | + |
| 41 | +- Assignment: := |
| 42 | +- Comparison: =, ≠, <, >, ≤, ≥ |
| 43 | +- Arithmetic: +, −, ×, ∕, mod |
| 44 | +- Floor/ceiling: ⌊, ⌋, ⌈, ⌉. a := ⌊b⌋ + ⌈c⌉ |
| 45 | +- Logical: and, or, not |
| 46 | +- Sums, products: Σ Π |
| 47 | + |
| 48 | +References: |
| 49 | +1. http://www.cs.cornell.edu/courses/cs482/2003su/handouts/pseudocode.pdf |
| 50 | +2. https://blog.usejournal.com/how-to-write-pseudocode-a-beginners-guide-29956242698 |
| 51 | +3. https://cs.wmich.edu/gupta/teaching/cs3310/sp18cs3310web/lecture%20notes%20cs3310/PseudocodeBasics.pdf |
| 52 | +4. https://en.wikipedia.org/wiki/Pseudocode#Mathematical_style_pseudocode |
| 53 | + |
| 54 | +### 2. Units and prefixes: |
| 55 | + |
| 56 | +Use Binary Prefixes (Ki, Mi) for Bytes. E.g.: |
| 57 | + |
| 58 | +``` |
| 59 | +1 MiB = 2^20 bytes = 1,048,576 bytes |
| 60 | +1 KiB = 2^10 bytes = 1,024 bytes |
| 61 | +``` |
| 62 | + |
| 63 | +- 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.) |
| 64 | +- 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 numbers: `0000-3FFF` instead of `0-3FFF`. |
| 65 | +- Put a space between numbers and their unit (ISO). |
| 66 | +- Decimal numbers must be written with a decimal point instead of a comma. |
| 67 | +- Binary numbers must be accompanied by the "binary" word. |
| 68 | +- Other units (such as Hertz) may use the decimal prefixes (K = 1000, M = 1000000) |
| 69 | + |
| 70 | +References: |
| 71 | +- https://superuser.com/questions/938234/size-of-files-in-windows-os-its-kb-or-kb#comment1275467_938259 |
| 72 | + |
| 73 | +Discussion: |
| 74 | +- [#76](https://github.com/gbdev/pandocs/issues/76), [#55](https://github.com/gbdev/pandocs/issues/55) |
| 75 | + |
| 76 | + |
| 77 | +### 3. 8 bits / 8-bit |
| 78 | + |
| 79 | +- "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. |
| 80 | + |
| 81 | +Discussion: |
| 82 | +- [#102](https://github.com/gbdev/pandocs/issues/102) |
| 83 | + |
| 84 | +### 4. Horizontal Blanking Interval, Vertical Blanking Interval |
| 85 | + |
| 86 | +- VBlank, HBlank, not V-Blank/H-Blank or Vblank/Hblank |
| 87 | + |
| 88 | +Discussion: |
| 89 | +- [#94](https://github.com/gbdev/pandocs/issues/94) |
| 90 | + |
| 91 | +### 5. Mentioning models |
| 92 | + |
| 93 | +We use the console codenames, so: |
| 94 | + |
| 95 | +- DMG |
| 96 | +- SGB |
| 97 | +- MGB (Game Boy Pocket) |
| 98 | +- SGB2 (Super Game Boy 2) |
| 99 | +- CGB (Game Boy Color) |
| 100 | +- AGB (Game Boy Advance) |
| 101 | + |
| 102 | +### 6. Spacing and hyphenation of some terms |
| 103 | + |
| 104 | +- "tile map", not "tilemap" |
| 105 | +- "wavelength", not "wave length" ([#350 (comment)](https://github.com/gbdev/pandocs/pull/350#discussion_r709713631)) |
| 106 | + |
| 107 | +### 7. Numerical ranges |
| 108 | + |
| 109 | +Those should either be written out (1 to 42), or use an "n-dash" `–` (can also be written as the HTML entity `–`). |
| 110 | + |
| 111 | +Discussion: |
| 112 | +- [#341 (comment)](https://github.com/gbdev/pandocs/pull/341#discussion_r708681099) |
| 113 | + |
| 114 | + |
| 115 | +## SVG |
| 116 | + |
| 117 | +### Rationale |
| 118 | + |
| 119 | +The preferred format for diagrams in Pan Docs is SVG. |
| 120 | +- ASCII, Unicode, or text-only diagrams are not accessible (screen readers, etc.) |
| 121 | +- "Raster" images do not scale, and e.g. text within them cannot be selected. |
| 122 | +- Additionally, raster images may be troublesome to post-edit without extra "source" files (e.g. XCF or PSD files). |
| 123 | +- Lastly, SVGs can be dynamically styled, allowing for better integration within the page. |
| 124 | + |
| 125 | +### Guidelines |
| 126 | + |
| 127 | +SVGs can be created using a lot of programs: [Inkscape](https://inkscape.org), a text editor ([SVGs are just XML documents!](https://developer.mozilla.org/en-US/docs/Web/SVG)), and others. |
| 128 | + |
| 129 | +**Be wary of "image to SVG converters"**, as these tend to just embed the raster image within a SVG document, which most of the time generates a larger file with none of the benefits expected from a SVG. |
| 130 | + |
| 131 | +"Raster" images, like PNG, JPEG, BMP, and so on, store pixels. |
| 132 | +SVGs (and more generally, "vector" graphics) instead contain commands to draw shapes. |
| 133 | +For this reason, and because computers are bad at recognizing shapes, **converting from the former to the latter has to be largely done by hand from scratch**. |
| 134 | +(On the other hand, it's a good time to go over any improvements that can be brought to the diagram!) |
| 135 | + |
| 136 | +### Dynamically-styled SVGs |
| 137 | + |
| 138 | +A good reference is [this commit](https://github.com/gbdev/pandocs/commit/be820673f71c8ca514bab4d390a3004c8273f988#diff-806f4be9ec1ba99e972f48151ca8a3f19d3048a7dbe6f39853dff85ee01806e6). |
| 139 | +(NB: only the new SVG file and the modification to `src/pixel_fifo.md` need to be considered. The rest is cleanup and plumbing.) |
| 140 | +It may be a good idea to check out that example if you aren't sure and want to check something. |
| 141 | + |
| 142 | +SVGs can be displayed in a page in two ways: either linked to from an `<img>` tag, or embedded directly in the HTML document via a `<svg>` tag. |
| 143 | +[Due to technicalities](https://stackoverflow.com/questions/18434094/how-to-style-svg-with-external-css), SVGs cannot access the parent document's style sheet when displayed using the former method. |
| 144 | + |
| 145 | +The way themes change styling is using [CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/--*), specifically [all of these](https://github.com/rust-lang/mdBook/blob/d22299d9985eafc87e6103974700a3eb8e24d73d/src/theme/css/variables.css#L11-L210). |
| 146 | +The variables can be reused within a SVG's stylesheet to make it automatically update its style when a new theme is selected, but this requires embedding the SVG within the page for it to have access to those variables. |
| 147 | + |
| 148 | +#### How-to |
| 149 | + |
| 150 | +In theory, pasting the SVG directly within the Markdown document would work. |
| 151 | +However, this increases its size a lot, and thus hinders navigation; it also makes the SVG impossible to view and edit on its own. |
| 152 | +For these reasons, use of mdBook's ["include" mechanism](https://rust-lang.github.io/mdBook/format/mdbook.html#including-files) is preferred. |
| 153 | + |
| 154 | +First, create the SVG file itself; see further above for general directions. |
| 155 | +To have the SVG be dynamically styled, you will likely have to open it in a text editor and manually change it. |
| 156 | +Locate the `<defs>` element directly within the `<svg>` tag, and then the `<style>` tag within that. |
| 157 | +Create those as necessary if they aren't present. |
| 158 | + |
| 159 | +Now, add CSS rules to style the elements (although CSS within SVGs affects [different attributes](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute), so [some attributes have different names](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/fill#text)). |
| 160 | +You can add classes and/or IDs to the elements as normal, and use those in CSS selectors. |
| 161 | + |
| 162 | +Once that is done, you must ensure that the file contains **no empty lines** (whitespace doesn't count) after the opening `<svg>` tag. |
| 163 | +Any blank lines will break the Markdown markup, and likely yield a broken image. |
| 164 | +Additionally, remember which line the opening `<svg>` tag is on for the next step. |
| 165 | + |
| 166 | +Then, add a directive to embed the file's contents, for example `{{#include imgs/ppu_modes_timing.svg:2:}}`. |
| 167 | +Replace `imgs/ppu_modes_timing.svg` with the path to the SVG from the `src/` folder, and `2` with the line number the opening `<svg>` tag is on. |
| 168 | + |
| 169 | +A word of caution about the directive's placement: if it is surrounded by empty lines, the image will be outside of any paragraphs, within the document's main flow. |
| 170 | +However, if it is adjacent to a line of text, it may be placed within the paragraph, which is likely not what you want. |
0 commit comments