Markdown linting bulk fix (#1432)

* Improved markdown linter settings Signed-off-by: Jerome Luckenbach <github@luckenba.ch> * Bulk fix for several markdown errors. Signed-off-by: Jerome Luckenbach <github@luckenba.ch> * Remove Paper UI from Json DB. Signed-off-by: Jerome Luckenbach <github@luckenba.ch>
openhab · Jan 10, 2021 · e879ad8 · e879ad8
1 parent 01081c6
commit e879ad8
Show file tree

Hide file tree

Showing 14 changed files with 193 additions and 162 deletions.
diff --git a/.github/markdownStyle.rb b/.github/markdownStyle.rb
@@ -14,3 +14,6 @@
 
 # Allow inline HTML
 exclude_rule 'MD033'
+
+# Allow Frontmatter and exclude top level header on first line rule
+exclude_rule 'MD041'
diff --git a/.markdownlint.json b/.markdownlint.json
@@ -1,8 +1,7 @@
 {
     "default": true,
-    "MD004": {
-        "style": "dash"
-    },
+    "MD004": { "style": "dash" },
     "MD013": false,
-    "MD025": false
+    "MD025": false,
+    "MD029": { "style": "one" }
 }
diff --git a/administration/jsondb.md b/administration/jsondb.md
@@ -46,7 +46,7 @@ openHAB stores configuration information in JSON (JavaScript Object Notation) fo
 
 ## Storage Scope
 
-All configuration information regarding _**Items, Links, and Things**_ are defined via the User Interfaces (Paper UI, HABmin, REST) or via internal openHAB services.
+All configuration information regarding _**Items, Links, and Things**_ are defined via the User Interfaces (UI, REST) or via internal openHAB services.
 
 ::: tip Note
 The JSON DB does NOT store information for manually configured _**Items, Links, or Things**_, since these are already stored in files within the `OPENHAB_CONF` sub-directories (e.g. `/etc/openhab/items/`).
@@ -55,6 +55,7 @@ The JSON DB does NOT store information for manually configured _**Items, Links,
 ## Storage Purpose
 
 JSON DB Storage can be used for:
+
 - Backup: Maintains a copy of your configurations in the `OPENHAB_USERDATA/jsondb/backup` directory
 - Troubleshooting: Allows the user to interact with the configurations that were automatically generated via the UIs
 - Advanced administration: Gives the possibility to manually define configuration parameters within the `*.json` files
@@ -65,11 +66,11 @@ openHAB writes the `*.json` files every time a change is made via the User Inter
 openHAB _**reads the `*.json` files only once at startup**_.  So, if you edit them manually, you should restart openHAB.
 
 The system employs two write mechanisms to improve performance where there are multiple writes in a short time. When the service is closed, all open services are written to disk.
-The parameters for the two mechanisms may be modified in Paper UI :arrow_right: Configuration :arrow_right: System :arrow_right: Json Storage
+The parameters for the two mechanisms may be modified in UI :arrow_right: Settings :arrow_right: Json Storage
 
 1. _Write delay_ (defaults to 500 ms): Sets the time to wait before writing changes to disk.
 This can reduce the number of writes when many changes are being introduced within a short period, and
-2. _Maximum write delay_ (defaults to 30000 ms): Sets the maximum period the service will wait to write data in cases where changes are happening continually.
+1. _Maximum write delay_ (defaults to 30000 ms): Sets the maximum period the service will wait to write data in cases where changes are happening continually.
 
 The service keeps up to five backups of each table.
 The outdated file is copied to the backup folder and then that file is overwritten with the new content.
@@ -78,6 +79,7 @@ The outdated file is copied to the backup folder and then that file is overwritt
 
 The JsonDB Storage resides in the `OPENHAB_USERDATA/jsondb/` directory.
 The full directory path depends on the installation method:
+
 - Linux Repository Installation: `/var/lib/openhab/jsondb/`
 - Linux Manual Installation: `/opt/openhab/userdata/jsondb/`
 - Windows (Manual) Installation: `C:\openHAB\userdata\jsondb\`
@@ -86,13 +88,12 @@ Within the `OPENHAB_USERDATA/jsondb/` directory, you will find the following fil
 
 | Filename                                                        | _Contents_                            |
 |-----------------------------------------------------------------|---------------------------------------|
-| org.openhab.config.discovery.**DiscoveryResult.json** | _Results of Paper UI Discovery_       |
+| org.openhab.config.discovery.**DiscoveryResult.json** | _Results of UI Discovery_       |
 | org.openhab.core.items.**Item.json**                  | _Items configurations_                |
 | org.openhab.core.thing.link.**ItemChannelLink.json**  | _Item to Channel Link configurations_ |
 | org.openhab.core.thing.link.**ItemThingLink.json**    | _Item to Thing Link configurations_   |
 | org.openhab.core.thing.**Thing.json**                 | _Things configurations_               |
 
-
 ## Example Use
 
 In this example, we will use the Network Binding (2.0) to Search for Things, add a new Thing to openHAB and then modify its parameters to check the information that is stored in the JsonDB.
@@ -103,7 +104,7 @@ Step 1. Add new Thing (name: `ISP_Gateway`) from UI:
 
 Step 2. Check the contents of the `OPENHAB_USERDATA/jsondb/org.openhab.core.thing.Thing.json` file:
 
-```
+```json
 root@rpi3:~# more /var/lib/openhab/jsondb/org.openhab.core.thing.Thing.json
 {
   "network:device:172_16_13_254": {
@@ -188,7 +189,8 @@ root@rpi3:~# more /var/lib/openhab/jsondb/org.openhab.core.thing.Thing.json
 }
 ```
 
-Step 3. Using Paper UI :arrow_right: Configuration :arrow_right: Things, edit the new `ISP_Gateway` Thing and modify the following parameters:
+Step 3. Using UI :arrow_right: Settings :arrow_right: Things, edit the new `ISP_Gateway` Thing and modify the following parameters:
+
 - Location (from unset to `MyHome`)
 - Retry (from 1 to 3)
 - Timeout (from 5000 to 10000)

diff --git a/administration/logging.md b/administration/logging.md
@@ -13,7 +13,7 @@ This includes how to access logging information and configure logging for user-d
 There are two ways to check log entries:
 
 1. Through files stored on the **file system**
-2. During runtime in the **Karaf Console**
+1. During runtime in the **Karaf Console**
 
 ## Filesystem
 
@@ -41,7 +41,7 @@ The log shell provides the following commands:
 
 For example, the following command enables real-time monitoring of the default log:
 
-```
+```shell
 openhab> log:tail
 20:38:00.031 [DEBUG] [sistence.rrd4j.internal.RRD4jService] - Stored 'Temperature_FF_Child' with state '19.1' in rrd4j database
 20:38:00.032 [DEBUG] [sistence.rrd4j.internal.RRD4jService] - Stored 'Temperature_FF_Bed' with state '19.5' in rrd4j database
@@ -51,7 +51,7 @@ openhab> log:tail
 
 A useful feature is that filters can be applied:
 
-```
+```shell
 openhab> log:tail org.openhab.io.rest.core.item.ItemResource
 20:36:52.879 [DEBUG] [thome.io.rest.core.item.ItemResource] - Received HTTP POST request at 'items/Light_FF_Bath_Ceiling' with value 'ON'.
 20:36:53.545 [DEBUG] [thome.io.rest.core.item.ItemResource] - Received HTTP POST request at 'items/Light_FF_Bath_Ceiling' with value 'OFF'.
@@ -98,10 +98,13 @@ The levels build a hierarchy with **ERROR** logging critical messages only and *
 Setting the log level to **DEFAULT** will log to the level defined in the package.subpackage (in most cases a binding).
 
 If the name of `package.subpackage` is not known, the name can be found out in the console:
+
 ```text
 list -s
 ```
+
 returns a list of all modules and the last column contains the information about the symbolic name of the bundle:
+
 ```text
 openhab> list -s
 START LEVEL 100 , List Threshold: 50
@@ -115,16 +118,18 @@ START LEVEL 100 , List Threshold: 50
  24 │ Active │  80 │ 3.0.0.v201312141243     │ com.google.inject
 
 ```
+
 The list can be also filtered with grep. To find out the Z-Wave binding the following command can be used
-```Text
+
+```shell
 openhab> list -s | grep zwave
 253 x Active x  80 x 2.5.5                   x org.openhab.binding.zwave
 
 ```
 
 The following example sets the logging for the Z-Wave binding to **DEBUG**
 
-```text
+```shell
 log:set DEBUG org.openhab.binding.zwave
 ```
 
@@ -153,13 +158,14 @@ For example you can use `log:set info org.openhab.core.model.script` and `log:se
 
 An example output of the last log statement above is:
 
-```
+```shell
 2016-06-04 16:28:39.482 [DEBUG] [org.openhab.core.model.script.heating] Bedroom: Temperature 21.3°C, Mode NORMAL
 ```
 
 Note that, in the last example above, inclusion and formatting of values is done using [Java Formatter String Syntax](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Formatter.html).
 
 ## Log4j configuration and logging into separate files
+
 By default, all log entries are saved in the file `openhab.log` and event-specific entries are saved in `events.log`.
 Additional log files can be defined in order to write specifics logs to a separate place.
 

diff --git a/concepts/items.md b/concepts/items.md
@@ -11,7 +11,7 @@ openHAB has a strict separation between the physical world (the "Things", see be
 
 Items represent functionality that is used by the application (mainly user interfaces or automation logic).
 Items have a state and are used through events.
-  
+
 The following Item types are currently available (alphabetical order):
 
 | Item Name          | Description                                                        | Command Types                              |
@@ -38,11 +38,12 @@ Cyclic membership is not forbidden but strongly not recommended.
 User interfaces might display Group Items as single entries and provide navigation to its members.
 
 Example for a Group Item as a simple collection of other Items:
-```
+
+```shell
     Group groundFloor
     Switch kitchenLight (groundFloor)
     Switch livingroomLight (groundFloor)
-``` 
+```
 
 ### Derive Group State from Member Items
 
@@ -64,10 +65,10 @@ For available Group functions and examples see [Configuration Guide](../configur
 `DateTimeType` objects are parsed using Java's `SimpleDateFormat.parse()` using the first matching pattern:
 
 1. `yyyy-MM-dd'T'HH:mm:ss.SSSZ`
-2. `yyyy-MM-dd'T'HH:mm:ss.SSSz`
-3. `yyyy-MM-dd'T'HH:mm:ss.SSSX`
-4. `yyyy-MM-dd'T'HH:mm:ssz`
-5. `yyyy-MM-dd'T'HH:mm:ss`
+1. `yyyy-MM-dd'T'HH:mm:ss.SSSz`
+1. `yyyy-MM-dd'T'HH:mm:ss.SSSX`
+1. `yyyy-MM-dd'T'HH:mm:ssz`
+1. `yyyy-MM-dd'T'HH:mm:ss`
 
 | Literal | Standard           | Example                               |
 |---------|--------------------|---------------------------------------|
@@ -124,25 +125,26 @@ Here is a short table demonstrating conversions for the examples above:
 
 ## Item Metadata
 
-Sometimes additional information is required to be attached to Items for certain use-cases. 
+Sometimes additional information is required to be attached to Items for certain use-cases.
 This could be an application which needs some hints in order to render the Items in a generic way, or an integration with voice controlled assistants, or any other services which access the Items and need to understand their "meaning".
 
-Such metadata can be attached to Items using disjunct namespaces so they won't conflict with each other. 
-Each metadata entry has a main value and optionally additional key/value pairs. 
-There can be metadata attached to an Item for as many namespaces as desired, like in the following example: 
+Such metadata can be attached to Items using disjunct namespaces so they won't conflict with each other.
+Each metadata entry has a main value and optionally additional key/value pairs.
+There can be metadata attached to an Item for as many namespaces as desired, like in the following example:
 
-    Switch MyFan "My Fan" { homekit="Fan.v2", alexa="Fan" [ type="oscillating", speedSteps=3 ] }
+Switch MyFan "My Fan" { homekit="Fan.v2", alexa="Fan" [ type="oscillating", speedSteps=3 ] }
 
 The metdata can be included with the channel linking, an Alexa metadata mapping is added after the channel linking separated with a comma in the example for a ZWave switch below.
-```
+
+```shell
 Switch LightSwitch "Light Switch" {channel="zwave:device:22c99d1e:node3:switch_binary", alexa="PowerController.powerState"}
-``` 
+```
 
 The metadata can be maintained via a dedicated REST endpoint and is included in the `EnrichedItemDTO` responses.
 
-Extensions which can infer some metadata automatically need to implement and register a `MetadataProvider` service in order to make them available to the system. 
-They may provision them from any source they like and also dynamically remove or add data. 
+Extensions which can infer some metadata automatically need to implement and register a `MetadataProvider` service in order to make them available to the system.
+They may provision them from any source they like and also dynamically remove or add data.
 They are also not restricted to a single namespace.
 
-The `MetadataRegistry` provides access for all extensions which need to read the Item metadata programmatically. 
+The `MetadataRegistry` provides access for all extensions which need to read the Item metadata programmatically.
 It is the central place where additional information about Items is kept.