feat: ldml-docs update guide ✍️

developer/ldml/guide/choosing-locale.md

@@ -0,0 +1,14 @@
+---
+title: Choosing a locale
+---
+
+As part of your keyboard development, you must choose one or more [BCP 47] locale codes to
+associate with the keyboard.
+
+The primary locale id is stored in the `locale` attribute of the [`keyboard3`][keyboard3]
+(outer) element, while any additional locale ids are stored in the optional [`locales`][locales]
+element.
+
+[BCP 47]: ../../current-version/reference/bcp-47
+[keyboard3]: ../reference/keyboard3
+[locales]: ../reference/locales

developer/ldml/guide/displays.md

@@ -0,0 +1,50 @@
+---
+title: Customizing Keytop Displays
+---
+
+## Why customize the display
+
+Normally, the display of a keytop, whether in a touch enironment or the on-screen display of a hardware keyboard, simply matches the characrer output.  So, a key that outputs `a` will have a keytop that looks like `a`.
+
+However, there are some situations where it is desireable to customize the display of a key. This is where the [display] element is useful.  This is an optional element.
+
+Some situations where you might want to customize the display are as follows.  This isn't an exhaustive list and there may be more situations where the display feature is useful.
+
+- Invisible characters: A key may output invisible text of some sort, such as a space, control, or a keyboard [marker](./markers.md).  Such keys can have a customized keycap that displays something helpful for the users. For example, `sp` for a space key.
+
+- Switch keys: A key which switches layers, such as one that changes to a shift or alternate layer.
+
+- Visible characters with challenging display:  doubled combining marks or combining marks without a base character might need special handling, such as choosing a different base character. A combining circumflex U+0302 could be represented by a caret `^` or perhaps by use of U+25CC followed by the combining character: `◌̂`
+
+## Example displays element
+
+```xml
+<displays>
+    <!-- show the key which outputs a no-break space as 'NBSP' -->
+    <display output="\u{00A0}" display="NBSP" />
+    <!-- show the marker 'grave' as a backquote -->
+    <display output="\m{grave}" display="`" />
+    <!-- show the key named 'switch-numbers' as '123' -->
+    <display keyId="switch-numbers" display="123" />
+</displays>
+```
+
+## displayOptions
+
+The `displayOptions` has a single configurable option at present, the baseCharacter.
+
+In Lao for example, it's sometimes preferred to use `x` as the base for showing combining marks, rather than the dotted circle ◌.
+
+This is a hint for platforms to suggest using an alternative character. It doesn't require any specific behavior.
+
+```xml
+<displays>
+    <!-- other 'display' elements-->
+    <displayOptions baseCharacter="x"/>
+</displays>
+```
+
+
+With the key display customized, it's time now to arrange the keys into [layers](./layers).
+
+[display]: ../reference/display

developer/ldml/guide/glossary.md

@@ -16,3 +16,4 @@ There are many possible subtags, but only three types are currently used in most
 
 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.

developer/ldml/guide/index.md

@@ -2,7 +2,26 @@
 title: LDML Guide
 ---
 
-## Language elements
+This guide will take you through the concepts, planning process, and structure needed to successfully author an LDML Keyboard used with Keyman.
+
+Start with the [glossary](./glossary) and read these in order, or skip around as suits your interest. The [reference](../reference/) is useful for details of a particular XML Element.
+
+## Getting Started
 
-* [LDML Language Overview](overview)
 * [Glossary](glossary)
+* [Planning](planning) your Keyboard
+
+## Jumping in
+
+* [Overview](overview) of the LDML format
+* The [Keybag](keybag)
+* Customizing key [Displays](displays)
+* Defining [Layers](layers)
+
+## Going further
+
+* Settings, Options
+* [Variables](variables)
+* [Transforms](transforms)
+* [Markers](markers)
+* [Reorders](reorders)

developer/ldml/guide/keybag.md

@@ -0,0 +1,95 @@
+---
+title: The Keybag
+---
+
+The first major part of authoring your keyboard consists in setting up the keybag.
+
+## What's in the Keybag?
+
+You can think of the keybag as if it were a literal "bag of keys" from which you can bring out a key and place it into the right spot in your layout.
+
+The keybag is not one-for-one with the [repertoire], due to the following reasons:
+
+- There may be text which is of the repertoire which are not typed by the user directly at all, but are accessed via transforms. For example, suppose `œ` were part of the repertoire, but accessed by the user by typing `o` + `e`. There might not be an `œ` key, though it is in the repertoire.
+
+- There may also be more than one key which produces the same output, but has a distinct identity as a key. For example, there might be a key producing `a` which is used on a hardware layer, but also another key also producing `a` on one of the touch layers which has gestures attached to it such as a long press yielding `à`, `á`, `â` etc.  The two `a` keys have diferent identities (`id=` attribute) and differ in other properties.
+
+- Rarer, but it may be possible that a key producing the same output intentionally has a different keycap display in two different contexts. Keys are identified by a unique identifier, so unique keys can have unique key [displays].
+
+## Defining keys in the Keybag
+
+Keys are defined by the [key] element within the [keys] element, as seen in a simple example:
+
+```xml
+<keys>
+    <key id="A" output="A" />
+    <key id="B" output="B" />
+    <key id="uppercase-c" output="C" />
+    <key id="lambda" output="λ" />
+    <key id="ক" output="ক" />
+</keys>
+```
+
+Note that the identifier doesn't have to be plain ASCII, as in the last key.
+
+In the following sections we will discuss more advanced uses of keys.
+
+## Switch Keys
+
+A key within a touch layout can switch to a different [layer](./layers) by use of the `layerId` attribute, which names another layer. For example, this key switches to the "numbers" layer:
+
+```xml
+<key id="switch-numbers" layerId="numbers" />
+```
+
+Such a key would otherwise have a blank keycap (because it doesn't produce any output), so it is recommended to use a [`display`](./displays) element to give it an identifiable appearance.
+
+## Key Geometry
+
+### Width
+
+Keys are normally the same width (width="1" or width="1.0"). In some cases, a key is given a larger width for layout reasons.
+The Khmer letter naa "ណ" is a little wider, so the key could be made wider to match. Widths are in tenths of a key width.
+
+```xml
+    <key id="naa" width="1.8" output="ណ" />
+```
+
+### Gap
+
+Sometimes on a key layout, it's useful to have a space where there aren't any keys.
+This can be used with the layout to represent, for example, a place where one layer has a key but another doesn't.
+
+There's a pre-defined key named `gap` that has the gap attribute set. It's possible to add
+additional gap keys if desired. The following defines `gap` as its normal definition, and then defines a 3-key wide gap.
+
+```xml
+<key id="gap" gap="true" /> <!-- This is implied, but we can define it explicitly.-->
+<key id="widegap" gap="true" width="3" />
+```
+
+### Stretch
+
+The stretch attribute defines a key that expands to fill all available horizontal space.
+This is used with the spacebar.
+
+```xml
+<key id="space" output=" " stretch="true" />
+```
+
+## Marker key
+
+Markers are discussed in more detail [markers](./markers) and [transforms](./transforms).
+For this discussion, it's used with a key that doesn't generate any actual output, but represents an invisible
+non-text data item that is used for later processing.
+
+```xml
+<key id="accent-grave" output="\m{grave}" />
+```
+
+The marker's id here is `grave`.
+
+Next, we will learn about customizing key [displays].
+
+[repertoire]: ./planning#repertoire
+[displays]: ./displays

developer/ldml/guide/layers.md

@@ -0,0 +1,68 @@
+---
+title: Defining Layers
+---
+
+A layer defines are how keys are arranged for display and use.
+For hardware layouts, a layer determines which hardware key connects to which key from the keybag.
+For touch layouts, or hardware keyboards in an on-screen visual presentation, the layer controls how the keys are displayed on the screen for interaction with the finger or mouse.
+
+## Layer Groups (`layers`)
+
+A layer group or [`layers`](../reference/layers) element occurs one or more times in the keyboard file.
+There may be at most one layer group for the hardware keyboard, and then one or more layer group for different widths (sizes) of touch layouts, such as for a phone versus a tablet.  As noted, a hardware layout can be used for on-screen/touch, but a touch layout cannot be used for hardware, so we recommend starting with a hardware layout.
+
+### Hardware Layer Groups
+
+The hardware layer group has a `formId=` attribute referencing the physical layout of the keys, such as `iso` or `us` for the European 102 key layout (with a key between the shift and Z key) and the US 101 key layout (with no key between the shift and Z) respectively.  Other layouts supported include `abnt2`, `jis`, and `ks`.
+
+### Touch Layer Groups
+
+Touch layer groups always have the attribute `formId="touch"`, and are distinguished from each other by the `minDeviceWidth=` attribute, which specifies a minimum width, in millimeters, that the layout group must have.
+
+## Defining a Layer
+
+Now we come to discuss the actual [`layer`](../reference/layer) element.
+
+### Layer ID
+
+The ID is required for touch layers, but is optional for hardware layers. The layer with the ID of `base` is the starting layer.
+
+Keys can switch layers by referencing this layer in their `layerId` attribute.
+
+### Modifiers
+
+The modifiers are required for hardware layers, but are optional for touch layers.
+
+Each layer has a set of modifiers defined. For hardware keyboards, this specifies which layer will be selected based on the modifiers held down. `none` is used for the layer with no modifiers.
+
+For example, `modifiers="none"` or `modifiers="shift"`.  See [`layer`](../reference/layer) for further details.
+
+### Rows
+
+Each layer contains one or more [`row`](../reference/row) elements, in order from top to bottom.
+
+For example, most hardware keyboards have five rows including the space bar.
+Note that for hardware layouts, only the "alphanumeric" keys, that is, the keys which produce a character or space, are included.  Shift, Control, and any other device-specific hardware keys are not included.
+
+For touch keyboards, the number of rows is completely up to the keyboard author. Different layers or layer groups do not have to have the same number of rows.
+
+The `keys` attribute of each `row` is a space-separated list of key IDs.
+
+Example:
+
+```xml
+<layer modifiers="none">
+    <row keys="c-tikka 1 2 3 4 5 6 7 8 9 0 hyphen equal" />
+    <row keys="q w e r t y u i o p g-tikka h-maqtugha" />
+    <row keys="a s d f g h j k l semi-colon hash" />
+    <row keys="z-tikka z x c v b n m comma period slash" />
+    <row keys="space" />
+</layer>
+```
+
+## Overview of Layers and Layer Groups
+
+Here is a reference image to help you understand layers and layer groups.
+
+![Image showing three layer groups. First, a layer group for hardware, with a base and shifted layer.  Then, a layer group for touch or mobile devices, that is less than (in this example) 100 millimeters wide, having a "123" key to switch to numbers. Finally, a layer group for wider or tablet devices, that is a width of 100 or greater millimeters, having a separate number row above the keyboard.](/cdn/dev/img/developer/ldml/layers.png)
+

developer/ldml/guide/markers.md

@@ -0,0 +1,4 @@
+---
+title: Markers
+---
+

developer/ldml/guide/overview.md

@@ -2,6 +2,99 @@
 title: LDML overview
 ---
 
-The LDML format …. Source files have the **.xml** extension and are text files.
+LDML is the Locale Data Markup Language. It it an XML-based format
+specified as the Unicode Consortium’s specification [UTS#35 Part 7],
+maintained by the [Common Locale Data Repository (CLDR)][CLDR]
+Technical Commitee.
 
-…
+LDML itself has several parts which describe diferent aspects of locale data.  This document describes the part pertaining to keyboards, part 7.
+
+## File Structure
+
+Source files have the **.xml** extension and are [XML] (text) files.  Any
+text editor can be used.  An editor which understands XML and can highlight
+syntax is preferred, such as that built into Keyman Developer.
+
+### Attributes and Escaping
+
+The LDML structure does not use any "element text", all text is in attributes.
+Attributes are opened and closed with double quotes `"`.
+
+Many attributes support escaping. That is, if you need to use a double quote
+within an attribute, the double quote must be escaped.
+For example, for a string variable with the value `I said, "yes"` it could be accomplished as shown:
+
+```xml
+<string id="yes" value="I said, \u{22}yes\u{22}"/>
+```
+
+This notation is described in [Unicode UTS #18 section 1.1][UTS18escaping] and
+consists of `\u{` followed by 1-6 hex digits and closed with `}`.
+`\u{1E8CA}` and `\u{1e8CA}` and `\u{1e8Ca}` all refer to
+U+1E8CA 𞣊 "MENDE KIKAKUI DIGIT FOUR". Upper and lower case does not matter.
+
+Escaping is not allowed everywhere.
+A double quote is not valid as the id of a key, for example, so the `<key id=`
+element does not support escaping.
+
+### Comments
+
+XML comments may be put anywhere, they do not affect the keyboard nor are
+they processed by any code.
+
+```xml
+<!-- This is a comment -->
+<!-- So is
+this-->
+```
+
+You can use comments to temporarily remove an element from processing.
+The following  "key" element is commented out, and so is not a part of
+the keyboard.
+
+```xml
+    <!-- <key id="abc" output="def" /> -->
+```
+
+### XML Prologue
+
+As an XML file, the XML prologue is needed.
+The prologue should be exactly as shown.
+(A DTD not used.)
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+```
+
+### Outer `keyboard3` Element
+
+The root element of a keyboard file is the [`keyboard3`][keyboard3] element.
+
+Note the `xmlns` and `conformsTo` elements both refer to a version of CLDR,
+in this case v47. For compatibility, you should set these to the earliest possible
+version number.
+
+<!-- TODO LDML-DOCS: more guidance on how to choose version # vs. keyman versions -->
+
+The `locale` attribute is the _primary_ [BCP 47] locale for the keyboard.
+See [choosing a locale](choosing-locale) for more information about choosing
+locale id(s) for your keyboard.
+
+```xml
+<keyboard3
+    conformsTo="47"
+    xmlns="https://schemas.unicode.org/cldr/47/keyboard3"
+    locale="bn" >
+    …
+</keyboard3>
+```
+
+Now that you have the outer structure in place, it's time to fill the [keybag].
+
+[CLDR]: https://cldr.unicode.org
+[UTS#35 Part 7]: https://www.unicode.org/reports/tr35/tr35-keyboards.html
+[BCP 47]: ../../current-version/reference/bcp-47
+[keyboard3]: ../reference/keyboard3
+[UTS18escaping]: https://www.unicode.org/reports/tr18/#Hex_notation
+[XML]: https://www.w3.org/XML/
+[keybag]: ./keybag