Add Campaign IDs (#1408)

.vscode/settings.json

@@ -98,6 +98,7 @@
     "cinttypes": "cpp",
     "typeindex": "cpp",
     "typeinfo": "cpp",
-    "variant": "cpp"
+    "variant": "cpp",
+    "__bit_reference": "cpp"
   }
 }

include/vcpkg/base/message-data.inc.h

@@ -14,10 +14,6 @@ DECLARE_MESSAGE(AString, (), "", "a string")
 DECLARE_MESSAGE(ADateVersionString, (), "", "a date version string")
 DECLARE_MESSAGE(AddArtifactOnlyOne, (msg::command_line), "", "'{command_line}' can only add one artifact at a time.")
 DECLARE_MESSAGE(AddCommandFirstArg, (), "", "The first parameter to add must be 'artifact' or 'port'.")
-DECLARE_MESSAGE(AddFirstArgument,
-                (msg::command_line),
-                "",
-                "The first argument to '{command_line}' must be 'artifact' or 'port'.")
 DECLARE_MESSAGE(AddingCompletionEntry, (msg::path), "", "Adding vcpkg completion entry to {path}.")
 DECLARE_MESSAGE(AdditionalPackagesToExport,
                 (),
@@ -45,7 +41,6 @@ DECLARE_MESSAGE(AddVersionArtifactsOnly,
                 "--version is artifacts only and can't be used with vcpkg add port")
 DECLARE_MESSAGE(AddVersionAddedVersionToFile, (msg::version, msg::path), "", "added version {version} to {path}")
 DECLARE_MESSAGE(AddVersionCommitChangesReminder, (), "", "Did you remember to commit your changes?")
-DECLARE_MESSAGE(AddVersionCommitResultReminder, (), "", "Don't forget to commit the result!")
 DECLARE_MESSAGE(AddVersionDetectLocalChangesError,
                 (),
                 "",
@@ -1309,6 +1304,10 @@ DECLARE_MESSAGE(FileSeekFailed,
                 "",
                 "Failed to seek to position {byte_offset} in {path}.")
 DECLARE_MESSAGE(FilesExported, (msg::path), "", "Files exported at: {path}")
+DECLARE_MESSAGE(FindCommandFirstArg,
+                (),
+                "'find', 'artifact', and 'port' are vcpkg specific terms and should not be translated.",
+                "The first argument to 'find' must be 'artifact' or 'port' .")
 DECLARE_MESSAGE(FishCompletion, (msg::path), "", "vcpkg fish completion is already added at \"{path}\".")
 DECLARE_MESSAGE(FloatingPointConstTooBig, (msg::count), "", "Floating point constant too big: {count}")
 DECLARE_MESSAGE(FollowingPackagesMissingControl,

include/vcpkg/documentation.h

@@ -6,13 +6,45 @@ namespace vcpkg
 {
     namespace docs
     {
-        inline constexpr StringLiteral registries_url = "https://learn.microsoft.com/vcpkg/users/registries";
-        inline constexpr StringLiteral manifests_url = "https://learn.microsoft.com/vcpkg/users/manifests";
-        inline constexpr StringLiteral package_name_url = "https://learn.microsoft.com/vcpkg/reference/vcpkg-json#name";
-        inline constexpr StringLiteral assetcaching_url = "https://learn.microsoft.com/vcpkg/users/assetcaching";
-        inline constexpr StringLiteral binarycaching_url = "https://learn.microsoft.com/vcpkg/users/binarycaching";
-        inline constexpr StringLiteral versioning_url = "https://learn.microsoft.com/vcpkg/users/versioning";
-        inline constexpr StringLiteral vcpkg_visual_studio_path_url =
-            "https://learn.microsoft.com/vcpkg/users/triplets#VCPKG_VISUAL_STUDIO_PATH";
+        static constexpr StringLiteral registries_url =
+            "https://learn.microsoft.com/vcpkg/users/registries?WT.mc_id=vcpkg_inproduct_cli";
+        static constexpr StringLiteral manifests_url =
+            "https://learn.microsoft.com/vcpkg/users/manifests?WT.mc_id=vcpkg_inproduct_cli";
+        static constexpr StringLiteral vcpkg_json_ref_name =
+            "https://learn.microsoft.com/vcpkg/reference/vcpkg-json?WT.mc_id=vcpkg_inproduct_cli#name";
+        static constexpr StringLiteral assetcaching_url =
+            "https://learn.microsoft.com/vcpkg/users/assetcaching?WT.mc_id=vcpkg_inproduct_cli";
+        static constexpr StringLiteral binarycaching_url =
+            "https://learn.microsoft.com/vcpkg/users/binarycaching?WT.mc_id=vcpkg_inproduct_cli";
+        static constexpr StringLiteral binarycaching_gha_url =
+            "https://learn.microsoft.com/vcpkg/users/binarycaching?WT.mc_id=vcpkg_inproduct_cli#gha";
+        static constexpr StringLiteral versioning_url =
+            "https://learn.microsoft.com/vcpkg/users/versioning?WT.mc_id=vcpkg_inproduct_cli";
+        static constexpr StringLiteral version_schemes =
+            "https://learn.microsoft.com/vcpkg/users/versioning?WT.mc_id=vcpkg_inproduct_cli#version-schemes";
+        static constexpr StringLiteral triplets_url =
+            "https://learn.microsoft.com/vcpkg/users/triplets?WT.mc_id=vcpkg_inproduct_cli";
+        static constexpr StringLiteral vcpkg_visual_studio_path_url =
+            "https://learn.microsoft.com/vcpkg/users/triplets?WT.mc_id=vcpkg_inproduct_cli#VCPKG_VISUAL_STUDIO_PATH";
+        inline constexpr StringLiteral package_name_url =
+            "https://learn.microsoft.com/vcpkg/reference/vcpkg-json?WT.mc_id=vcpkg_inproduct_cli#name";
+        static constexpr StringLiteral troubleshoot_build_failures_url =
+            "https://learn.microsoft.com/vcpkg/troubleshoot/build-failures?WT.mc_id=vcpkg_inproduct_cli";
+        static constexpr StringLiteral add_command_url =
+            "https://learn.microsoft.com/vcpkg/commands/add?WT.mc_id=vcpkg_inproduct_cli";
+        static constexpr StringLiteral add_command_recurse_opt_url =
+            "https://learn.microsoft.com/vcpkg/commands/remove?WT.mc_id=vcpkg_inproduct_cli#--recurse";
+        static constexpr StringLiteral add_version_command_url =
+            "https://learn.microsoft.com/vcpkg/commands/add-version?WT.mc_id=vcpkg_inproduct_cli";
+        static constexpr StringLiteral add_version_command_overwrite_version_opt_url =
+            "https://learn.microsoft.com/vcpkg/commands/add-version?WT.mc_id=vcpkg_inproduct_cli#--overwrite-version";
+        static constexpr StringLiteral radd_version_command_all_opt_url =
+            "https://learn.microsoft.com/vcpkg/commands/add-version?WT.mc_id=vcpkg_inproduct_cli#--all";
+        static constexpr StringLiteral format_manifest_command_url =
+            "https://learn.microsoft.com/vcpkg/commands/format-manifest?WT.mc_id=vcpkg_inproduct_cli";
+        static constexpr StringLiteral troubleshoot_binary_cache_url =
+            "https://learn.microsoft.com/vcpkg/users/binarycaching-troubleshooting?WT.mc_id=vcpkg_inproduct_cli";
+        static constexpr StringLiteral troubleshoot_versioning_url =
+            "https://learn.microsoft.com/vcpkg/users/versioning-troubleshooting?WT.mc_id=vcpkg_inproduct_cli";
     }
 }

locales/messages.json

@@ -48,8 +48,6 @@
   "AddArtifactOnlyOne": "'{command_line}' can only add one artifact at a time.",
   "_AddArtifactOnlyOne.comment": "An example of {command_line} is vcpkg install zlib.",
   "AddCommandFirstArg": "The first parameter to add must be 'artifact' or 'port'.",
-  "AddFirstArgument": "The first argument to '{command_line}' must be 'artifact' or 'port'.",
-  "_AddFirstArgument.comment": "An example of {command_line} is vcpkg install zlib.",
   "AddPortRequiresManifest": "'{command_line}' requires an active manifest file.",
   "_AddPortRequiresManifest.comment": "An example of {command_line} is vcpkg install zlib.",
   "AddPortSucceeded": "Succeeded in adding ports to vcpkg.json file.",
@@ -61,7 +59,6 @@
   "AddVersionArtifactsOnly": "--version is artifacts only and can't be used with vcpkg add port",
   "_AddVersionArtifactsOnly.comment": "'--version', and 'vcpkg add port' are command lines that must not be localized",
   "AddVersionCommitChangesReminder": "Did you remember to commit your changes?",
-  "AddVersionCommitResultReminder": "Don't forget to commit the result!",
   "AddVersionDetectLocalChangesError": "skipping detection of local changes due to unexpected format in git status output",
   "AddVersionFileNotFound": "couldn't find required file {path}",
   "_AddVersionFileNotFound.comment": "An example of {path} is /foo/bar.",
@@ -781,6 +778,8 @@
   "_FilesExported.comment": "An example of {path} is /foo/bar.",
   "FilesRelativeToTheBuildDirectoryHere": "the files are relative to the build directory here",
   "FilesRelativeToThePackageDirectoryHere": "the files are relative to ${{CURRENT_PACKAGES_DIR}} here",
+  "FindCommandFirstArg": "The first argument to 'find' must be 'artifact' or 'port' .",
+  "_FindCommandFirstArg.comment": "'find', 'artifact', and 'port' are vcpkg specific terms and should not be translated.",
   "FindVersionArtifactsOnly": "--version can't be used with vcpkg search or vcpkg find port",
   "_FindVersionArtifactsOnly.comment": "'--version', 'vcpkg search', and 'vcpkg find port' are command lines that must not be localized",
   "FishCompletion": "vcpkg fish completion is already added at \"{path}\".",

src/vcpkg-test/dependencies.cpp

@@ -4,6 +4,7 @@
 
 #include <vcpkg/commands.set-installed.h>
 #include <vcpkg/dependencies.h>
+#include <vcpkg/documentation.h>
 #include <vcpkg/portfileprovider.h>
 #include <vcpkg/sourceparagraph.h>
 #include <vcpkg/vcpkgcmdarguments.h>
@@ -478,7 +479,8 @@ This can be resolved by adding an explicit override to the preferred version. Fo
       "version": "2with\"quotes"
     }
   ]
-See `vcpkg help versioning` or https://learn.microsoft.com/vcpkg/users/versioning for more information.)");
+See `vcpkg help versioning` or )" +
+            docs::troubleshoot_versioning_url + R"( for more information.)");
 }
 
 TEST_CASE ("version install string port version", "[versionplan]")
