I see nothing wrong with extensive SYNOPSIS and EXAMPLES sections for programs using --long-options. The fish shell extracts completion information from man pa

I see nothing wrong with extensive SYNOPSIS and EXAMPLES sections for programs using --long-options. The fish shell extracts completion information from man pages, so that the user does not have to type so much and they get useful output, pulled from the manpage, no less.