diff --git a/README.md b/README.md index 6cb1561..fcab10c 100644 --- a/README.md +++ b/README.md @@ -1,101 +1,118 @@ # EurKEY-macOS -The Keyboard Layout for Europeans, Coders and Translators. This repo is a fork and contains a **modified verison** of the EurKEY base layout. It builds on the official layout. You can find version 1.3, the latest official release, in the bundle as well. See the changelog below for my modifications. +The keyboard layout for Europeans, coders, and translators. This repo contains a **modified version** of the EurKEY base layout for macOS, bundling multiple versions so users can pick what they need. -EurKEY-macOS is a rework targeted at MacBooks with the with pyhiscal English International keyboard (ISO) instead of the ANSI layout from the official upstream. Since it is an ISO layout, it has one additional key (`) and the big Enter key. +EurKEY-macOS targets MacBooks with the physical English International keyboard (ISO) instead of the ANSI layout from the official upstream. Since it is an ISO layout, it has one additional key (`` ` ``) and the big Enter key. -The keyboard layout should be compatible with the other ISO layouts typically available in Europe (e.g. German ISO). However, the printed keys will obviously be different. I tested the layout on the current tenkeyless MacBook keyboard (MacBook Air 2024). Working numpad keys are therefore not guaranteed. +The keyboard layout should be compatible with the other ISO layouts typically available in Europe (e.g., German ISO). However, the printed keys will obviously be different. I tested the layout on the current tenkeyless MacBook keyboard (MacBook Air 2024). Working numpad keys are therefore not guaranteed. + +## Versions + +The bundle ships 4 layout versions: + +| Version | Description | +| ------- | ----------- | +| **v1.3** | Official EurKEY spec implementation. **Recommended for most users.** | +| **v1.2** | Legacy version based on [Leonardo Schenkel's port](https://github.com/lbschenkel/EurKEY-Mac). Predates the v1.3 spec (no `¬` dead key, `§` instead of `ẞ` on Shift+Option+S). | +| **v1.4** | v1.3 with `ẞ` (capital sharp s) on Caps+`§` key. | +| **v2.0** | Custom edition — complete rework. Every key configures exactly as printed on the MacBook keyboard. Removes left/right modifier key distinction. New monochrome template icon. | ## Installation -- Download the `EurKEY.bundle` file. -- Copy the `EurKEY.bundle` file to `/Library/Keyboard Layouts/` (for global installation) or `~/Library/Keyboard Layouts/` (for user installation). -- Open System Settings > Keyboard > Input Sources
A screenshot showing the system preferences and where to find the edit button for the input sources. -- Click the `+` button
A screenshot showing how to open the dialogue to add a new input source. -- Add `EurKEY` from the list of available input sources
A screenshot showing where EurKEY is located in the input sources list. -- Select `EurKEY` as the input method
A screenshot showing the dropdown menu in the menu bar extra. +### From DMG (recommended) + +1. Download the latest `EurKEY-macOS-YYYY.MM.DD.dmg` from [Releases](https://github.com/felixfoertsch/EurKEY-macOS/releases). +2. Open the DMG. +3. Drag `EurKey-macOS.bundle` to the `Install Here (Keyboard Layouts)` folder. +4. Log out and back in (or restart). +5. System Settings → Keyboard → Input Sources → click `+` → select the EurKEY version you want. + +### Manual + +1. Download or clone this repo. +2. Copy `EurKey-macOS.bundle` to `/Library/Keyboard Layouts/` (system-wide) or `~/Library/Keyboard Layouts/` (user-only). +3. Log out and back in. +4. System Settings → Keyboard → Input Sources → click `+` → select EurKEY. + +System preferences showing the edit button for input sources. +Dialogue to add a new input source. +EurKEY in the input sources list. +Selecting EurKEY from the menu bar dropdown. + +## Validation + +The project includes automated validation to catch regressions. The validation script parses each `.keylayout` XML file and compares key mappings and dead key compositions against the v1.3 reference. + +```bash +# validate all layouts +python3 scripts/validate_layouts.py + +# parse a single layout to JSON +python3 scripts/parse_keylayout.py "EurKey-macOS.bundle/Contents/Resources/EurKEY v1.3.keylayout" --summary + +# build the bundle (validates + generates Info.plist) +bash scripts/build-bundle.sh + +# create a DMG installer +bash scripts/create-dmg.sh +``` + +## Dead key compositions (v2.0) + +v2.0 renames all dead key states to their initializing key combination: + +| Key combination | Dead key symbol | +| --------------- | --------------- | +| ⌥`` ` `` | `` ` `` | +| ⌥⇧`` ` `` | ~ | +| ⌥' | ´ | +| ⌥⇧' | ¨ | +| ⌥6 | ^ | +| ⌥⇧6 | ˇ | +| ⌥7 | ˚ | +| ⌥⇧7 | ¯ | +| ⌥m | Ω | +| ⌥⇧m | √ | +| ⌥\ | ¬ | ## Notes on Ukelele and template icons -I have tried to configure a template icon for the bundle and stumbled onto behaviour that I consider a bug in Ukelele. Template icons are the new style of icons that switch color depending on the system theme. - -I tried simply setting a template icon from the GUI using the checkbox, but it never saved it correctly. I had to manually edit `*.bundle/Info.plist` file and set the flag. - -The structure of the Info.plist file is as follows: +Template icons switch color with the system theme (dark/light). Ukelele's GUI checkbox for template icons does not save correctly — the `TISIconIsTemplate` flag must be set manually in `Info.plist`: ```xml - - - - - CFBundleIdentifier - de.felixfoertsch.keyboardlayout.EurKEY-macOS - → Bundle Identifier - - CFBundleName - EurKEY-macOS - → Filename of the *.bundle file - - CFBundleVersion - - KLInfo_EurKEY v2.0 - → Name of the keyboard layout in the collection list - - - TICapsLockLanguageSwitchCapable - - TISIconIsTemplate - - → Set to true to use the icon as a template - - TISInputSourceID - de.felixfoertsch.keyboardlayout.EurKEY-macOS.eurkeyv2.0 - → Identifier for the layout within the bundle, spaces are simply removed from the name. - → The syntax is: reverse-prefix-notation.BundleIdentifier.LayoutName - - TISIntendedLanguage - en - - - +TISIconIsTemplate + ``` +The build script (`scripts/build-bundle.sh`) generates `Info.plist` with this flag set correctly for all layout versions. + ## Changelog ### v2.0 (WIP) -- Configures every key exactly as it is printed on the MacBook keyboard (ISO, English - International). -- Removes distiction between left/right modifier keys. +- Configures every key exactly as it is printed on the MacBook keyboard (ISO, English International). +- Removes distinction between left/right modifier keys. - Uses the `*.bundle` format to group the layout versions. - Adds new monochrome macOS template icon that switches color with the system theme. -- Renames all dead key states to their initializing key combination for easier identifcation. The following table shows the mappings: - | Key Combinations | Dead Key Symbol | - | ---------------- | --------------- | - | ⌥`|` | - | ⌥⇧` | ~ | - | ⌥' | ´ | - | ⌥⇧' | ¨ | - | ⌥6 | ^ | - | ⌥⇧6 | ˇ | - | ⌥7 | ˚ | - | ⌥⇧7 | ¯ | - | ⌥m | Ω | - | ⌥⇧m | √ | - | ⌥\ | ¬ | +- Renames all dead key states to their initializing key combination for easier identification. ### v1.4 -- Switches behaviour of superscript and subscript numbers: The subscript numbers are the default; the superscript numbers are available via `⌥⇧`. +- Adds `ẞ` (capital sharp s) on Caps+`§` key. ### v1.3 -- Implements the layout according to [spec](https://eurkey.steffen.bruentjen.eu/changelog.html). The layout is based on [Leonardo Schenkel's version 1.2](https://github.com/lbschenkel/EurKEY-Mac). +- Implements the layout according to [spec](https://eurkey.steffen.bruentjen.eu/changelog.html). Based on [Leonardo Schenkel's version 1.2](https://github.com/lbschenkel/EurKEY-Mac). + +### v1.2 + +- Original macOS port by [Leonardo Brondani Schenkel](https://github.com/lbschenkel/EurKEY-Mac). ## Attribution -You can find the original EurKEY layout on [Steffen Brüntjens Website](https://eurkey.steffen.bruentjen.eu/start.html). My modified versions are originally based on the work of [Leonardo Brondani Schenkel](https://github.com/lbschenkel/EurKEY-Mac). +The original EurKEY layout is by [Steffen Brüntjen](https://eurkey.steffen.bruentjen.eu/start.html). The macOS port is originally based on the work of [Leonardo Brondani Schenkel](https://github.com/lbschenkel/EurKEY-Mac). ## License -- The EurKEY Layout is licensed under [GPLv3](http://www.gnu.org/licenses/gpl-3.0.html). See: [https://eurkey.steffen.bruentjen.eu/license.html](https://eurkey.steffen.bruentjen.eu/license.html). -- The EU flag icon is taken from [Iconspedia](http://www.iconspedia.com/pack/european-flags-1631/), created by [Alpak](http://alpak.deviantart.com/) and licensed under [CC](http://creativecommons.org/licenses/by-nc-nd/3.0). +- The EurKEY Layout is licensed under [GPLv3](http://www.gnu.org/licenses/gpl-3.0.html). See: [eurkey.steffen.bruentjen.eu/license.html](https://eurkey.steffen.bruentjen.eu/license.html). +- The EU flag icon is from [Iconspedia](http://www.iconspedia.com/pack/european-flags-1631/), created by [Alpak](http://alpak.deviantart.com/) and licensed under [CC BY-NC-ND 3.0](http://creativecommons.org/licenses/by-nc-nd/3.0).