Document package-description* and changes-type manifest values and adapt testscript to new values

3 files changed, 102 insertions, 65 deletions

diff --git a/bpkg/rep-fetch.cxx b/bpkg/rep-fetch.cxx
index 17536da..6f31478 100644
--- a/bpkg/rep-fetch.cxx
+++ b/bpkg/rep-fetch.cxx
@@ -481,25 +481,35 @@ namespace bpkg
 
         // Load *-file values.
         //
-        m.load_files (
-          [ev, &rd, &rl, &pl]
-          (const string& n, const path& p) -> optional<string>
-          {
-            // Always expand the build-file values.
-            //
-            if (ev || n == "build-file")
+        try
+        {
+          m.load_files (
+            [ev, &rd, &rl, &pl]
+            (const string& n, const path& p) -> optional<string>
             {
-              return read_package_file (p,
-                                        n,
-                                        pl,
-                                        rd,
-                                        rl,
-                                        empty_string /* fragment */);
-            }
-            else
-              return nullopt;
-          },
-          iu);
+              // Always expand the build-file values.
+              //
+              if (ev || n == "build-file")
+              {
+                return read_package_file (p,
+                                          n,
+                                          pl,
+                                          rd,
+                                          rl,
+                                          empty_string /* fragment */);
+              }
+              else
+                return nullopt;
+            },
+            iu);
+        }
+        catch (const manifest_parsing& e)
+        {
+          diag_record dr (fail);
+          dr << e << info;
+          print_package_info (dr, pl, rl, nullopt /* fragment */);
+          dr << endf;
+        }
 
         // Load the bootstrap, root, and config/*.build buildfiles into the
         // respective *-build values, if requested and if they are not already
@@ -679,38 +689,49 @@ namespace bpkg
 
           // Load *-file values.
           //
-          m.load_files (
-            [ev, &td, &rl, &pl, &fr, &checkout_submodules]
-            (const string& n, const path& p) -> optional<string>
-            {
-              // Always expand the build-file values.
-              //
-              if (ev || n == "build-file")
+          try
+          {
+            m.load_files (
+              [ev, &td, &rl, &pl, &fr, &checkout_submodules]
+              (const string& n, const path& p) -> optional<string>
               {
-                // Check out submodules if the referenced file doesn't exist.
-                //
-                // Note that this doesn't work for symlinks on Windows where
-                // git normally creates filesystem-agnostic symlinks that are
-                // indistinguishable from regular files (see fixup_worktree()
-                // for details). It seems like the only way to deal with that
-                // is to unconditionally checkout submodules on Windows. Let's
-                // not pessimize things for now (if someone really wants this
-                // to work, they can always enable real symlinks in git).
+                // Always expand the build-file values.
                 //
-                if (!exists (td / pl / p))
-                  checkout_submodules ();
-
-                return read_package_file (p,
-                                          n,
-                                          pl,
-                                          td,
-                                          rl,
-                                          fr.friendly_name);
-              }
-              else
-                return nullopt;
-            },
-            iu);
+                if (ev || n == "build-file")
+                {
+                  // Check out submodules if the referenced file doesn't exist.
+                  //
+                  // Note that this doesn't work for symlinks on Windows where
+                  // git normally creates filesystem-agnostic symlinks that
+                  // are indistinguishable from regular files (see
+                  // fixup_worktree() for details). It seems like the only way
+                  // to deal with that is to unconditionally checkout
+                  // submodules on Windows. Let's not pessimize things for now
+                  // (if someone really wants this to work, they can always
+                  // enable real symlinks in git).
+                  //
+                  if (!exists (td / pl / p))
+                    checkout_submodules ();
+
+                  return read_package_file (p,
+                                            n,
+                                            pl,
+                                            td,
+                                            rl,
+                                            fr.friendly_name);
+                }
+                else
+                  return nullopt;
+              },
+              iu);
+          }
+          catch (const manifest_parsing& e)
+          {
+            diag_record dr (fail);
+            dr << e << info;
+            print_package_info (dr, pl, rl, fr.friendly_name);
+            dr << endf;
+          }
 
           // Load the bootstrap, root, and config/*.build buildfiles into the
           // respective *-build values, if requested and if they are not
diff --git a/doc/manual.cli b/doc/manual.cli
index e2ff1f0..8d9a1d2 100644
--- a/doc/manual.cli
+++ b/doc/manual.cli
@@ -1055,8 +1055,12 @@ license: <licenses> [; <comment>]
 [description]: <text>
 [description-file]: <path> [; <comment>]
 [description-type]: <text-type>
+[package-description]: <text>
+[package-description-file]: <path> [; <comment>]
+[package-description-type]: <text-type>
 [changes]: <text>
 [changes-file]: <path> [; <comment>]
