From: janis_papanagnou+ng@hotmail.com   
      
   On 08.11.2025 00:24, Keith Thompson wrote:   
   > [...]   
   >   
   > For a program that requires at least some command-line arguments, a very   
   > short message that points the user to a "-h" or "--help" option can be   
   > useful.  Don't show a very long usage message unless the user explicitly   
   > asks for it.  [...]   
      
   The previously already mentioned two-level help is indeed to prefer.   
      
   >   
   > "rm --help" prints a 39-line message.  (I'm not going to get into   
   > whether "-h" or "--help" is better.  The latter is a GNU convention.)   
      
   The problem with a choice of -h for that is that this letter h might   
   be a good choice for an existing functional option and would then not   
   be available any more for that. (I thus consider this "convention" a   
   badly decided thing as far as -h is concerned, while --help is okay.)   
      
   We've thus used -? for that usage purpose, a _non-letter_ character;   
   it was standard in all our tools and I'm still using that convention   
   in my private context.   
      
   In that light it's also interesting to have a look into ksh's getopts   
   built-in function. If you use that function in your programs you have   
   automatically some help standard formats and outputs generated. If   
   you type (in ksh) getopts --man you will get its man-page and find at   
   the bottom these built-ins standards for help information:   
       -?    To generate a usage synopsis.   
       --??  To generate a verbose usage message.   
       --??man   
             To generate a formatted man page.   
       --??api   
             To generate an easy to parse usage message.   
       --??html   
             To generate a man page in html format.   
       --??nroff   
             To generate a man page in nroff format.   
       --??usage   
             List the current optstring.   
      
   That comes all for free [when using ksh getopts].   
      
   But the choices are IMO also a good paragon; -? for single line usage,   
   --?? for a verbose information. (For the latter I'd prefer --help and   
   instead of --??man it seems that --man also suffices; that at least   
   produces the same result for getopts --man and getopts --??man.)   
      
   For a three-level verbosity, -?, --help, --man, would be my choice.   
      
   >   
   > Unfortunately, this doesn't work for a command that can validly be run   
   > with no arguments, like cat.   
      
   Programs that accept no arguments (e.g. in filters that assume input   
   from stdin instead of from files then) you would have to use something   
   like -? (although cat, specifically, doesn't support that, sadly). For   
   other programs, those that need arguments, omitting any argument should   
   produce a one-liner usage message, IMO. Using -? could be widely used   
   for all cases.   
      
   >   
   > Print error messages to stderr, usage messages (at least if   
   > requested via some kind of help option) to stdout.  I've seem   
   > commands where "foo --help" prints more text than can fit on my   
   > screen, and "foo --help | less" shows me nothing because the output   
   > I asked for was sent to stderr.   
      
   This is also what ksh does. I think that's a very unfortunate decision;   
   especially because of the reason you mentioned, piping through a pager.   
      
   Janis   
      
   > [...]   
      
   --- SoupGate-Win32 v1.05   
    * Origin: you cannot sedate... all the things you hate (1:229/2)