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

Author: chrisdias

api/advanced-topics/remote-extensions.md

@@ -1,6 +1,6 @@
 ---
 ContentId: 5c708951-e566-42db-9d97-e9715d95cdd1
-DateApproved: 3/22/2019
+DateApproved: 5/2/2019
 
 # Summarize the whole topic in less than 300 characters for SEO purpose
 MetaDescription: A guide to adding Visual Studio Code Remote Development support to extensions
@@ -73,7 +73,7 @@ You can edit and debug your extension in a container by following these steps.
 
 4. Run **Remote-Containers: Reopen Folder in Container** and in a moment, VS Code will set up the container and connect. You can now edit your source code as you would in the local case.
 
-5. Finally, press `kbstyle(F5)` or use the **Debug view** to launch the extension and attach the debugger as you would locally. The window that appears will now contain your extension running inside this same container with the debugger attached to it.
+5. Finally, press `kbstyle(F5)` or use the **Debug view** to launch the extension and attach the debugger as you would locally. The window that appears now contains your extension running inside this same container with the debugger attached to it.
 
 #### Using SSH or WSL
 
@@ -83,7 +83,7 @@ You can edit and debug your extension on a remote [SSH host](/docs/remote/ssh) o
 
 2. Once the folder is open on the SSH host / in WSL, you can edit your source code as you would in the local case.
 
-3. Finally, press `kbstyle(F5)` or use the **Debug view** to launch the extension and attach the debugger as you would locally. The window that appears will now contain your extension running on the SSH Host / in WSL with the debugger attached to it.
+3. Finally, press `kbstyle(F5)` or use the **Debug view** to launch the extension and attach the debugger as you would locally. The window that appears now contains your extension running on the SSH Host / in WSL with the debugger attached to it.
 
 ## Common problems
 
