Document default options files for remaining commands

22 files changed, 344 insertions, 38 deletions

diff --git a/bdep/.gitignore b/bdep/.gitignore
index 97e4d6d..b8da6c9 100644
--- a/bdep/.gitignore
+++ b/bdep/.gitignore
@@ -3,6 +3,7 @@ bdep
 *-odb.?xx
 *-options.?xx
 projects-configs.?xx
+default-options-files.?xx
 version.hxx
 
 # Testscript output directory (can be symlink).
diff --git a/bdep/buildfile b/bdep/buildfile
index 7a14c51..7828fa6 100644
--- a/bdep/buildfile
+++ b/bdep/buildfile
@@ -36,7 +36,7 @@ test-options      \
 update-options    \
 clean-options
 
-help_topics = projects-configs
+help_topics = projects-configs default-options-files
 
 ./: exe{bdep}: {hxx ixx txx cxx}{+bdep} libue{bdep}
 
@@ -125,7 +125,8 @@ if $cli.configured
 
   # Help topics.
   #
-  cli.cxx{projects-configs}: cli{projects-configs}
+  cli.cxx{projects-configs}:      cli{projects-configs}
+  cli.cxx{default-options-files}: cli{default-options-files}
 
   # Option length must be the same to get commands/topics/options aligned.
   #
@@ -153,7 +154,8 @@ if $cli.configured
 
   # Avoid generating CLI runtime and empty inline file for help topics.
   #
-  cli.cxx{projects-configs}: cli.options += --suppress-cli --suppress-inline
+  cli.cxx{projects-configs}:      cli.options += --suppress-cli --suppress-inline
+  cli.cxx{default-options-files}: cli.options += --suppress-cli --suppress-inline
 
   # Include the generated cli files into the distribution and don't remove
   # them when cleaning in src (so that clean results in a state identical to
diff --git a/bdep/ci.cli b/bdep/ci.cli
index ccf6ed3..ed51f01 100644
--- a/bdep/ci.cli
+++ b/bdep/ci.cli
@@ -157,4 +157,25 @@ namespace bdep
        documentation."
     }
   };
+
+  "
+   \h|DEFAULT OPTIONS FILES|
+
+   See \l{bdep-default-options-files(1)} for an overview of the default
+   options files. For the \cb{ci} command the search start directory is
+   the project directory. The following options files are searched for in
+   each directory and, if found, loaded in the order listed:
+
+   \
+   bdep.options
+   bdep-ci.options
+   \
+
+   The following \cb{ci} command options cannot be specified in the
+   default options files:
+
+   \
+   --directory|-d
+   \
+  "
 }
diff --git a/bdep/clean.cli b/bdep/clean.cli
index 999722f..24460df 100644
--- a/bdep/clean.cli
+++ b/bdep/clean.cli
@@ -46,4 +46,25 @@ namespace bdep
   {
     "\h|CLEAN OPTIONS|"
   };
+
+  "
+   \h|DEFAULT OPTIONS FILES|
+
+   See \l{bdep-default-options-files(1)} for an overview of the default
+   options files. For the \cb{clean} command the search start directory is
+   the project directory. The following options files are searched for in
+   each directory and, if found, loaded in the order listed:
+
+   \
+   bdep.options
+   bdep-clean.options
+   \
+
+   The following \cb{clean} command options cannot be specified in the
+   default options files:
+
+   \
+   --directory|-d
+   \
+  "
 }
diff --git a/bdep/config.cli b/bdep/config.cli
index 818f600..5481bae 100644
--- a/bdep/config.cli
+++ b/bdep/config.cli
@@ -164,4 +164,29 @@ namespace bdep
   {
     "\h|CONFIG OPTIONS|"
   };
+
+
+  "
+   \h|DEFAULT OPTIONS FILES|
+
+   See \l{bdep-default-options-files(1)} for an overview of the default
+   options files. For the \cb{config} command the search start directory is
+   the project directory. The following options files are searched for in
+   each directory and, if found, loaded in the order listed:
+
+   \
+   bdep.options
+   bdep-config.options
+   bdep-config-add.options          # if the create subcommand
+   bdep-config-<subcommand>.options # (subcommand-dependent)
+   \
+
+   The following \cb{config} command options cannot be specified in the
+   default options files:
+
+   \
+   --directory|-d
+   --wipe
+   \
+  "
 }
