feat: ldml-docs update guide ✍️ #2151

srl295 · 2025-07-05T19:34:53Z

add planning, overview, keybag, displays, and layers sections
with this, the guide is somewhat complete for a basic non-transform keyboard!

#13836

@keymanapp-test-bot skip

#13836

- add planning section #13836

- add a few initial sections, mostly blank #13836

- updates across sections #13836

- updated displays and keybag #13836

- updated displays, keybag, layouts #13836

- update keybags and displays #13836

- layouts to layers (!) and add image #13836

- finish the layers section, also update keybag and displays #13836

markcsinclair

There looks to be some more work to do yet @srl295, especially in the glossary and 'going further' sections. Keep going!

developer/ldml/guide/index.md

developer/ldml/guide/choosing-locale.md

markcsinclair · 2025-08-06T13:25:24Z

developer/ldml/guide/glossary.md


 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.


The glossary should be expanded to include as many of the technical terms used in LDML as possible e.g. Keybag, Displays, Layers, shift layer, Variables, Transforms, Markers, Reorders, Elements, base physical types (US, ISO), organisation of keys (QWERTY, AZERTY, QWERTZ), touch-only keyboard, gestures, long press, flick, multitap, LDML, XML, locale, (element) attribute, DTD, CLDR, repertoire, key element, keys element, (key) gap, (key) stretch, keytop, keycap, switch key, layer group, modifier, (keyboard) row, etc.
Some of these terms you could just give a short entry and a link to either an internal or external definition/description (e.g. the key element is described in keybag.md).

I don't think that this para makes sense now that the Glossary is the final page in the Guide section. I would remove it or replace it with 'return to index'?

Suggested change

Now, go on to begin [planning](./planning) your LDML keyboard.

You have reached the end of the LDML keyboard authoring guide. Return to the [index](index).

markcsinclair · 2025-08-06T13:35:23Z

developer/ldml/guide/planning.md

+
+### Form and Function
+
+- Will this be a hardware-only or touch-only keyboard?


It would be good to have links from the technical terms to entries in the glossary.

developer/ldml/guide/overview.md

developer/ldml/guide/index.md

markcsinclair · 2025-08-06T14:26:52Z

developer/ldml/guide/variables.md

+---
+title: Variables
+---
+


No content yet?

markcsinclair · 2025-08-06T14:27:01Z

developer/ldml/guide/transforms.md

+---
+title: Transforms
+---
+


No content yet?

markcsinclair · 2025-08-06T14:27:35Z

developer/ldml/guide/reorders.md

+---
+title: Reorders
+---
+


No content yet?

markcsinclair · 2025-08-06T14:27:52Z

developer/ldml/guide/markers.md

+---
+title: Markers
+---
+


No content yet?

still in progress

keymanapp-test-bot · 2025-08-09T00:04:18Z

User Test Results

Test specification and instructions

User tests are not required

mcdurdin

This is looking good, looking forward to seeing the next bits

Can you wrap .md at 80 chars -- this is what we try to do on other pages on the site.

developer/ldml/guide/displays.md

developer/ldml/guide/index.md

developer/ldml/guide/keybag.md

developer/ldml/guide/choosing-locale.md

developer/ldml/guide/layers.md

developer/ldml/guide/planning.md

- keybag: updated per review comments - layers: upated per review comments - moved "overview" into the getting started section - planning: updated per review comments For: #13836

srl295 · 2025-08-28T23:08:09Z

@markcsinclair @mcdurdin I think I've now resolved all of the review comments other than:

stub pages (no content yet)
need more links to the glossary

I think if these look good we could merge this into the epic branch as an improvement, getting us through the first two parts of the guide. (getting started / jumping in)

…uide-epic-ldml-docs

…c-ldml-docs

mcdurdin · 2025-09-02T14:54:34Z

Have re-embarked on review here, will do this when my brain is fresh.

mcdurdin

Some really good work here. I have mostly nits!

mcdurdin · 2025-09-03T03:03:06Z

developer/ldml/guide/displays.md

+## Why customize the display
+
+Normally, the display of a keytop, whether in a touch environment or the
+on-screen display of a hardware keyboard, simply matches the characrer output.


Suggested change

on-screen display of a hardware keyboard, simply matches the characrer output.

on-screen display of a hardware keyboard, simply matches the character output.

mcdurdin · 2025-09-03T03:03:33Z

developer/ldml/guide/displays.md

+So, a key that outputs `a` will have a keytop that looks like `a`.
+
+However, there are some situations where it is desirable to customize the
+display of a key. This is where the [display] element is useful.  This is an


