Blockly: restructure and grammatical improvements

Signed-off-by: Jimmy Tanagra <[email protected]>

configuration/blockly/rules-blockly-ephemeris.md

@@ -6,7 +6,7 @@ title: Rules Blockly - Ephemeris
 
 # Ephemeris
 
-[return to Blockly Reference](index.html#ephemeris)
+[Return to Blockly Reference](index.html#ephemeris)
 
 ## Introduction
 
@@ -61,4 +61,4 @@ Additional holidays must be configured in _ephemeris.cfg_.
 
 ## Return to Blockly Reference
 
-[return to Blockly Reference](index.html#ephemeris)
+[Return to Blockly Reference](index.html#ephemeris)

configuration/blockly/rules-blockly-before-using.md → configuration/blockly/rules-blockly-getting-started.md

@@ -1,12 +1,12 @@
 ---
 layout: documentation
-title: Rules Blockly - Before Using
+title: Rules Blockly - Getting Started
 ---
 <!-- markdownlint-disable MD036 -->
 
-# Before using blockly in openHAB
+# Getting Started with Blockly in openHAB
 
-[return to Blockly Reference](index.html#before-using-blockly)
+[Return to Blockly Reference](index.html#getting-started)
 
 ## Preface
 
@@ -17,34 +17,31 @@ Please read them carefully before asking questions in the forum.
 
 [[toc]]
 
-## **openHAB Configuration Files**
+## openHAB Configuration Files
 
 Some openHAB blocks rely on particular configuration files found in the openHAB configuration folder.
-This folder is referred to as $OPENHAB\_CONF in this page, and the location of this folder for your setup can be found via the UI: _Help & About_ -> _Technical Information_ -> _Configuration folder_.
+This folder is referred to as `$OPENHAB_CONF` throughout this documentation.
+The location of this folder can be found via the UI when logged in as an admin: _Help & About_ -> _Technical Information_ -> _Configuration folder_.
 
-- via mounting the files shares from the server to your client-PC.
-In the main UI as an admin you can go to _Help & About_ and will have the different folder locations under _Technical information_.
-  - the exact configuration of the shares can be found on your server at [/etc/samba/smb.conf](https://github.com/openhab/openhabian/blob/main/includes/smb.conf).
-- Use the share _openHAB_-conf when mounting it from Windows or macOS
+When using openHABian, a [samba share](https://github.com/openhab/openhabian/blob/main/includes/smb.conf) called `openHAB-conf` is created for the configuration folder.
+This share can be mounted on your computer for easy access.
 
-**Link the openHAB share in Windows**
+### Mounting the openHAB-conf share in Windows
 
-- Find you openHAB-Server via the network share functionality
-- User the share _openHAB_-conf to assign it to a network drive
+- Find your openHAB-Server via the network share functionality
+- Find the `openHAB-conf` folder and assign it to a network drive
 
-**Link the openHAB share in macOS**
+### Mounting the openHAB share in macOS
 
 - Finder -> Go -> Connect to Server
-  - Enter the username and server name to connect to the openHAB Server
-
+- Enter the username and server name to connect to the openHAB Server
   ![macos-share-1](../images/blockly/blockly-openhab-macos-share-1.png)
-  - then choose the folder you want to mount
-
+- Then choose the folder you want to mount
   ![macos-share-2](../images/blockly/blockly-openhab-macos-share-2.png)
 
-**Finding it on Linux**
+### Finding it on Linux
 
-- Access the folder directly on the openHAB server at _/etc/openhab_
+- Access the folder directly on the openHAB server at `/etc/openhab`
 
 All methods reveal the following folders
 
@@ -61,29 +58,39 @@ All methods reveal the following folders
 - things
 - transform
 
-## Creating a blockly rule via the UI
-
-Also view ![youtube](../images/blockly/youtube-logo-small.png) [Creating a Blockly Rule](https://youtu.be/EdllUlJ7p6k?t=429)
-
-- go to Settings -> Rules
-- press ![plus](../images/blockly/blockly-plus-small.png) on bottom right
-- enter a unique id and rule name for your new blockly rule
-- Under "When" click on "Add Trigger" to define a trigger for the rule (you may add multiple triggers which are perceived as any of those triggers may occurs which stands for an OR combination of the triggers)
-  - choose a title for the rule
-  - choose "item" (or something else) that should trigger the rule
-  - select the item from your model and the click PICK on the upper right corner
-  - choose "received a command", "was updated" or "changed"
-- Under "Then" click on "Add Action"
-- choose ![run-script-1](../images/blockly/blockly-run-script.png)
-- click on ![run-script-2](../images/blockly/blockly-run-script-2.png) und you should now see this screen
-  ![blockly-edit-screen](../images/blockly/blockly-edit-screen.png)
-- you can now click the ![toolbox-submenu](../images/blockly/blockly-arrow.png) to access all openHAB Blocks.
+## Creating a Blockly
+
+Video tutorial ![youtube](../images/blockly/youtube-logo-small.png) [Creating a Blockly Rule](https://youtu.be/EdllUlJ7p6k?t=429)
+
+Steps:
+
+- Go to `Settings` -> `Rules`
+- Press ![plus](../images/blockly/blockly-plus-small.png) on bottom right
+- Enter a unique id and rule name for your new Blockly rule
+- Under `When`, click `Add Trigger` to define a trigger for the rule.
+  - Choose `Item Event` (or something else) that should trigger the rule.
+  - Select the item from your model and the click `Pick` on the upper right corner.
+  - (Optional) Enter a title for the trigger. A suitable default title will used when none was provided.
+  - Choose "received a command", "was updated" or "changed" accordingly.
+- Under `Then`, click `Add Action`
+  - Click ![Inline Script](../images/blockly/blockly-run-script.png)
+  - Click ![Design with Blockly](../images/blockly/blockly-design-with-blockly.png)
+  - You should now see this screen:
+    ![blockly-edit-screen](../images/blockly/blockly-edit-screen.png)
 - Drag and Drop the blocks to the white area
-- Press `Ctrl-s` (Windows) or `Command-s` (macOS) to save your rule
-- Press `Ctrl-r` (Windows) or `Command-r` (macOS) to directly run your rule with the trigger
-- Press `Ctrl-d` (Windows) or `Command-d` (macOS) to disable / enable your rule.
-See the following video on ![youtube](../images/blockly/youtube-logo-small.png) [How to disable Rules](https://youtu.be/hSRfooBKn9A?t=1668)
-- **Click on** ![showblock](../images/blockly/blockly-workspace-showblocks.png) **on the lower right of the bottom toolbar to see the generated code** and will transition to ![showcode](../images/blockly/blockly-workspace-showcode.png)(click again to come back to the blocks).
+- Press <kbd>Ctrl</kbd>+<kbd>S</kbd> (Windows) or <kbd>Command</kbd>+<kbd>S</kbd> (macOS) to save your rule
+- Press <kbd>Ctrl</kbd>+<kbd>R</kbd> (Windows) or <kbd>Command</kbd>+<kbd>R</kbd> (macOS) to directly run your rule with the trigger
+- Press <kbd>Ctrl</kbd>+<kbd>D</kbd> (Windows) or <kbd>Command</kbd>+<kbd>D</kbd> (macOS) to disable / enable your rule.
+  See the following video on ![youtube](../images/blockly/youtube-logo-small.png) [How to disable Rules](https://youtu.be/hSRfooBKn9A?t=1668)
+- **Click on** ![showblock](../images/blockly/blockly-workspace-showblocks.png) **on the lower right of the bottom toolbar to see the generated code** and it will transition to ![showcode](../images/blockly/blockly-workspace-showcode.png)(click again to come back to the blocks).
+
+::: Note
+
+Multiple triggers may be added to the rule.
+The rule will be executed once for each trigger that occurred.
+This means that if multiple trigger occurred, the rule will be executed multiple times.
+
+:::
 
 More about the topic of code generation can be viewed at ![youtube](../images/blockly/youtube-logo-small.png) [Blockly as an ECMA-Script code generator](https://youtu.be/EdllUlJ7p6k?t=1739)
 
@@ -108,6 +115,21 @@ A context menu is available when right-clicking on a block.
 Right-clicking on an empty area in the workspace will pop up a slightly different context menu.
 In particular, `Clean up Blocks` will automatically move and arrange your blocks neatly.
 
+### Getting Help
+
+Each block offers a **Help** link in its [context menu](#context-menu).
+It will open a page that provides further information about the function of that particular block.
+
+![context-help](../images/blockly/blockly-context-help.png)
+
+There is also a help button available in each section of the toolbox that links to the documentation of the whole section.
+
+![main-help-button](../images/blockly/blockly-main-help.png)
+
+_When asking for help in the community forums, please include the respective code that is being generated._
+
+See also: ![youtube](../images/blockly/youtube-logo-small.png) [Various Help Documentation available in openHAB Blocky](https://youtu.be/EdllUlJ7p6k?t=1589)
+
 ### Selecting Blocks
 
 Click on a block to select it.
@@ -150,28 +172,28 @@ You can also copy a set of blocks into your clipboard, and paste them into anoth
 
 ### Searching the workspace
 
-Sometimes blockly rules become pretty big, and it is hard to find particular blocks in the rule.
+Sometimes Blockly rules become pretty big, and it is hard to find particular blocks in the rule.
 Therefore, a search functionality has been provided by pressing Cmd/Ctrl-F which opens a small search window in the top right (just below the "save"-label).
 After pressing _Enter_ all found blocks that contain the search term are marked in black.
 
 ![blockly-search](../images/blockly/blockly-search.png)
 
 ## Use Frontail for viewing log files
 
-During development the log-block is lot very often which writes information into the log files.
+The log block can be used to write information into the log file during development.
 
-- To be able to conveniently view your log files it is recommended to setup _frontail_ which can be achieved easily via [openhabian-config](https://www.openhab.org/docs/installation/openhabian.html#optional-components)
+- To view the log file, it is recommended to setup _frontail_ which can be installed easily with [openhabian-config](https://www.openhab.org/docs/installation/openhabian.html#optional-components)
 - Start `openhabian-config` on your server and choose option 20 and then option 21
 - After installation you can view your logs under [openhabian-config](http://myopenhab-server:9001) (adapt the server name)
-- **see [how to log](https://www.openhab.org/docs/administration/logging.html)**
+- See [Logging in openHAB](https://www.openhab.org/docs/administration/logging.html) for more details.
 
 More on that topic can be viewed at ![youtube](../images/blockly/youtube-logo-small.png) [Logging](https://youtu.be/EdllUlJ7p6k?t=670)
 
-## Show an item status watch list besides the blockly rules
+## Show an item status watch list besides the Blockly rules
 
-In the developer section there is the possibility to add a sidebar to the blockly rules development workspace that allows to watch live status of an item.
-View the chapter ![youtube](../images/blockly/youtube-logo-small.png) [Debugging Rules with openHAB Developer Tools to watch Item-Status](https://youtu.be/EdllUlJ7p6k?t=325) for more information
+In the developer section there is the possibility to add a sidebar to the Blockly rules development workspace that allows to watch live status of an item.
+View the chapter ![youtube](../images/blockly/youtube-logo-small.png) [Debugging Rules with openHAB Developer Tools to watch Item-Status](https://youtu.be/EdllUlJ7p6k?t=325) for more information.
 
 ## Return to Blockly Reference
 
-[return to Blockly Reference](index.html#before-using-blockly)
+[Return to Blockly Reference](index.html#before-using-blockly)

configuration/blockly/rules-blockly-items-things.md

@@ -6,7 +6,7 @@ title: Rules Blockly - Items & Things
 
 # Item & Things
 
-[return to Blockly Reference](index.html#items-and-things)
+[Return to Blockly Reference](index.html#items-and-things)
 
 ## Introduction
 
@@ -305,4 +305,4 @@ Function: Gets a **Thing Status** for use in other Thing related functions
 
 ## Return to Blockly Reference
 
-[return to Blockly Reference](index.html#items-and-things)
+[Return to Blockly Reference](index.html#items-and-things)

configuration/blockly/rules-blockly-logging.md

@@ -6,7 +6,7 @@ title: Rules Blockly - Logging
 
 # Logging
 
-[return to Blockly Reference](index.html#logging)
+[Return to Blockly Reference](index.html#logging)
 
 ## Introduction
 
@@ -46,4 +46,4 @@ _Function:_ creates a print statement with the given text in the rule that logs
 
 ## Return to Blockly Reference
 
-[return to Blockly Reference](index.html#logging)
+[Return to Blockly Reference](index.html#logging)

configuration/blockly/rules-blockly-notifications.md

@@ -6,7 +6,7 @@ title: Rules Blockly - Notifications
 
 # Notifications
 
-[return to Blockly Reference](index.html#notifications)
+[Return to Blockly Reference](index.html#notifications)
 
 ## Introduction
 
@@ -61,4 +61,4 @@ _Function:_ Sends a notification to myopenhab.org only
 
 ## Return to Blockly Reference
 
-[return to Blockly Reference](index.html#notifications)
+[Return to Blockly Reference](index.html#notifications)

configuration/blockly/rules-blockly-persistence.md

@@ -6,7 +6,7 @@ title: Rules Blockly - Persistence
 
 # Persistence
 
-[return to Blockly Reference](index.html#persistence)
+[Return to Blockly Reference](index.html#persistence)
 
 ## Introduction
 
@@ -86,4 +86,4 @@ Type: ZonedDateTime
 
 ## Return to Blockly Reference
 
-[return to Blockly Reference](index.html#persistence)
+[Return to Blockly Reference](index.html#persistence)

configuration/blockly/rules-blockly-run-and-process.md

@@ -6,7 +6,7 @@ title: Rules Blockly - Run & Process and Transformations
 
 # Run & Process (Rules and Scripts)
 
-[return to Blockly Reference](index.html#run-process-rules-and-scripts)
+[Return to Blockly Reference](index.html#run-process-rules-and-scripts)
 
 ## Introduction
 
@@ -189,4 +189,4 @@ See also the short video part about ![youtube](../images/blockly/youtube-logo-sm
 
 ## Return to Blockly Reference
 
-[return to Blockly Reference](index.html#run-process-rules-and-scripts)
+[Return to Blockly Reference](index.html#run-process-rules-and-scripts)

configuration/blockly/rules-blockly-standard-ext.md

@@ -6,7 +6,7 @@ title: Rules Blockly - openHAB Extensions to the Standard
 
 # openHAB Extensions to the Standard
 
-[return to Blockly Reference](index.html#openhab-extensions-to-the-standard)
+[Return to Blockly Reference](index.html#openhab-extensions-to-the-standard)
 
 ## Introduction
 
@@ -243,9 +243,9 @@ Therefore there is a good introduction to loops available which can be viewed at
 
 ## Functions
 
-A more advanced feature for reusable blockly code is _functions_.
+A more advanced feature for reusable Blockly code is _functions_.
 More about that topic can be viewed at ![youtube](../images/blockly/youtube-logo-small.png) [Functions](https://youtu.be/hSRfooBKn9A?t=60) and [Parameters](https://youtu.be/hSRfooBKn9A?t=170).
 
 ## Return to Blockly Reference
 
-[return to Blockly Reference](index.html#openhab-extensions-to-the-standard)
+[Return to Blockly Reference](index.html#openhab-extensions-to-the-standard)

configuration/blockly/rules-blockly-timers-and-delays.md

@@ -6,7 +6,7 @@ title: Rules Blockly - Timers & Delays
 
 # Timers & Delays
 
-[return to Blockly Reference](index.html#timers-and-delays)
+[Return to Blockly Reference](index.html#timers-and-delays)
 
 Timers and Delays are a little more complex but add important functionality to rules.
 Whilst the "Wait-For"-block is straightforward, the timer blocks should be well understood before being used - they may behave differently than expected.
@@ -216,4 +216,4 @@ The rule is triggered when the burglar-alarm-item or the reset-button-item is ch
 
 ## Return to Blockly Reference
 
-[return to Blockly Reference](index.html#timers-and-delays)
+[Return to Blockly Reference](index.html#timers-and-delays)

configuration/blockly/rules-blockly-uom.md

@@ -6,12 +6,12 @@ title: Rules Blockly - Units of Measurements
 
 # Units of Measurements
 
-[return to Blockly Reference](index.html#items-and-things)
+[Return to Blockly Reference](index.html#items-and-things)
 
 ## Introduction
 
 [Unit of Measurements](docs/concepts/units-of-measurement.html) have been a part of openHAB for a long time already and received some major improvements in particular in openHAB 4.0.
-Therefore, to make the usage in blockly easier and allow math computations with measurement units, severals blocks have been added.
+Therefore, to make the usage in Blockly easier and allow math computations with measurement units, severals blocks have been added.
 
 Note that these blocks are only available since openHAB 4.0 and are based on JS Scripting / graalJS.
 
@@ -108,4 +108,4 @@ The following examples show how to use it with an Item:
 
 ## Return to Blockly Reference
 
-[return to Blockly Reference](index.html#items-and-things)
+[Return to Blockly Reference](index.html#items-and-things)

configuration/blockly/rules-blockly-value-storage.md

@@ -6,7 +6,7 @@ title: Rules Blockly - Value Storage
 
 # Value Storage
 
-[return to Blockly Reference](index.html#value-storage)
+[Return to Blockly Reference](index.html#value-storage)
 
 ## Introduction
 
@@ -78,4 +78,4 @@ Function: Checks if a value is undefined in the specified [cache](#caching)
 
 ## Return to Blockly Reference
 
-[return to Blockly Reference](index.html#value-storage)
+[Return to Blockly Reference](index.html#value-storage)

configuration/blockly/rules-blockly-voice-and-multimedia.md

@@ -6,7 +6,7 @@ title: Rules Blockly - Voice and Multimedia
 
 # Multimedia
 
-[return to Blockly Reference](index.html#voice-and-multimedia)
+[Return to Blockly Reference](index.html#voice-and-multimedia)
 
 ## Introduction
 
@@ -16,7 +16,7 @@ In general, this section deals with two topics
 1) Saying a text via using any Text-to-Speech API (e.g. Google's API)
 
 It should be noted that both functionalities do not just work right out of the box because e.g for (1) the audio sinks need to be installed in openHAB and for (2) e.g. the whole Google API needs to be configured in particular with your own personal Google account.
-Even though (2) is not trivial but after having done that the usage of the functionality with blockly is very easy and worth the effort.
+Even though (2) is not trivial but after having done that the usage of the functionality with Blockly is very easy and worth the effort.
 
 More about that topic can be viewed at ![youtube](../images/blockly/youtube-logo-small.png) [Playing sounds on audio sinks](https://youtu.be/EdllUlJ7p6k?t=2035)
 
@@ -47,7 +47,7 @@ More about that topic can be viewed at ![youtube](../images/blockly/youtube-logo
 _Function:_ Plays an audio file on an audio sink
 
 - the audio file must reside in the sounds-folder of openHAB that can be found [here](https://community.openhab.org/t/blockly-reference/128785#openhab-configuration-files-7)
-- all available audio sinks are automatically provided by openHABs blocklies
+- all available audio sinks are automatically provided by openHABs Blockly
 
 Also view ![youtube](../images/blockly/youtube-logo-small.png)[Playing sounds on audio sinks](https://youtu.be/EdllUlJ7p6k?t=2035)
 
@@ -60,7 +60,7 @@ _Function:_ Plays an audio file on an audio sink and setting the volume at the s
 same as above but also allowing to provide the volume at the same time
 
 - the audio file must reside in the sounds-folder of openHAB that can be found [here](https://community.openhab.org/t/blockly-reference/128785#openhab-configuration-files-7)
-- all available audio sinks are automatically provided by openHABs blocklies
+- all available audio sinks are automatically provided by openHABs Blockly
 
 **Known issue workaround:**
 In several cases (like the Google Minis) it is known that setting the volume together with playing the sound results into only setting the volume either during playing the sound or even after the sound has played.
@@ -78,7 +78,7 @@ In case this happens the more robust approach is as follows
 _Function:_ Starts a stream playing on an audio sink
 
 - The audio streams must be reachable from the openHAB server and can therefore be either internally or externally hosted
-- All available audio sinks are automatically provided by openHAB's blocklies
+- All available audio sinks are automatically provided by openHAB's Blockly
 - Changing the volume needs to be done via the thing volume channel linked to the sink device by sending the respective volume level command to that item
 
 More about that topic can be viewed at ![youtube](../images/blockly/youtube-logo-small.png) [Play Stream](https://youtu.be/hSRfooBKn9A?t=335)
@@ -97,4 +97,4 @@ _Function:_ Sends the given text to the sink by using the default Text-to-Speech
 
 More about that topic can be viewed at ![youtube](../images/blockly/youtube-logo-small.png)[Using Text-to-speach easily with blocks](https://youtu.be/EdllUlJ7p6k?t=2403)
 
-[return to Blockly Reference](index.html#voice-and-multimedia)
+[Return to Blockly Reference](index.html#voice-and-multimedia)