xml2xlsx-lidilem 0.2.8.6

Convertisseur XML annoté vers Excel (corpus littéraires PREFAB)

xml2xlsx

Convertisseur XML annoté vers Excel — Corpus littéraires PREFAB Version 0.2.8

---

Table des matières

1. Présentation
2. Installation
3. Schéma de données : DTD ou PREFAB
4. Règle d'or : le nommage des colonnes Excel
5. Modes de fonctionnement
   • 5.1 Fichier XML unique
   • 5.2 Dossier
   • 5.3 Réécriture XML
6. Cas pratiques de réécriture XML
7. Vérification d'intégrité
8. Interface graphique (GUI)
9. Interface en ligne de commande (CLI)
10. Formatage Excel et colorisation
11. Récapitulatif des modes
12. Dépannage
13. Licence

---

1. Présentation

xml2xlsx est un outil de conversion bidirectionnel entre fichiers XML annotés (corpus PREFAB) et tableurs Excel (.xlsx). Il permet d'extraire la structure XML vers Excel pour faciliter l'annotation et la révision, puis de réinjecter les modifications Excel dans le XML source.

Fonctionnalités principales :

• Extraction XML → Excel (fichier unique ou dossier entier)
• Réécriture XML à partir d'un Excel modifié (mode reverse)
• Détection automatique de la hiérarchie via DTD ou schéma PREFAB intégré
• Colorisation riche des balises dans Excel
• Vérification d'intégrité automatique après chaque conversion
• Interface graphique (GUI) et interface en ligne de commande (CLI)

---

2. Installation

Prérequis

• Python 3.8+
• Dépendances : openpyxl, pandas, numpy, lxml, tk

Via pip

pip install xml2xlsx-lidilem

En développement

git clone <url-du-dépôt>
cd xml2xlsx-lidilem
pip install -e .

Commandes disponibles après installation

Commande	Description
xml2xlsx	Lance le convertisseur en mode CLI
xml2xlsx-gui	Lance l'interface graphique

---

3. Schéma de données : DTD ou PREFAB

L'outil a besoin de connaître la hiérarchie des balises XML pour générer les colonnes Excel correctes. Deux options existent.

3.1 Schéma DTD (recommandé)

Fournissez un fichier .dtd décrivant les éléments et leurs attributs. L'outil parse automatiquement <!ELEMENT> et <!ATTLIST> pour construire la hiérarchie dynamiquement.

Avantages : portable, extensible, pas de modification du code source.

3.2 Schéma PREFAB intégré (fallback)

Sans DTD, l'outil utilise le schéma PREFAB codé en dur, adapté aux corpus littéraires PREFAB :

Balise parente	Enfants attendus	Attributs
p	INTRODD, PPI, NONPPI, MD, APP	—
INTRODD	EXPANSION, VDD, MOD	position
PPI	MD	decl, type, position
VDD	EXPANSION	type, lemme
EXPANSION	—	constr, type

Note : Le mode GUI affiche [schema] Schéma PREFAB intégré ou [schema] DTD chargé : chemin/vers/schema.dtd dans le journal au démarrage.

---

4. Règle d'or : le nommage des colonnes Excel

Le nom de chaque colonne encode la hiérarchie XML de la balise cible. Chaque niveau est séparé par un underscore (_). Le suffixe final indique le type de valeur :

Suffixe	Signification	Exemple
_text	Contenu textuel de la balise	INTRODD_text
_nomAttribut	Valeur de l'attribut nomAttribut	INTRODD_position
_2, _3…	2ème, 3ème occurrence de balise répétée	INTRODD_EXPANSION_2_text

Exemples de nommage

