Update docs for 2.2.0 release

ypzhao-rocket · ypzhao-rocket · commit cc23ea2264fe · 2023-08-17T09:08:08.000+08:00
diff --git a/docs/index.md b/docs/index.md
@@ -1,10 +1,10 @@
-## About The Project
+# Rocket MV Basic for VS Code
 
-Rocket MV BASIC for VS code is a free Visual Studio Code Extension created by Rocket Software. The purpose of this extension is to enable BASIC developers to develop MV BASIC applications in one of the most popular development platforms- Microsoft Visual Studio Code. Rocket MV BASIC for VS code provides users with an exceptional editing experience.
+Rocket MV BASIC for VS Code is a free Visual Studio Code extension created by Rocket Software. This extension enables BASIC developers to modernize their MultiValue applications in one of the most popular development platforms with an exceptional editing experience.
 
 ## Features
 
-This extension includes the following features:
+This extension allows:
 
  - BASIC statements / keywords highlighting
  - Semantic highlighting
@@ -22,20 +22,34 @@ This extension includes the following features:
  - Add customized documentation for functions, subroutines, or labels
  - Show syntax and grammar errors
  - Prompt parameters of BASIC internal functions
- - Compile / Catalog / Debug BASIC programs on the U2 server、
+ - Compile / Catalog BASIC programs on the U2 server
+ - Debug BASIC program files
  - Remote editing of BASIC program files on a U2 server (preview)
 
-## Quick Start
+## Getting started
 
