More detailed documentation on the behavior of multiple `state` calls with the same key

[yaksher]

The current documentation of State is very ambiguous on how exactly multiple calls to state with the same key behave.

My testing suggests that:

• the underlying "actual state", which is uniquely identified by its key, is effectively a series of updates, which are either functions of one argument or values that aren't functions; values that aren't functions effectively behave identically to constant functions of one argument (i.e., functions which just ignore their one argument and always return the same thing).
• when you access a state through any particular handle, created by a call to state(key) with an optional initial value, it invokes the state's updates up to the appropriate location in order on the initial value of the handle.

This means that calls to update don't care which handle you use for them, only the key of that handle, while calls to display() and similar will all depend on which handle you use. For example, the below code displays:

#let handle1 = state("test", 1)
#let handle2 = state("test", 2)
#handle1.display()
#handle2.display()
#handle1.update(it => it + 10)
#handle2.update(it => it + 10)
#handle1.display()
#handle2.display()
#state("test").update(3)
#handle1.display()

1, 2, 21, 22, 3 (note that both updates applied to the state accessed through both handles, but even after updating, the values are distinct)

I'm not sure how best to summarize this, but it should probably be somewhere in the docs.

[laurmaedje]

Your description is accurate.