Converted doc from markdown to asciidoctor.

pre-martin · Jan 5, 2023 · 642f815 · 642f815
1 parent 27651b5
commit 642f815
Show file tree

Hide file tree

Showing 8 changed files with 104 additions and 93 deletions.
diff --git a/README.adoc b/README.adoc
@@ -0,0 +1,25 @@
+= Stream Deck SimHub Plugin
+:toc:
+
+
+== About
+
+This is a plugin for https://www.elgato.com/stream-deck[Stream Deck]. It offers Stream Deck actions, which are updating their state from https://www.simhubdash.com/[SimHub].
+
+This means, that actions can be bound to SimHub properties. If the value of a bound SimHub property changes, the button in Stream Deck will reflect this property change.
+
+This plugin depends on the https://github.com/pre-martin/SimHubPropertyServer[SimHub Property Server plugin], which has to be installed in SimHub.
+
+
+== Installation
+
+Be sure to have the SimHub Property Server plugin installed into SimHub (see above). When updating this plugin, be sure to also check the SimHub Property Server plugin for updates.
+
+For the usage of this plugin, the https://dotnet.microsoft.com/en-us/download/dotnet/6.0[.NET Runtime 6.0] has to be installed. It is very likely, that this is already installed on your PC.
+
+Download the file `net.planetrenner.simhub.streamDeckPlugin` from the GitHub "Releases" page and double-click it to install it into Stream Deck.
+
+
+== Usage
+
+See link:doc/Usage.adoc[Usage.adoc]
diff --git a/README.md b/README.md
diff --git a/StreamDeckSimHub.Plugin/README.md b/StreamDeckSimHub.Plugin/README.md
diff --git a/StreamDeckSimHub.sln b/StreamDeckSimHub.sln
@@ -7,7 +7,7 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "StreamDeckSimHub.Plugin", "
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "SolutionFiles", "SolutionFiles", "{E3F720A4-BDC4-4B7D-B604-BF323E7AB170}"
 	ProjectSection(SolutionItems) = preProject
-		README.md = README.md
+		README.adoc = README.adoc
 		release.bat = release.bat
 		deploy.bat = deploy.bat
 	EndProjectSection

diff --git a/doc/Release.adoc b/doc/Release.adoc
@@ -0,0 +1,14 @@
+= Release Process
+
+. If there is no release branch yet for the current version: +  
+   `nbgv prepare-release`
+. Switch to the release branch: +  
+   `git switch release/v1.2`
+. Push the release branch
+. Create a tag and push it afterwards:
+    - `nbgv tag`
+    - `git push origin v1.2`
+. Build the plugin:
+    - `release.bat`
+. Create a release in GitHub from the tag and attach the file `net.planetrenner.simhub.streamDeckPlugin`
+. Push the main branch.
diff --git a/doc/Release.md b/doc/Release.md
diff --git a/doc/Usage.md → doc/Usage.adoc b/doc/Usage.md → doc/Usage.adoc
@@ -1,15 +1,18 @@
-# Usage of the plugin
+= Usage of the plugin
+:toc:
+:sectnums:
 
-## Overview
+
+== Overview
 
 After the installation of the Plugin, a new category named "SimHub" will be available in Stream Deck. Use the actions of this category to get Stream Deck buttons, which will update their state from SimHub properties.
 
 
-## Actions offered by this plugin
+== Actions offered by this plugin
 
-### Hotkey
+=== Hotkey
 
-This action offers the same functionality as the built-in action "Hotkey": If the Stream Deck button is pressed, a keypress event will be sent to the active window. Please see the structure [VirtualKeyShort](/PluginNative/Tools/Keyboard.cs) for supported key names. For alphanumeric keys (0-1, A-Z) the prefix `KEY_` can be omitted, so either `KEY_P` and `P` will have the same result. Some examples of valid values for the field "Hotkey" are:
+This action offers the same functionality as the built-in action "Hotkey": If the Stream Deck button is pressed, a keypress event will be sent to the active window. Please see the structure link:/StreamDeckSimHub.Plugin/Tools/Keyboard.cs[VirtualKeyShort] for supported key names. For alphanumeric keys (0-1, A-Z) the prefix `KEY_` can be omitted, so either `KEY_P` and `P` will have the same result. Some examples of valid values for the field "Hotkey" are:
 
 - `A` (will send the event for the key "A" to the active window)
 - `KEY_A` (same as above)
@@ -22,15 +25,15 @@ Please note, that not all entries in "VirtualKeyShort" make sense in the field "
 
 The added value for this action is in the field "SimHub Property": It allows to enter the name of a SimHub property or even a logical expression with a SimHub property:
 
-#### Simple SimHub property
+==== Simple SimHub property
 
 Enter the name of a SimHub property. E.g.
 
-```
+----
 dcp.gd.EngineIgnitionOn
-```
+----
 
