From 5ca0009f4c3b4229d891ca75350b3876fb2fed52 Mon Sep 17 00:00:00 2001 From: Mate Ory Date: Wed, 29 Oct 2025 22:33:51 +0100 Subject: [PATCH 1/2] add xref to date-related macros section for each date-related macro The individual descriptions don't really help about what the different prefixes mean, or what exactly the "time" we are talking about is. --- .../reference-macros/_index.md | 26 +++++++++---------- content/headless/chunk/macro-date-ref.md | 4 +++ content/headless/chunk/macro-date.md | 3 +-- content/headless/chunk/macro-day.md | 3 +-- content/headless/chunk/macro-fulldate.md | 2 +- content/headless/chunk/macro-hour.md | 2 +- content/headless/chunk/macro-min.md | 2 +- content/headless/chunk/macro-month.md | 2 +- content/headless/chunk/macro-sec.md | 2 +- content/headless/chunk/macro-tz.md | 2 +- content/headless/chunk/macro-tzoffset.md | 2 +- content/headless/chunk/macro-unixtime.md | 2 +- content/headless/chunk/macro-week.md | 2 +- content/headless/chunk/macro-year.md | 2 +- 14 files changed, 29 insertions(+), 27 deletions(-) create mode 100644 content/headless/chunk/macro-date-ref.md diff --git a/content/chapter-manipulating-messages/customizing-message-format/reference-macros/_index.md b/content/chapter-manipulating-messages/customizing-message-format/reference-macros/_index.md index 08446d8d..e6e2e211 100644 --- a/content/chapter-manipulating-messages/customizing-message-format/reference-macros/_index.md +++ b/content/chapter-manipulating-messages/customizing-message-format/reference-macros/_index.md @@ -82,7 +82,7 @@ The {{% param "product.abbrev" %}} application uses the following procedure to d ## HOUR12, C_HOUR12, R_HOUR12, S_HOUR12 {#macro-hour12} -*Description:* The hour of day the message was sent in 12-hour clock format. See also the [`${AMPM}`]({{< relref "/chapter-manipulating-messages/customizing-message-format/reference-macros/_index.md" >}}) macro. 12AM is midnight. Available in {{% param "product.abbrev" %}} 3.4 and later. +*Description:* The hour of day the message was sent in 12-hour clock format. See also the [`${AMPM}`]({{< relref "/chapter-manipulating-messages/customizing-message-format/reference-macros/_index.md" >}}) macro. 12AM is midnight. Available in {{% param "product.abbrev" %}} 3.4 and later. {{% include-headless "chunk/macro-date-ref.md" %}} ## HOST {#macro-host} @@ -116,13 +116,13 @@ The IP protocol version used to retrieve or receive the message. Contains either ## ISODATE, C_ISODATE, R_ISODATE, S_ISODATE {#macro-isodate} -*Description:* Date of the message in the ISO 8601 compatible standard timestamp format (`yyyy-mm-ddThh:mm:ss+-ZONE`), for example: `2006-06-13T15:58:00.123+01:00`. If possible, it is recommended to use `${ISODATE}` for timestamping. Note that AxoSyslog can produce fractions of a second (for example, milliseconds) in the timestamp by using the `frac-digits()` global or per-destination option. +*Description:* Date of the message in the ISO 8601 compatible standard timestamp format (`yyyy-mm-ddThh:mm:ss+-ZONE`), for example: `2006-06-13T15:58:00.123+01:00`. If possible, it is recommended to use `${ISODATE}` for timestamping. Note that AxoSyslog can produce fractions of a second (for example, milliseconds) in the timestamp by using the `frac-digits()` global or per-destination option. {{% include-headless "chunk/macro-date-ref.md" %}} {{< include-headless "wnt/n-frac-trunc.md" >}} ## ISOWEEK, C_ISOWEEK, R_ISOWEEK, S_ISOWEEK {#macro-isoweek} -*Description:* The number of week according to the ISO 8601 standard. Note that the `${WEEK}` macro that has been available in returns a non-standard week number that can differ from the value returned by the `${ISOWEEK}` macro. +*Description:* The number of week according to the ISO 8601 standard. Note that the `${WEEK}` macro that has been available in returns a non-standard week number that can differ from the value returned by the `${ISOWEEK}` macro. {{% include-headless "chunk/macro-date-ref.md" %}} Available in 3.24 and later. @@ -153,19 +153,19 @@ Note that before AxoSyslog version 3.0, the `${MESSAGE}` macro included the prog ## MONTH_ABBREV, C_MONTH_ABBREV, R_MONTH_ABBREV, S_MONTH_ABBREV {#macro-month-abbrev} -*Description:* The English abbreviation of the month name (3 letters). +*Description:* The English abbreviation of the month name (3 letters). {{% include-headless "chunk/macro-date-ref.md" %}} ## MONTH_NAME, C_MONTH_NAME, R_MONTH_NAME, S_MONTH_NAME {#macro-month-name} -*Description:* The English name of the month name. +*Description:* The English name of the month name. {{% include-headless "chunk/macro-date-ref.md" %}} ## MONTH_WEEK, C_MONTH_WEEK, R_MONTH_WEEK, S_MONTH_WEEK {#macro-month-week} -*Description:* The number of the week in the given month (0-5). The week with numerical value 1 is the first week containing a Monday. The days of month before the first Monday are considered week 0. For example, if a 31-day month begins on a Sunday, then the 1st of the month is week 0, and the end of the month (the 30th and 31st) is week 5. +*Description:* The number of the week in the given month (0-5). The week with numerical value 1 is the first week containing a Monday. The days of month before the first Monday are considered week 0. For example, if a 31-day month begins on a Sunday, then the 1st of the month is week 0, and the end of the month (the 30th and 31st) is week 5. {{% include-headless "chunk/macro-date-ref.md" %}} ## MSEC, C_MSEC, R_MSEC, S_MSEC {#macro-msec} -*Description:* The millisecond the message was sent. +*Description:* The millisecond the message was sent. {{% include-headless "chunk/macro-date-ref.md" %}} Available in {{% param "product.abbrev" %}} version 3.4 and later. @@ -318,7 +318,7 @@ Available in {{% param "product.abbrev" %}} 4.10 and later. ## STAMP, R_STAMP, S_STAMP {#macro-stamp} -*Description:* A timestamp formatted according to the [`ts-format()`]({{< relref "/chapter-global-options/reference-options/_index.md" >}}) global or per-destination option. +*Description:* A timestamp formatted according to the [`ts-format()`]({{< relref "/chapter-global-options/reference-options/_index.md" >}}) global or per-destination option. {{% include-headless "chunk/macro-date-ref.md" %}} ## SYSUPTIME {#macro-sysuptime} @@ -408,7 +408,7 @@ Available in {{% param "product.abbrev" %}} version 3.7 and later. ## USEC, C_USEC, R_USEC, S_USEC {#macro-usec} -*Description:* The microsecond the message was sent. +*Description:* The microsecond the message was sent. {{% include-headless "chunk/macro-date-ref.md" %}} Available in {{% param "product.abbrev" %}} version 3.4 and later. @@ -418,16 +418,16 @@ Available in {{% param "product.abbrev" %}} version 3.4 and later. ## WEEK_DAY_ABBREV, C_WEEK_DAY_ABBREV, R_WEEK_DAY_ABBREV, S_WEEK_DAY_ABBREV {#macro-week-day-abbrev} -*Description:* The 3-letter English abbreviation of the name of the day the message was sent, for example, `Thu`. +*Description:* The 3-letter English abbreviation of the name of the day the message was sent, for example, `Thu`. {{% include-headless "chunk/macro-date-ref.md" %}} ## WEEK_DAY, C_WEEK_DAY, R_WEEK_DAY, S_WEEK_DAY {#macro-week-day} -*Description:* The day of the week as a numerical value (1-7). +*Description:* The day of the week as a numerical value (1-7). {{% include-headless "chunk/macro-date-ref.md" %}} ## WEEKDAY, C_WEEKDAY, R_WEEKDAY, S_WEEKDAY {#macro-weekday} -*Description:* These macros are deprecated, use [${WEEK_DAY_ABBREV}, ${R_WEEK_DAY_ABBREV}, ${S_WEEK_DAY_ABBREV}]({{< relref "/chapter-manipulating-messages/customizing-message-format/reference-macros/_index.md" >}}) instead. The 3-letter name of the day of week the message was sent, for example, `Thu`. +*Description:* These macros are deprecated, use [${WEEK_DAY_ABBREV}, ${R_WEEK_DAY_ABBREV}, ${S_WEEK_DAY_ABBREV}]({{< relref "/chapter-manipulating-messages/customizing-message-format/reference-macros/_index.md" >}}) instead. The 3-letter name of the day of week the message was sent, for example, `Thu`. {{% include-headless "chunk/macro-date-ref.md" %}} ## WEEK_DAY_NAME, C_WEEK_DAY_NAME, R_WEEK_DAY_NAME, S_WEEK_DAY_NAME {#macro-week-day-name} -*Description:* The English name of the day. +*Description:* The English name of the day. {{% include-headless "chunk/macro-date-ref.md" %}} diff --git a/content/headless/chunk/macro-date-ref.md b/content/headless/chunk/macro-date-ref.md new file mode 100644 index 00000000..3e39cad2 --- /dev/null +++ b/content/headless/chunk/macro-date-ref.md @@ -0,0 +1,4 @@ +--- +--- +See {{% xref "/chapter-manipulating-messages/customizing-message-format/date-macros/_index.md" %}}. + diff --git a/content/headless/chunk/macro-date.md b/content/headless/chunk/macro-date.md index 7371457a..76c2e597 100644 --- a/content/headless/chunk/macro-date.md +++ b/content/headless/chunk/macro-date.md @@ -4,5 +4,4 @@ ## DATE, C_DATE, R_DATE, S_DATE -*Description:* Date of the message using the BSD-syslog style timestamp format (month/day/hour/minute/second, each expressed in two digits). This is the original syslog time stamp without year information, for example: `Jun 13 15:58:00`. - +*Description:* Date of the message using the BSD-syslog style timestamp format (month/day/hour/minute/second, each expressed in two digits). This is the original syslog time stamp without year information, for example: `Jun 13 15:58:00`. {{% include-headless "chunk/macro-date.md" %}} diff --git a/content/headless/chunk/macro-day.md b/content/headless/chunk/macro-day.md index ec8e622e..d9d3d87f 100644 --- a/content/headless/chunk/macro-day.md +++ b/content/headless/chunk/macro-day.md @@ -4,5 +4,4 @@ ## DAY, C_DAY, R_DAY, S_DAY -*Description:* The day the message was sent. - +*Description:* The day the message was sent. {{% include-headless "chunk/macro-date-ref.md" %}} diff --git a/content/headless/chunk/macro-fulldate.md b/content/headless/chunk/macro-fulldate.md index 78868e4c..1824eae7 100644 --- a/content/headless/chunk/macro-fulldate.md +++ b/content/headless/chunk/macro-fulldate.md @@ -4,5 +4,5 @@ ## FULLDATE, C_FULLDATE, R_FULLDATE, S_FULLDATE -*Description:* A nonstandard format for the date of the message using the same format as `${DATE}`, but including the year as well, for example: `2006 Jun 13 15:58:00`. +*Description:* A nonstandard format for the date of the message using the same format as `${DATE}`, but including the year as well, for example: `2006 Jun 13 15:58:00`. {{% include-headless "chunk/macro-date-ref.md" %}} diff --git a/content/headless/chunk/macro-hour.md b/content/headless/chunk/macro-hour.md index 27e04d26..d9dc5986 100644 --- a/content/headless/chunk/macro-hour.md +++ b/content/headless/chunk/macro-hour.md @@ -4,5 +4,5 @@ ## HOUR, C_HOUR, R_HOUR, S_HOUR -*Description:* The hour of day the message was sent. +*Description:* The hour of day the message was sent. {{% include-headless "chunk/macro-date-ref.md" %}} diff --git a/content/headless/chunk/macro-min.md b/content/headless/chunk/macro-min.md index 9a82200b..234116d4 100644 --- a/content/headless/chunk/macro-min.md +++ b/content/headless/chunk/macro-min.md @@ -4,5 +4,5 @@ ## MIN, C_MIN, R_MIN, S_MIN -*Description:* The minute the message was sent. +*Description:* The minute the message was sent. {{% include-headless "chunk/macro-date-ref.md" %}} diff --git a/content/headless/chunk/macro-month.md b/content/headless/chunk/macro-month.md index 1b13b2cc..d38891c8 100644 --- a/content/headless/chunk/macro-month.md +++ b/content/headless/chunk/macro-month.md @@ -4,5 +4,5 @@ ## MONTH, C_MONTH, R_MONTH, S_MONTH -*Description:* The month the message was sent as a decimal value, prefixed with a zero if smaller than 10. +*Description:* The month the message was sent as a decimal value, prefixed with a zero if smaller than 10. {{% include-headless "chunk/macro-date-ref.md" %}} diff --git a/content/headless/chunk/macro-sec.md b/content/headless/chunk/macro-sec.md index 261b3ac0..7ca62a38 100644 --- a/content/headless/chunk/macro-sec.md +++ b/content/headless/chunk/macro-sec.md @@ -4,5 +4,5 @@ ## SEC, C_SEC, R_SEC, S_SEC -*Description:* The second the message was sent. +*Description:* The second the message was sent. {{% include-headless "chunk/macro-date-ref.md" %}} diff --git a/content/headless/chunk/macro-tz.md b/content/headless/chunk/macro-tz.md index 314daf83..5e5dc208 100644 --- a/content/headless/chunk/macro-tz.md +++ b/content/headless/chunk/macro-tz.md @@ -4,5 +4,5 @@ ## TZ, C_TZ, R_TZ, S_TZ -*Description:* An alias of the [${TZOFFSET}](#macro-tzoffset.htm) macro. +*Description:* An alias of the [${TZOFFSET}](#macro-tzoffset.htm) macro. {{% include-headless "chunk/macro-date-ref.md" %}} diff --git a/content/headless/chunk/macro-tzoffset.md b/content/headless/chunk/macro-tzoffset.md index 2f226ce8..c89de175 100644 --- a/content/headless/chunk/macro-tzoffset.md +++ b/content/headless/chunk/macro-tzoffset.md @@ -4,5 +4,5 @@ ## TZOFFSET, C_TZOFFSET, R_TZOFFSET, S_TZOFFSET -*Description:* The time-zone as hour offset from GMT, for example: `-07:00`. In version 1.6.x this used to be `-0700` but as `${ISODATE}` requires the colon it was added to `${TZOFFSET}` as well. +*Description:* The time-zone as hour offset from GMT, for example: `-07:00`. In version 1.6.x this used to be `-0700` but as `${ISODATE}` requires the colon it was added to `${TZOFFSET}` as well. {{% include-headless "chunk/macro-date-ref.md" %}} diff --git a/content/headless/chunk/macro-unixtime.md b/content/headless/chunk/macro-unixtime.md index e7f56f0b..5fb0f7e3 100644 --- a/content/headless/chunk/macro-unixtime.md +++ b/content/headless/chunk/macro-unixtime.md @@ -4,5 +4,5 @@ ## UNIXTIME, C_UNIXTIME, R_UNIXTIME, S_UNIXTIME -*Description:* Standard UNIX timestamp, represented as the number of seconds since `1970-01-01T00:00:00`. +*Description:* Standard UNIX timestamp, represented as the number of seconds since `1970-01-01T00:00:00`. {{% include-headless "chunk/macro-date-ref.md" %}} diff --git a/content/headless/chunk/macro-week.md b/content/headless/chunk/macro-week.md index 43820c6d..52c42ec0 100644 --- a/content/headless/chunk/macro-week.md +++ b/content/headless/chunk/macro-week.md @@ -4,7 +4,7 @@ ## WEEK, C_WEEK, R_WEEK, S_WEEK -*Description:* The week number of the year, prefixed with a zero for the first nine weeks of the year. (The first Monday in the year marks the first week.) +*Description:* The week number of the year, prefixed with a zero for the first nine weeks of the year. (The first Monday in the year marks the first week.) {{% include-headless "chunk/macro-date-ref.md" %}} See also [ISOWEEK, C_ISOWEEK, R_ISOWEEK, S_ISOWEEK]({{< relref "/chapter-manipulating-messages/customizing-message-format/reference-macros/_index.md" >}}). diff --git a/content/headless/chunk/macro-year.md b/content/headless/chunk/macro-year.md index 598cc09c..f1cf7579 100644 --- a/content/headless/chunk/macro-year.md +++ b/content/headless/chunk/macro-year.md @@ -4,5 +4,5 @@ ## YEAR, C_YEAR, R_YEAR, S_YEAR -*Description:* The year the message was sent. +*Description:* The year the message was sent. {{% include-headless "chunk/macro-date-ref.md" %}} From 543a007cd132a756eeceee95d2e04dfa70036336 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A1t=C3=A9=20=C5=90ry?= Date: Thu, 30 Oct 2025 12:25:47 +0100 Subject: [PATCH 2/2] Apply suggestion from @orymate --- content/headless/chunk/macro-date.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/headless/chunk/macro-date.md b/content/headless/chunk/macro-date.md index 76c2e597..4dde563a 100644 --- a/content/headless/chunk/macro-date.md +++ b/content/headless/chunk/macro-date.md @@ -4,4 +4,4 @@ ## DATE, C_DATE, R_DATE, S_DATE -*Description:* Date of the message using the BSD-syslog style timestamp format (month/day/hour/minute/second, each expressed in two digits). This is the original syslog time stamp without year information, for example: `Jun 13 15:58:00`. {{% include-headless "chunk/macro-date.md" %}} +*Description:* Date of the message using the BSD-syslog style timestamp format (month/day/hour/minute/second, each expressed in two digits). This is the original syslog time stamp without year information, for example: `Jun 13 15:58:00`. {{% include-headless "chunk/macro-date-ref.md" %}}