@@ -1117,7 +1119,8 @@ This can be resolved by adding an explicit override to the preferred version. Fo
       "version": "1.0.0"
     }
   ]
-See `vcpkg help versioning` or https://learn.microsoft.com/vcpkg/users/versioning for more information.)");
+See `vcpkg help versioning` or )" +
+                docs::troubleshoot_versioning_url + R"( for more information.)");
     }
     SECTION ("higher baseline")
     {
@@ -1148,7 +1151,8 @@ This can be resolved by adding an explicit override to the preferred version. Fo
       "version": "1.0.2"
     }
   ]
-See `vcpkg help versioning` or https://learn.microsoft.com/vcpkg/users/versioning for more information.)");
+See `vcpkg help versioning` or )" +
+                docs::troubleshoot_versioning_url + R"( for more information.)");
     }
 }
 
@@ -1241,7 +1245,8 @@ This can be resolved by adding an explicit override to the preferred version. Fo
       "version": "1"
     }
   ]
-See `vcpkg help versioning` or https://learn.microsoft.com/vcpkg/users/versioning for more information.)");
+See `vcpkg help versioning` or )" +
+                docs::troubleshoot_versioning_url + R"( for more information.)");
     }
     SECTION ("lower baseline")
     {

src/vcpkg-test/input.cpp

@@ -1,5 +1,6 @@
 #include <vcpkg-test/util.h>
 
+#include <vcpkg/documentation.h>
 #include <vcpkg/input.h>
 #include <vcpkg/triplet.h>
 
@@ -94,13 +95,14 @@ TEST_CASE ("check_triplet validates", "[input][check_triplet]")
     REQUIRE(maybe_check.has_value());
     maybe_check = check_triplet("x86-windows", db);
     REQUIRE(!maybe_check.has_value());
-    REQUIRE(maybe_check.error() == LocalizedString::from_raw(R"(error: Invalid triplet: x86-windows
+    std::string expected_error = R"(error: Invalid triplet: x86-windows
 Built-in Triplets:
 Community Triplets:
 Overlay Triplets from "x64-windows.cmake":
   x64-windows
-See https://learn.microsoft.com/vcpkg/users/triplets for more information.
-)"));
+See )" + docs::triplets_url + R"( for more information.
+)";
+    REQUIRE(maybe_check.error() == expected_error);
 }
 
 TEST_CASE ("check_and_get_package_spec validates the triplet", "[input][check_and_get_package_spec]")
