Skip to content

Commit

Permalink
Convert all headings to Title Case
Browse files Browse the repository at this point in the history
  • Loading branch information
fauxpark authored and jackhumbert committed Dec 9, 2017
1 parent 6eb89ae commit 7b0356d
Show file tree
Hide file tree
Showing 49 changed files with 191 additions and 198 deletions.
6 changes: 3 additions & 3 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,13 @@

QMK (*Quantum Mechanical Keyboard*) is an open source community that maintains QMK Firmware, QMK Flasher, qmk.fm, and these docs. QMK Firmware is a keyboard firmware based on the [tmk\_keyboard](http://github.com/tmk/tmk_keyboard) with some useful features for Atmel AVR controllers, and more specifically, the [OLKB product line](http://olkb.com), the [ErgoDox EZ](http://www.ergodox-ez.com) keyboard, and the [Clueboard product line](http://clueboard.co/). It has also been ported to ARM chips using ChibiOS. You can use it to power your own hand-wired or custom keyboard PCB.

## How to get it {#how-to-get-it}
## How to Get It {#how-to-get-it}

If you plan on contributing a keymap, keyboard, or features to QMK, the easiest thing to do is [fork the repo through Github](https://github.com/qmk/qmk_firmware#fork-destination-box), and clone your repo locally to make your changes, push them, then open a [Pull Request](https://github.com/qmk/qmk_firmware/pulls) from your fork.

Otherwise, you can either download it directly ([zip](https://github.com/qmk/qmk_firmware/zipball/master), [tar](https://github.com/qmk/qmk_firmware/tarball/master)), or clone it via git (`[email protected]:qmk/qmk_firmware.git`), or https (`https://github.com/qmk/qmk_firmware.git`).

## How to compile {#how-to-compile}
## How to Compile {#how-to-compile}

Before you are able to compile, you'll need to [install an environment](getting_started_build_tools.md) for AVR or/and ARM development. Once that is complete, you'll use the `make` command to build a keyboard and keymap with the following notation:

Expand All @@ -20,6 +20,6 @@ This would build the `rev4` revision of the `planck` with the `default` keymap.

make preonic:default

## How to customize {#how-to-customize}
## How to Customize {#how-to-customize}

QMK has lots of [features](features.md) to explore, and a good deal of [reference documentation](http://docs.qmk.fm) to dig through. Most features are taken advantage of by modifying your [keymap](keymap.md), and changing the [keycodes](keycodes.md).
14 changes: 7 additions & 7 deletions docs/_summary.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
* [Getting started](README.md)
* [Getting Started](README.md)
* [QMK Introduction](getting_started_introduction.md)
* [Install Build Tools](getting_started_build_tools.md)
* Alternative: [Vagrant Guide](getting_started_vagrant.md)
* [Build/Compile instructions](getting_started_make_guide.md)
* [Flashing instructions](flashing.md)
* [Build/Compile Instructions](getting_started_make_guide.md)
* [Flashing Instructions](flashing.md)
* [Contributing to QMK](contributing.md)
* [How to Use Github](getting_started_github.md)

Expand Down Expand Up @@ -31,9 +31,9 @@
* [Layouts](feature_layouts.md)
* [Leader Key](feature_leader_key.md)
* [Macros](feature_macros.md)
* [Mouse keys](feature_mouse_keys.md)
* [Mouse Keys](feature_mouse_keys.md)
* [Pointing Device](feature_pointing_device.md)
* [PS2 Mouse](feature_ps2_mouse.md)
* [PS/2 Mouse](feature_ps2_mouse.md)
* [RGB Lighting](feature_rgblight.md)
* [Space Cadet](feature_space_cadet.md)
* [Stenography](feature_stenography.md)
Expand Down Expand Up @@ -65,12 +65,12 @@
* [Documentation Best Practices](documentation_best_practices.md)
* [Documentation Templates](documentation_templates.md)
* [Glossary](glossary.md)
* [Keymap overview](keymap.md)
* [Keymap Overview](keymap.md)
* [Unit Testing](unit_testing.md)

* For Makers and Modders
* [Hand Wiring Guide](hand_wire.md)
* [ISP flashing guide](isp_flashing_guide.md)
* [ISP Flashing Guide](isp_flashing_guide.md)

* For a Deeper Understanding
* [How Keyboards Work](how_keyboards_work.md)
Expand Down
2 changes: 1 addition & 1 deletion docs/becoming_a_qmk_collaborator.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,4 +4,4 @@ A QMK collaborator is a keyboard maker/designer that is interested in helping QM
* **Maintain the your keyboard's directory** - this may just require an initial setup to get your keyboard working, but it could also include accommodating changes made to QMK's core.
* **Approve and merge your keyboard's keymap pull requests** - we like to encourage users to contribute their keymaps for others to see and work from when creating their own.

If you feel you meet these requirements, shoot us an email at [email protected] with an introduction and some links to your keyboard!
If you feel you meet these requirements, shoot us an email at [email protected] with an introduction and some links to your keyboard!
2 changes: 1 addition & 1 deletion docs/compatible_microcontrollers.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,4 +22,4 @@ You can also use any ARM processor that [ChibiOS](http://www.chibios.org) suppor
* [Kinetis MKL26Z64](http://www.nxp.com/products/microcontrollers-and-processors/arm-processors/kinetis-cortex-m-mcus/l-series-ultra-low-power-m0-plus/kinetis-kl2x-48-mhz-usb-ultra-low-power-microcontrollers-mcus-based-on-arm-cortex-m0-plus-core:KL2x)
* [Kinetis MK20DX128](http://www.nxp.com/assets/documents/data/en/data-sheets/K20P64M50SF0.pdf)
* [Kinetis MK20DX128](http://www.nxp.com/assets/documents/data/en/data-sheets/K20P64M50SF0.pdf)
* [Kinetis MK20DX256](http://www.nxp.com/products/microcontrollers-and-processors/arm-processors/kinetis-cortex-m-mcus/k-series-performance-m4/k2x-usb/kinetis-k20-72-mhz-full-speed-usb-mixed-signal-integration-microcontrollers-mcus-based-on-arm-cortex-m4-core:K20_72)
* [Kinetis MK20DX256](http://www.nxp.com/products/microcontrollers-and-processors/arm-processors/kinetis-cortex-m-mcus/k-series-performance-m4/k2x-usb/kinetis-k20-72-mhz-full-speed-usb-mixed-signal-integration-microcontrollers-mcus-based-on-arm-cortex-m4-core:K20_72)
4 changes: 2 additions & 2 deletions docs/config_options.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ Some keyboards have folders and sub-folders to allow for different hardware conf

This level contains all of the options for that particular keymap. If you wish to override a previous declaration, you can use `#undef <variable>` to undefine it, where you can then redefine it without an error.

# The `config.h` file
# The `config.h` File

This is a C header file that is one of the first things included, and will persist over the whole project (if included). Lots of variables can be set here and accessed elsewhere. The `config.h` file shouldn't be including other `config.h` files, or anything besides this:

Expand Down Expand Up @@ -164,7 +164,7 @@ If you define these options you will enable the associated feature, which may in

This is a [make](https://www.gnu.org/software/make/manual/make.html) file that is included by the top-level `Makefile`. It is used to set some information about the MCU that we will be compiling for as well as enabling and disabling certain features.

## `rules.mk` options
## `rules.mk` Options

### Build Options

Expand Down
12 changes: 6 additions & 6 deletions docs/contributing.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# How To Contribute
# How to Contribute

👍🎉 First off, thanks for taking the time to read this and contribute! 🎉👍

Expand All @@ -9,7 +9,7 @@ Third-party contributions help us grow and improve QMK. We want to make the pull
* [General Guidelines](#general-guidelines)
* [What does the Code of Conduct mean for me?](#what-does-the-code-of-conduct-mean-for-me)

## I Don't Want To Read This Whole Thing I Just Have a Question!
## I Don't Want to Read This Whole Thing! I Just Have a Question!

If you'd like to ask questions about QMK you can do so on the [OLKB Subreddit](https://reddit.com/r/olkb) or on [Gitter](https://gitter.im/qmk/qmk_firmware).

Expand All @@ -27,7 +27,7 @@ QMK is largely written in C, with specific features and parts written in C++. It

<!-- FIXME: We should include a list of resources for learning C here. -->

# Where can I go for help?
# Where Can I Go for Help?

If you need help you can [open an issue](https://github.com/qmk/qmk_firmware/issues) or [chat on gitter](http://gitter.im/QMK/qmk_firmware).

Expand All @@ -52,7 +52,7 @@ Never made an open source contribution before? Wondering how contributions work
14. Make changes to the pull request if the reviewing maintainer recommends them.
15. Celebrate your success after your pull request is merged!

# Coding conventions
# Coding Conventions

Most of our style is pretty easy to pick up on, but right now it's not entirely consistent. You should match the style of the code surrounding your change, but if that code is inconsistent or unclear use the following guidelines:

Expand All @@ -64,7 +64,7 @@ Most of our style is pretty easy to pick up on, but right now it's not entirely
* Optional Braces: Always include optional braces.
* Good: if (condition) { return false; }
* Bad: if (condition) return false;
* We use C style comments: /* */
* We use C style comments: `/* */`
* Think of them as a story describing the feature
* Use them liberally to explain why particular decisions were made.
* Do not write obvious comments
Expand Down Expand Up @@ -147,6 +147,6 @@ We also ask that you follow these guidelines:

To maintain a clear vision of how things are laid out in QMK we try to plan out refactors in-depth and have a collaborator make the changes. If you have an idea for refactoring, or suggestions, [open an issue](https://github.com/qmk/qmk_firmware/issues), we'd love to talk about how QMK can be improved.

# What does the Code of Conduct mean for me?
# What Does the Code of Conduct Mean for Me?

Our [Code of Conduct](https://github.com/qmk/qmk_firmware/blob/master/CODE_OF_CONDUCT.md) means that you are responsible for treating everyone on the project with respect and courtesy regardless of their identity. If you are the victim of any inappropriate behavior or comments as described in our Code of Conduct, we are here for you and will do the best to ensure that the abuser is reprimanded appropriately, per our code.
20 changes: 10 additions & 10 deletions docs/custom_quantum_functions.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# How To Customize Your Keyboard's Behavior
# How to Customize Your Keyboard's Behavior

For a lot of people a custom keyboard is about more than sending button presses to your computer. You want to be able to do things that are more complex than simple button presses and macros. QMK has hooks that allow you to inject code, override functionality, and otherwise customize how your keyboard behaves in different situations.

Expand Down Expand Up @@ -34,13 +34,13 @@ enum my_keycodes {
};
```

## Programming The Behavior Of Any Keycode
## Programming the Behavior of Any Keycode

When you want to override the behavior of an existing key, or define the behavior for a new key, you should use the `process_record_kb()` and `process_record_user()` functions. These are called by QMK during key processing before the actual key event is handled. If these functions return `true` QMK will process the keycodes as usual. That can be handy for extending the functionality of a key rather than replacing it. If these functions return `false` QMK will skip the normal key handling, and it will be up you to send any key up or down events that are required.

These function are called every time a key is pressed or released.

### Example `process_record_user()` implementation
### Example `process_record_user()` Implementation

This example does two things. It defines the behavior for a custom keycode called `FOO`, and it supplements our Enter key by playing a tone whenever it is pressed.

Expand All @@ -64,7 +64,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) {
}
```

### `process_record_*` Function documentation
### `process_record_*` Function Documentation

* Keyboard/Revision: `bool process_record_kb(uint16_t keycode, keyrecord_t *record)`
* Keymap: `bool process_record_user(uint16_t keycode, keyrecord_t *record)`
Expand Down Expand Up @@ -96,7 +96,7 @@ This allows you to control the 5 LED's defined as part of the USB Keyboard spec.
* `USB_LED_COMPOSE`
* `USB_LED_KANA`

### Example `led_set_kb()` implementation
### Example `led_set_kb()` Implementation

```
void led_set_kb(uint8_t usb_led) {
Expand Down Expand Up @@ -128,7 +128,7 @@ void led_set_kb(uint8_t usb_led) {
}
```

### `led_set_*` Function documentation
### `led_set_*` Function Documentation

* Keyboard/Revision: `void led_set_kb(uint8_t usb_led)`
* Keymap: `void led_set_user(uint8_t usb_led)`
Expand All @@ -137,7 +137,7 @@ void led_set_kb(uint8_t usb_led) {

Before a keyboard can be used the hardware must be initialized. QMK handles initialization of the keyboard matrix itself, but if you have other hardware like LED's or i&#xb2;c controllers you will need to set up that hardware before it can be used.

### Example `matrix_init_kb()` implementation
### Example `matrix_init_kb()` Implementation

This example, at the keyboard level, sets up B1, B2, and B3 as LED pins.

Expand All @@ -153,7 +153,7 @@ void matrix_init_kb(void) {
}
```

### `matrix_init_*` Function documentation
### `matrix_init_*` Function Documentation

* Keyboard/Revision: `void matrix_init_kb(void)`
* Keymap: `void matrix_init_user(void)`
Expand All @@ -162,11 +162,11 @@ void matrix_init_kb(void) {

Whenever possible you should customize your keyboard by using `process_record_*()` and hooking into events that way, to ensure that your code does not have a negative performance impact on your keyboard. However, in rare cases it is necessary to hook into the matrix scanning. Be extremely careful with the performance of code in these functions, as it will be called at least 10 times per second.

### Example `matrix_scan_*` implementation
### Example `matrix_scan_*` Implementation

This example has been deliberately omitted. You should understand enough about QMK internals to write this without an example before hooking into such a performance sensitive area. If you need help please [open an issue](https://github.com/qmk/qmk_firmware/issues/new) or [chat with us on gitter](https://gitter.im/qmk/qmk_firmware).

### `matrix_scan_*` Function documentation
### `matrix_scan_*` Function Documentation

* Keyboard/Revision: `void matrix_scan_kb(void)`
* Keymap: `void matrix_scan_user(void)`
Expand Down
16 changes: 8 additions & 8 deletions docs/eclipse.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Setting Up Eclipse for QMK Development
# Setting up Eclipse for QMK Development

[Eclipse](https://en.wikipedia.org/wiki/Eclipse_(software)) is an open-source [Integrated Development Environment](https://en.wikipedia.org/wiki/Integrated_development_environment) (IDE) widely used for Java development, but with an extensible plugin system that allows to customize it for other languages and usages.

Expand All @@ -16,16 +16,16 @@ The purpose of the is page is to document how to set-up Eclipse for developing A
Note that this set-up has been tested on Ubuntu 16.04 only for the moment.

# Prerequisites
## Build environment
## Build Environment
Before starting, you must have followed the [Getting Started](home.md#getting-started) section corresponding to your system. In particular, you must have been able to build the firmware with [the `make` command](../#the-make-command).

## Java
Eclipse is a Java application, so you will need to install Java 8 or more recent to be able to run it. You may choose between the JRE or the JDK, the latter being useful if you intend to do Java development.

# Install Eclipse and its plugins
# Install Eclipse and Its Plugins
Eclipse comes in [several flavours](http://www.eclipse.org/downloads/eclipse-packages/) depending on the target usage that you will have. There is no package comprising the AVR stack, so we will need to start from Eclipse CDT (C/C++ Development Tooling) and install the necessary plugins.

## Download and install Eclipse CDT
## Download and Install Eclipse CDT
If you already have Eclipse CDT on your system, you can skip this step. However it is advised to keep it up-to-date for better support.

If you have another Eclipse package installed, it is normally possible to [install the CDT plugin over it](https://eclipse.org/cdt/downloads.php). However it is probably better to reinstall it from scratch to keep it light and avoid the clutter of tools that you don't need for the projects you will be working on.
Expand All @@ -41,10 +41,10 @@ When you are prompted with the Workspace Selector, select a directory that will

Once started, click the <kbd>Workbench</kbd> button at the top right to switch to the workbench view (there is a also checkbox at the bottom to skip the welcome screen at startup).

## Install the necessary plugins
## Install the Necessary Plugins
Note: you do not need to restart Eclipse after installing each plugin. Simply restart once all plugins are installed.

### [The AVR plugin](http://avr-eclipse.sourceforge.net/)
### [The AVR Plugin](http://avr-eclipse.sourceforge.net/)
This is the most important plugin as it will allow Eclipse to _understand_ AVR C code. Follow [the instructions for using the update site](http://avr-eclipse.sourceforge.net/wiki/index.php/Plugin_Download#Update_Site), and agree with the security warning for unsigned content.

### [ANSI Escape in Console](https://marketplace.eclipse.org/content/ansi-escape-console)
Expand All @@ -58,7 +58,7 @@ This plugin is necessary to properly display the colored build output generated
Once both plugins are installed, restart Eclipse as prompted.

# Configure Eclipse for QMK
## Importing the project
## Importing the Project
1. Click <kbd><kbd>File</kbd> > <kbd>New</kbd> > <kbd>Makefile Project with Existing Code</kbd></kbd>
2. On the next screen:
* Select the directory where you cloned the repository as _Existing Code Location_;
Expand All @@ -72,7 +72,7 @@ Once both plugins are installed, restart Eclipse as prompted.

¹ There might be issues for importing the project with a custom name. If it does not work properly, try leaving the default project name (i.e. the name of the directory, probably `qmk_firmware`).

## Build your keyboard
## Build Your Keyboard
We will now configure a make target that cleans the project and builds the keymap of your choice.

1. On the right side of the screen, select the <kbd>Make Target</kbd> tab
Expand Down
10 changes: 5 additions & 5 deletions docs/faq_build.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

This page covers questions about building QMK. If you have not yet you should read the [Build Environment Setup](getting_started_build_tools.md) and [Make Instructions](getting_started_make_guide.md) guides.

## Can't program on Linux
## Can't Program on Linux
You will need proper permission to operate a device. For Linux users see udev rules below. Easy way is to use `sudo` command, if you are not familiar with this command check its manual with `man sudo` or this page on line.

In short when your controller is ATMega32u4,
Expand All @@ -17,7 +17,7 @@ or just

But to run `make` with root privilege is not good idea. Use former method if possible.

## WINAVR is obsolete
## WINAVR is Obsolete
It is no longer recommended and may cause some problem.
See [TMK Issue #99](https://github.com/tmk/tmk_keyboard/issues/99).

Expand All @@ -33,7 +33,7 @@ You can buy a really unique VID:PID here. I don't think you need this for person
- http://www.obdev.at/products/vusb/license.html
- http://www.mcselec.com/index.php?page=shop.product_details&flypage=shop.flypage&product_id=92&option=com_phpshop&Itemid=1

## Linux udev rules
## Linux `udev` Rules
On Linux you need proper privilege to access device file of MCU, you'll have to use `sudo` when flashing firmware. You can circumvent this with placing these files in `/etc/udev/rules.d/`.

**/etc/udev/rules.d/50-atmel-dfu.rules:**
Expand All @@ -53,7 +53,7 @@ SUBSYSTEMS=="usb", ATTRS{idVendor}=="feed", MODE:="0666"
```


## Cortex: cstddef: No such file or directory
## Cortex: `cstddef: No such file or directory`
GCC 4.8 of Ubuntu 14.04 had this problem and had to update to 4.9 with this PPA.
https://launchpad.net/~terry.guo/+archive/ubuntu/gcc-arm-embedded

Expand All @@ -62,7 +62,7 @@ https://github.com/tmk/tmk_keyboard/wiki/mbed-cortex-porting#compile-error-cstdd
https://developer.mbed.org/forum/mbed/topic/5205/


## `clock_prescale_set` and `clock_div_1` not available
## `clock_prescale_set` and `clock_div_1` Not Available
Your toolchain is too old to support the MCU. For example WinAVR 20100110 doesn't support ATMega32u2.

```
Expand Down
Loading

0 comments on commit 7b0356d

Please sign in to comment.