From 81f066379a5acc53c485cc21b0d44899230745bb Mon Sep 17 00:00:00 2001
From: Boris Kolpackov <boris@codesynthesis.com>
Date: Mon, 28 Oct 2019 12:26:13 +0200
Subject: Document default options files for bdep-new command

---
 bdep/new.cli | 38 +++++++++++++++++++++++++++++++++++++-
 bdep/new.cxx |  4 ++++
 2 files changed, 41 insertions(+), 1 deletion(-)

diff --git a/bdep/new.cli b/bdep/new.cli
index 4d7c9a9..bcae7aa 100644
--- a/bdep/new.cli
+++ b/bdep/new.cli
@@ -557,7 +557,43 @@ 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{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|
 
    The \cb{BDEP_AUTHOR_EMAIL} environment variable can be used to specify the
    package email address. If not set, the \cb{new} command will first try to
diff --git a/bdep/new.cxx b/bdep/new.cxx
index 9dfd50a..4b57a8d 100644
--- a/bdep/new.cxx
+++ b/bdep/new.cxx
@@ -2180,6 +2180,8 @@ namespace bdep
   default_options_files
   options_files (const char*, const cmd_new_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
@@ -2255,6 +2257,8 @@ namespace bdep
   merge_options (const default_options<cmd_new_options>& defs,
                  const cmd_new_options& cmd)
   {
+    // NOTE: remember to update the documentation if changing anything here.
+
     // While validating/merging the default options, check for the "remote"
     // hooks presence and prepare the prompt, if that's the case.
     //
-- 
cgit v1.1