I realised this wasn’t really covered, as exposed by some recent questions here. So, a new aTbRef article is born: Square Brackets in code operator explanations.
Of course, it turns out the meaning can be both figurative (optional content) or literal (nested lists, dictionary keys) so context matters. But at least there’s now an article to which we can direct the confused.
SUGGESTION: use [, optional_argument] in italics for optional arguments.
I like the idea but in practical terms it’s not possible as $Name is not styled. So short of hand-HTML-coding 100s of page titles the idea isn’t practical. I’m open to ideas but the limiting factor is the time taken to implement/maintain the solution.
I suspect those liable to be unable to tell apart the two uses of [ … ] in the syntax examples are likely to miss the italicisation. That’s not a slur, but a reflection the issue is the degree to which the material is alien to the readers current experience. For instance, colour rather than font face is a better call-out. However, it fails for the above reasons: no support and the fiddly/time-consuming nature of the mark-up.
As it stands, the action code operator is the most complex part of aTbRef. Each of the now 302 items in the list has 20 user attributes, quite apart from the test and the need to constantly review code examples to account for changes in current practice. The latter is self-imposed, but out-of-date code, even if it runs, doesn’t really help the reader who’s trying to learn.