[blockly-docs] fix small doc bugs, add minor changes (#1775)

* [blockly-docs] fix small doc bugs, add minor changes

Signed-off-by: Stefan Höhn <stefan@andreaundstefanhoehn.de>

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

Co-authored-by: Jerome Luckenbach <github@luckenba.ch>

configuration/blockly/index.md

@@ -6,7 +6,7 @@ title: Rules Blockly
 
 # Blockly Reference
 
-One of the core feature that OpenHAB provides is writing rules to allow specific behaviour with the home automation system. The usual way of developing rules is by coding them like described in the [Textual Rules]({{base}}/configuration/rules-dsl.html).
+One of the core feature that OpenHAB provides is writing rules to allow specific behaviour with the home automation system. The usual way of developing rules is by coding them like described in the [Textual Rules](/docs/configuration/rules-dsl.html).
 However, this art of programming may become intimidating early on and shy away away people with few or almost no experience in programming.
 Therefore openHAB also provides a graphical way of writing rules which allows to put together rules in a rather visual way (even though some programming background may still help).
 
@@ -128,7 +128,7 @@ See [Value Storage](rules-blockly-value-storage.html) section.
 
 This section allows calling rules or other scripts, retrieving attributes provided by the rule context or transforming values via different conversion methods (e.g. map, regex, jsonpath)
 
-[![Run & Process](../images/blockly/blockly-value-storage-small.png "Value Storage")
+[![Run & Process](../images/blockly/blockly-run-and-process-small.png "Run & Process")
 ](rules-blockly-run-and-process.html)
 
 See [Run and Process](rules-blockly-run-and-process.html) section.
@@ -137,7 +137,7 @@ See [Run and Process](rules-blockly-run-and-process.html) section.
 
 This section allows calling rules or other scripts, retrieving attributes provided by the rule context or transforming values via different conversion methods (e.g. map, regex, jsonpath)
 
-[![Logging](../images/blockly/blockly-value-storage-small.png "Logging")
+[![Logging](../images/blockly/blockly-logging-overview-small.png "Logging")
 ](rules-blockly-logging.html)
 
 See [Logging](rules-blockly-logging.html) section.

configuration/blockly/rules-blockly-date-handling.md

@@ -67,8 +67,14 @@ The time is set to `00:00:00`.
 
 Type: *ZonedDateTime*
 
-From a String in the format `yyyy-MM-dd`, this block will return the date as *ZonedDateTime*. The input String  may be a variable-block.
-The time will be `00:00:00`.
+This block will return the date as *ZonedDateTime* based on a given String.
+The String may be one of the following formats
+
+- yyyy-MM-dd
+- yyyy-MM-dd HH:mm:ss
+- yyyy-MM-dd HH:mm:ss +HH:mm
+
+The input String  may be a variable-block.
 
 ### Get Date now with offset
 
@@ -78,6 +84,15 @@ Type: *ZonedDateTime*
 
 Returns a date as *ZonedDateTime* with offset relative to the current date *and* time.
 
+The options for the time period base are
+
+- seconds
+- minutes
+- hours
+- days
+- months
+- years
+
 ### Get String representation of date
 
 ![date-tostring](../images/blockly/blockly-get-date-string.png)

configuration/blockly/rules-blockly-ephemeris.md

@@ -22,7 +22,6 @@ See the [Ephemeris configuration page](https://www.openhab.org/docs/configuratio
 - TOC
 {:toc}
 
-{: #blockly-ephemeris-overview}
 
 ## Overview of the Ephemeris blocks
 

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

@@ -7,7 +7,7 @@ title: Rules Blockly - Items & Things
 [return to Blockly Reference](index.html#items-and-things)
 
 *Items* and *Things* are the [major entities of openHAB](https://www.openhab.org/docs/concepts/) to control and monitor the home.
-These can be accessed via the "Items & Things" section of the [Blockly Toolbox]({{base}}/configuration/index.html#blockly-toolbox).
+These can be accessed via the "Items & Things" section of the [Blockly Toolbox](/docs/configuration/index.html#blockly-toolbox).
 
 {::options toc_levels="2..4"/}
 
@@ -28,7 +28,7 @@ Both are possible using the item-block and thing-block
 
 > ![blockly-item-thing](../images/blockly/blockly-item-thing.png)
 
-However, these blocks are not useful by themselves - they are always used together with another block.
+However, **these blocks are not useful by themselves** - they are always used together with another block.
 The example below uses the *get state of item* block to retrieve the *MainSwitch* *item* state, before checking if that is equal to ON within a standard comparison block
 
 ![blockly-item-example](../images/blockly/blockly-item-example.png)
@@ -41,6 +41,8 @@ The example below uses the *get state of item* block to retrieve the *MainSwitch
 
 Function: Retrieves a specific **Item** or **Group** for use in other item related functions.
 
+- **Tip:** never use this block alone as it only returns the items name which alone does not make sense.
+Instead use the get-Item-Block below.
 - Clicking 'MyItem' displays a list of **Items** to pick from
 - Technically this block returns the *name* of the item as a String.
 - As a result, this block can be used wherever the item name is required as a String.
@@ -55,6 +57,11 @@ Function: Gets an **Item** for use in other item related functions
 - Clicking 'MyItem' displays a list of **Items** to pick from.
 - Technically this block returns an item *object*, to be used to retrieve specific attributes using other blocks (see below).
 - As this block does not return a String it cannot be directly attached to a log-block, as demonstrated below.
+  - **Tip:** Often you do want to retrieve the state, hence use the "Get State of Item"-block below
+  - The block returns the item itself.
+If you want to log the items information you can assign it to a variable first and the log the variable.
+
+![logging-getItem](../images/blockly/blockly-getItem-with-var.png)
 
 ![blockly-getItemStateDoesntFit](../images/blockly/blockly-getItemStateDoesntFit.png)
 
@@ -64,7 +71,13 @@ Function: Gets an **Item** for use in other item related functions
 
 Function: Get the current state of an **Item** or **Group**
 
-- Should return the state of an item as a String like ON/OFF, the temperature value etc.
+- Returns the [state](https://www.openhab.org/docs/configuration/items.html#state) of an item like ON/OFF, the temperature value etc.
+
+Note that most of the states can and will be directly **converted automatically to a String** but be careful that some of the **more complex states may instead return a complex object instead**.
+
+**Tip:** it is recommended in this case to assign this to a variable and use the "String-Append-Text" with an empty "" to convert it into a String for further processing.
+
+See the [Item-State documentation](https://www.openhab.org/docs/configuration/items.html#state) for more information
 
 Note: currently a String is not always returned.
 [See this thread](https://community.openhab.org/t/blockly-cannot-split-text-string-from-string-item/130819) for reference and potential workaround.
@@ -138,7 +151,7 @@ Function: Sends a command or posts an update to an **Item** or **Group**.
 - value: any state value that is allowed for that item, eg. ON or OFF for a switch.
 - Clicking 'MyItem' displays a list of **Items** to pick one item from
 
-For the difference between *send command* and *post update* two check ["Manipulating States"](https://www.openhab.org/docs/configuration/rules-dsl.html#manipulating-item-states).
+For the difference between *send command* and *post update* see ["Manipulating States"](https://www.openhab.org/docs/configuration/rules-dsl.html#manipulating-item-states) and ["Event Bus Actions"](https://www.openhab.org/docs/configuration/actions.html#event-bus-actions).
 
 **Item-block examples**
 
@@ -167,7 +180,7 @@ Function: Retrieves a specific **Thing** for use in other thing related function
 
 - Clicking 'MyThing' displays a list of **Things** to pick from
 - Technically this block returns the thingUid of the thing as a String
-- Learn more about things [here](https://www.openhab.org/docs/configuration/things.html)
+- Learn more about [things](https://www.openhab.org/docs/configuration/things.html) or [thing-concepts](https://www.openhab.org/docs/concepts/things.html)
 
 **Example**
 

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

@@ -41,6 +41,8 @@ A Script *is* a Rule too. It’s just a special type of rule that only has a sin
 
 - No parameters can be provided
 
+See [openHAB Call-Script](https://www.openhab.org/docs/configuration/actions.html#openhab-subsystem-actions) for background information
+
 ### Run Rule or Script created in UI
 
 ![run-rule-or-script](../images/blockly/blockly-run-rule.png)
@@ -83,7 +85,7 @@ This retrieves the value for the key "myKey1" that was passed by the calling rul
 A rule carries contextual information when triggered - this block can retrieve that information.
 
 - The rule trigger type defines which of the attributes are available to the rule - they will not all be available.
-- For more detailed information see [Event Object Attributes](https://openhab-scripters.github.io/openhab-helper-libraries/Guides/Event%20Object%20Attributes.html)
+- For more detailed information see [Event Object Attributes](https://openhab-scripters.github.io/openhab-helper-libraries/Guides/Event%20Object%20Attributes.html) or [openHAB Events](https://www.openhab.org/docs/developer/utils/events.html).
 
 ## Transform values via Map, Regex or JsonPath and others
 

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

@@ -8,7 +8,9 @@ title: Rules Blockly - Timers & 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. This chapter explains what these blocks do, sometimes displaying generated code to explain what is happening behind the scenes.
+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.
+This chapter explains what these blocks do, sometimes displaying generated code to explain what is happening behind the scenes.
 
 - TOC
 {:toc}
@@ -191,82 +193,6 @@ The rule is triggered when the burglar-alarm-item or the reset-button-item is ch
 
 ![timer-comprehensive](../images/blockly/blockly-timer-comprehensive.png)
 
----
-
-## Date handling blocks
-
-Date blocks are used as input parameters for other blocks.
-At the moment some of these blocks are found in the ephemeris section, whilst others are found in the persistence section - they may be equally useful for both.
-These blocks are *typed* to assure correct connection to other blocks.
-
-### today
-
-![today](../images/blockly/blockly-date-today.png)
-
-Type: *DayOffset*
-
-Ephemeris blocks expect a date formatted as the number of days since today.
-As a result, this block returns 0.
-
-### today +/- x days
-
-![now-plus-minus-offset](../images/blockly/blockly-date-plus.png)
-
-Type: *DayOffset*
-
-Returns the number of days since today, as configured in the number block.
-The number can be positive (offset into the future) or negative (offset into the past).
-
-### date-picker
-
-![date-picker](../images/blockly/blockly-date-picker.png)
-
-Type: *ZonedDateTime*
-
-Returns a date as *ZonedDateTime*.
-The date can be selected from a date picker.
-The time is set to `00:00:00`.
-
-### Get date
-
-![get-date](../images/blockly/blockly-date-get.png)
-
-Type: *ZonedDateTime*
-
-From a String in the format `yyyy-MM-dd`, this block will return the date as *ZonedDateTime*.
-The input String  may be a variable-block.
-The time will be `00:00:00`.
-
-### Get Date now with offset
-
-![now-with-offset](../images/blockly/blockly-get-now-offset.png)
-
-Type: *ZonedDateTime*
-
-Returns a date as *ZonedDateTime* with offset relative to the current date *and* time.
-
-### Get String representation of date
-
-![date-tostring](../images/blockly/blockly-get-date-string.png)
-
-Type: *String*
-
-Returns the the String representation of a given *ZonedDateTime*-block, with or without the time.
-
-### Example
-
-Assuming this block is run at `20:47:36` on `31/01/2022`
-
-![date-text-example](../images/blockly/blockly-date-text-example.png)
-
-The output in the log will be.
-
-```text
-2022-01-31
-2022-01-31 00:00:00
-2022-01-31 20:47:36
-```
-
 ## Return to Blockly Reference
 
 [return to Blockly Reference](index.html#timers-and-delays)

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

@@ -54,7 +54,7 @@ Even though (2) is not trivial but after having done that the usage of the funct
 
 ### Play Audio with Volume
 
-![img.png](../images/blockly/blockly-play-audio-with-volume.png)
+![play-audio](../images/blockly/blockly-play-audio-with-volume.png)
 
 *Function:* Plays an audio file on an audio sink and setting the volume at the same time