@@ -120,13 +122,14 @@ TEST_CASE ("check_and_get_package_spec validates the triplet", "[input][check_an
 
     maybe_spec = check_and_get_package_spec("zlib:x86-windows", Triplet::from_canonical_name("x64-windows"), db);
     REQUIRE(!maybe_spec.has_value());
-    REQUIRE(maybe_spec.error() == LocalizedString::from_raw(R"(error: Invalid triplet: x86-windows
+    std::string expected_error = R"(error: Invalid triplet: x86-windows
 Built-in Triplets:
 Community Triplets:
 Overlay Triplets from "x64-windows.cmake":
   x64-windows
-See https://learn.microsoft.com/vcpkg/users/triplets for more information.
-)"));
+See )" + docs::triplets_url + R"( for more information.
+)";
+    REQUIRE(maybe_spec.error() == expected_error);
 }
 
 TEST_CASE ("check_and_get_package_spec forbids malformed", "[input][check_and_get_package_spec]")
@@ -187,13 +190,14 @@ TEST_CASE ("check_and_get_full_package_spec validates the triplet", "[input][che
     maybe_spec =
         check_and_get_full_package_spec("zlib[core]:x86-windows", Triplet::from_canonical_name("x64-windows"), db);
     REQUIRE(!maybe_spec.has_value());
-    REQUIRE(maybe_spec.error() == LocalizedString::from_raw(R"(error: Invalid triplet: x86-windows
+    std::string expected_error = R"(error: Invalid triplet: x86-windows
 Built-in Triplets:
 Community Triplets:
 Overlay Triplets from "x64-windows.cmake":
   x64-windows
-See https://learn.microsoft.com/vcpkg/users/triplets for more information.
-)"));
+See )" + docs::triplets_url + R"( for more information.
+)";
+    REQUIRE(maybe_spec.error() == expected_error);
 }
 
 TEST_CASE ("check_and_get_full_package_spec forbids malformed", "[input][check_and_get_full_package_spec]")

