xml2xlsx-lidilem 0.2.5

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

Documentation — xml2xlsx

Convertisseur de corpus XML annoté vers Excel

Version documentée : package xml2xlsx Public cible : linguistes et annotateurs maîtrisant XML et les corpus écrits, sans formation Python particulière

---

Vue d'ensemble

xml2xlsx est un outil qui transforme des fichiers XML annotés en tableaux Excel lisibles, avec mise en couleur automatique des balises. Chaque paragraphe <p> du corpus devient une ligne du tableau ; chaque balise imbriquée devient une colonne.

La détection et l'extraction des balises est entièrement générique : l'outil ne présuppose aucun schéma d'annotation particulier. Il suffit de lui fournir une DTD pour qu'il s'adapte automatiquement à n'importe quelle hiérarchie de balises et d'attributs, quel que soit le projet ou la convention d'annotation utilisée.

L'outil peut être utilisé de deux façons :

• via une interface graphique (fenêtre avec boutons) — recommandé pour les non-développeurs
• via la ligne de commande — pour les usages avancés ou automatisés

---

1. Lancement de l'interface graphique

Depuis un terminal, dans le dossier du projet :

python -m xml2xlsx.gui

Une fenêtre s'ouvre avec les sections suivantes.

---

2. L'interface graphique pas à pas

2.1 Source d'entrée

Choisissez entre :

Option	Usage
Dossier	Traite tous les .xml d'un répertoire en une seule passe ; génère un fichier Excel par corpus + un fichier maître fusionné
Fichier XML	Traite un seul fichier .xml

2.2 Chemin

Cliquez sur Parcourir… pour sélectionner votre dossier ou fichier. Le chemin s'affiche dans le champ texte (vous pouvez aussi le saisir directement).

2.3 Schéma DTD (optionnel)

C'est ici que vous indiquez la DTD de votre corpus.

La DTD (Document Type Definition) décrit la structure XML : quelles balises existent, dans quel ordre, avec quels attributs. xml2xlsx s'en sert pour savoir quelles colonnes créer dans Excel.

• Avec DTD : l'outil lit votre DTD et génère les colonnes correspondant exactement à votre schéma d'annotation.
• Sans DTD : l'outil utilise un schéma PREFAB intégré par défaut (balises PPI, NONPPI, INTRODD, VDD, EXPANSION, MOD, MD, APP).

Si votre corpus utilise le schéma PREFAB standard, vous pouvez laisser ce champ vide.

2.4 Options

Option	Effet
Générer un fichier XLSX individuel par fichier XML	Crée un .xlsx à côté de chaque .xml traité (mode dossier uniquement)
Générer un fichier XLSX maître	Crée un fichier master_output.xlsx qui fusionne tous les fichiers du dossier
Calculer la colonne POSITION_INTRODD	Ajoute une colonne indiquant si <INTRODD> est en position ANTE, POST ou AUTRE par rapport à <PPI> dans chaque paragraphe

2.5 Lancer la conversion

Cliquez sur ▶ Lancer la conversion. Une barre de progression animée indique que le traitement est en cours.

Le Journal (panneau noir en bas) affiche en temps réel :

• les fichiers traités
• les fichiers Excel créés
• les éventuelles erreurs

---

3. Structure du fichier Excel produit

3.1 Colonnes générées

Le tableau suit la hiérarchie de votre XML. Pour chaque <p>, les colonnes sont :

Colonne	Contenu
source_file	Nom du fichier XML d'origine
p_id	Identifiant extrait du paragraphe (entre guillemets dans le texte, si présent)
paragraph_text	Texte complet du paragraphe avec les balises XML en couleur
POSITION_INTRODD	Position d'INTRODD (si l'option est activée)
NOM_BALISE_text	Texte contenu dans <NOM_BALISE>
NOM_BALISE_attribut	Valeur de l'attribut attribut sur <NOM_BALISE>

Pour les balises imbriquées, les noms de colonnes reflètent la hiérarchie par chaînage : INTRODD_VDD_text, INTRODD_VDD_lemme, etc.

Quand une balise apparaît plusieurs fois dans un même paragraphe, les occurrences supplémentaires reçoivent un suffixe numérique : EXPANSION_text, EXPANSION_2_text, EXPANSION_3_text.

3.2 Mise en couleur dans la colonne paragraph_text

Le texte du paragraphe est restitué avec les balises XML visibles et colorées selon leur type :

Balise	Signification	Couleur
PPI	Phrase préfabriquée des interactions	Rouge foncé
NONPPI	Segment non PPI	Vert foncé
DD	Discours direct	Turquoise
INTRODD	Introducteur du discours direct	Bleu foncé
VDD	Verbe introducteur du discours direct	Violet
EXPANSION	Expansion de l'introducteur du discours direct	Orange
MD	Marqueur du discours	Bleu moyen
MOD	Modifieur	Marron
APP	Appellatif	Gris foncé

Le texte entre les balises est affiché dans la couleur de sa balise parente. Les balises elles-mêmes (<PPI>, </PPI>) sont grises et en italique pour rester lisibles sans dominer le contenu.

3.3 Casse du texte

