Skip to content

Commit

Permalink
Improvements to documentation (qmk#1919)
Browse files Browse the repository at this point in the history 
* 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
  • Loading branch information
@arialdomartini @jackhumbert
arialdomartini authored and jackhumbert committed Nov 1, 2017
1 parent 1683d3a commit 32bb8f6
Show file tree
Hide file tree
Showing 4 changed files with 19 additions and 16 deletions.
2 changes: 1 addition & 1 deletion docs/faq_general.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@

## 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).

Expand Down
19 changes: 11 additions & 8 deletions docs/getting_started_build_tools.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# 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. -->

Expand Down Expand Up @@ -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

## Mac
## macOS
If you're using [homebrew,](http://brew.sh/) you can use the following commands:

brew tap osx-cross/avr
Expand All @@ -58,10 +58,10 @@ This is the recommended method. If you don't have homebrew, [install it!](http:/

## 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
Expand All @@ -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.

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.
Expand Down Expand Up @@ -122,13 +122,16 @@ 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
```

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

```

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).
12 changes: 6 additions & 6 deletions docs/getting_started_instroduction.md → docs/getting_started_introduction.md
View file
Original file line number Diff line number Diff line change
@@ -1,22 +1,22 @@
# 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.
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.
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 `handwired` and `keyboard` folders is a directory for each keyboard project, for example `qmk_firmware/keyboards/clueboard`. Within you'll find the following 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`.
* `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.
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
Expand All @@ -30,7 +30,7 @@ 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:
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
Expand Down
2 changes: 1 addition & 1 deletion readme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,4 +29,4 @@ QMK is developed and maintained by Jack Humbert of OLKB with contributions from

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

0 comments on commit 32bb8f6

Please sign in to comment.