keymanapp / help.keyman.com Goto Github PK

Per https://community.software.sil.org/t/android-fatal-error-loading-keyboard/3043/8

Details on default paths (eg. build/ etc) for .js and .kmx etc would be helpful.

There may be references elsewhere as well?

The nextlayer declaration in touch layouts overrides the layer() command in kmn files.

This should be documented here:

• https://help.keyman.com/developer/12.0/guides/develop/creating-a-touch-keyboard-layout-for-amharic-the-nitty-gritty
• https://help.keyman.com/developer/language/reference/layer

This is (at least partially) a keyboard coding/design error. From the .touch_layout file:

              {
                "id": "K_BKSP",
                "text": "*BkSp*",
                "sp": "1",
                "nextlayer": "default"
              }

This block appears quite a number of times, including for the default layer. Interestingly, this does not appear in the numeric layer. The BKSP from the numeric layer still works properly as a result.

About touch-layout vs. kmn precedence, I think the existing behavior is fine (touch-layout overrides kmn), however, this must be documented somewhere. So let's call it a documentation bug 😅

Originally posted by @eddieantonio in keymanapp/keyman#2349 (comment)

History will be now stored in https://downloads.keyman.com/history/HISTORY.md. Just the one file. The format of the file, is approximately:

# Keyman Version History