src/vcpkg-test/manifests.cpp

@@ -4,6 +4,7 @@
 
 #include <vcpkg/base/json.h>
 
+#include <vcpkg/documentation.h>
 #include <vcpkg/sourceparagraph.h>
 #include <vcpkg/vcpkgcmdarguments.h>
 
@@ -1418,8 +1419,8 @@ TEST_CASE ("default-feature-empty errors", "[manifests]")
     REQUIRE(!m_pgh.has_value());
     REQUIRE(m_pgh.error().data() ==
             "<test manifest>: error: $.default-features[0] (a feature name): \"\" is not a valid feature name. Feature "
-            "names must be lowercase alphanumeric+hypens and not reserved (see "
-            "https://learn.microsoft.com/vcpkg/users/manifests for more information).");
+            "names must be lowercase alphanumeric+hypens and not reserved (see " +
+                docs::manifests_url + " for more information).");
 }
 
 TEST_CASE ("default-feature-empty-object errors", "[manifests]")
@@ -1431,8 +1432,8 @@ TEST_CASE ("default-feature-empty-object errors", "[manifests]")
     REQUIRE(!m_pgh.has_value());
     REQUIRE(m_pgh.error().data() ==
             "<test manifest>: error: $.default-features[0].name (a feature name): \"\" is not a valid feature name. "
-            "Feature names must be lowercase alphanumeric+hypens and not reserved (see "
-            "https://learn.microsoft.com/vcpkg/users/manifests for more information).");
+            "Feature names must be lowercase alphanumeric+hypens and not reserved (see " +
+                docs::manifests_url + " for more information).");
 }
 
 TEST_CASE ("dependency-name-empty errors", "[manifests]")
@@ -1444,8 +1445,8 @@ TEST_CASE ("dependency-name-empty errors", "[manifests]")
     REQUIRE(!m_pgh.has_value());
     REQUIRE(m_pgh.error().data() ==
             "<test manifest>: error: $.dependencies[0] (a package name): \"\" is not a valid package name. Package "
-            "names must be lowercase alphanumeric+hypens and not reserved (see "
-            "https://learn.microsoft.com/vcpkg/users/manifests for more information).");
+            "names must be lowercase alphanumeric+hypens and not reserved (see " +
+                docs::manifests_url + " for more information).");
 }
 
 TEST_CASE ("dependency-name-empty-object errors", "[manifests]")
