Add docs for the new ways to report build failures and giving hint messages from portfile.cmake

vcpkg/TOC.yml

@@ -148,6 +148,8 @@
       href: maintainers/functions/vcpkg_extract_source_archive.md
     - name: vcpkg_extract_source_archive_ex
       href: maintainers/functions/vcpkg_extract_source_archive_ex.md
+    - name: vcpkg_fail_with_user_interaction_required
+      href: maintainers/functions/vcpkg_fail_with_user_interaction_required.md
     - name: vcpkg_fail_port_install
       href: maintainers/functions/vcpkg_fail_port_install.md
     - name: vcpkg_find_acquire_program
@@ -212,6 +214,8 @@
       href: maintainers/functions/vcpkg_replace_string.md
     - name: vcpkg_restore_env_variables
       href: maintainers/functions/vcpkg_restore_env_variables.md
+    - name: vcpkg_user_hint_on_failure
+      href: maintainers/functions/vcpkg_user_hint_on_failure.md
     - name: Internal
       items:
       - name: z_vcpkg_apply_patches

vcpkg/maintainers/functions/vcpkg_fail_with_user_interaction_required.md

@@ -0,0 +1,27 @@
+---
+title: vcpkg_fail_with_user_interaction_required
+description: Learn how to use vcpkg_fail_with_user_interaction_required.
+ms.date: 04/11/2023
+---
+# vcpkg_fail_with_user_interaction_required
+
+Outputs the message to the console and stops the execution of the `portfile.cmake`. 
+
+In comparison to `message(FATAL_ERROR <message>)` vcpkg don't emit instructions on how to report an issue and the `<message>` is printed instead. 
+
+## Usage
+
+```cmake
+vcpkg_fail_with_user_interaction_required(<message>)
+```
+
+## Parameters
+
+### `<message>`
+
+The error message that should be displayed to the user.
+
+## Source
+
+[scripts/cmake/vcpkg\_fail\_with\_user\_interaction\_required.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_fail_with_user_interaction_required.cmake)
+

vcpkg/maintainers/functions/vcpkg_user_hint_on_failure.md

@@ -0,0 +1,27 @@
+---
+title: vcpkg_user_hint_on_failure
+description: Learn how to use vcpkg_user_hint_on_failure.
+ms.date: 04/11/2023
+---
+# vcpkg_user_hint_on_failure
+
+Outputs the message to the console if the building of the port fails.
+
+The message is emitted after the instructions on how to report an issue as an hint how to resolve the build failure.
+
+## Usage
+
+```cmake
+vcpkg_user_hint_on_failure(<message>)
+```
+
+## Parameters
+
+### `<message>`
+
+The hint message that should be displayed to the user if case of an build failure.
+
+## Source
+
+[scripts/cmake/vcpkg\_user\_hint\_on\_failure.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_user_hint_on_failure.cmake)
+