+[changes-type]: <text-type>
 
 [url]: <url> [; <comment>]
 [doc-url]: <url> [; <comment>]
@@ -1131,7 +1135,7 @@ and use the \c{upstream-version} value to preserve the original version for
 information.
 
 
-\h2#manifest-package-type-language|\c{type, language}|
+\h2#manifest-package-type-language|\c{type}, \c{language}|
 
 \
 [type]: <type>
@@ -1385,23 +1389,30 @@ as well as words from its summary are already considered to be keywords and
 need not be repeated in this value.
 
 
-\h2#manifest-package-description|\c{description}|
+\h2#manifest-package-description|\c{description}, \c{package-description}|
 
 \
 [description]: <text>
 [description-file]: <path> [; <comment>]
 [description-type]: <text-type>
+[package-description]: <text>
+[package-description-file]: <path> [; <comment>]
+[package-description-type]: <text-type>
 \
 
-The detailed description of the package. It can be provided either inline as a
-text fragment or by referring to a file within a package (for example,
-\c{README}), but not both.
+The detailed description of the project (\c{description}) and package
+(\c{package-description}). If the package description is not specified, it is
+assumed to be the same as the project description. It only makes sense to
+specify the \c{package-description} value if the project and package are
+maintained separately. A description can be provided either inline as a text
+fragment or by referring to a file within a package (for example, \c{README}),
+but not both. For \c{package-description-file} the recommended file name is
+\c{PACKAGE-README} or \c{README-PACKAGE}.
 
 In the web interface (\c{brep}) the description is displayed according to its
 type. Currently, pre-formatted plain text, \l{https://github.github.com/gfm
 GitHub-Flavored Markdown}, and \l{https://spec.commonmark.org/current
-CommonMark} are supported with the following \c{description-type} values,
-respectively:
+CommonMark} are supported with the following \c{*-type} values, respectively:
 
 \
 text/plain
@@ -1412,13 +1423,13 @@ text/markdown;variant=CommonMark
 If just \c{text/markdown} is specified, then the GitHub-Flavored Markdown
 (which is a superset of CommonMark) is assumed.
 
-If the description type is not explicitly specified and the description is
-specified as \c{description-file}, then an attempt to derive the type from the
-file extension is made. Specifically, the \cb{.md} and \cb{.markdown}
-extensions are mapped to \c{text/markdown}, the \cb{.txt} and no extension are
-mapped to \c{text/plain}, and all other extensions are treated as an unknown
-type, similar to unknown \c{description-type} values. And if the description
-is not specified as a file, \c{text/plain} is assumed.
+If a description type is not explicitly specified and the description is
+specified as \c{*-file}, then an attempt to derive the type from the file
+extension is made. Specifically, the \cb{.md} and \cb{.markdown} extensions
+are mapped to \c{text/markdown}, the \cb{.txt} and no extension are mapped to
+\c{text/plain}, and all other extensions are treated as an unknown type,
+similar to unknown \c{*-type} values. And if a description is not specified as
+a file, \c{text/plain} is assumed.
 
 
 \h2#manifest-package-changes|\c{changes}|
@@ -1426,6 +1437,7 @@ is not specified as a file, \c{text/plain} is assumed.
 \
 [changes]: <text>
 [changes-file]: <path> [; <comment>]
+[changes-type]: <text-type>
 \
 
 The description of changes in the release.
@@ -1459,8 +1471,11 @@ changes:
 changes-file: NEWS
 \
 
-In the web interface (\c{brep}) the changes are displayed as pre-formatted
-plain text, similar to the package description.
+In the web interface (\c{brep}) the changes are displayed according to their
+type, similar to the package description (see the
+\l{#manifest-package-description \c{description}} value for details). If
+the changes type is not explicitly specified, then the types deduced for
+individual \c{changes} values must all be the same.
 
 
 \h2#manifest-package-url|\c{url}|
@@ -2120,7 +2135,7 @@ dependencies by other packages and therefore should be built in a host
 configuration. See the \l{bbot \c{bbot} documentation} for details.
 
 
-\h2#manifest-package-tests-examples-benchmarks|\c{tests, examples, benchmarks}|
+\h2#manifest-package-tests-examples-benchmarks|\c{tests}, \c{examples}, \c{benchmarks}|
 
 \
 [tests]: [*] <name> [<version-constraint>]
diff --git a/tests/pkg-verify.testscript b/tests/pkg-verify.testscript
index 69c29b0..7e7b5f3 100644
--- a/tests/pkg-verify.testscript
+++ b/tests/pkg-verify.testscript
@@ -88,6 +88,7 @@ $* --deep --ignore-unknown --manifest $src/foo-2.tar.gz >>EOO
     * First public release.
 
   \
+  changes-type: text/plain
   url: http://www.example.org/foo
   email: foo-users@example.org
   depends: bar == 2