From b7ae1936a713bf34862bae881b27a94af634a363 Mon Sep 17 00:00:00 2001
From: Philippe Le Van <philippe.levan@kibatic.com>
Date: Fri, 16 Feb 2024 14:20:23 +0100
Subject: [PATCH 1/8] Better readme

---
 README.md | 168 +++++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 128 insertions(+), 40 deletions(-)

diff --git a/README.md b/README.md
index d7198bd..5754f76 100644
--- a/README.md
+++ b/README.md
@@ -1,17 +1,93 @@
-# LOTemplateFiller
+LOTemplate (for Libre Office Template)
+======================================
 
-LOTemplateFiller is a script that fills a given document, used as a template, with elements given in a 
-json file. This script can be used as an API (using Flask), a CLI or a python module for your own code.
-For more information on a specific usage, read, the `Execute and use the API` or 
-`Execute and use the CLI` section.
+LOTemplate is document generator used to create documents programatically (ODT, DOCX, PDF) from a template and a json file.
 
-## Functionalities
-- scans the template to extract the variables sheet
-- search for all possible errors before filling
-- filling the template
-- export the filled template
+Templates are Word or Libreoffice documents (ODT or DOCX).
+
+What makes this tool different from others are the following features :
+
+* The templates are in DOCS or ODT format
+* Template can have complex structures (loop, conditions, counters, html,...)
+* The tool can scan the template to extract the variables sheet
+* The tool can be called by an API, a CLI or a python module.
+
+The tool is written in Python and use a real LibreOffice headless to fill the templates.
+
+Quick start
+-----------
+
+### Run the project with docker compose
+
+Create a docker-compose.yml
+
+```yaml
+version: '3'
+services:
+  lotemplate:
+    image: probesys38/lotemplate:v1.5.0
+    volumes:
+      - lotemplate-uploads:/app/uploads
+    environment:
+      - SECRET_KEY=lopassword
+    command: "gunicorn -w 4 -b 0.0.0.0:8000 app:app"
+```
+
+run the service
+
+```shell
+docker-compose up -d
+```
+
+### Use the API
+
+```bash
+# creation of a directory
+curl -X PUT -H 'secret_key: lopassword' -H 'directory: test_dir1' http://localhost:8000/
+# {"directory":"test_dir1","message":"Successfully created"}
+```
+
+Let's imagine we have an file basic_test.odt (created by libreoffice) like this :
+
+```
+Test document
+
+let’s see if the tag $my_tag is replaced and this $other_tag is detected.
+[if $my_tag == foo]My tag is foo[endif]
+[if $my_tag != foo]My tag is not foo[endif]
+```
+
+Upload this file to lotemplate
+
+```bash
+# upload a template
+curl -X PUT -H 'secret_key: lopassword' -F file=@/tmp/basic_test.odt http://localhost:8000/test_dir1
+# {"file":"basic_test.odt","message":"Successfully uploaded","variables":{"my_tag":{"type":"text","value":""},"other_tag":{"type":"text","value":""}}}
+
+# generate a file titi.odt from a template and a json content
+curl -X POST \
+    -H 'secret_key: lopassword' \
+    -H 'Content-Type: application/json' \
+    -d '[{"name":"my_file.odt","variables":{"my_tag":{"type":"text","value":"foo"},"other_tag":{"type":"text","value":"bar"}}}]' \
+    --output titi.odt http://localhost:8000/test_dir1/basic_test.odt 
+```
+
+After the operation, you get the file titi.odt with this content :
+
+```
+Test document
+
+let’s see if the tag foo is replaced and this bar is detected.
+
+My tag is foo
+
+```
+
+Installation
+------------
+
+### Requirements
 
-## Requirements
 For Docker use of the API, you can skip this step.
 
 - LibreOffice (the console-line version will be enough)
@@ -21,15 +97,12 @@ For Docker use of the API, you can skip this step.
   `pip install -r requirements.txt`. `Flask` and `Werkzeug` are optional, as they are used only for the API.
 
 ```bash
-# on debian bullseye, you can use these commands
-echo 'deb http://deb.debian.org/debian bullseye-backports main' > /etc/apt/sources.list.d/backports.list
+# on debian bookworm, you can use these commands
 apt update
-apt -y -t bullseye-backports install bash python3 python3-uno python3-pip libreoffice-nogui
+apt -y -t install bash python3 python3-uno python3-pip libreoffice-nogui
 pip install -r requirements.txt
 ```
 
