Browse Source

Update feature_layouts.md

- intro example added
- Wording changed in sections to be less ambiguous or difficult for translators
- enforced use of document specific terminology
pull/23383/head
Duncan Sutherland 2 weeks ago
committed by GitHub
parent
commit
d8eb27c84a
No known key found for this signature in database GPG Key ID: B5690EEEBB952194
1 changed files with 30 additions and 25 deletions
  1. +30
    -25
      docs/feature_layouts.md

+ 30
- 25
docs/feature_layouts.md View File

@ -1,27 +1,32 @@
# Community Layouts
This feature allows a keymap to be defined outside of the `keyboards/` directory, that can be compiled for keyboards with a common, community-established physical layout; [Miryoku](https://github.com/manna-harbour/miryoku) functional layout being a prominent utiliser of this feature.
This feature allows a keymap to be defined outside of the `keyboards/` directory, that can be compiled for keyboards with a common, community-established physical layout.
This feature also functions with the [Userspace](./feature_userspace.md) feature.
Example: You have a QMK powered, TKL ANSI physical layout keyboard with a keymap configured to your new experimental functional layout. Your friend/"partner in keyboard layout crime" also has a QMK powered, TKL ANSI physical layout keyboard but it's a different model to yours and therefore it would require your friend to redefine your keymap exclusively for their keyboard.
In this example, although the keyboards both have an identical physical layout, this same keymap has been defined twice; once for each keyboard. By placing this experimental keymap under the respective `tkl_ansi` Community Layout directory, the keymap in question has been defined once and then can be compiled for every QMK compatible keyboard with `tkl_ansi` Community Layout support.
[Miryoku](https://github.com/manna-harbour/miryoku) functional layout is a prominent utiliser of this feature.
?> Community Layouts also function in conjunction with the [Userspace](./feature_userspace.md) feature.
## Directory Structure
The `layouts/` directory acts as the "master" directory for this feature.
The `layouts/default/` and `layouts/community/` sub-directories are two examples of Community Layout "repositories":
- `default/` contains all information regarding each Community Layout, which includes a default keymap named `default_<community_layout>`, for use as reference.
- `community/` is where local (to GitHub Repo) keymaps and community/user shared keymaps (e.g. Miryoku) for each Community Layout are located.
- `default/` contains all information regarding each Community Layout, which includes a default keymap named `default_<community_layout>`, and is used for reference.
- `community/` is where local (GitHub Repository) keymaps and community/user shared keymaps (e.g. Miryoku) for each Community Layout are located.
QMK searches through all sub-directories in `layouts/`, so it's possible to have multiple repositories.
To assist explanation, terms encapsulated in angled brackets are used throughout this page.
```
layouts
├── default
│ └── <community_layout>
│ └── <community_layout_keymap>
layouts/
├── default/
│ └── <community_layout>/
│ └── <community_layout_keymap>/
│ └── keymap.c
└── community
└── <community_layout>
└── <community_layout_keymap>
└── community/
└── <community_layout>/
└── <community_layout_keymap>/
└── keymap.c
```
**<community_layout>**: As well as sub-directory name, this serves as Community Layout name
@ -33,11 +38,11 @@ For a keyboard to support one or more Community Layouts, the keyboard's `info.js
1. A `"community_layouts"` array containing the name(s) of the respective Community Layout(s) the keyboard in question supports. Name(s) must be identical to *<community_layout>*.
#### `layouts/` directory example:
```
layouts
└── default
├── 60_ansi
layouts/
└── default/
├── 60_ansi/
│ └── <...>
└── 60_iso
└── 60_iso/
└── <...>
```
#### keyboard's `info.json`/`keyboard.json`:
@ -87,10 +92,10 @@ Examples:
qmk compile -kb dz60 -km default_60_iso
### Conflicting Keymaps
When compiling a Community Layout keymap that has the same name for two or more Community Layouts the target keyboard supports, this can result in the undesired Community Layout keymap being compiled.
When compiling a <community_layout_keymap> that has the same name in two or more <community_layouts> the target keyboard supports, this can result in the undesired keymap being compiled.
#### Example Scenario:
Using the `contra` keyboard in this scenario as it supports the `ortho_4x12` and `planck_mit` Community Layouts.
Using the `contra` keyboard in this scenario, as it supports `ortho_4x12` and `planck_mit` Community Layouts.
**keyboard's `info.json`/`keyboard.json`**
```json
@ -99,18 +104,18 @@ Using the `contra` keyboard in this scenario as it supports the `ortho_4x12` and
**layouts/ directory example**
```
layouts
└── community
├── ortho_4x12
│ └── jondough
layouts/
└── community/
├── ortho_4x12/
│ └── jondough/
│ └── keymap.c
└── planck_mit
└── jondough
└── planck_mit/
└── jondough/
└── keymap.c
```
Running `qmk compile -kb contra -km jondough` without additional context can't determine which `jondough` keymap from which Community Layout is being specified for compilation.
Running `qmk compile -kb contra -km jondough` without additional context doesn't determine which `jondough` keymap is being specified for compilation.
In this scenario the `FORCE_LAYOUT` argument is included, to specify from which Community Layout the specified keymap is located:
In this scenario the `FORCE_LAYOUT` argument is included, to specify from which <community_layout> the specified keymap is used:
qmk compile -kb <keyboard> -km <community_layout_keymap> -e FORCE_LAYOUT=<community_layout>


Loading…
Cancel
Save