macros: hard and soft macros explanation adjustments, added some missing macro references (#303)

Author: HofiOne

_data/link_aliases.yml

@@ -55,7 +55,7 @@ adm-temp-macro-ose#sdata-sdatasdidsdname:
   aliases: [ "${SDATA}" ]
 
 adm-temp-macro-ose#sec-c_sec-r_sec-s_sec:
-  aliases: [ "/${SEC}|\\${[CRS]_SEC}/" ]
+  aliases: [ "/\\${SEC}|\\${[CRS]_SEC}/" ]
 
 adm-temp-macro-ose#stamp-r_stamp-s_stamp:
   aliases: [ "/\\${STAMP}|\\${[RS]_STAMP}/" ]
@@ -67,7 +67,7 @@ adm-temp-macro-ose#tzoffset-c_tzoffset-r_tzoffset-s_tzoffset:
   aliases: [ "/\\${TZOFFSET}|\\${[CRS]_TZOFFSET}/" ]
 
 adm-temp-macro-ose#unixtime-c_unixtime-r_unixtime-s_unixtime:
-  aliases: [ "/$\\{UNIXTIME}|\\${[CRS]_UNIXTIME}/" ]
+  aliases: [ "/\\${UNIXTIME}|\\${[CRS]_UNIXTIME}/" ]
 
 adm-temp-macro-ose#usec-c_usec-r_usec-s_usec:
   aliases: [ "/\\${USEC}|\\${[CRS]_USEC}/" ]
@@ -90,6 +90,9 @@ adm-temp-macro-ose#week_day_name-c_week_day_name-r_week_day_name-s_week_day_name
 adm-temp-macro-ose#year-c_year-r_year-s_year:
   aliases: [ "/\\${YEAR}|\\${[CRS]_YEAR}/" ]
 
+adm-temp-macro-ose#year_day-c_year_day-r_year_day-s_year_day:
+  aliases: [ "/\\${YEAR_DAY}|\\${[CRS]_YEAR_DAY}/" ]
+
 adm-log-flow#log-paths-with-flow-control:
   aliases: [ "Managing incoming and outgoing messages with flow-control" ]
 
@@ -261,6 +264,12 @@ adm-correlate:
 adm-stats:
   aliases: [ "syslog-ng-ctl stats", "syslog-ng-ctl query" ]
 
+adm-temp-hard-soft-macros#hard-macros:
+  aliases: [ "/[Hh]ard [Mm]acros/" ]
+
+adm-temp-hard-soft-macros#soft-macros:
+  aliases: [ "/[Ss]oft [Mm]acros/" ]
+
 doxygen-home:
   aliases: [ "/[Dd]oxygen/" ]
 

doc/_admin-guide/110_Template_and_rewrite/000_Customize_message_format/003_Hard_vs_soft_macros.md

@@ -1,17 +1,27 @@
 ---
 title: Hard versus soft macros
-id: adm-temp-hard-soft-macro
+id: adm-temp-hard-soft-macros
 description: >-
-    Hard macros contain data that is directly derived from the log message,
-    for example, the ${MONTH} macro derives its value from the timestamp.
-    Hard macros are read-only. Soft macros (sometimes also called name-value
-    pairs) are either built-in macros automatically generated from the log
-    message (for example, ${HOST}), or custom user-created macros generated
-    by using the {{ site.product.short_name }} pattern database or a CSV-parser. In contrast to
-    hard macros, soft macros are writable and can be modified within
-    {{ site.product.short_name }}, for example, using rewrite rules.
+    This section describes the differences between hard and soft macros in {{ site.product.short_name }}.
 ---
 
+## Hard macros
+
+Hard macros contain data that is directly derived from the log message,
+for example, the ${MONTH} macro derives its value from the timestamp.
+Hard macros are read-only.
+
+## Soft macros
+
+Soft macros (sometimes also called name-value
+pairs) are either built-in macros automatically generated from the log
+message (for example, ${HOST}), or custom user-created macros generated
+by using the {{ site.product.short_name }} pattern database or a CSV-parser. In contrast to
+hard macros, soft macros are writable and can be modified within
+{{ site.product.short_name }}, for example, using rewrite rules.
+
+## Comparison of hard and soft macros
+
 Hard and soft macros are rather similar and often treated as equivalent.
 Macros are most commonly used in filters and templates, which does not
 modify the value of the macro, so both soft and hard macros can be used.
@@ -31,6 +41,7 @@ ${PROGRAM}, ${SOURCE}. Custom values created using rewrite rules or parsers
 can be modified as well, just like stored matches of regular expressions
 ($0 \... $255).
 
-Note that you can modify the timezone of the message, and change the
+**NOTE:** You can modify the timezone of the message, and change the
 timezone-related macros that way. For details, see
 Rewrite the timezone of a message.
+{: .notice--info}

doc/_admin-guide/110_Template_and_rewrite/000_Customize_message_format/004_Macros_of_syslog-ng.md

@@ -37,6 +37,10 @@ facility letter can range from **A** to **Y**, where A corresponds to
 facility number zero (LOG_KERN), B corresponds to facility 1
 (LOG_USER), and so on.
 
+## ${CONTEXT_ID}
+
+The context_id for the pattern database rule that matched the message. see the context-id, context-timeout, and context-scope attributes of pattern database rules.
+
 ## Custom macros
 
 CSV parsers and pattern databases can also define macros
@@ -155,6 +159,10 @@ ${ISOWEEK} macro.
 
 Available in 3.24 and later.
 
+## ${LEGACY_MSGHDR}
+
+During default operation, {{ site.product.short_name }} stores the original incoming header of the log message. This is useful if the original format of a non-syslog-compliant message must be retained (as {{ site.product.short_name }} automatically corrects some non-compliant messages, the final result may slightly differ from the original).
+
 ## ${LEVEL_NUM}
 
 The priority (also called severity) of the message,
@@ -533,6 +541,10 @@ Available in {{ site.product.short_name }} version 3.4 and later.
 
 The year the message was sent.
 
+## ${YEAR_DAY}, ${C_YEAR_DAY}, ${R_YEAR_DAY}, ${S_YEAR_DAY}
+
+The day of the year the message was sent.
+
 ## ${WEEK}, ${C_WEEK}, ${R_WEEK}, ${S_WEEK}
 
 The week number of the year, prefixed with a zero for the

doc/_admin-guide/120_Parser/004_CSV_parser/000_CSV_parser_options.md

@@ -1,6 +1,7 @@
 ---
 title: Options of CSV parsers
 parser: csv
+prefix: empty
 id: adm-parser-csv-opt
 description: >-
     This section describes the options of the csv-parser() in {{ site.product.short_name }}.

doc/_admin-guide/120_Parser/010_JSON_parser/000_JSON_parser_options.md

@@ -1,34 +1,36 @@
 ---
 title: Options of JSON parsers
 parser: json
+prefix: empty
 id: adm-parser-json-opt
 description: >-
-    This section describes the options of the json-parser() in {{ site.product.short_name }}.
+    This section explains how to configure JSON parsing with extract-prefix() for subtree extraction, key-delimiter() for custom delimiters, marker() for identifying JSON messages, and prefix() for name-value pair prefixing in {{ site.product.short_name }}.
 ---
 
 The JSON parser has the following options.
 
 ## extract-prefix()
 
-| Synopsis: | extract-prefix() |
+| Type:    | string |
+| Default: |        |
 
 *Description:* Extract only the specified subtree from the JSON message.
 Use the dot-notation to specify the subtree. The rest of the message
 will be ignored. For example, assuming that the incoming object is named
-msg, the json-parser(extract-prefix(\"foo.bar\[5\]\")); parser is
-equivalent to the msg.foo.bar\[5\] javascript code. Note that the
+`msg`, the `json-parser(extract-prefix("foo.bar[5]"));` parser is
+equivalent to the `msg.foo.bar[5]` javascript code. Note that the
 resulting expression must be a JSON object in order to extract its
 members into name-value pairs.
 
 This feature also works when the top-level object is an array, because
 you can use an array index at the first indirection level, for example:
-json-parser(extract-prefix(\"\[5\]\")), which is equivalent to msg\[5\].
+`json-parser(extract-prefix("[5]"))`, which is equivalent to `msg[5]`.
 
 In addition to alphanumeric characters, the key of the JSON object can
 contain the following characters:
-!\"\#$%&\'()\*+,-/:;\<=\>?@\\\^\_\`{\|}\~
+`` !"#$%&'()*+,-/:;<=>?@\^_`{|}~ ``
 
-It cannot contain the following characters: .\]\[
+It cannot contain the following characters: `.][`
 
 ### Example: Convert logstash eventlog format v0 to v1
 
@@ -56,22 +58,22 @@ parser p_jsoneventv0 {
 ## key-delimiter()
 
 | Type:    | character |
-| Default: | .         |
+| Default: | `.`       |
 
 *Description:* The key-delimiter() option defines the used character when parsing flattened keys. Only single characters are supported.
 
-Using the json-parser() without the key-delimiter() option, results in the dot(.) character being used:
+Using the json-parser() without the key-delimiter() option, results in the dot `.` character being used:
 
 ```config
 foo.key="value"
 ```
 
 Using the json-parser() with the key-delimiter("~") option, results in the specified character being used:
 
-
 ## marker()
 
-| Synopsis: | marker() |
+| Type:    | string |
+| Default: |        |
 
 *Description:* Use a marker in case of mixed log messages, to identify
 JSON encoded messages for the parser.
@@ -82,8 +84,8 @@ message only if it is present.
 
 ### Example: Using the marker option in JSON parser
 
-This json parser parses log messages which use the \"@cee:\" marker in
-front of the json payload. It inserts \".cee.\" in front of the name of
+This json parser parses log messages which use the `@cee:` marker in
+front of the json payload. It inserts `.cee.` in front of the name of
 name-value pairs, so later on it is easier to find name-value pairs that
 were parsed using this parser. (For details on selecting name-value
 pairs, see value-pairs()

doc/_admin-guide/120_Parser/019_regexp_parser/000_regex_parser_options.md

@@ -1,6 +1,7 @@
 ---
 title: Options of Regular expression parsers
 parser: regexp
+prefix: empty
 id: adm-parser-regexp-opt
 description: >-
     This section describes the options of the regexp-parser() in {{ site.product.short_name }}.