Update the effect handlers manual page to use syntax

[kayceesrk]

#12309 has introduced syntax for deep handlers. The manual page (https://v2.ocaml.org/manual/effects.html) currently uses the Stdlib Effect module, not the syntax. The page has to be updated to use the syntax version.

The page should introduce the syntax version first for deep handlers. Towards the end of the section on deep handlers, one of the previously introduced examples can be used to show that the same program can be written using the Stdlib Effect module. This will be a good segue to introducing shallow handlers, which do not have syntax support.

[hyphenrf]

While I was reading the previous discussion, I saw #12309 (comment). It made me think about what pushing the syntax early in the relevant manual section conveys.

Wouldn't this be messaging that it's more of a mature feature despite the note in the beginning? The syntax on its own already lowers the barrier of usage (e.g. you now don't have to manually specify and wire the effect's type variable through in the handler).. using it as the default in documentation material becomes more of a soft endorsement I imagine. It would be the case for me if I was reading the manual & not aware of the wider context around the feature and its current stage of development. I'd be more tempted to design things using it, taking the note I mentioned to mean that just the API is in flux, not the semantics of the feature itself.

The messaging from you maintainers here in development discussions seems to be that we shouldn't use effects and their operations directly in everyday code.. instead using abstractions built on top of them which cover raw performs, handlers, and the effect constructors. Also that the feature itself can be subject to massive reworking, that it's not mature nor frozen in its current form. The manual would nudge it towards being more complete and satisfactory, with the evidence being its elevation from library API to syntax, and the use of that syntax by default in examples.

Maybe the note in the beginning should be elevated to a warning or the experimental nature be more visually emphasized, to balance things out. Maybe the syntax form should be pushed lower in the page, or just mentioned in the lexical definitions of the relevant constructs without changing the examples. Maybe I'm overthinking it. I don't know. What do you think?

[yawaramin]

Imho the user manual is not the place to be making editorial decisions about what parts of the language are encouraged or discouraged. It should clearly document the language as is.

[hyphenrf]

The manual isn't a formal spec. There are lots of soft parts with subjective wording that influence how a feature is approached,

what parts of the language are encouraged or discouraged

and precedent for this actually, as suggestions for idiomatic approaches, or as implicit nudges to make the reader aware of common gotchas, as I imagine this would be too.