# Plover Cycle Translations
[![Build Status][Build Status image]][Build Status url] [![PyPI - Version][PyPI version image]][PyPI url] [![PyPI - Downloads][PyPI downloads image]][PyPI url] [![linting: pylint][linting image]][linting url]
This [Plover][] [extension][] [plugin][] contains a [macro][] that allows you
define multiple translations in a single outline, and then cycle through them
[Alt-Tab][]- or [IME][]-style using a "selector stroke". It covers similar
ground to Plover's [`retro_toggle_asterisk`][] macro, but is broader in
scope than just toggling between an outline and its asterisk-flagged equivalent
(e.g. `"HAOEU": "high"` and `"HAO*EU": "hi"`).
Cycling translations can be helpful for disambiguating between:
- [homophones][] (words that are pronounced the same but differ in spelling;
e.g. "sent", "cent", and "scent")
- words and their similar sounding [proper nouns][] (e.g. "mark", "Mark", and
"Marc")
- differences in regional spelling for the same word (e.g. "colour", "color")
These variants can be defined with a single outline, rather than needing to
remember all their respective outlines. Alternatively, all of their original
outlines can be edited or overridden to be cycleable, so it will not matter
which variant's outline you stroke, you will always have the option to cycle.
For some examples of cycleable list entries to add to your own steno
dictionaries that encompass all of the points above, see [here][].
## Install
1. In the Plover application, open the Plugins Manager (either click the Plugins
Manager icon, or from the `Tools` menu, select `Plugins Manager`).
2. From the list of plugins, find `plover-cycle-translations`
3. Click "Install/Update"
4. When it finishes installing, restart Plover
5. After re-opening Plover, open the Configuration screen (either click the
Configuration icon, or from the main Plover application menu, select
`Preferences...`)
6. Open the Plugins tab
7. Check the box next to `plover_cycle_translations` to activate the plugin
## Usage
Using the "sent", "cent", and "scent" example above, the outlines for them in
Plover theory are:
- `"SEPBT": "sent"` - indicative of a [phonetic][] (how the word sounds)
reading of "sent"
- `"KREPBT": "cent"` - indicative of an [orthographic][] (how the word is
spelled) reading of "cent", using the [fingerspelled "C"][] `KR` chord
- `"SKREPBT": "scent"` - orthographic, similar to "cent"
If you wanted to standardise on the phonetic `SEPBT` outline for all three
words, you could use this plugin to create a dictionary entry as follows:
```json
"SEPBT": "=CYCLE:sent,cent,scent"
```
This will output "sent" when stroked. You then use a "selector stroke" to cycle
to the next word in the comma-separated list of words, in the order they are
defined. An example of a selector stroke dictionary entry would be:
```json
"R*R": "=CYCLE:NEXT"
```
As you cycle through the word list, each outputted word gets replaced with the
next word entry. Once you hit the end of the list, the cycle begins again: in
the example above, if you stroke `=CYCLE:NEXT` when you have output "scent",
it will be replaced with "sent".
If you have a particularly long list that you also want to cycle backwards
through, you can use a "previous" selector stroke to do so, like:
```json
"R*RB": "=CYCLE:PREVIOUS"
```
Cycleable dictionary entries are not limited to just single stroke outlines.
Multiple stroke outline entries are also supported:
```json
"ABG/SEL": "=CYCLE:axel,axle,axil"
```
Prefix and suffix entries are also supported:
```json
"PW*EU": "=CYCLE:{bi^},by,buy,bye"
```
Non-text characters like emoji are also supported:
```json
"H-PBD": "=CYCLE:👍,👎,👊"
```
## Development
Clone from GitHub with [git][] and install test-related dependencies with
[pip][]:
```console
git clone git@github.com:paulfioravanti/plover-cycle-translations.git
cd plover-cycle-translations
python -m pip install --editable ".[test]"
```
If you are a [Tmuxinator][] user, you may find my [plover-cycle-translations
project file][] of reference.
### Python Version
Plover's Python environment currently uses version 3.9 (see Plover's
[`workflow_context.yml`][] to confirm the current version).
So, in order to avoid unexpected issues, use your runtime version manager to
make sure your local development environment also uses Python 3.9.x.
### Testing
- [Pytest][] is used for testing
- [Coverage.py][] and [pytest-cov][] are used for test coverage, and to run
coverage within Pytest
- [Pylint][] is used for code quality
- [Mypy][] is used for static type checking
Currently, the only parts able to be tested are ones that do not rely directly
on Plover.
Run tests, coverage, and linting with the following commands:
```console
pytest --cov --cov-report=term-missing
pylint plover_cycle_translations
mypy plover_cycle_translations
```
To get a HTML test coverage report:
```console
coverage run --module pytest
coverage html
open htmlcov/index.html
```
If you are a [`just`][] user, you may find the [`justfile`][] useful during
development in running multiple code quality commands. You can run the following
command from the project root directory:
```console
just --working-directory . --justfile test/justfile
```
### Deploying Changes
After making any code changes, deploy the plugin into Plover with the following
command:
```console
plover --script plover_plugins install --editable .
```
> Where `plover` in the command is a reference to your locally installed version
> of Plover. See the [Invoke Plover from the command line][] page for details on
> how to create that reference.
When necessary, the plugin can be uninstalled via the command line with the
following command:
```console
plover --script plover_plugins uninstall plover-cycle-translations
```
[Alt-Tab]: https://en.wikipedia.org/wiki/Alt-Tab
[Build Status image]: https://github.com/paulfioravanti/plover-cycle-translations/actions/workflows/ci.yml/badge.svg
[Build Status url]: https://github.com/paulfioravanti/plover-cycle-translations/actions/workflows/ci.yml
[Coverage.py]: https://github.com/nedbat/coveragepy
[extension]: https://plover.readthedocs.io/en/latest/plugin-dev/extensions.html
[fingerspelled "C"]: https://www.artofchording.com/sounds/fingerspelling.html#letter-c
[Git]: https://git-scm.com/
[here]: https://github.com/paulfioravanti/steno-dictionaries/blob/main/dictionaries/cycleable.md
[homophones]: https://en.wikipedia.org/wiki/Homophone
[IME]: https://en.wikipedia.org/wiki/Input_method
[Invoke Plover from the command line]: https://github.com/openstenoproject/plover/wiki/Invoke-Plover-from-the-command-line
[`just`]: https://github.com/casey/just
[`justfile`]: ./test/justfile
[linting image]: https://img.shields.io/badge/linting-pylint-yellowgreen
[linting url]: https://github.com/pylint-dev/pylint
[macro]: https://plover.readthedocs.io/en/latest/plugin-dev/macros.html
[meta]: https://plover.readthedocs.io/en/latest/plugin-dev/metas.html
[Mypy]: https://github.com/python/mypy
[orthographic]: https://en.wikipedia.org/wiki/Orthography
[phonetic]: https://en.wikipedia.org/wiki/Phonetics
[pip]: https://pip.pypa.io/en/stable/
[plover-cycle-translations project file]: https://github.com/paulfioravanti/dotfiles/blob/master/tmuxinator/plover_cycle_translations.yml
[proper nouns]: https://en.wikipedia.org/wiki/Proper_noun
[PyPI]: https://pypi.org/
[PyPI downloads image]: https://img.shields.io/pypi/dm/plover-cycle-translations
[PyPI version image]: https://img.shields.io/pypi/v/plover-cycle-translations
[PyPI url]: https://pypi.org/project/plover-cycle-translations/
[Plover]: https://www.openstenoproject.org/
[Plover Plugins Registry]: https://github.com/openstenoproject/plover_plugins_registry
[plugin]: https://plover.readthedocs.io/en/latest/plugins.html#types-of-plugins
[Pylint]: https://github.com/pylint-dev/pylint
[Pytest]: https://docs.pytest.org/en/stable/
[pytest-cov]: https://github.com/pytest-dev/pytest-cov/
[`retro_toggle_asterisk`]: https://plover.readthedocs.io/en/latest/translation_language.html#other-formatting-actions
[Tmuxinator]: https://github.com/tmuxinator/tmuxinator
[`workflow_context.yml`]: https://github.com/openstenoproject/plover/blob/master/.github/workflows/ci/workflow_context.yml
Raw data
{
"_id": null,
"home_page": "https://github.com/paulfioravanti/plover-cycle-translations",
"name": "plover-cycle-translations",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "plover plover_plugin",
"author": "Paul Fioravanti",
"author_email": "paul@paulfioravanti.com",
"download_url": "https://files.pythonhosted.org/packages/59/a6/e4bf761cfb41388831b8ecfbd796d41f3f4712b6ffc530e9d1c2dca01311/plover_cycle_translations-0.5.4.tar.gz",
"platform": null,
"description": "# Plover Cycle Translations\n\n[![Build Status][Build Status image]][Build Status url] [![PyPI - Version][PyPI version image]][PyPI url] [![PyPI - Downloads][PyPI downloads image]][PyPI url] [![linting: pylint][linting image]][linting url]\n\nThis [Plover][] [extension][] [plugin][] contains a [macro][] that allows you\ndefine multiple translations in a single outline, and then cycle through them\n[Alt-Tab][]- or [IME][]-style using a \"selector stroke\". It covers similar\nground to Plover's [`retro_toggle_asterisk`][] macro, but is broader in\nscope than just toggling between an outline and its asterisk-flagged equivalent\n(e.g. `\"HAOEU\": \"high\"` and `\"HAO*EU\": \"hi\"`).\n\nCycling translations can be helpful for disambiguating between:\n\n- [homophones][] (words that are pronounced the same but differ in spelling;\n e.g. \"sent\", \"cent\", and \"scent\")\n- words and their similar sounding [proper nouns][] (e.g. \"mark\", \"Mark\", and\n \"Marc\")\n- differences in regional spelling for the same word (e.g. \"colour\", \"color\")\n\nThese variants can be defined with a single outline, rather than needing to\nremember all their respective outlines. Alternatively, all of their original\noutlines can be edited or overridden to be cycleable, so it will not matter\nwhich variant's outline you stroke, you will always have the option to cycle.\n\nFor some examples of cycleable list entries to add to your own steno\ndictionaries that encompass all of the points above, see [here][].\n\n## Install\n\n1. In the Plover application, open the Plugins Manager (either click the Plugins\n Manager icon, or from the `Tools` menu, select `Plugins Manager`).\n2. From the list of plugins, find `plover-cycle-translations`\n3. Click \"Install/Update\"\n4. When it finishes installing, restart Plover\n5. After re-opening Plover, open the Configuration screen (either click the\n Configuration icon, or from the main Plover application menu, select\n `Preferences...`)\n6. Open the Plugins tab\n7. Check the box next to `plover_cycle_translations` to activate the plugin\n\n## Usage\n\nUsing the \"sent\", \"cent\", and \"scent\" example above, the outlines for them in\nPlover theory are:\n\n- `\"SEPBT\": \"sent\"` - indicative of a [phonetic][] (how the word sounds)\n reading of \"sent\"\n- `\"KREPBT\": \"cent\"` - indicative of an [orthographic][] (how the word is\n spelled) reading of \"cent\", using the [fingerspelled \"C\"][] `KR` chord\n- `\"SKREPBT\": \"scent\"` - orthographic, similar to \"cent\"\n\nIf you wanted to standardise on the phonetic `SEPBT` outline for all three\nwords, you could use this plugin to create a dictionary entry as follows:\n\n```json\n\"SEPBT\": \"=CYCLE:sent,cent,scent\"\n```\n\nThis will output \"sent\" when stroked. You then use a \"selector stroke\" to cycle\nto the next word in the comma-separated list of words, in the order they are\ndefined. An example of a selector stroke dictionary entry would be:\n\n```json\n\"R*R\": \"=CYCLE:NEXT\"\n```\n\nAs you cycle through the word list, each outputted word gets replaced with the\nnext word entry. Once you hit the end of the list, the cycle begins again: in\nthe example above, if you stroke `=CYCLE:NEXT` when you have output \"scent\",\nit will be replaced with \"sent\".\n\nIf you have a particularly long list that you also want to cycle backwards\nthrough, you can use a \"previous\" selector stroke to do so, like:\n\n```json\n\"R*RB\": \"=CYCLE:PREVIOUS\"\n```\n\nCycleable dictionary entries are not limited to just single stroke outlines.\nMultiple stroke outline entries are also supported:\n\n```json\n\"ABG/SEL\": \"=CYCLE:axel,axle,axil\"\n```\n\nPrefix and suffix entries are also supported:\n\n```json\n\"PW*EU\": \"=CYCLE:{bi^},by,buy,bye\"\n```\n\nNon-text characters like emoji are also supported:\n\n```json\n\"H-PBD\": \"=CYCLE:\ud83d\udc4d,\ud83d\udc4e,\ud83d\udc4a\"\n```\n\n## Development\n\nClone from GitHub with [git][] and install test-related dependencies with\n[pip][]:\n\n```console\ngit clone git@github.com:paulfioravanti/plover-cycle-translations.git\ncd plover-cycle-translations\npython -m pip install --editable \".[test]\"\n```\n\nIf you are a [Tmuxinator][] user, you may find my [plover-cycle-translations\nproject file][] of reference.\n\n### Python Version\n\nPlover's Python environment currently uses version 3.9 (see Plover's\n[`workflow_context.yml`][] to confirm the current version).\n\nSo, in order to avoid unexpected issues, use your runtime version manager to\nmake sure your local development environment also uses Python 3.9.x.\n\n### Testing\n\n- [Pytest][] is used for testing\n- [Coverage.py][] and [pytest-cov][] are used for test coverage, and to run\n coverage within Pytest\n- [Pylint][] is used for code quality\n- [Mypy][] is used for static type checking\n\nCurrently, the only parts able to be tested are ones that do not rely directly\non Plover.\n\nRun tests, coverage, and linting with the following commands:\n\n```console\npytest --cov --cov-report=term-missing\npylint plover_cycle_translations\nmypy plover_cycle_translations\n```\n\nTo get a HTML test coverage report:\n\n```console\ncoverage run --module pytest\ncoverage html\nopen htmlcov/index.html\n```\n\nIf you are a [`just`][] user, you may find the [`justfile`][] useful during\ndevelopment in running multiple code quality commands. You can run the following\ncommand from the project root directory:\n\n```console\njust --working-directory . --justfile test/justfile\n```\n\n### Deploying Changes\n\nAfter making any code changes, deploy the plugin into Plover with the following\ncommand:\n\n```console\nplover --script plover_plugins install --editable .\n```\n\n> Where `plover` in the command is a reference to your locally installed version\n> of Plover. See the [Invoke Plover from the command line][] page for details on\n> how to create that reference.\n\nWhen necessary, the plugin can be uninstalled via the command line with the\nfollowing command:\n\n```console\nplover --script plover_plugins uninstall plover-cycle-translations\n```\n\n[Alt-Tab]: https://en.wikipedia.org/wiki/Alt-Tab\n[Build Status image]: https://github.com/paulfioravanti/plover-cycle-translations/actions/workflows/ci.yml/badge.svg\n[Build Status url]: https://github.com/paulfioravanti/plover-cycle-translations/actions/workflows/ci.yml\n[Coverage.py]: https://github.com/nedbat/coveragepy\n[extension]: https://plover.readthedocs.io/en/latest/plugin-dev/extensions.html\n[fingerspelled \"C\"]: https://www.artofchording.com/sounds/fingerspelling.html#letter-c\n[Git]: https://git-scm.com/\n[here]: https://github.com/paulfioravanti/steno-dictionaries/blob/main/dictionaries/cycleable.md\n[homophones]: https://en.wikipedia.org/wiki/Homophone\n[IME]: https://en.wikipedia.org/wiki/Input_method\n[Invoke Plover from the command line]: https://github.com/openstenoproject/plover/wiki/Invoke-Plover-from-the-command-line\n[`just`]: https://github.com/casey/just\n[`justfile`]: ./test/justfile\n[linting image]: https://img.shields.io/badge/linting-pylint-yellowgreen\n[linting url]: https://github.com/pylint-dev/pylint\n[macro]: https://plover.readthedocs.io/en/latest/plugin-dev/macros.html\n[meta]: https://plover.readthedocs.io/en/latest/plugin-dev/metas.html\n[Mypy]: https://github.com/python/mypy\n[orthographic]: https://en.wikipedia.org/wiki/Orthography\n[phonetic]: https://en.wikipedia.org/wiki/Phonetics\n[pip]: https://pip.pypa.io/en/stable/\n[plover-cycle-translations project file]: https://github.com/paulfioravanti/dotfiles/blob/master/tmuxinator/plover_cycle_translations.yml\n[proper nouns]: https://en.wikipedia.org/wiki/Proper_noun\n[PyPI]: https://pypi.org/\n[PyPI downloads image]: https://img.shields.io/pypi/dm/plover-cycle-translations\n[PyPI version image]: https://img.shields.io/pypi/v/plover-cycle-translations\n[PyPI url]: https://pypi.org/project/plover-cycle-translations/\n[Plover]: https://www.openstenoproject.org/\n[Plover Plugins Registry]: https://github.com/openstenoproject/plover_plugins_registry\n[plugin]: https://plover.readthedocs.io/en/latest/plugins.html#types-of-plugins\n[Pylint]: https://github.com/pylint-dev/pylint\n[Pytest]: https://docs.pytest.org/en/stable/\n[pytest-cov]: https://github.com/pytest-dev/pytest-cov/\n[`retro_toggle_asterisk`]: https://plover.readthedocs.io/en/latest/translation_language.html#other-formatting-actions\n[Tmuxinator]: https://github.com/tmuxinator/tmuxinator\n[`workflow_context.yml`]: https://github.com/openstenoproject/plover/blob/master/.github/workflows/ci/workflow_context.yml\n",
"bugtrack_url": null,
"license": "GNU General Public License v3 or later (GPLv3+)",
"summary": "Define multiple translations in a single steno outline and cycle through them.",
"version": "0.5.4",
"project_urls": {
"Homepage": "https://github.com/paulfioravanti/plover-cycle-translations"
},
"split_keywords": [
"plover",
"plover_plugin"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "31610d99a18937c70924d82657ef12735e3d473d94d7e6d4504bbf6eba9baae8",
"md5": "9cf31948d4680c01bf109f3448c47b3d",
"sha256": "79dfb9a54b98f849306a4e3fb856af3f97f2b373d0bdc413c9bae6154026ecd5"
},
"downloads": -1,
"filename": "plover_cycle_translations-0.5.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9cf31948d4680c01bf109f3448c47b3d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 21482,
"upload_time": "2024-10-22T09:28:25",
"upload_time_iso_8601": "2024-10-22T09:28:25.442573Z",
"url": "https://files.pythonhosted.org/packages/31/61/0d99a18937c70924d82657ef12735e3d473d94d7e6d4504bbf6eba9baae8/plover_cycle_translations-0.5.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "59a6e4bf761cfb41388831b8ecfbd796d41f3f4712b6ffc530e9d1c2dca01311",
"md5": "ee798a8473627fcc14528b98514be8ff",
"sha256": "1e83b0c70037bfa95118ce91684f4799af0880f5378269cccee51f24edcbfc95"
},
"downloads": -1,
"filename": "plover_cycle_translations-0.5.4.tar.gz",
"has_sig": false,
"md5_digest": "ee798a8473627fcc14528b98514be8ff",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 22638,
"upload_time": "2024-10-22T09:28:27",
"upload_time_iso_8601": "2024-10-22T09:28:27.123564Z",
"url": "https://files.pythonhosted.org/packages/59/a6/e4bf761cfb41388831b8ecfbd796d41f3f4712b6ffc530e9d1c2dca01311/plover_cycle_translations-0.5.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-22 09:28:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "paulfioravanti",
"github_project": "plover-cycle-translations",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "plover-cycle-translations"
}
JSON