• En mode fichier unique : la casse originale est conservée.
• En mode dossier (fichiers individuels et maître) : les colonnes de texte sont mises en minuscules pour faciliter la comparaison et le tri, sauf paragraph_text et quelques colonnes contextuelles.

---

4. Vérification d'intégrité automatique

Après chaque conversion, l'outil compare automatiquement le contenu du fichier XML source avec le tableau Excel produit :

• Il compte le nombre d'occurrences de chaque balise et attribut dans le XML.
• Il compte les cellules non vides correspondantes dans Excel.
• Il affiche un rapport dans le Journal :
  • OK: PPI: Excel=12, xml=12 → tout correspond
  • Erreur: VDD: Excel=10, xml=11 → décalage détecté, avec détail de la position divergente

Note importante : contrairement au moteur d'extraction des balises — qui est entièrement générique et s'adapte à n'importe quel schéma via la DTD — la vérification d'intégrité a été développée spécifiquement pour les fichiers traités dans le cadre du projet en cours. Elle peut produire des résultats incorrects ou incomplets sur des corpus dont la structure s'écarte de celle prévue. Elle n'est par ailleurs active que si un fichier DTD est fourni.

---

5. Utilisation en ligne de commande

Pour les utilisateurs à l'aise avec le terminal.

Syntaxe générale

python -m xml2xlsx.xml2xlsx <entrée> [sortie] [options]

Exemples

Convertir un fichier XML unique :

python -m xml2xlsx.xml2xlsx mon_corpus.xml

Produit mon_corpus.xlsx dans le même dossier.

Convertir tous les XML d'un dossier :

python -m xml2xlsx.xml2xlsx /chemin/vers/dossier/

Produit un .xlsx par fichier + master_output.xlsx.

Avec DTD explicite :

python -m xml2xlsx.xml2xlsx mon_corpus.xml --dtd schema.dtd

Avec calcul de POSITION_INTRODD :

python -m xml2xlsx.xml2xlsx mon_corpus.xml --position

Sans fichiers individuels (maître seulement) :

python -m xml2xlsx.xml2xlsx /chemin/dossier/ --no-individual

Spécifier le fichier de sortie :

python -m xml2xlsx.xml2xlsx mon_corpus.xml resultats/export.xlsx

Tableau des options

Option	Description
--dtd chemin/schema.dtd	Chemin vers la DTD (sinon schéma PREFAB par défaut)
--position	Calcule la colonne POSITION_INTRODD
--no-individual	Ne génère pas de fichier individuel par XML (mode dossier)

---

6. Structure XML attendue

L'outil attend un XML structuré avec des paragraphes <p> contenant des balises d'annotation imbriquées. Exemple minimal compatible avec le schéma PREFAB :

<text>
  <p>"tu parles"; 3.2; "il faut voir"
    <PPI decl="idiom" type="ppi" position="1">
      tu parles
      <MD>vraiment</MD>
    </PPI>
  </p>
  <p>"ça marche"; 1.0; "d'accord"
    <NONPPI>ça marche</NONPPI>
  </p>
</text>

L'identifiant de paragraphe (p_id) est extrait automatiquement depuis la première expression entre guillemets ("…") dans le texte brut du <p>.

---

7. Fichiers produits et où les trouver

Fichier	Emplacement
Fichier Excel individuel	Même dossier que le .xml source, même nom, extension .xlsx
Fichier Excel maître	Dans le dossier traité, nommé master_output.xlsx

---

8. Problèmes courants

Le journal affiche « Aucun fichier XML trouvé » → Vérifiez que le dossier sélectionné contient bien des fichiers .xml (et non des .XML en majuscules sur certains systèmes).

Des colonnes sont absentes du tableau → Si vous avez fourni une DTD, vérifiez qu'elle déclare bien toutes les balises utilisées dans vos fichiers. Sans DTD, seules les balises du schéma PREFAB intégré sont extraites.

La vérification d'intégrité signale des erreurs → Lisez le détail dans le Journal. L'outil indique précisément la position (numéro de ligne dans le XML) et la valeur divergente, ce qui permet de retrouver l'élément problématique.

L'interface graphique ne se lance pas → Vérifiez que le package est bien installé (pip install xml2xlsx ou installation depuis les sources) et que tkinter est disponible dans votre environnement Python.

---

9. Glossaire rapide

Terme	Signification dans ce contexte
DTD	Document Type Definition — fichier décrivant les balises autorisées et leur hiérarchie
Schéma PREFAB	Ensemble de balises prédéfinies propres au projet ANR PREFAB (voir table des couleurs section 3.2)
Fichier maître	Fichier Excel regroupant les données de tous les XML d'un dossier dans un seul tableau
POSITION_INTRODD	Colonne calculée indiquant si l'introducteur du DD précède (ANTE) ou suit (POST) la PPI dans le même paragraphe
Rich text	Texte formaté dans une cellule Excel avec plusieurs couleurs, utilisé ici pour visualiser les balises en place
PPI	Phrase préfabriquée des interactions
NONPPI	Segment non PPI
DD	Discours direct
INTRODD	Introducteur du discours direct
VDD	Verbe introducteur du discours direct
EXPANSION	Expansion de l'introducteur du discours direct
MD	Marqueur du discours
MOD	Modifieur
APP	Appellatif