I disagree as well, but on a bit different grounds. Man pages often lack examples of the syntactical structure, and the syntax is not appropriately documented

I disagree as well, but on a bit different grounds. Man pages often lack examples of the syntactical structure, and the syntax is not appropriately documented either. You can have commands where the flag is followed by an argument, but that flag also is positional, and the position is not documented. You can't just read the man page and get a working command, there's a lot of trial and error which is naturally solved by having a section of commands in an extended form with examples. Powershell does this, and they took it, from somewhere though I'm having trouble recalling the exact name at the moment I know it wasn't an innovation on their part they just glued a bunch of things together that were used in isolation.