@@ -1457,8 +1458,8 @@ TEST_CASE ("dependency-name-empty-object errors", "[manifests]")
     REQUIRE(!m_pgh.has_value());
     REQUIRE(m_pgh.error().data() ==
             "<test manifest>: error: $.dependencies[0].name (a package name): \"\" is not a valid package name. "
-            "Package names must be lowercase alphanumeric+hypens and not reserved (see "
-            "https://learn.microsoft.com/vcpkg/users/manifests for more information).");
+            "Package names must be lowercase alphanumeric+hypens and not reserved (see " +
+                docs::manifests_url + " for more information).");
 }
 
 TEST_CASE ("dependency-feature-name-core errors", "[manifests]")
@@ -1544,8 +1545,8 @@ TEST_CASE ("dependency-feature-name-empty errors", "[manifests]")
     REQUIRE(!m_pgh.has_value());
     REQUIRE(m_pgh.error().data() ==
             "<test manifest>: error: $.dependencies[0].features[0] (a feature name): \"\" is not a valid feature name. "
-            "Feature names must be lowercase alphanumeric+hypens and not reserved (see "
-            "https://learn.microsoft.com/vcpkg/users/manifests for more information).");
+            "Feature names must be lowercase alphanumeric+hypens and not reserved (see " +
+                docs::manifests_url + " for more information).");
 }
 
 TEST_CASE ("dependency-feature-name-empty-object errors", "[manifests]")
@@ -1562,6 +1563,6 @@ TEST_CASE ("dependency-feature-name-empty-object errors", "[manifests]")
     REQUIRE(!m_pgh.has_value());
     REQUIRE(m_pgh.error().data() ==
             "<test manifest>: error: $.dependencies[0].features[0].name (a feature name): \"\" is not a valid feature "
-            "name. Feature names must be lowercase alphanumeric+hypens and not reserved (see "
-            "https://learn.microsoft.com/vcpkg/users/manifests for more information).");
+            "name. Feature names must be lowercase alphanumeric+hypens and not reserved (see " +
+                docs::manifests_url + " for more information).");
 }

src/vcpkg-test/registries.cpp

@@ -4,6 +4,7 @@
 #include <vcpkg/base/strings.h>
 
 #include <vcpkg/configuration.h>
+#include <vcpkg/documentation.h>
 #include <vcpkg/registries.h>
 
 using namespace vcpkg;
@@ -421,16 +422,18 @@ TEST_CASE ("registries report pattern errors", "[registries]")
     REQUIRE(errors.size() == 3);
     CHECK(errors[0] == "test: error: $.registries[0].packages[1] (a package pattern): \"\" is not a valid package "
                        "pattern. Package patterns must "
-                       "use only one wildcard character (*) and it must be the last character in the pattern (see "
-                       "https://learn.microsoft.com/vcpkg/users/registries for more information).");
-    CHECK(errors[1] == "test: error: $.registries[0].packages[2] (a package pattern): \"a*a\" is not a valid package "
-                       "pattern. Package patterns "
-                       "must use only one wildcard character (*) and it must be the last character in the pattern (see "
-                       "https://learn.microsoft.com/vcpkg/users/registries for more information).");
-    CHECK(errors[2] == "test: error: $.registries[0].packages[3] (a package pattern): \"*a\" is not a valid package "
-                       "pattern. Package patterns "
-                       "must use only one wildcard character (*) and it must be the last character in the pattern (see "
-                       "https://learn.microsoft.com/vcpkg/users/registries for more information).");
+                       "use only one wildcard character (*) and it must be the last character in the pattern (see " +
+                           docs::registries_url + " for more information).");
+    CHECK(errors[1] ==
+          "test: error: $.registries[0].packages[2] (a package pattern): \"a*a\" is not a valid package "
+          "pattern. Package patterns "
+          "must use only one wildcard character (*) and it must be the last character in the pattern (see " +
+              docs::registries_url + " for more information).");
+    CHECK(errors[2] ==
+          "test: error: $.registries[0].packages[3] (a package pattern): \"*a\" is not a valid package "
+          "pattern. Package patterns "
+          "must use only one wildcard character (*) and it must be the last character in the pattern (see " +
+              docs::registries_url + " for more information).");
 }
 
 TEST_CASE ("registries ignored patterns warning", "[registries]")

src/vcpkg-test/specifier.cpp

@@ -2,6 +2,7 @@
 
 #include <vcpkg/base/util.h>
 
+#include <vcpkg/documentation.h>
 #include <vcpkg/packagespec.h>
 
 using namespace vcpkg;