diff --git a/bdep/config.cxx b/bdep/config.cxx
index f08bd41..ee5f9df 100644
--- a/bdep/config.cxx
+++ b/bdep/config.cxx
@@ -799,6 +799,8 @@ namespace bdep
                  const cmd_config_options& o,
                  const strings& args)
   {
+    // NOTE: remember to update the documentation if changing anything here.
+
     // bdep.options
     // bdep-config.options
     // bdep-config-<subcmd>.options
@@ -841,6 +843,8 @@ namespace bdep
   merge_options (const default_options<cmd_config_options>& defs,
                  const cmd_config_options& cmd)
   {
+    // NOTE: remember to update the documentation if changing anything here.
+
     return merge_default_options (
       defs,
       cmd,
diff --git a/bdep/deinit.cli b/bdep/deinit.cli
index ad7e626..cd14fec 100644
--- a/bdep/deinit.cli
+++ b/bdep/deinit.cli
@@ -49,4 +49,25 @@ namespace bdep
        directory has been removed or is otherwise unusable."
     }
   };
+
+  "
+   \h|DEFAULT OPTIONS FILES|
+
+   See \l{bdep-default-options-files(1)} for an overview of the default
+   options files. For the \cb{deinit} command the search start directory is
+   the project directory. The following options files are searched for in
+   each directory and, if found, loaded in the order listed:
+
+   \
+   bdep.options
+   bdep-deinit.options
+   \
+
+   The following \cb{deinit} command options cannot be specified in the
+   default options files:
+
+   \
+   --directory|-d
+   \
+  "
 }
diff --git a/bdep/fetch.cli b/bdep/fetch.cli
index acbb360..7d4d001 100644
--- a/bdep/fetch.cli
+++ b/bdep/fetch.cli
@@ -50,4 +50,25 @@ namespace bdep
       "Perform a full re-fetch of all the repositories."
     }
   };
+
+  "
+   \h|DEFAULT OPTIONS FILES|
+
+   See \l{bdep-default-options-files(1)} for an overview of the default
+   options files. For the \cb{fetch} command the search start directory is
+   the project directory. The following options files are searched for in
+   each directory and, if found, loaded in the order listed:
+
+   \
+   bdep.options
+   bdep-fetch.options
+   \
+
+   The following \cb{fetch} command options cannot be specified in the
+   default options files:
+
+   \
+   --directory|-d
+   \
+  "
 }
diff --git a/bdep/help.cli b/bdep/help.cli
index 238a730..c6aa1ab 100644
--- a/bdep/help.cli
+++ b/bdep/help.cli
@@ -27,4 +27,18 @@ namespace bdep
   {
     //"\h|HELP OPTIONS|"
   };
+
+  "
+   \h|DEFAULT OPTIONS FILES|
+
+   See \l{bdep-default-options-files(1)} for an overview of the default
+   options files. For the \cb{help} command the following options files are
+   searched for only in the predefined directories (home, system, etc) and, if
+   found, loaded in the order listed:
+
+   \
+   bdep.options
+   bdep-help.options
+   \
+  "
 }
diff --git a/bdep/help.cxx b/bdep/help.cxx
index fe64c2a..4175b89 100644
--- a/bdep/help.cxx
+++ b/bdep/help.cxx
@@ -12,6 +12,7 @@
 // Help topics.
 //
 #include <bdep/projects-configs.hxx>
+#include <bdep/default-options-files.hxx>
 
 using namespace std;
 using namespace butl;
@@ -32,6 +33,8 @@ namespace bdep
         usage = &print_bdep_common_options_long_usage;
       else if (t == "projects-configs")
         usage = &print_bdep_projects_configs_usage;
+      else if (t == "default-options-files")
+        usage = &print_bdep_default_options_files_usage;
       else
         fail << "unknown bdep command/help topic '" << t << "'" <<
           info << "run 'bdep help' for more information";