Suggested change

display of a key. This is where the [display] element is useful. This is an

display of a key. This is where the [`display`] element is useful. This is an

mcdurdin · 2025-09-03T03:04:34Z

developer/ldml/guide/displays.md

+
+## displayOptions
+
+The `displayOptions` has a single configurable option at present, the


Suggested change

The `displayOptions` has a single configurable option at present, the

The [`displayOptions`] element has a single configurable option at present, the

mcdurdin · 2025-09-03T03:04:48Z

developer/ldml/guide/displays.md

+baseCharacter.
+
+In Lao for example, it's sometimes preferred to use `x` as the base for showing
+combining marks, rather than the dotted circle ◌.


Suggested change

combining marks, rather than the dotted circle ◌.

combining marks, rather than the dotted circle `◌` (U+25CC).

mcdurdin · 2025-09-03T03:05:44Z

developer/ldml/guide/index.md

+needed to successfully author an LDML Keyboard used with Keyman.

-* [LDML Language Overview](overview)
+We recommend to start with [Planning](./planning) and read these pags in order,


Suggested change

We recommend to start with [Planning](./planning) and read these pags in order,

We recommend that you start with [Planning](./planning) and read these pages in order,

mcdurdin · 2025-09-03T03:39:03Z

developer/ldml/guide/overview.md

