Reorganize .cli files, add man/xhtml page generation (via script for now)

1 files changed, 179 insertions, 0 deletions

diff --git a/bpkg/common.cli b/bpkg/common.cli
new file mode 100644
index 0000000..17ee1a6
--- /dev/null
+++ b/bpkg/common.cli
@@ -0,0 +1,179 @@
+// file      : bpkg/common.cli
+// copyright : Copyright (c) 2014-2016 Code Synthesis Ltd
+// license   : MIT; see accompanying LICENSE file
+
+include <bpkg/types>;
+
+"\section=1"
+"\name=bpkg-common-options"
+"\summary=options common for all commands"
+
+namespace bpkg
+{
+  {
+    "<common-options>",
+
+    "\h|SYNOPSIS|
+
+     \c{\b{bpkg} [<common-options>] ...}
+
+     \h|DESCRIPTION|
+
+     The common options can be specified either before the command or after,
+     togethere with the command-specific options."
+  }
+
+  class common_options = 0
+  {
+    "\h|COMMON OPTIONS|"
+
+    // Retain this note only in the summary.
+    //
+    {
+      "",
+      "The common options are summarized below with a more detailed description
+       available as the \l{bpkg-common-options(1) \cb{common-options}} help
+       topic.",
+      ""
+    }
+
+    bool -v
+    {
+      "Print underlying commands being executed. This is equivalent to
+       \cb{--verbose 2}."
+    }
+
+    bool -q
+    {
+      "Run quietly, only printing error messages. This is equivalent
+       to \cb{--verbose 0}."
+    }
+
+    uint16_t --verbose = 1
+    {
+      "<level>",
+      "Set the diagnostics verbosity to <level> between 0 and 6. Level 0
+       disables any non-error messages while level 6 produces lots of
+       information, with level 1 beeing the default. The following additional
+       types of diagnostics are produced at each level:
+
+       \ol|
+
+       \li|high-level information messages|
+
+       \li|essential underlying commands that are being executed|
+
+       \li|all underlying commands that are being executed|
+
+       \li|information that could be helpful to the user|
+
+       \li|information that could be helpful to the developer|
+
+       \li|even more detailed information||"
+    }
+
+    path --build = "b"
+    {
+      "<path>",
+      "The build program to be used to build packages. This should be the path
+       to the build2 \cb{b} executable. You can also specify additional options
+       that should be passed to the build program with \cb{--build-option}. If
+       the build program is not explicitly specified, then \cb{bpkg} will use
+       \cb{b} by default."
+    }
+
+    strings --build-option
+    {
+      "<opt>",
+      "Additional option to be passed to the build program. See \cb{--build}
+       for more information on the build program. Repeat this option to specify
+       multiple build options."
+    }
+
+    path --fetch
+    {
+      "<path>",
+      "The fetch program to be used to download resources. Currently,
+       \cb{bpkg} recognizes \cb{curl}, \cb{wget}, and \cb{fetch}. Note that
+       the last component of <path> must contain one of these names as a
+       substring in order for \cb{bpkg} to recognize which program is being
+       used. You can also specify additional options that should be passed
+       to the fetch program with \cb{--fetch-option}.
+
+       If the fetch program is not specified, then \cb{bpkg} will try to
+       discover if one of the above program is available and use that.
+       Currently, \cb{bpkg} has the following preference order: \cb{wget}
+       1.16 or higher (supports \cb{--show-progress}), \cb{curl},
+       \cb{wget}, and \cb{fetch}."
+    }
+
+    strings --fetch-option
+    {
+      "<opt>",
+      "Additional option to be passed to the fetch program. See \cb{--fetch}
+       for more information on the fetch program. Repeat this option to
+       specify multiple fetch options."
+    }
+
+    path --tar = "tar"
+    {
+      "<path>",
+      "The tar program to be used to extract package archives. For example,
+       \cb{gtar} or \cb{bsdtar}. You can also specify additional options that
+       should be passed to the tar program with \cb{--tar-option}. If the tar
+       program is not explicitly specified, then \cb{bpkg} will use \cb{tar}
+       by default."
+    }
+
+    strings --tar-option
+    {
+      "<opt>",
+      "Additional option to be passed to the tar program. See \cb{--tar} for
+       more information on the tar program. Repeat this option to specify
+       multiple tar options."
+    }
+
+    string --pager // String to allow empty value.
+    {
+      "<path>",
+      "The pager program to be used to show long text. Commonly used pager
+       programs are \cb{less} and \cb{more}. You can also specify additional
+       options that should be passed to the pager program with
+       \cb{--pager-option}. If an empty string is specified as the pager
+       program, then no pager will be used. If the pager program is not
+       explicitly specified, then \cb{bpkg} will try to use \cb{less}. If it
+       is not available, then no pager will be used."
+    }
+
+    strings --pager-option
+    {
+      "<opt>",
+      "Additional option to be passed to the pager program. See \cb{--pager}
+       for more information on the pager program. Repeat this option to
+       specify multiple pager options."
+    }
+
+    // The following option is "fake" in that it is actually handled by
+    // argv_file_scanner. We have it here for documentation.
+    //
+    string --options-file
+    {
+      "<file>",
+      "Read additional options from <file>. Each option should appearing on a
+       separate line optionally followed by space and an option value. Empty
+       lines and lines starting with \cb{#} are ignored. Option values can
+       be enclosed in double (\cb{\"}) or single (\cb{'}) quotes to preserve
+       leading and trailing whitespaces as well as to specify empty values.
+       If the value itself contains trailing or leading quotes, enclose it
+       with an extra pair of quotes, for example \cb{'\"x\"'}. Non-leading
+       and non-trailing quotes are interpreted as being part of the option
+       value.
+
+       The semantics of providing options in a file is equivalent to providing
+       the same set of options in the same order on the command line at the
+       point where the \cb{--options-file} option is specified except that
+       the shell escaping and quoting is not required. You can repeat this
+       option to specify more than one options file."
+    }
+  };
+}