From f0ab09125493f91d66af836e0abb977459a0d801 Mon Sep 17 00:00:00 2001
From: Remy Oukaour <remy.oukaour@gmail.com>
Date: Tue, 12 Dec 2017 18:50:39 -0500
Subject: [PATCH] Add an FAQ, and ive a bit more detail in Windows install
 instructions

---
 FAQ.md                | 32 ++++++++++++++++++++++++++++++++
 INSTALL.md            | 29 ++++++++++++++++++-----------
 README.md             |  1 +
 docs/text_commands.md |  5 +++--
 4 files changed, 54 insertions(+), 13 deletions(-)
 create mode 100644 FAQ.md

diff --git a/FAQ.md b/FAQ.md
new file mode 100644
index 000000000..a02f22629
--- /dev/null
+++ b/FAQ.md
@@ -0,0 +1,32 @@
+# FAQ
+
+## What is pokecrystal11.gbc?
+
+Version 1.1 of Pokémon Crystal, which fixed some issues with the initial international release. `make crystal11` defines `CRYSTAL11` so the assembly builds the changed version.
+
+## Can't build ROM; "ERROR: `UNION` already defined"
+
+Download [**rgbds 0.3.3**](rgbds). Earlier versions will not work.
+
+## Can't build ROM; "Segmentation fault" from `rgbgfx`
+
+If you are using 64-bit Windows, download [**64-bit Cygwin**](cygwin) and [**64-bit rgbds**](rgbds).
+
+## Can't build ROM; "Section is too big" or "Unable to place section in bank"
+
+If you have not changed any of the asm, make sure you have the latest version of pokecrystal and the correct version of rgbds (see [INSTALL.md](INSTALL.md)).
+
+If you added or changed any code, it has to fit in the **memory banks**. The 2MB ROM is divided into 128 banks of 4KB each, numbered $00 to $7F. The linkerscript **pokecrystal.link** lists which **`SECTION`**s go in which banks. Try moving some code into a new section.
+
+## How do I edit maps?
+
+For `asm` scripts, read [docs/map_scripts.md](docs/map_scripts.md). For `blk` layouts, try [crowdmap](crowdmap) or [Polished Map](polished-map).
+
+## I need more help!
+
+Try asking on IRC or Discord (see [README.md](README.md)).
+
+[cygwin]: https://cygwin.com/install.html
+[rgbds]: https://github.com/rednex/rgbds/releases
+[crowdmap]: https://github.com/yenatch/crowdmap/
+[polished-map]: https://github.com/roukaour/polished-map
diff --git a/INSTALL.md b/INSTALL.md
index c15044d13..2bfc34085 100644
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -1,10 +1,12 @@
-The source files are assembled into a rom using [**rgbds**](https://github.com/rednex/rgbds).
+# Instructions
+
+The source files are assembled into a ROM using [**rgbds**](https://github.com/rednex/rgbds).
 These instructions explain how to set up the tools required to build.
 
-If you run into trouble, ask for help on irc or discord (see [README.md](README.md)).
+If you run into trouble, ask for help on IRC or Discord (see [README.md](README.md)).
 
 
-# Linux
+## Linux
 
 ```bash
 sudo apt-get install make gcc bison git libpng-dev
@@ -25,7 +27,7 @@ make
 ```
 
 
-# Mac
+## Mac
 
 In **Terminal**, run:
 
@@ -48,24 +50,23 @@ make
 ```
 
 
-# Windows
+## Windows
 
-To build on Windows, install [**Cygwin**](http://cygwin.com/install.html) with the default settings.
+Download [**Cygwin**](http://cygwin.com/install.html): **setup-x86_64.exe** for 64-bit Windows, **setup-x86.exe** for 32-bit.
+
+Run setup and leave the default settings. At "Select Packages", choose to install the following:
 
-In the installer, select the following packages:
 - `make`
 - `git`
 - `gcc-core`
 
-Then download [**rgbds**](https://github.com/rednex/rgbds/releases/).
-Extract rgbds-0.3.3-win64.tar.gz and put all the `exe` and `dll` files individually in **C:\Cygwin64\usr\local\bin**. If you are using 32-bit Windows and Cygwin, extract **rgbds-0.3.3-win32.tar.gz** to **C:\Cygwin\usr\local\bin**.
+Then download [**rgbds**](https://github.com/rednex/rgbds/releases/): the latest **win64.tar.gz** or **win32.tar.gz** release. Extract it and put all the `exe` and `dll` files individually in **C:\Cygwin64\usr\local\bin**.
 
 **Note: If you have an older rgbds, you will need to update to 0.3.3 or newer.** Ignore this if you have never installed rgbds before.
 
-In the **Cygwin terminal**:
+In the **Cygwin terminal**, enter these commands:
 
 ```bash
-
 git clone https://github.com/pret/pokecrystal
 cd pokecrystal
 ```
@@ -75,3 +76,9 @@ To build **pokecrystal.gbc**:
 ```bash
 make
 ```
+
+To build **pokecrystal11.gbc**:
+
+```bash
+make crystal11
+```
diff --git a/README.md b/README.md
index 5ec1bbf73..95940bd89 100644
--- a/README.md
+++ b/README.md
@@ -10,6 +10,7 @@ It builds the following roms:
 To set up the repository, see [INSTALL.md](INSTALL.md).
 
 ## See also
+
 * Disassembly of [**Pokémon Red/Blue**][pokered]
 * Disassembly of [**Pokémon Yellow**][pokeyellow]
 * Disassembly of [**Pokémon Pinball**][pokepinball]
diff --git a/docs/text_commands.md b/docs/text_commands.md
index 3d502f399..865ea69b5 100644
--- a/docs/text_commands.md
+++ b/docs/text_commands.md
@@ -38,8 +38,9 @@ Write text from a RAM address.
 
 ## `$02`: `text_bcd` *address*, *flags*
 
-Write [BCD](https://en.wikipedia.org/wiki/Binary-coded_decimal) from an address,
-typically RAM.
+Write [BCD](bcd) from an address, typically RAM.
+
+[bcd]: https://en.wikipedia.org/wiki/Binary-coded_decimal
 
 ## `$03`: `text_move` *address*