Merge pull request #618 from intersystems-community/revise-serverside

Revise serverside

Author: isc-rsingh

docs/.vscode/settings.json

@@ -0,0 +1,7 @@
+{
+    "objectscript.conn": {
+        "server": "default~iris",
+        "ns": "USER",
+        "active": true
+    }
+}

docs/Configuration.md

@@ -6,26 +6,27 @@ nav_order: 3
 ---
 # Configuration
 
-VS Code settings enable you to customize various aspects of its function. The InterSystems-provided extensions enable you to define InterSystems IRIS servers and the connections to those servers.
+VS Code settings enable you to customize various aspects of its function. The InterSystems extensions provide settings used to configure VS Code for ObjectScript development.
 
 ## 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 specific settings used to configure VS Code for ObjectScript development.
+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.
+
 There are several levels on which settings are stored and used:
 
 - **User** - User settings are stored in a file location specific to you and apply globally to any instance of VS Code or any VS Code workspace that you open.
 - **Workspace** - Workspace settings are stored in a file inside the workspace and apply to anyone who opens the workspace.
 - **Folder** - If more than one folder is present in the workspace, you can select the folder where the settings file is stored by selecting from the Folder drop down list.
 
-For example, the following screen shot shows Workspace selected:
+For example, the following screen shot shows the Workspace level selected:
 
 ![Workspace selected.](../assets/images/ClickWorkspace.png "workspace selected")
 
 See the VS Code documentation section [User and Workspace Settings](https://code.visualstudio.com/docs/getstarted/settings).
 
 ## Configuring a Server
 
-First, configure one or more servers. Select **View > Command Palette > InterSystems Server Manager: Store Password in Keychain**. This command lets you define a new server, as well as storing a password. Click the plus sign in the upper right corner of the dialog, as shown:
+First, configure one or more servers. Select **View > Command Palette > InterSystems Server Manager: Store Password in Keychain**. This command lets you define a new server and securely store a password in the system keychain. Click the plus sign in the upper right corner of the dialog, as shown:
 
 ![Define New Server.](../assets/images/new-server.png "define new server")
 
@@ -37,7 +38,9 @@ Provide the following values when prompted:
 - **Username** - the username to use in logging in to this server.
 - **Confirm connection type** - the protocol used for connections, possible values are **http** and **https**.
 
-Once you have entered these values, the server definition is stored in your user settings. At that point another prompt appears, asking for a password to store in the system Keychain. Enter the password for the username supplied earlier to complete the process.
+Once you have entered these values, the server definition is stored in your user settings. At that point another prompt appears, asking for a password to store in the system keychain. Enter the password for the username supplied earlier to complete the process. Storing a password is optional. You can terminate the process and store the server configuration by pressing either **Escape** or **Return**. If you do not store a password, users are prompted for a password each time they connect to the server.
+
+You can create a configuration for a server that is not currently running.
 
 ## Editing a Server Configuration
 
@@ -80,7 +83,15 @@ If you do not store the password securely in the system Keychain or add it to th
 
 ## Configuring a Server Connection
 
-Open the folder where you want client-side files to be located. Select the **ObjectScript Explorer** button which has been added to the Activity Bar. Select the **Choose Server and Namespace** button. This action opens a dialog that lets you select a server, or create a new one. Once you have selected a server and namespace, connection configuration is complete.
+Open the folder where you want client-side files to be located. Select the **ObjectScript Explorer** button on the Activity Bar. Select the **Choose Server and Namespace** button. This action opens a dialog that lets you select a server, or create a new one. Once you have selected a server and namespace, connection configuration is complete. VS Code adds the server and namespace to the status bar, as shown in the following screen shot.
+
+![Connection information in the status bar.](../assets/images/action-for-server-start.png "connection information in the status bar")
+
+You cannot create a connection to a server that is not running.
+
+Click on the server and namespace in the status bar to open a list of actions you can take for this server:
+
+![Select action for server.](../assets/images/action-for-server.png "select action for server")
 
 ## Editing a Server Connection
 
@@ -92,7 +103,7 @@ The connection configuration looks like this:
 "objectscript.conn": {
 	"ns": "USER",
 	"server": "iris-1",
-    "active": true,
+	"active": true,
 },
 ```
 

docs/RunDebug.md

@@ -6,13 +6,28 @@ nav_order: 4
 ---
 # Running and Debugging
 
-In order to run or debug an ObjectScript class or routine, you must create a launch configuration. Click the run button in the Activity Bar:
+The InterSystems ObjectScript Extension provides support for ObjectScript debugging. It takes advantage of the debugging capabilities built into VS Code, so you may find these VS Code documentation resources useful:
+
+- [Node.js debugging in VS Code](https://code.visualstudio.com/docs/editor/debugging)
+- [Debugging](https://code.visualstudio.com/docs/editor/debugging)
+
+## Launch Configurations
+
+In order to run or debug an ObjectScript class or routine, you must create a launch configuration. Some other languages default to running the currently active file, but to run ObjectScript, you must specify the routine or ClassMethod to use.
+
+Click the run button in the Activity Bar:
+
+![Run button.](../assets/images/run.png "run button")
 
 If no launch configurations are available, you are prompted to create one:
 
 ![Create launch configuration.](../assets/images/CreateLaunchConfig.png "create launch configuration")
 
-Clicking the link creates and opens a `launch.json` file containing the following default information:
+Clicking the link opens a dialog containing a list of debug environments. Select **ObjectScript Debug**. 
+
+![Select debug environment.](../assets/images/debug-environment.png "select debug environment")
+
+Once you have chosen a debug environment, VS Code creates and opens a `launch.json` file containing the following default content:
 
 ```json
 {
@@ -33,7 +48,7 @@ These attributes are mandatory for any launch configuration:
 - **request** - Identifies the type of action for this launch configuration. Possible values are `launch` and `attach`.
 - **name** - An arbitrary name to identify the configuration. This name appears in the Start Debugging drop down list.
 
-In addition, for an **objectscript** configuration, you need to supply the attribute **program**, which specifies the executable or file to run when launching the debugger, as shown in the following example:
+In addition, for an **objectscript** configuration, you need to supply the attribute **program**, which specifies the routine or ClassMethod to run when launching the debugger, as shown in the following example:
 
 ```json
 "launch": {
@@ -49,10 +64,19 @@ In addition, for an **objectscript** configuration, you need to supply the attri
 		{
 			"type": "objectscript",
 			"request": "launch",
-			"name": "ObjectScript Debug GoodbyWorld",
-			"program": "##class(Test.MyOtherClass).GoodbyWorld()",
+			"name": "ObjectScript Debug GoodbyeWorld",
+			"program": "##class(Test.MyOtherClass).GoodbyeWorld()",
 		},
 	]
 	}
 ```
 
+## Launching a ClassMethod or Routine
+
+You can select a launch configuration from the list VS Code provides in the Run and Debug field at the top of the debug side bar:
+
+![Select launch configuration.](../assets/images/select-config.png "select launch configuration")
+
+Clicking on the green arrow runs the currently selected launch configuration.
+
+Debugging commands and items on the **Run** menu function much as they do for other languages supported by VS Code. For information on VS Code debugging, see the documentation resources listed at the start of this section. 

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: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:user/"
+			"name": "iris184:USER",
+			"uri": "isfs://iris184/user"
 		},
 		{
-			"name": "test:%SYS (read-only)",
-			"uri": "isfs-readonly://test:%sys/"
+			"name": "iris184:%SYS (read-only)",
+			"uri": "isfs-readonly://iris184/%sys"
 		}
 	],
 	"settings": {}