## <version> <tier> <yyyy-mm-dd>
<type>[(<scope>[/<sub-scope>)]: title [(#<prnum>)]

For example:

# Keyman Version History

## 14.0.4 alpha 2020-02-03

chore(ci): trigger builds after version increment (#2572)

We need to parse this for presenting history to users for version 14.0 and later. A single history view covering all platforms is appropriate -- sort the entries by scope to make it easier to read.

Four things we can tidy up.

• Remove .php extension from local links. There are thousands of links that need work here so sensible regex or script will be needed. Note: a regex can get a little hairy due to quote differences (' vs "), anchors (e.g. #foo), non-local links (starting with http:), whitespace.
• Change http -> https where possible in links. Required for keyman sites, probably good for others.
• Remove target="_blank" from links. Particularly for internal links.
• Remove http[s]://help.keyman.com/ prefix from links. Be aware that some of this content may be repurposed (e.g. /products/android content) so we may need absolute links in those areas.

This relates to responsive design of page; see https://help.keyman.com/developer/cloud/keyboard_info/1.0/ for example

The beginning of the language guide would be clearer with a sample keyboard file labeling the different parts.

For example (should be redone by someone with better graphic skills).

It would be good to have a "how to contribute" document on the help site that goes through the step-by-step process of submitting a PR via the online editor in GitHub.

Alternatively, research the concept of an "Edit" button at the bottom of the screen -- near the feedback button -- that pops a HTML/MD editor and automatically submits a PR on the resultant edit. There are probably tools to do this.

I've copied from an earlier comment the outstanding TODO items:

• I'll write documentation about how to run the lexical model compiler
• I'll move the "advanced model configuration" to somewhere that is NOT the tutorial, as that assumes people know how to write TypeScript code :/

And from this comment:

• How do I compile a lexical model?
  • Blocker: requires a standalone model compiler keymanapp/keyman#1983, keymanapp/keyman#1986
• How do I test a lexical model?
• How do I package a lexical model?
  • Blocker: Requires support in Keyman Developer keymanapp/keyman#1977, keymanapp/keyman#2024
• How do I share my lexical model with Keyman's API? Done: https://help.keyman.com/developer/lexical-models/

Originally posted by @mcdurdin in #32 (comment)

On https://help.keyman.com/DEVELOPER/12.0/guides/develop/touch-keyboard-tutorial/
There's a broken link to the Quick French Tutorial

I'm pretty sure issue also appears in Developer guides 10.0 - 12.0

https://help.keyman.com/products/linux is missing.

• Keyman Language History is not updated with 11.0, 12.0, 13.0 changes:
  developer\language\guide\history.php

While reviewing #159, I noticed the left index has some items to clean up
http://help.keyman.com.local/developer/videos or
https://help.keyman.com/developer/sample_template

1. I believe the sample_template is not intended to be displayed on the site (engineering reference)
2. The two generic "index" links go to Developer 6.0 and 8.0 content

https://help.keyman.com/troubleshooting/browsers

It looks like it hasn't been touched since 2009:

https://github.com/keymanapp/help.keyman.com/blob/eeb8c0ac35560943bfa653050262168deff13c88/troubleshooting/browsers.php

I think the best option is simply to delete this page; or else, we'd have to have some DRY way to get the current supported platforms, so that this page does not require manual maintenance.

• Add a Markdown to HTML preprocessor
• Reformat each KB article as Markdown
• Setup web.config to redirect /kb/xxxx to appropriate /kb/index.php?id=xxxx to load the markdown.
• Setup redirects from tavultesoft.com

From keymanapp/keyboards#252:

@LornaSIL writes:

I would recommend that we remove deprecated keyboard help files from this page: http://https//help.keyman.com/keyboard/. The page is already a bit unwieldy and will get worse as we keep adding newer keyboards. The main (deprecated) keyboard page itself will still link to the deprecated help page.

@mcdurdin responds:

To remove the deprecated items from the main index (or have them under a secondary index so that they can still be easily crawled if necessary), we'll need to do some work on help.keyman.com.

As seen at https://help.keyman.com/keyboard/itrans_odia/1.0.0/itrans_odia.php, the CSS styling for kbd elements uses 'sans-serif' as the font, which doesn't distinguish between l and I:

http://help.keyman.com/products/desktop/9.0/docs/basic_options_tab.php This page is missing details on Base Keyboard.

This should be resolved in the Keyman 10 Documentation.

See #35

• For example, the Desktop version history link on https://help.keyman.com/products/desktop/current-version/docs/about_history does not currently work.
• The /version-history/ page does not appear to have easy to find links anywhere.

https://help.keyman.com/DEVELOPER/12.0/reference/file-types/ should include file format details for all files, in particular the source files. Especially important is .keyman-touch-layout and .kvks.

A note from the Keyman Consultation Training workshop:

From @sewhite: "put that summary of why changing the keycap for mobile does not change the key's output in the developer documentation"

• it'd be nice to have an option to import the keycap and turn that into the key's representation code. (U_xxxx )

@jahorton writes

To streamline maintenance for each product's history page and ensure consistency, it should be built dynamically from the corresponding history.md file in the public repo.

Said files will use the format specified in this document.

From developer discussion on packaging KMFL vs Keyman for Linux with 20.04 LTS

Question raised: Are current KMFL users expected to easily migrate to Linux Keyman, or is that not super smooth and people would be easily expected to continue using KMFL for a while?

Given there's current feedback from users that still use KMFL with their .kmn keyboards

@mcdurdin writes

It might be good to document the transition process from KMFL to Keyman - keyboards, setup and more

Some possible steps:

1. Use kmcomp to compile .kmn to .kmx
2. Use a TBD script to generate a bare .kps package source file (XML) containing the .kmx file.

Considerations:
How to search for .kmn files (user home or system directories?)

In the original design, Keyman was supposed to fall back to shorter tags when searching for an appropriate model, e.g. en-AU would be searched first, then en. This meant that a US English model should have en-US and en BCP-47 tags assigned. Or, tpi-Latn-PG -> tpi-Latn -> tpi-PG -> tpi (i.e. script has heavier weight than region in search). That level of detail probably doesn't belong on this page but does belong somewhere in the docs.

I'm not sure we ever implemented this? If not, please turn this into an issue :)

Originally posted by @mcdurdin in #44

You, got it, Marc ;)

Via email:

Ah, I see the links on the desktop browser on Windows. I've been doing a
lot of reading using my Android device and the Support and Edit page
links don't show up in Firefox or Chrome even when "Request desktop
site" or "Desktop site" is checked.

Marc wrote:

Note that you can also edit the page yourself by clicking the Edit
Page link at the bottom of the page, especially for small things like
this; it just needs to be approved by someone on the team and then it
merges in automatically.

from @mcdurdin

This is a collection of known documentation gaps in Keyman Developer, collected from a variety of locations. When the time is ripe, they can be split out into separate issues as needed.

• Update content to use <kbd> and <samp> elements. This way we get nice formatting for keys and sample text
• Remove class="xref", class=”link”, from <a> and type=”disc” from ul elements
• Analyse all headers in reference documentation for consistency (Inconsistent use of <h1>, <h2> etc. Also content within headers in Reference sections is inconsistent.)
• Add a banner to 6.0, 7.0, 8.0 docs to note that they are old. If possible, include a link to latest version of doc.
• Make this search engine aware, with meta to indicate old content. So search engines prioritise the latest content?
• Package tutorial needs rewrite with regard to Keyman Cloud keyboard repository; to encourage good design…
• Rewrite 8.0 keyboard developer guide
• The keyboard metadata .json file format needs a reference page in /developer/somewhere/
• kmw_embedcss needs docs on css rules that are sensible to use
• kmw_embedjs needs docs on js API and guide on interacting with KMW (mobile, embedded, desktop)
• Document deep linking keyman: protocol for all Keyman Engine platforms (also see sillsdev/keyman#52)

from @DavidLRowe
(1) On the page: http://help.keyman.com/developer/9.0/guides/develop/tutorial/step-7, there's a very minor change to the French text:

'Alors Alice demanda, "O est ma chatte?"'

I think O should be Où (and Ö should be Öù in the later line).

(2) On the page: http://help.keyman.com/developer/9.0/guides/develop/advanced-keyboard-development-example

Specifying "(such as Gentium)" could be a minor problem, since the original Gentium font isn't readily available. One is more likely to find "Gentium Basic" or "Gentium Plus". An alternative would be Doulos SIL or Charis SIL.

Waiting on Tim Eves who has content to plug into this.

From @andjc:

A few questions re what form of language tag to use and where to use it

1. Should it just be the bcp47 language subtag? Or should script subtag be always included if no suppress script field in bcp47 registry?

2. Should country/region subtag be included?

I guess to associate a keyboard with an input locale in Keyman and Windows it is necessary as a min to have lang_subtag-script_subtag although I guess that country/region may be relevant as well. Not sure how the new input loacle related mechanisms interact with other aspects of locales on win10

3. also what is best pracatice wrt to input locales and RTL scripts on windows. Should Biblical Hebrew be associated with biblical hebrew or modern hebrew input locales?

4. and if you have more than one language tag, how do you specify which language tag to associate keyboard with?

5. also do we add full language tag to keyboard_info file or just the kps?

@mcdurdin wrote:
I think the pattern we are going with is:

1. Always include script if no suppress-script given.

2. Include region only if it is necessary to disambiguate (e.g. Tigrigna Eritrea vs Tigrigna Ethiopia needs -ER or -ET but Tok Pisin doesn't need -PG). Keyman Developer now helps with this as does the Keyman Desktop keyboard installation UI, but there is still a gap for pre-existing keyboards (see https://trello.com/c/aa7WIeP2/742-windows-if-a-keyboard-is-installed-with-an-incomplete-language-tag-eg-no-script-tag-then-use-the-same-global-data-we-use-in-the for the work item I just created) .

3. Biblical Hebrew should be associated with Ancient Hebrew language, and Hebrew script. That should allow for RTL identification in a sane world. We may need to experiment.

4. Pick the biggest / most relevant language as the first language in the list. Keyman Desktop will offer the alternatives as priority options after installation.

5. The .keyboard_info and .kps language tags are allowed to diverge. Ideally, we won't do that, but in some situations, e.g. IPA (und-fonipa in .keyboard_info, und-Latn(?) in .kps) we are forced to do that for nasty compatibility reasons.

(edit to include #47)
@mcdurdin wrote:
In the original design, Keyman was supposed to fall back to shorter tags when searching for an appropriate [lexical] model, e.g. en-AU would be searched first, then en. This meant that a US English model should have en-US and en BCP-47 tags assigned. Or, tpi-Latn-PG -> tpi-Latn -> tpi-PG -> tpi (i.e. script has heavier weight than region in search). That level of detail probably doesn't belong on this page but does belong somewhere in the docs.

Describe the bug
From the drop down menu of Product Support on help.keyman.com when clicking on Keymanweb.com, the return URL is: https://help.keyman.com/products/web/11.0/.

Should the version number be 12.0?

To Reproduce
Steps to reproduce the behavior:

1. Go to 'help.keyman.com' page
2. Hover on "Product Support"
3. Click on 'Keymanweb.com'
4. See error

Expected behavior
The version number needs to be bumped to 12.0?
The return URL should be https://help.keyman.com/products/web/12.0/.

I used the new feature of Developer 11 (Project | New Project | Basic) to create a "test1" keyboard. When I saw it wanted to save a test1.kpj file, I created a test1 folder to put it in. But when I went to save the project, I was warned that folder test1 existed (that is, the empty one I had just created) and did I want to overwrite it. I said Yes and everything was fine.

I tried again with "test2" and pointed Developer at a sandbox folder so I could see what it would do. I got this mildly unhelpful message:

which didn't tell me whether it was going to make sandbox\test2\test2.kpj or sandbox\test2.kpj.

In faith, I clicked OK and got here:

where I could scroll the Path field to the end. But that still leaves me wondering whether Developer will make a "test2" folder in "sandbox" or not. (It does.)

So now I'm thinking that the "Keyboard Name" is the Human readable name, and the "Keyboard ID" is the folder name, project name, etc. I see that putting an upper case letter or hyphen in the "Keyboard ID" field causes the OK button to grey out, whereas I can type upper case letters or hyphen in the "Keyboard Name" field.

Reference

https://docs.google.com/document/d/1nQi65m2i9DrAmwG_ahdYtn5JcWYTwI_kJoSLeK2nPAs/edit#heading=h.gql9ftadtdao

TODOs

• KeymanWeb Cloud API 1.0-4.0 documentation need updates. Following are some notable changes from the documentation for versions 2.0-4.0:

• Edit id description on page: https://help.keyman.com/developer/cloud/5.0/obj-language.php.

• Reference the schemas on api.keyman.com.

• Keyman Engine for Windows documentation already refers to BCP-47 codes. However, these are slightly conflated with ethnologuecodes, viz. https://help.keyman.com/developer/engine/desktop/10.0/api/IKeymanKeyboard/DefaultBCP47Languages

• The page https://help.keyman.com/products/desktop/10.0/docs/advanced_locale_edit.php(as well as the two previous versions) have currently broken links to the Online Editor that is supposed to facilitate localization of the UI. Assuming we plan to reinstate that capability in some form or fashion, we need to evaluate what we say about the language code. I’m assuming we could just say BCP-47. Marc fixed links, but BCP 47 TBD

• Check for any other use of 3-letter ISO 639-3 tags across documentation examples.

• Don’t forget to update https://help.keyman.com/developer/language/guide/history.

Keymanweb 10.0 TODOs

• Use of “ISO” and “language” need to be clarified on the 5.0 version of this page: https://help.keyman.com/developer/engine/web/2.0/reference/keyboard_properties

• The definition of “languageCode” needs to be changed on the 5.0 version of this page: https://help.keyman.com/developer/engine/web/2.0/reference/core/setActiveKeyboard

• The three-letter codes in the 5.0 version of these files need to be changed to BCP-47: https://help.keyman.com/developer/engine/web/2.0/guide/examples/js/unified_loader.js

• https://help.keyman.com/developer/engine/web/2.0/guide/examples/js/keymanweb.js

• The references to IS0 639-3 and “three-letter code” need to be changed on the 5.0 versions of these pages: https://help.keyman.com/developer/engine/web/2.0/guide/adding-keyboards (also the examples ”eng” and “heb” need to become “en” and “he” respectively)

• https://help.keyman.com/DEVELOPER/ENGINE/web/2.0/reference/core/addKeyboards

• https://help.keyman.com/DEVELOPER/ENGINE/web/2.0/reference/core/getKeyboard

• https://help.keyman.com/DEVELOPER/ENGINE/web/2.0/reference/core/setActiveKeyboard

• https://help.keyman.com/DEVELOPER/ENGINE/web/2.0/reference/events/kmw.beforekeyboardchange

• https://help.keyman.com/DEVELOPER/ENGINE/web/2.0/reference/events/kmw.keyboardchange

• https://help.keyman.com/DEVELOPER/ENGINE/web/2.0/reference/events/kmw.keyboardregistered

• On the page https://help.keyman.com/DEVELOPER/ENGINE/web/2.0/reference/keyboard_properties, either edit the existing description for KLC (languageCode) to refer to BCP-47, or if a new code is to be defined to live alongside the legacy code, add a new row for it with the appropriate description.

https://help.keyman.com/products/linux/11.0/ currently only contains very basic 'install keyboard' GUI documentation. This is not sufficient; the command line tools should also be documented (the man pages, plus an overview). See https://manpages.debian.org/unstable/keyman/ for sample content (which should of course be generated from the source man pages at release time).

I had quite a difficult time finding a guide for developing a simple Touch Layout. I was directed to this link, which makes it very clear: https://help.keyman.com/developer/11.0/guides/develop/touch-keyboard-tutorial/making-touch-keyboard. Here's the original discussion about this: https://community.software.sil.org/t/multiple-longpress-options/2048/6

It would be helpful to have this information included in 2 places:

Here: https://help.keyman.com/developer/11.0/context/keyboard-editor#toc-touch-layout-tab

Also, in the Context Help area in Keyman Developer:

Please see https://drive.google.com/file/d/1DiXm3coYDmCOdP2aaLHEvzcJeO-S3kgb/view?usp=sharing for a screenshot. I couldn't get the image upload to work because of internet issues.

I think that especially having it in the Context Help area in Keyman Developer would help newer people to create simple keyboards without much trouble.

Thank you,

James

Page not found when clicks the .TTF: https://help.keyman.com/developer/13.0/reference/file-types/ttf

Reported by He-bi in Online Workshop

To aid people developing word list lexical models, we need a mini how-to on how to export a compatible TSV from their application of choice. These may include:

• Google Sheets
• Microsoft Excel
• FleidWorks (FLEx)
• WeSay
• PrimerPrep

Any others?

From @mcdurdin

Not sure what to do with this now. Desktop portions of help.keyman.com are automatically built with docbook. Mac ones no longer are.

When I do a search on "kmea" I get two results. The second result is a page that does not exist,

The full URL for the missing page is:
https://help.keyman.com/products/android/10.0/version/?_ga=2.200103469.2034434210.1531837091-304870458.1501684319

Content in /developer/engine/web appears to be version 2.0-centric. The 2.0 content should all be under 2.0/ folder.

The keyboard renderer should use the information provided in the .keyboard_info to present osk.

For example, see https://help.keyman.com/keyboard/newa_traditional/1.0/newa_traditional. The web font is available on s.keyman.com.

This issue was blocked by the keyboard using a .otf. Keyman 13.0.101 adds support for .otf extension but the help site is currently using 10.0.103 (!) and updating to 13.0.101 breaks the site in other ways.

This may be accomplished by using the KeymanWeb API's in a more appropriate manner or by consuming the data directly from api.keyman.com -- will defer to @jahorton.

Depends on keymanapp/keyman#2784, keymanapp/keyman#2818.

Now that we have QR Codes in Keyman Desktop and Keyman for Mac, and hopefully soon on other platforms as well, it would be good to have a master help page on sharing keyboards cross-device. Each relevant platform needs context help update as well of course, but the context help should also link to the master page for more info.

Matthew says:

The docs are great for individual questions, the touch keyboard walkthroughs were great, just hard to find complete examples without grepping the repository.

Marc says:

Yes. We could make good use of the repo now for examples.

Suggested by @MattGyverLee

e.g. Keyboard Quality White Paper on https://help.keyman.com/developer/12.0/ and https://help.keyman.com/developer/keyboards/advanced/step-0.php both refer to http://www.tavultesoft.com/keymandev/quality/ which redirects to https://keyman.com/developer/

A user pointed out that the keywords "using keys" is not described anywhere in the language guide or the language reference. I searched for it too and didn't find it. It should be there.

The platform support grids in the Developer language reference do not include Keyman for Linux. This should be added.

While you are at it...

Platform support anomalies

• mnemonic layout support is currently incorrect for Mac. While mnemonic keyboards work on Mac, you cannot select a different base keyboard.

• If statement support is also incomplete as the options form is not supported on mac (or Linux).

See https://community.software.sil.org/t/special-keys-in-keyman-touch-layout/1715

There are only two special keys:

K_LOPT shows the keyboard menu or switches keyboards
K_ROPT dismisses/hides the keyboard
The K_LOPT keyboard has slightly different semantics on iOS and Android. On iOS, a touch will swap to the next keyboard, and longpress will bring up a menu. On Android, touching the key will open the keyboard menu. In Keyman 11 on Android, the menu has an additional option to switch to a non-Keyman keyboard (missing in version 10). Longpress does not currently have a meaning on this key on Android.

This needs to be documented at https://help.keyman.com/developer/language/guide/virtual-keys and https://help.keyman.com/developer/11.0/guides/develop/creating-a-touch-keyboard-layout-for-amharic-the-nitty-gritty

nuf said.

Actually, we need to clean that file up and start reporting through new crash reporting infrastructure once we start on it...