Merge branch 'master' into feat/common/12208-fast-xml-parser3

.github/workflows/api-verification.yml

@@ -1,4 +1,5 @@
 name: "API Verification"
+run-name: "API Verification for ${{ github.ref_name }}"
 on:
  workflow_run:
     workflows: [Ubuntu packaging]

HISTORY.md

@@ -1,5 +1,19 @@
 # Keyman Version History
 
+## 18.0.120 alpha 2024-10-02
+
+* chore(common): Add note on troubleshooting website errors (#12487)
+* docs(common): mention `KEYMAN_USE_NVM` in minimum versions doc (#12490)
+* docs(web): fix paths to several help pages (#12491)
+* docs(web): fix structure of test document (#12492)
+
+## 18.0.119 alpha 2024-09-28
+
+* refactor(developer): copy dev 17.0 help into repo (#12427)
+* fix(developer): warn before importing over touch layout (#12478)
+* chore(linux): display branch name with API verification (#12480)
+* docs(core): Update kmx-plus-file-format.md (#12479)
+
 ## 18.0.118 alpha 2024-09-26
 
 * chore(developer): add context/options (#11566)

VERSION.md

@@ -1 +1 @@
-18.0.119
+18.0.121

developer/docs/help/context/about-tike.md

@@ -0,0 +1,8 @@
+---
+title: About Dialog
+---
+
+![About dialog](../images/ui/frmAboutTike.png)
+
+The About dialog displays copyright and registration information for
+Keyman Developer, and has a link to the Keyman website.

developer/docs/help/context/character-map.md

@@ -0,0 +1,136 @@
+---
+title: Using the Character Map
+---
+
+![Character Map tool](../images/ui/frmCharacterMapNew.png)
+
+To display the Character Map:
+
+-   Press <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>c</kbd>
+-   Select **View** &#8594; **Character Map**
+
+The Character Map will appear by default docked to the right hand side
+of the IDE but can be undocked or re-docked on any side of the window.
+
+### Using the Character Map
+
+To insert a character:
+1. Position the text cursor where you want to insert the character
+2. Locate the desired character in the Character Map and insert it by:
+    - selecting the character and pressing the Enter key, or
+    - double-clicking on the character, or
+    - right-clicking on the character and selecting Insert Character.
+
+    > ### Note
+    If the Insert Mode is set to Code or Name, pressing Enter or
+    double-clicking on the character will insert the Unicode code or
+    name of the character, not the character itself. These options are
+    most useful when writing or editing keyboard source files (.KMN).
+
+### Insert Modes
+
+There are three insert modes: Code, Character and Name:
+
+- Code: inserts the character's Unicode code
+- Character: inserts the character itself
+- Name: inserts the character's Unicode name
+
+To change the insert mode:
+
+1. Right-click on the Character Map.
+2. Highlight the Insert Mode submenu.
+3. Choose the desired mode from the Insert Mode submenu.
+
+### Character Map Options
+
+When you right click on the Character Map, the following menu options
+are displayed:
+
+Insert Character
+:   Inserts the selected character at the cursor position in your
+    document.
+
+Filter...
+:   Displays the Filter dialog box. See [Filtering](#toc-filtering) below.
+
+Goto...
+:   Displays the Goto dialog box. See Using [Goto](#toc-goto) below.
+
+Font...
+:   Allows you to choose a different font for viewing the Character Map. <br/>
+    Note: This does not affect the font being used in your document!
+
+Insert Mode
+:   Allows you to select the character insert mode you want. See [Insert
+    Modes](#toc-insert-modes) above.
+
+Display Quality
+:   Allows you to select a different font display quality for the
+    Character Map. The options are:  <br/>
+    - Plain: no font smoothing
+    - Antialiased: uses the Windows standard font smoothing
+    - ClearType: uses the Windows ClearType font smoothing method
+
+### Characters and Fonts
+
+When a character is not available in the selected font, the Character
+Map will fall back to **Code2000**, **Code2001**, **Code2002**, **Arial Unicode MS** and
+**Lucida Sans Unicode** fonts. If the character is not found in these
+fallback fonts, the Character Map will use font linking to attempt to
+find a character from other fonts installed on the system, and as a last
+resort, will show a square box if no suitable font can be found.
+
+If a character is not displayed from other than the selected font, it
+will be shown in blue instead of black.
+
+### Filtering
+
+![Character Map Filter dialog](../images/ui/frmCharacterMapFilter.png)
+
+The Character Map can be filtered by Unicode character name or character
+range. Filters can be entered in the Filter By field at the bottom of
+the Character Map; a quick reference user interface dialog to help you
+edit the filter is available by clicking the \[...\] button.
+
+When no filter is applied, the Character Map will show all characters
+from the Unicode 8.0 standard.
+
+All filter strings are case insensitive. Character names use the letters
+`A-Z`, numerals `0-9`, and punctuation underscore (`_`) and hyphen
+(`-`).
+
+Spaces between words in the filter are represented either by underscore
+(`_`) or space (` `) and can be used interchangeably.
+
+A filter can be for a range or on the Unicode Character Name.
+
+The filter format for a range is: `[U+]XXXX-[U+]YYYY`, where `U+` is
+optional, `XXXX` is the starting Unicode value and `YYYY` is the
+finishing Unicode value.
+
+The filtering options for Unicode Character Names are:
+
+### Examples
+
+|                          |                         |
+|--------------------------|-------------------------|
+| Filter                   | Result                  |
+| `LATIN CAPITAL LETTER A` | Finds all Latin capital A variations         |
+| `LATIN * LETTER A`       | finds all Latin capital and lower case A variations |
+| `LATIN * LETTER [AEIOU]` | finds all Latin A,E,I,O or U vowel combinations |
+| `<Thai`                  | finds the Thai Unicode block        |
+| `>LAO`                   | finds all characters with names starting in "LAO" in the current font  |
+| `YI_`                    | finds all characters with names starting in "YI " - you must use `_` (underscore) and not `( )` space at the end of a search string. <br/> Note that without the `_`, this search also matches YIN_YANG. |
+| `LATIN * LETTER A$`      | finds only "a" and "A"             |
+| `1000-119F`              | finds all characters between U+1000 and U+119F (inclusive) - the Myanmar alphabet in this case    |
+
+### Goto
+
+The Goto tool can be used to move directly to a specific Unicode
+character or value.
+
+1. Right click on a character and select Goto. The **Enter Unicode character value or name** dialog box will be displayed.
+2. Enter the Unicode character value - e.g. `006B` or `U+006B` OR enter the start of the character name, e.g. `LAO_LETTER` will go
+    to **LAO_LETTER_KO**, being the first character that matches. You
+    can substitute spaces for underscores if you prefer.
+3. Click OK. The character map will attempt to move to the character you specified.

developer/docs/help/context/debug.md

@@ -0,0 +1,165 @@
+---
+title: Debug Window
+---
+
+![Debug window - Debug State](../images/ui/frmKeymanWizard_Debug_State.png)
+
+The debug window is shown at the bottom of the keyboard editor when
+debugging the keyboard. There are several user interface areas: The
+debugger input window, the debugger status window, a debugger toolbar
+(usually docked under the menu), and the status bar will show the
+current debugger status.
+
+## Debugger input window
+
+![Debug window - Debug State](../images/ui/frmDebug.png)
+
+The debugger input window is used for typing input to test the keyboard.
+In the top half of this window, input you type while testing your
+keyboard will be displayed, exactly the same as in use, with one
+exception: deadkeys will be shown visually with an
+![OBJ](../images//ui/obj.gif) symbol.
+
+The lower half of the window shows a grid of the characters to the
+virtual left of the insertion point, or the selected characters if you
+make a selection. Deadkeys will be identified in the grid. The grid will
+show characters in right-to-left scripts in backing store order, from
+left to right. If there are more characters in your text than can fit on
+the screen, then only those that fit will be shown in the grid.
+
+## Debug controls
+
+The debug menu and debug toolbar control the debugger.
+
+![Debug toolbar](../images/ui/Debug_Toolbar.png)
+
+![Debug menu](../images/ui/Debug_Menu.png)
+
+Set/Clear breakpoint
+:   A breakpoint can be put on a line of code to ask Keyman Developer to
+    stop and show what is happening in the keyboard layout when that
+    line is reached. Typically, you would put a breakpoint on a
+    particular rule, so you could debug an unexpected behaviour on that
+    rule.
+
+Start Debugging
+:   Starts the debugger
+
+Stop Debugger
+:   Stops the current debug session
+
+Single Step Mode
+:   When this option is active, you will step through every group and
+    rule that your keyboard applies when a keystroke is pressed. The
+    Step Forward and Run controls are only relevant in Single Step Mode.
+
+Step Forward
+:   Move to the next step in your keyboard code.
+
+Run
+:   Stop processing the current keystroke event in single step mode
+    (unless a breakpoint is hit). The next keystroke event will drop
+    into single step mode again.
+
+Pause
+:   Use the Pause button or press <kbd>Shift</kbd> + <kbd>Esc</kbd> to pause the debugger. When
+    the debugger is paused, it will not accept any input, and ordinary shortcut keys (<kbd>Shift</kbd> + <kbd>F5</kbd>, <kbd>Alt</kbd> + <kbd>Tab</kbd>, etc.) will function as usual. Press Pause again to resume debugging.
+
+<!-- System keyboard
+:   The system keyboard layout currently being used. You can test your
+    keyboard with a different underlying layout by selecting
+    **Select System Keyboard** from the **Debug** menu. -->
+
+## Debug State box
+
+The debug state box shows the internal state of the keyboard
+interpreter.
+
+### State
+
+![Debug window - Debug State](../images/ui/frmKeymanWizard_Debug_State.png)
+
+This window shows the current keystroke state, and the sequence of
+keystrokes that were typed to arrive at this state. Clearing the text in
+the debug window will also clear the keystroke log; as will pressing the
+Restart button.
+
+The Restart button is disabled while stepping through an event.
+
+### Elements
+
+![Debug window - Debug Elements](../images/ui/frmKeymanWizard_Debug_Elements.png)
+
+This shows the elements that make up rule currently being processed: the
+context, the key, and also what the output will be. If the rule uses
+stores, the contents of the store will be shown in the right-hand
+column, with the matched letter in red.
+
+### Call Stack
+
+![Debug window - Debug Call stack](../images/ui/frmKeymanWizard_Debug_CallStack.png)
+
+Here all the lines that have been processed to this point are shown in a
+list. You can double-click on any entry in the list to display the line
+in the keyboard source.
+
+### Deadkeys
+
+![Debug window - Debug Deadkeys](../images/ui/frmKeymanWizard_Debug_Deadkeys.png)
+
+This lists all the deadkeys that are currently in the context. You can
+select one from the list to see it highlighted in the debug input box.
+This information can also be seen in the character grid in the lower
+half of the debugger input window.
+
+### Regression Testing
+
+![Debug window - Debug Regression Test](../images/ui/frmKeymanWizard_Debug_RegressionTest.png)
+
+The idea in regression testing is to record a sequence of keystrokes and
+the output the keyboard produced, in order to test for the same
+behaviour when you make changes to the keyboard.
+
+Use Start Log/Stop Log to record the input and output. You can then use
+Start Test to run the test again, or go the Options menu to clear the log,
+or save or load a test, or use the batch mode to run several tests in a
+row.
+
+If the output produced while running a test is different to that stored
+when recording it, Keyman will halt the test on the line where the
+failure occurred, and activate Single Step mode.
+
+### Status bar
+
+The input status is shown in the second pane of the status bar. It can
+show one of the following messages:
+
+Ready for input
+:   The debugger is waiting for more input
+
+Focused for input
+:   The debugger is waiting for more input, and the Debug Input window
+    is active
+
+Paused
+:   The debugger is paused
+
+Receiving events
+:   The debugger is processing input
+
+Debugging
+:   The debugger is active during Single Step mode or after a breakpoint
+
+## Test mode
+
+Enter test mode by clicking the **Test Mode**
+button on the debugger toolbar.
+
+The test mode lets you test your keyboard without the debugger being
+active. This lets you test functionality that is not available within
+the debugger - primarily [IMX code](../guides/develop/imx/).
+
+Once in test mode, no debugger controls are available.
+
+You can see the character codes for the current or selected characters
+in the status bar, which can be useful when debugging your keyboard.

developer/docs/help/context/edit-language-example.md

@@ -0,0 +1,44 @@
+---
+title: Add/Edit Language Example Dialog
+---
+
+![Add/Edit Language Example dialog](../images/ui/frmEditLanguageExample.png)
+
+This dialog allows you to create or edit example key sequences to demonstrate
+how to use your keyboard. Examples should be relatively short -- one to five
+words is ideal, but if possible, should demonstrate sequences that may be hard
+for users to discover on their own.
+
+These language examples can be seen live, for example, on
+[keymanweb.com](https://keymanweb.com).
+
+## Language tag
+
+Enter the BCP 47 language tag that this example corresponds to. It should be a
+language tag that is listed in the package file.
+
+## Key sequence
+
+This is a space separated list of keys. For spacebar, use `space`. For modifier
+key combinations, use the modifier key(s) followed by `+` and the key that they
+are pressed together with, e.g. `right-alt+shift+A`.
+
+* modifiers indicated with "+"
+* spacebar is "space"
+* plus key is "shift+=" or "plus" on US English (all other punctuation as per
+  key cap).
+* Hardware modifiers are: "shift", "ctrl", "alt", "left-ctrl", "right-ctrl",
+  "left-alt", "right-alt"
+* Key caps should generally be their character for desktop (Latin script case
+  insensitive), or the actual key cap for touch
+* Caps Lock should be indicated with "caps-on", "caps-off"
+
+## Expected text
+
+Here, put the actual output generated by the key sequence.
+
+## Note
+
+You may include a translation of the text or another note that highlights an
+aspect of how the text is typed.
+