documentation

Author: edcdavid

README.md

@@ -1,2 +1,107 @@
 # parser
-The HTML Parser helps parse claim.json files generated by the CNF suite of tests
+The HTML Parser helps parse claim.json files generated by the CNF suite of
+tests. The HTML parser does the following:
+- display results in a human readable way. Decoding failure reasons 
+- annotate test results and download a shareable HTML page
+- save annotations to a file to be reused with other claim files
+- load claim files and annotation(feedback) files from local disk, uploaded by user or passed on the URL (HTML server only)
+
+## Relationship between the claim format and parser release versions
+### The claim format version
+
+A given parser release can only decode a single claim format version. The claim format version is defined as follows:
+- `v0.0.1` is the initial claim format version. It is used by the previous code before creating this repository
+- For newer versions, the minor version is incremented by 1 for each new claim format versions. The patch version is always zero.
+- The Major version is set to zero. The first claim format version supported by the parser in this repo is:`v0.1.0`
+
+### The parser release version
+
+The release version of the parser is based on the claim format version. The patch version is incremented by one for each new parser release supporting the same claim format version. For instance, a parser with a `v0.1.4` release version supports claim format `v0.1.0` and so is a release `v0.1.34`. A parser release 'v0.2.1' supports claim format `v0.2.0`.
+
+## Project directory structure
+```
+├── doc
+├── html  
+│   ├── build.js
+│   ├── index.js
+│   ├── results.html
+│   └── style.css
+├── LICENSE
+├── Makefile
+└── README.md
+```
+
+`doc`: documentation
+
+`html`: directory contains the HTML artifacts
+
+`html/build.js`: nodejs script to merger HTML artifacts and minify
+
+`html/index.js`: javascript component of the HTML page
+
+`html/style.css`: CSS component of the HTML page
+
+`LICENSE`: license file
+
+`Makefile`: Makefile
+
+`README.md`: README
+
+## Uploading a previous feedback to the html parser page
+
+Users can write notes or feedback about their test run in the HTML parser. 
+This displayed results and feedback can be downloaded as a static HTML page to be shared. 
+Users can also save their feedback as a json file for later use. 
+To load a file containing previouly entered feedback, users can
+upload their `feedback.json` file to the parser HTML page via the `Upload Feedback File` button.  Alternatively,
+users can convert their `feedback.json` to `feedback.js` and place it in the same folder as the result.html page.
+The feedback will be loaded automatically.
+
+to convert a feedback.json to feedback.js, rename the file to `feedback.js` and prepend `var feedback=` to the `feedback.json file` from:
+```
+{"source-all-access-control-cluster-role-bindings":"test2","so
+```
+to:
+```
+var feedback={"source-all-access-control-cluster-role-bindings":"test2","so ...
+```
+
+similarly the `claim.json` file can be automatically loaded, but first needs to be converted to a `claimjson.js` file.
+To do this first rename the `claim.json` file to `claimjson.js` then prepend `var initialjson=` to the renamed file:
+```
+{
+  "claim": {
+    "configurations": {
+```
+to
+```
+var initialjson = {
+  "claim": {
+    "configurations": {
+```
+## HTML Page modes
+
+### Manually uploading claim and feedback files via the webpage
+
+load the result.html or result-embed.html files locally and click on the "Choose File" button to pick the claim file to load:
+
+![claim](doc/images/pick-claim.jpg)
+
+Click on the "Upload Feedback File: Choose File" button to pick the feedback file to upload:
+
+![feedback](doc/images/pick-feedback.jpg)
+
+### Load local claimjson.js and feedback.js files
+
+When it is loaded, the webpage also looks for the following properly formatted javascript files: claimjson.js and feedback.js.
+If present in the same directory as the webpage, both files are loaded to update the webpage content without user interaction. Delete the files to prevent auto-loading the results and feedback. Works for hosted pages and local pages.
+
+### Load claim and feedback files via URL parameters
+
+When the result.html or result-embed.html are hosted it is also possible to pass the url of a claim and a feedback file as follows:
+http://localhost/results-embed.html?claimfile=claim.json&feedback=feedback3.json
+
+* the `claimfile=` parameter indicates the claim file to load
+* the `feedback=` parameter indicates the feedback file to load
+
+Both files are loaded without user interaction.