@@ -118,7 +119,8 @@ TEST_CASE ("specifier parsing", "[specifier]")
             REQUIRE(
                 s.error() ==
                 LocalizedString::from_raw(
-                    R"(error: expected the end of input parsing a package name; this usually means the indicated character is not allowed to be in a port name. Port names are all lowercase alphanumeric+hypens and not reserved (see https://learn.microsoft.com/vcpkg/reference/vcpkg-json#name for more information).
+                    R"(error: expected the end of input parsing a package name; this usually means the indicated character is not allowed to be in a port name. Port names are all lowercase alphanumeric+hypens and not reserved (see )" +
+                    docs::vcpkg_json_ref_name + R"( for more information).
   on expression: zlib#
                      ^)"));
         }

src/vcpkg/binarycaching.cpp

@@ -592,7 +592,7 @@ namespace
                         msg_sink.println(Color::warning,
                                          msgFailedVendorAuthentication,
                                          msg::vendor = "NuGet",
-                                         msg::url = docs::binarycaching_url);
+                                         msg::url = docs::troubleshoot_binary_cache_url);
                     }
                     else if (res.output.find("for example \"-ApiKey AzureDevOps\"") != std::string::npos)
                     {
@@ -750,8 +750,9 @@ namespace
                     msgUploadingBinariesToVendor, msg::spec = spec, msg::vendor = "NuGet", msg::path = write_src);
                 if (!m_cmd.push(msg_sink, nupkg_path, nuget_sources_arg({&write_src, 1})))
                 {
-                    msg_sink.println(
-                        Color::error, msgPushingVendorFailed, msg::vendor = "NuGet", msg::path = write_src);
+                    msg_sink.println(Color::error,
+                                     msg::format(msgPushingVendorFailed, msg::vendor = "NuGet", msg::path = write_src)
+                                         .append(msgSeeURL, msg::url = docs::troubleshoot_binary_cache_url));
                 }
                 else
                 {
@@ -767,7 +768,9 @@ namespace
                 if (!m_cmd.push(msg_sink, nupkg_path, nuget_configfile_arg(write_cfg)))
                 {
                     msg_sink.println(
-                        Color::error, msgPushingVendorFailed, msg::vendor = "NuGet config", msg::path = write_cfg);
+                        Color::error,
+                        msg::format(msgPushingVendorFailed, msg::vendor = "NuGet config", msg::path = write_cfg)
+                            .append(msgSeeURL, msg::url = docs::troubleshoot_binary_cache_url));
                 }
                 else
                 {
@@ -1972,8 +1975,7 @@ namespace vcpkg
             if (s.gha_read || s.gha_write)
             {
                 if (!args.actions_cache_url.has_value() || !args.actions_runtime_token.has_value())
-                    return msg::format_error(msgGHAParametersMissing,
-                                             msg::url = "https://learn.microsoft.com/vcpkg/users/binarycaching#gha");
+                    return msg::format_error(msgGHAParametersMissing, msg::url = docs::binarycaching_gha_url);
             }
 
             if (!s.archives_to_read.empty() || !s.url_templates_to_get.empty() || !s.gcs_read_prefixes.empty() ||

src/vcpkg/commands.add-version.cpp

@@ -9,6 +9,7 @@
 #include <vcpkg/base/util.h>
 
 #include <vcpkg/commands.add-version.h>
+#include <vcpkg/documentation.h>
 #include <vcpkg/paragraphs.h>
 #include <vcpkg/registries.h>
 #include <vcpkg/vcpkgcmdarguments.h>
@@ -63,12 +64,18 @@ namespace
             if (DateVersion::try_parse(version.version.text))
             {
                 Checks::msg_exit_with_message(
-                    VCPKG_LINE_INFO, msgAddVersionSuggestVersionDate, msg::package_name = port_name);
+                    VCPKG_LINE_INFO,
+                    msg::format(msgAddVersionSuggestVersionDate, msg::package_name = port_name)
+                        .append_raw("\n")
+                        .append(msgSeeURL, msg::url = docs::version_schemes));
             }
             if (DotVersion::try_parse_relaxed(version.version.text))
             {
                 Checks::msg_exit_with_message(
-                    VCPKG_LINE_INFO, msgAddVersionSuggestVersionRelaxed, msg::package_name = port_name);
+                    VCPKG_LINE_INFO,
+                    msg::format(msgAddVersionSuggestVersionRelaxed, msg::package_name = port_name)
+                        .append_raw("\n")
+                        .append(msgSeeURL, msg::url = docs::version_schemes));
             }
         }
     }
@@ -228,6 +235,8 @@ namespace
                                      .append(msgAddVersionCommitChangesReminder)
                                      .append_raw("\n***")
                                      .append(msgAddVersionNoFilesUpdated)
