AR282 fix FR user doc + add partial EN user doc

doc/user/EN/README.md

@@ -0,0 +1,11 @@
+# User documentation
+
+_Note : english documentation is not fully translated yet_
+
+* [How to install _Find and Compare Records_](./how_to_install.md)
+* [Input file documentation](./input_file.md)
+* [How to use _Find and Compare Records_](./how_to_use.md)
+* [List & informations about available processings](./processings.md)
+* [Analysis documentation](./analysis.md)
+* [Results file documentation](./output_files.md)
+* [Computed output data documentation](./output_data.md)

doc/user/EN/analysis.md

@@ -0,0 +1,84 @@
+# Analysis documentation
+
+## Comparaison des données entre les bases
+
+Une fois toutes les informations récupérées, compare les données entre les deux bases :
+
+* Pour le titre : génère un score de similarité, d'appartenance, d'inversion et d'inversion appartenance à l'aide de [la distance de Levenshtein](https://fr.wikipedia.org/wiki/Distance_de_Levenshtein)
+* Pour les dates de publication : vérifie si l'un des dates de la base de données d'origine est comprise dans l'une des dates de la base de données de destination (ne compare pas si les dates ne sont pas renseignées)
+* Pour les éditeurs : compare chaque éditeur de la base de données d'origine avec chaque éditeur de la base de donnée de destination en génèrant un score de similarité, puis renvoie la paire avec le score le plus élevé.
+
+Ensuite, le script valide ou non chaque critère de comparaison de l'analyse choisie et indique un degré de validation pour cette comparaison.
+
+## Analyse des résultats des correspondances
+
+L'analyse des résultats des correspondances se base sur 3 critères :
+
+1. sur les 4 formes du titre étudiée, la correspondance des titres est supérieure à un seuil minimum pour au moins X d'entre eux
+1. la correspondance des éditeurs est supérieure à un seuil minimum
+1. la correspondance des dates de publication est prise en compte ou non
+
+## Résultats de l'analyse
+
+L'analyse renvoie 5 données :
+
+* _Validation globale_ : résultat final de l'analyse, prend la valeur :
+  * _Vérifications complètes_ : tous les critères sélectionnés sont validés
+  * _Vérifications partielles_ : une partie des critères sélectionnés sont validés
+  * _Vérifications KO_ : aucun des critères sélectionnés n'a été validé
+  * _Pas de vérification_ : l'analyse choisie n'effectue aucune vérification
+  * Si rien ne s'affiche, l'analyse n'a pas eu lieu
+* _Nombre de validations réussies_ : le nombre de critéères sélectionnés qui ont été validés
+* _Validation des titres_ :
+  * `True` si le nombre de formes du titre ayant un score supérieur ou égal au seuil minimum requis est supérieur ou égal au nombre minimum requis
+  * `False` si ce n'est pas le cas
+* _Validation des éditeurs_
+  * `True` si le score de correspondance de la pair d'éditeur choisie est supérieur ou égal au seuil minimum requis
+  * `False` si ce n'est pas le cas
+* _Validation des dates_
+  * `True` si l'une des dates de Koha correspond à l'une de celles du Sudoc
+  * `False` si ce n'est pas le cas
+
+_Note : les détails (notamment les scores de similarités) sont disponibles à la fin des colonnes udu fichier de sortie_
+
+## Configurations des analyses par défaut
+
+_Si les seuils minimum sont configurés à 0, l'analyse ignorera le critère en question._
+
+### Analyse 0 : Aucune analyse
+
+* Seuil minimum pour la correspondance des titres : `0`
+* Nombre minimum de formes du titre devant être supérieur au seuil : `0`
+* Seuil minimum pour la correspondance des éditeurs : `0`
+* Utilisation de la date de publication : `NON`
+
+### Analyse 1 : Titre 80 (3/4), Editeurs 80, Dates
+
+* Seuil minimum pour la correspondance des titres : `80`
+* Nombre minimum de formes du titre devant être supérieur au seuil : `3`
+* Seuil minimum pour la correspondance des éditeurs : `80`
+* Utilisation de la date de publication : `OUI`
+
+### Analyse 2 : Titre 90
+
+* Seuil minimum pour la correspondance des titres : `90`
+* Nombre minimum de formes du titre devant être supérieur au seuil : `4`
+* Seuil minimum pour la correspondance des éditeurs : `0`
+* Utilisation de la date de publication : `NON`
+
+### Analyse 3 : Titre 95, Editeurs 95
+
+* Seuil minimum pour la correspondance des titres : `95`
+* Nombre minimum de formes du titre devant être supérieur au seuil : `4`
+* Seuil minimum pour la correspondance des éditeurs : `95`
+* Utilisation de la date de publication : `NON`
+
+## Configurer une analyse
+
+Pour ajouter une nouvelle analyse, il faut rajouter un nouvel objet dans `analysis.json` avec les clefs suivantes :
+
+* `name` `(str)`: nom de l'analyse qui s'affichera dans les interfaces
+* `TITLE_MIN_SCORE` (`int`) : seuil minimum requis pour que la correspondances des titres soit considérée comme OK
+* `NB_TITLE_OK` (`int`) : nombre minimum de correspondance de formes de titre requis pour que le critère de correspondance des titres soit considéré comme OK
+* `PUBLISHER_MIN_SCORE` (`int`) : seuil minimum requis pour que la correspondances des éditeurs soit considérée comme OK
+* `USE_DATE` (`bool`) : utilisation du critère correspondance des dates de publication

doc/user/EN/how_to_install.md

@@ -0,0 +1,47 @@
+# How to install _Find and Compare Records_
+
+Download the application and extract its content.
+
+## Bibliothèques utilisées non incluses dans Python Standard Library
+
+Those libraries are used by the script but are not in the [Python Standard Library](https://docs.python.org/3/library/), all of them should be installed first :
+
+* _Reminder : with Windows, open the command terminal and write the following command lines after `py -m` (or `pyhton -m`)_
+* [`unidecode`](https://pypi.org/project/Unidecode/) (`pip install Unidecode==1.3.8`)
+* [`FuzzyWuzzy`](https://pypi.org/project/fuzzywuzzy/) (`pip install fuzzywuzzy==0.18.0`)
+  * With [`python-Levenshtein`](https://pypi.org/project/python-Levenshtein/) (`pip install python-Levenshtein==0.25.1`), installed with `rapidfuzz` `3.9.3`
+* [`FreeSimpleGUI`](https://pypi.org/project/FreeSimpleGUI/) (`pip install FreeSimpleGUI==5.1.0`)
+* [`requests`](https://pypi.org/project/requests/) (`pip install requests==2.32.3`)
+* [`python-dotenv`](https://pypi.org/project/python-dotenv/) (`pip install python-dotenv==1.0.1`)
+* [`pymarc`](https://pypi.org/project/pymarc/) (`pip install pymarc==4.2.2` __(do not use versions `5.X.X` as some functions are not retrocompatible)__)
+* [`pyisbn`](https://pypi.org/project/pyisbn) (`pip install pyisbn==1.3.1`)
+
+## Configuration file
+
+At the root of the application is `sample.env` file which needs to be renammed in `.env`.
+Or you need to create a new file `.env` with variables :
+
+* General variables :
+    * `SERVICE` : name of the service (for logs, including the file name)
+    * `LANG` : the user interface language in ISO 639-2 format (`fre` & `eng` are the onyl supported language)
+    * `PROCESSING_VAL` : `BETTER_ITEM`, `MARC_FILE_IN_KOHA_SRU`, `BETTER_ITEM_DVD`, `BETTER_ITEM_NO_ISBN` or `BETTER_ITEM_MAPS`
+* Database URL :
+  * `ORIGIN_URL` : origin database URL (domain name)
+  * `TARGET_URL` : target database URL (domain name)
+* Processing variables for `BETTER_ITEM` suite :
+  * `ILN` : institution ILN for the library
+  * `RCR` : library RCR
+* Processing variables for `MARC_FILE_IN_KOHA_SRU` :
+  * `FILTER1`
+  * `FILTER2`
+  * `FILTER3`
+* Databases mapping :
+  * `ORIGIN_DATABASE_MAPPING` : origin database mapping name (`ORIGIN_DATABASE` by default)
+  * `TARGET_DATABASE_MAPPING` : target database mapping name (`TARGET_DATABASE` by default)
+* Logs configuration :
+  * `LOGS_PATH` : full path to the folder containing the log file
+  * `LOG_LEVEL` : logging level to use : `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL` (`INFO` by default)
+* Paths to file & folders :
+  * `CSV_OUTPUT_JSON_CONFIG_PATH` : CSV export configuration file path
+  * `FILE_PATH` : input file path
+  * `OUTPUT_PATH` : output folder path

doc/user/EN/how_to_use.md

@@ -0,0 +1,122 @@
+# How to use _Find and Compare Records_
+
+Une fois l'application téléchargée et le fichier `sample.env` renommé en `.env`, vous pouvez exécuter l'application.
+
+Pour ce faire :
+
+* Exécuter le fichier `FCR.bat` situé à la racine de l'application
+* Ou, avec l'invite de commande, placez-vous dans le répertoire de l'application (avec `cd`) et exécuter avec Python le fichier `main_gui.py`
+
+## Étape 1 : configuration principale
+
+![Écran principal de _Find and Compare Records_](./img/UI_main_screen.png)
+
+_Le bouton en haut à droite permet de changer la langue de l'interface du entre le français et l'anglais._
+
+Cet écran permet de configurer les paramètres généraux de l'application à savoir :
+
+* Le traitement qui sera exécuté _([voir plus d'informations sur les traitements disponibles](./processings.md))_
+* Les chemins d'accès :
+  * Au fichier à analyser _([voir plus d'informations sur ce fichier](./input_file.md))_
+  * Au dossier qui contiendra les fichiers de résultats
+  * Au dossier qui contiendra le fichier des journaux
+* Le nom du service (qui sert uniquement pour les journaux, notamment pour nommer le fichier)
+* Le niveau de journalisation
+
+Le bouton _Sauvegarder ces paramètres d'exécution_ permet de sauvegarder les paramètres actuellement définis sur l'interface pour une prochaine exécution (langue comprise).
+
+Une fois cet écran correctement paramétré (voire sauvegardé), le bouton _Suivant (configuration du traitement)_ permet de passer à la seconde étape.
+
+## Étape 2 : configuration du traitement
+
+Ce nouvel écran contient 3 onglets :
+
+* _Configuration principale du traitement_
+* _Configuration des mappings_
+* _Choix des mappings de BDD_
+
+Par ailleurs, sous le titre de l'écran, le traitement choisi est rappelé.
+
+Une fois la configuration de tous les onglets terminée, le bouton _Lancer l'analyse_ permet de passer à la troisième et dernière étape.
+
+### Onglet _Configuration principale du traitement_
+
+Cet onglet n'affiche pas les mêmes options selon le traitement choisi.
+
+Le bouton _Sauvegarder les paramètres principaux de ce traitement_ permet de sauvegarder les paramètres actuellement définis sur l'interface pour une prochaine exécution.
+
+
+#### Suite `BETTER_ITEM`
+
+![Écran de configuration du traitement, onglet de configuration principale pour `BETTER_ITEM`](./img/UI_processing_conf_main_tab_better_item.png)
+
+* URL de la base de données d'origine : ce traitement récupère les données de la base de données d'origine via les APIs de celle-ci, il faut donc indiquer __le nom de domaine qui permet d'exécuter les APIs__
+* ILN : l'ILN de l'établissement concerné _(utilisé pour filtrer les identifiants dans les autres bases de données)_
+* RCR : le RCR de la bibliothèque concernée _(utilisé pour filtrer les exempalires et code-barres d'exemplaires)_
+
+#### `MARC_FILE_IN_KOHA_SRU`
+
+![Écran de configuration du traitement, onglet de configuration principale pour `MARC_FILE_IN_KOHA_SRU`](./img/UI_processing_conf_main_tab_marc_file_in_koha_sru.png)
+
+* URL de la base de données de destination : ce traitement récupère les données de la base de données de destination via les APIs de celle-ci, il faut donc indiquer __le nom de domaine qui permet d'exécuter les APIs__ (ou se connecter au SRU si c'est via le SRU)
+* Filtre 1, 2 & 3 : filtre libres, configurables en fonction de la base de données de destination (ou d'origine)
+  * Le filtre 1 est utilisé pour filtrer les exempalires et code-barres d'exemplaires
+  * Pour lier des filtres à des données, il est nécessaire de modifier le code dans `cl_PODA.py` ([voir la documentation développeur sur les PODAs à ce sujet](../../PODAs.md#database))
+
+### Onglet _Configuration des mappings_
+
+![Écran de configuration du traitement, onglet de configuration des mappings](./img/UI_processing_conf_db_conf_tab.png)
+
+Cet onglet est le plus complexe mais également celui qui, une fois sauvegardée, n'a plus besoin d'être reconfiguré.
+
+Il permet de configurer via une interface quelles données seront récupérées dans les notices bibliographiques (configurées dans le fichier `json_configs/marc_fields.json`).
+Pour plus d'informations sur comment configurer ces mappings, se référer à [la documentation sur l'extracteur de données universel](../../../doc/UDE.md).
+
+Dans un premier temps, il est nécessaire de sélectionner le mapping que l'on souhaite modifier.
+Il est possible de créer un nouveau mapping à l'aide du bouton _Sauvegarder ce mapping comme un nouveau_, qui copiera l'ensemble des données actuellement configurées pour le mapping actuellement sélectionné vers le nouveau.
+Le bouton ouvrira une boîte de dialogue vous demandant de renseigner le nom du nouveau mapping, il faudra ensuite valider avec `Ok` pour procéder à la sauvegarde.
+
+![Boîte de dialogue pour enregistrer le nouveau mapping](./img/UI_save_new_mapping.png)
+
+Dans un second temps, il est nécessaire de choisir la donnée à configurer.
+Il est possible de renommer cette donnée pour la langue actuelle avec le bouton _Renommer_.
+Le bouton ouvrira une boîte de dialogue vous demandant de renseigner le nouveau nom de la donnée, il faudra ensuite valider avec `Ok` pour procéder à la sauvegarde.
+Pour s'assurer de la donnée qui est en cours d'édition, entre parenthèses se trouve l'identifiant de la donnée.
+
+![Boîte de dialogue pour enregistrer le nouveau nom de la donnée](./img/UI_save_new_data_name.png)
+
+Dans un troisième temps, il est nécessaire de choisir le champ UNIMARC à configurer.
+Pour chaque champ, quatre données sont à remplir (ou non) :
+
+* Est une donnée codée en une ligne : permet de déterminer si le champ est une donnée codée présente dans un seul sous-champ (exemple `100`)
+* Sous-champ filtre : permet de renseigner le sous-champ qui doit permettre d'exclure les champs non voulus (exemple : uniquement traiter les exemplaires de la bibliothèque renseignée)
+* Sous-champs à exporter : la liste des sous-champs à exporter, qui doivent être séparés par des virgules (les espaces entre les virgules ne sont pas pris en compte)
+* Positions à exporter :
+  * La liste des positions à exporter, qui doivent être séparées par des virgules (les espaces entre les virgules ne sont pas pris en compte)
+  * Cette information n'est utile que si le champ est déterminé comme étant une donnée codée en une seule ligne
+  * Pour extraire un caractère uniquement, renseigner sa position
+  * Pour extraire une chaîne de caractères, renseigner la première position à exporter et la dernière position à exporter, séparées par un tiret
+
+Pour ajouter des nouveaux champs, sélectionner le champ `Ajouter un nouveau champ`, qui fera apparaître une nouvelle donnée à remplir à côté de lui.
+Renseignez dedans le numéro du champ voulu.
+
+![Configuration d'un nouveau champ](./img/UI_add_new_field.png)
+
+Pour sauvegarder la modification effectuée sur le champ, cliquez sur le bouton _Sauvegarder ce champ MARC_.
+Cette opération est nécessaire __pour chaque champ__, sinon les données ne seront pas sauvegardées.
+
+### Onglet _Choix des mappings de BDD_
+
+![Écran de configuration du traitement, onglet de choix des mappings de base de données](./img/UI_processing_conf_chose_mapping_tab.png)
+
+Cet onglet est le plus simple puisqu'il suffit de choisir le mapping que l'on souhaite attribuer à la base de donnée d'origine et à la base de donnée de destination.
+
+Le bouton _Sauvegarder les mappings de BDD choisis_ permet de sauvegarder les paramètres actuellement définis sur l'interface pour une prochaine exécution.
+
+## Étape 3 : choisir l'analyse
+
+![Fenêtre de choix de l'analyse](./img/UI_chose_analysis.png)
+
+Cette dernière fenêtre permet de choisir l'analyse voulue parmis celles définies dans le fichier `json_configs/analysis.json`.
+
+Le bouton _Lancer le script principal_ permet (enfin) de lancer le script.

doc/user/EN/input_file.md

@@ -0,0 +1,24 @@
+# Input file documentation
+
+Le fichier à traiter varie selon le traitement sélectionné :
+
+* [Suite `BETTER_ITEM`](#suite-better_item) (`BETTER_ITEM`, `BETTER_ITEM_DVD`, `BETTER_ITEM_NO_ISBN`, `BETTER_ITEM_MAPS`)
+* [`MARC_FILE_IN_KOHA_SRU`](#marc_file_in_koha_sru)
+
+## Suite `BETTER_ITEM`
+
+Le fichier utilisé est un fichier de type CSV utilisant un `;` comme délimiteur.
+
+Celui-ci contient les informations d'un exemplaire, l'identifiant dans la base de donnée d'origine et (parfois) un identifiant pour certaines requêtes.
+Ce dernier identifiant est utilisé unisuement pour le traitement `BETTER_ITEM` et doit être un ISBN.
+
+Le fichier doit __forcément__ avoir comme :
+
+* Première colonne la colonne contenant l'identifiant pour les reqûetes (l'ISBN pour `BETTER_ITEM`, une colonne vide ou avec un autre donnée pour les autres)
+* Dernière colonne celle contenant l'identifiant de la base de donnée d'origine
+
+Toutes les colonnes du fichier seront exportées à la fin du fichier de sortie.
+
+## `MARC_FILE_IN_KOHA_SRU`
+
+Le fichier utilisé est un simple fichier de notices en ISO 2709, contenant les exemplaires.