-The value of this SimHub property will update the state of the button. See [SimHub Property Server](https://github.com/pre-martin/SimHubPropertyServer) for a list of valid property names.
+The value of this SimHub property will update the state of the button. See https://github.com/pre-martin/SimHubPropertyServer[SimHub Property Server] for a list of valid property names.
 
 The logic for the action state depending on the SimHub property value is as follows:
 
@@ -40,18 +43,20 @@ The logic for the action state depending on the SimHub property value is as foll
 Examples:
 
 - Button to toggle the Ignition in ACC (which is mapped to "Shift + I" by default):
-  ![Ignition](Example-Ignition.png)
++
+image::Example-Ignition.png[Ignition]
 - Button to toggle the Engine in ACC (which is mapped to "S" by default):
-  ![Engine](Example-Engine.png)
++
+image::Example-Engine.png[Engine]
 - Another useful button for ACC would be the Hotkey "Alt + L" with the SimHub property "gd.sdb.PitLimiterOn" to toggle the pit limiter.
 
-#### SimHub property with logical expression
+==== SimHub property with logical expression
 
 This allows a much finer grained logic for the button state. Enter the name of a SimHub property, a condition and a value. E.g.
 
-```
+----
 acc.graphics.gapBehind<=500
-```
+----
 
 In this example, the button would be in the state "on", if the gap behind is equal to or smaller than 500 milliseconds. It would be "off", if the gap behind is greater than 500 milliseconds. The field "Hotkey" could be empty in this example, so that the Stream Deck button could be used as an indicator only.
 
@@ -60,30 +65,52 @@ The following conditions are supported:
 - `==` test for equal
 - `>=`
 - `>`
-- `<=`
+- `+<=+`
 - `<`
 - `!=` test for not equal
-- `~~` test for "between two values", which means ">= value1 and <= value2"
+- `~~` test for "between two values", which means ">= value1 and +<=+ value2"
 
-The condition "between" requires two values, which have to be separated by a semicoolon, e.g.
+The condition "between" requires two values, which have to be separated by a semicolon, e.g.
 
-```
+----
 acc.graphics.WiperLV~~1;2
-```
+----
 
 The following table shows the comparison logic for different SimHub property types and comparison values (which are entered into the Stream Deck UI):
 
-| SimHub property type | supported comparison values | evaluation rules                                            |
-|----------------------|-----------------------------|-------------------------------------------------------------|
-| boolean              | "true", "false"             | should be self explanatory                                  |
-|                      | any integer value           | comp. value == 0: "false"<br/>comp. value > 0: "true"       |
-| integer              | any integer value           | should be self explanatory                                  |
-|                      | "true", "false"             | prop. value == 1: "true"<br>all other prop. values: "false" |
-| long                 | same as "integer"           | same as integer                                             |
-| double               | any integer or floating     | should be self explanatory                                  |
+|===
+| SimHub property type | supported comparison values | evaluation rules
+
+| boolean              
+| "true", "false"             
+| should be self explanatory                 
+
+|                      
+| any integer value           
+| comp. value == 0: "false" +
+  comp. value > 0: "true"       
+
+| integer              
+| any integer value           
+| should be self explanatory                 
+
+|                      
+| "true", "false"             
+| prop. value == 1: "true" +
+  all other prop. values: "false"
+
+| long                 
+| same as "integer"           
+| same as integer                            
+
+| double               
+| any integer or floating     
+| should be self explanatory                 
+
+|===
 
 
-### Hotkey 4-state
+=== Hotkey 4-state
 
 This action is the same as the "Hotkey" action: It sends a keystroke to the active window, and it can be connected to a SimHub property, which will update its state.
 

diff --git a/release.bat b/release.bat
@@ -1,12 +1,19 @@
 @echo off
 setlocal
 
-dotnet publish StreamDeckSimHub.Plugin\StreamDeckSimHub.Plugin.csproj -c Release -r win-x64 --self-contained
+set CONFIG=Release
+if "%1%" == "debug" set CONFIG=Debug
+
+echo.
+echo Building for configuration: %CONFIG%
+echo.
+
+dotnet publish StreamDeckSimHub.Plugin\StreamDeckSimHub.Plugin.csproj -c %CONFIG% -r win-x64 --self-contained
 
 if exist build rmdir /s /q build
 if exist build goto :endFailure
 mkdir build
-xcopy StreamDeckSimHub.Plugin\bin\Release\net6.0\win-x64\publish build\net.planetrenner.simhub.sdPlugin /e /i
+xcopy StreamDeckSimHub.Plugin\bin\%CONFIG%\net6.0\win-x64\publish build\net.planetrenner.simhub.sdPlugin /e /i
 
 cd build
 ..\..\DistributionTool.exe -b -i net.planetrenner.simhub.sdPlugin -o .