Nom de colonne	Ce que l'outil va faire
INTRODD_text	Lire/écrire le texte de <INTRODD>
INTRODD_position	Lire/écrire l'attribut position de <INTRODD>
INTRODD_EXPANSION_text	Lire/écrire le texte de <EXPANSION> dans <INTRODD>
INTRODD_EXPANSION_REL_text	Créer/modifier <REL> dans <EXPANSION> dans <INTRODD>
INTRODD_EXPANSION_REL_type	Ajouter l'attribut type à <REL>
INTRODD_EXPANSION_2_text	Deuxième <EXPANSION> dans <INTRODD>

Cibler une occurrence répétée dans le texte

Pour cibler la Nème occurrence d'un texte répété dans une balise, ajoutez _N à la valeur dans la cellule (jamais dans le nom de la colonne). Le suffixe est retiré automatiquement avant injection dans le XML.

Valeur dans la cellule	Occurrence ciblée
Vite !	1ère occurrence (défaut)
Vite !_2	2ème occurrence
Vite !_3	3ème occurrence

Règle : Une cellule vide n'est jamais reportée. L'outil ne touche qu'aux cellules qui contiennent une valeur.

---

5. Modes de fonctionnement

L'outil propose trois modes d'opération, accessibles en GUI comme en CLI.

---

5.1 Mode Fichier XML unique (XML → Excel)

Convertit un seul fichier .xml en un tableur .xlsx. Le fichier Excel est créé à côté du XML source avec le même nom.

Colonnes produites :

• source_file — nom du fichier source
• p_id — identifiant du paragraphe
• paragraph_text — texte complet avec balises inline colorisées
• Une colonne par balise et attribut détectés dans la hiérarchie

En GUI

Sélectionnez le bouton radio Fichier XML, puis choisissez le fichier via Parcourir… Cliquez sur ▶ Lancer.

Les options XLSX individuel par fichier et Fichier XLSX maître sont désactivées en ce mode (non pertinentes pour un fichier unique).

En CLI

# Conversion simple
xml2xlsx mon_fichier.xml

# Avec sortie nommée
xml2xlsx mon_fichier.xml resultats.xlsx

# Avec DTD personnalisée
xml2xlsx mon_fichier.xml --dtd schema.dtd

# Avec calcul de POSITION_INTRODD
xml2xlsx mon_fichier.xml --position

---

5.2 Mode Dossier (XML → Excel, traitement par lots)

Traite tous les fichiers .xml d'un dossier. Produit un fichier Excel individuel par XML et/ou un fichier Excel maître consolidant tous les fichiers.

Fichiers produits :

• Fichier individuel (optionnel) : nom_fichier.xlsx à côté de chaque XML
• Fichier maître (optionnel) : master_output.xlsx dans le dossier source

Les textes du fichier maître sont automatiquement mis en minuscules (sauf paragraph_text, INTRODD_text et quelques colonnes préservées — voir section 10).

En GUI

Sélectionnez le bouton radio Dossier, choisissez le dossier via Parcourir…

Options disponibles :

• XLSX individuel par fichier — génère un fichier Excel par XML (coché par défaut)
• Fichier XLSX maître — génère le fichier consolidé (coché par défaut)
• Calculer POSITION_INTRODD — ajoute une colonne indiquant si INTRODD est avant ou après PPI (ANTE / POST / AUTRE)

En CLI

# Dossier complet (individuel + maître)
xml2xlsx /chemin/vers/dossier/

# Dossier avec sortie maître nommée
xml2xlsx /chemin/vers/dossier/ resultats_consolides.xlsx

# Dossier sans fichiers individuels
xml2xlsx /chemin/vers/dossier/ --no-individual

# Dossier + DTD + calcul de position
xml2xlsx /chemin/vers/dossier/ --dtd schema.dtd --position

---

5.3 Mode Réécriture XML (Excel → XML)

Lit un fichier Excel modifié et reporte les valeurs annotées dans le XML source correspondant. L'outil génère un nouveau fichier XML suffixé _updated.xml sans écraser l'original.

Principe de fonctionnement :

L'outil lit les noms de colonnes de l'Excel pour déduire la hiérarchie XML cible. Pour chaque cellule non vide :