-Requirements: [VS Code](https://code.visualstudio.com/) 1.75 or higher version is required.
+Requirements:
+
+1. [VS Code](https://code.visualstudio.com/) version 1.75 or higher.
+2. [JDK](https://www.oracle.com/java/technologies/downloads/) or [OpenJDK](https://openjdk.org/projects/jdk/20/) version 11 or higher.
+
+### Install & configure the extension
 
   1. Install this extension from the VS Code Marketplace.
 
+	*Step 1*: Open **Visual Studio Code**.
+
+	*Step 2*: Click the **Extensions** icon ![EXTENSIONS](./img/icon-extensions-20x20.png) (<kbd>CTRL</kbd> + <kbd>SHIFT</kbd> + <kbd>X</kbd>). This opens the **EXTENSIONS** panel.
+
+	*Step 3*: Search for **Rocket MV Basic**.
+
+	*Step 4*: Click **Install** and wait for the installation to complete.
+
   2. Download, install and setup the Java environment. Note that you can skip Step 1 and Step 2 if you already have Java 11+ (OpenJDK or Oracle JDK) installed. 
 
-	*Step 1*: Download the Open JDK 11 or above GA releases zip file from [this page](http://jdk.java.net/archive/).
+	*Step 1*: Click **Manage** ![Manage](./img/icon-manage-20x20.png) **>** **Extension settings**. This opens the **Extension Settings** window.  
 
-	*Step 2*: Unzip the downloaded zip file to a temporary location on your system (for example, "*C:\ThirdParty\open-jdk-11*").
+	*Step 2*: In the **JDK Environment** section enter the full path to the JDK **bin** folder. For example., *C:\jdk-20\bin*.
 
 	*Step 3*.  Open User Settings (use the appropriate option listed below):
 
@@ -59,11 +73,13 @@ Requirements: [VS Code](https://code.visualstudio.com/) 1.75 or higher version i
 
 	**Note**: Using this method, an existing working environment that requires a different version of Java would not be impacted and the extension will work properly in the Java 11 (or above) environment.
 
-  3. Select "File" > "Open Folder" to open a folder that contains the BASIC program files you want to view or edit. You can also add multiple folders to the workspace using "File" > "Add Folder to Workspace". We recommend that you open the U2 account level folders to avoid encountering exceptions.
+### Open an account folder as a workspace
+
+  1. Select "File" > "Open Folder" to open a folder that contains the BASIC program files you want to view or edit. You can also add multiple folders to the workspace using "File" > "Add Folder to Workspace". We recommend that you open the U2 account level folders to avoid encountering exceptions.
 
 	**Note**: This extension is designed to work with folders/directories rather than individual program files. If you open a single file, some functions may be limited.
 
-  4. Activate the extension.
+  2. Activate the extension.
 
     - By default, the extension is automatically activated when opening a file with the suffix ".B". If your BASIC program files don’t end with a ".B" suffix, please refer to the FAQ to see how to customize the rules for activating the extension automatically.
     - If the extension is not activated automatically, please open the *Command Palette* in VS code(use any option listed below), and enter the "Activate Rocket MV BASIC" command to activate it manually.  
@@ -114,7 +130,7 @@ Click the links below to learn more about using each feature. You can also refer
 
 - [Compile BASIC programs](./usage/Compile.md)
 - [Multiple Workspace Folders](./usage/MultipleWorkspaceFolders.md)
-- [Debugging (Preview)](./usage/Debugging.md)
+- [Debugging](./usage/Debugging.md)
 
 ## Contact Us
 
diff --git a/docs/usage/Compatibility.md b/docs/usage/Compatibility.md
@@ -0,0 +1,15 @@
+# VS Code Compatibility 
+
+Upgrading VS Code may potentially introduce some issues that could result in anomalies with the compilation or debugging functions of our extension. In such cases, you can consider downgrading VS Code as a workaround. We have summarized a list of recent stable versions of VS Code for your reference.
+
+|  VS Code  |   GRPC Debug  |  CLI Debug  | Compilation | Online Editing |
+| --------- | ------------- | ----------- | ----------- | -------------- |
+|  1.81.0   |      √        |      √      |      √      |       √        |
+|  1.80.2   |      √        |      ×      |      √      |       √        |
+|  1.79.2   |      √        |      ×      |      √      |       √        |
+|  1.78.2   |      √        |      √      |      √      |       √        |
+|  1.77.3   |      √        |      √      |      √      |       √        |
+|  1.76.2   |      √        |      √      |      √      |       √        |
+|  1.75.1   |      √        |      √      |      √      |       √        |
+
+**Note**: Please refer [Debugging](./Debugging.md) to find out suitable UniVerse / UniData for debugging features.
diff --git a/docs/usage/ConfigDap.md b/docs/usage/ConfigDap.md
@@ -0,0 +1,34 @@
+
+## Configure Debugging Binaries in UniVerse
+
+Please check whether this feature is supported for your U2 server and platform according [this page](./DAPRelease.md).
+
+ - If yes, you need download and configure related binaries.
+
+ - If not, do not change your environment.
+
+To configure the debugging related binaries, please follow below steps.
+
+#### Windows
+
+1. Copy **dap_agent.exe** and **grpcs.exe** from the package to your UniVerse **bin** folder. E.g., *C:\U2\UV\bin*
+  
+2. Verify whether the unirpcservices file contains **grpcs** service. If **grpcs** service doesn't exist, you must add it manually. Add the new service as shown below to the **unirpcservices** file:
+
+    ```
+    grpcs <full_path_to_grpcs.exe> * TCP/IP 0 3600
+    ```
+
+    The 'unirpcservices' file can be found in your U2 server installation folder: for example, **C:\U2\unishared\unirpc\unirpcservices**.
+
+#### Linux
+
+1. Copy **dap_agent** and **grpcs** from the package to your UniVerse **bin** folder. For example, */usr/u2/uv/bin/*
+  
+2. Verify whether the **unirpcservices** file contains the **grpcs** service. If the **grpcs** service doesn't exist, you must add it manually. Add the new service as shown below to the **unirpcservices** file:
+
+    ```
+    grpcs <full_path_to_grpcs> * TCP/IP 0 3600
+    ```
+
+    The **unirpcservices** file can be found in your U2 server installation folder. For example,  **/usr/u2/unishared/unirpc/unirpcservices**.
diff --git a/docs/usage/Connection.md b/docs/usage/Connection.md
@@ -1,8 +1,12 @@
 ## U2 Connection Settings
 
-The Rocket MV BASIC extension can also connect to a U2 server. Regardless of whether you are connected to a server or not, all editor functions will work as expected. But when connected to a U2 server, some functions will have advanced capabilities. 
+The Rocket MV BASIC extension can also connect to a U2 server. Regardless of whether you are connected to a server or not, all editor functions will work as expected. But when connected to a U2 server, some new features will be enabled, and some features will be enhanced:
 
-**Note**: you cannot edit program files on the U2 server even if you are connected to it. You can only edit files on your local machine.
+ - [Goto definition](./Definition.md)
+ - [Auto-completion](./Completion.md)
+ - [Catalog](./Catalog.md)
+ - [Compile BASIC program](./Compile.md)
+ - [Debugging BASIC program](./Debugging.md)
 
 ### Settings
 
diff --git a/docs/usage/DAPRelease.md b/docs/usage/DAPRelease.md
@@ -0,0 +1,20 @@
+## Debugging Binaries Releases
+
+A high-performance debugging feature has been introduced in the 2.2.0 release (and in UniVerse 11.4.1). However, to use this feature, you will need to upgrade UniVerse to version 11.4.1 or higher. If you decide not to upgrade, you can continue using the original debugging feature available on previous versions of the U2 server.
+
+Below is a detailed breakdown of the information for each release. You can find instructions for configuring the debugging binaries in UniVerse [here](./ConfigDap.md).
+
+### 2.2.0 
+
+ - This high-performance debugging feature is supported only on UniVerse version 11.4.1 for both Windows and Linux platforms.
+ - If you are using UniVerse 11.4.1, there is no need to manually download and configure these binaries. They are already included in this version.
+ - However, please note that this feature and the associated binaries are not supported on any versions previous to UniVerse 11.4.1.
+
+    |   UniVerse   |    Windows  |    Linux    |     AIX     |
+    | ------------ | ----------- | ----------- | ----------- |
+    |   11.4.1     |      √      |      √      |       ×     |
+    |   < 11.4.1   |      ×      |      ×      |       ×     |
+
+**Assets**
+
+(link to github release page)
diff --git a/docs/usage/Debugging.md b/docs/usage/Debugging.md
@@ -16,15 +16,13 @@ Versions: 8.2.4
 
 Platforms: Windows, Linux, AIX
 
-Please refer [Known issues](./KnownIssues.md) list to find out existing issues in debugging feature.
+### A high performance debugging feature
 
-### Setup Environment
-
-In the 1.6.0 release, additional binaries should be installed on UniVerse to support the debugging features. This is no longer necessary for the 1.7.0 release.
+Since the 2.2.0 release, a high-performance debugging feature is supported on UniVerse 11.4.1. To use this feature, you must upgrade to UniVerse 11.4.1 or higher version. Please see [Debugging Binaries Releases](./DAPRelease.md) for more details.
 
 ## Start Debugging
 
-**Note**: You should not debug BASIC subroutines direcly, because this not allowed in UniVerse and UniData.
+**Note**: You should not debug BASIC subroutines directly, because this not allowed in UniVerse and UniData.
 
 ### Connecting to a U2 server account folder
 
@@ -38,7 +36,7 @@ There are 2 methods to debug a BASIC program file: debugging without a launch fi
 
 Before debugging, open the BASIC program first.
 
-**Note**: debugging a BASIC subroutine directly is not allowed
+**Note**: debugging a BASIC subroutine directly is not allowed.
 
 ### Debugging without a launch file
 
@@ -87,9 +85,9 @@ Then a default debugging configuration file launch.json will be generated in dir
  - "name": this is the name of the launch task. You can change the name to other values.
  - "program": if this value is empty, current focused file will be debugged. You can also set this value to another BASIC program file's absolute path. This file will be compiled before debugging.
  - "stopOnEntry": used to control whether the program will be stopped at the first runnable line when start debugging. Currently only true is supported.
- - "preLanuchTask": this is used to run pre-required task before debugging. In our extension, we use this setting to compile the BASIC program in setting "program" first.
- - "depenedncies": put other BASIC program files here if they need to be compiled before debugging.
- - "arguments": put additional debugging arguments here. Please refer to your UniVerse / UniData user documentation for more details. By default, this setting doesn’t appear in the configuration file, but can be added manually if needed.
+ - "preLaunchTask": this is used to run pre-required task before debugging. In our extension, we use this setting to compile the BASIC program in setting "program" first.
+ - "dependencies": put other BASIC program files' absolute paths here if they need to be compiled before debugging. For example, "C:\U2\UV\XDEMO\TEST". 
+ - "arguments": put additional debugging online· here. Please refer to your UniVerse / UniData user documentation for more details. By default, this setting doesn’t appear in the configuration file, but can be added manually if needed.
 
 From the **Run and Debug** view, set the launch option to **Launch Program**. Then press the F5 button to start debugging. 
 
@@ -115,6 +113,8 @@ You can find all break points in **BREAKPOINTS** panel of the **Run and Debug**
 
 The program will stop when the process encounters a break point.
 
+**Note**: Condition breakpoints are not supported.
+
 ### Continue
 
 When the process encounters a break point, the program will stop running. You can press the F5 key or click the Continue button from the debug panel to continue running the program. 
@@ -139,7 +139,7 @@ These two operations are still not stable. They partially work if breakpoints ar
 
 ## Restart debug
 
-This operation is currently NOT supported.
+Click **restart** button to restart debugging process.
 
 ### Stop debugging
 
@@ -149,7 +149,9 @@ Click the **Stop** button to stop the debugging process.
 
 ### View variables
 
-When debugging starts, you can view all variables in the **Run and Debug** view.
+When debugging starts, you can view all variables in the **Run and Debug** view. 
+
+You can also change a variable's value by double-clicking it in the **Run and Debug** view (this only works on UniVerse 11.4.1).
 
 ![](../img/debug_variables.png)
 
@@ -163,6 +165,8 @@ Click the plus (+) button from the **WATCH** panel and enter the variable name t
 
 ![](../img/debug_add_watch.png)
 
+**Note**: Only variables are supported. Expressions are not supported.
+
 ### Handle input operation
 
 You can switch to the VS Code terminal to handle an INPUT statement during BASIC program running. 
diff --git a/docs/usage/FAQ.md b/docs/usage/FAQ.md
@@ -45,3 +45,11 @@ The item in the example image above specifies that the Rocket MV BASIC extension
 3. Manually remove the MV BASIC extension directory under user profile. For example, you may find MV BASIC extension version 1.6.0 in "C:\Users\user_name\.vscode\extensions\rocketsoftware.rocket-mvbasic-1.6.0".
 
 4. Restart VS Code and install the latest extension.
+
+**Q: Why isn’t the debugging functionality working? It was working well before.**
+
+**A:** This may be a result of the VS Code upgrade. In VS Code 1.79.x, the debugging functionality has some updates which impact our extension. If you encounter debugging issues, please try to downgrade VS Code to [version 1.78.2](https://code.visualstudio.com/updates/v1_78) (on which the debugging functionality should work well). Please refer [VS Code Compatibility](./Compatibility.md) for more details.
+
+**Q: How can I exclude specific files from the explorer view?** 
+**A:** You can update the vscode settings file “.vscode/settings.json” to exclude files. For more details, please refer VS Code official online documentation.
+
diff --git a/docs/usage/KnownIssues.md b/docs/usage/KnownIssues.md
diff --git a/mkdocs.yml b/mkdocs.yml
