From 645450d27b340439878a073c67a477bb380c15af Mon Sep 17 00:00:00 2001
From: Karen Arutyunov <karen@codesynthesis.com>
Date: Mon, 15 Feb 2021 21:46:05 +0300
Subject: Regularize step ids and introduce step id fallbacks

---
 doc/manual.cli | 52 ++++++++++++++++++++++++++++------------------------
 1 file changed, 28 insertions(+), 24 deletions(-)

(limited to 'doc')

diff --git a/doc/manual.cli b/doc/manual.cli
index c5781ae..4337627 100644
--- a/doc/manual.cli
+++ b/doc/manual.cli
@@ -784,7 +784,7 @@ values as discussed in \l{#arch-controller Controller Logic}. The
 \c{<>}-values are from the task manifest and the environment:
 
 \
-# bpkg.configure.create
+# bpkg.create
 #
 bpkg -V create <env-modules> <env-config-args> <config-args>
 
@@ -800,13 +800,13 @@ bpkg -v fetch --trust <repository-fp>
 #
 bpkg -v build --yes --configure-only <package-name>/<package-version>
 
-# bpkg.update.update
+# bpkg.update
 #
 bpkg -v update <package-name>
 
 # if the test operation is supported by the package:
 #
-# bpkg.test.test
+# bpkg.test
 #
 bpkg -v test <package-name>
 
@@ -820,11 +820,11 @@ bpkg -v test <package-name>
   bpkg -v build --yes --configure-only \\
        '<package-name> [<version-constraint>]'
 
-  # bpkg.update.update
+  # bpkg.update
   #
   bpkg -v update <package-name>
 
-  # bpkg.test.test
+  # bpkg.test
   #
   bpkg -v test <package-name>
 }
@@ -832,7 +832,7 @@ bpkg -v test <package-name>
 # if config.install.root is specified:
 #
 {
-  # bpkg.install.install
+  # bpkg.install
   #
   bpkg -v install <package-name>
 
@@ -858,15 +858,17 @@ bpkg -v test <package-name>
   # task manifest values:
   #
   {
-    # bpkg.test-installed.create
+    # bpkg.test-installed.create (fallback to bpkg.create if absent)
     #
     bpkg -V create <env-modules> <env-config-args> <config-args>
 
-    # bpkg.configure.add
+    # bpkg.test-installed.configure.add (fallback to
+    # bpkg.configure.add if absent)
     #
     bpkg -v add <repository-url>
 
-    # bpkg.configure.fetch
+    # bpkg.test-installed.configure.fetch (fallback to
+    # bpkg.configure.fetch if absent)
     #
     bpkg -v fetch --trust <repository-fp>
 
@@ -875,22 +877,24 @@ bpkg -v test <package-name>
     # test-exclude task manifest values:
     #
     {
-      # bpkg.configure.build
+      # bpkg.test-installed.configure.build (fallback to
+      # bpkg.configure.build if absent)
       #
       bpkg -v build --yes --configure-only \\
            '<package-name> [<version-constraint>]'
 
-      # bpkg.update.update
+      # bpkg.test-installed.update (fallback to bpkg.update if
+      # absent)
       #
       bpkg -v update <package-name>
 
-      # bpkg.test.test
+      # bpkg.test-installed.test (fallback to bpkg.test if absent)
       #
       bpkg -v test <package-name>
     }
   }
 
-  # bpkg.uninstall.uninstall
+  # bpkg.uninstall
   #
   bpkg -v uninstall <package-name>
 }
@@ -981,7 +985,7 @@ are ignored. All other lines in this file have the following format:
 <machine-pattern> <config> <target>[/<environment>] <classes> [<config-arg>]* [<warning-regex>]*
 
 <config-arg> = [<prefix>:](<variable>|<option>)
-<prefix> = <tool>[.<operation>[.<command>]]
+<prefix> = <tool>[.phase][.<operation>[.<command>]]
 \
 
 Where \c{<machine-pattern>} is filesystem wildcard pattern that is matched
@@ -1012,8 +1016,8 @@ manifest.
 
 Values in the \c{<config-arg>} list can be opionally prefixed with the \i{step
 id} or a leading portion thereof to restrict it to a specific step, operation,
-or tool in the \i{worked script} (see \l{#arch-worker Worker
-Logic}). Unprefixed values only apply to the \c{bpkg.configure.create},
+phase, or tool in the \i{worker script} (see \l{#arch-worker Worker
+Logic}). Unprefixed values only apply to the \c{bpkg.create},
 \c{b.test-installed.create}, and \c{bpkg.test-installed.create} steps. Note
 that options with values can only be specified using the single argument
 notation. For example:
@@ -1082,14 +1086,14 @@ linux*-gcc_8 linux-gcc_8 x86_64-linux-gnu \"all gcc-8+:gcc-7+\"
 \
 
 If the \c{<config-arg>} list contains the \c{config.install.root} variable
-that applies to the \c{bpkg.configure.create} step, then in addition to
-building and possibly running tests, the \c{bbot} worker will also test
-installing and uninstalling each package. Furthermore, if the package contains
-subprojects that support the test operation and/or refers to other packages
-via the \c{tests}, \c{examples}, or \c{benchmarks} manifest values which are
-not excluded by the \c{test-exclude} task manifest values, then the worker
-will additionally build such subprojects/packages against the installation and
-run their tests.
+that applies to the \c{bpkg.create} step, then in addition to building and
+possibly running tests, the \c{bbot} worker will also test installing and
+uninstalling each package. Furthermore, if the package contains subprojects
+that support the test operation and/or refers to other packages via the
+\c{tests}, \c{examples}, or \c{benchmarks} manifest values which are not
+excluded by the \c{test-exclude} task manifest values, then the worker will
+additionally build such subprojects/packages against the installation and run
+their tests (test installed phase).
 
 Two types of installations can be tested: \i{system} and \i{private}. A system
 installation uses a well-known location, such as \c{/usr} or \c{/usr/local},
-- 
cgit v1.1