keymanapp / help.keyman.com Goto Github PK
View Code? Open in Web Editor NEWhttps://help.keyman.com/ source
https://help.keyman.com/ source
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:
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.
'
vs "
), anchors (e.g. #foo
), non-local links (starting with http:
), whitespace.This relates to responsive design of page; see https://help.keyman.com/developer/cloud/keyboard_info/1.0/ for example
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:
And from this comment:
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.
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
https://help.keyman.com/troubleshooting/browsers
It looks like it hasn't been touched since 2009:
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.
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
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"
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:
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, thenen
. This meant that a US English model should haveen-US
anden
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.
<kbd>
and <samp>
elements. This way we get nice formatting for keys and sample text<a>
and type=”disc” from ul elements<h1>
, <h2>
etc. Also content within headers in Reference sections is inconsistent.)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.
SHelpTopic_Context_CharacterIdentifier := 'context/character-identifier';
SHelpTopic_Context_DownloadProgress := 'context/download-progress';
SHelpTopic_Context_Help := 'context/help';
SHelpTopic_Context_KeyboardFonts := 'context/keyboard-fonts';
SHelpTopic_Context_MustIncludeDebug := 'context/must-include-debug';
SHelpTopic_Context_NewFileDetails := 'context/new-file-details';
SHelpTopic_Context_SelectSystemKeyboard := 'context/select-system-keyboard';
SHelpTopic_Context_SelectWindowsLanguages := 'context/select-windows-languages';
From @andjc:
A few questions re what form of language tag to use and where to use it
Should it just be the bcp47 language subtag? Or should script subtag be always included if no suppress script field in bcp47 registry?
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
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?
and if you have more than one language tag, how do you specify which language tag to associate keyboard with?
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:
Always include script if no suppress-script given.
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) .
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.
Pick the biggest / most relevant language as the first language in the list. Keyman Desktop will offer the alternatives as priority options after installation.
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:
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.
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:
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...
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...
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.