Merge branch 'master' of https://github.com/Microsoft/vscode-docs-pr

Author: Chuxel

docs/remote/containers.md

@@ -318,7 +318,7 @@ COPY settings.vscode.json /root/.vscode-remote/data/Machine/settings.json
 
 There are a few different ways VS Code Remote - Containers can be used to develop an application inside a fully containerized environment. In general, there are two primary scenarios that drive interest in this development style:
 
-* [Stand-Alone Dev Sandboxes](#working-with-a-developer-sandbox): You may not be deploying your application into a containerized environment but still want to isolate your build and runtime environment from your local OS or develop in an environment that is more representative of production. For example, you may be running some code on your local macOS or Windows machine that is ultimately deployed to a Linux VM or server in production.
+* [Stand-Alone Dev Sandboxes](#working-with-a-developer-sandbox): You may not be deploying your application into a containerized environment but still want to isolate your build and runtime environment from your local OS or develop in an environment that is more representative of production. For example, you may be running code on your local macOS or Windows machine that will ultimately be deployed to a Linux VM or server.
 
 * **Container Deployed Applications**: You deploy your application into one or more containers and would like to work locally in the containerized environment. VS Code currently supports working with container-based applications defined in a number of ways:
 

docs/remote/troubleshooting.md

@@ -508,7 +508,9 @@ ENV APT_KEY_DONT_WARN_ON_DANGEROUS_USAGE=DontWarn
 
 ### Selecting the distribution used by Remote - WSL
 
-The Remote - WSL extension uses your **default distribution** which you can change using `wslconfig.exe`. For example:
+The Remote - WSL extension uses your **default distribution** which you can change using [wslconfig.exe](https://docs.microsoft.com/windows/wsl/wsl-config).
+
+For example:
 
 ```bat
 wslconfig /setdefault Ubuntu
@@ -544,21 +546,73 @@ Optionally, you can add the following contents to a `.gitattributes` file to for
 
 ## Extension tips
 
-While many extensions will work unmodified, there are a few issues that can prevent certain features from working as expected. In some cases you can use another command to work around the issue, while in others the extension may need to be modified. This section provides a quick reference for common issues and tips on resolving them. You can also refer to the main extension article on [Supporting Remote Development](/api/advanced-topics/remote-extensions) for an in-depth guide on modifying extensions when required.
-
-| Problem | Description | Resolution |
-|---------|-------------|------------|
-| **Local absolute path settings fail when applied remotely** | VS Code's local user settings are  reused when you connect to a remote endpoint. While this keeps your user experience consistent, you may need to vary absolute path settings between your local machine and each host / container / WSL since the target locations are different. | You can set endpoint specific settings after you connect to a a remote endpoint by running the **Preferences: Open Remote Settings** command from the Command Palette (`kbstyle(F1)`) or by clicking on the "Remote" tab in the settings editor. These settings will override any local settings you have in place whenever you connect.|
-| **Browser does not open locally** | Some extensions use external node modules or custom code to launch a browser window. Unfortunately, this may cause the extension to launch the browser remotely instead of locally. | The extension can switch to using the `vscode.env.openExternal` API to resolve this problem. See the [extension guide](/api/advanced-topics/remote-extensions#opening-something-in-a-local-browser-or-application) for details. |
-| **Clipboard does not work** | Some extensions use node modules like `clipboardy` to integrate with the clipboard. Unfortunately, this may cause the extension to incorrectly integrate with the clipboard on the remote side. | The extension can switch to the VS Code clipboard API to resolve the problem. See the [extension guide](/api/advanced-topics/remote-extensions#using-the-clipboard) for details. |
-| **Cannot access local web server from browser or application** | When working inside a container or SSH host, the port the browser is connecting to may be blocked. | The extension can switch to the  `vscode.env.openExternal` API (which automatically forwards localhost ports) to resolve this problem. See the [extension guide](/api/advanced-topics/remote-extensions#opening-something-in-a-local-browser-or-application) for details.  |
-| **WebView contents do not appear** | If the extension's WebView content uses an iframe to connect to a local web server, the port the WebView is connecting to may be blocked. | The WebView API now includes a `portMapping` property that the extension can use to solve this problem. See the [extension guide](/api/advanced-topics/remote-extensions#accessing-localhost) for details. |
-| **Blocked localhost ports** |  If you are trying to connect to a localhost port from an external application, the port may be blocked. | There currently is no API for extensions to programmatically forward arbitrary ports, but you can use the **Remote-Containers: Forward Port from Container...** or **Remote-SSH: Forward Port from Active Host...** to do so manually. |
-| **Errors storing extension data** | Extensions may try to persist global data by looking for the `~/.config/Code` folder on Linux. This folder may not exist, which can cause the extension to throw errors like `ENOENT: no such file or directory, open '/root/.config/Code/User/fileame-goes-here`. | Extensions can use the `context.globalStoragePath` or `context.storagePath` property to resolve this problem. See the [extension guide](/api/advanced-topics/remote-extensions#persisting-extension-data-or-state) for details. |
-| **Cannot sign in / have to sign in each time I connect to a new endpoint** | Extensions with a sign in may persist secrets using their own code. This code can fail due to missing dependencies. Even if it succeeds, the secrets will be stored remotely, which means you have to sign in for every new endpoint. | Extensions can use the `keytar` node module to solve this problem. See the [extension guide](/api/advanced-topics/remote-extensions#persisting-secrets) for details. |
-| **Extensions that ship or acquire pre-built native modules fail** | Native modules bundled with (or dynamically acquired for) a VS Code extension must be recompiled [using Electron's `electron-rebuild`](https://electronjs.org/docs/tutorial/using-native-node-modules). However, VS Code Server runs a standard (non-Electron) version of Node.js which can cause binaries to fail when used remotely.  | Extensions need to be modified to solve this problem. The will need to include (or dynamically acquire) both sets of binaries (Electron and standard Node.js) for the "modules" version in Node.js that VS Code ships and then check to see if `context.executionContext === vscode.ExtensionExecutionContext.Remote` in their activation function to set up the correct binaries. See the [extension guide](/api/advanced-topics/remote-extensions#using-native-node.js-modules) for details. |
-| **Cannot access / transfer remote workspace files to local machines** | Extensions that open workspace files in external applications may encounter errors because the external application cannot directly access the remote files. | We are investigating options for how extensions might be able to transfer files from the remote workspace to solve this problem. |
-| **Cannot access attached device from extension** | Extensions that access locally attached devices will be unable to connect to them when running remotely. | We are investigating the best approach to solve this problem. |
+While many extensions will work unmodified, there are a few issues that can prevent certain features from working as expected. In some cases, you can use another command to work around the issue, while in others the extension may need to be modified. This section provides a quick reference for common issues and tips on resolving them. You can also refer to the main extension article on [Supporting Remote Development](/api/advanced-topics/remote-extensions) for an in-depth guide on modifying extensions when required.
+
+### Local absolute path settings fail when applied remotely
+
+VS Code's local user settings are  reused when you connect to a remote endpoint. While this keeps your user experience consistent, you may need to vary absolute path settings between your local machine and each host / container / WSL since the target locations are different.
+
+Resolution: You can set endpoint specific settings after you connect to a a remote endpoint by running the **Preferences: Open Remote Settings** command from the Command Palette (`kbstyle(F1)`) or by clicking on the "Remote" tab in the settings editor. These settings will override any local settings you have in place whenever you connect.
+
+### Browser does not open locally
+
+Some extensions use external node modules or custom code to launch a browser window. Unfortunately, this may cause the extension to launch the browser remotely instead of locally.
+
+Resolution: The extension can switch to using the `vscode.env.openExternal` API to resolve this problem. See the [extension guide](/api/advanced-topics/remote-extensions#opening-something-in-a-local-browser-or-application) for details.
+
+### Clipboard does not work
+
+Some extensions use node modules like `clipboardy` to integrate with the clipboard. Unfortunately, this may cause the extension to incorrectly integrate with the clipboard on the remote side.
+
+Resolution: The extension can switch to the VS Code clipboard API to resolve the problem. See the [extension guide](/api/advanced-topics/remote-extensions#using-the-clipboard) for details.
+
+### Cannot access local web server from browser or application
+
+When working inside a container or SSH host, the port the browser is connecting to may be blocked.
+
+Resolution: The extension can switch to the  `vscode.env.openExternal` API (which automatically forwards localhost ports) to resolve this problem. See the [extension guide](/api/advanced-topics/remote-extensions#opening-something-in-a-local-browser-or-application) for details.
+
+### WebView contents do not appear
+
+If the extension's WebView content uses an iframe to connect to a local web server, the port the WebView is connecting to may be blocked.
+
+Resolution: The WebView API now includes a `portMapping` property that the extension can use to solve this problem. See the [extension guide](/api/advanced-topics/remote-extensions#accessing-localhost) for details.
+
+### Blocked localhost ports
+
+If you are trying to connect to a localhost port from an external application, the port may be blocked.
+
+Resolution: There currently is no API for extensions to programmatically forward arbitrary ports, but you can use the **Remote-Containers: Forward Port from Container...** or **Remote-SSH: Forward Port from Active Host...** to do so manually.
+
+### Errors storing extension data
+
+Extensions may try to persist global data by looking for the `~/.config/Code` folder on Linux. This folder may not exist, which can cause the extension to throw errors like `ENOENT: no such file or directory, open '/root/.config/Code/User/fileame-goes-here`.
+
+Resolution: Extensions can use the `context.globalStoragePath` or `context.storagePath` property to resolve this problem. See the [extension guide](/api/advanced-topics/remote-extensions#persisting-extension-data-or-state) for details.
+
+### Cannot sign in / have to sign in each time I connect to a new endpoint
+
+Extensions with a sign in may persist secrets using their own code. This code can fail due to missing dependencies. Even if it succeeds, the secrets will be stored remotely, which means you have to sign in for every new endpoint.
+
+Resolution: Extensions can use the `keytar` node module to solve this problem. See the [extension guide](/api/advanced-topics/remote-extensions#persisting-secrets) for details.
+
+### Extensions that ship or acquire pre-built native modules fail
+
+Native modules bundled with (or dynamically acquired for) a VS Code extension must be recompiled [using Electron's `electron-rebuild`](https://electronjs.org/docs/tutorial/using-native-node-modules). However, VS Code Server runs a standard (non-Electron) version of Node.js which can cause binaries to fail when used remotely.
+
+Resolution: Extensions need to be modified to solve this problem. The will need to include (or dynamically acquire) both sets of binaries (Electron and standard Node.js) for the "modules" version in Node.js that VS Code ships and then check to see if `context.executionContext === vscode.ExtensionExecutionContext.Remote` in their activation function to set up the correct binaries. See the [extension guide](/api/advanced-topics/remote-extensions#using-native-node.js-modules) for details.
+
+### Cannot access / transfer remote workspace files to local machines
+
+Extensions that open workspace files in external applications may encounter errors because the external application cannot directly access the remote files.
+
+Resolution: We are investigating options for how extensions might be able to transfer files from the remote workspace to solve this problem.
+
+### Cannot access attached device from extension
+
+Extensions that access locally attached devices will be unable to connect to them when running remotely.
+
+Resolution: We are investigating the best approach to solve this problem.
 
 ## Questions and feedback