Setup documentation infrastructure

4 files changed, 297 insertions, 0 deletions

diff --git a/bdep/bdep.cli b/bdep/bdep.cli
new file mode 100644
index 0000000..67460b0
--- /dev/null
+++ b/bdep/bdep.cli
@@ -0,0 +1,90 @@
+// file      : bdep/bdep.cli
+// copyright : Copyright (c) 2014-2017 Code Synthesis Ltd
+// license   : MIT; see accompanying LICENSE file
+
+include <bdep/common.cli>;
+
+"\section=1"
+"\name=bdep"
+"\summary=project dependency manager"
+
+namespace bdep
+{
+  {
+    "<command> <topic> <common-options> <command-options> <command-args>",
+
+    "\h|SYNOPSIS|
+
+     \cb{bdep --help}\n
+     \cb{bdep --version}\n
+     \c{\b{bdep help} [<command> | <topic>]}\n
+     \c{\b{bdep} [<common-options>] <command> [<command-options>] <command-args>}
+
+     \h|DESCRIPTION|
+
+     The \cb{build2} project dependency manager is used to @@ TODO.
+
+     For a detailed description of any command or help topic, use the
+     \cb{help} command or see the corresponding man page (the man pages have
+     the \cb{bdep-} prefix, for example \l{bdep-help(1)}). Note also that
+     <command-options> and <command-args> can be specified in any order and
+     <common-options> can be specified as part of <command-options>."
+  }
+
+  // For usage it's nice to see the list of commands on the first page. So
+  // let's not put this "extended" description into usage.
+  //
+  {
+    "",
+    "",
+
+    //@@ TODO
+    "Description...
+    "
+  }
+
+  class commands
+  {
+    "\h|COMMANDS|"
+
+    //
+    // NOTE: Use the same sentence as in the page's \summary and make
+    // sure it is short enough to fit in one line in usage.
+    //
+
+    bool help
+    {
+      "[<topic>]",
+      "\l{bdep-help(1)} \- show help for a command or help topic",
+      ""
+    }
+
+    bool init
+    {
+      "\l{bdep-init(1)} \- @@ TODO"
+    }
+  };
+
+  // Make sure these don't conflict with command names above.
+  //
+  class topics
+  {
+    "\h|HELP TOPICS|"
+
+    bool common-options
+    {
+      "\l{bdep-common-options(1)} \- details on common options"
+    }
+  };
+
+  class options: common_options
+  {
+    bool --help;
+    bool --version;
+  };
+
+  "\h|EXIT STATUS|
+
+  Non-zero exit status is returned in case of an error.
+  "
+}
diff --git a/bdep/common.cli b/bdep/common.cli
new file mode 100644
index 0000000..168233b
--- /dev/null
+++ b/bdep/common.cli
@@ -0,0 +1,148 @@
+// file      : bdep/common.cli
+// copyright : Copyright (c) 2014-2017 Code Synthesis Ltd
+// license   : MIT; see accompanying LICENSE file
+
+// @@ TODO
+//include <bdep/types.hxx>;
+
+"\section=1"
+"\name=bdep-common-options"
+"\summary=details on common options"
+
+namespace bdep
+{
+  {
+    "<common-options>",
+
+    "\h|SYNOPSIS|
+
+     \c{\b{bdep} [<common-options>] ...}
+
+     \h|DESCRIPTION|
+
+     The common options control behavior that is common to all or most of the
+     \cb{bdep} commands. They can be specified either before the command or
+     after, together 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 in \l{bdep-common-options(1)}.",
+      ""
+    }
+
+    bool -v
+    {
+      "Print essential underlying commands being executed. This is equivalent
+       to \cb{--verbose 2}."
+    }
+
+    bool -V
+    {
+      "Print all underlying commands being executed. This is equivalent to
+       \cb{--verbose 3}."
+    }
+
+    bool --quiet|-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 being the default. The following additional
+       types of diagnostics are produced at each level:
+
+       \ol|
+
+       \li|High-level information messages.|
+
+       \li|Essential underlying commands being executed.|
+
+       \li|All underlying commands 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
+    {
+      "<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{bdep} will
+       by default use \cb{b} plus an executable suffix if one was specified
+       when building \cb{bdep}. So, for example, if \cb{bdep} name was set
+       to \cb{bdep-1.0}, then it will look for \cb{b-1.0}."
+    }
+
+    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."
+    }
+
+    //@@ TODO: add --bpkg and --bpkg-option
+
+    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{bdep} 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."
+    }
+  };
+}
diff --git a/bdep/help.cli b/bdep/help.cli
new file mode 100644
index 0000000..c62a604
--- /dev/null
+++ b/bdep/help.cli
@@ -0,0 +1,30 @@
+// file      : bdep/help.cli
+// copyright : Copyright (c) 2014-2017 Code Synthesis Ltd
+// license   : MIT; see accompanying LICENSE file
+
+include <bdep/common.cli>;
+
+"\section=1"
+"\name=bdep-help"
+"\summary=show help for a command or help topic"
+
+namespace bdep
+{
+  {
+    "<command> <topic>",
+
+    "\h|SYNOPSIS|
+
+     \c{\b{bdep help} [<command> | <topic>]}
+
+     \h|DESCRIPTION|
+
+     Show the detailed help for <command> or help <topic> or a summary of
+     available commands and topics if none was specified."
+  }
+
+  class help_options: common_options
+  {
+    //"\h|HELP OPTIONS|"
+  };
+}
diff --git a/bdep/init.cli b/bdep/init.cli
new file mode 100644
index 0000000..75178f8
--- /dev/null
+++ b/bdep/init.cli
@@ -0,0 +1,29 @@
+// file      : bdep/init.cli
+// copyright : Copyright (c) 2014-2017 Code Synthesis Ltd
+// license   : MIT; see accompanying LICENSE file
+
+include <bdep/common.cli>;
+
+"\section=1"
+"\name=bdep-init"
+"\summary=@@ TODO"
+
+namespace bdep
+{
+  {
+    "<options>",
+
+    "\h|SYNOPSIS|
+
+     \c{\b{bdep init} [<options>] @@ TODO}
+
+     \h|DESCRIPTION|
+
+     The \cb{init} command..."
+  }
+
+  class init_options: common_options
+  {
+    //"\h|INIT OPTIONS|"
+  };
+}