docs: upgrading & general settings

CHANGELOG.md

@@ -3,7 +3,7 @@
 This version introduces huge (and _breaking_) changes. **Make sure to refer to
 [the “Upgrading”
 section](https://alternerdtive.github.io/VoiceAttack-profiles/upgrading/) in the
-new documentation if you are upgrading from an older version!**
+documentation if you are upgrading from an older version!**
 
 Oh yes, there is [an all new and improved documentation
 now](https://alternerdtive.github.io/VoiceAttack-profiles)!
@@ -52,6 +52,9 @@ able to invoke that plugin. [You can safely ignore that](https://github.com/alte
   also possible, but not on the roadmap yet.
 * EDDI events (and some other more administrative commands) are now hidden from
   the VoiceAttack log.
+* `power to` command now supports of lot more options. `power to X and Y` sets
+  8/4/0, `balanced power to X and Y` sets 6/6/0, `half power to X` sets 6/3/3,
+  `half power to X and Y` sets 5/5/2.
 
 ### EliteAttack 8.0
 
@@ -88,7 +91,8 @@ profile will keep the old name. Feel free to manually rename it.
 ### Changed
 
 * RATSIGNAL handling is no longer done through a file, there is now a helper
-  tool that communicates with the plugin directly.
+  tool that communicates with the plugin directly. See “Upgrading” in the
+  documentation.
 * Now supports up to 30 cases (0–29). Thanks, Epicalypse!
 
 ### Fixed

docs/configuration/general.md

@@ -1,18 +1,26 @@
 # General Configuration
 
-Additionally, you need to have keyboard binds setup at least as secondary 
-bindings in Elite’s controls options. VA _cannot_ “push” joystick buttons for 
-you, it can only do keyboard inputs. Hence its only way to interact with Elite 
-is through keyboard emulation, even if you otherwise play the game with 
-a controller or HOTAS. Or racing wheel. Or Rock Band set. Or bananas.
+## Settings
 
+All profiles will load sane defaults if you haven’t changed anything. The
+configuration is stored in a bunch of VoiceAttack variables stored in your
+custom profile. You could even have different custom profiles with their own
+distinct settings.
 
-### Settings ###
+You change the configuration via voice commands:
 
-All profiles will load sane defaults if you haven’t changed anything. You no 
-longer need to fiddle with the `startup` commands of each profile, instead you 
-can use voice commands to change settings! See the `docs/` and the 
-`_configuration` commands section of each profile.
+* For booleans (toggles): `customize setting [enable;disable] <trigger phrase>`
+* For everything else: `customize setting set <trigger phrase>`
+
+You can find a list of trigger phrases here, or you can say
+`customize setting list [options;settings]` for a list of voice triggers and
+what they do. If you don’t remember your settings or just want a nice list,
+`customize setting report [options;settings]` will print that to the
+VoiceAttack log. If you want to reset everything back to default state, say
+`customize setting clear all my settings`.
+
+The “customize setting” preset is kind of a leftover from times long gone and
+does not quite fit anymore. Might change in a future version.
 
 Basically all the settings are available using the `customize settings` prefix, 
 then saying `[enable;disable] <setting>` for on/off switches and `set <setting>` 
@@ -21,22 +29,33 @@ for text variables.
 One caveat applies: settings will only be saved in the profile you have 
 selected, but be preserved if you switch around.
 
-### Making changes ###
+### General Settings for All Profiles
+
+Toggles:
+
+* `eddi quiet mode`: Make EDDI shut up. Disables all built-in speech responders.
+
+Other settings:
+
+* `elite paste key`: The key used to paste in conjunction with CTRL. The
+  physical key in your layout that would be 'V' on QWERTY.
+* `log level`: The level of detail for logging to the VoiceAttack log. Valid
+  levels are "ERROR", "WARN", "NOTICE", "INFO" and "DEBUG". Default: "NOTICE".
+
+## Adding Commands
 
 If you want to edit a command or add your own, _do not edit the profiles 
 directly_. Instead create commands in your custom profile, and copy commands you 
 want to change over to that before editing them. This will make sure no changes 
 are lost if you update the profiles.
 
+### EDDI Events
+
 Because of limitations of VoiceAttack itself, only the first matching command
 found will be executed, _including EDDI events_. That means that if you create
-commands to handle EDDI events, you are going to have to check the imported 
-profiles if they rely on these event handlers as well, and call them manually if 
-they do.
+commands to handle EDDI events, you are going to have to make sure that the
+appropriate handlers in my profiles are called, too. That is done by invoking
+the `eddi.Event` plugin context of the `alterNERDtive-base` plugin. Otherwise
+stuff _will_ break.
 
-E.g.  if you want to create a custom `((EDDI Message sent))` handler in your 
-profile, you will have to make it excute the `EliteDangerous.EDDI Message sent` 
-and `RatAttack.EDDI Message sent` commands.  Otherwise stuff _will_ break.
-
-If you have no idea what the previous two paragraphs were about, you can most 
-likely just ignore them.
+![[EDDI-event.png]]

docs/general.md

@@ -0,0 +1 @@
+# General Commands

docs/installing.md

@@ -26,7 +26,7 @@ for you if you are not using that.
 Make sure you have plugin support enabled:
 
 1. Go to VoiceAttack settings. ![[VoiceAttack-settings.png]]
-1. Check “enable plugin support” ![[VoiceAttack-settings-plugin-support.png]]
+1. Check “enable plugin support”. ![[VoiceAttack-settings-plugin-support.png]]
 
 While you are there, you might also want to enable the automatic update checks.
 
@@ -177,7 +177,7 @@ button.
 ![[VoiceAttack-profile-options-include.png]]
 
 Add all my profiles (“EliteDangerous”, “RatAttack”, “SpanshAttack”,
-`StreamAttack`).
+“StreamAttack”).
 
 ![[VoiceAttack-profile-options-includelist.png]]
 
@@ -192,3 +192,24 @@ profile is loaded” checkbox, and select the “startup” command you have cre
 earlier.
 
 ![[VoiceAttack-profile-options-startup.png]]
+
+## Set Elite Keyboard Binds
+
+You need to have keyboard binds setup at least as secondary bindings in Elite’s
+controls options. VoiceAttack _cannot_ “push” joystick buttons for you, it can
+only do keyboard inputs. Hence its only way to interact with Elite is through
+keyboard emulation, even if you otherwise play the game with a controller or
+HOTAS. Or racing wheel. Or Rock Band set. Or bananas.
+
+![[Elite-binds.png]]
+
+Should you use a keyboard layout that is _not_ en-US QWERTY, some keys might not
+work out of the box. You can try telling bindED about your keyboard layout by
+setting the `bindED.layout#` variable (including the \#!) to something more
+appropriate in your startup command.
+
+![[bindED-layout.png]]
+
+Currently bindED supports the `en-US`, `en-GB` and `de-Neo2` layouts. [You can
+find instructions on how to add your own on
+Github](https://github.com/alterNERDtive/bindED/wiki/Keyboard-Layouts).

docs/upgrading.md

@@ -1,4 +1,60 @@
-# Upgrading #
+# Upgrading
 
-## 4.0.0 ##
+To upgrade to the latest version, follow these steps:
 
+1. Say “download profiles update”.
+1. Put the `alterNERDtive-voiceattack-profiles.vax` file from Github into the
+   “Import” folder.
+1. Restart VoiceAttack.
+
+In general, migration from old versions will be handled automatically. If there
+is something you have to do manually, you will find the information below.
+
+## 3.x.x to 4.0
+
+If you have been using a custom profile as outlined in [[Installing#Create a 
+Custom Profile]] your settings will be migrated to the new variables
+automatically.
+
+If you have not … well, you will unfortunately have to take note of your
+settings, and recreate them after creating a custom profile and including
+everything.
+
+### bindED
+
+If you have done anything non-standard with bindED before, it might break. The
+profiles now include my fork of bindED which has a lot more features, but
+doesn’t support a bunch of plugin invocations that have become obsolete.
+
+### RatAttack
+
+Handing a RATSIGNAL from IRC to VoiceAttack via text file is now deprecated and
+support for that will be removed in a future version.
+
+Instead you should use the new `RatAttack-cli.exe` helper tool that uses IPC to
+talk to the VoiceAttack plugin. For that you have to change the way your IRC
+client handles incoming case announcements. Instead of writing the announcement
+to the text file and walling VoiceAttack to run a command, it will have to call
+the helper tool with a) the announcement and b) an optional true/false switch to
+determine if the case should be announced via TTS or just added to the case
+list.
+
+For my AdiIRC, it looks like this (obviously change the path, please):
+
+```adiirc
+on *:TEXT:RATSIGNAL - CMDR*(??_SIGNAL):#fuelrats:{
+  if ( $away ) {
+    /run -h "X:\path\to\VoiceAttack\Apps\alterNERDtive\RatAttack-cli.exe" " $+ $replace($1-,","") $+ " false
+  }
+  else {
+    /run -h "X:\path\to\VoiceAttack\Apps\alterNERDtive\RatAttack-cli.exe" " $+ $replace($1-,","") $+ " true
+  }
+}
+```
+
+If I am away it will just add the new case to the list. If I am not away, it
+will announce it using TTS.
+
+The “replace” part handles the fact that announcements now put the system in
+quotes. They have to be escaped as double quotes (`""`) to create a correct
+command invocation.

mkdocs.yml

@@ -30,18 +30,19 @@ nav:
         - 'installing.md'
         - 'upgrading.md'
     - 'Configure':
-        - 'configuration/VoiceAttack.md'
         - 'configuration/general.md'
         - 'configuration/EliteAttack.md'
         - 'configuration/RatAttack.md'
         - 'configuration/SpanshAttack.md'
         - 'configuration/StreamAttack.md'
     - 'Use':
+        - 'general.md'
         - 'EliteAttack.md'
         - 'RatAttack.md'
         - 'SpanshAttack.md'
         - 'StreamAttack.md'
     - 'Issues':
+        - 'VoiceAttack tips': 'VoiceAttack.md'
         - 'troubleshooting.md'
         - 'Report a Bug': 'https://github.com/alterNERDtive/VoiceAttack-profiles/issues/new'
     - 'Watch in Action':

plugins/VoiceAttack-base/util.cs

@@ -20,10 +20,8 @@ namespace alterNERDtive.util
             {
                 "alterNERDtive-base",
                 new OptDict<string, Option>{
-                    { new Option<bool>("eddi.quietMode", true, voiceTrigger: "eddi quiet mode", description: "Make EDDI shut up. Disables all built-in speech respondes.") },
+                    { new Option<bool>("eddi.quietMode", true, voiceTrigger: "eddi quiet mode", description: "Make EDDI shut up. Disables all built-in speech responders.") },
                     { new Option<decimal>("keyPressDuration", (decimal)0.01, voiceTrigger: "key press duration", description: "The time keys will be held down for.") },
-                    { new Option<decimal>("delays.quitToDesktop", (decimal)10.0, voiceTrigger: "quit to desktop delay",
-                        description: "The delay before restarting the game after hitting “Exit to Desktop”.\nDefault: 10.0 seconds.") },
                     { new Option<string>("elite.pasteKey", "v", voiceTrigger: "elite paste key",
                         description: "The key used to paste in conjunction with CTRL. The physical key in your layout that would be 'V' on QWERTY.") },
                     { new Option<string>("log.logLevel", "NOTICE", voiceTrigger: "log level", validValues: new List<string>{ "ERROR", "WARN", "NOTICE", "INFO", "DEBUG" },
@@ -44,6 +42,8 @@ namespace alterNERDtive.util
                     { new Option<bool>("autoHonkNewSystems", true, voiceTrigger: "auto honk new systems", description: "Automatically honk upon entering as system if it is your first visit.") },
                     { new Option<bool>("autoRestock", true, voiceTrigger: "auto restock", description:
                         "Automatically restock after docking at a station.\nYou will alywas refuel, repair and enter the Station Services menu.") },
+                    { new Option<decimal>("delays.quitToDesktop", (decimal)10.0, voiceTrigger: "quit to desktop delay",
+                        description: "The delay before restarting the game after hitting “Exit to Desktop”.\nDefault: 10.0 seconds.") },
                     { new Option<bool>("enableAutoUpdateCheck", true, voiceTrigger: "auto update check", description: "Automatically check Github for profiles updates.") },
                     { new Option<bool>("flightAssistOff", false, voiceTrigger: "flight assist off", description: "Permanent Flight Assist off mode. You should really do that, it’s great.") },
                     { new Option<bool>("hyperspaceDethrottle", true, voiceTrigger: "hyper space dethrottle", description: "Throttle down after a jump and when dropping from SC. Like the SC Assist module does.") },