docs: def wrong_usage (docstring, *rest):
      """Print a message indicating invalid command-line arguments and exit with an
      error code.
  
      :arg str docstring: the program help text
      :arg rest: an optional specific error message
  
      This function is intended for small programs launched from the command
      line. The intention is for the program help information to be written in
      its docstring, and then for argument checking to look something like
      this::
  
          \"\"\"mytask <input> <output>
  
          Do something to the input to create the output.
          \"\"\"
          ...
          import sys
          ... # other setup
          check_usage (__doc__)
          ... # more setup
          if len (sys.argv) != 3:
             wrong_usage (__doc__, "expect exactly 2 arguments, not %d",
                          len (sys.argv))
  
      When called, an error message is printed along with the *first stanza* of
      *docstring*. The program then exits with an error code and a suggestion to
      run the program with a --help argument to see more detailed usage
      information. The "first stanza" of *docstring* is defined as everything up
      until the first blank line, ignoring any leading blank lines.
  
      The optional message in *rest* is treated as follows. If *rest* is empty,
      the error message "invalid command-line arguments" is printed. If it is a
      single item, the stringification of that item is printed. If it is more
      than one item, the first item is treated as a format string, and it is
      percent-formatted with the remaining values. See the above example.
  
      See also :func:`check_usage` and :func:`show_usage`.
  
      """
      intext = False
  
      if len (rest) == 0:
          detail = 'invalid command-line arguments'
      elif len (rest) == 1:
          detail = rest[0]
      else:
          detail = rest[0] % tuple (rest[1:])
  
      print ('error:', detail, '\n', file=sys.stderr) # extra NL
      show_usage (docstring, True, sys.stderr, 1)