diff --git a/developer/docs/help/guides/develop/walkthrough/00-introduction.md b/developer/docs/help/guides/develop/walkthrough/00-introduction.md index cf5d0327504..0577ecef535 100644 --- a/developer/docs/help/guides/develop/walkthrough/00-introduction.md +++ b/developer/docs/help/guides/develop/walkthrough/00-introduction.md @@ -2,7 +2,12 @@ title: Introduction --- -[Next: Part 1 - Creating a Keyboard Project >](01-creating-keyboard-project) + +
+ Introduction to the [Keyman Developer Walkthrough](.). + + [Next: Part 1 - Creating a Keyboard Project →](01-creating-keyboard-project) +
## Step-by-Step @@ -12,7 +17,7 @@ If you encounter unfamiliar terms, please consult the [glossary](glossary). ### Introducing Keyman Developer -Keyman Developer is a powerful tool you can use to create custom keyboards optimized to type in any language you choose. Keyboard authors can distribute their work for desktop, web, tablet and phone, enabling global communities to quickly benefit from keyboards made for their own language. +Keyman Developer is a powerful tool you can use to create custom software keyboards optimized to type in any language you choose. Keyboard authors can distribute their work for desktop, web, tablet and phone, enabling global communities to quickly benefit from keyboards made for their own language. Keyboards created with Keyman Developer can be used on Windows, macOS, Linux, iOS, Android, and the web. @@ -23,7 +28,7 @@ Currently this software is Windows-only, although the command line tools it uses Keyman Developer is completely free to download and use. You can download it from [https://keyman.com/developer/download](https://keyman.com/developer/download). -On the downloads page, just click the big green “Download Now” button to get the latest version of Keyman. Once you have it, run the `keymandeveloper.exe` file you’ve received. The numbers following “keymandeveloper” indicate which version of Keyman Developer you are installing. +On the downloads page, just click the big green “Download Now” button to get the latest version of Keyman. Once you have it, run the `keymandeveloper-a.b.c.exe` file you’ve downloaded. The numbers following “keymandeveloper” indicate which version of Keyman Developer you are installing; you can also see the Keyman Developer version in the main installer window, or after installation, in the Help/About dialog. After installing Keyman Developer, you should be able to run it on your computer and begin creating projects immediately. @@ -31,9 +36,11 @@ Note that Keyman Developer is a separate app from Keyman, which is the app that In order to use the keyboard you create with Keyman Developer, you'll need to have the Keyman app installed on your computer or device. Keyman is available on the following platforms: Windows, macOS, Linux, iOS, Android, and the web. -The icons for Keyman Developer ![Keyman Developer icon](images/keyman-developer-icon.png) and Keyman ![Keyman icon](images/keyman-icon.png) are similar but slightly different. +The Keyman Developer icon ![Keyman Developer icon](images/keyman-developer-icon.png) is a faded version of the Keyman icon ![Keyman icon](images/keyman-icon.png). +
To continue the Step-by-Step tutorial move to the next page: [Part 1 - Creating a Keyboard Project](01-creating-keyboard-project) +
--- @@ -48,9 +55,9 @@ Ask questions and talk with other keyboard authors on the [Keyman Community Foru ### Keyman online help -[Keyman Developer Language Documentation](https://help.keyman.com/developer/language/guide/) +[Keyman Developer Language Guide](https://help.keyman.com/developer/language/guide/) -Reference for the general structure of the Keyman language. +Information about the general structure and concepts of the Keyman language. [Keyman Developer Language Reference](https://help.keyman.com/developer/language/reference/) @@ -69,7 +76,12 @@ Read up on Keyman’s latest releases and patch notes on the [Keyman Blog](https Keyman uses a number of [Github](https://github.com/keymanapp) repositories to store source code, keyboards, lexical models and documentation. There is also a mechanism for reporting problems. [Keyman Bug Reports](https://github.com/keymanapp/keyman/issues) -Report Keyman software bugs and issues here. NOTE: NOT for help and support questions. The Keyman community forum is the best place to ask for help with development. Think you’ve found a Keyman bug or a problem with a specific keyboard? Describe what you’ve found on the Keyman community forum and ask whether to report a bug. +Report Keyman software bugs and issues here. + +> [!NOTE] +> GitHub issues are not the best place to ask for help or support questions. The Keyman community forum is a better place to ask for help with keyboard development. Think you’ve found a Keyman bug or a problem with a specific keyboard? Describe what you’ve found on the Keyman community forum and ask whether to report a bug. -[Next: Part 1 - Creating a Keyboard Project >](01-creating-keyboard-project) +
+ [Next: Part 1 - Creating a Keyboard Project →](01-creating-keyboard-project) +
diff --git a/developer/docs/help/guides/develop/walkthrough/01-creating-keyboard-project.md b/developer/docs/help/guides/develop/walkthrough/01-creating-keyboard-project.md index 630c00821ce..1e5c8f8078f 100644 --- a/developer/docs/help/guides/develop/walkthrough/01-creating-keyboard-project.md +++ b/developer/docs/help/guides/develop/walkthrough/01-creating-keyboard-project.md @@ -2,11 +2,12 @@ title: Creating a Keyboard Project --- -Part 1 of the [Keyman Developer Walkthrough](../walkthrough). + +
+ Part 1 of the [Keyman Developer Walkthrough](.). -[< Back: Introduction](00-introduction) - -[Next: Part 2 - Designing a Desktop Layout >](02-designing-desktop-layout) + [← Introduction](00-introduction)   [Part 2 - Designing a Desktop Layout →](02-designing-desktop-layout) +
## Step-by-Step @@ -31,8 +32,9 @@ For the Dagbani keyboard, the keyboard planning has been done for you. Follow th - Select `OK` to close the `Select BCP 47 tag` dialog. - Select `OK` to close the `New Basic Keyboard Project` dialog. +
To continue the Step-by-Step tutorial move to the next page: [Part 2 - Designing a Desktop Layout](02-designing-desktop-layout) - +
--- ## Planning a Keyboard @@ -41,7 +43,7 @@ The first step is identifying the language or languages your keyboard will cover - it is difficult to optimize a keyboard for multiple languages since a rarely used character for one language may be a common character for another. - it is harder for users to find the keyboard since the name of the keyboard may not relate to the particular language they are researching. -- a separate lexical model (for predictive text) is needed for each language, so having a keyboard that handles multiple languages may make installation of a lexical model harder. +- it is more difficult for users to select the correct language for during installation, particularly if a keyboard handles many languages. This is particularly important for lexical models for predictive text, as a separate model is needed for each language. Furthermore, having a keyboard specifically designed for a single language may help with community acceptance. @@ -87,20 +89,23 @@ Note that the `Keyboard ID` (near the bottom of the dialog) fills in automatical You can modify the value in this field, though you are limited to the characters a-z, the numbers 0-9 and underscore. This value will be used as the base filename of many of your Keyman files. -If you decide to change the keyboard ID, you’ll need to change most of the files in the project. -This is best done using Keyman Developer’s `Clone local project` feature. - -- From the `Project` menu, select `New Project` then `Clone local project`. -- Use the `Browse` button to navigate to the `.kpj` file of your existing project. -- Specify a new `project ID` (and adjust `Destination path` if desired), then select `OK`. +> [!NOTE] +> If you decide to change the keyboard ID, you’ll need to change most of the files in the project. This is best done using Keyman Developer’s `Clone local project` feature. +> • From the `Project` menu, select `New Project` then `Clone local project`. +> • Use the `Browse` button to navigate to the `.kpj` file of your existing project. +> • Specify a new `project ID` (and adjust `Destination path` if desired), then select `OK`. ### Description This brief description of your keyboard is included in all of your information files. -Try to keep this short but informative, as this is what people will see when searching for your keyboard. +Try to keep this short but informative, as this is what people will see when searching for your keyboard on the keyman.com website. It may be useful to include alternate language names, the script (Latin, Devanagari, etc) if the language is written in more than one script, the region where it is used, or other details about the keyboard. +The description field can use [Markdown](https://www.markdownguide.org/cheat-sheet/) for basic formatting and links. + +The description is added to `README.md` and the package `.kps` file. + ### Author, Copyright, and Full Copyright Enter your name in the `Author` field. @@ -111,20 +116,25 @@ The Full Copyright field has the date as well as the copyright holder. The name used in the Copyright fields must be the real name of an individual or of an organization. Copyright cannot be assigned to a pseudonym. +The short copyright message is added to `README.md`, `welcome.htm`, `readme.htm`, package `.kps` details, and the [`©right` keyboard system store](https://help.keyman.com/developer/language/reference/copyright) in the `.kmn` file. +The full copyright message is added to `LICENSE.md`. + ### Languages -This table displays the [BCP 47](https://help.keyman.com/developer/current-version/reference/bcp-47) tag (or tags) associated with your keyboard. +This table displays the [BCP 47](../../../reference/bcp-47) tag (or tags) associated with your keyboard. A BCP 47 tag identifies a language and will help users find your keyboard when they search for their language. If you don’t know what your language’s tag is, you can search for its name and find the corresponding tag in the [IANA Language Subtag Registry](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry), which contains all existing BCP 47 tags, the [Glottolog](https://glottolog.org/glottolog/language) (under the ISO-639-3 column), or the [SIL Ethnologue](https://www.ethnologue.com/). The SIL Ethnologue is the most user-friendly option of the three, if you are unfamiliar with language tags. In addition to your basic BCP 47 tag, you can add -[Script](https://help.keyman.com/developer/current-version/reference/bcp-47#toc-the-script-subtag) and -[Region](https://help.keyman.com/developer/current-version/reference/bcp-47#toc-the-region-subtag) subtags. +[Script](../../../reference/bcp-47#toc-the-script-subtag) and +[Region](../../../reference/bcp-47#toc-the-region-subtag) subtags. However, you should always use the simplest possible BCP 47 tag to identify your language. Only add Script and Region tags if your keyboard is for a script or region that differs from the most commonly used form of the language. +Language information is added to `README.md` and in the package `.kps` file, in the Keyboards section. + ### Version The keyboard version number allows Keyman to tell which of two copies of a keyboard is newer. This allows Keyman to offer users updated versions of keyboards. @@ -133,10 +143,11 @@ The version number consists of two or three integer numbers separated by periods New keyboards usually start with version `1.0` (which is equivalent to `1.0.0`). Generally the first number is incremented for major changes to the keyboard, -the second for minor changes, and the third for corrections or bug fixes. -But the most important point is that the new version number be greater than the existing one (as noted above). +the second for minor changes, and the third for corrections or bug fixes (this is known as [semantic versioning](https://semver.org); note that Keyman keyboard versions do not allow additional labels). -The version number appears in the `HISTORY.md` file and the `.kmn` file. +The most important point is that the new version number be greater than the existing one (as noted above). + +The version number appears in the `HISTORY.md` file and the `.kmn` file in the [`&keyboardversion` keyboard system store](https://help.keyman.com/developer/language/reference/keyboardversion). It should be updated in both places whenever you distribute a new version of the keyboard. ### Targets @@ -148,7 +159,7 @@ If you select `any`, you do not need to (and should not) choose any other option It is best practice to support as many devices as possible when creating your keyboard, because it is hard to predict who will use your keyboard in the future. By making your keyboard as accessible as possible, you can help even more people. -If you decide not to include a touch layout, untick the `any` option and select `desktop` and `web` which will allow the keyboard to be used on a web page as well as on Linux, macOS and Windows (the three `desktop` platforms). If you later add a touch layout, you can reverse this process and go back to selecting just `any`. +If you decide not to include a touch layout, untick the `any` option and select `desktop` and `web` which will allow the keyboard to be used on a web page as well as on Linux, macOS and Windows (the three `desktop` platforms). If you later add a touch layout, you can reverse this process and go back to selecting just `any` in the [`&targets` keyboard system store](https://help.keyman.com/developer/language/reference/targets). ### Path @@ -160,7 +171,7 @@ It’s a good idea to let Keyman handle naming your files, since it uses good na Once you have filled out all of the fields, Keyman Developer will create your project and open it in a new window with your project’s `.kpj` (Keyman project) file displayed. -You can read more about the `.kpj` file type in the [official Keyman documentation](https://help.keyman.com/developer/current-version/reference/file-types/kpj). +You can read more about the `.kpj` file type in the [official Keyman documentation](../../../reference/file-types/kpj). ## Basing a new Keyboard Project on an existing one @@ -184,6 +195,6 @@ When ready, select `OK` to download the files, adjust the filenames and open the Now that you have your project set up, continue to the next section of the tutorial to start developing your first keyboard layout. -[< Back: Introduction](00-introduction) - -[Next: Part 2 - Designing a Desktop Layout >](02-designing-desktop-layout) \ No newline at end of file +
+ [← Introduction](00-introduction)   [Part 2 - Designing a Desktop Layout →](02-designing-desktop-layout) +
diff --git a/developer/docs/help/guides/develop/walkthrough/02-designing-desktop-layout.md b/developer/docs/help/guides/develop/walkthrough/02-designing-desktop-layout.md index 2fc65182cdf..ad87d0052d4 100644 --- a/developer/docs/help/guides/develop/walkthrough/02-designing-desktop-layout.md +++ b/developer/docs/help/guides/develop/walkthrough/02-designing-desktop-layout.md @@ -2,11 +2,12 @@ title: Designing a Desktop Layout --- -Part 2 of the [Keyman Developer Walkthrough](../walkthrough). + +
+Part 2 of the [Keyman Developer Walkthrough](.). -[< Back: Part 1 - Creating a Keyboard Project](01-creating-keyboard-project) - -[Next: Part 3 - Creating a Desktop Layout >](03-creating-desktop-layout) +[← Part 1 - Creating a Keyboard Project](01-creating-keyboard-project)   [Part 3 - Creating a Desktop Layout →](03-creating-desktop-layout) +
## Step-by-Step @@ -18,7 +19,9 @@ We’ll start with the default QWERTY layout and add rules so that typing ; This Step-by-Step tutorial won’t be using the visual layout features of Keyman Developer for creating the desktop keyboard. +
To continue the Step-by-Step tutorial move to the next page: [Part 3 - Creating a Desktop Layout](03-creating-desktop-layout) +
--- @@ -60,7 +63,7 @@ For visual mapping, this can be done with tools as rudimentary as a pen and pape Navigate to your `.kpj` file, go to the `Keyboards` tab, and open your `.kmn` file. This is where your keyboard’s information lies, as well as the code that makes it work. -You can read more about the `.kmn` file type in the [official Keyman documentation](https://help.keyman.com/developer/current-version/reference/file-types/kmn). +You can read more about the `.kmn` file type in the [official Keyman documentation](../../../reference/file-types/kmn). Inside your `.kmn` file, select the `Layout` tab on the left. For a new project, the `Design` tab (at the bottom) should already be selected. @@ -112,7 +115,9 @@ Here’s an example of how to list your keystrokes. (This can also be reused whe Once you have planned the visual layout of your keyboard and determined how to assign the rest of the keys on the keyboard, it’s time to begin coding. If your layout is simple enough that you do not need to program additional keys, you do not need to worry as much about the next section. In some cases, using Keyman’s visual editor is enough for a desktop keyboard. -Note that once you begin adding rules, the keyboard becomes too complex to modify with the visual layout tools, so it is best to do any visual layout work first using the `Design` tab, then add the additional rules using the `Code` tab. + +> [!NOTE] +> Once you begin adding multi-part rules, the keyboard becomes too complex to modify with the visual layout tools, so it is best to do any visual layout work first using the `Design` tab, then add the additional rules using the `Code` tab. ### Deadkeys @@ -139,7 +144,6 @@ We could choose to design the keyboard so that typing `[ { ] } - _ = + \ |` will That could be done with the `Design` mode using the visual layout tools, or by adding rules. We would then want to add rules to allow the user to type the characters that were on the ten keys that we repurposed to type the additional characters, for example type the `;` key then the `[` key to get an actual `[` character. - -[< Back: Part 1 - Creating a Keyboard Project](01-creating-keyboard-project) - -[Next: Part 3 - Creating a Desktop Layout >](03-creating-desktop-layout) \ No newline at end of file +
+[← Part 1 - Creating a Keyboard Project](01-creating-keyboard-project)   [Part 3 - Creating a Desktop Layout →](03-creating-desktop-layout) +
\ No newline at end of file diff --git a/developer/docs/help/guides/develop/walkthrough/03-creating-desktop-layout.md b/developer/docs/help/guides/develop/walkthrough/03-creating-desktop-layout.md index 090e9cb627c..0e28aa51739 100644 --- a/developer/docs/help/guides/develop/walkthrough/03-creating-desktop-layout.md +++ b/developer/docs/help/guides/develop/walkthrough/03-creating-desktop-layout.md @@ -2,11 +2,12 @@ title: Creating a Desktop Layout --- -Part 3 of the [Keyman Developer Walkthrough](../walkthrough). + +
+Part 3 of the [Keyman Developer Walkthrough](.). -[< Back: Part 2 - Designing a Desktop Layout](02-designing-desktop-layout) - -[Next: Part 4 - Using the Debugger >](04-using-debugger) +[← Part 2 - Designing a Desktop Layout](02-designing-desktop-layout)   [Part 4 - Using the Debugger →](04-using-debugger) +
## Step-by-Step @@ -71,7 +72,9 @@ store(output_char) "ɛɔŋɣʒƐƆŊƔƷ" - Select the `Build` tab on the left, then the `Compile Keyboard` button. (Alternatively you can use the `Keyboard` menu, `Compile Keyboard` menu item to compile the keyboard. Or you can use the F7 function key as a shortcut.) - You should see messages at the bottom indicating `dagbani.kmn built successfully`. If this is not the case, you’ll need to examine the error messages to see what the error is and correct it. +
To continue the Step-by-Step tutorial move to the next page: [Part 4 - Using the Debugger](04-using-debugger) +
--- @@ -95,14 +98,17 @@ If you click on that key, you’ll see it change color and the information about ![](images/unicode-character-value.png) -This shows: +On the key cap, this shows: - `[` the default value from the QWERTY layout -- `ɛ` the value displayed on this key for the On-screen Keyboard (OSK) -- `U+025B` the Unicode value that the key will produce -- `ɛ` the character that the key will produce (the equivalent of the Unicode value) +- `ɛ` the character that the key will produce + +Below the key cap, there are two edit fields which allow you to change the character that the key will product: + +- `U+025B` the Unicode value(s) that the key will produce +- `ɛ` the character(s) that the key will produce (the equivalent of the Unicode value) -The last two of these values are linked. If you change one, the other will change. Most of the time the second and fourth items will be the same, but sometimes it might be helpful to display something different than what is actually produced. If, for example, the character being produced is not visible, such as a no-break space or a right-to-left mark, it might be helpful to display `NBSP` or `RTL` or some symbol to remind the user what the key produces. +These two edit fields are linked. If you change one, the other will change. Clicking on the `Code` tab at the bottom of the window displays the code equivalent of the work in the visual editor: @@ -118,7 +124,7 @@ If you were to continue this example, you would drag the `ɔ` character to the ` ## Understanding Keyman Code -Keyman’s Visual Editor (the `Design` tab) is helpful in assigning characters to keys in a consistent manner. For a simple keyboard, it may be all that you need. It’s likely, however, that you’ll need to use the `Code` tab to provide the logic needed for your keyboard. +Keyman’s Visual Editor (the `Design` mode of the `Layout` tab) is helpful in assigning characters to keys in a consistent manner. For a simple keyboard, it may be all that you need. It’s likely, however, that you’ll need to use the `Code` tab to provide the logic needed for your keyboard. When you begin an new project (using the “Project” menu, “New Project” menu item), Keyman Developer initializes your `.kmn` file. With the `Layout` tab on the left selected, you will see two small tabs at the bottom of the window: the `Design` tab and the `Code` tab. @@ -142,7 +148,7 @@ group(main) using keys The `store()` statements at the top are called the “header” of your file. This is where the important information about your keyboard is stored. -A summary of the elements of the Keyman header can be found in part of [another tutorial](https://help.keyman.com/developer/18.0/guides/develop/tutorial/step-3) and detailed information is in the official Keyman documentation: +A summary of the elements of the Keyman header can be found in the [language guide](https://help.keyman.com/developer/language/guide/headers) and detailed information is in the official Keyman documentation: - [&version](https://help.keyman.com/developer/language/reference/version) - [&name](https://help.keyman.com/developer/language/reference/name) @@ -182,7 +188,7 @@ There are a few key terms that you must know when writing rules: **Context** The context specifies the conditions that will trigger a rule. -If the character(s) to the left of the cursor match the context of a rule, the rule will be processed by Keyman. +If the character(s) prior to the cursor match the context of a rule, the rule will be processed by Keyman. **Key** @@ -193,9 +199,9 @@ For more information on keys and keystrokes, read the [official Keyman documenta The output determines which characters are produced by a rule. When a rule is processed, Keyman will replace the context with the output. -The Context (which may be empty) is separated from the Key by “+”. +The Context (which may be empty) is separated from the Key by `+`. -The Key is separated from the Output by “>”. +The Key is separated from the Output by `>`. You can include comments in your Keyman code by typing a plain `c` followed by a space then any text you like afterwards. (If you want the letter “c”, you must surround in in quotes like `"c"`.) This is a good way to document your code and make things easier to read later, both for yourself and others. Comments can be made at the end of a line (with a space before the `c` as well as after) or be on their own line. Any text that follows the `c` through the end of the line will be ignored when the keyboard is compiled. @@ -204,7 +210,7 @@ Writing rules in Keyman is very straightforward for simple key substitutions. Su `"^" + "a" > "â"` In this example, the **context** is `^`, the **key** is `a`, and the **output** is `â`. -Whenever Keyman finds the context (`^`) to the left of the cursor and the current keystroke is `a`, it will replace the context (and the typed character) with `â`. +Whenever Keyman finds the context (`^`) prior to the cursor and the current keystroke is `a`, it will replace the context (and the typed character) with `â`. Characters written into Keyman code should always be surrounded by single quotes (`' '`) or double quotes (`" "`). Either pair will work (as long as they match). @@ -275,7 +281,7 @@ You can read more about the `store`, `index` and `any` keywords in the [Keyman l ### Deadkeys -At the end of the previous topic, an example was given of using the “;” key as a “deadkey”. Typing the deadkey produces no output, but it potentially changes the output of the following key. Changing the first two rules from the Step-by-Step example to treat the “;” as a deadkey, would result in: +At the end of the previous topic, an example was given of using the ; key as a “deadkey”. Typing the deadkey produces no output, but it potentially changes the output of the following key. Changing the first two rules from the Step-by-Step example to treat the ; as a deadkey, would result in: ```keyman + ";" > dk(1) c Define ";" as a deadkey @@ -308,6 +314,8 @@ It is also possible to create an on-screen layout automatically based on what yo - Select the `Fill from layout` button above the keyboard image - Check the results. +The On-Screen Keyboard editor looks very similar to the `Design` mode of the `Layout` tab. Most of the time, the key caps will be the same as in the `Design` mode of the `Layout` tab, but sometimes it might be helpful to display something different than what is actually produced. If, for example, the character being produced is not visible, such as a no-break space or a right-to-left mark, it might be helpful to display `NBSP` or `RTL` or some symbol to remind the user what the key produces. + ## Exporting an On-Screen Keyboard Layout One way to document a keyboard layout is to use images of the keyboard showing the different layers: default layer, Shift layer, Right-Alt layer, etc. @@ -322,6 +330,6 @@ Then complete the information needed: - Select `Save` - In the `Output Bitmap Parameters` dialog, select `One file per shift state`, `Output Unicode keyboards`, and adjust the width of the image as needed, then select `OK`. Keyman Developer will create one or more files using the base filename plus letters to indicate the shift state plus `.png`. You can reference these files in your welcome.htm file. -[< Back: Part 2 - Designing a Desktop Layout](02-designing-desktop-layout) - -[Next: Part 4 - Using the Debugger >](04-using-debugger) \ No newline at end of file +
+[← Part 2 - Designing a Desktop Layout](02-designing-desktop-layout)   [Part 4 - Using the Debugger →](04-using-debugger) +
\ No newline at end of file diff --git a/developer/docs/help/guides/develop/walkthrough/04-using-debugger.md b/developer/docs/help/guides/develop/walkthrough/04-using-debugger.md index 86fc2b6c469..a86917754ed 100644 --- a/developer/docs/help/guides/develop/walkthrough/04-using-debugger.md +++ b/developer/docs/help/guides/develop/walkthrough/04-using-debugger.md @@ -1,10 +1,13 @@ -# Using the Debugger - -Part 4 of the [Keyman Developer Walkthrough](../walkthrough). +--- +title: Using the Debugger +--- -[< Back: Part 3 - Creating a Desktop Layout](03-creating-desktop-layout) + +
+Part 4 of the [Keyman Developer Walkthrough](.). -[Next: Part 5 - Designing a Touch Layout >](05-designing-touch-layout) +[← Part 3 - Creating a Desktop Layout](03-creating-desktop-layout)   [Part 5 - Designing a Touch Layout →](05-designing-touch-layout) +
## Step-by-Step @@ -17,18 +20,20 @@ Part 4 of the [Keyman Developer Walkthrough](../walkthrough). - From the `Debug` menu, select the `Stop Debugger` menu item. +
To continue the Step-by-Step tutorial move to the next page: [Part 5 - Designing a Touch Layout](05-designing-touch-layout) +
--- ## Running the Debugger -See [https://help.keyman.com/developer/current-version/context/debug](https://help.keyman.com/developer/current-version/context/debug) for more information on running the debugger. +See the [debugger documentation](../../../context/debug) for more information on running the debugger. ## Interpreting Errors When compiling your Keyman code, Keyman Developer will report any errors, warnings and hints in the box at the bottom of the window. The message will give a short description of what the compiler found was wrong along with the line number of where the problem was detected. The error, warning or hint has an identifier (“KM02033” for example). This identifier is a link to a more detailed description. -[< Back: Part 3 - Creating a Desktop Layout](03-creating-desktop-layout) - -[Next: Part 5 - Designing a Touch Layout >](05-designing-touch-layout) \ No newline at end of file +
+[← Part 3 - Creating a Desktop Layout](03-creating-desktop-layout)   [Part 5 - Designing a Touch Layout →](05-designing-touch-layout) +
\ No newline at end of file diff --git a/developer/docs/help/guides/develop/walkthrough/05-designing-touch-layout.md b/developer/docs/help/guides/develop/walkthrough/05-designing-touch-layout.md index cd8fee607b0..acc2f9d6d53 100644 --- a/developer/docs/help/guides/develop/walkthrough/05-designing-touch-layout.md +++ b/developer/docs/help/guides/develop/walkthrough/05-designing-touch-layout.md @@ -2,11 +2,12 @@ title: Designing a Touch Layout --- -Part 5 of the [Keyman Developer Walkthrough](../walkthrough). + +
+Part 5 of the [Keyman Developer Walkthrough](.). -[< Back: Part 4 - Using the Debugger](04-using-debugger) - -[Next: Part 6 - Creating a Touch Layout >](06-creating-touch-layout) +[← Part 4 - Using the Debugger](04-using-debugger)   [Next: Part 6 - Creating a Touch Layout →](06-creating-touch-layout) +
## Step-by-Step @@ -14,7 +15,9 @@ In the Dagbani keyboard, `;e` was selected as the way to generate the character For the Step-by-Step tutorial, the design decisions have been made for you. We will be adding ten longpress keys to the default touch layout. +
To continue the Step-by-Step tutorial move to the next page: [Part 6 - Creating a Touch Layout](06-creating-touch-layout) +
--- @@ -44,7 +47,8 @@ If you use Keyman Developer’s New Project feature, a touch layout is added aut There are advantages to basing the touch layout on the desktop layout. Users who switch between the two may benefit from the similarity. In addition, your touch layout may be able to take advantage of the logic in the desktop layout code you’ve already created. -Specifically, if the `ID` field for a key in the touch layout begins with `K_` then the Keyman processes the keystroke information (as modified by the active layer of the touch layout) according to what is in the .kmn file. +Specifically, if the `ID` field for a key in the touch layout begins with `K_` then Keyman treats the key as the same as the corresponding desktop key (as modified by the active layer of the touch layout) +according to the rules that are in the .kmn file. If you establish the desktop keyboard layout and create the On-Screen Keyboard, you can switch to the Touch Editor and import from the OSK. @@ -53,6 +57,6 @@ To switch to a “phone” layout, select the basic template, which rearranges t (For more details, see the next topic.) The result will need to be reviewed and tested, but using this approach may save you some time. -[< Back: Part 4 - Using the Debugger](04-using-debugger) - -[Next: Part 6 - Creating a Touch Layout >](06-creating-touch-layout) \ No newline at end of file +
+[← Part 4 - Using the Debugger](04-using-debugger)   [Part 6 - Creating a Touch Layout →](06-creating-touch-layout) +
\ No newline at end of file diff --git a/developer/docs/help/guides/develop/walkthrough/06-creating-touch-layout.md b/developer/docs/help/guides/develop/walkthrough/06-creating-touch-layout.md index e820856f7ee..b4fab0a85c0 100644 --- a/developer/docs/help/guides/develop/walkthrough/06-creating-touch-layout.md +++ b/developer/docs/help/guides/develop/walkthrough/06-creating-touch-layout.md @@ -2,11 +2,12 @@ title: Creating a Touch Layout --- -Part 6 of the [Keyman Developer Walkthrough](../walkthrough). + +
+Part 6 of the [Keyman Developer Walkthrough](.). -[< Back: Part 5 - Designing a Touch Keyboard](05-designing-touch-layout) - -[Next: Part 7 - Writing Keyboard Documentation Files >](07-writing-keyboard-documentation) +[← Part 5 - Designing a Touch Keyboard](05-designing-touch-layout)   [Part 7 - Writing Keyboard Documentation Files →](07-writing-keyboard-documentation) +
## Step-by-Step @@ -73,7 +74,9 @@ Keyman Developer provides a way to test your keyboard in a web browser. - If you click on the `Shift` key, the display changes to the `shift` layer and you can enter characters from that layer. - When you are finished testing, you can close the browser tab. +
To continue the Step-by-Step tutorial move to the next page: [Part 7 - Writing Keyboard Documentation Files](07-writing-keyboard-documentation) +
--- @@ -140,12 +143,12 @@ Use care when combining different kinds of gestures as some of them may conflict ## Reference -See [https://help.keyman.com/developer/current-version/context/keyboard-editor#toc-touch-layout-tab](https://help.keyman.com/developer/current-version/context/keyboard-editor#toc-touch-layout-tab) for more details. +See [Touch layout editor documentation](../../../context/keyboard-editor#toc-touch-layout-tab) for more details. ## Testing Touch Keyboards See the end of the Step-by-Step section above for a description of how to use Keyman Developer to test your touch layout in a browser window. It’s also possible to transfer the .kmp file to a touch device and install the keyboard there for testing. -[< Back: Part 5 - Designing a Touch Keyboard](05-designing-touch-layout) - -[Next: Part 7 - Writing Keyboard Documentation Files >](07-writing-keyboard-documentation) \ No newline at end of file +
+[← Part 5 - Designing a Touch Keyboard](05-designing-touch-layout)   [Part 7 - Writing Keyboard Documentation Files →](07-writing-keyboard-documentation) +
\ No newline at end of file diff --git a/developer/docs/help/guides/develop/walkthrough/07-writing-keyboard-documentation.md b/developer/docs/help/guides/develop/walkthrough/07-writing-keyboard-documentation.md index e64ba5163c0..13d70cb3175 100644 --- a/developer/docs/help/guides/develop/walkthrough/07-writing-keyboard-documentation.md +++ b/developer/docs/help/guides/develop/walkthrough/07-writing-keyboard-documentation.md @@ -2,11 +2,12 @@ title: Writing Keyboard Documentation --- -Part 7 of the [Keyman Developer Walkthrough](../walkthrough). + +
+Part 7 of the [Keyman Developer Walkthrough](.). -[< Back: Part 6 - Creating a Touch Layout](06-creating-touch-layout) - -[Next: Part 8 - Preparing a Keyboard Package >](08-preparing-keyboard-package) +[← Part 6 - Creating a Touch Layout](06-creating-touch-layout)   [Part 8 - Preparing a Keyboard Package →](08-preparing-keyboard-package) +
## Step-by-Step @@ -39,7 +40,9 @@ Part 7 of the [Keyman Developer Walkthrough](../walkthrough). - Close the welcome.htm file. Click “Yes” to save the changes. +
To continue the Step-by-Step tutorial move to the next page: [Part 8 - Preparing a Keyboard Package](08-preparing-keyboard-package) +
## Editing the README.md file @@ -105,6 +108,6 @@ The Keyman keyboards repository requires that this PHP file have the name of the The PHP help file often contains the same information as is in the welcome.htm file. See [Keyman Keyboard help document (PHP help file)](https://help.keyman.com/developer/keyboards/phphelpfile) for more details. -[< Back: Part 6 - Creating a Touch Layout](06-creating-touch-layout) - -[Next: Part 8 - Preparing a Keyboard Package >](08-preparing-keyboard-package) \ No newline at end of file +
+[← Part 6 - Creating a Touch Layout](06-creating-touch-layout)   [Part 8 - Preparing a Keyboard Package →](08-preparing-keyboard-package) +
\ No newline at end of file diff --git a/developer/docs/help/guides/develop/walkthrough/08-preparing-keyboard-package.md b/developer/docs/help/guides/develop/walkthrough/08-preparing-keyboard-package.md index 63be79445a6..9bd0956cdb5 100644 --- a/developer/docs/help/guides/develop/walkthrough/08-preparing-keyboard-package.md +++ b/developer/docs/help/guides/develop/walkthrough/08-preparing-keyboard-package.md @@ -2,11 +2,12 @@ title: Preparing a Keyboard Package --- -Part 8 of the [Keyman Developer Walkthrough](../walkthrough). + +
+Part 8 of the [Keyman Developer Walkthrough](.). -[< Back: Part 7 - Writing Keyboard Documentation](07-writing-keyboard-documentation) - -[Next: Part 9 - Distributing a Keyboard Package >](09-distributing-keyboard-package) +[← Part 7 - Writing Keyboard Documentation](07-writing-keyboard-documentation)   [Part 9 - Distributing a Keyboard Package →](09-distributing-keyboard-package) +
## Step-by-Step @@ -20,13 +21,15 @@ Part 8 of the [Keyman Developer Walkthrough](../walkthrough). - Select the `Build` tab, then the `Compile Package` button. A **dagbani.kps built successfully** message should be displayed. - Congratulations! You have successfully built and packaged a keyboard for the Dagbani language. +
To continue the Step-by-Step tutorial move to the next page: [Part 9 - Distributing a Keyboard Package](09-distributing-keyboard-package) +
--- ## Package Files -See the [Keyman Package Editor documentation](https://help.keyman.com/developer/18.0/context/package-editor) if you need more details on the following items. +See the [Keyman Package Editor documentation](../../../context/package-editor) if you need more details on the following items. ### Files @@ -58,6 +61,6 @@ Here is where you can enter information for: - Image file: If you supply a 140 pixel wide x 250 pixel high image in JPEG or PNG format, then your custom image will be shown during installation (in place of the default Keyman image). Your image file must be added to the Files list before it will be available to be selected here. - Related packages: If your keyboard is part of a group of keyboards, you can specify which other keyboards are part of the group. (For example, you might have three keyboards for the same language, one based on the QWERTY layout, one AZERTY, one QWERTZ, and you could use this field to note the relationship between them.) You can also use this feature to deprecate another keyboard that your keyboard supersedes. -[< Back: Part 7 - Writing Keyboard Documentation](07-writing-keyboard-documentation) - -[Next: Part 9 - Distributing a Keyboard Package >](09-distributing-keyboard-package) \ No newline at end of file +
+[← Part 7 - Writing Keyboard Documentation](07-writing-keyboard-documentation)   [Part 9 - Distributing a Keyboard Package →](09-distributing-keyboard-package) +
\ No newline at end of file diff --git a/developer/docs/help/guides/develop/walkthrough/09-distributing-keyboard-package.md b/developer/docs/help/guides/develop/walkthrough/09-distributing-keyboard-package.md index 1580d9d2fd5..1a38688018d 100644 --- a/developer/docs/help/guides/develop/walkthrough/09-distributing-keyboard-package.md +++ b/developer/docs/help/guides/develop/walkthrough/09-distributing-keyboard-package.md @@ -2,25 +2,28 @@ title: Distributing a Keyboard Package --- -Part 9 of the [Keyman Developer Walkthrough](../walkthrough). + +
+Part 9 of the [Keyman Developer Walkthrough](.). -[< Back: Part 8 - Preparing a Keyboard Package](08-preparing-keyboard-package) - -[Next: Part 10 - Generating a Lexical Model >](10-generating-lexical-model) +[← Part 8 - Preparing a Keyboard Package](08-preparing-keyboard-package)   [Part 10 - Generating a Lexical Model →](10-generating-lexical-model) +
## Step-by-Step For the Step-by-Step tutorial, there’s really nothing to do for this page. This tutorial is for learning only, therefore you don't want to submit this keyboard to the Keyman keyboards repository (since it already contains a keyboard by that name). If you like, you could look at the other sections on this page before continuing the Step-by-Step tutorial (or come back to them later). +
To continue the Step-by-Step tutorial move to the next page: [Part 10 - Generating a Lexical Model](10-generating-lexical-model) +
--- ## Submitting a keyboard to the Keyman Keyboards Repository -Follow the instructions at [https://help.keyman.com/developer/keyboards/](https://help.keyman.com/developer/keyboards/) to submit your keyboard to the Keyman keyboards repository. This will enable anyone with Internet access to download and use the keyboard. (Please do not submit the Dagbani keyboard used in the Step-by-Step tutorial. There is already a Dagbani keyboard in the repository.) +Follow the instructions at [Working with the Keyman Cloud Keyboard Repository](https://help.keyman.com/developer/keyboards/) to submit your keyboard to the Keyman keyboards repository. This will enable anyone with Internet access to download and use the keyboard. (Please do not submit the Dagbani keyboard used in the Step-by-Step tutorial. There is already a Dagbani keyboard in the repository.) -One requirement for keyboards that are submitted to the Keyman keyboards repository is the addition of a PHP help file that provides the online help available on the keyman.com site. See the **Editing the PHP help file** section of the [Writing Keyboard Documentation](07-writing-keyboard-documentation) page for more details. +One requirement for keyboards that are submitted to the Keyman keyboards repository is the addition of a PHP help file that provides the online help available on the keyman.com site. See the **Editing the PHP help file** section of the [Writing Keyboard Documentation](07-writing-keyboard-documentation#toc-editing-the-php-help-file) page for more details. ## Other Distribution Methods @@ -30,6 +33,6 @@ With Keyman Developer running, it’s possible to select `Packaging`, and the `. The Keyboard App Builder (KAB) lets you put a Keyman keyboard (and optionally a lexical model) into an app for iOS or Android, which can be distributed. More details can be found on the [Keyboard App Builder](https://software.sil.org/keyboardappbuilder/) page. -[< Back: Part 8 - Preparing a Keyboard Package](08-preparing-keyboard-package) - -[Next: Part 10 - Generating a Lexical Model >](10-generating-lexical-model) \ No newline at end of file +
+[← Part 8 - Preparing a Keyboard Package](08-preparing-keyboard-package)   [Part 10 - Generating a Lexical Model →](10-generating-lexical-model) +
\ No newline at end of file diff --git a/developer/docs/help/guides/develop/walkthrough/10-generating-lexical-model.md b/developer/docs/help/guides/develop/walkthrough/10-generating-lexical-model.md index 8902f8dda4d..a946ded54f0 100644 --- a/developer/docs/help/guides/develop/walkthrough/10-generating-lexical-model.md +++ b/developer/docs/help/guides/develop/walkthrough/10-generating-lexical-model.md @@ -2,11 +2,12 @@ title: Generating a Lexical Model --- -Part 10 of the [Keyman Developer Walkthrough](../walkthrough). + +
+Part 10 of the [Keyman Developer Walkthrough](.). -[< Back: Part 9 - Distributing a Keyboard Package](09-distributing-keyboard-package) - -[Next: Part 11 - Installing a Keyman Lexical Model >](11-installing-lexical-model) +[← Part 9 - Distributing a Keyboard Package](09-distributing-keyboard-package)   [Part 11 - Installing a Keyman Lexical Model →](11-installing-lexical-model) +
## Step-by-Step @@ -39,7 +40,7 @@ In addition, the list of words should be reviewed. - In this tutorial, we're going to open a file, copy its contents, then paste those lines into the `wordlist.tsv` file to replace the default content. Depending on how your browser is configured, when you open the file, it may open in a new tab or it may open in the same tab as this set of instructions. In the first case you can close the tab to return here, but in the second case you'll need to use the Back feature of your browser. (You may want to read ahead to make sure you understand the next few steps since the instructions might be hidden temporarily.) - Click on the **dag-short-wl.txt** filename just below this paragraph to open the file (or right-click and select Open in a new tab). -[dag-short-wl.txt](./dag-short-wl.txt) + * [dag-short-wl.txt](./dag-short-wl.txt) - Use Ctrl+A to select the entire contents and Ctrl+C to copy the selected text. - Return to these instructions, either with the browser's Back feature, or by closing the newly opened tab, as appropriate. @@ -79,7 +80,9 @@ In addition, the list of words should be reviewed. - Select the `Build` tab on the left. Then select the `Compile Package` button. Verify that you get the **sil.dag.wl.model.kps built successfully** message. - Congratulations! You have successfully built and packaged a lexical model for the Dagbani language. +
To continue the Step-by-Step tutorial move to the next page: [Part 11 - Installing a Keyman Lexical Model](11-installing-lexical-model) +
## Introduction @@ -149,13 +152,13 @@ Keyman will place you in your `.kpj` file immediately, as with a keyboard projec Currently `Wordlist (trie-1.0)` is the only choice for the `Format` field. -You’ll normally want to keep the `default` choice for the `Word breaker` field and the `(Space U+0020)` option for the `Insert after word` field, unless you are dealing with an orthography that doesn’t use space to separate words. For scripts such as Khmer, Thai, and Lao, which have special ways to delimit words, see the Keyman documentation on [coding a custom word breaker](https://help.keyman.com/developer/current-version/guides/lexical-models/advanced/word-breaker). +You’ll normally want to keep the `default` choice for the `Word breaker` field and the `(Space U+0020)` option for the `Insert after word` field, unless you are dealing with an orthography that doesn’t use space to separate words. For scripts such as Khmer, Thai, and Lao, which have special ways to delimit words, see the Keyman documentation on [coding a custom word breaker](../../../guides/lexical-models/advanced/word-breaker). You can specify the opening and closing quotation marks, and whether the language is using a right-to-left script (such as Arabic, Hebrew, Syriac, etc.) If your language uses a script with uppercase and lowercase (such as Latin, Cyrillic, Greek, etc.) you probably will want to enable the `Language uses casing` checkbox, so that Keyman will take casing into account when matching and suggesting words. For example, if you start typing `Rab`, Keyman will propose `Rabbit` rather than `rabbit`. -The Keyman site has more details on [advanced topics](https://help.keyman.com/developer/17.0/guides/lexical-models/advanced/word-breaker). +The Keyman site has more details on [advanced topics](../../../guides/lexical-models/advanced/word-breaker). ## Editing Wordlists @@ -166,7 +169,7 @@ Keyman provides a default `wordlist.tsv` file for you as an example. You can rep For a newly created project, the only wordlist present is `wordlist.tsv`. If you open that file, you'll see some sample data included as an illustration. -For advanced information on Keyman wordlist file formats and exporting your own wordlist files, read the [TSV file documentation](https://help.keyman.com/developer/17.0/reference/file-types/tsv). +For advanced information on Keyman wordlist file formats and exporting your own wordlist files, read the [TSV file documentation](../../../reference/file-types/tsv). ### Ignored lines @@ -262,7 +265,7 @@ For the purposes of this tutorial, we’ve provided a sample text that you can d The sample text is a collection of folktales for the Fulfulde language. Right-click on the **Anduna_anndaaka.txt** link below and select `Save link as` and navigate to a folder where you can save the file and work on it. After you have deleted some unneeded words from the file you'll use PrimerPrep to create a wordlist file that you will then include in the `source` folder of your lexical model project. -[Aduna_anndaaka.txt](./Aduna_anndaaka.txt) +* [Aduna_anndaaka.txt](./Aduna_anndaaka.txt) ### File Preparation @@ -368,6 +371,6 @@ Note: The text provided for this tutorial is already in a `.txt` file format. Fo ![](images/windows-save-txt.png) -[< Back: Part 9 - Distributing a Keyboard Package](09-distributing-keyboard-package) - -[Next: Part 11 - Installing a Keyman Lexical Model >](11-installing-lexical-model) +
+[← Part 9 - Distributing a Keyboard Package](09-distributing-keyboard-package)   [Part 11 - Installing a Keyman Lexical Model →](11-installing-lexical-model) +
\ No newline at end of file diff --git a/developer/docs/help/guides/develop/walkthrough/11-installing-lexical-model.md b/developer/docs/help/guides/develop/walkthrough/11-installing-lexical-model.md index 2531ab71e67..02d7594421a 100644 --- a/developer/docs/help/guides/develop/walkthrough/11-installing-lexical-model.md +++ b/developer/docs/help/guides/develop/walkthrough/11-installing-lexical-model.md @@ -2,9 +2,12 @@ title: Installing a Keyman Lexical Model --- + +
Part 11 of the [Keyman Developer Walkthrough](../walkthrough). -[< Back: Part 10 - Generating a Lexical Model](10-generating-lexical-model) +[← Part 10 - Generating a Lexical Model](10-generating-lexical-model) +
## Step-by-Step @@ -18,7 +21,7 @@ This concludes the walkthrough. Hopefully it has given you an overview of the en ## Submitting a lexical model to the Keyman Lexical Models Repository -Follow the instructions at [https://help.keyman.com/developer/lexical-models/](https://help.keyman.com/developer/lexical-models/) to submit your lexical model to the Keyman lexical models repository. This will enable anyone with Internet access to download and use the lexical model. (Please do not submit the Dagbani lexical model used in the Step-by-Step tutorial. It’s really not suitable for submission to the repository.) +Follow the instructions at [Working with the Keyman Cloud Lexical Models Repository](https://help.keyman.com/developer/lexical-models/) to submit your lexical model to the Keyman lexical models repository. This will enable anyone with Internet access to download and use the lexical model. (Please do not submit the Dagbani lexical model used in the Step-by-Step tutorial. It’s really not suitable for submission to the repository.) Once the lexical model has been published, any Android or iOS device with Keyman installed and access to the Internet should be able to access and load the lexical model for use with a keyboard with the same language tag (BCP 47 code) as the lexical model. @@ -29,4 +32,6 @@ If an Android or iOS device has access to the Keyman package file (.kmp) that co As mentioned earlier, the Keyboard App Builder (KAB) lets you put a Keyman keyboard along with a lexical model into an app for iOS or Android, which can be distributed. More details can be found on the [Keyboard App Builder](https://software.sil.org/keyboardappbuilder/) page. -[< Back: Part 10 - Generating a Lexical Model](10-generating-lexical-model) \ No newline at end of file +
+[← Part 10 - Generating a Lexical Model](10-generating-lexical-model) +
diff --git a/developer/docs/help/guides/develop/walkthrough/__index.txt b/developer/docs/help/guides/develop/walkthrough/__index.txt new file mode 100644 index 00000000000..2bb307d6f92 --- /dev/null +++ b/developer/docs/help/guides/develop/walkthrough/__index.txt @@ -0,0 +1,13 @@ +00-introduction.md +01-creating-keyboard-project.md +02-designing-desktop-layout.md +03-creating-desktop-layout.md +04-using-debugger.md +05-designing-touch-layout.md +06-creating-touch-layout.md +07-writing-keyboard-documentation.md +08-preparing-keyboard-package.md +09-distributing-keyboard-package.md +10-generating-lexical-model.md +11-installing-lexical-model.md +glossary.md diff --git a/developer/docs/help/guides/develop/walkthrough/images/code-tab.png b/developer/docs/help/guides/develop/walkthrough/images/code-tab.png index 9e55f71e17c..2bf03001016 100644 Binary files a/developer/docs/help/guides/develop/walkthrough/images/code-tab.png and b/developer/docs/help/guides/develop/walkthrough/images/code-tab.png differ diff --git a/developer/docs/help/guides/develop/walkthrough/walkthrough.css b/developer/docs/help/guides/develop/walkthrough/walkthrough.css new file mode 100644 index 00000000000..f1027498afa --- /dev/null +++ b/developer/docs/help/guides/develop/walkthrough/walkthrough.css @@ -0,0 +1,16 @@ +.walkthrough-navigation { + display: block; + clear: both; + background: #eeeeee; + border-radius: 8px; +} + +.walkthrough-navigation::before { + content: "Keyman Developer Walkthrough"; + display: block; + background: #cccccc; + border-radius: 8px 8px 0 0; + padding: 6px 10px 6px; + font-size: 10pt; + margin-bottom: 8px; +} \ No newline at end of file