From 5af0b12a1abcdeba69656e98b2acb901b841dcf8 Mon Sep 17 00:00:00 2001
From: Robert Holt <rjmholt_msft@outlook.com>
Date: Fri, 2 Nov 2018 15:41:05 -0700
Subject: [PATCH 01/15] Add first json entries

---
 .../About/about_PowerShell_Config.md          | 133 ++++++++++++++++++
 1 file changed, 133 insertions(+)
 create mode 100644 reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md

diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md b/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md
new file mode 100644
index 000000000000..3bf508413df7
--- /dev/null
+++ b/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md
@@ -0,0 +1,133 @@
+---
+ms.date:  11/02/2018
+schema:  2.0.0
+locale:  en-us
+keywords:  powershell
+title:  about_PowerShell_Config
+---
+
+# About PowerShell Config
+
+## SHORT DESCRIPTION
+
+Cross-platform configuration files for PowerShell Core.
+
+## LONG DESCRIPTION
+
+A `powershell.config.json` file allows configuration of
+installation-wide settings in PowerShell Core.
+These settings were previously configured in the Windows Registry
+in Windows PowerShell.
+The file is in the [JSON](https://en.wikipedia.org/wiki/JSON) format,
+with settings specified by key.
+
+> [!WARNING]
+> A `powershell.config.json` file that contains invalid JSON
+> or unsupported keys or values will result in not being able
+> to start an interactive PowerShell session.
+> If this occurs, you will need to fix the configuration file
+> from another application to run PowerShell.
+
+### System-wide configuration
+
+A `powershell.config.json` file in the `$PSHOME` directory will apply
+to all PowerShell Core sessions running for that PowerShell Core
+installation.
+
+> [!NOTE]
+> The system `powershell.config.json` location is defined as
+> the same directory as the executing System.Management.Automation.dll
+> assembly. This applies to hosted PowerShell SDK instances as well.
+
+### User configurations
+
+Configuration of PowerShell can also be provided on a per-user basis.
+This applies configuration settings to a specific user.
+For this, the configuration file can be found in the user-scope
+configuration directory.
+On Windows this is `$env:LocalAppData\Microsoft\powershell`,
+on UNIX-like platforms this is `$HOME/.config/powershell/`.
+
+> [!TIP]
+> The user configuration directory can be found across platforms
+> with the command `Split-Path $PROFILE`.
+
+### Configuration settings
+
+#### ExecutionPolicy
+
+Configures the execution policy for PowerShell sessions,
+determining what scripts can be run.
+See [About Execution Policies](./about_Execution_Policies.md).
+
+```Schema
+"<shell-id>:ExecutionPolicy": "<execution-policy>"
+```
+
+Where:
+
+- `<shell-id>` refers to the ID of the PowerShell host.
+  For normal PowerShell Core, this is `"Microsoft.PowerShell"`.
+- `<execution-policy>` refers to a valid execution policy name,
+  as described in [About Execution Policies](./about_Execution_Policies.md).
+
+Default setting: Uses the existing execution policy for the platform.
+See [About Execution Policies](./about_Execution_Policies.md).
+
+Example:
+
+```json
+{
+  "Microsoft.PowerShell.ExecutionPolicy": "RemoteSigned"
+}
+```
+
+Equivalent registry key in Windows PowerShell:
+
+```
+HKLM\SOFTWARE\Microsoft\PowerShell\1\ShellIds\Microsoft.PowerShell
+-AND-
+HKCU\SOFTWARE\Microsoft\PowerShell\1\ShellIds\Microsoft.PowerShell
+```
+
+#### ModulePath
+
+Sets the **PSModulePath** environment variable when
+PowerShell starts up.
+
+```Schema
+"PSModulePath": "<ps-module-path>"
+```
+
+Where:
+
+- `<ps-module-path>` is the **PSModulePath**
+  value you would use for `$env:PSModulePath`.
+
+Default setting:
+
+```
+$env:ProgramFiles/PowerShell/Modules
+```
+
+Examples:
+
+```json
+{
+  "PSModulePath": "C:\\Users\\Bruce McNamara\\PowerShell\\Modules"
+}
+```
+
+```json
+{
+  "PSModulePath": "/home/me/.local/share/powershell/Modules"
+}
+```
+
+Equivalent registry key in Windows PowerShell:
+
+```
+HKLM:\System\CurrentControlSet\Control\Session Manager\Environment
+```
+
+### Examples
\ No newline at end of file

From 63b9f902a6f771590a5495ca39a2d3182b1afb68 Mon Sep 17 00:00:00 2001
From: Robert Holt <rjmholt_msft@outlook.com>
Date: Fri, 2 Nov 2018 19:16:13 -0700
Subject: [PATCH 02/15] Add ExperimentalFeatures heading

---
 .../About/about_PowerShell_Config.md             | 16 ++++++++++------
 1 file changed, 10 insertions(+), 6 deletions(-)

diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md b/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md
index 3bf508413df7..03297ae5e0d9 100644
--- a/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md
+++ b/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md
@@ -14,12 +14,12 @@ Cross-platform configuration files for PowerShell Core.
 
 ## LONG DESCRIPTION
 
-A `powershell.config.json` file allows configuration of
+A `powershell.config.json` is a JSON-format file allowing configuration of
 installation-wide settings in PowerShell Core.
-These settings were previously configured in the Windows Registry
-in Windows PowerShell.
-The file is in the [JSON](https://en.wikipedia.org/wiki/JSON) format,
-with settings specified by key.
+It is read in and used when PowerShell starts up,
+but is also modified at runtime by PowerShell.
+These settings were previously configured
+in the Windows Registry in Windows PowerShell.
 
 > [!WARNING]
 > A `powershell.config.json` file that contains invalid JSON
@@ -66,8 +66,10 @@ See [About Execution Policies](./about_Execution_Policies.md).
 
 Where:
 
-- `<shell-id>` refers to the ID of the PowerShell host.
+- `<shell-id>` refers to the ID of the current PowerShell host.
   For normal PowerShell Core, this is `"Microsoft.PowerShell"`.
+  In any PowerShell session, you can discover it with `$ShellId`.
+  See also [About Automatic Variables](./about_Automatic_Variables.md).
 - `<execution-policy>` refers to a valid execution policy name,
   as described in [About Execution Policies](./about_Execution_Policies.md).
 
@@ -130,4 +132,6 @@ Equivalent registry key in Windows PowerShell:
 HKLM:\System\CurrentControlSet\Control\Session Manager\Environment
 ```
 
+### ExperimentalFeatures
+
 ### Examples
\ No newline at end of file

From d0b73cb1d3ecae8595a7eef54657635e968d8ab9 Mon Sep 17 00:00:00 2001
From: Robert Holt <rjmholt_msft@outlook.com>
Date: Sat, 10 Nov 2018 23:58:30 -0800
Subject: [PATCH 03/15] Add experimental feature documentation

---
 .../About/about_PowerShell_Config.md          | 35 +++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md b/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md
index 03297ae5e0d9..870ccecd1c2a 100644
--- a/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md
+++ b/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md
@@ -126,6 +126,10 @@ Examples:
 }
 ```
 
+> [!NOTE]
+> You can use `/` or `\` as a directory separator for this value
+> just like you would for the `$env:PSModulePath` environment variable.
+
 Equivalent registry key in Windows PowerShell:
 
 ```
@@ -134,4 +138,35 @@ HKLM:\System\CurrentControlSet\Control\Session Manager\Environment
 
 ### ExperimentalFeatures
 
+The names of the experimental features to enable in PowerShell.
+Include experimental feature names here to ensure they are
+in effect when PowerShell starts up.
+
+For more information on experimental features,
+see [PowerShell RFC 29](https://github.com/PowerShell/PowerShell-RFC/blob/master/5-Final/RFC0029-Support-Experimental-Features.md).
+
+```Schema
+"ExperimentalFeatures": [<experimental-feature-name>, ...]
+```
+
+Where:
+
+- `<experimental-feature-name>` is a string,
+  the name of an experimental feature to enable.
+
+Default setting: An empty array (`[]`);
+no experimental features are enabled in Powershell by default.
+
+Example:
+
+```json
+
+{
+  "ExperimentalFeatures": [
+    "PSImplicitRemotingBatching",
+    "PSUseAbbreviationExpansion"
+  ]
+}
+```
+
 ### Examples
\ No newline at end of file

From 22cf627eee6379674d19fa6380f4881d0eac78e7 Mon Sep 17 00:00:00 2001
From: Robert Holt <rjmholt_msft@outlook.com>
Date: Sun, 11 Nov 2018 11:44:59 -0800
Subject: [PATCH 04/15] Change heading usage

---
 .../About/about_PowerShell_Config.md          | 64 ++++++++++++++-----
 1 file changed, 48 insertions(+), 16 deletions(-)

diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md b/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md
index 870ccecd1c2a..6e8a6278f07b 100644
--- a/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md
+++ b/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md
@@ -52,9 +52,9 @@ on UNIX-like platforms this is `$HOME/.config/powershell/`.
 > The user configuration directory can be found across platforms
 > with the command `Split-Path $PROFILE`.
 
-### Configuration settings
+## Configuration settings
 
-#### ExecutionPolicy
+### ExecutionPolicy
 
 Configures the execution policy for PowerShell sessions,
 determining what scripts can be run.
@@ -73,10 +73,12 @@ Where:
 - `<execution-policy>` refers to a valid execution policy name,
   as described in [About Execution Policies](./about_Execution_Policies.md).
 
-Default setting: Uses the existing execution policy for the platform.
+#### Default setting
+
+Uses the existing execution policy for the platform.
 See [About Execution Policies](./about_Execution_Policies.md).
 
-Example:
+#### Example
 
 ```json
 {
@@ -84,7 +86,7 @@ Example:
 }
 ```
 
-Equivalent registry key in Windows PowerShell:
+#### Equivalent registry key in Windows PowerShell
 
 ```
 HKLM\SOFTWARE\Microsoft\PowerShell\1\ShellIds\Microsoft.PowerShell
@@ -92,7 +94,7 @@ HKLM\SOFTWARE\Microsoft\PowerShell\1\ShellIds\Microsoft.PowerShell
 HKCU\SOFTWARE\Microsoft\PowerShell\1\ShellIds\Microsoft.PowerShell
 ```
 
-#### ModulePath
+### ModulePath
 
 Sets the **PSModulePath** environment variable when
 PowerShell starts up.
@@ -106,13 +108,13 @@ Where:
 - `<ps-module-path>` is the **PSModulePath**
   value you would use for `$env:PSModulePath`.
 
-Default setting:
+#### Default setting
 
 ```
 $env:ProgramFiles/PowerShell/Modules
 ```
 
-Examples:
+#### Examples
 
 ```json
 {
@@ -130,7 +132,7 @@ Examples:
 > You can use `/` or `\` as a directory separator for this value
 > just like you would for the `$env:PSModulePath` environment variable.
 
-Equivalent registry key in Windows PowerShell:
+#### Equivalent registry key in Windows PowerShell
 
 ```
 HKLM:\System\CurrentControlSet\Control\Session Manager\Environment
@@ -146,21 +148,21 @@ For more information on experimental features,
 see [PowerShell RFC 29](https://github.com/PowerShell/PowerShell-RFC/blob/master/5-Final/RFC0029-Support-Experimental-Features.md).
 
 ```Schema
-"ExperimentalFeatures": [<experimental-feature-name>, ...]
+"ExperimentalFeatures": ["<experimental-feature-name>", ...]
 ```
 
 Where:
 
-- `<experimental-feature-name>` is a string,
-  the name of an experimental feature to enable.
+- `<experimental-feature-name>` is the name of an experimental feature to enable.
+
+#### Default setting
 
-Default setting: An empty array (`[]`);
+An empty array (`[]`);
 no experimental features are enabled in Powershell by default.
 
-Example:
+#### Example
 
 ```json
-
 {
   "ExperimentalFeatures": [
     "PSImplicitRemotingBatching",
@@ -169,4 +171,34 @@ Example:
 }
 ```
 
-### Examples
\ No newline at end of file
+### LogIdentity
+
+> [!IMPORTANT]
+> This setting can only be used in macOS and Linux.
+
+Sets the identity name used to write to [syslog](https://en.wikipedia.org/wiki/Syslog).
+
+```Schema
+"LogIdentity": "<log-identity>"
+```
+
+Where:
+
+- `<log=identity>` is the string identity that PowerShell should use
+  for writing to syslog.
+
+#### Default setting
+
+```
+"powershell"
+```
+
+#### Example
+
+```json
+{
+  "LogIdentity": "dev-powershell"
+}
+```
+
+### Example Configurations
\ No newline at end of file

From 128772bb22bc94ce79261a7bd3b911f3fd253405 Mon Sep 17 00:00:00 2001
From: Robert Holt <rjmholt_msft@outlook.com>
Date: Sun, 11 Nov 2018 11:54:37 -0800
Subject: [PATCH 05/15] Add headers for remaining configuration topics

---
 .../About/about_PowerShell_Config.md          | 24 ++++++++++++++++++-
 1 file changed, 23 insertions(+), 1 deletion(-)

diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md b/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md
index 6e8a6278f07b..d94614ee0a22 100644
--- a/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md
+++ b/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md
@@ -52,7 +52,7 @@ on UNIX-like platforms this is `$HOME/.config/powershell/`.
 > The user configuration directory can be found across platforms
 > with the command `Split-Path $PROFILE`.
 
-## Configuration settings
+## General configuration settings
 
 ### ExecutionPolicy
 
@@ -171,6 +171,8 @@ no experimental features are enabled in Powershell by default.
 }
 ```
 
+## Non-Windows logging configuration
+
 ### LogIdentity
 
 > [!IMPORTANT]
@@ -201,4 +203,24 @@ Where:
 }
 ```
 
+### LogLevel
+
+### LogChannels
+
+### LogKeywords
+
+## Group policy configuration
+
+### ScriptExecution
+
+### ScriptBlockLogging
+
+### ProtectedEventLogging
+
+### Transcription
+
+### UpdateableHelp
+
+### ConsoleSessionConfiguration
+
 ### Example Configurations
\ No newline at end of file

From 8ff703f1f94212aa145155b2cb06eb6d4e3817e5 Mon Sep 17 00:00:00 2001
From: Robert Holt <rjmholt_msft@outlook.com>
Date: Sun, 11 Nov 2018 22:30:45 -0800
Subject: [PATCH 06/15] Add logging configuration information

---
 .../About/about_PowerShell_Config.md          | 168 +++++++++++++++++-
 1 file changed, 160 insertions(+), 8 deletions(-)

diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md b/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md
index d94614ee0a22..923bebbd3274 100644
--- a/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md
+++ b/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md
@@ -60,6 +60,10 @@ Configures the execution policy for PowerShell sessions,
 determining what scripts can be run.
 See [About Execution Policies](./about_Execution_Policies.md).
 
+> [!NOTE]
+> The [`Set-ExecutionPolicy`](../../Microsoft.PowerShell.Security/Set-ExecutionPolicy.md)
+> cmdlet will modify this setting in the configuration file.
+
 ```Schema
 "<shell-id>:ExecutionPolicy": "<execution-policy>"
 ```
@@ -67,7 +71,7 @@ See [About Execution Policies](./about_Execution_Policies.md).
 Where:
 
 - `<shell-id>` refers to the ID of the current PowerShell host.
-  For normal PowerShell Core, this is `"Microsoft.PowerShell"`.
+  For normal PowerShell Core, this is `Microsoft.PowerShell`.
   In any PowerShell session, you can discover it with `$ShellId`.
   See also [About Automatic Variables](./about_Automatic_Variables.md).
 - `<execution-policy>` refers to a valid execution policy name,
@@ -80,6 +84,8 @@ See [About Execution Policies](./about_Execution_Policies.md).
 
 #### Example
 
+This sets the execution policy of PowerShell to `RemoteSigned`.
+
 ```json
 {
   "Microsoft.PowerShell.ExecutionPolicy": "RemoteSigned"
@@ -116,21 +122,31 @@ $env:ProgramFiles/PowerShell/Modules
 
 #### Examples
 
+This is a simple PSModulePath configuration
+in a Windows environment:
+
 ```json
 {
-  "PSModulePath": "C:\\Users\\Bruce McNamara\\PowerShell\\Modules"
+  "PSModulePath": "C:\\Users\\Bruce McNamara\\PowerShell\\Modules;C:\\Program Files\\PowerShell\\6\\Modules"
 }
 ```
 
+This is a simple PSModulePath configuration
+in a macOS or Linux environment:
+
 ```json
 {
-  "PSModulePath": "/home/me/.local/share/powershell/Modules"
+  "PSModulePath": "/home/me/.local/share/powershell/Modules:/opt/powershell/6/Modules"
 }
 ```
 
 > [!NOTE]
-> You can use `/` or `\` as a directory separator for this value
-> just like you would for the `$env:PSModulePath` environment variable.
+> When configuring the module path in this way,
+> you should use the appropriate directory and path separator characters for the platform.
+> You can discover these from PowerShell:
+>
+> - Directory separator character: `[System.IO.Path]::DirectorySeparatorChar`
+> - Path separator character: `[System.IO.Path]::PathSeparator`
 
 #### Equivalent registry key in Windows PowerShell
 
@@ -162,6 +178,10 @@ no experimental features are enabled in Powershell by default.
 
 #### Example
 
+This setting enables the `PSImplicitRemoting`
+and `PSUseAbbreviationExpansion` experimental features
+when PowerShell starts up.
+
 ```json
 {
   "ExperimentalFeatures": [
@@ -173,12 +193,22 @@ no experimental features are enabled in Powershell by default.
 
 ## Non-Windows logging configuration
 
+> [!IMPORTANT]
+> The configuration options in this section only apply to macOS and Linux.
+> Logging configuration on Windows is handled by the ETW Event Viewer.
+
+PowerShell's logging on macOS and Linux can be configured
+in the PowerShell configuration file.
+For a full description of logging in PowerShell, see [About Logging](./about_Logging.md).
+More information on logging configuration on non-Windows platforms
+can be found in [About Logging - Configuring Logging on non-Windows system](./about_Logging.md#configuring-logging-on-non-windows-system).
+
 ### LogIdentity
 
 > [!IMPORTANT]
 > This setting can only be used in macOS and Linux.
 
-Sets the identity name used to write to [syslog](https://en.wikipedia.org/wiki/Syslog).
+Sets the identity name used to write to the system log.
 
 ```Schema
 "LogIdentity": "<log-identity>"
@@ -186,7 +216,7 @@ Sets the identity name used to write to [syslog](https://en.wikipedia.org/wiki/S
 
 Where:
 
-- `<log=identity>` is the string identity that PowerShell should use
+- `<log-identity>` is the string identity that PowerShell should use
   for writing to syslog.
 
 #### Default setting
@@ -199,16 +229,138 @@ Where:
 
 ```json
 {
-  "LogIdentity": "dev-powershell"
+  "LogIdentity": "powershell-preview"
 }
 ```
 
 ### LogLevel
 
+> [!IMPORTANT]
+> This setting can only be used in macOS and Linux.
+
+Specifies the minimum severity level at which PowerShell should log.
+
+```Schema
+"LogLevel": "<log-level>|default"
+```
+
+Where:
+
+- `<log-level>` is one of:
+  - `Always`
+  - `Critical`
+  - `Error`
+  - `Warning`
+  - `Informational`
+  - `Verbose`
+  - `Debug`
+
+> [!NOTE]
+> Setting a given log level in the list
+> will enable all log levels above it.
+
+Setting this setting to `"default"` will be interpreted as the default value.
+
+#### Default setting
+
+```
+"Informational"
+```
+
+#### Example
+
+```json
+{
+  "LogLevel": "Verbose"
+}
+```
+
 ### LogChannels
 
+> [!IMPORTANT]
+> This setting can only be used in macOS and Linux.
+
+Determines which logging channels are enabled.
+
+```Schema
+"LogChannels": "<log-channel>,..."
+```
+
+Where:
+
+- `<log-channel>` is one of:
+  - `Operational` (logs ordinary information about what PowerShell is doing)
+  - `Analytic` (intended for more diagnostic usage)
+
+Values for this field should be included in the same
+string and separated by a comma (`,`).
+
+#### Default setting
+
+```
+"Operational"
+```
+
+#### Example
+
+```json
+{
+  "LogChannels": "Operational,Analytic"
+}
+```
+
 ### LogKeywords
 
+> [!IMPORTANT]
+> This setting can only be used in macOS and Linux.
+
+> [!NOTE]
+> It is generally advised to leave this value unset
+> unless you are trying to diagnose a specific behavior
+> in a known part of PowerShell's functionality.
+> Setting this value can only decrease the amount of information logged.
+
+Sets which log keywords should be enabled.
+This allows control over which parts of PowerShell are logged and which are not.
+
+```Schema
+"LogKeywords": "<log-keyword>,..."
+```
+
+Where:
+
+- `<log-keyword>` is one of:
+  - `Runspace` (runspace management)
+  - `Pipeline` (pipeline operations)
+  - `Protocol` (communication protocol handling, such as PSRP)
+  - `Transport` (transport layer support, such as SSH)
+  - `Host` (PowerShell host functionality, for example console interaction)
+  - `Cmdlets` (PowerShell builtin cmdlets)
+  - `Serializer` (serialization logic)
+  - `Session` (PowerShell session state)
+  - `ManagedPlugin` (WSMan plugin)
+
+Values for this field should be composed within the string with a comma (`,`).
+
+#### Default value
+
+The default value for this field is all keywords:
+
+```
+"Runspace,Pipeline,Protocol,Transport,Host,Cmdlets,Serializer,Session,ManagedPlugin"
+```
+
+#### Example
+
+This setting will mean that only logging from
+runspace operations, pipeline logic and cmdlet use
+will be written to the logs.
+All other logging will be omitted.
+
+```json
+"LogKeywords": "Runspace,Pipeline,Cmdlets"
+```
+
 ## Group policy configuration
 
 ### ScriptExecution

From 55cfec3ea61784a351c2db2acab585880a1e1a46 Mon Sep 17 00:00:00 2001
From: Robert Holt <rjmholt_msft@outlook.com>
Date: Wed, 28 Nov 2018 11:55:33 -0800
Subject: [PATCH 07/15] Comment out GPO settings

---
 .../About/about_PowerShell_Config.md                         | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md b/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md
index 923bebbd3274..1d882cc25bc2 100644
--- a/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md
+++ b/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md
@@ -361,6 +361,7 @@ All other logging will be omitted.
 "LogKeywords": "Runspace,Pipeline,Cmdlets"
 ```
 
+<!--
 ## Group policy configuration
 
 ### ScriptExecution
@@ -375,4 +376,6 @@ All other logging will be omitted.
 
 ### ConsoleSessionConfiguration
 
-### Example Configurations
\ No newline at end of file
+-->
+
+### Example Configurations

From f04f1f1f184bc9e2c453a7adfa009fdbb446b8ec Mon Sep 17 00:00:00 2001
From: Robert Holt <roholt@microsoft.com>
Date: Fri, 14 Dec 2018 11:38:44 -0800
Subject: [PATCH 08/15] Add examples

---
 .../About/about_PowerShell_Config.md          | 63 ++++++++++++++++++-
 1 file changed, 61 insertions(+), 2 deletions(-)

diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md b/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md
index 1d882cc25bc2..782e729b1c60 100644
--- a/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md
+++ b/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md
@@ -375,7 +375,66 @@ All other logging will be omitted.
 ### UpdateableHelp
 
 ### ConsoleSessionConfiguration
-
 -->
 
-### Example Configurations
+### Example configurations
+
+#### Basic configuration with execution policyfor
+
+This PowerShell configuration sets the execution policy to `Bypass`
+and leaves all other configurations as default.
+
+For example, this configuration will leave the `"LogIdentity"` setting as `"powershell"`.
+
+```json
+{
+  "Microsoft.PowerShell.ExecutionPolicy": "Bypass"
+}
+```
+
+#### Fuller configuration settings (Windows)
+
+This configuration has more settings explicitly set:
+
+- Execution policy for this PowerShell installation is `AllSigned`
+- The module path is set to include three module directories
+- The `PSImplicitRemotingBatching` experimental feature is enabled
+
+> [!NOTE]
+> The `ExecutionPolicy` and `PSModulePath` settings here would only work on a Windows platform,
+> since the module path uses `\` and `;` separator characters
+> and the execution policy is not `Unrestricted` (the only policy allowed on UNIX-like platforms).
+
+```json
+{
+  "Microsoft.PowerShell.ExecutionPolicy": "AllSigned",
+  "PSModulePath": "C:\\Users\\Marisol Briggs\\Documents\\PowerShell\\Modules;C:\\Shared\\Modules;C:\\Program Files\\PowerShell\\6\\Modules",
+  "ExperimentalFeatures": ["PSImplicitRemotingBatching"],
+}
+```
+
+#### Fuller configuration settings (UNIX-like)
+
+This configuration sets a number of options
+that will only work in macOS or Linux:
+
+- The module path has three module directories on it.
+- The `PSImplicitRemotingBatching` experimental feature is enabled
+- The PowerShell logging level is set to `Verbose`, for more logging
+- When this PowerShell installation writes to the logs,
+  it will use the `"home-powershell"` identity.
+
+> [!NOTE]
+> In addition to the platform-specific settings,
+> the use of `/` and `:` as separator characters in the `"PSModulePath"` configuration
+> mean it will only be useful on a macOS or Linux platform
+> (likely Linux, given the directory structure).
+
+```json
+{
+  "PSModulePath": "/home/bjessup/.config/powershell/Modules:/mnt/sparedrive/PowerShellModules:/opt/microsoft/powershell/Modules",
+  "ExperimentalFeatures": ["PSImplicitRemotingBatching"],
+  "LogLevel": "Verbose",
+  "LogIdentity": "home-powershell"
+}
+```
\ No newline at end of file

From 7a1c2ca31aa026f08e9381f4e1e4ed1488503722 Mon Sep 17 00:00:00 2001
From: Robert Holt <roholt@microsoft.com>
Date: Fri, 14 Dec 2018 12:01:33 -0800
Subject: [PATCH 09/15] Add special document folder hack

---
 .../About/about_PowerShell_Config.md                          | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md b/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md
index 782e729b1c60..21a874d972d0 100644
--- a/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md
+++ b/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md
@@ -45,12 +45,12 @@ Configuration of PowerShell can also be provided on a per-user basis.
 This applies configuration settings to a specific user.
 For this, the configuration file can be found in the user-scope
 configuration directory.
-On Windows this is `$env:LocalAppData\Microsoft\powershell`,
+On Windows this is `"$([System.Environment]::GetFolderPath("MyDocuments"))\Microsoft\powershell"`,
 on UNIX-like platforms this is `$HOME/.config/powershell/`.
 
 > [!TIP]
 > The user configuration directory can be found across platforms
-> with the command `Split-Path $PROFILE`.
+> with the command `Split-Path $PROFILE.CurrentUserCurrentHost`.
 
 ## General configuration settings
 

From fb60c2198a6c9185363e32d4c99a71d647c93491 Mon Sep 17 00:00:00 2001
From: Sean Wheeler <sean.wheeler@microsoft.com>
Date: Fri, 14 Dec 2018 13:58:35 -0800
Subject: [PATCH 10/15] Editorial changes

@rjmholt Please review these changes.
---
 .../About/about_PowerShell_Config.md          | 288 ++++++------------
 1 file changed, 99 insertions(+), 189 deletions(-)

diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md b/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md
index 21a874d972d0..5bc6833917d2 100644
--- a/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md
+++ b/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md
@@ -9,30 +9,25 @@ title:  about_PowerShell_Config
 # About PowerShell Config
 
 ## SHORT DESCRIPTION
-
 Cross-platform configuration files for PowerShell Core.
 
 ## LONG DESCRIPTION
 
-A `powershell.config.json` is a JSON-format file allowing configuration of
-installation-wide settings in PowerShell Core.
-It is read in and used when PowerShell starts up,
-but is also modified at runtime by PowerShell.
-These settings were previously configured
-in the Windows Registry in Windows PowerShell.
+The `powershell.config.json` file contains configuration settings for
+PowerShell Core. PowerShell loads this configuration at startup. The settings
+can also be modified at runtime. Previously, these settings were stored in the
+Windows Registry for Windows PowerShell.
 
 > [!WARNING]
-> A `powershell.config.json` file that contains invalid JSON
-> or unsupported keys or values will result in not being able
-> to start an interactive PowerShell session.
-> If this occurs, you will need to fix the configuration file
-> from another application to run PowerShell.
+> If the `powershell.config.json` file contains invalid JSON,
+> unsupported keys, or values, PowerShell cannot start an interactive session.
+> If this occurs, you must fix the configuration file.
 
 ### System-wide configuration
 
-A `powershell.config.json` file in the `$PSHOME` directory will apply
-to all PowerShell Core sessions running for that PowerShell Core
-installation.
+A `powershell.config.json` file in the `$PSHOME` directory defines the
+configuration for all PowerShell Core sessions running from that PowerShell
+Core installation.
 
 > [!NOTE]
 > The system `powershell.config.json` location is defined as
@@ -41,28 +36,21 @@ installation.
 
 ### User configurations
 
-Configuration of PowerShell can also be provided on a per-user basis.
-This applies configuration settings to a specific user.
-For this, the configuration file can be found in the user-scope
-configuration directory.
-On Windows this is `"$([System.Environment]::GetFolderPath("MyDocuments"))\Microsoft\powershell"`,
-on UNIX-like platforms this is `$HOME/.config/powershell/`.
-
-> [!TIP]
-> The user configuration directory can be found across platforms
-> with the command `Split-Path $PROFILE.CurrentUserCurrentHost`.
+You can also configure PowerShell on a per-user basis by placing the file in
+the user-scope configuration directory. The user configuration directory can
+be found across platforms with the command
+`Split-Path $PROFILE.CurrentUserCurrentHost`.
 
 ## General configuration settings
 
 ### ExecutionPolicy
 
-Configures the execution policy for PowerShell sessions,
-determining what scripts can be run.
-See [About Execution Policies](./about_Execution_Policies.md).
+Configures the execution policy for PowerShell sessions, determining what
+scripts can be run. By default, PowerShell uses the existing execution policy.
 
 > [!NOTE]
 > The [`Set-ExecutionPolicy`](../../Microsoft.PowerShell.Security/Set-ExecutionPolicy.md)
-> cmdlet will modify this setting in the configuration file.
+> cmdlet modifies this setting in the configuration file.
 
 ```Schema
 "<shell-id>:ExecutionPolicy": "<execution-policy>"
@@ -73,18 +61,9 @@ Where:
 - `<shell-id>` refers to the ID of the current PowerShell host.
   For normal PowerShell Core, this is `Microsoft.PowerShell`.
   In any PowerShell session, you can discover it with `$ShellId`.
-  See also [About Automatic Variables](./about_Automatic_Variables.md).
-- `<execution-policy>` refers to a valid execution policy name,
-  as described in [About Execution Policies](./about_Execution_Policies.md).
-
-#### Default setting
-
-Uses the existing execution policy for the platform.
-See [About Execution Policies](./about_Execution_Policies.md).
+- `<execution-policy>` refers to a valid execution policy name.
 
-#### Example
-
-This sets the execution policy of PowerShell to `RemoteSigned`.
+The following example sets the execution policy of PowerShell to `RemoteSigned`.
 
 ```json
 {
@@ -92,18 +71,14 @@ This sets the execution policy of PowerShell to `RemoteSigned`.
 }
 ```
 
-#### Equivalent registry key in Windows PowerShell
-
-```
-HKLM\SOFTWARE\Microsoft\PowerShell\1\ShellIds\Microsoft.PowerShell
--AND-
-HKCU\SOFTWARE\Microsoft\PowerShell\1\ShellIds\Microsoft.PowerShell
-```
+In Windows, the equivalent registry keys can be found in
+`\SOFTWARE\Microsoft\PowerShell\1\ShellIds\Microsoft.PowerShell` under
+`HKEY_LOCAL_MACHINE` and `HKEY_CURRENT_USER`.
 
 ### ModulePath
 
-Sets the **PSModulePath** environment variable when
-PowerShell starts up.
+Sets the **PSModulePath** environment variable when PowerShell starts up.
+The default value is `$env:ProgramFiles/PowerShell/Modules`.
 
 ```Schema
 "PSModulePath": "<ps-module-path>"
@@ -111,19 +86,11 @@ PowerShell starts up.
 
 Where:
 
-- `<ps-module-path>` is the **PSModulePath**
-  value you would use for `$env:PSModulePath`.
+- `<ps-module-path>` is the **PSModulePath** value you would use for
+  `$env:PSModulePath`.
 
-#### Default setting
-
-```
-$env:ProgramFiles/PowerShell/Modules
-```
-
-#### Examples
-
-This is a simple PSModulePath configuration
-in a Windows environment:
+This examples shows a minimal PSModulePath configuration for a Windows
+environment:
 
 ```json
 {
@@ -131,8 +98,8 @@ in a Windows environment:
 }
 ```
 
-This is a simple PSModulePath configuration
-in a macOS or Linux environment:
+This examples shows a minimal PSModulePath configuration for a macOS or Linux
+environment:
 
 ```json
 {
@@ -141,27 +108,17 @@ in a macOS or Linux environment:
 ```
 
 > [!NOTE]
-> When configuring the module path in this way,
-> you should use the appropriate directory and path separator characters for the platform.
-> You can discover these from PowerShell:
+> You must use the appropriate directory and path separator characters for the
+> platform. You can discover these from PowerShell:
 >
 > - Directory separator character: `[System.IO.Path]::DirectorySeparatorChar`
 > - Path separator character: `[System.IO.Path]::PathSeparator`
 
-#### Equivalent registry key in Windows PowerShell
-
-```
-HKLM:\System\CurrentControlSet\Control\Session Manager\Environment
-```
-
 ### ExperimentalFeatures
 
 The names of the experimental features to enable in PowerShell.
-Include experimental feature names here to ensure they are
-in effect when PowerShell starts up.
-
-For more information on experimental features,
-see [PowerShell RFC 29](https://github.com/PowerShell/PowerShell-RFC/blob/master/5-Final/RFC0029-Support-Experimental-Features.md).
+By default, no experimental features are enabled.
+The default value is an empty array.
 
 ```Schema
 "ExperimentalFeatures": ["<experimental-feature-name>", ...]
@@ -171,15 +128,8 @@ Where:
 
 - `<experimental-feature-name>` is the name of an experimental feature to enable.
 
-#### Default setting
-
-An empty array (`[]`);
-no experimental features are enabled in Powershell by default.
-
-#### Example
-
-This setting enables the `PSImplicitRemoting`
-and `PSUseAbbreviationExpansion` experimental features
+The following example enables the **PSImplicitRemoting**
+and **PSUseAbbreviationExpansion** experimental features
 when PowerShell starts up.
 
 ```json
@@ -191,24 +141,25 @@ when PowerShell starts up.
 }
 ```
 
+For more information on experimental features, see [PowerShell RFC 29][RFC0029].
+
 ## Non-Windows logging configuration
 
 > [!IMPORTANT]
 > The configuration options in this section only apply to macOS and Linux.
-> Logging configuration on Windows is handled by the ETW Event Viewer.
+> Logging for Windows is managed by the Windows Event Viewer.
 
 PowerShell's logging on macOS and Linux can be configured
 in the PowerShell configuration file.
-For a full description of logging in PowerShell, see [About Logging](./about_Logging.md).
-More information on logging configuration on non-Windows platforms
-can be found in [About Logging - Configuring Logging on non-Windows system](./about_Logging.md#configuring-logging-on-non-windows-system).
+For a full description of PowerShell logging for non-Windows systems, see [About Logging](./about_Logging.md).
 
 ### LogIdentity
 
 > [!IMPORTANT]
 > This setting can only be used in macOS and Linux.
 
-Sets the identity name used to write to the system log.
+Sets the identity name used to write to the system log. The default value is
+"powershell".
 
 ```Schema
 "LogIdentity": "<log-identity>"
@@ -219,13 +170,12 @@ Where:
 - `<log-identity>` is the string identity that PowerShell should use
   for writing to syslog.
 
-#### Default setting
-
-```
-"powershell"
-```
+> [!NOTE]
+> You may want to have different **LogIdentity** values for each different
+> instance of PowerShell you have installed.
 
-#### Example
+In this example, we are configuring the **LogIdentity** for a preview
+release of PowerShell.
 
 ```json
 {
@@ -247,27 +197,21 @@ Specifies the minimum severity level at which PowerShell should log.
 Where:
 
 - `<log-level>` is one of:
-  - `Always`
-  - `Critical`
-  - `Error`
-  - `Warning`
-  - `Informational`
-  - `Verbose`
-  - `Debug`
+  - Always
+  - Critical
+  - Error
+  - Warning
+  - Informational
+  - Verbose
+  - Debug
 
 > [!NOTE]
-> Setting a given log level in the list
-> will enable all log levels above it.
-
-Setting this setting to `"default"` will be interpreted as the default value.
-
-#### Default setting
+> Setting a the log level enables all log levels above it.
 
-```
-"Informational"
-```
+Setting this setting to **default** will be interpreted as the default value.
+The default value is **Informational**.
 
-#### Example
+The following example sets the value to **Verbose**.
 
 ```json
 {
@@ -289,19 +233,11 @@ Determines which logging channels are enabled.
 Where:
 
 - `<log-channel>` is one of:
-  - `Operational` (logs ordinary information about what PowerShell is doing)
-  - `Analytic` (intended for more diagnostic usage)
-
-Values for this field should be included in the same
-string and separated by a comma (`,`).
-
-#### Default setting
+  - Operational - logs basic information about PowerShell activities
+  - Analytic - logs more detailed diagnostic information
 
-```
-"Operational"
-```
-
-#### Example
+The default value is **Operational**. To enable both channels, include both
+values as a single comma-separated string. For example:
 
 ```json
 {
@@ -314,15 +250,8 @@ string and separated by a comma (`,`).
 > [!IMPORTANT]
 > This setting can only be used in macOS and Linux.
 
-> [!NOTE]
-> It is generally advised to leave this value unset
-> unless you are trying to diagnose a specific behavior
-> in a known part of PowerShell's functionality.
-> Setting this value can only decrease the amount of information logged.
-
-Sets which log keywords should be enabled.
-This allows control over which parts of PowerShell are logged and which are not.
-
+Determines which parts of PowerShell are logged. By default, all log keywords are enabled.
+To enable multiple keywords, list the values in a single comma-separated string.
 ```Schema
 "LogKeywords": "<log-keyword>,..."
 ```
@@ -330,32 +259,24 @@ This allows control over which parts of PowerShell are logged and which are not.
 Where:
 
 - `<log-keyword>` is one of:
-  - `Runspace` (runspace management)
-  - `Pipeline` (pipeline operations)
-  - `Protocol` (communication protocol handling, such as PSRP)
-  - `Transport` (transport layer support, such as SSH)
-  - `Host` (PowerShell host functionality, for example console interaction)
-  - `Cmdlets` (PowerShell builtin cmdlets)
-  - `Serializer` (serialization logic)
-  - `Session` (PowerShell session state)
-  - `ManagedPlugin` (WSMan plugin)
+  - Runspace - runspace management
+  - Pipeline - pipeline operations
+  - Protocol - communication protocol handling, such as PSRP
+  - Transport - transport layer support, such as SSH
+  - Host - PowerShell host functionality, for example console interaction
+  - Cmdlets -PowerShell builtin cmdlets
+  - Serializer - serialization logic
+  - Session - PowerShell session state
+  - ManagedPlugin - WSMan plugin
 
-Values for this field should be composed within the string with a comma (`,`).
-
-#### Default value
-
-The default value for this field is all keywords:
-
-```
-"Runspace,Pipeline,Protocol,Transport,Host,Cmdlets,Serializer,Session,ManagedPlugin"
-```
-
-#### Example
+> [!NOTE]
+> It is generally advised to leave this value unset
+> unless you are trying to diagnose a specific behavior
+> in a known part of PowerShell.
+> Changing this value only decreases the amount of information logged.
 
-This setting will mean that only logging from
-runspace operations, pipeline logic and cmdlet use
-will be written to the logs.
-All other logging will be omitted.
+This example limits the logging to runspace operations, pipeline logic, and
+cmdlet use. All other logging will be omitted.
 
 ```json
 "LogKeywords": "Runspace,Pipeline,Cmdlets"
@@ -377,22 +298,9 @@ All other logging will be omitted.
 ### ConsoleSessionConfiguration
 -->
 
-### Example configurations
-
-#### Basic configuration with execution policyfor
-
-This PowerShell configuration sets the execution policy to `Bypass`
-and leaves all other configurations as default.
-
-For example, this configuration will leave the `"LogIdentity"` setting as `"powershell"`.
-
-```json
-{
-  "Microsoft.PowerShell.ExecutionPolicy": "Bypass"
-}
-```
+## More example configurations
 
-#### Fuller configuration settings (Windows)
+### Example Windows configuration
 
 This configuration has more settings explicitly set:
 
@@ -413,28 +321,30 @@ This configuration has more settings explicitly set:
 }
 ```
 
-#### Fuller configuration settings (UNIX-like)
+### Example non-Windows configuration
 
-This configuration sets a number of options
-that will only work in macOS or Linux:
+This configuration sets a number of options that only work in macOS or Linux:
 
-- The module path has three module directories on it.
-- The `PSImplicitRemotingBatching` experimental feature is enabled
-- The PowerShell logging level is set to `Verbose`, for more logging
-- When this PowerShell installation writes to the logs,
-  it will use the `"home-powershell"` identity.
+- The module path contains three module directories
+- The **PSImplicitRemotingBatching** experimental feature is enabled
+- The PowerShell logging level is set to **Verbose**, for more logging
+- This PowerShell installation writes to the logs using the **home-powershell**
+  identity.
 
-> [!NOTE]
-> In addition to the platform-specific settings,
-> the use of `/` and `:` as separator characters in the `"PSModulePath"` configuration
-> mean it will only be useful on a macOS or Linux platform
-> (likely Linux, given the directory structure).
 
 ```json
 {
-  "PSModulePath": "/home/bjessup/.config/powershell/Modules:/mnt/sparedrive/PowerShellModules:/opt/microsoft/powershell/Modules",
+  "PSModulePath": "/home/bmcnamara/.config/powershell/Modules:/mnt/sparedrive/PowerShellModules:/opt/microsoft/powershell/Modules",
   "ExperimentalFeatures": ["PSImplicitRemotingBatching"],
   "LogLevel": "Verbose",
   "LogIdentity": "home-powershell"
 }
-```
\ No newline at end of file
+```
+
+## See also
+
+[About Execution Policies](./about_Execution_Policies.md)
+
+[About Automatic Variables](./about_Automatic_Variables.md)
+
+[RFC0029]: https://github.com/PowerShell/PowerShell-RFC/blob/master/5-Final/RFC0029-Support-Experimental-Features.md

From bd23ce4f3e780cc29e2e4f3e74257f8a1c4d81ac Mon Sep 17 00:00:00 2001
From: Dongbo Wang <dongbow@microsoft.com>
Date: Mon, 17 Dec 2018 09:23:58 -0800
Subject: [PATCH 11/15] Update
 reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md

Co-Authored-By: rjmholt <rjmholt@gmail.com>
---
 .../Microsoft.PowerShell.Core/About/about_PowerShell_Config.md  | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md b/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md
index 5bc6833917d2..013bb7b92622 100644
--- a/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md
+++ b/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md
@@ -30,7 +30,7 @@ configuration for all PowerShell Core sessions running from that PowerShell
 Core installation.
 
 > [!NOTE]
-> The system `powershell.config.json` location is defined as
+> The `$PSHOME` location is defined as
 > the same directory as the executing System.Management.Automation.dll
 > assembly. This applies to hosted PowerShell SDK instances as well.
 

From 0b6b10e8dfd32de6b5698140b6b111ba59b1d97e Mon Sep 17 00:00:00 2001
From: Robert Holt <roholt@microsoft.com>
Date: Mon, 17 Dec 2018 10:58:30 -0800
Subject: [PATCH 12/15] Fix up PSModulePath documentation

---
 .../About/about_PowerShell_Config.md          | 84 ++++++++++++++-----
 1 file changed, 61 insertions(+), 23 deletions(-)

diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md b/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md
index 013bb7b92622..0a1190ea9fb8 100644
--- a/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md
+++ b/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md
@@ -9,21 +9,27 @@ title:  about_PowerShell_Config
 # About PowerShell Config
 
 ## SHORT DESCRIPTION
-Cross-platform configuration files for PowerShell Core.
+
+Configuration files for PowerShell Core, replacing Registry configuration.
 
 ## LONG DESCRIPTION
 
-The `powershell.config.json` file contains configuration settings for
-PowerShell Core. PowerShell loads this configuration at startup. The settings
-can also be modified at runtime. Previously, these settings were stored in the
-Windows Registry for Windows PowerShell.
+The `powershell.config.json` file contains configuration settings for PowerShell Core.
+PowerShell loads this configuration at startup.
+The settings can also be modified at runtime.
+Previously, these settings were stored in the Windows Registry for Windows PowerShell,
+but are now contained in a file to enable configuration on macOS and Linux.
 
 > [!WARNING]
-> If the `powershell.config.json` file contains invalid JSON,
-> unsupported keys, or values, PowerShell cannot start an interactive session.
+> If the `powershell.config.json` file contains invalid JSON
+> PowerShell cannot start an interactive session.
 > If this occurs, you must fix the configuration file.
 
-### System-wide configuration
+> [!NOTE]
+> Unrecognized keys or invalid values in the configuration file
+> will be silently ignored.
+
+### AllUsers (shared) configuration
 
 A `powershell.config.json` file in the `$PSHOME` directory defines the
 configuration for all PowerShell Core sessions running from that PowerShell
@@ -34,7 +40,7 @@ Core installation.
 > the same directory as the executing System.Management.Automation.dll
 > assembly. This applies to hosted PowerShell SDK instances as well.
 
-### User configurations
+### CurrentUser (per-user) configurations
 
 You can also configure PowerShell on a per-user basis by placing the file in
 the user-scope configuration directory. The user configuration directory can
@@ -75,10 +81,19 @@ In Windows, the equivalent registry keys can be found in
 `\SOFTWARE\Microsoft\PowerShell\1\ShellIds\Microsoft.PowerShell` under
 `HKEY_LOCAL_MACHINE` and `HKEY_CURRENT_USER`.
 
-### ModulePath
+### PSModulePath
 
-Sets the **PSModulePath** environment variable when PowerShell starts up.
-The default value is `$env:ProgramFiles/PowerShell/Modules`.
+Overrides a PSModulePath component for this PowerShell session.
+If the configuration is for the current user, sets the CurrentUser module path.
+If the configuration is for all users, sets the AllUser module path.
+
+If no value is set, the default value for the respective module path component will be used.
+See [about_Modules](./about_Modules.md#module-and-dsc-resource-locations-and-psmodulepath)
+for more details on these defaults.
+
+This setting allows environment variables to be used by embedding them between `%` characters,
+like `"%HOME%\Documents\PowerShell\Modules"`, in the same way as CMD allows.
+This syntax also applies on Linux and macOS. See below for examples.
 
 ```Schema
 "PSModulePath": "<ps-module-path>"
@@ -86,33 +101,56 @@ The default value is `$env:ProgramFiles/PowerShell/Modules`.
 
 Where:
 
-- `<ps-module-path>` is the **PSModulePath** value you would use for
-  `$env:PSModulePath`.
+- `<ps-module-path>` is the absolute path to a module directory.
+  For all user configurations, this is the AllUsers shared module directory.
+  For current user configurations, this is CurrentUser module directory.
 
-This examples shows a minimal PSModulePath configuration for a Windows
+This example shows a PSModulePath configuration for a Windows
 environment:
 
 ```json
 {
-  "PSModulePath": "C:\\Users\\Bruce McNamara\\PowerShell\\Modules;C:\\Program Files\\PowerShell\\6\\Modules"
+  "PSModulePath": "C:\\Program Files\\PowerShell\\6\\Modules"
 }
 ```
 
-This examples shows a minimal PSModulePath configuration for a macOS or Linux
+This example shows a PSModulePath configuration for a macOS or Linux
 environment:
 
 ```json
 {
-  "PSModulePath": "/home/me/.local/share/powershell/Modules:/opt/powershell/6/Modules"
+  "PSModulePath": "/opt/powershell/6/Modules"
+}
+```
+
+This example shows embedding an environment variable in a PSModulePath configuration.
+Note that using the `HOME` environment variable and the `/` directory separator,
+this will work on Windows, macOS and Linux.
+
+```json
+{
+  "PSModulePath": "%HOME%/Documents/PowerShell/Modules"
 }
 ```
 
+This example shows embedding an environment variable in a PSModulePath configuration
+that will only work on macOS and Linux:
+
+```json
+{
+  "PSModulePath": "%XDG_CONFIG_HOME%/powershell/Modules"
+}
+```
+
+> [!NOTE]
+> PowerShell variables cannot be embedded in PSModulePath configurations.
+
+> [!NOTE]
+> PSModulePath configurations on Linux and macOS are case-sensitive.
+
 > [!NOTE]
-> You must use the appropriate directory and path separator characters for the
-> platform. You can discover these from PowerShell:
->
-> - Directory separator character: `[System.IO.Path]::DirectorySeparatorChar`
-> - Path separator character: `[System.IO.Path]::PathSeparator`
+> A PSModulePath configuration must use valid directory separators for the platform.
+> On macOS and Linux, this means `/`. On Windows, both `/` and `\` will work.
 
 ### ExperimentalFeatures
 

From 8c35973ea3827aa870398f074d6ac1cf51063aad Mon Sep 17 00:00:00 2001
From: Robert Holt <roholt@microsoft.com>
Date: Mon, 17 Dec 2018 11:19:14 -0800
Subject: [PATCH 13/15] Add execution policy note

---
 .../About/about_PowerShell_Config.md                | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md b/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md
index 0a1190ea9fb8..abe0810df189 100644
--- a/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md
+++ b/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md
@@ -51,12 +51,21 @@ be found across platforms with the command
 
 ### ExecutionPolicy
 
+> [!IMPORTANT]
+> This configuration only applies on Windows platforms.
+
 Configures the execution policy for PowerShell sessions, determining what
 scripts can be run. By default, PowerShell uses the existing execution policy.
 
+For AllUsers configurations, this sets the **LocalMachine** execution policy.
+For CurrentUser configurations, this sets the **CurrentUser** execution policy.
+
 > [!NOTE]
 > The [`Set-ExecutionPolicy`](../../Microsoft.PowerShell.Security/Set-ExecutionPolicy.md)
-> cmdlet modifies this setting in the configuration file.
+> cmdlet modifies this setting in the AllUsers configuration file
+> when invoked with `-Scope LocalMachine`,
+> and modifies this setting in the CurrentUser configuration file
+> when invoked with `-Scope CurrentUser`.
 
 ```Schema
 "<shell-id>:ExecutionPolicy": "<execution-policy>"
@@ -385,4 +394,4 @@ This configuration sets a number of options that only work in macOS or Linux:
 
 [About Automatic Variables](./about_Automatic_Variables.md)
 
-[RFC0029]: https://github.com/PowerShell/PowerShell-RFC/blob/master/5-Final/RFC0029-Support-Experimental-Features.md
+[RFC0029]: https://github.com/PowerShell/PowerShell-RFC/blob/master/5-Final/RFC0029-Support-Experimental-Features.md
\ No newline at end of file

From d64f0b5239d5ef5e70795489f8bd5cbadf82eca3 Mon Sep 17 00:00:00 2001
From: Sean Wheeler <sean.wheeler@microsoft.com>
Date: Mon, 17 Dec 2018 12:17:11 -0800
Subject: [PATCH 14/15] Formatting per About_ topic rules

---
 .../About/about_PowerShell_Config.md          | 82 ++++++++++---------
 1 file changed, 42 insertions(+), 40 deletions(-)

diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md b/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md
index abe0810df189..a3d5fcd5cba0 100644
--- a/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md
+++ b/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md
@@ -14,11 +14,11 @@ Configuration files for PowerShell Core, replacing Registry configuration.
 
 ## LONG DESCRIPTION
 
-The `powershell.config.json` file contains configuration settings for PowerShell Core.
-PowerShell loads this configuration at startup.
-The settings can also be modified at runtime.
-Previously, these settings were stored in the Windows Registry for Windows PowerShell,
-but are now contained in a file to enable configuration on macOS and Linux.
+The `powershell.config.json` file contains configuration settings for
+PowerShell Core. PowerShell loads this configuration at startup. The settings
+can also be modified at runtime. Previously, these settings were stored in the
+Windows Registry for Windows PowerShell, but are now contained in a file to
+enable configuration on macOS and Linux.
 
 > [!WARNING]
 > If the `powershell.config.json` file contains invalid JSON
@@ -92,17 +92,19 @@ In Windows, the equivalent registry keys can be found in
 
 ### PSModulePath
 
-Overrides a PSModulePath component for this PowerShell session.
-If the configuration is for the current user, sets the CurrentUser module path.
-If the configuration is for all users, sets the AllUser module path.
+Overrides a PSModulePath component for this PowerShell session. If the
+configuration is for the current user, sets the CurrentUser module path. If
+the configuration is for all users, sets the AllUser module path.
 
-If no value is set, the default value for the respective module path component will be used.
-See [about_Modules](./about_Modules.md#module-and-dsc-resource-locations-and-psmodulepath)
+If no value is set, the default value for the respective module path component
+will be used. See
+[about_Modules](./about_Modules.md#module-and-dsc-resource-locations-and-psmodulepath)
 for more details on these defaults.
 
-This setting allows environment variables to be used by embedding them between `%` characters,
-like `"%HOME%\Documents\PowerShell\Modules"`, in the same way as CMD allows.
-This syntax also applies on Linux and macOS. See below for examples.
+This setting allows environment variables to be used by embedding them between
+`%` characters, like `"%HOME%\Documents\PowerShell\Modules"`, in the same way
+as CMD allows. This syntax also applies on Linux and macOS. See below for
+examples.
 
 ```Schema
 "PSModulePath": "<ps-module-path>"
@@ -110,12 +112,11 @@ This syntax also applies on Linux and macOS. See below for examples.
 
 Where:
 
-- `<ps-module-path>` is the absolute path to a module directory.
-  For all user configurations, this is the AllUsers shared module directory.
-  For current user configurations, this is CurrentUser module directory.
+- `<ps-module-path>` is the absolute path to a module directory. For all user
+  configurations, this is the AllUsers shared module directory. For current
+  user configurations, this is CurrentUser module directory.
 
-This example shows a PSModulePath configuration for a Windows
-environment:
+This example shows a PSModulePath configuration for a Windows environment:
 
 ```json
 {
@@ -132,9 +133,9 @@ environment:
 }
 ```
 
-This example shows embedding an environment variable in a PSModulePath configuration.
-Note that using the `HOME` environment variable and the `/` directory separator,
-this will work on Windows, macOS and Linux.
+This example shows embedding an environment variable in a PSModulePath
+configuration. Note that using the `HOME` environment variable and the `/`
+directory separator, this will work on Windows, macOS and Linux.
 
 ```json
 {
@@ -142,8 +143,8 @@ this will work on Windows, macOS and Linux.
 }
 ```
 
-This example shows embedding an environment variable in a PSModulePath configuration
-that will only work on macOS and Linux:
+This example shows embedding an environment variable in a PSModulePath
+configuration that will only work on macOS and Linux:
 
 ```json
 {
@@ -153,13 +154,10 @@ that will only work on macOS and Linux:
 
 > [!NOTE]
 > PowerShell variables cannot be embedded in PSModulePath configurations.
-
-> [!NOTE]
-> PSModulePath configurations on Linux and macOS are case-sensitive.
-
-> [!NOTE]
-> A PSModulePath configuration must use valid directory separators for the platform.
-> On macOS and Linux, this means `/`. On Windows, both `/` and `\` will work.
+> PSModulePath configurations on Linux and macOS are case-sensitive. A
+> PSModulePath configuration must use valid directory separators for the
+> platform. On macOS and Linux, this means `/`. On Windows, both `/` and `\`
+> will work.
 
 ### ExperimentalFeatures
 
@@ -173,7 +171,8 @@ The default value is an empty array.
 
 Where:
 
-- `<experimental-feature-name>` is the name of an experimental feature to enable.
+- `<experimental-feature-name>` is the name of an experimental feature to
+  enable.
 
 The following example enables the **PSImplicitRemoting**
 and **PSUseAbbreviationExpansion** experimental features
@@ -196,9 +195,9 @@ For more information on experimental features, see [PowerShell RFC 29][RFC0029].
 > The configuration options in this section only apply to macOS and Linux.
 > Logging for Windows is managed by the Windows Event Viewer.
 
-PowerShell's logging on macOS and Linux can be configured
-in the PowerShell configuration file.
-For a full description of PowerShell logging for non-Windows systems, see [About Logging](./about_Logging.md).
+PowerShell's logging on macOS and Linux can be configured in the PowerShell
+configuration file. For a full description of PowerShell logging for
+non-Windows systems, see [About Logging](./about_Logging.md).
 
 ### LogIdentity
 
@@ -297,8 +296,10 @@ values as a single comma-separated string. For example:
 > [!IMPORTANT]
 > This setting can only be used in macOS and Linux.
 
-Determines which parts of PowerShell are logged. By default, all log keywords are enabled.
-To enable multiple keywords, list the values in a single comma-separated string.
+Determines which parts of PowerShell are logged. By default, all log keywords
+are enabled. To enable multiple keywords, list the values in a single
+comma-separated string.
+
 ```Schema
 "LogKeywords": "<log-keyword>,..."
 ```
@@ -356,9 +357,10 @@ This configuration has more settings explicitly set:
 - The `PSImplicitRemotingBatching` experimental feature is enabled
 
 > [!NOTE]
-> The `ExecutionPolicy` and `PSModulePath` settings here would only work on a Windows platform,
-> since the module path uses `\` and `;` separator characters
-> and the execution policy is not `Unrestricted` (the only policy allowed on UNIX-like platforms).
+> The `ExecutionPolicy` and `PSModulePath` settings here would only work on a
+> Windows platform, since the module path uses `\` and `;` separator characters
+> and the execution policy is not `Unrestricted` (the only policy allowed on
+> UNIX-like platforms).
 
 ```json
 {
@@ -394,4 +396,4 @@ This configuration sets a number of options that only work in macOS or Linux:
 
 [About Automatic Variables](./about_Automatic_Variables.md)
 
-[RFC0029]: https://github.com/PowerShell/PowerShell-RFC/blob/master/5-Final/RFC0029-Support-Experimental-Features.md
\ No newline at end of file
+[RFC0029]: https://github.com/PowerShell/PowerShell-RFC/blob/master/5-Final/RFC0029-Support-Experimental-Features.md

From 347d5e3e9a274d6413ccbb3dcd9eaa25a7f54df8 Mon Sep 17 00:00:00 2001
From: Robert Holt <roholt@microsoft.com>
Date: Mon, 17 Dec 2018 13:33:31 -0800
Subject: [PATCH 15/15] Correct examples, add warning about module scopes

---
 .../About/about_PowerShell_Config.md                | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md b/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md
index a3d5fcd5cba0..e48c7a64de08 100644
--- a/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md
+++ b/reference/6/Microsoft.PowerShell.Core/About/about_PowerShell_Config.md
@@ -96,6 +96,11 @@ Overrides a PSModulePath component for this PowerShell session. If the
 configuration is for the current user, sets the CurrentUser module path. If
 the configuration is for all users, sets the AllUser module path.
 
+> [!WARNING]
+> Configuring an AllUsers or CurrentUser module path here
+> will not change the scoped installation location for PowerShellGet modules like [Install-Module](https://docs.microsoft.com/en-us/powershell/module/powershellget/install-module).
+> These cmdlets always use the *default* module paths.
+
 If no value is set, the default value for the respective module path component
 will be used. See
 [about_Modules](./about_Modules.md#module-and-dsc-resource-locations-and-psmodulepath)
@@ -353,7 +358,7 @@ cmdlet use. All other logging will be omitted.
 This configuration has more settings explicitly set:
 
 - Execution policy for this PowerShell installation is `AllSigned`
-- The module path is set to include three module directories
+- The CurrentUser module path is set to a module directory on a shared drive
 - The `PSImplicitRemotingBatching` experimental feature is enabled
 
 > [!NOTE]
@@ -365,7 +370,7 @@ This configuration has more settings explicitly set:
 ```json
 {
   "Microsoft.PowerShell.ExecutionPolicy": "AllSigned",
-  "PSModulePath": "C:\\Users\\Marisol Briggs\\Documents\\PowerShell\\Modules;C:\\Shared\\Modules;C:\\Program Files\\PowerShell\\6\\Modules",
+  "PSModulePath": "Z:\\Marisol's Shared Drive\\Modules",
   "ExperimentalFeatures": ["PSImplicitRemotingBatching"],
 }
 ```
@@ -374,7 +379,7 @@ This configuration has more settings explicitly set:
 
 This configuration sets a number of options that only work in macOS or Linux:
 
-- The module path contains three module directories
+- The CurrentUser module path is set to a custom module directory in `$HOME`
 - The **PSImplicitRemotingBatching** experimental feature is enabled
 - The PowerShell logging level is set to **Verbose**, for more logging
 - This PowerShell installation writes to the logs using the **home-powershell**
@@ -383,7 +388,7 @@ This configuration sets a number of options that only work in macOS or Linux:
 
 ```json
 {
-  "PSModulePath": "/home/bmcnamara/.config/powershell/Modules:/mnt/sparedrive/PowerShellModules:/opt/microsoft/powershell/Modules",
+  "PSModulePath": "%HOME%/.powershell/Modules",
   "ExperimentalFeatures": ["PSImplicitRemotingBatching"],
   "LogLevel": "Verbose",
   "LogIdentity": "home-powershell"