From 5a958b24c6e3714828c76343c4c470b07a6bad10 Mon Sep 17 00:00:00 2001 From: John de St Germain Date: Thu, 15 Feb 2024 16:26:57 -0600 Subject: [PATCH] Lots of link/warning fixes --- .gitignore | 2 +- README.md | 4 +- docs/CharaChorder One.rst | 8 +- docs/CharaChorder Operating System (CCOS).rst | 4 +- docs/CharaChorder X.rst | 24 ++--- docs/CharaChorder_Lite.rst | 10 +- docs/Chords.rst | 43 +++------ docs/Device Manager.rst | 16 ++-- docs/GenerativeTextMenu.rst | 91 +++++-------------- docs/Glossary.rst | 2 +- 10 files changed, 73 insertions(+), 131 deletions(-) diff --git a/.gitignore b/.gitignore index 9edb1f4..b079cf6 100644 --- a/.gitignore +++ b/.gitignore @@ -6,4 +6,4 @@ venv/ results/*.png results/*.txt processed_data/*.dat -.*.sw? +.*.sw? \ No newline at end of file diff --git a/README.md b/README.md index cd6fb0b..18b19f3 100644 --- a/README.md +++ b/README.md @@ -25,9 +25,11 @@ sphinx-autobuild docs _build ## Building ```sh -sphinx-build docs _build +sphinx-build -a docs _build ``` +Note, the -a flag will rebuild all files, regardless of if they have changed. This is useful so that warnings don't get cached. All warnings are preferred to be fixed rather than left, although in some cases (docs don't exist yet) the warnings are fine to leave. + ## Adding a new top level page If you are adding or editing an under construction top level page, make sure to diff --git a/docs/CharaChorder One.rst b/docs/CharaChorder One.rst index 1b6d63c..2bf0c9b 100644 --- a/docs/CharaChorder One.rst +++ b/docs/CharaChorder One.rst @@ -185,11 +185,11 @@ whether or not your cursor is somewhere where text can be entered… - You will be able to see a small, lime colored light inside the space that holds the USB-C port on the left half of the CharaChorder One. -If you have :doc:`realtime feedback` enabled, once you can see the highlighted text that reads +If you have :ref:`realtime feedback` enabled, once you can see the highlighted text that reads “CCOS is ready”, your device is ready to be used. .. note:: - IMPORTANT: :doc:`Realtime feedback` is enabled by default on new CharaChorder devices. + IMPORTANT: :ref:`Realtime feedback` is enabled by default on new CharaChorder devices. Getting Started ******************* @@ -240,7 +240,7 @@ which is the latest firmware release by visiting `this site `__. .. warning:: - IMPORTANT: Before performing the below steps, please make sure that you have a :doc:`backup of your layout` as well as a :doc:`backup of your chord library` and a :doc:`backup of your GTM settings`. The update might reset those, so it's important that you keep backup files handy. For instructions on how to restore backed up files, visit the :doc:`Backups` section. + IMPORTANT: Before performing the below steps, please make sure that you have a :ref:`backup of your layout` as well as a :ref:`backup of your chord library` and a :ref:`backup of your GTM settings`. The update might reset those, so it's important that you keep backup files handy. For instructions on how to restore backed up files, visit the :ref:`Backups` section. #. On a chromium based browser, such as Chrome, go to the CharaChorder `Device Manager `__ #. Click “Connect” @@ -454,7 +454,7 @@ layout has been optimized for writing in English by :doc:`chentry` and :doc:`chording`, some users may choose to :doc:`remap` their device’s layout to better suit their personal needs. For a thorough explanation on how remapping -works and how to remap your device, visit the :doc:`remapping section` +works and how to remap your device, visit the :ref:`remapping section` Practice ~~~~~~~~ diff --git a/docs/CharaChorder Operating System (CCOS).rst b/docs/CharaChorder Operating System (CCOS).rst index 062f82c..8f2fc7d 100644 --- a/docs/CharaChorder Operating System (CCOS).rst +++ b/docs/CharaChorder Operating System (CCOS).rst @@ -13,7 +13,7 @@ consistent performance across all devices and enhances the ability of our team to introduce new features, fix bugs, as well as respond to feedback more efficiently with a convergent and spearheaded approach. In addition to the introduction of importable and exportable settings, inside your -:doc:`Generative Text Menu (GTM)` you'll find new +:doc:`Generative Text Menu (GTM)` you'll find new configurable settings including programmable debounce, arpeggiate tolerances, and even a customizable scan rate. Specialized 'hard coded' chords which were previously immutable can now be edited, including chords only available in @@ -49,7 +49,7 @@ can adopt or build upon, with possibilities that are only limited by the human imagination. Do you want to publish your own DataHand inspired :doc:`CharaChorder One` layout? Do you want to utilize fluid chorded/character entry in tandem with layouts/theories developed for velotype -or stenography on your :doc:`CharaChorder Lite`? Do you want +or stenography on your :doc:`CharaChorder Lite`? Do you want to introduce the world's first 1-Dimensional keyboard layout designed for both character entry and chorded entry? What about a creative combination of all of the above which utilizes 100% custom hardware? No problem. This is all possible diff --git a/docs/CharaChorder X.rst b/docs/CharaChorder X.rst index 6db5c8e..e372147 100644 --- a/docs/CharaChorder X.rst +++ b/docs/CharaChorder X.rst @@ -71,12 +71,12 @@ additional software to work. .. warning:: IMPORTANT: During your first time plugging your CharaChorder in, - and every time thereafter when you have :doc:`realtime feedback` + and every time thereafter when you have :ref:`realtime feedback` enabled, it’s recommended that you have your cursor in a blank typing space. The CharaChorder has a welcome message that can send instructions to your computer that are not intended by the user. This feature can be disabled in - the :doc:`GTM`. + the :doc:`GTM`. Take the male USB-A connector from your keyboard and plug it into the CharaChorder X's female USB-A port. After that, take the male USB'A connector on the CharaChorder X and plug it into a female USB-A port on your computer. @@ -87,18 +87,18 @@ following things: - Regardless of whether or not your cursor is somewhere where text can be entered: You will be able to see a small, red colored light inside the shell of the CharaChorder X. -If you have :doc:`realtime feedback` enabled, once you can see the highlighted text that reads +If you have :ref:`realtime feedback` enabled, once you can see the highlighted text that reads “CCOS is ready”, your device is ready to be used. .. note:: - IMPORTANT: :doc:`Realtime feedback` is enabled by default on new CharaChorder devices. + IMPORTANT: :ref:`Realtime feedback` is enabled by default on new CharaChorder devices. Getting Started *************** There are a few steps that you’ll likely want to take if this is your first time using your CharaChorder device. In the following section, we -will update your device, explain navigation in the :doc:`GTM`, and demonstrate the default layout on your new +will update your device, explain navigation in the :doc:`GTM`, and demonstrate the default layout on your new device. Updating your Device @@ -134,7 +134,7 @@ which is the latest firmware release by visiting `this site `__. .. warning:: - **IMPORTANT**: Before performing the below steps, please make sure that you have a :doc:`backup of your layout` as well as a :doc:`backup of your chord library`. The update might reset those, so it's important that you keep backup files handy. For instructions on how to restore backed up files, visit the :doc:`Backups` section. The update might also reset some of your :doc:`GTM` settings. Be sure to write down settings before you update. + **IMPORTANT**: Before performing the below steps, please make sure that you have a :ref:`backup of your layout` as well as a :ref:`backup of your chord library`. The update might reset those, so it's important that you keep backup files handy. For instructions on how to restore backed up files, visit the :ref:`Backups` section. The update might also reset some of your :doc:`GTM` settings. Be sure to write down settings before you update. #. On a chromium based browser, such as Chrome, go to the CharaChorder `Device Manager `__ #. Click “Connect” @@ -155,7 +155,7 @@ site `__. At this point, your CharaChorder X will automatically reboot and the CharaChorder drive will have disappeared. Congratulations! You have successfully updated your device. You can check your device’s firmware -version by following the steps :ref:`here`. +version by following the steps :ref:`here`. Understanding the Settings -------------------------- @@ -165,7 +165,7 @@ device is plug-and-play, you don’t need any software to edit the device’s settings; all you need is a place to type text. We call these settings the Generative Text Menu, or GTM for short. -You can access the :doc:`GTM` by +You can access the :doc:`GTM` by :doc:`chording` the `ESC` key and the letter `g` **(G + ESC)** in any space that allows text entry such as a notepad app. For an explanation on chords and how to perform them, visit the :doc:`Chords` section. @@ -173,7 +173,7 @@ and how to perform them, visit the :doc:`Chords` section. .. warning:: **A bug currently exists on Windows 11 default Notepad app where chording doesn't load correctly. We are looking into this, but, for now, we recommend using a different app.** -Once you perform the chord to call up the :doc:`GTM`, your CharaChorder will type out the menu and its options. +Once you perform the chord to call up the :doc:`GTM`, your CharaChorder will type out the menu and its options. It will look something like this: @@ -191,14 +191,14 @@ decrease these, you can use the up and down arrow keys on your keyboard. ``CharaChorder > Chording > Press Tolerance [ Use up/down arrow keys to adjust: 25ms ]`` -You can read an explanation on all of the settings on your CharaChorder device :doc:`here`. +You can read an explanation on all of the settings on your CharaChorder device :doc:`here`. The Layout ------------- The CharaChorder X uses your keyboard's layout, so you don't have to learn a new one. The CharaChorder X reads the keycodes that your keyboard sends and makes use of them to produce outputs on your computer. The only drawback to this is that the CharaChorder X is unable to read keypresses that do not send a code. One common key that doesn't send a code is the Fn key. This key serves as a layer-access key, locally on your keyboard, that allows you to reach the F-keys. Although the CharaChorder X is unable to read the Fn keypress, the F-keys (F1-F24) will send out a keycode, and, thus, the CharaChorder X will send out that signal to the computer. -Additionally, the CharaChorder X enables you to make use of two extra layers as well. In order to reach those layers, you will have to :doc:`remap` your keyboard to include the layer access keys. Nonetheless, you can continue reading below to learn how the layers work on the CharaChorder X. +Additionally, the CharaChorder X enables you to make use of two extra layers as well. In order to reach those layers, you will have to :ref:`remap` your keyboard to include the layer access keys. Nonetheless, you can continue reading below to learn how the layers work on the CharaChorder X. Layers ~~~~~~ @@ -268,7 +268,7 @@ Configurability You can change the layout of your keyboard while it's connected to the CharaChorder X, which means that you can :doc:`remap` almost all keys. Some users may choose to :doc:`remap` their device’s layout to accommodate missing keys, such as the :doc:`DUP key`. For a thorough explanation on how remapping -works and how to remap your device, visit the :doc:`remapping section` +works and how to remap your device, visit the :ref:`remapping section` Practice ~~~~~~~~ diff --git a/docs/CharaChorder_Lite.rst b/docs/CharaChorder_Lite.rst index c4ddae0..47cdfaa 100644 --- a/docs/CharaChorder_Lite.rst +++ b/docs/CharaChorder_Lite.rst @@ -86,7 +86,7 @@ When searching for switches that fit the CCL, make sure that the switches are la .. _60% Keyboard Diagram: .. image:: /assets/images/60%KB.jpg :width: 1200 - :alt: A diagram of a 60% Keyboard + :alt: A diagram of a 60% Keyboard .. note:: Despite being a 60% keyboard, the CharaChorder Lite DOES have 4 arrow keys. @@ -334,7 +334,7 @@ Learning the Layout :width: 1200 :alt: Image showing the CharaChorder Lite default layout -The CharaChorder Lite's layout is mostly traditional QWERTY. All of the letters and numbers are where you would expect them on other keyboards. However, there are some keys that are moved around, and a couple of extra keys as well. We'll describe the Lite's layout below. Remember that you can always :ref:`remap` the keys to your liking on the `CharaChorder Device Manager `__. +The CharaChorder Lite's layout is mostly traditional QWERTY. All of the letters and numbers are where you would expect them on other keyboards. However, there are some keys that are moved around, and a couple of extra keys as well. We'll describe the Lite's layout below. Remember that you can always :ref:`remap` the keys to your liking on the `CharaChorder Device Manager `__. Earlier, we explained that the CharaChorder Lite is a 60% keyboard. It's been named that because it's missing the navigation keys usually present on 65% keyboards, though it still has four arrow keys. Therefore, it is accurate to refer to the CCL as a 60%+6 keyboard, where the 6 refers to keys that aren't usually on a 60% keyboard. Additionally, the CCL has 67 keys, instead of the 61 keys that 60% keyboards traditionally have. @@ -365,7 +365,7 @@ else. Your device will always be in the A1 layer upon boot. While the A1 layer is active on the CharaChorder Lite by default, you can map the A1 access key, which bears the name “KM_1_R” or “KM_1_L”, on the -:doc:`layout manager` site. There is no real need to map the A1 access keys. +:doc:`layout manager` site. There is no real need to map the A1 access keys. .. image:: /assets/images/LiteLayoutAlpha.png :width: 1200 @@ -393,7 +393,7 @@ A3 Layer ^^^^^^^^ The A3 layer, sometimes referred to as the “function layer”, is -accessible with the :ref:`A3 access key`. This key is not mapped by default on the CharaChorder Lite, but you can add it to your device by :ref:`remapping`. On the :ref:`CharaChorder Device Manager`, this key is assignable by the names “KM_3_L” and “KM_3_R”. +accessible with the :ref:`A3 access key`. This key is not mapped by default on the CharaChorder Lite, but you can add it to your device by :ref:`remapping`. On the :doc:`CharaChorder Device Manager`, this key is assignable by the names “KM_3_L” and “KM_3_R”. Once you've mapped the A3 layer access buttons, the A3 Layer is accessible by pressing and holding either one of them. You do not have to hold them both in order to access @@ -447,7 +447,7 @@ The CharaChorder Lite’s layout is configurable, which means that you can :doc:`remap` all keys. Though the QWERTY layout is loved by many, some users may choose to :doc:`remap` their device’s layout to better suit their personal needs. For an explanation of how remapping -works and how to remap your device, visit the :ref:`remapping section`. +works and how to remap your device, visit the :ref:`remapping section`. Practice ~~~~~~~~ diff --git a/docs/Chords.rst b/docs/Chords.rst index b3b44b6..f874b39 100644 --- a/docs/Chords.rst +++ b/docs/Chords.rst @@ -27,14 +27,15 @@ below. Throughout this guide, we might use the term “perform” when talking about carrying out a chord. .. _Chord Input: + Chord Input ~~~~~~~~~~~~~~~~~~ A chord input is the combination of keys used in order to get a desired, predetermined -:ref:`output`. For example, we can have a chord that +:ref:`output`. For example, we can have a chord that requires the simultaneous press and release of the keys ``b`` and ``c`` -to get the output “because”. In :ref:`chord notation`, +to get the output “because”. In :ref:`chord notation`, we would write that chord input as ``b+c``. Since chord inputs are performed simultaneously, meaning that all of the keys needed for an input are pressed and released at the same time, chord inputs are not @@ -46,9 +47,9 @@ Chord Output A chord output is the predetermined letters, words, phrases and/or actions that result after performing a chord. If we use the -:ref:`chord input` of ``b`` and ``c`` and the result is +:ref:`chord input` of ``b`` and ``c`` and the result is the word “because”, then the word “because” would be the output. In -:ref:`chord notation`, we would write that chord (the +:ref:`chord notation`, we would write that chord (the input and the output) as ``b+c = because``. Chord Notation @@ -90,21 +91,20 @@ How do I make Chords? You can make chords for your CharaChorder using a few different methods which we will discuss below. In order to make a chord, you will have to indicate your desired -:ref:`chord input` as well as your desired -:ref:`chord output`. +:ref:`chord input` as well as your desired +:ref:`chord output`. Your CharaChorder device already comes with some chords loaded onto it. These cover some of the most common words in the English language. You can click on the link to see that list in an external tab: `Starter Chords `_. -You can create custom chords on the :ref:`Device Manager`, -Dot I/O. Additionally, you, can create chords on the go by using -:ref:`impulse chording`. Read on for specific +You can create custom chords on the :doc:`Device Manager`. Additionally, you, can create chords on the go by using +:ref:`impulse chording`. Read on for specific instructions on how to do that. On Device Manager -~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~ The CharaChorder Device Manager is our official web based configuration tool designed for CharaChorder devices. On there, you can do a variety of things. You can read all about Device Manager in this @@ -112,31 +112,14 @@ variety of things. You can read all about Device Manager in this The process for adding chords to your CharaChorder is the same on all of our CharaChorder devices. You can -:ref:`add new chords`, or -:ref:`import an existing chord library`. +:ref:`add new chords`, or +:ref:`import an existing chord library`. Read how below. Adding New Chords on Device Manager ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -1. On a chromium based browser, such as Chrome, go to the CharaChorder :doc:`device manager`: `Weblink `__ -2. Click “Connect” -3. When the popup box comes up that reads “manager.charachorder.com wants to - connect to a serial port”, choose your CharaChorder device, then - click the blue “connect” button. You’ll know that you’re properly - connected if you can see your device name and CCOS version, similar to - the following text: - ``CHARACHORDER ONE M0 --- Version 1.1.3`` -4. Under the “Chords” section, click the button labeled “New chord”. -5. The button changes to "Hold chord". At this time, you should press and hold the keys press the keys that you want to use for your - :ref:`chord input`. The order in which the keys are pressed - is not :ref:`important`. -6. Once you are happy, let go and then in the box to the right, type in your desired - :ref:`output` -7. At this point you can add more chords, if you would like by repeating the previous steps. -8. Once you are satisfied with the :ref:`chord inputs` - and the :ref:`chord outputs`, click the “Save” - button at the top left. +The steps to do this are :ref:`in the Device Manager documentation`. Impulse chording ~~~~~~~~~~~~~~~~~~~ diff --git a/docs/Device Manager.rst b/docs/Device Manager.rst index b0afa47..798dc89 100644 --- a/docs/Device Manager.rst +++ b/docs/Device Manager.rst @@ -78,7 +78,7 @@ Additionally, you'll find a helpful toggle labeled "Auto-connect". By enabling t To the right of the connect/disconnect button, you'll find the "terminal" button. Clicking it will take you to the :ref:`terminal` page where you can send serial commands to your device. Check out the :doc:`Serial API` docs for information on what commands you can use. -One more step to the right and you'll land on the boot menu button. Here, you'll be able to reboot your device and put it into :ref:`bootloader` mode. +One more step to the right and you'll land on the boot menu button. Here, you'll be able to reboot your device and put it into :ref:`bootloader` mode. History Menu ---------------- @@ -187,7 +187,7 @@ You can follow the steps below to create a new chord on the device manager. .. Note:: In order to follow these steps, you must already have your device :ref:`connected` to the device manager. -1. Find the "New chord" text under the :ref:`search bar` and click it. +1. Find the "New chord" text under the :ref:`search bar` and click it. 2. When the text displays "Hold chord," press and hold all of the keys that you want to use as your :ref:`chord input`. Once you have pressed all of the keys, release the keys. @@ -288,13 +288,13 @@ Layer Selector **A2 Layer** - The A2 layer, sometimes referred to as the numeric layer, is accessible with the :doc:`A2 access key`. In the :doc:`device manager` this key has the name “Numeric Layer (Left)” and “Numeric Layer (Right)”, one for each hand. + The A2 layer, sometimes referred to as the numeric layer, is accessible with the :doc:`A2 access key`. In the Device Manager, this key has the name “Numeric Layer (Left)” and “Numeric Layer (Right)”, one for each hand. The A2 Layer is accessible by pressing and holding one layer access button. Any key that is mapped to the A2 Layer can only be accessed by pressing and holding the A2 Layer access key along with the target key. You do not need to :doc:`chord` the keys together; it’s only required that the A2 Layer access key is pressed while the target key is pressed. **A3 Layer** - The A3 layer, sometimes referred to as the “function layer”, is accessible with the :ref:`A3 access key`. On the :ref:`CharaChorder Device Manager`, this key is assignable by the names “Function Layer (Left)” and “Function Layer (Right)”. + The A3 layer, sometimes referred to as the “function layer”, is accessible with the :ref:`A3 access key`. In the Device Manager, this key is assignable by the names “Function Layer (Left)” and “Function Layer (Right)”. Once you've mapped the A3 layer access buttons, the A3 Layer is accessible by pressing and holding either one of them. You do not have to hold them both in order to access the A3 layer. Any key that is on the A3 Layer can only be accessed by pressing and holding the :doc:`A3 access key`, along with the target key. You do not need to :doc:`chord` the keys together; it’s only required that the A3 layer access key is pressed while the target key is pressed. @@ -341,7 +341,7 @@ You can use action codes in chord outputs as well as while :ref:`remapping` interprets as characters. **Put simply, they are the characters that we see while typing.** These include letters, numbers, special characters, function keys, and others. +Action codes are data that :doc:`CCOS` interprets as characters. **Put simply, they are the characters that we see while typing.** These include letters, numbers, special characters, function keys, and others. Action Code Menu ^^^^^^^^^^^^^^^^^^^^^^^ @@ -351,7 +351,7 @@ You can open the action codes menu one of two ways: 2. While editing your layout in the :ref:`layout editor`, click on a key to bring up the action codes menu. -In this menu, you can scroll through :ref:`available action codes` by :ref:`category`, or simply search specific actions. +In this menu, you can scroll through :ref:`available action codes` by :ref:`category`, or simply search specific actions. If you ever need to leave the action codes menu, simply click the X at the top right of the menu. This will close out the box and not make any changes. @@ -406,7 +406,7 @@ You can see the action codes below, or view them externally `here. ` CCOS device. Read on to see the different settings you can change. You can find more detailed explanations in the :ref:`GTM` section. +On the Settings tab in the top navigation bar of the Device Manager page, you can adjust the settings of your :ref:`connected` CCOS device. Read on to see the different settings you can change. You can find more detailed explanations in the :doc:`GTM` section. Spurring ---------- @@ -673,7 +673,7 @@ Additionally, you can restore your chords, your layout, and your settings on the 3. Select a file to use to restore from. This file should be in .json format. .. note:: - Files that you can restore from will have been created ahead of time by following the :ref:`steps to create a backup`. + Files that you can restore from will have been created ahead of time by following the :ref:`steps to create a backup`. 4. If there are changes, the :ref:`save button` will appear on the top left. Note the changes in the appropriate tab. If you restored chords, check the :ref:`chords tab`, if you restored a layout, check the :ref:`layout tab`, and if you restored settings, check the :ref:`settings tab`. diff --git a/docs/GenerativeTextMenu.rst b/docs/GenerativeTextMenu.rst index 572162f..fc20d37 100644 --- a/docs/GenerativeTextMenu.rst +++ b/docs/GenerativeTextMenu.rst @@ -6,16 +6,16 @@ Generative Text Menu (GTM) ``CharaChorder GTM [ >KMCDR` settings including :ref:`chording tolerances`, :ref:`mouse speeds`, and :ref:`realtime feedback`, among other settings and features, without the need to use a software. It's a core feature of :doc:`CCOS` that you will want to +anywhere you type. Through it, we are able to modify :doc:`CCOS` settings including :ref:`chording tolerances`, :ref:`mouse speeds`, and :ref:`realtime feedback`, among other settings and features, without the need to use a software. It's a core feature of :doc:`CCOS` that you will want to learn how to use to make the device your own. -You will notice that some settings have different press and release values. This is because the switches are read by the :doc:`CCOS` at two different moments in time: when they are pressed, and when they are released. We have designed :doc:`CCOS` to have configurable settings for each of those "events" separately, for maximum adjustability. Intuitively, each **press** setting, such as :ref:`debounce press`, will affect the way that the :doc:`CCOS` reads the switch at the time that the switch is pressed into any one direction. Conversely, **release** settings, such as :ref:`release debounce`, will change the way that the :doc:`CCOS` reads the switch at the exact moment that the switch is released, or un-pressed, from any one direction. +You will notice that some settings have different press and release values. This is because the switches are read by the :doc:`CCOS` at two different moments in time: when they are pressed, and when they are released. We have designed :doc:`CCOS` to have configurable settings for each of those "events" separately, for maximum adjustability. Intuitively, each **press** setting, such as :ref:`debounce press`, will affect the way that the :doc:`CCOS` reads the switch at the time that the switch is pressed into any one direction. Conversely, **release** settings, such as :ref:`release debounce`, will change the way that the :doc:`CCOS` reads the switch at the exact moment that the switch is released, or un-pressed, from any one direction. .. note:: Although you can configure your CCOS settings anywhere that you can type through the GTM, you can also edit them on the :doc:`CharaChorder Device Manager`. .. warning:: - Please note that updating your CCOS device might reset your GTM settings to default. Please make sure that you have a :doc:`backup of your GTM settings` before updating your CCOS device. For instructions on how to restore backed up files, visit the :doc:`Backups` section. + Please note that updating your CCOS device might reset your GTM settings to default. Please make sure that you have a :ref:`backup of your GTM settings` before updating your CCOS device. For instructions on how to restore backed up files, visit the :ref:`Restoring from a Backup` section. .. contents:: Table of Contents of this Page :local: @@ -35,7 +35,6 @@ Use the table below to find out how to trigger the GTM for your CCOS device. Ple "CharaChorder X", "Chord ``G`` and ``Esc`` key" "CharaChorder Engine", "Chord ``G`` and ``Esc`` key" -.. _How to navigate through the GTM: How to navigate through the GTM ******************************* @@ -52,7 +51,6 @@ In some submenus, you will see numeric values. In order to increase or decrease ``CharaChorder > Chording > Press Tolerance [ Use up/down arrow keys to adjust: 25ms ]`` -.. _Available Menus: Available Menus *************** @@ -65,13 +63,11 @@ Available Menus ":ref:`Display`","Settings related to your device version and other CCOS texts" ":ref:`Resources`", "A menu of resources, mostly links" -.. _Keyboard: Keyboard -------- Under this menu, you will be able to modify settings pertaining to how your CCOS device interacts with your computer. -.. _Scan Rate: Scan Rate ~~~~~~~~~ @@ -93,7 +89,6 @@ You can find the default scan rates of the different CharaChorder devices in the +------------------+----------------+------------+------------+---------------+ -.. _Debounce Press: Debounce Press ~~~~~~~~~~~~~~ @@ -101,7 +96,7 @@ Debounce Press The debounce press setting refers to the time frame (measured in milliseconds) in which :doc:`CCOS` will filter out duplicate key activations on a press event. In other words, any duplicate activations within the given time frame will only be counted as one. -We should adjust this setting if we are having unintentional duplicate characters while typing. Increasing this value will lower the probability that unwanted duplicate characters will appear because it tells :doc:`CCOS` to wait longer before typing an additional character that's assigned to the same switch-direction. However, having this setting set too high might also cause issues with :doc:`CCOS` not reading intentional double-presses, so it's recommended to try different numbers in small increments. This setting should be used in connection with the :ref:`debounce release` setting. +We should adjust this setting if we are having unintentional duplicate characters while typing. Increasing this value will lower the probability that unwanted duplicate characters will appear because it tells :doc:`CCOS` to wait longer before typing an additional character that's assigned to the same switch-direction. However, having this setting set too high might also cause issues with :doc:`CCOS` not reading intentional double-presses, so it's recommended to try different numbers in small increments. This setting should be used in connection with the :ref:`debounce release` setting. You can find the default debounce press value of the different CharaChorder devices in the table below: @@ -117,7 +112,6 @@ You can find the default debounce press value of the different CharaChorder devi -.. _Debounce Release: Debounce Release ~~~~~~~~~~~~~~~~ @@ -125,7 +119,7 @@ Debounce Release The debounce release setting refers to the time frame (measured in milliseconds) in which :doc:`CCOS` will filter out duplicate key activations on a release event. In other words, any duplicate activations within the given time frame will only be counted as one. -We should adjust this setting if we are having unintentional duplicate characters while typing. Increasing this value will lower the probability that unwanted duplicate characters will appear because it tells :doc:`CCOS` to wait longer before typing an additional character that's assigned to the same switch-direction. However, having this setting set too high might also cause issues with :doc:`CCOS` not reading intentional double-presses, so it's recommended to try different numbers in small increments. This setting should be used in connection with the :ref:`debounce press ` setting. +We should adjust this setting if we are having unintentional duplicate characters while typing. Increasing this value will lower the probability that unwanted duplicate characters will appear because it tells :doc:`CCOS` to wait longer before typing an additional character that's assigned to the same switch-direction. However, having this setting set too high might also cause issues with :doc:`CCOS` not reading intentional double-presses, so it's recommended to try different numbers in small increments. This setting should be used in connection with the :ref:`debounce press ` setting. You can find the default debounce release value of the different CharaChorder devices in the table below: @@ -139,9 +133,6 @@ You can find the default debounce release value of the different CharaChorder d | CharaChorder X | 1 ms | 0 ms | 100 ms | 1 ms | +------------------+----------------+------------+------------+---------------+ - - -.. _Keystroke Delay: Keystroke Delay ~~~~~~~~~~~~~~~ @@ -165,8 +156,6 @@ This value is adjusted in 40us increments. You can find the default debounce pre | CharaChorder X | 480 μs | 0 μs | 10200 μs | 40 μs | +------------------+----------------+------------+-------------+--------------+ - -.. _Capslock: Capslock ~~~~~~~~ @@ -175,7 +164,6 @@ Capslock This setting is similar to a computer's Capslock: it toggles the state of the capslock. When on, all letters output by the CCOS device will be capitalized. When off, all letters output by the CCOS device will be lowercase. -.. _Operating System: Operating System ~~~~~~~~~~~~~~~~ @@ -197,8 +185,6 @@ The intent of this setting is to provide more accurate key mapping. As such, it .. Warning:: As of December of 2023, this setting doesn't do anything on CCOS devices. - -.. _GUI-CTRL Soft Swap (CharaChorder Lite only): GUI-CTRL Soft Swap (CharaChorder Lite only) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -228,13 +214,11 @@ This setting has two options: GUI-CTRL and CTRL-GUI. This setting is set to GUI- Users who are used to traditional keyboard layouts will want to take advantage of this setting so they don't have to relearn the new position of the keys. -.. _Mouse: Mouse ----- CCOS allows you to use your device as a mouse including functions like scrolling and cursor movement. This section will cover settings that relate to the mouse function on CCOS devices. -.. _Poll Rate: Poll Rate ~~~~~~~~~ @@ -263,9 +247,8 @@ You can find the default settings for each device in the table below: "CharaChorder Lite", "20 ms", "0 ms", "100 ms", "1 ms (Hz)" "CharaChorder X", "20 ms", "0 ms", "100 ms", "1 ms (Hz)" -This setting is used in conjunction with the :ref:`slow speed ` and :ref:`fast speed ` settings. Both, the :ref:`slow speed ` and the :ref:`fast speed ` rely on the poll rate. +This setting is used in conjunction with the :ref:`slow speed ` and :ref:`fast speed ` settings. Both, the :ref:`slow speed ` and the :ref:`fast speed ` rely on the poll rate. -.. _Slow Speed: Slow Speed ~~~~~~~~~~ @@ -273,13 +256,13 @@ Slow Speed Slow speed is activated when you use only one of the mouse keys in a single direction (as opposed to using 2 keys in the same direction). Increasing this setting will make your CCOS pointer move faster. -This setting is used in conjunction with :ref:`poll rate `. See the explanation below. +This setting is used in conjunction with :ref:`poll rate `. See the explanation below. .. dropdown:: Explanation of CCOS mouse speeds - The mouse speed refers to the speed of the cursor on the CharaChorder's mouse functionality. The cursor will move at the number of pixels (px) indicated by this setting multiplied by the number of Hz indicated by the :ref:`polling rate`. + The mouse speed refers to the speed of the cursor on the CharaChorder's mouse functionality. The cursor will move at the number of pixels (px) indicated by this setting multiplied by the number of Hz indicated by the :ref:`polling rate`. - In other words, if your speed is set to 2 px, and your :ref:`poll rate` is set to 20 ms (~50 Hz), your CharaChorder's cursor will move at 100 pixels per second (px/s). The equation comes out to: + In other words, if your speed is set to 2 px, and your :ref:`poll rate` is set to 20 ms (~50 Hz), your CharaChorder's cursor will move at 100 pixels per second (px/s). The equation comes out to: ``Speed (px) x poll rate (Hz) = Number of pixels that the cursor will move per second`` @@ -292,8 +275,6 @@ You can find the default settings for each device in the table below: "CharaChorder Lite", "16 px", "0 px", "250 px", "1 px" "CharaChorder X", "16 px", "0 px", "250 px", "1 px" - -.. _Fast Speed: Fast Speed ~~~~~~~~~~ @@ -301,13 +282,13 @@ Fast Speed Fast speed is activated when you use two mouse keys in a single direction (as opposed to using only one key in the same direction). Increasing this setting will make your CCOS pointer move faster. -This setting is used in conjunction with :ref:`poll rate `. See the explanation below. +This setting is used in conjunction with :ref:`poll rate `. See the explanation below. .. dropdown:: Explanation of CCOS mouse speeds - The mouse speed refers to the speed of the cursor on the CharaChorder's mouse functionality. The cursor will move at the number of pixels (px) indicated by this setting multiplied by the number of Hz indicated by the :ref:`polling rate`. + The mouse speed refers to the speed of the cursor on the CharaChorder's mouse functionality. The cursor will move at the number of pixels (px) indicated by this setting multiplied by the number of Hz indicated by the :ref:`polling rate`. - In other words, if your speed is set to 2 px, and your :ref:`poll rate` is set to 20 ms (~50 Hz), your CharaChorder's cursor will move at 100 pixels per second (px/s). The equation comes out to: + In other words, if your speed is set to 2 px, and your :ref:`poll rate` is set to 20 ms (~50 Hz), your CharaChorder's cursor will move at 100 pixels per second (px/s). The equation comes out to: ``Speed (px) x poll rate (Hz) = Number of pixels that the cursor will move per second`` @@ -320,7 +301,6 @@ You can find the default settings for each device in the table below: "CharaChorder Lite", "32 px", "0 px", "250 px", "1 px" "CharaChorder X", "32 px", "0 px", "250 px", "1 px" -.. _Scroll Speed: Scroll Speed ~~~~~~~~~~~~ @@ -328,13 +308,13 @@ Scroll Speed Scroll speed refers to the speed at which your CCOS scroll will scroll. -Increasing this setting will make your CCOS scrolling scroll faster. This setting is used in conjunction with :ref:`poll rate `. See the explanation below. +Increasing this setting will make your CCOS scrolling scroll faster. This setting is used in conjunction with :ref:`poll rate `. See the explanation below. .. dropdown:: Explanation of CCOS mouse speeds - The scroll speed refers to the speed at which the CharaChorder scrolls at. The CCOS will scroll at the number of pixels (px) indicated by this setting multiplied by the number of Hz indicated by the :ref:`polling rate`. + The scroll speed refers to the speed at which the CharaChorder scrolls at. The CCOS will scroll at the number of pixels (px) indicated by this setting multiplied by the number of Hz indicated by the :ref:`polling rate`. - In other words, if your speed is set to 2 px, and your :ref:`poll rate` is set to 20 ms (~50 Hz), your CharaChorder's scroll will move at 100 pixels per second (px/s). The equation comes out to: + In other words, if your speed is set to 2 px, and your :ref:`poll rate` is set to 20 ms (~50 Hz), your CharaChorder's scroll will move at 100 pixels per second (px/s). The equation comes out to: ``Speed (px) x poll rate (Hz) = Number of pixels that the cursor will move per second`` @@ -348,7 +328,6 @@ You can find the default settings for each device in the table below: "CharaChorder X", "2 px", "0 px", "25 px", "1 px" -.. _Active Mode: Active Mode ~~~~~~~~~~~ @@ -357,13 +336,11 @@ Active Mode Active mode nudges your mouse cursor one pixel every minute or so (not a specific timing). This setting can be used to keep your computer from going to sleep. You might turn this setting off if you notice desktop apps are preventing you from getting mobile notifications (for example on Discord or Microsoft Teams). -.. _Chording: Chording -------- CCOS devices feature the ability to :doc:`chord`. The following settings affect the device's chording abilities. -.. _Character Only Mode: Character Only Mode ~~~~~~~~~~~~~~~~~~~ @@ -373,7 +350,6 @@ This setting is a toggle that disables chording capabilities on CCOS devices. It If your CCOS device suddenly loses its chording ability, it's a good idea to check if this setting is toggled off. -.. _Press Tolerance: Press Tolerance ~~~~~~~~~~~~~~~ @@ -387,14 +363,14 @@ The press tolerance refers to a window of time in which a chord can be performed :width: 1200 :alt: Diagram Explaining Tolerances -Put simply, increasing the press tolerance (usually, done in conjunction with increasing the :ref:`release tolerance `) makes it easier to perform chords. +Put simply, increasing the press tolerance (usually, done in conjunction with increasing the :ref:`release tolerance `) makes it easier to perform chords. .. note:: The press tolerance scales (increases) according to the number of keys in a chord. The window of time will be bigger with a 6-key chord than with a 3-key chord. This means that, though you might set the tolerance to a specific timing, it will actually be longer than that depending on how many keys are in your chord. You can increase this setting in order to make that window of time longer and make chording easier. -The downside to having higher values is that you may accidentally trigger chords during normal character entry. Therefore, if you are noticing chords fire unintentionally, it is a good idea to lower this setting along with the :ref:`release tolerance `. +The downside to having higher values is that you may accidentally trigger chords during normal character entry. Therefore, if you are noticing chords fire unintentionally, it is a good idea to lower this setting along with the :ref:`release tolerance `. You can find the default settings for each device in the table below: @@ -405,7 +381,6 @@ You can find the default settings for each device in the table below: "CharaChorder Lite", "25 ms", "0 ms", "150 ms", "1 ms" "CharaChorder X", "25 ms", "0 ms", "150 ms", "1 ms" -.. _Release Tolerance: Release Tolerance ~~~~~~~~~~~~~~~~~ @@ -413,20 +388,18 @@ Release Tolerance The release tolerance refers to a window of time in which a chord can be performed, measured in milliseconds (ms). This timer is initiated upon the first "release" action of any key in a chord and ends once the chord is fully performed, or until the release tolerance runs out, whichever comes first. -.. _Tolerances: - .. image:: /assets/images/Press-and-Release-Tolerances.png :width: 1200 :alt: Diagram Explaining Tolerances -Put simply, increasing the release tolerance (usually, done in conjunction with increasing the :ref:`press tolerance `) makes it easier to perform chords. +Put simply, increasing the release tolerance (usually, done in conjunction with increasing the :ref:`press tolerance `) makes it easier to perform chords. .. note:: The press tolerance scales (increases) according to the number of keys in a chord. The window of time will be bigger with a 6-key chord than with a 3-key chord. This means that, though you might set the tolerance to a specific timing, it will actually be longer than that depending on how many keys are in your chord. You can increase this setting in order to make that window of time longer and make chording easier. -The downside to having higher values is that you may accidentally trigger chords during normal character entry. Therefore, if you are noticing chords fire unintentionally, it is a good idea to lower this setting along with the :ref:`press tolerance `. +The downside to having higher values is that you may accidentally trigger chords during normal character entry. Therefore, if you are noticing chords fire unintentionally, it is a good idea to lower this setting along with the :ref:`press tolerance `. You can find the default settings for each device in the table below: @@ -438,7 +411,6 @@ You can find the default settings for each device in the table below: "CharaChorder X", "18 ms", "0 ms", "150 ms", "1 ms" -.. _Timeout: Timeout ~~~~~~~ @@ -464,17 +436,15 @@ You can find the default settings for each device in the table below: "CharaChorder Lite", "4 s", "0 s", "25 s", "0.1 s" "CharaChorder X", "4 s", "0 s", "25 s", "0.1 s" -.. _Spurring: Spurring ~~~~~~~~ ``Path: GTM > Chording > Spurring`` -A 'chording only' mode which tells your device to output chords on a press event rather than a press & release and release event. When in spurring mode, you can press the keys of a chord one at a time with a much longer waiting period, which makes it a useful mode for those who want to practice chording without worrying about proper :ref:`timing`. +A 'chording only' mode which tells your device to output chords on a press event rather than a press & release and release event. When in spurring mode, you can press the keys of a chord one at a time with a much longer waiting period, which makes it a useful mode for those who want to practice chording without worrying about proper :ref:`timing`. Spurring mode also enables you to jump from one chord to another without releasing everything. It can provide significant speed gains when chording, but also takes away the flexibility of character entry. Spurring mode can truly maximize speed when chording if a user has chords for all of the words they want to use. -.. _Spurring On/Off: Spurring On/Off ^^^^^^^^^^^^^^^ @@ -482,7 +452,6 @@ Spurring On/Off This setting will toggle spurring mode ON or OFF. -.. _Spurring Timeout: Spurring Timeout ^^^^^^^^^^^^^^^^ @@ -499,18 +468,16 @@ You can find the default settings for each device in the table below: "CharaChorder Lite", "240 s", "0 s", "250 s", "1 s" "CharaChorder X", "240 s", "0 s", "250 s", "1 s" -.. _Arpeggiate: Arpeggiate ~~~~~~~~~~ ``Path: GTM > Chording > Arpeggiate`` -Arpeggiate actions are timed actions that can modify a chord after the chord is performed. A quick example of this is the use of :doc:`chord modifiers` after you perform the chord. You can read that section for information on how the :doc:`chord modifiers` work. +Arpeggiate actions are timed actions that can modify a chord after the chord is performed. A quick example of this is the use of chord modifiers after you perform the chord. You can read that section for information on how the :doc:`chord modifiers` work. -With arpeggiates enabled, you can chord the word ``run`` and then, within the :ref:`arpeggiate timeout window`, press the :doc:`past tense modifier` for the word to be "modified" into its past tense variant; in english, ``ran``. +With arpeggiates enabled, you can chord the word ``run`` and then, within the :ref:`arpeggiate timeout window`, press the past tense modifier for the word to be "modified" into its past tense variant; in english, ``ran``. -.. _Arpeggiate On/Off: Arpeggiate On/Off ^^^^^^^^^^^^^^^^^ @@ -520,7 +487,6 @@ This setting will let you toggle the arpeggiate capability ON or OFF. Some users dislike arpeggiates as, in really fast typing, it may cause unwanted modifications. -.. _Arpeggiate Timeout: Arpeggiate Timeout ^^^^^^^^^^^^^^^^^^ @@ -530,13 +496,11 @@ The arpeggiate timeout is a window of time after a chord is performed during whi A common issue that users may run into while having arpeggiates enabled is the shift key modifying the preceding chord instead of the next key. For this reason, some users lower the arpeggiate timeout to a really low amount of time in order to reduce the possibility of this happening unintentionally. -.. _Display: Display ------- Under this section, you'll find settings that deal with how your CharaChorder displays certain things. -.. _Version: Version ~~~~~~~ @@ -544,7 +508,6 @@ Version Though this is not a setting that can be modified, it's a useful piece of text that will show you the CCOS version that your CharaChorder is currently on. You can use this to quickly check what version you are running on the fly, anywhere that you can read GTM -.. _Realtime Feedback: Realtime Feedback ~~~~~~~~~~~~~~~~~ @@ -555,9 +518,8 @@ This setting toggles realtime feedback ON or OFF. Realtime feedback refers to the helpful text like ``SPURRING_ON``, ``SPURRING_OFF`` etc, that lets the user know if a certain mode has been activated or deactivated on the CharaChorder device. Since there is no other visual way to know if the chord used to enable or disable certain settings, it is helpful to have these texts pop up as confirmation. .. Note:: - The realtime feedback setting controls the :ref:`startup` setting. If realtime feedback is OFF, then startup will be OFF, regardless of that setting's individual toggle. + The realtime feedback setting controls the :ref:`startup` setting. If realtime feedback is OFF, then startup will be OFF, regardless of that setting's individual toggle. -.. _Startup: Startup ~~~~~~~ @@ -570,9 +532,8 @@ However, if you have editable text highlighted when you connect your CharaChorde If you would rather not have this message display every time that you connect your device, then you can toggle this setting OFF. .. Warning:: - The Startup setting is dependent on the :ref:`realtime feedback setting`. If that setting is set to OFF, then Startup won't display, even if Startup is set to ON. + The Startup setting is dependent on the :ref:`realtime feedback setting`. If that setting is set to OFF, then Startup won't display, even if Startup is set to ON. -.. _LEDs (CharaChorder Lite only): LEDs (CharaChorder Lite only) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -583,7 +544,6 @@ The :doc:`CharaChorder Lite` comes with RGB LEDs that light u .. note:: LED settings only exist in the GTM for :doc:`CharaChorder Lite` devices, not on any other CharaChorder devices. -.. _LED On/Off: On/Off ^^^^^^ @@ -591,7 +551,6 @@ On/Off Quickly toggle the LEDs on or off with this setting. -.. _LED Color: Color ^^^^^ @@ -616,7 +575,6 @@ Use this setting to change the color of the LED backlights on your CharaChorder Please note that, as of December of 2023, the LEDs are NOT individually addressable. The color setting changes the color of ALL LEDs at the same time. -.. _LED Brightness: Brightness ^^^^^^^^^^ @@ -637,7 +595,6 @@ You can find the default settings for the CharaChorder Lite in the table below: "CharaChorder Lite", "5", "0", "50", "1" -.. _Resources: Resources --------- diff --git a/docs/Glossary.rst b/docs/Glossary.rst index d2d3904..7655a1d 100644 --- a/docs/Glossary.rst +++ b/docs/Glossary.rst @@ -54,7 +54,7 @@ community. GTM (Generative Text Menu) A text-based menu accessible anywhere you type. It allows access to - various device settings and features without software. See :doc:`Generative Text Menu (GTM)`. + various device settings and features without software. See :doc:`GenerativeTextMenu`. Impulse Chord An 'on-the-fly' custom chord that can be spontaneously created anywhere