+                                     .append_raw("\n***")
+                                     .append(msgSeeURL, msg::url = docs::add_version_command_url)
                                      .append_raw("***"));
             if (keep_going) return UpdateResult::NotUpdated;
             Checks::exit_fail(VCPKG_LINE_INFO);
@@ -253,6 +262,8 @@ namespace
                         .append(msgAddVersionUpdateVersionReminder)
                         .append_raw('\n')
                         .append(msgAddVersionOverwriteOptionSuggestion, msg::option = SwitchOverwriteVersion)
+                        .append_raw('\n')
+                        .append(msgSeeURL, msg::url = docs::add_version_command_overwrite_version_opt_url)
                         .append_raw("\n***")
                         .append(msgAddVersionNoFilesUpdated)
                         .append_raw("***"));
@@ -334,11 +345,12 @@ namespace vcpkg
         }
         else
         {
-            Checks::msg_check_exit(VCPKG_LINE_INFO,
-                                   add_all,
-                                   msgAddVersionUseOptionAll,
-                                   msg::command_name = "x-add-version",
-                                   msg::option = SwitchAll);
+            Checks::msg_check_exit(
+                VCPKG_LINE_INFO,
+                add_all,
+                msg::format(msgAddVersionUseOptionAll, msg::command_name = "x-add-version", msg::option = SwitchAll)
+                    .append_raw("\n")
+                    .append(msgSeeURL, msg::url = docs::add_version_command_url));
 
             for (auto&& port_dir : fs.get_directories_non_recursive(paths.builtin_ports_directory(), VCPKG_LINE_INFO))
             {
@@ -406,8 +418,10 @@ namespace vcpkg
                                 .append_raw('\n')
                                 .append(msgAddVersionFormatPortSuggestion, msg::command_line = command_line)
                                 .append_raw('\n')
-                                .append(msgAddVersionCommitResultReminder)
-                                .append_raw('\n'));
+                                .append(msgSeeURL, msg::url = docs::format_manifest_command_url)
+                                .append(msgAddVersionCommitChangesReminder)
+                                .append_raw('\n')
+                                .append(msgSeeURL, msg::url = docs::add_version_command_url));
                         Checks::check_exit(VCPKG_LINE_INFO, !add_all);
                         continue;
                     }
@@ -429,6 +443,8 @@ namespace vcpkg
                                          .append(msgAddVersionCommitChangesReminder)
                                          .append_raw("\n***")
                                          .append(msgAddVersionNoFilesUpdated)
+                                         .append_raw("\n***")
+                                         .append(msgSeeURL, msg::url = docs::add_version_command_url)
                                          .append_raw("***"));
                 if (add_all) continue;
                 Checks::exit_fail(VCPKG_LINE_INFO);

src/vcpkg/commands.add.cpp

@@ -69,7 +69,10 @@ namespace vcpkg
             if (!manifest)
             {
                 Checks::msg_exit_with_message(
-                    VCPKG_LINE_INFO, msgAddPortRequiresManifest, msg::command_line = "vcpkg add port");
+                    VCPKG_LINE_INFO,
+                    msg::format(msgAddPortRequiresManifest, msg::command_line = "vcpkg add port")
+                        .append_raw('\n')
+                        .append(msgSeeURL, msg::url = docs::add_command_url));
             }
 
             if (Util::Maps::contains(parsed.settings, SwitchVersion))
@@ -164,6 +167,8 @@ namespace vcpkg
             Checks::exit_success(VCPKG_LINE_INFO);
         }
 
-        Checks::msg_exit_with_message(VCPKG_LINE_INFO, msgAddFirstArgument, msg::command_line = "vcpkg add");
+        Checks::msg_exit_with_message(
+            VCPKG_LINE_INFO,
+            msg::format(msgAddCommandFirstArg).append_raw('\n').append(msgSeeURL, msg::url = docs::add_command_url));
     }
 }

src/vcpkg/commands.build.cpp

@@ -1535,7 +1535,7 @@ namespace vcpkg
             }
         }
 
-        return res;
+        return res.append(msgSeeURL, msg::url = docs::troubleshoot_build_failures_url);
     }
 
     void append_log(const Path& path, const std::string& log, size_t max_log_length, std::string& out)

src/vcpkg/commands.find.cpp

@@ -7,6 +7,7 @@
 
 #include <vcpkg/commands.find.h>
 #include <vcpkg/configure-environment.h>
+#include <vcpkg/documentation.h>
 #include <vcpkg/metrics.h>
 #include <vcpkg/portfileprovider.h>
 #include <vcpkg/registries.h>
