Skip to content

Commit 427c393

Browse files
avivaceISSOtm
authored andcommitted
Restructure docs, add separate DEPLOY and CONTRIBUTING files (#372)
1 parent b99d50b commit 427c393

File tree

4 files changed

+188
-28
lines changed

4 files changed

+188
-28
lines changed

CONTRIBUTING.md

Lines changed: 170 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
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 `&ndash;`).
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.

README.MD renamed to DEPLOY.md

Lines changed: 2 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,6 @@
1-
# Pan Docs
1+
## Deploy
22

3-
"Pan Docs" is a document started in early 1995, considered the single most comprehensive technical reference to Game Boy available to the public.
4-
5-
This git repository hosts a renewed version of it, mantained in the Markdown format and enjoying renewed community attention.
6-
7-
Go to [gbdev.io/pandocs](https://gbdev.io/pandocs) to read the document.
8-
9-
## Contributing
10-
11-
Everyone is welcome to contribute opening issues, expressing feedback, adding and improving content or share new findings.
12-
13-
Here are some resources you should take a look at:
14-
15-
- [The wiki](https://github.com/gbdev/pandocs/wiki), containing various rules and contribution guidelines you will have to follow when proposing changes. Some RFCs and discussions detailing the document scope are linked there as well.
16-
- [The project board](https://github.com/gbdev/pandocs/projects/1), for a general picture of the roadmap and the ongoing efforts.
17-
- [The issues](https://github.com/gbdev/pandocs/issues), where we discuss what needs to be worked on, and how. If you are looking into investigating Game Boy unknown behaviours, check the Issues labeled with ["research"](https://github.com/gbdev/pandocs/issues?q=is%3Aissue+is%3Aopen+label%3Aresearch).
18-
- [The various community channels](https://gbdev.io/chat.html) where we you can chat directly with maintainers and other contributors.
19-
20-
Once you feel comfortable, fork this repository, make your modifications, and [send a Pull Request](https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests).
21-
22-
### Deploy
23-
24-
To deploy Pan Docs locally:
3+
This document will explain you how to run a local copy of Pan Docs.
254

265
1. Install [Rust](https://www.rust-lang.org/tools/install), [mdBook](https://github.com/rust-lang/mdBook#readme), and [Python 3](https://www.python.org/downloads).
276
mdBook is the tool rendering the documentation, Rust is used for some custom plugins and Python scripts are used to render some images. E.g.:
@@ -191,7 +170,3 @@ cp build/highlight.min.js ../pandocs/theme/highlight.js
191170
- `Cargo.lock`, `Cargo.toml` - Since `preproc/` and `renderer/` share most dependencies (transitively through `mdbook`), this folder is set up as a Cargo workspace. This creates a single `target/` directory in the repo's root, containing both crates' dependencies.
192171
- `book.toml` - The [mdBook configuration file](https://rust-lang.github.io/mdBook/format/configuration).
193172
- `requirements.txt` - The Python package requirements; [see above](#contributing).
194-
195-
## License
196-
197-
We assume the content to be in the [public domain](LICENSE).

README.md

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Pan Docs
2+
3+
"Pan Docs" is a document started in early 1995, considered the single most comprehensive technical reference to Game Boy available to the public.
4+
5+
This git repository hosts a renewed version of it, mantained in the Markdown format and enjoying renewed community attention.
6+
7+
Go to [gbdev.io/pandocs](https://gbdev.io/pandocs) to read the document.
8+
9+
## Contributing
10+
11+
Everyone is welcome to contribute opening issues, expressing feedback, adding and improving content or share new findings. Please, check [CONTRIBUTING](CONTRIBUTING.md) for a complete view on how to contribute to this project.
12+
13+
## License
14+
15+
We assume the content to be in the [public domain](LICENSE).

src/About.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ Emulator developers may be also interested in the [Game Boy: Complete Technical
1313

1414
## Contributing
1515

16-
This project is open source, released under the [CC0 license](https://raw.githubusercontent.com/gbdev/pandocs/master/LICENSE). Everyone is welcome to help, provide feedback and propose additions or improvements. The git repository is hosted at [github.com/gbdev/pandocs](https://github.com/gbdev/pandocs), where you can learn more about how you can [contribute](https://github.com/gbdev/pandocs/blob/master/README.MD), find detailed contribution guidelines and procedures, file Issues and send Pull Requests.
16+
This project is open source, released under the [CC0 license](https://raw.githubusercontent.com/gbdev/pandocs/master/LICENSE). Everyone is welcome to help, provide feedback and propose additions or improvements. The git repository is hosted at [github.com/gbdev/pandocs](https://github.com/gbdev/pandocs), where you can learn more about how you can [contribute](https://github.com/gbdev/pandocs/blob/master/README.md), find detailed contribution guidelines and procedures, file Issues and send Pull Requests.
1717

1818
There is a [Discord chat](https://gbdev.io/chat) dedicated to the gbdev community.
1919

0 commit comments

Comments
 (0)