diff --git a/bdep/init.cli b/bdep/init.cli
index 5071913..32024eb 100644
--- a/bdep/init.cli
+++ b/bdep/init.cli
@@ -174,4 +174,30 @@ namespace bdep
        an explicit \l{bdep-sync(1)} command."
     }
   };
+
+  "
+   \h|DEFAULT OPTIONS FILES|
+
+   See \l{bdep-default-options-files(1)} for an overview of the default
+   options files. For the \cb{init} command the search start directory is the
+   project directory. The following options files are searched for in each
+   directory and, if found, loaded in the order listed:
+
+   \
+   bdep.options
+   bdep-{config config-add}.options                # if --config-add|-A
+   bdep-{config config-add config-create}.options  # if --config-create|-C
+   bdep-init.options
+   \
+
+   The following \cb{init} command options cannot be specified in the
+   default options files:
+
+   \
+   --directory|-d
+   --config-add|-A
+   --config-create|-C
+   --wipe
+   \
+  "
 }
diff --git a/bdep/init.cxx b/bdep/init.cxx
index 86f570f..5bc6a72 100644
--- a/bdep/init.cxx
+++ b/bdep/init.cxx
@@ -278,6 +278,8 @@ namespace bdep
   default_options_files
   options_files (const char*, const cmd_init_options& o, const strings&)
   {
+    // NOTE: remember to update the documentation if changing anything here.
+
     // bdep.options
     // bdep-{config config-add}.options               # -A
     // bdep-{config config-add config-create}.options # -C
@@ -308,6 +310,8 @@ namespace bdep
   merge_options (const default_options<cmd_init_options>& defs,
                  const cmd_init_options& cmd)
   {
+    // NOTE: remember to update the documentation if changing anything here.
+
     return merge_default_options (
       defs,
       cmd,
diff --git a/bdep/new.cli b/bdep/new.cli
index e338683..259a4df 100644
--- a/bdep/new.cli
+++ b/bdep/new.cli
@@ -575,37 +575,37 @@ namespace bdep
   "
    \h|DEFAULT OPTIONS FILES|
 
-    See \l{bdep-default-options-files(1)} for an overview of the default
-    options files. For the \cb{new} command the search start directory is the
-    project directory in the package and subdirectory modes and the parent
-    directory of the new project in all other modes. The following options
-    files are searched for in each directory and, if found, loaded in the
-    order listed:
-
-    \
-    bdep.options
-    bdep-{config config-add}.options                # if --config-add|-A
-    bdep-{config config-add config-create}.options  # if --config-create|-C
-    bdep-new.options
-    bdep-new-{project|package|subdirectory}.options # (mode-dependent)
-    \
-
-    The following \cb{new} command options cannot be specified in the
-    default options files:
-
-    \
-    --output-dir|-o
-    --directory|-d
-    --package
-    --subdirectory
-    --no-checks
-    --config-add|-A
-    --config-create|-C
-    --wipe
-    \
-
-    While the presence of the \cb{--pre-hook} or \cb{--post-hook} options in
-    remote default options files will trigger a prompt.
+   See \l{bdep-default-options-files(1)} for an overview of the default
+   options files. For the \cb{new} command the search start directory is the
+   project directory in the package and subdirectory modes and the parent
+   directory of the new project in all other modes. The following options
+   files are searched for in each directory and, if found, loaded in the
+   order listed:
+
+   \
+   bdep.options
+   bdep-{config config-add}.options                # if --config-add|-A
+   bdep-{config config-add config-create}.options  # if --config-create|-C
+   bdep-new.options
+   bdep-new-{project|package|subdirectory}.options # (mode-dependent)
+   \
+
+   The following \cb{new} command options cannot be specified in the
+   default options files:
+
+   \
+   --output-dir|-o
+   --directory|-d
+   --package
+   --subdirectory
+   --no-checks
+   --config-add|-A
+   --config-create|-C
+   --wipe
+   \
+
+   While the presence of the \cb{--pre-hook} or \cb{--post-hook} options in
+   remote default options files will trigger a prompt.
 
 
    \h|ENVIRONMENT|
diff --git a/bdep/publish.cli b/bdep/publish.cli
index 1d3771c..0a3eafb 100644
--- a/bdep/publish.cli
+++ b/bdep/publish.cli
@@ -151,7 +151,28 @@ namespace bdep
     }
   };
 
-  "\h|ENVIRONMENT|
+  "
+   \h|DEFAULT OPTIONS FILES|
+
+   See \l{bdep-default-options-files(1)} for an overview of the default
+   options files. For the \cb{publish} command the search start directory is
+   the project directory. The following options files are searched for in
+   each directory and, if found, loaded in the order listed:
+
+   \
+   bdep.options
+   bdep-publish.options
+   \
+
+   The following \cb{publish} command options cannot be specified in the
+   default options files:
+
+   \
+   --directory|-d
+   \
+
+
+   \h|ENVIRONMENT|
 
    The \cb{BDEP_AUTHOR_NAME} and \cb{BDEP_AUTHOR_EMAIL} environment variables
    can be used to specify the publisher's name and email address,
diff --git a/bdep/release.cli b/bdep/release.cli
index b20edb1..44d339a 100644
--- a/bdep/release.cli
+++ b/bdep/release.cli
@@ -237,4 +237,29 @@ namespace bdep
        current working directory."
     }
   };
