Clarify and correct examples in `about_Environment_Variables`

[Maxime-ADAGP]

Prerequisites

• Write a descriptive title.
• Search the existing issues.
• I am reporting the documentation problem for version of PowerShell I am using.

Version

5.1, 7.0, 7.1, 7.2, 7.3 (preview)

Link to affected document

https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_environment_variables?view=powershell-7.2#using-and-changing-environment-variables

Description of the documentation error

At the end of the "Using and changing environment variables" section, the documentation mentions the usage of Item cmdlets to manage environment variable values. I find the examples provided in this final paragraph confusing:

For example, to use the Set-Item cmdlet to append ;c:\temp to the value of the Path environment variable, use the following syntax:

Remove-Item -Path Env:Path

In this command, the variable is cleared. Note that the environment variable is referenced as an Item path and $ is not used.

Set-Item -Path Env:Path -Value ($Env:Path + ";C:\Temp")

In this command, the value is enclosed in parentheses so that it is interpreted as a unit.

It first mentions using Set-Item then proceeds to provide the syntax for Remove-Item.

Additionally, I find this example quite dangerous for a new user who doesn't know the potential consequences of executing this command.

Suggested fix

I'd replace the first example's path variable with a bogus one, such as Foo, then mention in the second example that we have appended ;c:\temp to the value of Path:

For example, to use the Remove-Item cmdlet to clear the value of the Foo environment variable, use the following syntax:

Remove-Item -Path Env:Foo

Note that the environment variable is referenced as an Item path and $ is not used.

Set-Item -Path Env:Path -Value ($Env:Path + ";C:\Temp")

In this command, we have appended ;C:\Temp to the value of the Path environment variable. Note that the value is enclosed in parentheses so that it is interpreted as a unit.

[michaeltlombardi]

Hey @Maxime-ADAGP, thanks so much for reporting this! I'm going to rework the section for clarity and flow and address these concerns today.