+ * Options and positional arguments can be mixed arbitrarily. When a `--` appears
+ * as an argument, it is understood as a signal that all other arguments are
+ * positional.
+ *
+ * `OPT_REQUIRED` can be used with positional arguments, but all required arguments
+ * must come before the non-required ones. When `OPT_POSITIONAL_TAIL` is declared
+ * required, it means that it must match at least once.
+ *
+ * Ordering of positional arguments within the list of options need not match
+ * their positions. Holes in position numbering are inadvisable.
+ ***/
+
+#define OPT_POSITIONAL(n) (OPT_POSITIONAL_TAIL+(n))
+#define OPT_POSITIONAL_TAIL 128
+
+/***
+ * [[func]]
+ * Functions
+ * ---------
+ ***/
+
+/**
+ * Parse all arguments, given in a NULL-terminated array of strings.
+ *
+ * Typically, this is called from `main(argc, argv)` as `opt_parse(options, argv+1)`,
+ * skipping the 0th argument, which contains program name.
+ *
+ * Returns the number of arguments used (which need not be all of them
+ * if `OPT_LAST_ARG` was encountered).
+ *
+ * The argument array is left untouched.
+ * However, option values are not necessarily copied, the variables
+ * set by the parser may point to the argument array.
+ **/
+int opt_parse(const struct opt_section * options, char ** argv);
+
+/**
+ * Report parsing failure, suggest `--help`, and abort the program with
+ * exit code 2.
+ **/
+void opt_failure(const char * mesg, ...) FORMAT_CHECK(printf,1,2) NONRET;
+
+void opt_help(const struct opt_section * sec);
+void opt_handle_help(struct opt_item * opt, const char * value, void * data);
+
+/***
+ * [[conf]]
+ * Cooperating with config file parser
+ * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ *
+ * Parsing of command-line options and configuration files are usually
+ * intertwined in a somewhat tricky way. We want to provide command-line
+ * options that control the name of the configuration file, or possibly to
+ * override configuration settings from the command line. On the other hand,
+ * regular command-line options can refer to values loaded from the
+ * program's configuration.
+ *
+ * To achieve this goal, the option parser is able to cooperate with the
+ * config file parser. This is enabled by listing the `OPT_CONF_OPTIONS`
+ * macro in the list of command-line options.
+ *
+ * The following options are defined for you:
+ *
+ * - `-C` (`--config`) to load a specific configuration file. This option
+ * suppresses loading of the default configuration, but it can be given
+ * multiple times to merge settings from several files.
+ *
+ * - `-S` (`--set`) to include a part of configuration inline. For example,
+ * you can use `-Ssection.item=value` to change a single configuration item.
+ *
+ * - `--dumpconfig` to dump the configuration to standard output and exit.
+ * (This is available only if the program is compiled with `CONFIG_UCW_DEBUG`.)
+ *
+ * The default configuration file (as specified by <<var_cf_def_file,`cf_def_file`>>) is loaded
+ * as soon as the first option different from `-C` is encountered, unless
+ * a different file has been already loaded. For this reason, `-C` must be
+ * the very first argument given to the program.
+ *
+ * This interface supersedes <<conf:getopt_h,`cf_getopt()`>>.