doc: document local variables and their distinction to message JSON properties

1 files changed, 20 insertions, 0 deletions

diff --git a/doc/rainerscript.html b/doc/rainerscript.html
index d1d9f0a2..0faa38b5 100644
--- a/doc/rainerscript.html
+++ b/doc/rainerscript.html
@@ -34,6 +34,26 @@ return a valid result, as you can't really add two letters (to
 concatenate them, use the concatenation operator &).
  However, all type conversions are automatically done by the
 script interpreter when there is need to do so.<br>
+<h2>Variable (Property) types</h2>
+<p>All rsyslog properties (see the <a href="property_replacer.html">property
+replacer</a> page for a list) can be used in RainerScript. In addition, it also
+supports local variables. These are local to the current message, but are
+NOT message properties (e.g. the "$!" all JSON property does not contain
+them). Future releases will probably introduce rsyslog global variables which
+exists outside the scope of a single message.
+<p>Only message json (CEE/Lumberjack) properties can be modified by
+the "set" and "unset" statements, not any other message property. Obviously,
+local variables are also modifieable.
+<p>Message JSON property names start with "$!" where the bang character
+represents the root.
+<p>Local variables names start with "$.", where the dot denotes the root.
+<p>Both JSON properties as well as local variables may contain an arbitrary
+deep path before the final element. The bang character is always used as path
+separator, no matter if it is a message property or a local variable. For example
+"$!path1!path2!varname" is a three-level deep message property where as
+the very similar looking "$.path1!path2!varname" specifies a three-level
+deep local variable. The bang or dot character immediately following the
+dollar sign is used by rsyslog to separate the different types.
 <h2>configuration objects</h2>
 <h3>main_queue()</h3>
 <p><i>This object is available since 7.5.3.</i>