docs: def create_argument_parser():
      """
      Command line options and arguments parsing. This function return
      a list of options and the list of arguments (pattern, filenames).
      """
      parser = argparse.ArgumentParser(prog='lograptor', description=__description__, add_help=False)
      parser.usage = """%(prog)s [options] PATTERN [FILE ...]
      %(prog)s [options] [-e PATTERN | -f FILE] [FILE ...]
      Try '%(prog)s --help' for more information."""
  
      group = parser.add_argument_group("General Options")
      group.add_argument(
          "--conf", dest="cfgfiles", action='append', default=None, metavar="FILE",
          help="use a specific configuration file"
      )
      group.add_argument(
          "-d", dest="loglevel", default=2, type=int, metavar="[0-4]", choices=range(5),
          help="Logging level (default is 2, use 4 for debug). A level of 0 suppress also "
               "error messages about nonexistent or unreadable files."
      )
      group.add_argument('-V', '--version', action='version', version=__version__)
      group.add_argument('--help', action='help', help="show this help message and exit")
  
      group = parser.add_argument_group("Scope Selection")
      group.add_argument(
          "-a", "--apps", metavar='APP[,APP...]', type=comma_separated_string,
          default=[], help="process the log lines related to a list of applications"
      )
      group.add_argument(
          "--hosts", metavar="HOSTNAME/IP[,HOSTNAME/IP...]", type=comma_separated_string,
          default=[], help="process the log lines related to an hostname/IP"
      )
      group.add_argument(
          "-F", "--filter", metavar="FIELD=PATTERN[,FIELD=PATTERN...]",
          action="append", dest="filters", type=filter_spec, default=[],
          help="process the log lines that match all the conditions for rule's field values"
      )
      group.add_argument(
          "--time", metavar="HH:MM,HH:MM", type=TimeRange, action="store", dest="time_range",
          help="process the log lines related to a time range"
      )
      group.add_argument(
          "--date", metavar="[YYYY]MMDD[,[YYYY]MMDD]", action="store", dest="time_period",
          type=date_interval_spec, help="restrict the search scope to a date or a date interval"
      )
      group.add_argument(
          "--last", action="store", dest="time_period", type=last_period_spec,
          metavar="[hour|day|week|month|Nh|Nd|Nw|Nm]",
          help="restrict the search scope to a previous time period"
      )
  
      group = parser.add_argument_group("Matcher Selection")
      group.add_argument(
          "-G", "--ruled", dest='matcher', action=StoreOptionAction,
          help="use patterns and application rules (default)"
      )
      group.add_argument(
          "-X", "--unruled", dest='matcher', action=StoreOptionAction,
          help="use patterns only, skip application rules"
      )
      group.add_argument(
          "-U", "--unparsed", dest='matcher', action=StoreOptionAction,
          help="match the patterns, don't match any application rule"
      )
  
      group = parser.add_argument_group("Matching Control")
      group.add_argument(
          "-e", "--regexp", metavar="PATTERN", dest="patterns", default=[],
          action="append", help="use PATTERN for matching"
      )
      group.add_argument(
          "-f", "--file", metavar="FILE", dest="pattern_files", default=[],
          action="append", help="obtain patterns from FILE"
      )
      group.add_argument(
          "-i", "--ignore-case", action="store_true", dest="case", default=False,
          help="ignore case distinctions"
      )
      group.add_argument(
          "-v", "--invert-match", action="store_true", dest="invert", default=False,
          help="invert the sense of patterns regexp matching"
      )
      group.add_argument(
          "-w", "--word-regexp", action="store_true", dest="word", default=False,
          help="force PATTERN to match only whole words"
      )
  
      group = parser.add_argument_group("General Output Control")
      group.add_argument(
          "--output", default=['stdout'], metavar='CHANNEL[,CHANNEL...]', dest='channels',
          type=comma_separated_string, help="send output to channels (default: ['stdout'])"
      )
      group.add_argument(
          "-c", "--count", action="store_true", default=False,
          help="print only a count of matching lines per FILE"
      )
      group.add_argument(
          "--color", default='auto', nargs='?', choices=['auto', 'always', 'never'],
          help="use markers to highlight the matching strings"
      )
      group.add_argument(
          "-L", "--files-without-match", action="store_false", dest="files_with_match", default=None,
          help="print only names of FILEs containing no match"
      )
      group.add_argument(
          "-l", "--files-with-match", action="store_true", dest="files_with_match",
          help="print only names of FILEs containing matches"
      )
      group.add_argument(
          "-m", "--max-count", metavar='NUM', action="store", type=positive_integer, default=0,
          help="stop after NUM matches"
      )
      group.add_argument(
          "-o", "--only-matching", action="store_true", default=False,
          help="show only the part of a line matching PATTERN"
      )
      group.add_argument(
          "-q", "--quiet", action="store_true", default=False, help="suppress all normal output"
      )
      group.add_argument(
          "-s", "--no-messages", action="store_const", const=0, dest='loglevel',
          help="suppress error messages (equivalent to -d 0)"
      )
  
      group = parser.add_argument_group("Output Data Control")
      group.add_argument(
          "--report", metavar='NAME', nargs='?', default=False,
          help="produce a report at the end of processing"
      )
      group.add_argument(
          "--ip-lookup", action="store_true", default=False,
          help="translate IP addresses to DNS names"
      )
      group.add_argument(
          "--uid-lookup", action="store_true", default=False,
          help="translate UIDs to usernames"
      )
      group.add_argument(
          "--anonymize", action="store_true", default=False,
          help="anonymize defined rule's fields value"
      )
  
      group = parser.add_argument_group("Output Line Prefix Control")
      group.add_argument(
          "-n", "--line-number", action="store_true", default=False,
          help="print line number with output lines"
      )
      group.add_argument(
          "-H", "--with-filename", action="store_true", dest="with_filename", default=None,
          help="print the file name for each match"
      )
      group.add_argument(
          "-h", "--no-filename", action="store_false", dest="with_filename", default=None,
          help="suppress the file name prefix on output"
      )
  
      group = parser.add_argument_group("Context Line Control")
      group.add_argument(
          "-T", "--thread", action="store_true", default=False,
          help="the context is the log thread of the application"
      )
      group.add_argument(
          "-B", "--before-context", metavar='NUM', type=positive_integer, default=0,
          help="print NUM lines of leading context"
      )
      group.add_argument(
          "-A", "--after-context", metavar='NUM', type=positive_integer, default=0,
          help="print NUM lines of trailing context"
      )
      group.add_argument(
          "-C", "--context", metavar='NUM', type=positive_integer, default=0,
          help="print NUM lines of output context"
      )
      group.add_argument(
          "--group-separator", metavar='SEP', default='--',
          help="use SEP as a group separator. By default SEP is double hyphen (--)."
      )
      group.add_argument(
          "--no-group-separator", dest="group_separator", action="store_const", const='',
          help="use empty string as a group separator"
      )
  
      group = parser.add_argument_group("File and Directory Selection")
      group.add_argument(
          "-r", "--recursive", action="store_true", default=False,
          help="read all files under each directory, recursively"
      )
      group.add_argument(
          "-R", "--dereference-recursive", action="store_true", default=False,
          help="likewise, but follow all symlinks"
      )
      group.add_argument(
          "--include", metavar='GLOB', default=[], action="append",
          help="search only files that match GLOB"
      )
      group.add_argument(
          "--exclude", metavar='GLOB', default=[], action="append",
          help="skip files and directories matching GLOB"
      )
      group.add_argument(
          "--exclude-from", metavar='FILE', default=[], action="append",
          help="skip files matching any file pattern from FILE"
      )
      group.add_argument(
          "--exclude-dir", metavar='DIR', default=[], action="append",
          help="exclude directories matching the pattern DIR"
      )
  
      parser.add_argument(
          'files', metavar='[FILE ...]', nargs='*',
          help='Input files. Each argument can be a file path or a glob pathname. '
               'A "-" stands for standard input. If no arguments are given then processes '
               'all the files included within the scope of the selected applications.'
      )
      return parser