Edits per comments from John Murray

Author: jstetson10

docs/Configuration.md

@@ -15,15 +15,15 @@ To work with VS Code, you need to open a workspace. A VS Code workspace can be j
 
 If you need to have more than one root folder in a VS Code workspace, use a feature called multi-root workspaces. See [Multi-root Workspaces](https://code.visualstudio.com/docs/editor/multi-root-workspaces) in the VS Code documentation.
 
-A multi root workspace contains a `*.code-workspace` file. The file can have any name followed by *.code-workspace*, for example `test.code-workspace`. The `*.code-workspace` file stores information about what folders are in the workspace. Other settings that would otherwise be stored in the settings.json or launch.json files can be stored in the `*.code-workspace` file. You can optionally have a workspace file even if you are not using the multi-root feature.
+A multi-root workspace is defined by a `*.code-workspace` file. The file can have any name followed by *.code-workspace*, for example `test.code-workspace`. The `*.code-workspace` file stores information about what folders are in the workspace, and may also store other settings that would otherwise be stored in the settings.json or launch.json files. Settings in a folder's `.vscode/settings.json` or `.vscode/launch.json` will override those in the `*.code-workspace` file, so be careful to use one or the other unless you truly need to leverage this flexibility. You can have a workspace file even if you are only working with a single root folder. Indeed, if you are [working server-side](../serverside/) you will always be using a workspace file.
 
-To edit a `*.code-workspace` file in VS Code using the **InterSystems ObjectScript** extension, select **File > Preferences > Settings** (**Code > Preferences > Settings** on Mac) and select the Workspace level. Search for **objectscript: conn**, and click on *Edit in settings.json*. VS Code opens the `*.code-workspace` file for that workspace.
+To edit **InterSystems ObjectScript** extension settings in a `*.code-workspace` file in VS Code, open the workspace using **File > Open Workspace...**, select **File > Preferences > Settings** (**Code > Preferences > Settings** on Mac) and select the Workspace tab. Search for **objectscript: conn**, and click on *Edit in settings.json*. VS Code opens the `*.code-workspace` file for that workspace.
 
-The **InterSystems ObjectScript** extension uses the multi-root workspaces feature to support ObjectScript development on the InterSystems server.
+The **InterSystems ObjectScript** extension uses the multi-root workspaces feature to support ObjectScript development directly in namespaces on InterSystems servers.
 
 ## Settings
 
-Many available settings are general to VS Code, and you can learn about them in the [Visual Studio Code Documentation](https://code.visualstudio.com/docs). The InterSystems Server Manager and InterSystems ObjectScript extensions supply additional settings you can use to define InterSystems IRIS servers and connections to those servers.
+Many available settings are general to VS Code, and you can learn about them in the [Visual Studio Code Documentation](https://code.visualstudio.com/docs). The InterSystems Server Manager, InterSystems ObjectScript, and InterSystems Language Server extensions supply additional settings you can use to define InterSystems IRIS servers and connections to those servers.
 
 There are several levels on which settings are stored and used:
 

docs/ExtensionUI.md

@@ -4,6 +4,7 @@ title: InterSystems Extensions UI
 permalink: /extensionui/
 nav_order: 3
 ---
+
 # InterSystems Extensions User Interface
 
 The InterSystems extensions add additional capability to the VS Code user interface to support development in ObjectScript. These additions are based on the standard VS Code UI, which is described in the section [User Interface](https://code.visualstudio.com/docs/getstarted/userinterface) in the VS Code documentation.
@@ -17,8 +18,8 @@ Select the Explorer view button in the Activity Bar to open the view.
 The Explorer view is a standard VS Code view. InterSystems extensions add the following items to context menus in the this view:
 
 - **Add Server Namespace to Workspace...** - in context menu of folders
-- **Import and Compile** - in context menu of folders and files
-- **Import Without Compilation** - in context menu of folders and files
+- **Import and Compile** - in context menu of folders and files when you are connected to an InterSystems server
+- **Import Without Compilation** - in context menu of folders and files when you are connected to an InterSystems server
 
 ## InterSystems Tools View
 
@@ -32,19 +33,19 @@ This view shows server resources in a tree format.
 
 ![Server tree view.](../assets/images/server-tree-view.png "server tree view")
 
-As you can see, the view groups servers into a variety of folders, such as currently in use, favorites, and recently used. Within the view, you can perform operations on the servers. When you move the cursor over a server listing, you see controls to mark the server as a favorite, and open the management portal for the server in either the simple browser in a VS Code tab, or an external browser:
+As you can see, the view groups servers into a variety of folders, such as currently in use, favorites, and recently used. Within the view, you can perform operations on the servers. When you move the cursor over a server listing, command buttons appear which let you mark the server as a favorite, or open the Management Portal for the server in either the simple browser in a VS Code tab or in an external browser:
 
 - ![Add to starred.](../assets/images/add-to-starred.png "add to starred")
-- ![Open management portal in tab.](../assets/images/management-portal-tab.png "open management portal the simple browser in VS Code")
-- ![Open management portal in browser.](../assets/images/management-portal-browser.png "open management portal in browser")
+- ![Open Management Portal in tab.](../assets/images/management-portal-tab.png "open management portal the simple browser in VS Code")
+- ![Open Management Portal in browser.](../assets/images/management-portal-browser.png "open management portal in browser")
 
-Notes About the VS Code Simple Browser
+#### Notes About the VS Code Simple Browser
 
 Only one Simple Browser tab can be open at a time, so launching a second server's Management Portal replaces the previous one.
 
 If the server version is InterSystems IRIS 2020.1.1 or later you need to change a setting on the suite of web applications that implement Management Portal. The Simple Browser is not be permitted to store the Portal's session management cookies, so the Portal must be willing to fall back to using the CSPCHD query parameter mechanism.
 
-In the management portal, select **System Administration > Security > Applications > Web Applications**. Enter `/csp/sys` in the **filter** field to find the five web applications whose path begins with `/csp/sys`.
+In Management Portal, select **System Administration > Security > Applications > Web Applications**. Enter `/csp/sys` in the **filter** field to find the five web applications whose path begins with `/csp/sys`.
 
 ![Portal web app list.](../assets/images/five-web-apps.png "portal web app list")
 
@@ -60,8 +61,8 @@ Expand the target server, then expand its **Namespaces**  folder. Hover over the
 
 ![Namespace edit buttons.](../assets/images/namespace-buttons.png "namespace edit buttons")
 
-- Click the **edit pencil** button to add an isfs://server:namespace/ folder to your VS Code workspace.
-- Click the **viewing eye** button to add an isfs-readonly://server:namespace/ folder to your VS Code workspace.
+- Click the **edit pencil** button to add an *isfs://server:namespace/* folder to your VS Code workspace.
+- Click the **viewing eye** button to add an *isfs-readonly://server:namespace/* folder to your VS Code workspace.
 - Hold the **alt** or **option** key while clicking the edit or view button to add a folder that gives you access to server-side web application files (for example, CSP files).
 
 Once you have added a server-side namespace to the workspace, VS Code opens the Explorer view showing the added namespace. The following screen shot shows the **Sample** and **User** packages in the **src** folder on the client, and the **Sample** and **User** packages in the **USER** namespace on the server, with read-only access.
@@ -80,11 +81,12 @@ You can use the plus sign (`+`) at the top of the view to add a server. This con
 
 The server definition is added to your user-level *settings.json* file and also appears at the top of the 'Recent' folder.
 
+{: #server-context-menu}
 ### Server Context Menu
 
 Servers listed in the InterSystems Tools view provide a context menu which provides access to several commands, including storing and clearing passwords in the keychain.
 
-![Server conext menu.](../assets/images/server-context-menu.png "server context menu")
+![Server context menu.](../assets/images/server-context-menu.png "server context menu")
 
 A submenu enables you to set the color of the icon to the left of the server name. The following screen shot shows this menu, and the icon color set to red.
 
@@ -98,7 +100,7 @@ On Windows, the Server Manager can create connection entries for all connections
 
 ## ObjectScript View
 
-The InterSystems ObjectScript extension supplies an ObjectScript view. The button to select this view appears in the Activity Bar only when a workspace or folder is open:
+The InterSystems ObjectScript extension supplies an ObjectScript view container. The button to select it appears in the Activity Bar only when a folder or a workspace that includes a client-side folder is open:
 
 ![ObjectScript button.](../assets/images/objectscript.png "objectscript button")
 
@@ -117,3 +119,14 @@ The ObjectScript view provides the following items:
 The InterSystems IRIS documentation section [Extending Studio](https://docs.intersystems.com/irislatest/csp/docbook/Doc.View.cls?KEY=ASC#ASC_Hooks_extending_studio ) describes how to configure menus for source code control and other purposes. Entries from menus named **%SourceMenu** and **%SourceContext** appear in the **Server Source Control...** quickpick provided the source control class doesn't disable the entry, for example, disabling checkout if it knows that the file is already checked out.
 
 Entries from menus with any other name appear in the **Server Command Menu...**.
+
+## Views and View Containers
+
+Technically the **InterSystems Tools** and **ObjectScript** entities described above are what VS Code calls [view containers](https://code.visualstudio.com/api/extension-capabilities/extending-workbench#view-container). Each contains a single view:
+
+- In container **InterSystems Tools** is view **Servers**
+- In container **ObjectScript** is view **Explorer**
+
+When a VS Code container has only a single view in it the view header merges with the container header, with the two names separated by a colon.
+
+Views can be dragged between containers, so for example you could move Explorer off its ObjectScript container and onto the InterSystems Tools container. Or move Servers onto the ObjectScript container. Or move either of them onto VS Code's main Explorer container.

docs/ServerSide.md

@@ -50,7 +50,7 @@ The `.code-workspace` file is a JSON file which you can edit directly, as descri
    - The value following `/` specifies the name of the server.
    - The value following `:` specifies the namespace (lowercase).
 
-The string `isfs` which appears in the **uri** for folders configured for server-side editing is an abbreviation created by InterSystems which stands for **InterSystems File Service**. It implements the VS Code [FileSystemProvider API](https://code.visualstudio.com/api/references/vscode-api#FileSystemProvider), which let's you make any remote location look like a local one. It was designed for common things like FTP servers, but it works well for making artefacts in an InterSystems IRIS database namespace look like local files.
+The string `isfs` which appears in the **uri** for folders configured for server-side editing is an abbreviation created by InterSystems which stands for **InterSystems File Service**. It implements the VS Code [FileSystemProvider API](https://code.visualstudio.com/api/references/vscode-api#FileSystemProvider), which let's you make any remote location look like a local one. It works well for making artefacts in an InterSystems IRIS database namespace look like local files.
 
 To add more root folders to your workspace, giving you access to code in a different namespace, or on a different server, use the context menu on your existing root folder to invoke the `Add Server Namespace to Workspace...` command. This command is also available on the Command Palette.