Fix #29 Troubleshooting Guide improvements plus other documentation i…

…mprovements. (#33)

README.md

@@ -1,52 +1,67 @@
-# CCL Unit
-Cerner Command Language (CCL), aka Discern Explorer, is a database query and scripting language used with Cerner Millennium databases. [CCL Unit][ccl_unit] 
-is a unit test framework for CCL.
+# ccl-testing
 
-***ccl-testing*** houses maven plugins to perform CCL Unit tests and analyses and generate reports from the results, to perform static analyses,
-and to generate code documentation. It also houses some dependencies for those maven plugins. Specifically, ccl-testing houses the components listed below. 
-Please visit individual components for details and usage instructions. 
+## Contents
+[Introduction](#introduction)  
+[Component Versions](#component-versions)  
+[Quick Start Guide](#quick-start-guide)  
+[Recommendations](#recommendations)  
+[Troubleshooting](#troubleshooting)  
+[Release Schedule](#release-schedule)  
+[Contributing](#contributing)  
+[License](#license)  
 
-* [**ccl-maven-plugin (3.2)**](ccl-maven-plugin/README.md) - Maven plugin for transferring resources, compiling CCL code and tests, executing the
+## Introduction
+[Cerner Command Language][CCL], aka CCL, aka Discern Explorer, is a database query and scripting language used with Cerner Millennium databases.  [CCL Unit][ccl_unit] 
+is a unit testing framework for CCL.
+
+The ***ccl-testing*** repository houses maven plugins to perform CCL Unit tests and analyses, to generate reports from the results, to perform static analyses,
+and to generate code documentation. It also houses some dependencies for those maven plugins.  
+See [Component Versions](#component-versions) for a list of the components.  
+
+
+## Component Versions
+The latest released versions of the ccl-testing components are listed below.  
+Visit individuals components for details and usage instructions.  
+Visit the [change log](CHANGELOG.md) for version details. 
+
+* [**ccl-maven-plugin (3.2)**][ccl-maven-plugin] - Maven plugin for transferring resources, compiling CCL code and tests, executing the
 tests, and retrieving the test and coverage results.
 * [**cerreal-maven-plugin (2.1)**](cerreal-maven-plugin/README.md) - Maven reporting plugin to report test and coverage results.
 * [**whitenoise-maven-plugin (2.5)**](whitenoise/whitenoise-maven-plugin/README.md) - Maven reporting plugin that identifies common CCL coding errors.
 * [**cdoc-maven-plugin (1.2)**](cdoc/cdoc-maven-plugin/README.md) - Maven reporting plugin that generates code documentation from code comments.
-* [**ecosystem**](ecosystem/README.md) - Eclipse preferences to ensure consistent formating and compiler settings. Imported using Workspace Mechanic.
+* [**ecosystem**](ecosystem/README.md) - Eclipse preferences to ensure consistent formating and compiler settings. Import with [Workspace Mechanic][workspace_mechanic].
 * [**ftp-util (2.0)**](ftp-util/README.md) - ccl-maven-plugin dependency used to ftp resource to/from the Cerner Millennium back end.
-* [**j4ccl (3.1)**](j4ccl/README.md) - ccl-maven-plugin dependency defining common classes and interfaces for accessing a Cerner Millennium back end.
+* [**j4ccl (3.1)**](j4ccl/README.md) - ccl-maven-plugin dependency defining   classes and interfaces for accessing a Cerner Millennium back end.
 * [**j4ccl-ssh (4.2)**](j4ccl-ssh/README.md) - ccl-maven-plugin dependency leveraging JCraft SSH to implement the j4ccl interfaces.
 * [**jsch-util (2.0.0)**](jsch-util/README.md) - ccl-maven-plugin dependency leveraging JCraft to provide back-end connections for j4ccl-ssh.
-* [**cclunit-archetype (1.5)**](./archetype/ARCHETYPEUSAGE.md) - archetype to generate a skeleton CCL project using the latest plugins.
-* [**cclunit-maven-settings-check-archetype (1.2)**](./archetype/ARCHETYPEUSAGE.md) - archetype to generate a CCL project to check maven settings.
-
-Some significant differences from legacy versions to note:
-* The artifactId for plugins is now `X-maven-plugin` rather than `maven-X-plugin` to satisfy [maven3 restrictions on plugin naming][plugin-naming].
-* Several groupId values changed. All components now live below com.cerner.ccl or com.cerner.ftp. In particular use com.cerner.ccl.testing not com.cerner.ccltesting.
-* The [specifyDebugCcl](ccl-maven-plugin/doc/CONFIGURATIONOPTIONS.md#specifyDebugCcl) flag in the ccl-maven-plugin.
-
+* [**cclunit-archetype (1.5)**][archetype usage] - archetype to generate a skeleton CCL project using the latest plugins.
+* [**cclunit-maven-settings-check-archetype (1.2)**][archetype usage] - archetype to generate a CCL project to check maven settings.
+
 ## Quick Start Guide
-If you are new to CCL Unit testing and want to get started quickly, [look here][cclunit_quickstart].
+If you are new to CCL Unit testing and want to get started writing and running tests quickly, [look here][ccl_unit_usage].  
+
+Install and configure [Apache Maven](https://maven.apache.org/) as described [here](doc/CONFIGUREMAVEN.md).  
+Use [the maven archetype][archetype usage] to generate a new mavenized CCL project.
 
-For recommendations on setting up maven, [look here](doc/CONFIGUREMAVEN.md). 
+## Recommendations
+Configure the system so your password will not show up in log files. [Look here](ccl-maven-plugin/doc/PASSWORDLOGGING.md) for details.  
+Use [the maven archetype][archetype usage] to generate new projects.  
+      If you really want to do it manually, here is a [sample pom] (the same one the archetype creates).    
+Become familiar with the [usage instructions][ccl-maven-plugin] and [configuration options][ccl-maven-plugin-configuration-options] for the unit testing plugin.  
 
-Take a look at the [sample pom configuration](ccl-maven-plugin/README.md) and 
-[configuration options](ccl-maven-plugin/doc/CONFIGURATIONOPTIONS.md) for the unit testing plugin.
 
-Don't want your password showing up in log files? [Look here](ccl-maven-plugin/doc/PASSWORDLOGGING.md).
+## Troubleshooting  
+Having issues? [Look here](ccl-maven-plugin/doc/BUILDISSUES.md) for some common problems and troubleshooting tips.
 
-Having build issues? [Look here](ccl-maven-plugin/doc/BUILDISSUES.md) for some common problems and troubleshooting tips.
 
 ## Release Schedule
 
 The release schedule will be driven by requests for and contributions of enhancements and corrections.  
 See the [change log](CHANGELOG.md) for the contents of previous releases.
 
-## Contribute
-
-You are welcomed to Contribute. Please read our [Contribution Guidelines][contibution_guidelines].
-
-
+## Contributing
 
+You are welcomed to contribute enhancements or fixes to the documention or code. Please read our [Contribution Guidelines][contibution_guidelines].  
 Committers should follow the [Release Guidelines][release_guidelines].
 
 
@@ -69,8 +84,13 @@ limitations under the License.
 ```
 
 
+[CCL]: https://en.wikipedia.org/wiki/Cerner_CCL
 [contibution_guidelines]: CONTRIBUTING.md#contributing
 [release_guidelines]: RELEASING.md#releasing-ccl-testing
 [ccl_unit]: https://github.com/cerner/cclunit-framework
-[cclunit_quickstart]: https://github.com/cerner/cclunit-framework/blob/master/doc/QUICKSTART.md
-[plugin-naming]:https://maven.apache.org/guides/introduction/introduction-to-plugin-prefix-mapping.html
+[ccl_unit_usage]: https://github.com/cerner/cclunit-framework#cclunit-framework
+[archetype usage]: ./archetype/ARCHETYPEUSAGE.md
+[sample pom]: ccl-maven-plugin/doc/SAMPLEPOM.md
+[ccl-maven-plugin]: ccl-maven-plugin/README.md
+[ccl-maven-plugin-configuration-options]: ccl-maven-plugin/doc/CONFIGURATIONOPTIONS.md
+[workspace_mechanic]: https://code.google.com/archive/a/eclipselabs.org/p/workspacemechanic 

archetype/ARCHETYPEUSAGE.md

@@ -1,39 +1,68 @@
 # Maven Archetype Usage
+A maven archetype is used to create a new maven project having predefined folders and files.
+
+## Contents
+[Skeleton CCL Project](#skeleton-ccl-project)  
+[Maven Verification Project](#maven-verification-project)  
+
+## Skeleton CCL Project
+
+**cclunit-archetype** generates a skeleton CCL project with the expected folder structure using the lastest maven plugins.  
+Once the project is generated 
+- Put CCL source files in src/main/ccl   
+- Put CCL unit test cases in src/test/ccl   
+- Launch a command prompt in the project folder.  
+- Execute any maven command, for example  
+    - `mvn clean compile -P<profile>` to compile the source  
+    - `mvn clean compile test -P<profile>` to compile the source and execute the unit tests  
+    - `mvn clean compile test site -P<profile>` to compile the source, execute the unit tests and generate reports  
+
+While generating the project a series of prompts will be presented.  
+- You can press `Enter` to select the default value for any prompt that presents a default value.
+- Along the way you must enter a groupId, artifactId and vesion. These references contain guidelines for their selection.
+    - [maven conventions], 
+    - [maven coordinates], 
+    - [choosing coordinates].
+
+To generate the project 
+- Launch a command prompt in an empty directory.  
+- Enter `mvn archetype:generate -Dfilter=com.cerner.ccl.archetype:cclunit-archetype`.  
+- Respond to the ensuing prompts.
+    - Enter `1` to select the first/only item `cclunit-archetype` in the presented list of archetypes.
+    - Press `Enter` to select the highest version in the list of available versions.
+    - Enter a groupId, artifactId, version, and (opitonal) package when prompted.
+    - Enter `Y` or `N`when prompted to confirm the entries or start over.
+
+Maven will create a folder named `<artifactId>` and add the archetype contents into it.  
+Note that the starting directory does not really have to be empyt, but it must not contain a pom file. 
+ - If it already contains a folder named `<artifactId>`, the behavior is not guaranteed except that  
+    - No existing files will be modified.  
+    - Partial contents from the archetype could be added or the command could fail.  
+
+
+
+## Maven Verification Project
+**cclunit-maven-settings-check-archetype** generates a mavenized CCL project used to verify if maven is properly configured .  
+- The generated project will contain a sample program with a sample unit test case.  
+- The project will be configured with maven-ccl-plugin but no other plugins.  
+- An older version of maven-ccl-plugin could be used. 
+
+
+Once the project is generated 
+- Launch a command prompt in the project folder 
+- Execute the following maven command
+    - `mvn clean compile test -P<profile>`
+
+If the project builds without errors, maven is properly configured for mavenize CCL projects, and otherwise, it is not.
+
+
+To generate the project 
+- Execute the folowing command in an empty directory and 
+    - `mvn archetype:generate -Dfilter=com.cerner.ccl.archetype:cclunit-maven-settings-check-archetype`   
+
+Refer to [Skeleton CCL Project](#skeleton-ccl-project) for guidance in answering the prompts.
 
-Enter either of the following commands in an empty directory.  
-  `mvn archetype:generate -Dfilter=<artifactId>`  
-  `mvn archetype:generate -Dfilter=<groupId>:<artifactId>` 
-- The filter is optional (but not really)
- - if one is specified it must be complete
-- The archetypes of interest for CCL Unit testing are
- - **com.cerner.ccl.archetype:cclunit-archetype**
-   - generates a skeleton CCL project with the specified maven coordinates configured to use the latest versions of ccl-testing plugins available when the archetype was created.
- - **com.cerner.ccl.archetype:cclunit-maven-settings-check-archetype**
-   - generates a mavenized CCL project with no additional plugins that builds without errors.
-   - execute the command `mvn clean test -P<profile>` on the generated project to determine if maven, the profile and associated domain are set up correctly.
-
-Here is what to expect when running the `achetype:generate` command.  
-You can just press `Enter` to select the default 
-for any prompt that provides one.
-
-- After entering the generate command maven will present a numbered list of matching archetypes. 
- - or indicate no matches if there are none. 
-- Enter the number from the list for the desired archetype.
-- If multiple versions are available, there will be a prompt to select the version.
-- Enter a groupId, artifactId, version, and (opitonal) package when prompted. 
-- When prompted, enter Y to confirm the entries are correct or N to start again.
-- Maven will create a folder with the same name as the artifactId and add the contents from the archetype into it. 
-  - If a folder with that name already exists, the behavior is not guaranteed except that no existing files will be modified.  
-   - Partial contents from the archetype could be added or the command could fail.
-
-Here are a some references containing guidelines for selecting a groupId, artifactId and version for the project you are generating: 
- - [maven conventions], 
- - [maven coordinates], 
- - [choosing coordinates].
 
 [maven conventions]:https://maven.apache.org/maven-conventions.html
 [maven coordinates]:https://maven.apache.org/pom.html#Maven_Coordinates
 [choosing coordinates]:http://central.sonatype.org/pages/choosing-your-coordinates.html
-[cerreal]:../cerreal-maven-plugin/README.md
-[whitenoise]:../whitnoise-maven-plugin/README.md
-[cdoc]:../cdoc-maven-plugin/README.md

ccl-maven-plugin/doc/BUILDISSUES.md

@@ -1,12 +1,21 @@
-# Build Issues
+  # Build Issues
 
-Timout Issues
+## Contents
+[Timeout Issues](#timeout-issues)  
+[Prerequisite Violations](#prerequisite-violations)  
+[Compile Failures](#compile-failures)  
+[Parsing Errors](#parsing-errors)  
+[Test Failures](#test-failures)  
+[Code Coverage Problems](#code-coverage-problems)  
+[Legacy Upgrades](#legacy-upgrades)  
+
+Timeout Issues
 ===
 expectj4 send status TIMEOUT (-2)
 
 Be sure the [prompt patterns] are correct. The plugin uses them to decide when the back end system is ready to receive commands. 
-If a pattern does not match the actual prompt, the plugin will either hang indefinitely or time out waiting for the prompt. In contrast, if a pattern ends up 
-matching output that is not from the prompt, the plugin could send a command before the back end is ready to receive it. 
+If a pattern does not match the actual prompt, the plugin will either hang indefinitely or time out waiting for the prompt. On the other hand, 
+if a prompt pattern ends up matching output that is not actually the OS prompt, the plugin could send a command before the back end is ready to receive it. 
 
 Passing the `-X` command argument to maven will cause the plugin to output to stdout
 exactly what is being sent to the back end and what response is being expected. Search the output for `commandExpectationGroup:` which will be followed by two lists,
@@ -19,28 +28,49 @@ configuration can be modified to suppress some of the [expect4j] output.
 
 If the prompt patterns are correct, then the backend device and/or the connection to it are too slow to beat the [expectation timeout][expectation timeout]. Try setting a larger value.
 
+Prerequisite Violations
+===
+To prevent a successful build with incorrect and confusing results, builds are failed if these prerequisites are not satisfied.  
+- program source file names must be all lower case.
+- program source files must have a .prg extension
+- program source file names must match the name of the generated object
+    - case-insensitive - characters inside the file can be any case
+
 Compile Failures
 ===
-Listing files for all compile operations are created in $cer_temp. The exact location will be shown in [cclLogfile][configuration] if it is configured. Look for `call compile`.
+If a compile failure occurs, inspect the last displayed listing file in `$cer_temp` to see the error in context.  
+**validating compile <listing file name>** is displayed as each file is compiled.  
 
-If an error occurs while trying to compile a test case into a test program, the listing file will be saved in $CCLUSERDIR with a .lis extension. 
-The file is deleted if the compile is successful.
 
 Parsing Errors
 ===
-If an xml parsing error occurs, an exception will be prominently visible in the maven output. Unfortunately, the xml parser has no idea what it is parsing so the exception only 
-indicates there was a parsing error. If the maven log level is at least Info (default), then the output will name each entity just before it is parsed.
+If an xml parsing error occurs, an exception will display prominently in the maven output. Unfortunately, the xml parser has no idea what it is parsing so the exception only 
+indicates there was a parsing error. The output will name each entity just before it is parsed if the maven log level is at least Info (the default value).
 
 Test Failures
 ===
-Try [`-DdeprecatedFlag=W`][configuration]. CCL's messaging for deprecated constructs does not always explain the problem is deprecation. This should only be done temporarily as it
+Try [`-DdeprecatedFlag=W`](CONFIGURATIONOPTIONS.md#deprecatedFlag). CCL's messaging for deprecated constructs does not always explain the problem is deprecation. This should only be done temporarily as it
 prevents the identification of undeclared variables. Here are some known examples
 - %CCL-E-414 and %CCL-E-415: Non-boolean predicate could return truncation in where clause requiring ccl893 or higher.
   - most likely MAXREC or ASSIGN was used in a where clause without adding '> 0' or '= #'. 
 - %CCL-E-393: updt column missing from update command.
   - When updating a record, the updt_dt_tm column must be be updated.
 
-[prompt patterns]:./CONFIGURATIONOPTIONS.md#os-prompt-pattern
-[expectation timeout]:./CONFIGURATIONOPTIONS.md#expectation-timeout
-[configuration]:CONFIGURATIONOPTIONS.md#ccl-log-file
-[expect4j]:https://github.com/cverges/expect4j
+Code Coverage Problems
+===
+To see code coverage, [specifyDebugCcl](ccl-maven-plugin/doc/CONFIGURATIONOPTIONS.md#specifyDebugCcl) must be false for CCL versions prior to 8.13.0.
+
+Legacy Upgrades
+===
+There are some significant differences from legacy versions to note:
+* The artifactId for plugins is now `X-maven-plugin` rather than `maven-X-plugin` 
+    * This is to satisfy [maven3 restrictions on plugin naming][plugin-naming].
+* Several groupId values were changed. 
+    * All components now live below `com.cerner.ccl` or `com.cerner.ftp`. 
+    * In particular use `com.cerner.ccl.testing` not `com.cerner.ccltesting`.
+
+
+[prompt patterns]:./CONFIGURATIONOPTIONS.md#osPromptPattern
+[expectation timeout]:./CONFIGURATIONOPTIONS.md#expectationTimeout
+[expect4j]:https://github.com/cverges/expect4j
+[plugin-naming]:https://maven.apache.org/guides/introduction/introduction-to-plugin-prefix-mapping.html