• Si la balise existe déjà dans le XML → son contenu ou attribut est mis à jour
• Si la balise n'existe pas encore → elle est créée et insérée à la bonne position dans la hiérarchie
• Si la valeur cellule se termine par _N → la Nème occurrence textuelle du mot est balisée

En GUI

Sélectionnez Réécrire XML. Deux champs deviennent actifs :

• Fichier Excel modifié — le fichier .xlsx contenant les annotations
• XML original (reverse) — le fichier .xml source dans lequel injecter les modifications

Le DTD est optionnel mais recommandé pour les schémas hors PREFAB.

En CLI

# Réécriture XML depuis Excel
xml2xlsx annotations.xlsx --reverse original.xml

# Avec DTD
xml2xlsx annotations.xlsx --reverse original.xml --dtd schema.dtd

Le fichier de sortie est automatiquement nommé original_updated.xml dans le même répertoire que le XML source.

---

6. Cas pratiques de réécriture XML

Cas 1 : Ajouter une balise dans une hiérarchie profonde

Situation : on dispose d'un XML contenant <INTRODD> avec une <EXPANSION>. On souhaite annoter la relative à l'intérieur de l'expansion en créant une balise <REL>.

Étape 1 : Créer la colonne dans l'Excel

La hiérarchie est INTRODD > EXPANSION > REL. Le nom de la colonne reflète cette hiérarchie de haut en bas :

Niveau	Balise	Nom de colonne cumulé
1 (ancêtre)	INTRODD	INTRODD
2 (enfant)	EXPANSION	INTRODD_EXPANSION
3 (cible)	REL	INTRODD_EXPANSION_REL
Suffixe texte	—	INTRODD_EXPANSION_REL_text ← nom final

Étape 2 : Renseigner la cellule

Dans la colonne INTRODD_EXPANSION_REL_text, saisir le texte de la relative :

dont on reconnaît cependant l'ancienne grandeur aux vestiges des monuments

Étape 3 : Ajouter un attribut

Pour qualifier la balise <REL> avec un attribut type, ajouter une colonne INTRODD_EXPANSION_REL_type :

Colonne Excel	Valeur saisie	Effet dans le XML
INTRODD_EXPANSION_REL_text	dont on reconnaît…	Crée <REL>…</REL>
INTRODD_EXPANSION_REL_type	relative avec 'dont'	Ajoute type="relative avec 'dont'"

Résultat XML

<EXPANSION constr="SN" type="verbal">
  sur un ton de modestie forcée…,
  <REL type="relative avec 'dont'">dont on reconnaît cependant
  l'ancienne grandeur aux vestiges des monuments</REL>,
  avait dû être véritablement quelque chose.
</EXPANSION>

Pour une deuxième relative dans la même <EXPANSION> : créer la colonne INTRODD_EXPANSION_REL_2_text. Pour des balises enfants de <REL>, prolonger la hiérarchie : INTRODD_EXPANSION_REL_ADJ_text, etc.

---

Cas 2 : Cibler une occurrence précise d'un mot répété

Situation : un paragraphe contient deux occurrences de « Vite ! » et on veut annoter uniquement la deuxième.

Étape 1 : Créer la colonne

La balise <ADV> est enfant direct de <p>, donc pas de préfixe parent. Nom de colonne : ADV_text.

Étape 2 : Renseigner la valeur avec suffixe d'occurrence

Dans la cellule de la colonne ADV_text, saisir Vite !_2. Le suffixe _2 est retiré automatiquement : la balise XML contiendra uniquement « Vite ! ».

Résultat XML

… il s'agissait d'accélérer le mouvement.
Vite ! <ADV>Vite !</ADV> Sept heures dix…

La première occurrence reste inchangée, seule la deuxième est balisée.

---

7. Vérification d'intégrité

