proposal: add level field to figure to enable custom multi-level numberings #6767
Description
Proposal
This proposal seeks to address current limitations of how to handle multi-level numbering patterns for figures, such that the correct counter (and numbering pattern) is used for references, captions, etc.
In particular, the proposal aims to add a level field to the figure element function (analogous to the level of heading). The level field would be optional, with a default value of 1. It would be used internally to set the level parameter of the figure.counter.step method.
Use Case
With this addition, it becomes trivial for users to implement custom multi-level numberings for figures, tables, listings and custom figure kinds (of arbitrary nesting level), such as subfigures (as described in feature request #246).
See #6767 (comment) for example usage.
And, most importantly, the numbering pattern is kept in sync with the counter of a given figure element. Since the numbering pattern may take any form (e.g. "1.1a") and the figure.counter would have the same corresponding number of levels. This should help to improve the situation described in #5442.
The code change required by this proposal is 3 lines of code. The following PR implements this proposal: #6768.
In particular, this proposal would resolve the issue described in #3930, since numbering pattern and counter (of a corresponding nesting level depth) would stay in sync, and in particular, it would be able to use the correct location for the counter (i.e. correct context).
(It is worth noting that the current numbering function that can be used to implement custom multi-level numbering is not enough to resolve #3930, since it lacks the ability to provide the correct context (as described in #3930); thereby having numbers be incorrect when referenced (and depending on where they are referenced), since the numbering function is unable to use the correct location.)
Related discussions
The following discussion threads on the forum would benefit from the above proposal.