Improvements to documentation (#1919)

* Typo: Github => GitHub

* Typo: windows => Windows, docker => Docker, and some punctuations

* "QMK Introduction" links to the right file

* "Unix" rather than "UNIX", which is a trademark

* Directory name is "keyboards", not "keyboard"

* "handwired" is a subdirectory of "keyboards"

* Punctuation and minor fixes

* macOS rather than Mac

* Punctuation and other minor fixes

* Vagrant Guide links to an existing file

* Jun Wako referenced with his name rather than his nickname

* Saxon genitive 's outside the link

diff --git a/docs/faq_general.md b/docs/faq_general.md
index fcc40e0a1fe02602ba7c5b49f402ad098436b878..7647b1c2a1407cb6bd4d5b495afdc3158236825e 100644 (file)
--- a/docs/faq_general.md
+++ b/docs/faq_general.md
@@ -10,7 +10,7 @@
 
 ## What Differences Are There Between QMK and TMK?
 
 
 ## What Differences Are There Between QMK and TMK?
 

-TMK was originally designed and implemented by [Jun Wako](https://github.com/tmk). QMK started as [Jack Humbert's](https://github.com/jackhumbert) fork of TMK for the Planck. After a while Jack's fork had diverged quite a bit from TMK, and in 2015 Jack decided to rename his fork to QMK.
+TMK was originally designed and implemented by [Jun Wako](https://github.com/tmk). QMK started as [Jack Humbert](https://github.com/jackhumbert)'s fork of TMK for the Planck. After a while Jack's fork had diverged quite a bit from TMK, and in 2015 Jack decided to rename his fork to QMK.

 
 From a technical standpoint QMK builds upon TMK by adding several new features. Most notably QMK has expanded the number of available keycodes and uses these to implement advanced features like `S()`, `LCTL()`, and `MO()`. You can see a complete list of these keycodes in [Keycodes](keycodes.md).
 
 
 From a technical standpoint QMK builds upon TMK by adding several new features. Most notably QMK has expanded the number of available keycodes and uses these to implement advanced features like `S()`, `LCTL()`, and `MO()`. You can see a complete list of these keycodes in [Keycodes](keycodes.md).
 

diff --git a/docs/getting_started_build_tools.md b/docs/getting_started_build_tools.md
index 934617d852241fdcdb8162b8c553adf0e79e5a8f..88612ff56429c0ab50dad198c65a52cccf71662c 100644 (file)
--- a/docs/getting_started_build_tools.md
+++ b/docs/getting_started_build_tools.md
@@ -1,6 +1,6 @@
 # Installing Build Tools
 
 # Installing Build Tools
 

-This page describes setting up the build environment for QMK. These instructions cover AVR processors (such as the atmega32u4.)
+This page describes setting up the build environment for QMK. These instructions cover AVR processors (such as the atmega32u4).

 
 <!-- FIXME: We should have ARM instructions somewhere. -->
 
 
 <!-- FIXME: We should have ARM instructions somewhere. -->
 


@@ -44,7 +44,7 @@ By default, this will download compilers for both AVR and ARM. If you don't need
 
     nix-shell --arg arm false
 
 
     nix-shell --arg arm false
 

-## Mac
+## macOS

 If you're using [homebrew,](http://brew.sh/) you can use the following commands:
 
     brew tap osx-cross/avr
 If you're using [homebrew,](http://brew.sh/) you can use the following commands:
 
     brew tap osx-cross/avr


@@ -58,10 +58,10 @@ This is the recommended method. If you don't have homebrew, [install it!](http:/
 
 ## Windows with msys2 (recommended)
 
 
 ## Windows with msys2 (recommended)
 

-The best environment to use, for Windows Vista through any later version (tested on 7 and 10,) is [msys2](http://www.msys2.org).
+The best environment to use, for Windows Vista through any later version (tested on 7 and 10), is [msys2](http://www.msys2.org).

 
 

-* Install msys2 by downloading and following the instructions here: http://www.msys2.org
-* Open the "MSYS2 MingGW 64-bit" shortcut
+* Install msys2 by downloading it and following the instructions here: http://www.msys2.org
+* Open the ``MSYS2 MingGW 64-bit`` shortcut

 * Navigate to your qmk checkout. For example, if it's in the root of your c drive:
  * `$ cd /c/qmk_firmware`
 * Run `util/msys2_install.sh` and follow the prompts
 * Navigate to your qmk checkout. For example, if it's in the root of your c drive:
  * `$ cd /c/qmk_firmware`
 * Run `util/msys2_install.sh` and follow the prompts


@@ -80,7 +80,7 @@ If you already have cloned the repository on your Windows file system you can ig
 
 You will need to clone the repository to your Windows file system using the normal Git for Windows and **not** the WSL Git. So if you haven't installed Git before, [download](https://git-scm.com/download/win) and install it. Then [set it up](https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup), it's important that you setup the e-mail and user name, especially if you are planning to contribute. 
 
 
 You will need to clone the repository to your Windows file system using the normal Git for Windows and **not** the WSL Git. So if you haven't installed Git before, [download](https://git-scm.com/download/win) and install it. Then [set it up](https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup), it's important that you setup the e-mail and user name, especially if you are planning to contribute. 
 

-Once Git is installed, open the Git bash command and change the directory to where you want to clone QMK, note that you have to use forward slashes, and that your c drive is accessed like this `/c/path/to/where/you/want/to/go`. Then run `git clone --recurse-submodules https://github.com/qmk/qmk_firmware`, this will create a new folder `qmk_firmware` as a subfolder of the current one.
+Once Git is installed, open the Git Bash command and change the directory to where you want to clone QMK; note that you have to use forward slashes, and that your c drive is accessed like this `/c/path/to/where/you/want/to/go`. Then run `git clone --recurse-submodules https://github.com/qmk/qmk_firmware`, this will create a new folder `qmk_firmware` as a subfolder of the current one.

 
 ### Toolchain setup
 The Toolchain setup is done through the Windows Subsystem for Linux, and the process is fully automated. If you want to do everything manually, there are no other instructions than the scripts themselves, but you can always open issues and ask for more information.
 
 ### Toolchain setup
 The Toolchain setup is done through the Windows Subsystem for Linux, and the process is fully automated. If you want to do everything manually, there are no other instructions than the scripts themselves, but you can always open issues and ask for more information.


@@ -122,8 +122,11 @@ If this is a bit complex for you, Docker might be the turn-key solution you need
 # defaults are ergodox/default
 
 docker run -e keymap=gwen -e keyboard=ergodox_ez --rm -v $('pwd'):/qmk:rw edasque/qmk_firmware
 # defaults are ergodox/default
 
 docker run -e keymap=gwen -e keyboard=ergodox_ez --rm -v $('pwd'):/qmk:rw edasque/qmk_firmware

+```
+
+On Windows Docker seems to have issues with the VOLUME tag in Dockerfile, and `$('pwd')` won't print a Windows compliant path; use full path instead, like this:

 
 

-# On windows docker seems to have issue with VOLUME tag in Dockerfile, and $('pwd') won't print a windows compliant path, use full path instead like this
+```bash

 docker run -e keymap=default -e keyboard=ergobox_ez --rm -v D:/Users/Sacapuces/Documents/Repositories/qmk:/qmk:rw edasque/qmk_firmware
 
 ```
 docker run -e keymap=default -e keyboard=ergobox_ez --rm -v D:/Users/Sacapuces/Documents/Repositories/qmk:/qmk:rw edasque/qmk_firmware
 
 ```


@@ -131,4 +134,4 @@ docker run -e keymap=default -e keyboard=ergobox_ez --rm -v D:/Users/Sacapuces/D
 This will compile the targeted keyboard/keymap and leave it in your QMK directory for you to flash.
 
 ## Vagrant
 This will compile the targeted keyboard/keymap and leave it in your QMK directory for you to flash.
 
 ## Vagrant

-If you have any problems building the firmware, you can try using a tool called Vagrant. It will set up a virtual computer with a known configuration that's ready-to-go for firmware building. OLKB does NOT host the files for this virtual computer. Details on how to set up Vagrant are in the [vagrant guide](vagrant_guide.md).
+If you have any problems building the firmware, you can try using a tool called Vagrant. It will set up a virtual computer with a known configuration that's ready-to-go for firmware building. OLKB does NOT host the files for this virtual computer. Details on how to set up Vagrant are in the [vagrant guide](getting_started_vagrant.md).

diff --git a/docs/getting_started_instroduction.md b/docs/getting_started_instroduction.md
deleted file mode 100644 (file)
index 3cd2750..0000000
--- a/docs/getting_started_instroduction.md
+++ /dev/null
@@ -1,47 +0,0 @@
-# Introduction
-
-This page attempts to explain the basic information you need to know to work with the QMK project. It assumes that you are familiar with navigating a UNIX shell, but does not assume you are familiar with C or with compiling using make.
-
-## Basic QMK structure
-
-QMK is a fork of @tmk's [tmk_keyboard](https://github.com/tmk/tmk_keyboard) project. The original TMK code, with modifications, can be found in the `tmk` folder. The QMK additions to the project may be found in the `quantum` folder. Keyboard projects may be found in the `handwired` and `keyboard` folders.
-
-### Keyboard project structure
-
-Within the `handwired` and `keyboard` folders is a directory for each keyboard project, for example `qmk_firmware/keyboards/clueboard`. Within you'll find the following structure:
-
-* `keymaps/`: Different keymaps that can be built
-* `rules.mk`: The file that sets the default "make" options. Do not edit this file directly, instead use a keymap specific `Makefile`.
-* `config.h`: The file that sets the default compile time options. Do not edit this file directly, instead use a keymap specific `config.h`.
-
-### Keymap structure
-
-In every keymap folder, the following files may be found. Only `keymap.c` is required, if the rest of the files are not found the default options will be chosen.
-
-* `config.h`: the options to configure your keymap
-* `keymap.c`: all of your keymap code, required
-* `rules.mk`: the features of QMK that are enabled
-* `readme.md`: a description of your keymap, how others might use it, and explanations of features. Please upload images to a service like imgur.
-
-# The `config.h` file
-
-There are 2 `config.h` locations:
-
-* keyboard (`/keyboards/<keyboard>/config.h`)
-* keymap (`/keyboards/<keyboard>/keymaps/<keymap>/config.h`)
-
-If the keymap `config.h` exists that file is included by the build system and the keyboard `config.h` is not included. If you wish to override settings in your keymap's `config.h` you will need to include some glue code:
-
-```
-#ifndef CONFIG_USER_H
-#define CONFIG_USER_H
-
-#include "../../config.h"
-```
-
-If you want to override a setting from the parent `config.h` file, you need to `#undef` and then `#define` the setting again, like this:
-
-```c
-#undef MY_SETTING
-#define MY_SETTING 4
-```

diff --git a/docs/getting_started_introduction.md b/docs/getting_started_introduction.md
new file mode 100644 (file)
index 0000000..3e9a8eb
--- /dev/null
+++ b/docs/getting_started_introduction.md
@@ -0,0 +1,47 @@
+# Introduction
+
+This page attempts to explain the basic information you need to know to work with the QMK project. It assumes that you are familiar with navigating a Unix shell, but does not assume you are familiar with C or with compiling using make.
+
+## Basic QMK structure
+
+QMK is a fork of [Jun Wako](https://github.com/tmk)'s [tmk_keyboard](https://github.com/tmk/tmk_keyboard) project. The original TMK code, with modifications, can be found in the `tmk` folder. The QMK additions to the project may be found in the `quantum` folder. Keyboard projects may be found in the `handwired` and `keyboard` folders.
+
+### Keyboard project structure
+
+Within the folder `keyboards` and its subfolder `handwired` is a directory for each keyboard project, for example `qmk_firmware/keyboards/clueboard`. Within it you'll find the following structure:
+
+* `keymaps/`: Different keymaps that can be built
+* `rules.mk`: The file that sets the default "make" options. Do not edit this file directly, instead use a keymap specific `Makefile`
+* `config.h`: The file that sets the default compile time options. Do not edit this file directly, instead use a keymap specific `config.h`.
+
+### Keymap structure
+
+In every keymap folder, the following files may be found. Only `keymap.c` is required, and if the rest of the files are not found the default options will be chosen.
+
+* `config.h`: the options to configure your keymap
+* `keymap.c`: all of your keymap code, required
+* `rules.mk`: the features of QMK that are enabled
+* `readme.md`: a description of your keymap, how others might use it, and explanations of features. Please upload images to a service like imgur.
+
+# The `config.h` file
+
+There are 2 `config.h` locations:
+
+* keyboard (`/keyboards/<keyboard>/config.h`)
+* keymap (`/keyboards/<keyboard>/keymaps/<keymap>/config.h`)
+
+If the keymap `config.h` exists, that file is included by the build system and the keyboard `config.h` is not included. If you wish to override settings in your keymap's `config.h` you will need to include some glue code:
+
+```
+#ifndef CONFIG_USER_H
+#define CONFIG_USER_H
+
+#include "../../config.h"
+```
+
+If you want to override a setting from the parent `config.h` file, you need to `#undef` and then `#define` the setting again, like this:
+
+```c
+#undef MY_SETTING
+#define MY_SETTING 4
+```

diff --git a/readme.md b/readme.md
index 74dd6e8a994bd8fa222b036827d592ed5281fce8..76acab52a0189bb90ef6dbd03c723876879006e6 100644 (file)
--- a/readme.md
+++ b/readme.md
@@ -29,4 +29,4 @@ QMK is developed and maintained by Jack Humbert of OLKB with contributions from
 
 ## Documentation
 
 
 ## Documentation
 

-[https://docs.qmk.fm](https://docs.qmk.fm) is hosted on [Gitbook](https://www.gitbook.com/book/qmk/firmware/details) and [Github](/docs/) (they are synced). You can request changes by making a fork and [pull request](https://github.com/qmk/qmk_firmware/pulls), or by clicking the "suggest an edit" link on any page of the Docs.
+[https://docs.qmk.fm](https://docs.qmk.fm) is hosted on [Gitbook](https://www.gitbook.com/book/qmk/firmware/details) and [GitHub](/docs/) (they are synced). You can request changes by making a fork and [pull request](https://github.com/qmk/qmk_firmware/pulls), or by clicking the "suggest an edit" link on any page of the Docs.