Documentation improvements

1 files changed, 21 insertions, 15 deletions

diff --git a/bpkg/pkg-verify.cli b/bpkg/pkg-verify.cli
index 850b7d4..534b98e 100644
--- a/bpkg/pkg-verify.cli
+++ b/bpkg/pkg-verify.cli
@@ -6,35 +6,41 @@ include <bpkg/common.cli>;
 
 "\section=1"
 "\name=bpkg-pkg-verify"
-"\summary=verify archive is a valid package"
+"\summary=verify package archive"
 
-/*
-"\h{SYNOPSIS}
+namespace bpkg
+{
+  {
+    "<options> <archive>",
 
-bpkg pkg-verify <archive>"
+    "\h|SYNOPSIS|
 
-"\h{DESCRIPTION}
+     \c{\b{bpkg pkg-verify} [<options>] <archive>}
 
-The \cb{pkg-verify} command verifies that the specified archive is a
-valid \cb{bpkg} package. Specifically, it checks that the archive
-contains a valid manifest file and that both the archive's name
-and its top-level directory match the canonical <name>-<version>
-form."
-*/
+     \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
+     file in that top-level directory."
+  }
 
-namespace bpkg
-{
   class pkg_verify_options: common_options
   {
+    "\h|PKG-VERIFY OPTIONS|"
+
     bool --silent
     {
-      "Suppress error messages about the reason why the package is
+      "Suppress the error messages about the reason why the package is
        invalid. Just return the error status."
     }
 
     bool --ignore-unknown
     {
-      "Ignore unknown manifest entries."
+      "Ignore unknown manifest entries. By default, \cb{bpkg} will refuse to
+       declare such a package validate since it cannot be sure the unknown
+       entries are valid."
     }
   };
 }