As I see it, --help should only be a reminder for the syntax and available flags.
For example, you would use --help when I'm not sure if the flag to make chmod do recursion is -r or -R.
--help should be clean and easy to read. The detailed usage goes to the manual.

If you buy a chainsaw and have no idea how to use it, you check the manual. If you want a reminder about what a button does, there's the pictogram above it.

I use "chef" at work to auromatize deployments, which has a "knife" command that does not have a manual, so you MUST use their painful embedded help.
You type "knife help" and get rewarded by a wall of text that doesn't even fit on my 1920x1600 monitor.
You run it again through "less", and AH, you forgot to redirect stderr to stdout. 3rd try.
You finally find the subcommand you want, type "knife help subcommand", and get the same wall as before. Because the command is fucking "knife subcommand help", and it's not specified in the previous shitty help.

Trying to provide interactive help is confusing, and all you can do is provide meaningless examples because you don't make full sentences in such help text to describe how it works.
This is what you do in manuals though, which is why they are still relevant and important.
Especially when the manoage includes an EXAMPLE section ;)