Documentation Improvements

Author: isc-bsaviano

docs/Configuration.md

@@ -110,10 +110,6 @@ Open the folder where you want client-side files to be located. Select the **Obj
 
 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
 
 If you need to modify a server connection select **File > Preferences > Settings** (**Code > Preferences > Settings** on Mac) from the menu. Select the **Workspace** settings level. Search for **objectscript: conn**, and click on *Edit in settings.json*.
@@ -133,3 +129,34 @@ The components of this configuration are:
 - **ns** - namespace to use on the server
 - **server** - server name as specified in the server configuration
 - **active** - specifies whether the connection is active.
+
+## Add Custom Entries to the Server Actions Menu
+
+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")
+
+You can add custom entries to this list using the `objectscript.conn.links` configuration object, which contains key-value pairs where the key is the label displayed in the menu and the value is the uri to open. The following variables are available for substitution in the uri:
+
+- **${host}** - The hostname of the connected server. For example, `localhost`
+- **${port}** - The port of the connected server. For example, `52773`
+- **${serverUrl}** - The full connection string for the server. For example, `http://localhost:52773/pathPrefix`
+- **${ns}** - The namespace that we are connected to, URL encoded. For example, `%25SYS` or `USER`
+- **${namespace}** - The raw `ns` parameter of the connection. For example, `sys` or `user`
+- **${classname}** - The name of the currently opened class, or the empty string if the currently opened document is not a class.
+- **${classnameEncoded}** - `${classname}` URL encoded.
+
+An example links configuration looks like this:
+
+```json
+"objectscript.conn": {
+    "links": {
+        "Portal Explorer": "${serverUrl}/csp/sys/exp/%25CSP.UI.Portal.ClassList.zen?$NAMESPACE=${ns}",
+        "SOAP Wizard": "${serverUrl}/isc/studio/templates/%25ZEN.Template.AddInWizard.SOAPWizard.cls?$NAMESPACE=${ns}"
+    },
+}
+```
+
+And the resulting Server Actions Menu looks like this:
+
+![Server actions with custom links.](../assets/images/server-actions-with-links.png "server actions menu with custom links")

docs/RunDebug.md

@@ -8,20 +8,20 @@ nav_order: 5
 
 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)
+- [Debugging Intro Video](https://code.visualstudio.com/docs/introvideos/debugging)
+- [Debugging User Guide](https://code.visualstudio.com/docs/editor/debugging)
 
-## Launch Configurations
+## Debug 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.
+In order to run or debug an ObjectScript class or routine or attach to a running process, you must create a debug configuration. Some other languages default to running the currently active file, but to run ObjectScript, you must specify the routine or ClassMethod to use or the running process to attach to.
 
 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:
+If no debug configurations are available, you are prompted to create one:
 
-![Create launch configuration.](../assets/images/CreateLaunchConfig.png "create launch configuration")
+![Create debug configuration.](../assets/images/CreateLaunchConfig.png "create debug configuration")
 
 Clicking the link opens a dialog containing a list of debug environments. Select **ObjectScript Debug**. 
 
@@ -42,13 +42,13 @@ Once you have chosen a debug environment, VS Code creates and opens a `launch.js
 }
 ```
 
-These attributes are mandatory for any launch configuration:
+These attributes are mandatory for any debug configuration:
 
 - **type** - Identifies the type of debugger to use. In this case, `objectscript`, supplied by the InterSystems ObjectScript extension.
 - **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 routine or ClassMethod to run when launching the debugger, as shown in the following example:
+In addition, for an **objectscript launch** 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": {
@@ -68,15 +68,44 @@ In addition, for an **objectscript** configuration, you need to supply the attri
 			"program": "##class(Test.MyOtherClass).GoodbyeWorld()",
 		},
 	]
-	}
+}
 ```
 
-## Launching a ClassMethod or Routine
+For an **objectscript attach** configuration, you may supply the following attributes:
+
+- **processId** - Specifies the ID of process to attach to as a `string` or `number`. Defaults to `"${command:PickProcess}"`, which provides a dropdown list of process ID's to attach to at runtime.
+- **system** - Specifies whether to allow attaching to system process. Defaults to `false`.
+
+The following example shows multiple valid **objectscript attach** configurations:
+
+```json
+"launch": {
+	"version": "0.2.0",
+	"configurations": [
+		{
+			"type": "objectscript",
+			"request": "attach",
+			"name": "Attach 1",
+			"processId": 5678
+		},
+		{
+			"type": "objectscript",
+			"request": "attach",
+			"name": "Attach 2",
+			"system": true
+		},
+	]
+}
+```
+
+## Starting a Debugging Session
+
+You can select a debug configuration from the list VS Code provides in the Run and Debug field at the top of the debug side bar:
 
-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 debug configuration.](../assets/images/select-config.png "select debug configuration")
 
-![Select launch configuration.](../assets/images/select-config.png "select launch configuration")
+Clicking on the green arrow runs the currently selected debug configuration.
 
-Clicking on the green arrow runs the currently selected launch configuration.
+When starting **objectscript launch** debug session, make sure that the file containing the **program** that you are debugging is open in your editor and is the active tab. VS Code will start a debug session with the server of the file in the active editor (the tab that the user is focused on).
 
 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.