improve doc

tools/README.md

@@ -6,6 +6,8 @@ Have a look to the given examples.
 
 ## Usage
 
+Usage: python convert_library [--compat] your_library_file.xlsx
+
 To launch it, open a shell in a command line, and type:
 
 ```bash
@@ -14,6 +16,8 @@ python convert_library.py your_library_file.xlsx
 
 This will produce a file name your_library_file.yaml
 
+The compat flag is recommended only to maintain libraries that have been generated prior or up to release 1.9.20. Without the compat flag, URNs generated for nodes without ref_id are constructed using the parent_urn. These generated URNs are much simpler to understand and maintain if required, compared to the previus system using "nodeXXX" suffix.
+
 ## Format of Excel files
 
 ```
@@ -57,13 +61,9 @@ Conventions:
         tab                             | <tab_name> | implementation_groups
         tab                             | <tab_name> | risk_matrix
         tab                             | <tab_name> | mappings
+        tab                             | <tab_name> | answers
 
-    
-    For libraries:
-        - library_provider is the entity that provides the reference document (e.g. ANSSI, NIST). 
-        - library_packager is the entity that converts the reference document in a library for CISO Assistant (e.g. intuitem). the value "intuitem" for packager is reserved for intuitem. Other packagers are kindly asked to use another descriptive value.
-        - library_description shall be sufficiently detailed, and shall contain a link to the reference document.
-        - framework_ref_id, framework_name and framework_description are generally identical to their corresponding values for library.
+        variables can also have a translation in the form "variable[locale]"
 
     For requirements:
         If no section_name is given, no upper group is defined, else an upper group (depth 0) with the section name is used.
@@ -78,6 +78,8 @@ Conventions:
             - reference_controls
             - annotation
             - typical_evidence
+            - questions
+            - answer
             - skip_count: trick for fixing a referential without changing the urns (advanced users)
         The normal tree order shall be respected
         If multiple threats or reference_control are given for a requirements, they shall be separated by blank or comma.
@@ -87,7 +89,7 @@ Conventions:
             - ref_id(*)
             - name
             - description
-            - category (policy/process/techncial/physical).
+            - category (policy/process/technical/physical).
             - csf_function (govern/identify/protect/detect/respond/recover).
             - annotation
     For risk matrices:
@@ -108,8 +110,14 @@ Conventions:
             - relationship(*)
             - rationale
             - stregth_of_relationship
-    A library has a single locale. Translated libraries have the same urns, they are merged during import.
+    For Answers:
+        The first line is a header, with the following possible fields (* for required):
+            - id(*)
+            - question_type(*)
+            - question_choices(*)
+    A library has a single locale, which is the reference language. Translations are given in columns with header like "name[fr]"
     Dependencies are given as a comma or blank separated list of urns.
+
 ```
 
 ## Mappings

tools/convert_library.py

@@ -1,5 +1,11 @@
 """
 simple script to transform an Excel file to a yaml library for CISO assistant
+Usage: python convert_library [--compat] your_excel_file
+
+The compat flag is recommended only to maintain libraries that have been generated prior or up to release 1.9.20.
+Without the compat flag, URNs generated for nodes without ref_id are constructed using the parent_urn.
+This generated urns that are much simpler to understand and maintain if required.
+
 Conventions:
     | means a cell separation, <> means empty cell
     The first tab shall be named "library_content" and contain the description of the library in the other tabs