+
+  "
+   \h|DEFAULT OPTIONS FILES|
+
+   See \l{bdep-default-options-files(1)} for an overview of the default
+   options files. For the \cb{release} command the search start directory is
+   the project directory. The following options files are searched for in
+   each directory and, if found, loaded in the order listed:
+
+   \
+   bdep.options
+   bdep-release.options
+   bdep-release-{version|revision|open|tag}.options # (mode-dependent)
+   \
+
+   The following \cb{release} command options cannot be specified in the
+   default options files:
+
+   \
+   --directory|-d
+   --revision
+   --open
+   --tag
+   \
+  "
 }
diff --git a/bdep/release.cxx b/bdep/release.cxx
index 08cc61e..abb3784 100644
--- a/bdep/release.cxx
+++ b/bdep/release.cxx
@@ -1321,9 +1321,11 @@ namespace bdep
   default_options_files
   options_files (const char*, const cmd_release_options& o, const strings&)
   {
+    // NOTE: remember to update the documentation if changing anything here.
+
     // bdep.options
     // bdep-release.options
-    // bdep-release{version|revision|open|tag}.options
+    // bdep-release-{version|revision|open|tag}.options
 
     default_options_files r {
       {path ("bdep.options"), path ("bdep-release.options")},
@@ -1343,6 +1345,8 @@ namespace bdep
   merge_options (const default_options<cmd_release_options>& defs,
                  const cmd_release_options& cmd)
   {
+    // NOTE: remember to update the documentation if changing anything here.
+
     return merge_default_options (
       defs,
       cmd,
diff --git a/bdep/status.cli b/bdep/status.cli
index 422dbe6..8960277 100644
--- a/bdep/status.cli
+++ b/bdep/status.cli
@@ -79,4 +79,25 @@ namespace bdep
       "Perform the \cb{fetch --full} command prior to printing the status."
     }
   };
+
+  "
+   \h|DEFAULT OPTIONS FILES|
+
+   See \l{bdep-default-options-files(1)} for an overview of the default
+   options files. For the \cb{status} command the search start directory is
+   the project directory. The following options files are searched for in
+   each directory and, if found, loaded in the order listed:
+
+   \
+   bdep.options
+   bdep-status.options
+   \
+
+   The following \cb{status} command options cannot be specified in the
+   default options files:
+
+   \
+   --directory|-d
+   \
+  "
 }
diff --git a/bdep/sync.cli b/bdep/sync.cli
index 04b8330..f4afc85 100644
--- a/bdep/sync.cli
+++ b/bdep/sync.cli
@@ -222,7 +222,32 @@ namespace bdep
     uint16_t --hook = 0;
   };
 
