Update documentation to clarify semicolon escaping behavior (#4693)

* Initial plan

* Fix incorrect escaping of semicolons in cmake.configureSettings

Co-authored-by: snehara99 <[email protected]>

* Fix issue number in changelog: #4682 -> #4693

Co-authored-by: snehara99 <[email protected]>

* Fix issue number in changelog: #4693 -> #4585

Co-authored-by: snehara99 <[email protected]>

* Revert code changes, update documentation instead to clarify semicolon escaping behavior

Co-authored-by: snehara99 <[email protected]>

* Remove redundant phrase from cmake.configureSettings documentation

Co-authored-by: snehara99 <[email protected]>

* Move changelog entry from Documentation to Bug Fixes section

Co-authored-by: snehara99 <[email protected]>

---------

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: snehara99 <[email protected]>

Author: Copilot

CHANGELOG.md

@@ -7,7 +7,7 @@ Features:
 - Add command to clear build diagnostics from the Problems pane. [#4691](https://github.com/microsoft/vscode-cmake-tools/pull/4691)
 
 Bug Fixes:
-
+- Clarify that semicolons in `cmake.configureSettings` string values are escaped, and array notation should be used for CMake lists. [#4585](https://github.com/microsoft/vscode-cmake-tools/issues/4585)
 - Fix "CMake: Quick Start" command failing silently when no folder is open. Now shows an error message with an option to open a folder. [#4504](https://github.com/microsoft/vscode-cmake-tools/issues/4504)
 - Fix "CMake: Run Without Debugging" not changing the working directory when the build directory changes. [#4549](https://github.com/microsoft/vscode-cmake-tools/issues/4549)
 - Fix CMake script path links not working in CHS/CSY/FRA/PLK locales due to localized quotes. [#4383](https://github.com/microsoft/vscode-cmake-tools/issues/4383)

docs/cmake-settings.md

@@ -28,7 +28,7 @@ Options that support substitution, in the table below, allow variable references
 | `cmake.configureEnvironment` | An object containing `key:value` pairs of environment variables, which will be passed to CMake only when configuring.| `null` (no environment variable pairs) | yes |
 | `cmake.configureOnEdit` | Automatically configure CMake project directories when the path in the `cmake.sourceDirectory` setting is updated or when `CMakeLists.txt` or `*.cmake` files are saved. | `true` | no |
 | `cmake.configureOnOpen` | Automatically configure CMake project directories when they are opened. | `true` | no |
-| `cmake.configureSettings` | An object containing `key:value` pairs, which will be passed to CMake when configuring. The same as passing `-DVAR_NAME=ON` via `cmake.configureArgs`. NOTE: If you are setting an array argument within `cmake.configureSettings`, you should use array notation, i.e. `"CONFIGURE_SETTINGS_LIST": [ "a", "b" ]` | `{}` (no values) | yes |
+| `cmake.configureSettings` | An object containing `key:value` pairs, which will be passed to CMake when configuring. The same as passing `-DVAR_NAME=ON` via `cmake.configureArgs`. NOTE: Semicolons (`;`) in string values are automatically escaped to prevent CMake from interpreting them as list separators. If you want to pass a CMake list, use array notation instead, e.g. `"MY_LIST": [ "a", "b" ]`. | `{}` (no values) | yes |
 | `cmake.copyCompileCommands`| If not `null`, copies the `compile_commands.json` file generated by CMake to the path specified by this setting whenever CMake successfully configures. |  `null` (do not copy the file) | yes |
 | `cmake.coverageInfoFiles` | LCOV coverage info files to be processed after running tests with coverage using the test explorer. | `[]` | yes |
 | `cmake.cpackArgs` | An array of additional arguments to pass to cpack. | `[]` | yes |