docs: new rota help page

[Meng-Heng]

Fixes: #2126

@keymanapp-test-bot skip

[keymanapp-test-bot]

User Test Results

Test specification and instructions

User tests are not required

[darcywong00]

I think rotas are subtly different from double-press (multi-press gesture)

@jahorton - isn't there a gesture timeout involved for multi-press actions?

Whereas rotas are separate keyboard rules to handle the rotation of pressing the same key

[mcdurdin]

Rotas are often a separate key, as well, for example, press a for a basic 'a', then press / repeatedly to rotate through various forms of the 'a'.

[Meng-Heng]

I was going for the names that our users asked; for searchability and doublepressing was one of them. I'm going to come up with something for you both to correct again. 😄

[mcdurdin]

This example doesn't really work. Can you explain what you were trying to do, and we can put together a concise example?

[Meng-Heng]

I'm trying to do a rotation from 'z' -> 'ʋ̀' -> 'z'.

store(lat_norm_replacement) "zxc;ZXC:"
store(lat_vowels) "ʋɛɔɩƲƐƆɭ"

any(lat_norm_replacement) + '`' > index(lat_vowels, 1) U+0300   c ʋ̀
any(lat_norm_replacement) + "'" > index(lat_vowels, 1) U+0301   c ʋ́ 
any(lat_norm_replacement) + '~' > index(lat_vowels, 1) U+0303   c ʋ̃

'ʋ̀' + 'z' > 'z'
'ʋ́' + 'z' > 'z'
'ʋ̃' + 'z' > 'z'

I removed the line that caused the issue. Do you think it's still relevant to the document?

[mcdurdin]

I think these lines should be replaced with:

store(diacritic_key) "`'~"
store(diacritic) U+0300 U+0301 U+0302

store(lat_norm_replacement) "zxc;ZXC:"
store(lat_vowel) "ʋɛɔɩƲƐƆɭ"

any(lat_norm_replacement) + any(diacritic_key) > index(lat_vowel, 1) index(diacritic, 2)

match > use(rotate_repeat)

group(rotate_repeat)
any(lat_vowel) any(diacritic) index(lat_vowel, 1) index(diacritic, 2) > index(lat_norm_replacement, 1)

Then you need to explain what this is doing!

[Meng-Heng]

@mcdurdin, this rule does not work. Can you help change it?

[mcdurdin]

I am not quite sure what you are trying to do with this rule?

[Meng-Heng]

Sorry, I'm trying to get:

• z + ` = ʋ́
• ʋ́ + ` = z

[Meng-Heng]

But it could be any marks from the three (`,',~)

[mcdurdin]

OK, this is quite a complicated rota, because it is going between single characters and multiple characters. Can we use a simpler example here so we don't lose people?

store(vowel)  'aeiou'
store(acute)  'áéíóú'
store(grave)  'àèìòù'
store(circum) 'âêîôû'

any(vowel) + "'" > index(acute, 1)
any(acute) + "'" > index(vowel, 1)

any(vowel) + "`" > index(grave, 1)
any(grave) + "`" > index(vowel, 1)

any(vowel)  + "^" > index(circum, 1)
any(circum) + "^" > index(vowel, 1)

c -----------

any(vowel) + '/' > index(acute, 1)
any(acute) + '/' > index(grave, 1)
any(grave) + '/' > index(circum, 1)
any(circum) + '/' > index(vowel, 1)

This will allow the user to type a, ' for example, and rotate through plain-a or a with acute.

Or with /, rotate through all the different diacritic markers before going back to plain 'a'.

Does this achieve what you want to communicate to the keyboard authors? We can do more complex rotas or more complex patterns, but this has the virtue of being easy to read and understand.

[Meng-Heng]

Yes! This work too.
I was going with what I used for the wali keyboard but did not quite understand the depth/complexity of it. I'll try viewing something like this in a different point of view next time.
I don't want to lose people/users too. 😆

Thank you for simplifying this, @mcdurdin.

[Meng-Heng]

This PR is ready for review.

[jahorton]

I see that the referenced keyboard does use rotas, though it does feel a little odd to link to a specific keyboard from a guide page. Just wanting to prompt discussion about if the Xinaliq page link is something we want here.

[darcywong00]

I'm fine either keeping or removing the link. Keyboard authors might find it helpful to see rota examples in other keyboards (maybe a small list of rota keyboards)

[mcdurdin]

If we keep the link, make it clear that these are example keyboards using rotas. And better to link to the source of the keyboard than the documentation.

[LornaSIL]

I agree. I think the link to xinaliq could be removed.

[Meng-Heng]

Thank you, everyone!

[mcdurdin]

Suggested change

	Rotational keys, or "rotas" are combinations of one or more keys pressed together to produce a character or letter output, following the sequences defined by Keyman rules, and they will always end up back to the first letter as part of a rotation.
	Rotational keys, or "rotas" are combinations of one or more keys pressed in sequence to produce a character or letter output, following the sequences defined by Keyman rules, and they will always end up back to the first letter as part of a rotation.