docs: TI review of wiki pages and updates to readme files (eclipse-ch…

…e4z#56)

CONTRIBUTING.md

@@ -19,7 +19,7 @@ Make sure that the user email you specified on your local git is the same as on
 For more information, please see the Eclipse Committer Handbook:
 https://www.eclipse.org/projects/handbook/#resources-commit
 
-Such signoff is easily achieved using the `--signoff` option of the `git commit` command (provided that the git credentials are properly configured):
+The signoff is easily achieved using the `--signoff` option of the `git commit` command (provided that the git credentials are properly configured):
 ```
 git commit --signoff
 ```

README.md

@@ -6,20 +6,18 @@
 <img src="https://sonarcloud.io/images/project_badges/sonarcloud-black.svg" width="94" height="20" href="" />
 </a>
 
-HLASM Language Support is an extension for [Visual Studio Code](https://code.visualstudio.com/) (and [Theia](https://theia-ide.org/)) that adds support for
-the High Level Assembler. It provides code completion, highlighting and navigation features, detects common mistakes in the source, and lets you trace the evaluation of the
-conditional assembly source code, using a modern debugging interface.
+HLASM Language Support is an extension for [Visual Studio Code](https://code.visualstudio.com/) (and [Theia](https://theia-ide.org/)) that adds support for the High Level Assembler language. It provides code completion, highlighting and navigation features, detects common mistakes in the source, and lets you trace the evaluation of the conditional assembly source code, using a modern debugging interface.
 
 The extension is available on the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=broadcomMFD.hlasm-language-support). You can install it in a standard way from within the Visual Studio Code.
 
 HLASM Language Support is also part of [Code4z](https://marketplace.visualstudio.com/items?itemName=broadcomMFD.code4z-extension-pack), an all-round package that offers a modern experience for mainframe application developers, including [COBOL Language Support](https://marketplace.visualstudio.com/items?itemName=broadcomMFD.cobol-language-support), [Explorer for Endevor](https://marketplace.visualstudio.com/items?itemName=broadcomMFD.explorer-for-endevor), [Zowe Explorer](https://marketplace.visualstudio.com/items?itemName=Zowe.vscode-extension-for-zowe) and [Debugger for Mainframe](https://marketplace.visualstudio.com/items?itemName=broadcomMFD.debugger-for-mainframe) extensions.
 
 
 ## Useful information
-- If you have a question about the functionalities of the extension, or come across a problem [file an issue](https://github.com/eclipse/che-che4z-lsp-for-hlasm/issues).
-- Contributions are always welcome! Please see the [CONTRIBUTING.md](CONTRIBUTING.md) for more information
-- See the project [wiki](https://github.com/eclipse/che-che4z-lsp-for-hlasm/wiki/) for project documentation 
-- For instructions how to build and install the project from source, see the project [wiki](https://github.com/eclipse/che-che4z-lsp-for-hlasm/wiki/Build-instructions)
+- If you have a question about the functionalities of the extension, or come across a problem, [file an issue](https://github.com/eclipse/che-che4z-lsp-for-hlasm/issues).
+- Contributions are always welcome! Please see the [CONTRIBUTING.md](CONTRIBUTING.md) for more information.
+- See the project [wiki](https://github.com/eclipse/che-che4z-lsp-for-hlasm/wiki/) for project documentation. 
+- For instructions on how to build and install the project from source, see the project [wiki](https://github.com/eclipse/che-che4z-lsp-for-hlasm/wiki/Build-instructions).
 - All [releases](https://github.com/eclipse/che-che4z-lsp-for-hlasm/releases) are available here on GitHub.
 - Any and all feedback is appreciated and welcome!
 

clients/vscode-hlasmplugin/README.md

@@ -17,25 +17,27 @@ HLASM Language Support is also part of [Code4z](https://marketplace.visualstudio
 
 ## Getting Started
 
-### Usage
+### Enabling the Extension
 
 Follow these steps to open a HLASM project:
 
-1. In menu _File_ -> _Open Folder..._, select the folder with the HLASM sources. <!-- (An example workspace is provided in the folder `example_workspace`.) Uncomment once PR#44 is merged-->
+1. In _File_ -> _Open Folder..._, select the folder with the HLASM sources. <!-- (An example workspace is provided in the folder `example_workspace`.) Uncomment once PR#44 is merged-->
 2. Open any HLASM source file (note that HLASM does not have a standard filename extension) or create a new file.
 3. If the auto-detection of HLASM language does not recognize the file, set it manually in the bottom-right corner of the VS Code window.  
-4. The extension is now enabled on the open file. If you have macro definitions in separate files or use the COPY instruction, you need to setup the workspace.
+4. The extension is now enabled on the open file. If you have macro definitions in separate files or use the COPY instruction, you need to set up a workspace.
 
-### Setting up a multi-file project environment
+### Setting Up a Multi-File Project Environment
 
-HLASM COPY instruction copies the source code from various external files, as driven by HLASM evaluation. The source code interpreter in the HLASM Extension needs to be set up correctly to be able to find the same files as the HLASM assembler program. 
+The HLASM COPY instruction copies the source code from various external files, as driven by HLASM evaluation. The source code interpreter in the HLASM Extension needs to be set up correctly to be able to find the same files as the HLASM assembler program. 
 
-This is done by setting up two configuration files — `proc_grps.json` and `pgm_conf.json`. The extension guides the user in their creation:
+To do this, set up two configuration files — `proc_grps.json` and `pgm_conf.json`. Follow these steps:
 
-1. After opening a HLASM file for the first time, two pop-ups are displayed. Select _Create pgm_conf.json with current program_ and _Create empty proc_grps.json_. The two configuration files are then created with default values. They are written into the `.hlasmplugin` subfolder.
-2. Navigate to the `proc_grps.json` file. This is the entry point where you can specify paths to macro definitions and COPY files. To do this, simply fill the `libs` array with the corresponding paths. For example, if you have your macro files in the `ASMMAC/` folder, add the string `"ASMMAC"` into the libs array.
+1. After you open a HLASM file for the first time, two pop-ups display. Select _Create pgm_conf.json with current program_ and _Create empty proc_grps.json_. 
+   The two configuration files are then created with default values. They are stored in the `.hlasmplugin` subfolder.
+2. Navigate to the `proc_grps.json` file. This is the entry point where you can specify paths to macro definitions and COPY files. 
+3. Fill the `libs` array with the corresponding paths. For example, if you have your macro files in the `ASMMAC/` folder, add the string `"ASMMAC"` into the libs array.
 
-Follow [Configuration](#External-Macro-Libraries-and-COPY-Members) for more detailed instructions for configuring the environment.
+Follow [Configuration](#Configuration) for more detailed instructions on configuring the environment.
 
 ## Language Features
 
@@ -83,16 +85,20 @@ Breakpoints can be set before or during the debugging session.
 
 ![](https://github.com/eclipse/che-che4z-lsp-for-hlasm/raw/master/clients/vscode-hlasmplugin/readme_res/tracer.gif)
 
-## External Macro Libraries and COPY Members
+## Configuration
+
+### External Macro Libraries and COPY Members
 The HLASM Language Support extension looks for locally stored members when a macro or COPY instruction is evaluated. The paths of these members are specified in two configuration files in the `.hlasmplugin` folder of the currently open workspace:
 
 - `proc_grps.json` defines _processor groups_ by assigning a group name to a list of directories. Hence, the group name serves as a unique identifier of a set of HLASM libraries defined by a list of directories.
 
 - `pgm_conf.json` provides a mapping between _programs_ (open-code files) and processor groups. It specifies which list of directories is used with which source file. If a relative source file path is specified, it is relative to the current workspace.
 
-Therefore, to use a predefined set of macro and copy members, do the following steps: 
-1. Enumerate the library directories in `proc_grps.json` and name them with an identifier; thus, create a new processor group.
-2. Use the identifier of the new processor group with the name of your source code file in `pgm_conf.json` to assign the library members to the program.
+To use a predefined set of macro and copy members, follow these steps: 
+1. Specify any number of library directories to search for macros and COPY files in `proc_grps.json`. These directories are searched in order they are listed. 
+2. Name the group of directories with an identifier.
+   You have created a new processor group.
+3. Use the identifier of the new processor group with the name of your source code file in `pgm_conf.json` to assign the library members to the program.
 
 The structure of the configuration is based on CA Endevor® SCM. Ensure that you configure these files before using macros from separate files or the COPY instruction.
 When you open a HLASM file or manually set the HLASM language for a file, you can choose to automatically create these files for the current program.
@@ -142,42 +148,41 @@ The following example specifies that GROUP1 is used when working with `source_co
 ```
 If you have the two configuration files configured as above and invoke the MAC1 macro from `source_code`, the folder `ASMMAC/` in the current workspace is searched for a file with the exact name "MAC1". If that search is unsuccessful the folder `C:/SYS.ASMMAC` is searched. If that search is unsuccessful an error displays that the macro does not exist.
 
-Note that the macro `MAC1` is searched in directories in order as they are listed in the configuration. 
-
-There is also the option `alwaysRecognize` which takes an array of wildcards. It allows you to configure two things:
-- All files matching these wildcards will always be recognized as HLASM files. 
-- If an extension wildcard is defined, all macro and copy files with such extension may be used in the source code. For example, with the extension wildcard `*.hlasm`, a user may add macro `MAC` to his source code even if it is in a file called `Mac.hlasm`.
-
-Example of `alwaysRecognize`:
-
-With the following configuration file, processor group `GROUP1` will be assigned to `source_code` and `source_code.hlasm` file as well. Also, macro and copy files in the `lib` directory can be referenced and correctly recognized in the program without the `.asm` extension.
+The program name in `pgm_conf.json` can be wildcarded, as in the following example:
 
 ```
 {
   "pgms": [
     {
-      "program": "source_code",
+      "program": "*",
       "pgroup": "GROUP1"
     }
-  ],
-  "alwaysRecognize" : ["*.hlasm", "libs/*.asm"]
+  ]
 }
 ```
+In this example, GROUP1 is used for all open code programs.
 
-Example of wildcards:
+### File Extensions
+
+`pgm_conf.json` includes the optional parameter `alwaysRecognize` in which you can specify an array of wildcards. 
+- All files matching these wildcards are automatically recognized as HLASM files.
+- If an extension wildcard is defined, all macro and copy files with this extension can be used in the source code. 
+
+For example, with the extension wildcard `*.hlasm`, a user can add the macro `MAC` to his source code even if it is in a file called `MAC.hlasm`. Additionally, all files with the extension `.hlasm` are automatically recognised as HLASM files.
+
+The following example of `pgm_conf.json` specifies that the processor group `GROUP1` is assigned to both `source_code` and `source_code.hlasm`. Also, macro and copy files in the `lib` directory are referenced and correctly recognized in the program without the `.asm` extension.
 
-The program field in `pgm_conf.json` supports wildcards, for example:
 ```
 {
   "pgms": [
     {
-      "program": "*",
+      "program": "source_code",
       "pgroup": "GROUP1"
     }
-  ]
+  ],
+  "alwaysRecognize" : ["*.hlasm", "libs/*.asm"]
 }
 ```
-In this example, GROUP1 is used for all open code programs.
 
 ## Questions, issues, feature requests, and contributions
 - If you have a question about how to accomplish something with the extension, or come across a problem file an issue on [GitHub](https://github.com/eclipse/che-che4z-lsp-for-hlasm)

docs/Analyzer-pages/Analyzer.md

@@ -1,45 +1,42 @@
-The role of the analyzer is to provide a facade over objects and methods to create a simple interface for lexical and semantic processing (analyzing) of a single HLASM source file. The output of the analysis is the basic input of the LSP server.
+The role of the analyzer is to provide a facade over objects and methods to create a simple interface for lexical and semantic processing (analysis) of a single HLASM source file. The output of the analysis is the basic input of the LSP server.
 
-After the analyzer is constructed, it analyzes the provided source file. As a result, it updates HLASM context tables and provides a list of diagnostics linked to the file, highlighting, list of symbol definitions, etc.
+After the analyzer is constructed, it analyzes the provided source file. As a result, it updates HLASM context tables and provides a list of diagnostics linked to the file, highlighting, a list of symbol definitions, etc.
 
 Overview
 --------
 
 The analyzer is composed of several sub-components, all required to properly process the file.
 
-**LSP data collector** collects and retrieves all LSP information created while processing the file.
+- The **LSP data collector** collects and retrieves all LSP information created while processing the file.
+- **HLASM context tables** hold information about the context of the processed HLASM source code.
+- **Lexer–Parser sub-components** simplify the processing interface and ease the use of this component. They are needed to create a source file parser.
+- The **processing manager** executes the main loop where the file is processed.
 
-**HLASM context tables** hold information about the context of the processed HLASM source code.
+The LSP data collector is required by the Lexer-Parser sub-components. They are composed into the parser object required by the processing manager. HLASM context tables are used by the manager and the sub-components as well.
 
-**Lexer–Parser sub-components** simplify the processing interface and ease the use of this component. They are needed to create a source file parser.
-
-**Processing manager** executes the main loop where the file is processed.
-
-LSP data collector is required by Lexer-Parser sub-components. They are composed into the parser object required by processing manager. HLASM context tables are used by the manager and the sub-components as well.
-
-The components together contribute to the proper functionality of the method `analyze`. It processes a provided file and fills LSP data collector from which LSP information can be further retrieved.
+The components together contribute to the proper functionality of the method `analyze`. It processes a provided file and fills the LSP data collector, from which LSP information can be further retrieved.
 
 ### Construction
 
 In order to parse a HLASM file, the analyzer class is constructed with the following parameters:
 
--   *Name and content of a file.*
+-   *Name and content of the file.*
 
 -   *Parse library provider* – an object responsible for resolving source file dependencies. The dependencies are only discovered during the analysis, so it is not possible to provide the files beforehand.
 
--   *Processing tracer* (see [[Macro tracer]]).
+-   *Processing tracer* (see [[macro tracer]]).
 
-When this constructor is used, the analyzer creates HLASM context tables and processes the provided source as an open-code. We say that the analyzer has *owner semantics*; it is the owner of the context tables.
+When this constructor is used, the analyzer creates HLASM context tables and processes the provided source as an open-code. The analyzer has *owner semantics*; it is the owner of the context tables.
 
 The analyzer provides *reference semantics* as well (holding just a reference of the context tables). The provided source is not treated as an open-code, rather as an external file dependency. The constructor of an analyzer with reference semantics adds the following two parameters to the previous one:
 
 -   *HLASM context tables reference* — belongs to the owning open-code analyzer.
 
 -   *Library data* — states how the dependency file should be treated (see [[Processing manager]]).
 
-This constructor is called within open-code analyzer by its sub-components when they use the *Parse library provider*.
+This constructor is called within the open-code analyzer by its sub-components when they use the *Parse library provider*.
 
-The components of analyzer are further described in the following pages:
+The components of the analyzer are further described in the following pages:
 1. [[LSP data collector]]
 2. [[Processing manager]]
 3. [[Instruction format validation]]