-## Use the API
-
 ### Run the API
 
 Run the following command on your server :
@@ -50,22 +123,12 @@ or, for Docker deployment:
 docker-compose up
 ```
 
-## Docker for dev when your uid is not 1000
-
-for this we use fixuid (https://github.com/boxboat/fixuid)
-
-you have to define two env variable MY_UID and MY_GID with your uid and gid
-copy docker-compose.override.yml.example to docker-compose.override.yml
-
-```shell
-export MY_UID=$(id -u)
-export MY_GID=$(id -g)
-cp docker-compose.override.yml.example docker-compose.override.yml
-docker-compose up
-```
+Basic Usage
+-----------
 
+### With the API
 
-### Quick start with the API
+#### Examples of curl requests
 
 ```bash
 # creation of a directory
@@ -118,7 +181,7 @@ Test document
 let’s see if the tag foo is replaced and this bar is detected.
 ```
 
-### API reference
+#### API reference
 
 Then use the following routes :
 
@@ -157,7 +220,9 @@ If you're deploying the app with Docker, port and ip are editable in the [Docker
 You can also specify the host and port used to run and connect to soffice as command line arguments,
 or in a config file (`config.yml`/`config.ini`/`config` or specified via --config).
 
-## Execute and use the CLI
+
+
+### Execute and use the CLI
 
 Run the script with the following arguments :
 ```
@@ -190,7 +255,7 @@ optional arguments:
 
 Args that start with '--' (e.g. --json) can also be set in a config file
 (`config.yml`/`config.ini`/`config` or specified via --config). Config file syntax allows: key=value,