@@ -263,7 +263,7 @@ export async function activate(context: vscode.ExtensionContext) {
 
 ### Communicating between extensions using commands
 
-Some extensions return APIs as a part of their activation function that are intended for other extensions to use (via `vscode.extension.getExtension(extensionName).exports`). While these will work if all extensions involved are on the same side (either all UI Extensions or all Workspace Extensions), these will not work between UI and Workspace Extensions.
+Some extensions return APIs as a part of their activation that are intended for other extensions to use (via `vscode.extension.getExtension(extensionName).exports`). While these will work if all extensions involved are on the same side (either all UI Extensions or all Workspace Extensions), these will not work between UI and Workspace Extensions.
 
 Fortunately, VS Code automatically routes any executed commands to the correct extension regardless of its location. You can freely invoke any command (including those provided by other extensions) without worrying about impacts.
 

docs/remote/containers.md

@@ -5,7 +5,7 @@ TOCTitle: Containers
 PageTitle: Developing inside a Container using Visual Studio Code Remote Development
 ContentId: 7ec8a02b-2eb7-45c1-bb16-ddeaac694ff6
 MetaDescription: Developing inside a Container using Visual Studio Code Remote Development
-DateApproved: 4/11/2019
+DateApproved: 5/2/2019
 ---
 # Developing inside a Container
 
@@ -115,17 +115,17 @@ The [vscode-dev-containers repository](https://aka.ms/vscode-dev-containers) has
 
 ### Configuration edit loop
 
-Editing your container configuration is easy. Since rebuilding a container will "reset" the container to its starting contents (with the exception of your local source code), VS Code does not automatically rebuild if you edit a container configuration file (`devcontainer.json`, `Dockerfile`, `docker-compose.yml`). Instead, there are some commands that can be used to make editing your config easier.
+Editing your container configuration is easy. Since rebuilding a container will "reset" the container to its starting contents (with the exception of your local source code), VS Code does not automatically rebuild if you edit a container configuration file (`devcontainer.json`, `Dockerfile`, `docker-compose.yml`). Instead, there are some commands that can be used to make editing your configuration easier.
 
 Here is the typical edit loop using these commands:
 
 1. Start with `kbstyle(F1)` > **Remote-Containers: Create Container Configuration File...**
 2. Edit the contents of the `.devcontainer` folder as required.
-3. Try it with `kbstyle(F1)` > **Remote-Containers: Reopen folder in Container**.
+3. Try it with `kbstyle(F1)` > **Remote-Containers: Reopen Folder in Container**.
 4. On failure:
    1. `kbstyle(F1)` > **Remote-Containers: Reopen Folder Locally** which will open a new local window.
    2. In this local window: Edit the contents of the `.devcontainer` folder as required.
-   3. Try it again: Go back to the container window, `kbstyle(F1)` > **Remote-Containers: Reload Window**.
+   3. Try it again: Go back to the container window, `kbstyle(F1)` > **Developer: Reload Window**.
    4. Repeat as needed.
 5. If the build was successful, but you want to make more changes:
       1. Edit the contents of the `.devcontainer` folder as required when connected to the container.

docs/remote/faq.md

@@ -5,7 +5,7 @@ TOCTitle: FAQ
 PageTitle: Visual Studio Code Remote Development Frequently Asked Questions
 ContentId: 66bc3337-5fe1-4dac-bde1-a9302ff4c0cb
 MetaDescription: Visual Studio Code Remote Development Frequently Asked Questions (FAQ) for SSH, Containers, and WSL
-DateApproved: 4/11/2019
+DateApproved: 5/2/2019
 ---
 # Remote Development FAQ
 

docs/remote/remote-overview.md

@@ -5,11 +5,11 @@ TOCTitle: Overview
 PageTitle: Visual Studio Code Remote Development
 ContentId: eceea3f0-feee-47c2-8b65-1f1b0825355b
 MetaDescription: Visual Studio Code Remote Development
-DateApproved: 1/30/2019
+DateApproved: 5/2/2019
 ---
 # VS Code Remote Development
 
-VS Code Remote Development allows you to use a container, remote machine, or the [Windows Subsystem for Linux (WSL)](https://docs.microsoft.com/windows/wsl) as a full-featured development environment. You can:
+Visual Studio Code Remote Development allows you to use a container, remote machine, or the [Windows Subsystem for Linux (WSL)](https://docs.microsoft.com/windows/wsl) as a full-featured development environment. You can:
 
 - Develop on the **same operating system** you deploy to or use **larger or more specialized** hardware.
 - **Sandbox** your development environment to avoid impacting your local **machine configuration**.
@@ -37,6 +37,6 @@ While most VS Code extensions should work unmodified in a remote environment, ex
 
 ## Questions or feedback
 
-- See [Tips and Tricks](https://aka.ms/vscode-remote/troubleshooting) or the [FAQ](/docs/remote/faq).
+- See [Tips and Tricks](/docs/remote/troubleshooting.md) or the [FAQ](/docs/remote/faq.md).
 - Search on [Stack Overflow](https://stackoverflow.com/questions/tagged/vscode).
 - Add a [feature request](https://aka.ms/vscode-remote/feature-requests) or [report a problem](https://aka.ms/vscode-remote/issues/new).

docs/remote/ssh.md

@@ -5,17 +5,17 @@ TOCTitle: SSH
 PageTitle: Developing on Remote Machines using SSH and Visual Studio Code
 ContentId: 42e65445-fb3b-4561-8730-bbd19769a160
 MetaDescription: Developing on Remote Machines or VMs using Visual Studio Code Remote Development and SSH
-DateApproved: 4/11/2019
+DateApproved: 5/2/2019
 ---
 # Remote Development using SSH
 
 The **Visual Studio Code Remote - SSH** extension allows you to open a remote folder on any remote machine, virtual machine, or container with a running SSH server and take full advantage of VS Code's feature set. Once connected to a server, you can interact with files and folders anywhere on the remote filesystem.
 
-Given **no source code needs to be on your local machine**, this approach provides dramatic performance and fidelity benefits over using network shares or synchronizing files.
+No source code needs to be on your local machine to gain these benefits since the extension runs commands and other extensions directly on the remote machine.
 
 ![SSH Architecture](images/ssh/architecture-ssh.png)
 
-The result is that VS Code can provide a **local-quality development experience** including full IntelliSense (completions), code navigation, and debugging, **regardless of where your code is hosted**.
+This lets VS Code provide a **local-quality development experience** — including full IntelliSense (completions), code navigation, and debugging — **regardless of where your code is hosted**.
 
 ## Getting started
 
@@ -25,7 +25,7 @@ To get started you need to:
 
 1. Install an [OpenSSH compatible SSH client](/docs/remote/troubleshooting.md#installing-a-supported-ssh-client) if one is not already present.
 
-    > **Note:** PuTTY is not supported on Windows since a `ssh` command must be in the path.
+    > **Note:** PuTTY is not supported on Windows since the `ssh` command must be in the path.
 
 2. Install [Visual Studio Code Insiders](https://code.visualstudio.com/insiders/).
 

docs/remote/troubleshooting.md

@@ -5,7 +5,7 @@ TOCTitle: Tips and Tricks
 PageTitle: Visual Studio Code Remote Development Troubleshooting Tips and Tricks
 ContentId: 42e65445-fb3b-4561-8730-bbd19769a160
 MetaDescription: Visual Studio Code Remote Development troubleshooting tips and tricks for SSH, Containers, and the Windows Subsystem for Linux (WSL)
-DateApproved: 4/11/2019
+DateApproved: 5/2/2019
 ---
 # Remote Development Tips and Tricks
 
@@ -547,18 +547,19 @@ 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. These issues can typically be resolved by adopting a VS Code API. 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.
+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 |
 |---------|-------------|------------|
-| **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 `vscode.env.openExternal` API will open a local browser 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. | Use the VS Code clipboard API. See [here for details](/api/advanced-topics/remote-extensions#using-the-clipboard). |
-| **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 `vscode.env.openExternal` API will automatically forward 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 your 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 you can use to solve this problem. See [here for details](/api/advanced-topics/remote-extensions#accessing-localhost). |
+| **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`. | Use the `context.globalStoragePath` or `context.storagePath` property instead. 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. | Use the `keytar` node module. 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.  | First, include (or dynamically acquire) both sets of binaries (Electron and standard Node.js) for the "modules" version in Node.js that VS Code ships. Next, check to see if `context.executionContext === vscode.ExtensionExecutionContext.Remote` in your activation function to set up the correct binaries based on whether the extension is running remotely or locally. See the [extension guide](/api/advanced-topics/remote-extensions#using-native-node.js-modules) for details. |
+| **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. |