Après chaque conversion (XML→Excel ou Excel→XML), l'outil effectue automatiquement un contrôle d'intégrité. Le rapport s'affiche dans le journal (GUI) ou la console (CLI).

Symboles du rapport

Symbole	Signification
✅ Intégrité confirmée	Aucune perte, toutes les balises présentes
✅ OK: N nouveau(x) tag(s)	Nouvelles balises ajoutées, rien de perdu
✓ Tag X : N (inchangé)	Balise X présente en même nombre qu'avant
✓ Tag X augmenté	Balise X ajoutée (normal lors d'une annotation)
➕ Nouveau tag X	Balise X absente du XML original, nouvellement créée
⚠️ Tag X réduit	Nombre de balises X diminué — à vérifier
❌ Tag X supprimé	Balise X disparue — problème à corriger
❌ Problèmes détectés	Des données ont été perdues — ne pas utiliser ce fichier

Exemple de rapport correct (ajout de <REL>)

▶ Vérification de l'intégrité…
  ✅ OK: 1 nouveau tag ajouté, aucune perte
  ✓ Tag 'text': 1 (inchangé)
  ✓ Tag 'p': 343 (inchangé)
  ✓ Tag 'INTRODD': 134 (inchangé)
  ✓ Tag 'VDD': 118 (inchangé)
  ✓ Tag 'PPI': 342 (inchangé)
  ✓ Tag 'EXPANSION': 35 (inchangé)
  ➕ Nouveau tag 'REL' (1 instance)

Important : Si le rapport affiche des lignes ❌, ne pas utiliser le fichier XML produit. Vérifiez les valeurs saisies et relancez la conversion.

---

8. Interface graphique (GUI)

xml2xlsx-gui

8.1 Panneau de gauche : Contrôles

Source d'entrée

Trois boutons radio sélectionnent le mode :

• Dossier — traitement par lots de tous les .xml d'un dossier
• Fichier XML — conversion d'un seul fichier XML
• Réécrire XML — injection des annotations Excel dans le XML source

Chemins

Selon le mode sélectionné, le libellé du premier champ change :

• Dossier XML — en mode Dossier
• Fichier XML — en mode Fichier XML
• Fichier Excel modifié — en mode Réécrire XML

En mode Réécrire XML, le champ XML original (reverse) devient actif et obligatoire.

Schéma DTD (optionnel)

Permet de charger un fichier .dtd externe. Si laissé vide, le schéma PREFAB intégré est utilisé.

Options

Option	Description	Modes actifs
XLSX individuel par fichier	Génère un .xlsx par fichier XML traité	Dossier uniquement
Fichier XLSX maître	Génère master_output.xlsx consolidant tous les fichiers	Dossier uniquement
Calculer POSITION_INTRODD	Ajoute une colonne ANTE/POST/AUTRE selon position d'INTRODD par rapport à PPI	Tous modes XML→Excel

8.2 Panneau de droite : Journal

Affiche en temps réel le déroulement de la conversion : fichiers traités, résultats de l'intégrité, erreurs éventuelles. Police Courier sur fond sombre.

8.3 Barre de progression

La barre s'anime pendant la conversion. Le bouton ▶ Lancer est désactivé pendant le traitement pour éviter les double-exécutions.

---

9. Interface en ligne de commande (CLI)

xml2xlsx <entrée> [sortie] [--dtd FICHIER] [--position] [--no-individual] [--reverse XML_ORIGINAL]

Arguments

Argument	Obligatoire	Description
<entrée>	Oui	Fichier .xml, dossier de .xml, ou fichier .xlsx en mode --reverse
[sortie]	Non	Chemin du .xlsx de sortie (défaut : même nom que l'entrée, ou master_output.xlsx pour un dossier)
--dtd FICHIER	Non	Chemin vers un fichier DTD pour la détection de schéma
--position	Non	Calcule la colonne POSITION_INTRODD (ANTE / POST / AUTRE)
--no-individual	Non	En mode dossier, ne génère pas les fichiers individuels par XML
--reverse XML	Non	Active le mode Réécriture XML : passer le chemin du XML source

Exemples complets

Fichier unique

# Conversion basique
xml2xlsx corpus.xml

# Avec DTD et nom de sortie personnalisé
xml2xlsx corpus.xml resultats.xlsx --dtd monschema.dtd

# Avec colonne de position
xml2xlsx corpus.xml --dtd monschema.dtd --position

Dossier

# Traitement complet (individuel + maître)
xml2xlsx /data/corpus/

# Maître uniquement, DTD, positions
xml2xlsx /data/corpus/ --no-individual --dtd schema.dtd --position

# Maître dans un emplacement spécifique
xml2xlsx /data/corpus/ /resultats/analyse_complete.xlsx --no-individual

Réécriture XML

# Injection simple
xml2xlsx annotations.xlsx --reverse corpus_original.xml

# Avec DTD
xml2xlsx annotations.xlsx --reverse corpus_original.xml --dtd schema.dtd

---

10. Formatage Excel et colorisation

Le fichier Excel produit est formaté automatiquement :

• En-têtes en gras sur fond gris clair
• Retour à la ligne automatique dans toutes les cellules
• Largeur des colonnes calculée automatiquement (max. 100 caractères)
• Hauteur des lignes ajustée au contenu
• Colorisation des balises dans la colonne paragraph_text

Couleurs des balises

Balise	Couleur	Code hex
INTRODD	Bleu foncé	#1F4E79
VDD	Violet	#7030A0
EXPANSION	Orange foncé	#C55A11
MOD	Marron	#833C00
PPI	Rouge foncé	#C00000
NONPPI	Vert foncé	#375623
MD	Bleu moyen	#2E75B6
APP	Gris foncé	#595959
DD	Turquoise	#1D6B5E
Balise inconnue	Noir	#000000

Colonnes préservées en casse originale

En mode Dossier (fichier maître), les valeurs texte sont normalisées en minuscules, sauf :

• paragraph_text
• INTRODD_text
• APP_text
• INTRODD_EXPANSION_text, INTRODD_EXPANSION_2_text, INTRODD_EXPANSION_3_text

---

11. Récapitulatif des modes

Mode	Entrée	Sortie	CLI	GUI
Fichier XML unique	Un fichier .xml	Un fichier .xlsx	xml2xlsx fichier.xml	Bouton radio « Fichier XML »
Dossier	Un dossier de .xml	XLSX individuels + master_output.xlsx	xml2xlsx dossier/	Bouton radio « Dossier »
Réécriture XML	Un .xlsx + un .xml source	nom_updated.xml	xml2xlsx annot.xlsx --reverse source.xml	Bouton radio « Réécrire XML »

---

12. Dépannage

Symptôme	Cause probable	Solution
❌ Tag X supprimé dans le rapport	Modification accidentelle d'une colonne structure	Ne pas modifier p_id, source_file. Relancer depuis l'Excel original.
Colonne absente dans l'Excel	Balise absente dans tous les paragraphes	Normal : les colonnes vides sont supprimées automatiquement.
Aucun fichier XML trouvé	Dossier vide ou mauvaise extension	Vérifier que les fichiers ont l'extension .xml (minuscules).
Valeur non reportée dans le XML	Cellule vide ou valeur non reconnue	Une cellule vide est ignorée. Vérifier la valeur et le nom de colonne.
Mauvaise occurrence balisée	Suffixe _N absent ou incorrect	Ajouter _2 ou _3 à la fin de la valeur dans la cellule, pas dans le nom de colonne.
Erreur de parsing XML	XML mal formé	Valider le XML source avant de le fournir à l'outil.

---

13. Licence

Ce logiciel est distribué sous licence MIT.

xml2xlsx-lidilem — Convertisseur XML annoté vers Excel pour corpus littéraires PREFAB