-flag=true, stuff=[a,b,c] (for details, [see syntax](https://goo.gl/R74nmi)).
+flag=true, stuff=[a,b,c] (for details, [see syntax](https://pypi.org/project/ConfigArgParse/)).
 If an arg is specified in more than one place, then commandline values
 override config file values which override defaults.
 
@@ -200,7 +265,9 @@ Get a file to fill with the `--scan` argument, and fill the fields you want. Add
 of an array to dynamically add rows. Then pass the file, and the completed json file(s) (using `--json_file`)
 to fill it.
 
-## Template Syntax
+
+Template Syntax
+---------------
 
 ### text variables
 
@@ -683,7 +750,8 @@ Other formats can be easily added by adding the format information in the dictio
 Format information can be found on the 
 [unoconv repo](https://github.com/unoconv/unoconv/blob/94161ec11ef583418a829fca188c3a878567ed84/unoconv#L391).
 
-## Doc for developpers
+Doc for developpers of lotemplate
+---------------------------------
 
 ### Run the tests
 
@@ -693,7 +761,22 @@ You need to have docker and docker-compose installed and then run
 make tests
 ```
 
-## Unsolvable problems
+### Installation with Docker for dev when your uid is not 1000
+
+for this we use fixuid (https://github.com/boxboat/fixuid)
+
+you have to define two env variable MY_UID and MY_GID with your uid and gid
+copy docker-compose.override.yml.example to docker-compose.override.yml
+
+```shell
+export MY_UID=$(id -u)
+export MY_GID=$(id -g)
+cp docker-compose.override.yml.example docker-compose.override.yml
+docker-compose up
+```
+
+Unsolvable problems
+-------------------
 
 The error `UnoException` happens frequently and 
 unpredictably, and this error stops the soffice processus 
@@ -716,7 +799,9 @@ case). Again, this is a bug in LibreOffice/soffice that has existed for years.
 For trying to fix these problems, you can try:
 - Use the most recent stable release of LibreOffice (less memory, more stable, fewer crashes)
 
-## Useful elements
+Useful elements
+---------------
+
 - [JODConverter wiki for list formats compatibles with LibreOffice](https://github.com/sbraconnier/jodconverter/wiki/Getting-Started)
 - [The unoconv source code, written in python with PyUNO](https://github.com/unoconv/unoconv/blob/master/unoconv)
 - [Unoconv source code for list formats - and properties - compatible with LibreOffice for export](https://github.com/unoconv/unoconv/blob/94161ec11ef583418a829fca188c3a878567ed84/unoconv#L391)
@@ -727,7 +812,8 @@ For trying to fix these problems, you can try:
 - [Flask documentation - quickstart](https://flask.palletsprojects.com/en/2.0.x/quickstart/)
 - [Flask documentation - upload](https://flask.palletsprojects.com/en/2.0.x/patterns/fileuploads/)
     
-## To consider
+To consider
+-----------
 
 - Possibly to add dynamic images in tables
 - another way to make image variables that would be compatible with Microsoft Word and maybe other formats (example : set the variable name in the 'alternative text' field)
@@ -735,8 +821,10 @@ For trying to fix these problems, you can try:
 - handle bulleted lists using table like variables
 - use variable formatting instead of the one of the character before
 
-## Versions :
-
+Versions
+--------
+- v1.5.1 : 2024-02-16 : Better README
+  - Rewriting of the README file
 - v1.5.0 : 2024-02-12 : syntax error detection
   - add syntax error detection in if statements
   - add syntax error detection in for statements

From 6b3547e11670e7595e2f57cc90693d2da6cba2bf Mon Sep 17 00:00:00 2001
From: Philippe Le Van <philippe.levan@kibatic.com>
Date: Fri, 16 Feb 2024 14:51:53 +0100
Subject: [PATCH 2/8] added flowchart

---
 README.md | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 5754f76..80cd0f9 100644
--- a/README.md
+++ b/README.md
@@ -5,10 +5,22 @@ LOTemplate is document generator used to create documents programatically (ODT,
 
 Templates are Word or Libreoffice documents (ODT or DOCX).
 
+```mermaid
+flowchart LR
+    template[Template<br/>in DOCX or ODT]
+    json[Data<br/>JSON]
+    lotemplate[LO Template]
+    generatedFile[Generated File<br/>PDF, DOCX, ODT]
+    
+    template --> lotemplate
+    json --> lotemplate
+    lotemplate --> generatedFile
+```
+
 What makes this tool different from others are the following features :
 
 * The templates are in DOCS or ODT format
-* Template can have complex structures (loop, conditions, counters, html,...)
+* Template can have complex structures (variables, loop, conditions, counters, html,...)
 * The tool can scan the template to extract the variables sheet
 * The tool can be called by an API, a CLI or a python module.
 

From 61d3e85836348606865c7acc876bc189ff95e807 Mon Sep 17 00:00:00 2001
From: Philippe Le Van <philippe.levan@kibatic.com>
Date: Fri, 16 Feb 2024 14:56:02 +0100
Subject: [PATCH 3/8] better schema

---
 README.md | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 80cd0f9..f053d92 100644
--- a/README.md
+++ b/README.md
@@ -3,8 +3,6 @@ LOTemplate (for Libre Office Template)
 
 LOTemplate is document generator used to create documents programatically (ODT, DOCX, PDF) from a template and a json file.
 
-Templates are Word or Libreoffice documents (ODT or DOCX).
-
 ```mermaid
 flowchart LR
     template[Template<br/>in DOCX or ODT]
@@ -19,7 +17,7 @@ flowchart LR
 
 What makes this tool different from others are the following features :
 
-* The templates are in DOCS or ODT format
+* The templates are in DOCX or ODT (Word or Libre Office) format
 * Template can have complex structures (variables, loop, conditions, counters, html,...)
 * The tool can scan the template to extract the variables sheet
 * The tool can be called by an API, a CLI or a python module.

From 77d69ea4ff162ea07f7b1306e1c45c12f7c767ab Mon Sep 17 00:00:00 2001
From: Philippe Le Van <philippe.levan@kibatic.com>
Date: Fri, 16 Feb 2024 15:07:33 +0100
Subject: [PATCH 4/8] better schema

---
 README.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index f053d92..cf51d78 100644
--- a/README.md
+++ b/README.md
@@ -7,8 +7,8 @@ LOTemplate is document generator used to create documents programatically (ODT,
 flowchart LR
     template[Template<br/>in DOCX or ODT]
     json[Data<br/>JSON]
-    lotemplate[LO Template]
-    generatedFile[Generated File<br/>PDF, DOCX, ODT]
+    lotemplate["LO Template<br/>(accessible by API or CLI)"]
+    generatedFile[Generated File<br/>PDF, DOCX, ODT, RTF,...]
     
     template --> lotemplate
     json --> lotemplate

From 300f34066e660b0bdd796f2e6e630010813ad6c2 Mon Sep 17 00:00:00 2001
From: Philippe Le Van <philippe.levan@kibatic.com>
Date: Fri, 16 Feb 2024 16:12:49 +0100
Subject: [PATCH 5/8] better schema

---
 README.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index cf51d78..e6bd71d 100644
--- a/README.md
+++ b/README.md
@@ -5,10 +5,10 @@ LOTemplate is document generator used to create documents programatically (ODT,
 
 ```mermaid
 flowchart LR
-    template[Template<br/>in DOCX or ODT]
-    json[Data<br/>JSON]
+    template["Template<br/>(DOCX or ODT)"]
+    json["Data<br/>(JSON)"]
     lotemplate["LO Template<br/>(accessible by API or CLI)"]
-    generatedFile[Generated File<br/>PDF, DOCX, ODT, RTF,...]
+    generatedFile["Generated File<br/>(PDF, DOCX, ODT, RTF,...)"]
     
     template --> lotemplate
     json --> lotemplate

From 711fed29b037bfc0213a3a825b4df918823344c2 Mon Sep 17 00:00:00 2001
From: Philippe Le Van <philippe.levan@kibatic.com>
Date: Fri, 16 Feb 2024 16:13:56 +0100
Subject: [PATCH 6/8] fix markdown syntax

---
 README.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/README.md b/README.md
index e6bd71d..5b24508 100644
--- a/README.md
+++ b/README.md
@@ -833,6 +833,7 @@ To consider
 
 Versions
 --------
+
 - v1.5.1 : 2024-02-16 : Better README
   - Rewriting of the README file
 - v1.5.0 : 2024-02-12 : syntax error detection

From 1765be5db7030fdf529d285cb26297a401af468b Mon Sep 17 00:00:00 2001
From: Philippe Le Van <philippe.levan@kibatic.com>
Date: Fri, 16 Feb 2024 17:05:33 +0100
Subject: [PATCH 7/8] table of contents

---
 README.md | 60 +++++++++++++++++++++++++++++++++----------------------
 1 file changed, 36 insertions(+), 24 deletions(-)

diff --git a/README.md b/README.md
index 5b24508..3109429 100644
--- a/README.md
+++ b/README.md
@@ -93,8 +93,20 @@ My tag is foo
 
 ```
 
-Installation
-------------
+Table of content
+----------------
+
+* [Installation](#installation)
+* [Basic Usage](#basic-usage)
+* [Template Syntax](#template-syntax)
+* [Supported formats](#supported-formats)
+* [Doc for developpers of lotemplate](#doc-for-devs)
+* [Unsolvable problems](#unsolvable-problems)
+* [External documentations](#external-documentations)
+* [Versions](#versions)
+
+<a name="installation"></a>Installation
+---------------------------------------
 
 ### Requirements
 
@@ -133,8 +145,8 @@ or, for Docker deployment:
 docker-compose up
 ```
 
-Basic Usage
------------
+<a name="basic-usage"></a>Basic Usage
+-------------------------------------
 
 ### With the API
 
@@ -276,8 +288,8 @@ of an array to dynamically add rows. Then pass the file, and the completed json
 to fill it.
 
 
-Template Syntax
----------------
+<a name="template-syntax"></a>Template Syntax
+---------------------------------------------
 
 ### text variables
 
@@ -742,7 +754,8 @@ we displayed [counter.last iterator] solutions
 ```
 
 
-## Supported formats
+<a name="supported-formats"></a>Supported formats
+-------------------------------------------------
 
 ### Import
 | Format                  | ODT, OTT | HTML | DOC, DOCX | RTF | TXT | OTHER |
@@ -760,8 +773,8 @@ Other formats can be easily added by adding the format information in the dictio
 Format information can be found on the 
 [unoconv repo](https://github.com/unoconv/unoconv/blob/94161ec11ef583418a829fca188c3a878567ed84/unoconv#L391).
 
-Doc for developpers of lotemplate
----------------------------------
+<a name="doc-for-dev"></a>Doc for developpers of lotemplate
+-----------------------------------------------------------
 
 ### Run the tests
 
@@ -785,8 +798,8 @@ cp docker-compose.override.yml.example docker-compose.override.yml
 docker-compose up
 ```
 
-Unsolvable problems
--------------------
+<a name="unsolvable-problems"></a>Unsolvable problems
+-----------------------------------------------------
 
 The error `UnoException` happens frequently and 
 unpredictably, and this error stops the soffice processus 
@@ -809,8 +822,8 @@ case). Again, this is a bug in LibreOffice/soffice that has existed for years.
 For trying to fix these problems, you can try:
 - Use the most recent stable release of LibreOffice (less memory, more stable, fewer crashes)
 
-Useful elements
----------------
+<a name="external-documentations"></a>External documentations
+---------------------------------------------------------
 
 - [JODConverter wiki for list formats compatibles with LibreOffice](https://github.com/sbraconnier/jodconverter/wiki/Getting-Started)
 - [The unoconv source code, written in python with PyUNO](https://github.com/unoconv/unoconv/blob/master/unoconv)
@@ -821,18 +834,9 @@ Useful elements
 - [Deploying Flask](https://flask.palletsprojects.com/en/2.0.x/deploying/)
 - [Flask documentation - quickstart](https://flask.palletsprojects.com/en/2.0.x/quickstart/)
 - [Flask documentation - upload](https://flask.palletsprojects.com/en/2.0.x/patterns/fileuploads/)
-    
-To consider
------------
-
-- Possibly to add dynamic images in tables
-- another way to make image variables that would be compatible with Microsoft Word and maybe other formats (example : set the variable name in the 'alternative text' field)
-- key system for each institution for security
-- handle bulleted lists using table like variables
-- use variable formatting instead of the one of the character before
 
-Versions
---------
+<a name="versions"></a>Versions
+-------------------------------
 
 - v1.5.1 : 2024-02-16 : Better README
   - Rewriting of the README file
@@ -871,3 +875,11 @@ Versions
 - v1.0.1, 2023-05-05 : workaround, fix in html formatting
 - v1.0.0, 2023-05-03 : if statement, for statement, html statement
 - not numbered : about may 2022 : first version
+
+### Possible futur evolutions
+
+- Possibly to add dynamic images in tables
+- another way to make image variables that would be compatible with Microsoft Word and maybe other formats (example : set the variable name in the 'alternative text' field)
+- key system for each institution for security
+- handle bulleted lists using table like variables
+- use variable formatting instead of the one of the character before

From e1e3b2d585c526fffae3033ebab644b001498db0 Mon Sep 17 00:00:00 2001
From: Philippe Le Van <philippe.levan@kibatic.com>
Date: Fri, 16 Feb 2024 17:09:31 +0100
Subject: [PATCH 8/8] table of contents fixed

---
 README.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 3109429..6636983 100644
--- a/README.md
+++ b/README.md
@@ -98,7 +98,7 @@ Table of content
 
 * [Installation](#installation)
 * [Basic Usage](#basic-usage)
-* [Template Syntax](#template-syntax)
+* [Template syntax and examples](#template-syntax)
 * [Supported formats](#supported-formats)
 * [Doc for developpers of lotemplate](#doc-for-devs)
 * [Unsolvable problems](#unsolvable-problems)
@@ -288,8 +288,8 @@ of an array to dynamically add rows. Then pass the file, and the completed json
 to fill it.
 
 
-<a name="template-syntax"></a>Template Syntax
----------------------------------------------
+<a name="template-syntax"></a>Template syntax and examples
+----------------------------------------------------------
 
 ### text variables
 
@@ -773,7 +773,7 @@ Other formats can be easily added by adding the format information in the dictio
 Format information can be found on the 
 [unoconv repo](https://github.com/unoconv/unoconv/blob/94161ec11ef583418a829fca188c3a878567ed84/unoconv#L391).
 
-<a name="doc-for-dev"></a>Doc for developpers of lotemplate
+<a name="doc-for-devs"></a>Doc for developpers of lotemplate
 -----------------------------------------------------------
 
 ### Run the tests