Style/naming cleanup in man synopsis

14 files changed, 47 insertions, 38 deletions

diff --git a/bpkg/bpkg.cli b/bpkg/bpkg.cli
index e23a059..c19138b 100644
--- a/bpkg/bpkg.cli
+++ b/bpkg/bpkg.cli
@@ -15,10 +15,10 @@ namespace bpkg
 
     "\h|SYNOPSIS|
 
-     \cb{bpkg --help}\n
-     \cb{bpkg --version}\n
-     \c{\b{bpkg help} [<command> | <topic>]}\n
-     \c{\b{bpkg} [<common-options>] <command> [<command-options>] <command-args>}
+     \c{\b{bpkg --help}\n
+        \b{bpkg --version}\n
+        \b{bpkg help} [<command> | <topic>]\n
+        \b{bpkg} [<common-options>] <command> [<command-options>] <command-args>}
 
      \h|DESCRIPTION|
 
diff --git a/bpkg/cfg-create.cli b/bpkg/cfg-create.cli
index 5c556e8..46ee97e 100644
--- a/bpkg/cfg-create.cli
+++ b/bpkg/cfg-create.cli
@@ -11,11 +11,14 @@ include <bpkg/common.cli>;
 namespace bpkg
 {
   {
-    "<options> <module> <cfg-var>",
+    "<options>
+     <cfg-args> <cfg-var> <module>",
 
     "\h|SYNOPSIS|
 
-     \c{\b{bpkg cfg-create}|\b{create} [<options>] [(<module> | <cfg-var>)...]}
+     \c{\b{bpkg cfg-create}|\b{create} [<options>] [<cfg-args>]}
+
+     \c{<cfg-args> = (<module> | <cfg-var>)...}
 
      \h|DESCRIPTION|
 
diff --git a/bpkg/pkg-build.cli b/bpkg/pkg-build.cli
index 87440a0..3c5568f 100644
--- a/bpkg/pkg-build.cli
+++ b/bpkg/pkg-build.cli
@@ -11,14 +11,18 @@ include <bpkg/configuration.cli>;
 namespace bpkg
 {
   {
-    "<options> <scheme> <pkg> <ver> <file> <dir> <pkgs> <location> <packages>",
+    "<options>
+     <pkg-spec> <scheme> <pkg> <ver>
+     <file>
+     <dir>
+     <rep-loc>",
 
     "\h|SYNOPSIS|
 
-     \c{\b{bpkg pkg-build}|\b{build} [<options>] (<packages> | [\b{@}]<location> | <file> | <dir>/)...}
+     \c{\b{bpkg pkg-build}|\b{build} [<options>] (<pkg-spec> | [\b{@}]<rep-loc> | <file> | <dir>/)...}
 
-     \c{<packages> = [<scheme>\b{:}]<pkg>[\b{/}<ver>][\b{,}...\b{@}<location>]}\n
-     \c{<scheme> \ \ = [\b{?}]\b{sys}}
+     \c{<pkg-spec> = [<scheme>\b{:}]<pkg>[\b{/}<ver>][\b{,}...\b{@}<rep-loc>]\n
+        <scheme> \ \ = [\b{?}]\b{sys}}
 
      \h|DESCRIPTION|
 
@@ -38,10 +42,10 @@ namespace bpkg
      bpkg build foo libfoo/1.2.3
      \
 
-     Alternatively, the package repository (<location>) can be specified as
-     part of the build command. In this case, if <ver> is not specified, then
-     the latest available from this repository version will be built. For
-     example:
+     Alternatively, the package repository location (<rep-loc>) can be
+     specified as part of the build command. In this case, if <ver> is not
+     specified, then the latest available from this repository version will be
+     built. For example:
 
      \
      bpkg build foo,libfoo/1.2.3@https://git.example.org/foo.git#master
diff --git a/bpkg/pkg-checkout.cli b/bpkg/pkg-checkout.cli
index 3283a3f..d671121 100644
--- a/bpkg/pkg-checkout.cli
+++ b/bpkg/pkg-checkout.cli
@@ -15,7 +15,7 @@ namespace bpkg
 
     "\h|SYNOPSIS|
 
-     \c{\b{bpkg pkg-checkout} [<options>] <pkg>/<ver>}
+     \c{\b{bpkg pkg-checkout} [<options>] <pkg>\b{/}<ver>}
 
      \h|DESCRIPTION|
 
diff --git a/bpkg/pkg-configure.cli b/bpkg/pkg-configure.cli
index d3df8d0..7db9222 100644
--- a/bpkg/pkg-configure.cli
+++ b/bpkg/pkg-configure.cli
@@ -11,7 +11,7 @@ include <bpkg/configuration.cli>;
 namespace bpkg
 {
   {
-    "<options> <pkg> <ver> <cfg-var>",
+    "<options> <pkg> <cfg-var>",
 
     "\h|SYNOPSIS|
 
diff --git a/bpkg/pkg-fetch.cli b/bpkg/pkg-fetch.cli
index 4e1dda1..213c536 100644
--- a/bpkg/pkg-fetch.cli
+++ b/bpkg/pkg-fetch.cli
@@ -15,7 +15,7 @@ namespace bpkg
 
     "\h|SYNOPSIS|
 
-     \c{\b{bpkg pkg-fetch} [<options>] (<pkg>/<ver>) | (-e <file>)}
+     \c{\b{bpkg pkg-fetch} [<options>] (<pkg>\b{/}<ver> | \b{-e} <file>)}
 
      \h|DESCRIPTION|
 
diff --git a/bpkg/pkg-status.cli b/bpkg/pkg-status.cli
index 3721262..3a346a6 100644
--- a/bpkg/pkg-status.cli
+++ b/bpkg/pkg-status.cli
@@ -15,7 +15,7 @@ namespace bpkg
 
     "\h|SYNOPSIS|
 
-     \c{\b{bpkg pkg-status}|\b{status} [<options>] <pkg>[/<ver>]...}
+     \c{\b{bpkg pkg-status}|\b{status} [<options>] <pkg>[\b{/}<ver>]...}
 
      \h|DESCRIPTION|
 
diff --git a/bpkg/pkg-unpack.cli b/bpkg/pkg-unpack.cli
index f4da2c2..c13d3dc 100644
--- a/bpkg/pkg-unpack.cli
+++ b/bpkg/pkg-unpack.cli
@@ -15,7 +15,7 @@ namespace bpkg
 
     "\h|SYNOPSIS|
 
-     \c{\b{bpkg pkg-unpack} [<options>] <pkg> | (-e <dir>)}
+     \c{\b{bpkg pkg-unpack} [<options>] (<pkg> | \b{-e} <dir>)}
 
      \h|DESCRIPTION|
 
diff --git a/bpkg/pkg-verify.cli b/bpkg/pkg-verify.cli
index 1b733c7..836791a 100644
--- a/bpkg/pkg-verify.cli
+++ b/bpkg/pkg-verify.cli
@@ -11,18 +11,18 @@ include <bpkg/common.cli>;
 namespace bpkg
 {
   {
-    "<options> <archive>",
+    "<options> <file>",
 
     "\h|SYNOPSIS|
 
-     \c{\b{bpkg pkg-verify} [<options>] <archive>}
+     \c{\b{bpkg pkg-verify} [<options>] <file>}
 
      \h|DESCRIPTION|
 
-     The \cb{pkg-verify} command verifies that the specified archive is a
-     valid \cb{bpkg} package. Specifically, it checks that the archive's name
-     and the top-level directory inside the archive match the canonical
-     '\c{\i{name}\b{-}\i{version}}' form and that there is a valid manifest
+     The \cb{pkg-verify} command verifies that the specified archive file is a
+     valid \cb{bpkg} package. Specifically, it checks that the file's name and
+     the top-level directory inside the archive match the canonical
+     \c{\i{name}\b{-}\i{version}} form and that there is a valid manifest
      file in that top-level directory."
   }
 
diff --git a/bpkg/rep-add.cli b/bpkg/rep-add.cli
index b630f0a..b566bbd 100644
--- a/bpkg/rep-add.cli
+++ b/bpkg/rep-add.cli
@@ -13,18 +13,18 @@ include <bpkg/configuration.cli>;
 namespace bpkg
 {
   {
-    "<options> <location> <tag> <branch> <commit-id>",
+    "<options> <rep-loc> <tag> <branch> <commit-id>",
 
     "\h|SYNOPSIS|
 
-     \c{\b{bpkg rep-add}|\b{add} [<options>] <location>...}
+     \c{\b{bpkg rep-add}|\b{add} [<options>] <rep-loc>...}
 
      \h|DESCRIPTION|
 
      The \cb{rep-add} command adds the specified package repositories to the
-     configuration. The repository location is a URL or a directory path. If a
-     repository with the same name already exists in the configuration, then
-     its location is replaced with the specified.
+     configuration. The repository location <rep-loc> is a URL or a directory
+     path. If a repository with the same canonical name already exists in the
+     configuration, then its location is replaced with the specified.
 
      Note that this command doesn't fetch the list of available packages for
      the newly added repository. For that, use the \l{bpkg-rep-fetch(1)}
diff --git a/bpkg/rep-fetch.cli b/bpkg/rep-fetch.cli
index 9ec1de7..ba9b879 100644
--- a/bpkg/rep-fetch.cli
+++ b/bpkg/rep-fetch.cli
@@ -11,11 +11,11 @@ include <bpkg/configuration.cli>;
 namespace bpkg
 {
   {
-    "<options> <name> <location>",
+    "<options> <rep-name> <rep-loc>",
 
     "\h|SYNOPSIS|
 
-     \c{\b{bpkg rep-fetch}|\b{fetch} [<options>] [(<name>|<location>)...]}
+     \c{\b{bpkg rep-fetch}|\b{fetch} [<options>] [(<rep-name> | <rep-loc>)...]}
 
      \h|DESCRIPTION|
 
diff --git a/bpkg/rep-info.cli b/bpkg/rep-info.cli
index 029b27b..df0eee3 100644
--- a/bpkg/rep-info.cli
+++ b/bpkg/rep-info.cli
@@ -13,11 +13,11 @@ include <bpkg/common.cli>;
 namespace bpkg
 {
   {
-    "<options> <rep>",
+    "<options> <rep-loc>",
 
     "\h|SYNOPSIS|
 
-     \c{\b{bpkg rep-info} [<options>] <rep>}
+     \c{\b{bpkg rep-info} [<options>] <rep-loc>}
 
      \h|DESCRIPTION|
 
diff --git a/bpkg/rep-remove.cli b/bpkg/rep-remove.cli
index 25280b2..09cd372 100644
--- a/bpkg/rep-remove.cli
+++ b/bpkg/rep-remove.cli
@@ -13,13 +13,15 @@ include <bpkg/configuration.cli>;
 namespace bpkg
 {
   {
-    "<options> <name> <location>",
+    "<options> <rep-name> <rep-loc>",
+
 
     "\h|SYNOPSIS|
 
-     \c{\b{bpkg rep-remove}|\b{remove} [<options>] (<name>|<location>)...}\n
-     \c{\b{bpkg rep-remove}|\b{remove} [<options>] (--all|-a)}\n
-     \c{\b{bpkg rep-remove}|\b{remove} [<options>] --clean}
+     \c{\b{bpkg rep-remove}|\b{remove} [<options>] (<rep-name>|<rep-loc>)...\n
+        \b{bpkg rep-remove}|\b{remove} [<options>] \b{--all}|\b{-a}\n
+        \b{bpkg rep-remove}|\b{remove} [<options>] \b{--clean}}
+
 
      \h|DESCRIPTION|
 
diff --git a/doc/style b/doc/style
-Subproject 658436a9522b5a0d016c3da0253708093607f95
+Subproject f9ae99d1bef56a056cbcac5a4411cfdd3e76ac3