From f5e9bcfa3fd82b951099e6f811cba32552de1f08 Mon Sep 17 00:00:00 2001 From: Gergely Nagy Date: Sat, 13 Oct 2018 15:27:03 +0200 Subject: [PATCH] Rearrange the file layout in preparation of becoming a monorepo Move the documentation to `doc/plugin/Steno.md`, sources under `src/kaleidoscope/plugin/` (appropriately namespaced). This is in preparation of merging plugins into a single monorepo. Signed-off-by: Gergely Nagy --- README.md | 95 +----------------- doc/plugin/Steno.md | 96 +++++++++++++++++++ src/Kaleidoscope-Steno.h | 2 +- .../plugin}/GeminiPR.cpp | 4 +- .../plugin}/GeminiPR.h | 6 +- 5 files changed, 105 insertions(+), 98 deletions(-) create mode 100644 doc/plugin/Steno.md rename src/{Kaleidoscope => kaleidoscope/plugin}/GeminiPR.cpp (95%) rename src/{Kaleidoscope => kaleidoscope/plugin}/GeminiPR.h (91%) diff --git a/README.md b/README.md index 76692ae1..ef194e81 100644 --- a/README.md +++ b/README.md @@ -5,97 +5,4 @@ [travis:image]: https://travis-ci.org/keyboardio/Kaleidoscope-Steno.svg?branch=master [travis:status]: https://travis-ci.org/keyboardio/Kaleidoscope-Steno -Stenography is a way to write in shorthand, a chorded input system that allows -very fast input (considerably higher than normal touch typing), by using -shorthand chords and a dictionary. This plugin implements the `GeminiPR` -protocol that supports a number of systems, including [Plover][plover]. - - [plover]: http://www.openstenoproject.org/plover/ - -While Plover supports a normal QWERTY keyboard too, having a dedicated plugin -comes with important advantages: - -* No need to toggle Plover on and off, because the normal keys are not taken - over by Plover anymore. -* Easier toggling, because you only have to toggle the layer, not Plover too. If - you switch back to a keyboard layer, without toggling Plover off, nothing - unexpected will happen. Plover will not take over the keys. -* The `GeminiPR` protocol supports language systems other than English. - -Do note that the `GeminiPR` protocol is implemented over the virtual serial -port, so any plugin that wants to use that port too, will run into -conflicts with the Steno plugin. In other words, don't use it together -with [Focus][k:focus]. - - [k:focus]: https://github.com/keyboardio/Kaleidoscope-Focus - -## What is Steno? Why should I use it? How do I learn? - -As mentioned above, steno (short for "stenography") is a shorthand, chorded -input system that allows very fast input - licensed stenographers are required -to type **225 WPM at 95% accuracy** to get their license. Although reaching that -speed typically takes 2-6 years of practice and training, lower speeds -comparable to or exceeding that of touch typing can reportedly be reached in -only a few months. - -[This talk][stenotalk] (YouTube link) gives a brief introduction to Steno, how -it works, and why it is cool. - - [stenotalk]: https://youtu.be/Wpv-Qb-dB6g - -One recommend way to get started with learning Steno is with [Plover][plover]. -Plover is software for your computer that will interpret the steno input from -your Model 01 (or other NKRO QWERTY keyboard); it is available for Windows, -macOS, and Linux. Plover's [Beginner's Guide][ploverguide] is a great place to -get started with Steno in general and Plover in particular. - - [ploverguide]: https://github.com/openstenoproject/plover/wiki/Beginner's-Guide:-Get-Started-with-Plover - -## Using the plugin - -To use the plugin, simply include the header in your Sketch, tell the firmware -to use the `GeminiPR` object, and place Steno keys on your keymap. It is best -illustrated with an example: - -```c++ -#include -#include - -// Somewhere in the keymap: -S(S1), S(S2), etc - -KALEIDOSCOPE_INIT_PLUGINS(GeminiPR); - -void setup() { - Kaleidoscope.setup(); -} -``` - -## Keys provided by the plugin - -The plugin provides a number of keys one can put on the keymap, that allow -correspond to various Steno keys. All of these must be used together with the -`S()` macro provided by the plugin, as can be seen in the example above. - -The provided keys are: `FN`, `N1`, `N2`, `N3`, `N4`, `N5`, `N6`, `S1`, `S2`, -`TL`, `KL`, `PL`, `WL`, `HL`, `RL`, `A`, `O`, `ST1`, `ST2`, `RE1`, `RE2`, `PWR`, -`ST3`, `ST4`, `E`, `U`, `FR`, `RR`, `PR`, `BR`, `LR`, `GR`, `TR`, `SR`, `DR`, -`N7`, `N8`, `N9`, `NA`, `NB`, `NC`, `ZR`. - -See the [example][plugin:example] for the default/suggested placements of each -of these keys. - -## Plugin methods and properties - -The plugin provides a `GeminiPR` object, with no public methods or properties. - -## Dependencies - -* [Kaleidoscope-Ranges](https://github.com/keyboardio/Kaleidoscope-Ranges) - -## Further reading - -Starting from the [example][plugin:example] is the recommended way of getting -started with the plugin. - - [plugin:example]: https://github.com/keyboardio/Kaleidoscope-Steno/blob/master/examples/Steno/Steno.ino +See [doc/plugin/Steno.md](doc/plugin/Steno.md) for documentation. diff --git a/doc/plugin/Steno.md b/doc/plugin/Steno.md new file mode 100644 index 00000000..c92af803 --- /dev/null +++ b/doc/plugin/Steno.md @@ -0,0 +1,96 @@ +# Kaleidoscope-Steno + +Stenography is a way to write in shorthand, a chorded input system that allows +very fast input (considerably higher than normal touch typing), by using +shorthand chords and a dictionary. This plugin implements the `GeminiPR` +protocol that supports a number of systems, including [Plover][plover]. + + [plover]: http://www.openstenoproject.org/plover/ + +While Plover supports a normal QWERTY keyboard too, having a dedicated plugin +comes with important advantages: + +* No need to toggle Plover on and off, because the normal keys are not taken + over by Plover anymore. +* Easier toggling, because you only have to toggle the layer, not Plover too. If + you switch back to a keyboard layer, without toggling Plover off, nothing + unexpected will happen. Plover will not take over the keys. +* The `GeminiPR` protocol supports language systems other than English. + +Do note that the `GeminiPR` protocol is implemented over the virtual serial +port, so any plugin that wants to use that port too, will run into +conflicts with the Steno plugin. In other words, don't use it together +with [Focus][k:focus]. + + [k:focus]: https://github.com/keyboardio/Kaleidoscope-Focus + +## What is Steno? Why should I use it? How do I learn? + +As mentioned above, steno (short for "stenography") is a shorthand, chorded +input system that allows very fast input - licensed stenographers are required +to type **225 WPM at 95% accuracy** to get their license. Although reaching that +speed typically takes 2-6 years of practice and training, lower speeds +comparable to or exceeding that of touch typing can reportedly be reached in +only a few months. + +[This talk][stenotalk] (YouTube link) gives a brief introduction to Steno, how +it works, and why it is cool. + + [stenotalk]: https://youtu.be/Wpv-Qb-dB6g + +One recommend way to get started with learning Steno is with [Plover][plover]. +Plover is software for your computer that will interpret the steno input from +your Model 01 (or other NKRO QWERTY keyboard); it is available for Windows, +macOS, and Linux. Plover's [Beginner's Guide][ploverguide] is a great place to +get started with Steno in general and Plover in particular. + + [ploverguide]: https://github.com/openstenoproject/plover/wiki/Beginner's-Guide:-Get-Started-with-Plover + +## Using the plugin + +To use the plugin, simply include the header in your Sketch, tell the firmware +to use the `GeminiPR` object, and place Steno keys on your keymap. It is best +illustrated with an example: + +```c++ +#include +#include + +// Somewhere in the keymap: +S(S1), S(S2), etc + +KALEIDOSCOPE_INIT_PLUGINS(GeminiPR); + +void setup() { + Kaleidoscope.setup(); +} +``` + +## Keys provided by the plugin + +The plugin provides a number of keys one can put on the keymap, that allow +correspond to various Steno keys. All of these must be used together with the +`S()` macro provided by the plugin, as can be seen in the example above. + +The provided keys are: `FN`, `N1`, `N2`, `N3`, `N4`, `N5`, `N6`, `S1`, `S2`, +`TL`, `KL`, `PL`, `WL`, `HL`, `RL`, `A`, `O`, `ST1`, `ST2`, `RE1`, `RE2`, `PWR`, +`ST3`, `ST4`, `E`, `U`, `FR`, `RR`, `PR`, `BR`, `LR`, `GR`, `TR`, `SR`, `DR`, +`N7`, `N8`, `N9`, `NA`, `NB`, `NC`, `ZR`. + +See the [example][plugin:example] for the default/suggested placements of each +of these keys. + +## Plugin methods and properties + +The plugin provides a `GeminiPR` object, with no public methods or properties. + +## Dependencies + +* [Kaleidoscope-Ranges](https://github.com/keyboardio/Kaleidoscope-Ranges) + +## Further reading + +Starting from the [example][plugin:example] is the recommended way of getting +started with the plugin. + + [plugin:example]: https://github.com/keyboardio/Kaleidoscope-Steno/blob/master/examples/Steno/Steno.ino diff --git a/src/Kaleidoscope-Steno.h b/src/Kaleidoscope-Steno.h index 44743729..c4879b93 100644 --- a/src/Kaleidoscope-Steno.h +++ b/src/Kaleidoscope-Steno.h @@ -18,4 +18,4 @@ #pragma once -#include +#include diff --git a/src/Kaleidoscope/GeminiPR.cpp b/src/kaleidoscope/plugin/GeminiPR.cpp similarity index 95% rename from src/Kaleidoscope/GeminiPR.cpp rename to src/kaleidoscope/plugin/GeminiPR.cpp index 879548bc..0998c269 100644 --- a/src/Kaleidoscope/GeminiPR.cpp +++ b/src/kaleidoscope/plugin/GeminiPR.cpp @@ -19,6 +19,7 @@ #include namespace kaleidoscope { +namespace plugin { namespace steno { uint8_t GeminiPR::keys_held_; @@ -47,7 +48,8 @@ EventHandlerResult GeminiPR::onKeyswitchEvent(Key &mapped_key, byte row, byte co return EventHandlerResult::EVENT_CONSUMED; } +} } } -kaleidoscope::steno::GeminiPR GeminiPR; +kaleidoscope::plugin::steno::GeminiPR GeminiPR; diff --git a/src/Kaleidoscope/GeminiPR.h b/src/kaleidoscope/plugin/GeminiPR.h similarity index 91% rename from src/Kaleidoscope/GeminiPR.h rename to src/kaleidoscope/plugin/GeminiPR.h index 333acf40..ed98d93a 100644 --- a/src/Kaleidoscope/GeminiPR.h +++ b/src/kaleidoscope/plugin/GeminiPR.h @@ -21,9 +21,10 @@ #include #include -#define S(n) (Key) {.raw = kaleidoscope::steno::geminipr::n } +#define S(n) (Key) {.raw = kaleidoscope::plugin::steno::geminipr::n } namespace kaleidoscope { +namespace plugin { namespace steno { class GeminiPR : public kaleidoscope::Plugin { public: @@ -91,5 +92,6 @@ enum { } } } +} -extern kaleidoscope::steno::GeminiPR GeminiPR; +extern kaleidoscope::plugin::steno::GeminiPR GeminiPR;