+<?xml version="1.0" encoding="UTF-8"?>
+```
+
+### Outer `keyboard3` Element


Suggested change

### Outer `keyboard3` Element

### Root `keyboard3` Element

mcdurdin · 2025-09-03T03:41:44Z

developer/ldml/guide/planning.md

+- 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?


Suggested change

- Which width(s) will you start with for the touch layout?

- Which device screen width(s) will you start with for the touch layout?

mcdurdin · 2025-09-03T03:42:53Z

developer/ldml/guide/planning.md

+- Which characters are the most important to access? That is, those that would
+  be right on the keyboard or on a shift layer, versus others that might be
+  reached via a gesture or multiple key combination.
+


We could reference the DISCUS principles here? /developer/keyboards/standard

mcdurdin · 2025-09-03T03:44:44Z

developer/ldml/reference/import.md

-`id`
-:   The …
+`id` :   The …


My guess is that this unwrapping was not intentional, throughout, for definition lists?

unintentional, probably mis-parsing of markdown

The vscode wrapping plugin I use (rewrap) doesn't recognize DLs and so munges my DLs like this. One slightly clumsy workaround is a blank line between dt and dd.

mcdurdin · 2025-09-03T03:45:39Z

developer/ldml/reference/keyboard3.md


-`conformsTo` - Required
-:   This indicates the minimum supported version number of CLDR that this file conforms to.  In other words, this file may not use features from CLDR versions after this number. This must be a whole number such as "46". See [CLDR Releases] for a current list of CLDR versions. Authors should use the _minimum_ possible number here so that the keyboard is the most widely usable.
-
-`draft` - Optional
-:   For keyboards which are contributed to CLDR itself, this indicates the approval level of the [CLDR keyboard process]. For keyboard authors, it is best to omit this attribute or set it to `contributed`. Other possible values include `approved`, `unconfirmed`, and `provisional`.
-
-`locale` - Required
-:   This attribute specifies the [BCP 47] tag used for the primary locale for this keyboard. The [`locales`](./locales) element can be used to specify additional locales, however, at least one locale must be specified in the `locale` attribute.
+`conformsTo` - Required :   This indicates the minimum supported version number


same - DL is unwrapped wrongly

srl295 added 3 commits July 5, 2025 09:51

feat: ldml-docs: more updates to overview ✍️

9e1d261

#13836

feat: ldml-docs: skeletal guide ToC ✍️

836ecd0

#13836

feat: ldml-docs: update guide ToC ✍️

cb24532

- add planning section #13836

srl295 self-assigned this Jul 5, 2025

keyman-status added this to Keyman Jul 5, 2025

github-project-automation bot moved this to Todo in Keyman Jul 5, 2025

feat: ldml-docs: update guide ToC ✍️

f4d5704

- add a few initial sections, mostly blank #13836

srl295 marked this pull request as draft July 5, 2025 22:00

feat: ldml-docs: update guide ToC ✍️

2fcda11

- updates across sections #13836

srl295 changed the title ~~feat: ldml-docs update guide~~ feat: ldml-docs update guide ✍️ Jul 16, 2025

srl295 added 5 commits July 16, 2025 17:12

feat: ldml-docs: update guide ToC ✍️

af14e3a

- updated displays and keybag #13836

feat: ldml-docs: update guide ToC ✍️

0fc5a1e

- updated displays, keybag, layouts #13836

feat: ldml-docs: update guide ToC ✍️

a2e6b9d

- update keybags and displays #13836

feat: ldml-docs: update guide ToC ✍️

5dc7026

- layouts to layers (!) and add image #13836

feat: ldml-docs: update guide ToC ✍️

756b62c

- finish the layers section, also update keybag and displays #13836

srl295 marked this pull request as ready for review August 1, 2025 01:03

srl295 requested review from Nnyny, SabineSIL, markcsinclair and mcdurdin August 1, 2025 01:04

markcsinclair assigned markcsinclair and unassigned srl295 Aug 6, 2025

markcsinclair reviewed Aug 6, 2025

View reviewed changes

markcsinclair assigned srl295 and unassigned markcsinclair Aug 6, 2025

update per review

b6c4345

keymanapp-test-bot bot added the epic-ldml-docs label Aug 9, 2025

keymanapp-test-bot bot added this to the A19S9 milestone Aug 9, 2025

mcdurdin reviewed Aug 11, 2025

View reviewed changes

feat: ldml-docs: updates to guides

6d7d85d

- keybag: updated per review comments - layers: upated per review comments - moved "overview" into the getting started section - planning: updated per review comments For: #13836

srl295 requested review from markcsinclair and mcdurdin August 28, 2025 23:05

darcywong00 modified the milestones: A19S10, A19S11 Aug 29, 2025

srl295 added 2 commits August 30, 2025 17:23

chore: rewrap to 80 columns

3ee0de3

Merge remote-tracking branch 'origin/master' into feat/13836/update-g…

f7adb99

…uide-epic-ldml-docs

github-actions bot added the feat label Aug 30, 2025

chore: Merge branch 'epic/ldml-docs' into feat/13836/update-guide-epi…

5773bc8

…c-ldml-docs

mcdurdin assigned mcdurdin and unassigned srl295 Sep 2, 2025

mcdurdin requested changes Sep 3, 2025

View reviewed changes

darcywong00 modified the milestones: A19S11, A19S12 Sep 13, 2025

darcywong00 modified the milestones: A19S12, A19S13 Sep 27, 2025

darcywong00 modified the milestones: A19S13, A19S14 Oct 11, 2025

darcywong00 modified the milestones: A19S14, A19S15 Oct 24, 2025

keyman-server modified the milestones: A19S15, A19S16 Nov 8, 2025

keyman-server modified the milestones: A19S16, A19S17 Nov 22, 2025

keyman-server modified the milestones: A19S17, A19S18 Dec 6, 2025

keyman-server modified the milestones: A19S18, A19S19 Dec 21, 2025


		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.

	Now, go on to begin [planning](./planning) your LDML keyboard.
	You have reached the end of the LDML keyboard authoring guide. Return to the [index](index).


		### Form and Function

		- Will this be a hardware-only or touch-only keyboard?

	on-screen display of a hardware keyboard, simply matches the characrer output.
	on-screen display of a hardware keyboard, simply matches the character output.

	display of a key. This is where the [display] element is useful. This is an
	display of a key. This is where the [`display`] element is useful. This is an


		## displayOptions

		The `displayOptions` has a single configurable option at present, the

	The `displayOptions` has a single configurable option at present, the
	The [`displayOptions`] element has a single configurable option at present, the

	combining marks, rather than the dotted circle ◌.
	combining marks, rather than the dotted circle `◌` (U+25CC).

	We recommend to start with [Planning](./planning) and read these pags in order,
	We recommend that you start with [Planning](./planning) and read these pages in order,

	- Which width(s) will you start with for the touch layout?
	- Which device screen width(s) will you start with for the touch layout?

Uh oh!

feat: ldml-docs update guide ✍️ #2151

Are you sure you want to change the base?

feat: ldml-docs update guide ✍️ #2151

Uh oh!

Conversation

srl295 commented Jul 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

markcsinclair left a comment • edited by mcdurdin Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

keymanapp-test-bot bot commented Aug 9, 2025

User Test Results

Uh oh!

mcdurdin left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

srl295 commented Aug 28, 2025

Uh oh!

mcdurdin commented Sep 2, 2025

Uh oh!

mcdurdin left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

srl295 commented Jul 5, 2025 •

edited

Loading

markcsinclair left a comment •

edited by mcdurdin

Loading