KE-complex_modifications : un dépôt partagé de règles pour Karabiner-Elements

Ce que contient ce dépôt

Le dépôt KE-complex_modifications est la source partagée des règles complex_modifications pour Karabiner-Elements. Le site de distribution ke-complex-modifications.pqrs.org héberge ces fichiers de règles. Chaque fichier JSON du dépôt regroupe plusieurs règles dans un seul fichier, afin que les utilisateurs puissent choisir et activer uniquement les remappages spécifiques dont ils ont besoin. Le README utilise le paquet de liaisons de touches Emacs comme exemple, qui contient plusieurs ensembles de règles pour différents cas d'utilisation.

Structure des fichiers JSON distribués

Chaque fichier JSON distribué possède un champ title, un tableau maintainers facultatif de noms d'utilisateur GitHub et un tableau rules. Chaque règle à l'intérieur a une description et un tableau manipulators. Le README montre un manipulateur de base avec des objets type, from et to. Lorsque des mainteneurs sont listés, le site de distribution crée automatiquement des liens vers ces comptes GitHub. Cette structure permet à un seul fichier de porter plusieurs règles indépendantes que les utilisateurs peuvent activer individuellement depuis Karabiner-Elements.

Ajouter un nouvel ensemble de règles

Pour ajouter des règles, un contributeur fork le dépôt, le clone avec les sous-modules, crée une branche, puis place soit un fichier générateur JavaScript dans src/json, soit un fichier JSON fini dans public/json. Optionnellement, public/groups.json peut être mis à jour pour placer les règles dans une catégorie, avec un extra_description_path pour le HTML supplémentaire. Après avoir exécuté make all, les éventuelles erreurs de validation apparaissent dans le terminal. Le contributeur commit, pousse et ouvre ensuite une demande de tirage.

Validation et tests

La commande make all valide le JSON et génère les fichiers de sortie à partir des scripts générateurs. Pour tester localement, un contributeur copie un fichier JSON généré vers ~/.config/karabiner/assets/complex_modifications et l'importe depuis les paramètres de Karabiner-Elements sous Complex Modifications > Rules > Add rule. Un serveur web local peut être démarré avec make preview-server, qui sert le site à http://localhost:8000 pour prévisualiser les descriptions et la mise en page des règles. Le README note que le rechargement à chaud automatique n'est pas pris en charge pour les modifications HTML.

Descriptions supplémentaires pour les ensembles de règles

Pour les règles nécessitant plus qu'une description sur une ligne, les contributeurs peuvent ajouter un fichier HTML sous public/extra_descriptions et le référencer depuis groups.json via un champ extra_description_path. Le HTML apparaît sur le site de distribution dans la liste des règles. Le README donne plusieurs conseils : le CSS Bootstrap est appliqué automatiquement, donc les classes utilitaires d'espacement fonctionnent ; ne pas inclure les balises html ou body ; les images peuvent être incluses avec des chemins relatifs et doivent être commitées dans le dépôt. Après modification, la page doit être rechargée manuellement.

Synchroniser un fork

Le README inclut une procédure de synchronisation pour les dépôts préalablement forkés. Une commande unique ajoute le remote upstream, puis une séquence répétée récupère toutes les balises, réinitialise la branche main locale sur upstream/main, met à jour les sous-modules, nettoie les fichiers non suivis et pousse la branche mise à jour vers le fork du contributeur. Cela maintient un fork aligné avec le dépôt d'origine sans fusion.

Contraintes des scripts générateurs et licence

Les scripts générateurs dans src/json s'exécutent sous Duktape, le moteur JavaScript intégré à l'outil en ligne de commande de Karabiner-Elements. L'environnement suit ES5.1, donc let, les fonctions fléchées, les paramètres par défaut, la syntaxe de propagation et les littéraux de modèle ne sont pas disponibles ; const est spécialement pris en charge. Le README signale plusieurs exemples de générateurs qui démontrent des motifs comme l'utilisation de listes d'identifiants de bundle prédéfinies, la génération de remappages à partir de listes de caractères, l'inclusion de fichiers depuis d'autres fichiers et la génération de règles à partir de combinaisons de touches. Le dépôt est publié sous l'Unlicense, le dédiant au domaine public, mais la licence ne fournit aucune garantie ni protection de responsabilité.

Vérifier KE-complex_modifications dans son contexte

Le README de ce projet doit être lu comme une description de son périmètre, non comme une garantie générale. Pour une première vérification, reprenez un exemple nommé dans le dépôt, exécutez la commande fournie et conservez la sortie obtenue. Comparez ensuite cette sortie avec le format attendu et relevez les paramètres que la documentation laisse ouverts. Cette démarche permet de séparer une capacité effectivement illustrée d’une hypothèse d’intégration. Les questions de sécurité, de support, de compatibilité et de performances restent limitées aux affirmations présentes dans les fichiers consultés. Un essai court, attaché au projet et à ses chemins de fichiers, donne ainsi une décision plus précise qu’une appréciation fondée sur le seul nombre d’étoiles.

Conclusion éditoriale

Ce projet s’adresse aux personnes dont le besoin correspond aux fichiers et commandes décrits pour KE-complex_modifications. Il convient moins à un usage qui exigerait des garanties absentes du README. Avant décision, reprenez un exemple du dépôt, exécutez la commande documentée et observez précisément sa sortie : Le README de ce projet doit être lu comme une description de son périmètre, non comme une garantie générale. Pour une première vérification, reprenez un exemple nommé dans le dépôt, exécutez la commande fournie et conservez la sortie obtenue. Comparez ensuite

Sources officielles

1. Official documentation
2. Official README
3. Project repository