From e3bcc990be8fe31a1ed84243819e087df65f7628 Mon Sep 17 00:00:00 2001
From: "Steven R. Loomis" <srl295@gmail.com>
Date: Sat, 30 Aug 2025 18:36:52 -0500
Subject: [PATCH] feat: glossary entries for ldml

- entries for planning

For: #13836
---
 developer/ldml/guide/glossary.md | 43 +++++++++++++++++++++++++++++++-
 developer/ldml/guide/planning.md | 21 +++++++++++++---
 2 files changed, 59 insertions(+), 5 deletions(-)

diff --git a/developer/ldml/guide/glossary.md b/developer/ldml/guide/glossary.md
index bc417835a..5ced9a23f 100644
--- a/developer/ldml/guide/glossary.md
+++ b/developer/ldml/guide/glossary.md
@@ -20,4 +20,45 @@ places in Keyman Developer:
 More information about BCP 47 language tag and full details on [how they are
 used in Keyman Developer](../../current-version/reference/bcp-47).
 
-Now, go on to begin [planning](./planning) your LDML keyboard.
+## G {#g-glossary}
+
+### Gestures
+
+On a [touch keyboard](#touch-keyboard), a gesture refers to an action other than
+a simple touch/tap on the key.  Gestures are used to access features of the
+keyboard which may be less commonly used, but to save space by not requiring a
+additional key.  For example, a long press on the `e` key might result in being
+able to choose accented letters such as `é` and others without needing to have
+both an `e` and an `é` key in the same layer.
+
+The gestures supported by LDML are:
+
+* Flicks: where the finger slides off of the key in a particular direction.
+
+* Multitap: where the key is tapped multiple times in rapid succession.
+    Sometimes known as a **rota**.
+
+* Long press: where the key is held down for a period of time, producing a
+    pop-up menu of additional choices.
+
+## H {#h-glossary}
+
+### Hardware keyboard
+
+A hardware keyboard refers to the assignment of a particular physical
+arrangement of keys. Basic assignments of key function are based on which
+modifiers are held down at the same time as a key is pressed. For an LDML
+keyboard, more complicated multi-key sequences are accomplished using
+[transforms](./transforms).
+
+Compare to [touch keyboard](#touch-keyboard)
+
+## T {#t-glossary}
+
+### Touch keyboard
+
+A touch keyboard is one that is meant to be shown on screen, activated by finger
+touch or other gestures.  It can have multiple layers, switchable by choosing
+other keys.  For example, there may be a key which switches to a layer
+containing numbers, or a key which switches to a layer containing uppercase
+letters.
diff --git a/developer/ldml/guide/planning.md b/developer/ldml/guide/planning.md
index e50e3ebcb..b512b6be4 100644
--- a/developer/ldml/guide/planning.md
+++ b/developer/ldml/guide/planning.md
@@ -20,14 +20,23 @@ To aid you in the planning, here are a series of questions that can be asked:
 
 ### Form and Function
 
-- Will this be a hardware-only or touch-only keyboard? (It is recommended to
-work on the hardware format first, as a hardware keyboard can be used in touch
-but not vice versa.)
+- Will this be a touch-only keyboard, or one usable via either a hardware
+  keyboard or used as a touch keyboard?
+
+    A [hardware keyboard] refers to the assignment of a particular physical
+    arrangement of keys.
+
+    A [touch keyboard] refers to a keyboard arrangement meant to be shown on
+    screen, activated by finger touch or other [gestures].
+
+    It is recommended to work on the hardware format first, as a hardware
+    keyboard layout can be used as a touch keyboard, but not vice versa.
+
 - What is the base physical type for hardware, such as US or ISO?
 - Does the keyboard follow an existing organization of keys, such as QWERTY,
   AZERTY, QWERTZ etc?
 - Which width(s) will you start with for the touch layout?
-- What gestures will you make use of, such as long press, flicks, and multitap?
+- What [gestures] will you make use of, such as long press, flicks, and multitap?
 
 ### Repertoire
 
@@ -40,3 +49,7 @@ but not vice versa.)
   reached via a gesture or multiple key combination.
 
 Next, let's take a look at an [overview](./overview) of the LDML format.
+
+[hardware keyboard]: ./glossary#hardware-keyboard
+[touch keyboard]: ./glossary#touch-keyboard
+[gestures]: ./glossary#gestures