[Logging] Add example for logging Item state (#546)

* Add example for logging Item State

-  Addresses #534
-  Edited text to improve comprehension
-  Changed "Demo" to "heating-control.rules" in text
-  Changed "Demo" example to "heating-control.rules" example in #534
-  Article needs more work, but this PR is limited to addressing this issue.

* Address various comments from ThomDietrich

-  Numerous changes to address comments

Signed-off-by: Brad Gilmer <brad@gilmer.tv> (github: bgilmer77)

* Shorten package name/log example

-  Shortened package to e.model.script.heating-control.rules
-  Removed one of the temp entries from the logging example

Signed-off-by: Brad Gilmer <brad@gilmer.tv> (github: bgilmer77)

* Add improvements

Signed-off-by: Thomas Dietrich <thomas.dietrich@tu-ilmenau.de> (github: ThomDietrich)

* Change suggested by @bgilmer

Signed-off-by: Thomas Dietrich <thomas.dietrich@tu-ilmenau.de> (github: ThomDietrich)

administration/logging.md

@@ -8,7 +8,7 @@ title: Logging
 # Logging in openHAB
 
 This article describes the logging functionality in openHAB 2.
-Ths includes how to access logging information and configure logging for user-defined rules. 
+Ths includes how to access logging information and configure logging for user-defined rules.
 
 There are two ways to check log entries:
 
@@ -91,29 +91,39 @@ Note that the log levels set using the `log:set` commands are not persistent and
 
 ## Create Log Entries in Rules
 
-It is also possible to create own log entries in rules. This is especially useful for debugging purposes.
+There are times, especially when troubleshooting rules, when it can be helpful to write information and variable or Item State values to the log.
 
-For each log level there is an corresponding command for creating log entries. These commands require two parameters: the subpackage (here: `Demo`) and the text which should appear in the log:
+For each log level there is an corresponding command for creating log entries.
+You may use these log levels to filter or better differentiate the generated logging output.
+The logging commands require two parameters: the subpackage, in the examples below `heating-control.rules`, and the text which should appear in the log:
 
 ```java
-logError("Demo","This is a log entry of type Error!")
-logWarn("Demo","This is a log entry of type Warn!")
-logInfo("Demo","This is a log entry of type Info!")
-logDebug("Demo","This is a log entry of type Debug!")
+logError("heating-control.rules", "This is a log entry of type Error!")
+logWarn("heating-control.rules", "This is a log entry of type Warn!")
+logInfo("heating-control.rules", "This is a log entry of type Info!")
+logDebug("heating-control.rules", "This is a log entry of type Debug!")
 ```
 
-In order to see the messages, logging for the message class has to be activated. The main package is predefined (`org.eclipse.smarthome.model.script`) and the subpackage needs to be concatenated:
+The main package of all script/rules based log entries is predefined as `org.eclipse.smarthome.model.script`.
+The chosen subpackage is appended to the end of the main package.
+It can be useful for filtering or package-based log level settings.
+
+Examples for typical logging lines found in rules:
 
 ```text
-log:set DEBUG org.eclipse.smarthome.model.script.Demo
+logInfo("heating-control.rules", "Heating mode set to normal")
+logError("heating-control.rules", "Heating control failed while in mode " + Heating_Mode.state)
+logDebug("heating-control.rules", "Bedroom: Temperature: %1$.1f°C, Mode %2$s", Bedroom_Temp.state, Bedroom_Heater_Mode.state)
 ```
 
-The output for the above log statement of type **DEBUG** is:
+An example output of the last log statement above is:
 
 ```
-2016-06-04 16:28:39.482 [DEBUG] [.eclipse.smarthome.model.script.Demo] - This is a log entry of type DEBUG!
+2016-06-04 16:28:39.482 [DEBUG] [.e.model.script.heating-control.rules] 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/javase/7/docs/api/java/util/Formatter.html).
+
 ## Logging into Separate File
 
 Per default all log entries are saved in the file `openhab.log` and event specific entries are saved in `events.log`. Additional files can be defined in order to write specifics logs to a separate place.