-  "\h|ENVIRONMENT|
+  "
+   \h|DEFAULT OPTIONS FILES|
+
+   See \l{bdep-default-options-files(1)} for an overview of the default
+   options files. For the \cb{sync} command the search start directory is the
+   project directory, except for the implicit mode for which only the
+   predefined directories (system, etc) are searched in. The following options
+   files are searched for in each directory and, if found, loaded in the order
+   listed:
+
+   \
+   bdep.options
+   bdep-{sync|sync-implicit}.options # (mode-dependent)
+   \
+
+   The following \cb{sync} command options cannot be specified in the
+   default options files:
+
+   \
+   --directory|-d
+   --implicit
+   --config|-c
+   \
+
+
+   \h|ENVIRONMENT|
 
    The \cb{BDEP_SYNC} environment variable can be used to suppress automatic
    synchronization on build system invocation. If set, auto-synchronization
diff --git a/bdep/sync.cxx b/bdep/sync.cxx
index 1ed3c12..4084572 100644
--- a/bdep/sync.cxx
+++ b/bdep/sync.cxx
@@ -900,6 +900,8 @@ namespace bdep
   default_options_files
   options_files (const char*, const cmd_sync_options& o, const strings&)
   {
+    // NOTE: remember to update the documentation if changing anything here.
+
     // bdep.options
     // bdep-{sync|sync-implicit}.options
 
@@ -934,6 +936,8 @@ namespace bdep
   merge_options (const default_options<cmd_sync_options>& defs,
                  const cmd_sync_options& cmd)
   {
+    // NOTE: remember to update the documentation if changing anything here.
+
     return merge_default_options (
       defs,
       cmd,
diff --git a/bdep/test.cli b/bdep/test.cli
index 4b6349f..58d7764 100644
--- a/bdep/test.cli
+++ b/bdep/test.cli
@@ -62,4 +62,25 @@ namespace bdep
       "Also test all dependencies, recursively."
     }
   };
+
+  "
+   \h|DEFAULT OPTIONS FILES|
+
+   See \l{bdep-default-options-files(1)} for an overview of the default
+   options files. For the \cb{test} command the search start directory is
+   the project directory. The following options files are searched for in
+   each directory and, if found, loaded in the order listed:
+
+   \
+   bdep.options
+   bdep-test.options
+   \
+
+   The following \cb{test} command options cannot be specified in the
+   default options files:
+
+   \
+   --directory|-d
+   \
+  "
 }
diff --git a/bdep/update.cli b/bdep/update.cli
index 3868a0a..83b1b79 100644
--- a/bdep/update.cli
+++ b/bdep/update.cli
@@ -46,4 +46,25 @@ namespace bdep
   {
     "\h|UPDATE OPTIONS|"
   };
+
+  "
+   \h|DEFAULT OPTIONS FILES|
+
+   See \l{bdep-default-options-files(1)} for an overview of the default
+   options files. For the \cb{update} command the search start directory is
+   the project directory. The following options files are searched for in
+   each directory and, if found, loaded in the order listed:
+
+   \
+   bdep.options
+   bdep-update.options
+   \
+
+   The following \cb{update} command options cannot be specified in the
+   default options files:
+
+   \
+   --directory|-d
+   \
+  "
 }
diff --git a/doc/cli.sh b/doc/cli.sh
index 3ba95b9..e331e4f 100755
--- a/doc/cli.sh
+++ b/doc/cli.sh
@@ -63,7 +63,8 @@ o="--suppress-undocumented --output-prefix bdep- --class-doc bdep::common_option
 compile "common" $o --output-suffix "-options" --class-doc bdep::common_options=long
 compile "bdep" $o --output-prefix "" --class-doc bdep::commands=short --class-doc bdep::topics=short
 
-# NOTE: remember to update a similar list in buildfile as well as in bdep.cli.
+# NOTE: remember to update a similar list in buildfile and bdep.cli as well as
+# the help topics sections in bdep/buildfile and help.cxx.
 #
 pages="new help init sync fetch status ci release publish deinit config test \
 update clean projects-configs default-options-files"