Revisions and improvements to server side section

Author: jstetson10

docs/ServerSide.md

@@ -4,55 +4,63 @@ title: Server-side Editing
 permalink: /serverside/
 nav_order: 5
 ---
-# VS Code Workspaces
+{: #code-workspaces}
+# VS Code Workspaces 
 
-To work with VS Code, you need to open a workspace. A VS Code workspace is usually just the root folder of your project. Workspace settings as well as debugging and task configurations are stored in the root folder in a folder called .vscode.
+To work with VS Code, you need to open a workspace. A VS Code workspace can be just the root folder of your project. Workspace settings as well as debugging and task configurations are stored in the root folder in a folder called .vscode.
 
 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 file 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 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.
 
-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 option. When you click **Edit in settings.json**, VS Code opens the *.code-workspace* file for that workspace.
+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.
 
 The **InterSystems ObjectScript** extension uses the multi-root workspaces feature to support ObjectScript development on the InterSystems server.
 
-# Server-side Source Control
+# Configuration for Server-side Editing
 
-You can configure the InterSystems ObjectScript extension to edit code directly on the server, using the [multi-root workspaces](https://code.visualstudio.com/docs/editor/multi-root-workspaces) VS Code feature. This type of configuration is useful in cases where source code is stored in a Source Code Management (SCM) product interfaced to the server. For example you might already be using the Source Control menu in InterSystems Studio or Portal, implemented by a source control class that extends `%Studio.SourceControl.Base`. 
+You can configure the InterSystems ObjectScript extension to edit code directly on the server, using the [multi-root workspaces](https://code.visualstudio.com/docs/editor/multi-root-workspaces) VS Code feature. This type of configuration is useful in cases where source code is stored in a Source Code Management (SCM) product interfaced to the server. For example you might already be using the Source Control menu in InterSystems Studio or Portal, implemented by a source control class that extends `%Studio.SourceControl.Base`.
 
 First configure the `intersystems.servers` entry for your server, as described in [Configuration](../configuration).
 
-Next create a workspace for editing code direct on the server:
+Next create a workspace for editing code directly on the server:
 
-1. Open VS Code. If a folder or workspace is already open, close it, for example by pressing <kbd>Ctrl/Cmd</kbd>+<kbd>K</kbd>, releasing that keypair, then pressing <kbd>F</kbd>.
+1. Open VS Code. You must perform the following steps starting with no folder or workspace open, so if a folder or workspace is already open, close it.
+1. Open the Explorer view if it is not already visible.
+1. Click the button labeled **Choose Server and Namespace** in the Explorer view, as shown in the following screen shot:
 
-2. Open the Explorer view (<kbd>Ctrl/Cmd</kbd>+<kbd>Shift</kbd>+<kbd>E</kbd>) if it is not already visible.
+    ![Explorer view.](../assets/images/ss-explorer-view.png "explorer view")
+1. Pick a server from the list, or click the **+** sign to create a new server configuration:
 
-3. When the button labeled "Choose Server and Namespace" appears, click it.
+   ![Choose a server.](../assets/images/ss-choose-server.png "choose a server")
+1. Enter credentials if prompted.
+1. Pick a namespace from the list retrieved from the target server:
 
-4. Pick a server from your `intersystems.servers` settings object, or create a new server configuration.
+   ![Choose a namespace.](../assets/images/ss-choose-namespace.png "choose a namespace")
+1. Pick an access mode from the list:
 
-5. Enter credentials if prompted.
+   ![Choose an access type.](../assets/images/ss-access-type.png "choose an access type")
+1. If you want to reopen this workspace in the future, use the command **File > Save Workspace As...** to save it as a `.code-workspace` file.
 
-6. Pick a namespace from the list retrieved from the target server.
+Note that the ObjectScript button is not vivible in the Activity Bar, because the files listed in the Explorer view are all on the server, so it is not needed for this configuration.
 
-7. Pick an access mode (Editable or Read-only).
-
-8. If you want to reopen this workspace in future, save it as a `.code-workspace` file.
-
-> Pro tip: The .code-workspace file you just created is a JSON file which can be edited directly. The Command Palette command `Preferences: Open Workspace Settings (JSON)` gets you there quickly. A simple example looks like this:
+The `.code-workspace` file is a JSON file which you can edit directly, as described in the section  [VS Code Workspaces](#code-workspaces). A simple example looks like this:
 ```json
 {
 	"folders": [
 		{
-			"name": "test:USER",
-			"uri": "isfs://test/?ns=USER"
+			"name": "iris184:USER",
+			"uri": "isfs://iris184/user"
 		}
 	],
 	"settings": {}
 }
 ```
-> The `name` property sets how the root folder is labeled and can be edited to suit your needs.
+- The `name` property provides a name for this server-side workspace.
+- The `uri` property indicates the location of resources on the server. The supplied value has three components:
+   - The first component can be either `isfs` or `isfs-readonly`. These values specify that this folder is on an InterSystems IRIS server. `isfs-readonly` specifies read-only access.
+   - The value following `://` specifies the name of the server.
+   - The value follosing `/` specifies the namespace.
 
 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.
 
@@ -61,12 +69,12 @@ An example of a two-folder workspace in which the second folder gives read-only
 {
 	"folders": [
 		{
-			"name": "test:USER",
-			"uri": "isfs://test/?ns=USER"
+			"name": "iris184:USER",
+			"uri": "isfs://iris184/user"
 		},
 		{
-			"name": "test:%SYS (read-only)",
-			"uri": "isfs-readonly://test/?ns=%SYS"
+			"name": "iris184:%SYS (read-only)",
+			"uri": "isfs-readonly://iris184/%sys"
 		}
 	],
 	"settings": {}