From f93af27663b0d7123c3f596648a5c4c9837b383e Mon Sep 17 00:00:00 2001
From: Stefan Bienert <stefan.bienert@unibas.ch>
Date: Fri, 6 May 2022 15:49:15 +0200
Subject: [PATCH] Extending the validation tool README.

---
 validation/README.md | 27 ++++++++++++++++++++++-----
 1 file changed, 22 insertions(+), 5 deletions(-)

diff --git a/validation/README.md b/validation/README.md
index 697e5bb..5123638 100644
--- a/validation/README.md
+++ b/validation/README.md
@@ -1,20 +1,37 @@
 # ModelCIF validation tool
 
-This is a tool to check that the formatting of ModelCIF files complies with the ModelCIF format declaration (aka "dictionary"). Upon successful validation, a ModelCIF file can be extended with the dictionary version the file was compared to (option ToDo: add option). For more basic mmCIF validation, the dictionary of the underlying PDBx/mmCIF format is also available.
+This is a tool to check that the formatting of ModelCIF files complies with the ModelCIF format declaration (aka "dictionary"). Upon successful validation, a ModelCIF file can be extended with the dictionary version the file was compared to (option `--extend-validated-file` ToDo: add anchor for option). For more basic mmCIF validation, the dictionary of the underlying PDBx/mmCIF format is also available.
 
 The easiest way to run validation is from Docker container. Running it out of Docker requires an installation of [OpenStructure](https://openstructure.org).
 
 [[_TOC_]]
 
-- how to run the tool
+## How to run the validation tool
 
-- how to run the container
+This is just a description of the validation tool itself. When running it from inside a container, the command needs to be prefixed with the instructions to start the container. Find information for running the validation container in "[How to run the container](how-to-run-the-container)".
+
+Upon completion, if there hasn't been any error running the command, the validation tool returns a concise report in JSON format. That output is meant to be input to a website or any kind of nicely formatted report. Output can also be stored as a file. If the tested ModelCIF file is fully compliant with the ModelCIF format, the JSON output has
+
+- `status` "completed"
+- no messages in the `diagnosis` list
+- `version` of the dictionaries the file was tested against
+
+Format violations will be listed in `diagnosis`.
+
+
+
+- basic usage
+- explain output
+- add version of dict validated against
+- remaining options
+
+## How to run the container
 
 - how to pull the container
 
 - how to build the container
 
-- files (at the bottom)
+# Files in this directory
 
-<!--  LocalWords:  PDBx
+<!--  LocalWords:  PDBx ModelCIF TOC JSON
  -->
-- 
GitLab