From 545c165ce08bff237b1468f42b0607e899dab959 Mon Sep 17 00:00:00 2001
From: nicole mazzuca <mazzucan@outlook.com>
Date: Tue, 9 Feb 2021 15:53:36 -0800
Subject: [(z_)vcpkg_prettify_command(_line)] Scripts Tree Audit (#16130)

* [vcpkg_prettify_command] Audit

* rename file

* rename out-var in docs

* fix file path

* add internal use message to docs

* escapin' in z_vcpkg_prettify_command_line

* regenerate docs
---
 .../internal/z_vcpkg_function_arguments.md         | 27 ++++++++++++++++++++++
 .../internal/z_vcpkg_prettify_command_line.md      | 19 +++++++++++++++
 docs/maintainers/portfile-functions.md             |  3 ++-
 docs/maintainers/vcpkg_execute_required_process.md |  2 +-
 docs/maintainers/vcpkg_prettify_command.md         | 17 --------------
 5 files changed, 49 insertions(+), 19 deletions(-)
 create mode 100644 docs/maintainers/internal/z_vcpkg_function_arguments.md
 create mode 100644 docs/maintainers/internal/z_vcpkg_prettify_command_line.md
 delete mode 100644 docs/maintainers/vcpkg_prettify_command.md

(limited to 'docs')

diff --git a/docs/maintainers/internal/z_vcpkg_function_arguments.md b/docs/maintainers/internal/z_vcpkg_function_arguments.md
new file mode 100644
index 000000000..e60407f20
--- /dev/null
+++ b/docs/maintainers/internal/z_vcpkg_function_arguments.md
@@ -0,0 +1,27 @@
+# z_vcpkg_function_arguments
+
+**Only for internal use in vcpkg helpers. Behavior and arguments will change without notice.**
+Get a list of the arguments which were passed in.
+Unlike `ARGV`, which is simply the arguments joined with `;`,
+so that `(A B)` is not distinguishable from `("A;B")`,
+this macro gives `"A;B"` for the first argument list,
+and `"A\;B"` for the second.
+
+```cmake
+z_vcpkg_function_arguments(<out-var> [<N>])
+```
+
+`z_vcpkg_function_arguments` gets the arguments between `ARGV<N>` and the last argument.
+`<N>` defaults to `0`, so that all arguments are taken.
+
+## Example:
+```cmake
+function(foo_replacement)
+    z_vcpkg_function_arguments(ARGS)
+    foo(${ARGS})
+    ...
+endfunction()
+```
+
+## Source
+[scripts/cmake/z_vcpkg_function_arguments.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/z_vcpkg_function_arguments.cmake)
diff --git a/docs/maintainers/internal/z_vcpkg_prettify_command_line.md b/docs/maintainers/internal/z_vcpkg_prettify_command_line.md
new file mode 100644
index 000000000..1b7636630
--- /dev/null
+++ b/docs/maintainers/internal/z_vcpkg_prettify_command_line.md
@@ -0,0 +1,19 @@
+# z_vcpkg_prettify_command_line
+
+**Only for internal use in vcpkg helpers. Behavior and arguments will change without notice.**
+Turn a command line into a formatted string.
+
+```cmake
+z_vcpkg_prettify_command_line(<out-var> <argument>...)
+```
+
+This command is for internal use, when printing out to a message.
+
+## Examples
+
+* `scripts/cmake/vcpkg_execute_build_process.cmake`
+* `scripts/cmake/vcpkg_execute_required_process.cmake`
+* `scripts/cmake/vcpkg_execute_required_process_repeat.cmake`
+
+## Source
+[scripts/cmake/z_vcpkg_prettify_command_line.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/z_vcpkg_prettify_command_line.cmake)
diff --git a/docs/maintainers/portfile-functions.md b/docs/maintainers/portfile-functions.md
index 9cebaf40a..c92abc2c6 100644
--- a/docs/maintainers/portfile-functions.md
+++ b/docs/maintainers/portfile-functions.md
@@ -53,9 +53,10 @@
 - [vcpkg\_install\_nmake](vcpkg_install_nmake.md)
 - [vcpkg\_install\_qmake](vcpkg_install_qmake.md)
 - [vcpkg\_minimum\_required](vcpkg_minimum_required.md)
-- [vcpkg\_prettify\_command](vcpkg_prettify_command.md)
 - [vcpkg\_replace\_string](vcpkg_replace_string.md)
 
 ## Internal Functions
 
 - [vcpkg\_internal\_get\_cmake\_vars](internal/vcpkg_internal_get_cmake_vars.md)
+- [z\_vcpkg\_function\_arguments](internal/z_vcpkg_function_arguments.md)
+- [z\_vcpkg\_prettify\_command\_line](internal/z_vcpkg_prettify_command_line.md)
diff --git a/docs/maintainers/vcpkg_execute_required_process.md b/docs/maintainers/vcpkg_execute_required_process.md
index a14e2bcbb..21b1029eb 100644
--- a/docs/maintainers/vcpkg_execute_required_process.md
+++ b/docs/maintainers/vcpkg_execute_required_process.md
@@ -15,7 +15,7 @@ vcpkg_execute_required_process(
 ```
 ## Parameters
 ### ALLOW_IN_DOWNLOAD_MODE
-Allows the command to execute in Download Mode.  
+Allows the command to execute in Download Mode.
 [See execute_process() override](../../scripts/cmake/execute_process.cmake).
 
 ### COMMAND
diff --git a/docs/maintainers/vcpkg_prettify_command.md b/docs/maintainers/vcpkg_prettify_command.md
deleted file mode 100644
index c9ef234e2..000000000
--- a/docs/maintainers/vcpkg_prettify_command.md
+++ /dev/null
@@ -1,17 +0,0 @@
-# vcpkg_prettify_command
-
-Turns list of command arguments into a formatted string.
-
-## Usage
-```cmake
-vcpkg_prettify_command(<INPUT_VAR> <OUTPUT_VAR>)
-```
-
-## Examples
-
-* `scripts/cmake/vcpkg_execute_build_process.cmake`
-* `scripts/cmake/vcpkg_execute_required_process.cmake`
-* `scripts/cmake/vcpkg_execute_required_process_repeat.cmake`
-
-## Source
-[scripts/cmake/vcpkg_prettify_command.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_prettify_command.cmake)
-- 
cgit v1.2.3