Updated documentation:

1. What's new
2. Supported user macros
3. Time suffixes
4. LLD macros
5. Upgrade notes
6. Item configuration
7. Low-level discovery
8. Network discovery
9. Action operations
10. Web scenarios
11. Slide shows
12. Administration -> General (GUI, Housekeeper, Trigger displaying options, Other parameters)

glebs.ivanovskis Few comments:

1. In some places only suffix support was added, in some - only user macro support. I don't know if we need to go into details in What's new, but there are more features lurking behind update intervals in ZBXNEXT-1675 which might be good to mention in What's new, e.g.: 'History storage period' can now be as short as 1h (ZBXNEXT-867), user macros can be used as time periods in action/operation conditions and working hours (no one asked for it).
2. Discovery 'Delay period' was renamed to 'Update interval'.
3. User profile -> Messaging 'Message timeout' is missing.
4. Looks good.
5. Nice!
6. Worth adding "Since Zabbix 3.4.0"?
7. There are no such examples in our official templates, but just for screenshots we could probably place a few macros in LLD rule custom intervals and item prototype form? Showcase user macro with LLD macro in context (e.g. {$UPDATE_INTERVAL:"{#FSNAME}"})?
8. Worth adding "Since Zabbix 3.4.0"?
9. Worth adding "Since Zabbix 3.4.0"?
10. Worth adding "Since Zabbix 3.4.0"?
11. Looks good.
12. Excellent!
13. You have not mentioned Action conditions, but it looks good. Apart from "Since Zabbix 3.4.0", probably.

And probably it worth noting that for items, LLD rules and item prototypes support of user macros in 'Update interval' actually means support of user macros in 'Update interval' and 'Custom intervals'.

Probably a few examples can be extracted from use cases described in the specification. Like using item update interval macro in trigger expression or configuring working hours as a macro and using it in item flexible intervals to increase polling frequency during business hours.

martins-v Added the examples to user macro page.

martins-v I've tried to address all the issues in the comments. Except the screenshot for LLD, which cannot be made properly because the field length in custom intervals does not allow to display a longer macro fully... RESOLVED

glebs.ivanovskis Great respect for such attention to detail!
6. I noticed that reference to version 2.2 was removed. In some other places we keep all "history" (e.g. here), but if it is a new trend I have no objections.
7. Not a big deal, looks fine without a screenshot.
1.-13. CLOSED
I like the idea of a separate User macro supported by location page, but I would place it into Configuration->Macros section where a very similar LLD macro page lives.
In Example 5 would be more user friendly to use screenshot instead of

{$LONG_INTERVAL};{$SHORT_INTERVAL}/{$WORKING_HOURS}

Users will write such expressions only when configuring items via API, normally they will use frontend form.
And finally, could you please take care of ZBXNEXT-1675.(66)?

martins-v I do not really intend to remove all older history of 'supported since' notes, however, as the amount of info in documention grows and Zabbix versions are released more often, I believe we need to start removing some 'supported since' notes at least partially in places where they are becoming an "obstruction".

The reason why User macro supported by location page is in the appendixes is that we try to move sections containing longer lists of detail in there. It helps to keep the main section of documentation more compact. LLD macro page may end up in appendixes too, if we dramatically increase the number of locations where they are supported. There is room for criticism to such approach, as even the important trigger function page is in the appendixes. However, it is probably better than the approach we had before Zabbix 2.0, when documentation in many sections was one long list following another.

I've added a screenshot to example 5.

ZBXNEXT-1675.(66) has been addressed.

RESOLVED

glebs.ivanovskis Perfect! Thank you for explanations!
CLOSED

glebs.ivanovskis, can you comment on what we need to mention in the upgrade notes regarding this issue?

Also, does anything change for the user experience regarding flexible intervals?

Basically, whatever from Database section of specification that is suitable for end user documentation. Most importantly, we should mention that Keep lost resources setting of LLD rules containing macro will be set to 25 years during upgrade. We convert this setting from days into seconds. We can't simply append "d" since syntax "{$MACRO}d" is not supported and we can't convert macro values to seconds since they may be used in other places. Therefore, this is something to take care of manually. Less important things include History/Trend storage period maximum reduction to 25 years and action step duration maximum reduction to 1 week.

Custom intervals will support macros too. Flexible interval part featuring interval itself will support time units:

(1) May or may not be related to this task. Broken link Time-unit symbols in internal items, trigger functions, internal and aggregate checks. I fixed them, please review.

sasha Thanks! CLOSED