@@ -285,6 +286,8 @@ namespace vcpkg
             perform_find_port_and_exit(paths, full_description, enable_json, filter, paths.overlay_ports);
         }
 
-        Checks::msg_exit_with_error(VCPKG_LINE_INFO, msgAddCommandFirstArg);
+        Checks::msg_exit_with_error(
+            VCPKG_LINE_INFO,
+            msg::format(msgFindCommandFirstArg).append_raw('\n').append(msgSeeURL, msg::url = docs::add_command_url));
     }
 } // namespace vcpkg

src/vcpkg/commands.help.cpp

@@ -151,7 +151,7 @@ namespace vcpkg
             }
         }
 
-        result.append(msgSeeURL, msg::url = "https://learn.microsoft.com/vcpkg/users/triplets");
+        result.append(msgSeeURL, msg::url = docs::triplets_url);
         result.append_raw('\n');
     }
 

src/vcpkg/commands.remove.cpp

@@ -4,6 +4,7 @@
 #include <vcpkg/commands.remove.h>
 #include <vcpkg/commands.update.h>
 #include <vcpkg/dependencies.h>
+#include <vcpkg/documentation.h>
 #include <vcpkg/input.h>
 #include <vcpkg/installedpaths.h>
 #include <vcpkg/portfileprovider.h>
@@ -239,7 +240,9 @@ namespace vcpkg
 
             if (!is_recursive)
             {
-                msg::println_warning(msgAddRecurseOption);
+                msg::println_warning(msg::format(msgAddRecurseOption)
+                                         .append_raw('\n')
+                                         .append(msgSeeURL, msg::url = docs::add_command_recurse_opt_url));
                 Checks::exit_fail(VCPKG_LINE_INFO);
             }
         }

src/vcpkg/dependencies.cpp

@@ -1777,7 +1777,7 @@ namespace vcpkg
             serialize_dependency_override(example_array, DependencyOverride{on.name(), baseline.version});
             doc.append_raw(Json::stringify_object_member(OVERRIDES, example_array, Json::JsonStyle::with_spaces(2), 1));
 
-            doc.append(msgVersionIncomparable4, msg::url = docs::versioning_url);
+            doc.append(msgVersionIncomparable4, msg::url = docs::troubleshoot_versioning_url);
             return doc;
         }
 

src/vcpkg/registries.cpp

@@ -1053,6 +1053,7 @@ namespace
         }
 
         error_msg.append(msgVersionIncomparable4, msg::url = docs::versioning_url);
+        error_msg.append(msgSeeURL, msg::url = docs::troubleshoot_versioning_url);
         return error_msg;
     }
 

src/vcpkg/vcpkgpaths.cpp

@@ -793,7 +793,9 @@ namespace vcpkg
             return *i;
         }
 
-        Checks::msg_exit_with_error(VCPKG_LINE_INFO, msgVcpkgDisallowedClassicMode);
+        Checks::msg_exit_with_error(VCPKG_LINE_INFO,
+                                    msg::format(msgVcpkgDisallowedClassicMode)
+                                        .append(msgSeeURL, msg::url = docs::troubleshoot_build_failures_url));
     }
 
     const Path& VcpkgPaths::buildtrees() const
@@ -803,7 +805,9 @@ namespace vcpkg
             return *i;
         }
 
-        Checks::msg_exit_with_error(VCPKG_LINE_INFO, msgVcpkgDisallowedClassicMode);
+        Checks::msg_exit_with_error(VCPKG_LINE_INFO,
+                                    msg::format(msgVcpkgDisallowedClassicMode)
+                                        .append(msgSeeURL, msg::url = docs::troubleshoot_build_failures_url));
     }
 
     const Path& VcpkgPaths::packages() const
@@ -813,7 +817,9 @@ namespace vcpkg
             return *i;
         }
 
-        Checks::msg_exit_with_error(VCPKG_LINE_INFO, msgVcpkgDisallowedClassicMode);
+        Checks::msg_exit_with_error(VCPKG_LINE_INFO,
+                                    msg::format(msgVcpkgDisallowedClassicMode)
+                                        .append(msgSeeURL, msg::url = docs::troubleshoot_build_failures_url));
     }
 
     Path VcpkgPaths::baselines_output() const { return buildtrees() / "versioning_" / "baselines"; }
@@ -1204,6 +1210,7 @@ namespace vcpkg
             }
 
             error.append_raw('\n').append(std::move(maybe_git_read_tree_output).error());
+            error.append(msgSeeURL, msg::url = docs::troubleshoot_versioning_url);
             return error;
         }