docs: def add_argument(self, *args, **kwargs):
          """this method overrides the standard in order to create a parallel
          argument system in both the argparse and configman worlds.  Each call
          to this method returns a standard argparse Action object as well as
          adding an equivalent configman Option object to the required_config
          for this object.  The original args & kwargs that defined an argparse
          argument are preserved in the 'foreign_data' section of the
          corresponding configman Option."""
          # pull out each of the argument definition components from the args
          # so that we can deal with them one at a time in a well labeled manner
          # In this section, variables beginning with the prefix "argparse" are
          # values that define Action object.  Variables that begin with
          # "configman" are the arguments to create configman Options.
          argparse_action_name = kwargs.get('action', None)
          argparse_dest = kwargs.get('dest', None)
          argparse_const = kwargs.get('const', None)
          argparse_default = kwargs.get('default', None)
          if argparse_default is argparse.SUPPRESS:
              # we'll be forcing all options to have the attribute of
              # argparse.SUPPRESS later.  It's our way of making sure that
              # argparse returns only values that the user explicitly added to
              # the command line.
              argparse_default = None
          argparse_nargs = kwargs.get('nargs', None)
          argparse_type = kwargs.get('type', None)
          argparse_suppress_help = kwargs.pop('suppress_help', False)
          if argparse_suppress_help:
              configman_doc = kwargs.get('help', '')
              kwargs['help'] = argparse.SUPPRESS
          else:
              argparse_help = kwargs.get('help', '')
              if argparse_help == argparse.SUPPRESS:
                  configman_doc = ''
              else:
                  configman_doc = argparse_help
  
          # we need to make sure that all arguments that the user has not
          # explicily set on the command line have this attribute.  This means
          # that when the argparse parser returns the command line values, it
          # will not return values that the user did not mention on the command
          # line.  The defaults that otherwise would have been returned will be
          # handled by configman.
          kwargs['default'] = argparse.SUPPRESS
          # forward all parameters to the underlying base class to create a
          # normal argparse action object.
          an_action = super(ArgumentParser, self).add_argument(
              *args,
              **kwargs
          )
          argparse_option_strings = an_action.option_strings
  
          # get a human readable string that identifies the type of the argparse
          # action class that was created
          if argparse_action_name is None:
              argparse_action_name = find_action_name_by_value(
                  self._optionals._registries,
                  an_action
              )
  
          configman_is_argument = False
  
          # each of argparse's Action types must be handled separately.
          #--------------------------------------------------------------------
          # STORE
          if argparse_action_name == 'store':
              if argparse_dest is None:
                  configman_name, configman_is_argument = self._get_option_name(
                      args
                  )
                  if not configman_name:
                      configman_name = args[0]
              else:
                  configman_name = argparse_dest
                  configman_is_argument = not argparse_option_strings
              configman_default = argparse_default
              if argparse_nargs and argparse_nargs in "1?":
                  if argparse_type:
                      configman_from_string = argparse_type
                  elif argparse_default:
                      configman_from_string = (
                          str_to_instance_of_type_converters.get(
                              type(argparse_default),
                              str
                          )
                      )
                  else:
                      configman_from_string = str
              elif argparse_nargs and argparse_type:
                  configman_from_string = partial(
                      str_to_list,
                      item_converter=argparse_type,
                      item_separator=' ',
                  )
              elif argparse_nargs and argparse_default:
                  configman_from_string = partial(
                      str_to_list,
                      item_converter=str_to_instance_of_type_converters.get(
                          type(argparse_default),
                          str
                      ),
                      item_separator=' ',
                  )
              elif argparse_nargs:
                  configman_from_string = partial(
                      str_to_list,
                      item_converter=str,
                      item_separator=' ',
                  )
              elif argparse_type:
                  configman_from_string = argparse_type
              elif argparse_default:
                  configman_from_string = str_to_instance_of_type_converters.get(
                      type(argparse_default),
                      str
                  )
              else:
                  configman_from_string = str
              configman_to_string = to_str
  
          #--------------------------------------------------------------------
          # STORE_CONST
          elif (
              argparse_action_name == 'store_const'
              or argparse_action_name == 'count'
          ):
              if argparse_dest is None:
                  configman_name, configman_is_argument = self._get_option_name(
                      args
                  )
                  if not configman_name:
                      configman_name = args[0]
              else:
                  configman_name = argparse_dest
              configman_default = argparse_default
              if argparse_type:
                  configman_from_string = argparse_type
              else:
                  configman_from_string = str_to_instance_of_type_converters.get(
                      type(argparse_const),
                      str
                  )
              configman_to_string = to_str
  
          #--------------------------------------------------------------------
          # STORE_TRUE /  STORE_FALSE
          elif (
              argparse_action_name == 'store_true'
              or argparse_action_name == 'store_false'
          ):
              if argparse_dest is None:
                  configman_name, configman_is_argument = self._get_option_name(
                      args
                  )
                  if not configman_name:
                      configman_name = args[0]
              else:
                  configman_name = argparse_dest
              configman_default = argparse_default
              configman_from_string = boolean_converter
              configman_to_string = to_str
  
          #--------------------------------------------------------------------
          # APPEND
          elif argparse_action_name == 'append':
              if argparse_dest is None:
                  configman_name, configman_is_argument = self._get_option_name(
                      args
                  )
                  if not configman_name:
                      configman_name = args[0]
              else:
                  configman_name = argparse_dest
              configman_default = argparse_default
              if argparse_type:
                  configman_from_string = argparse_type
              else:
                  configman_from_string = str
              configman_to_string = to_str
  
          #--------------------------------------------------------------------
          # APPEND_CONST
          elif argparse_action_name == 'append_const':
              if argparse_dest is None:
                  configman_name, configman_is_argument = self._get_option_name(
                      args
                  )
                  if not configman_name:
                      configman_name = args[0]
              else:
                  configman_name = argparse_dest
              configman_default = argparse_default
              if argparse_type:
                  configman_from_string = argparse_type
              else:
                  configman_from_string = str_to_instance_of_type_converters.get(
                      type(argparse_const),
                      str
                  )
              configman_to_string = to_str
  
          #--------------------------------------------------------------------
          # VERSION
          elif argparse_action_name == 'version':
              return an_action
  
          #--------------------------------------------------------------------
          # OTHER
          else:
              configman_name = argparse_dest
  
          # configman uses the switch name as the name of the key inwhich to
          # store values.  argparse is able to use different names for each.
          # this means that configman may encounter repeated targets.  Rather
          # than overwriting Options with new ones with the same name, configman
          # renames them by appending the '$' character.
          while configman_name in self.required_config:
              configman_name = "%s$" % configman_name
          configman_not_for_definition = configman_name.endswith('$')
  
          # it's finally time to create the configman Option object and add it
          # to the required_config.
          self.required_config.add_option(
              name=configman_name,
              default=configman_default,
              doc=configman_doc,
              from_string_converter=configman_from_string,
              to_string_converter=configman_to_string,
              #short_form=configman_short_form,
              is_argument=configman_is_argument,
              not_for_definition=configman_not_for_definition,
              # we're going to save the args & kwargs that created the
              # argparse Action.  This enables us to perfectly reproduce the
              # the original Action object later during the configman overlay
              # process.
              foreign_data=DotDict({
                  'argparse.flags.subcommand': False,
                  'argparse.args': args,
                  'argparse.kwargs': kwargs,
                  'argparse.owning_subparser_name': self.subparser_name,
              })
          )
          return an_action