Ingestion DITA XML native dans Astro

Cette sous-section expérimentale démontre comment Astro peut ingérer directement des fichiers topics DITA XML authentiques couvrant les trois grands archétypes de la rédaction structurée (Concept, Tâche, Référence), valider leur structure sémantique et générer un rendu HTML accessible, tout en exposant les fichiers sources originaux à l’identique.

Les trois archétypes DITA

Au cœur de la méthode DITA (Darwin Information Typing Architecture) se trouve la séparation stricte du contenu selon l’intention de l’utilisateur. Chaque archétype répond à un besoin d’information distinct :

• Concept (<concept>) : Explique ce qu’est une notion, ses caractéristiques fondamentales et pourquoi elle importe, sans prescrire de procédure pas-à-pas.
• Tâche (<task>) : Décrit comment accomplir une activité précise grâce à une série ordonnée d’étapes (`<step>`), d’actions (`<cmd>`) et d’informations contextuelles (`<context>`).
• Référence (<reference>) : Fournit des données factuelles structurées destinées à la consultation rapide (propriétés, tableaux de configuration, paramètres, syntaxe), sans narration superflue.

Topics de démonstration

Chaque topic ci-dessous est généré directement depuis son fichier XML source authentique :

Concept

Tondeuse à gazon

La tondeuse à gazon est une machine utilisée pour couper l’herbe dans le jardin.

lawnmower.dita →

Tâche

Vidange d’huile moteur

Effectuez la vidange d’huile de votre véhicule tous les 6 000 kilomètres ou tous les trois mois.

changingtheoil.dita →

Référence

Fichier de configuration de plug-in

Le fichier plugin.xml contrôle tous les aspects d’un plug-in, rendant chaque extension visible au reste du toolkit. Le fichier s’appuie sur des points d’extension prédéfinis pour localiser les changements et les intégrer dans le code central.

plugin-configfile.dita →

Carte DITA et architecture de navigation

Dans la philosophie DITA, un topic ne contient jamais de lien rigide « page suivante » ou « page précédente ». Les topics sont des unités modulaires indépendantes et réutilisables dans de multiples contextes. C’est la carte DITA (<map>) qui définit la taxonomie, la hiérarchie et la séquence de lecture du lecteur.

Cette sous-section utilise la carte de démonstration « Carte de démonstration de rédaction structurée DITA » (collection-type="sequence") pour orchestrer dynamiquement la progression du lecteur à travers les trois archétypes :

dita-astro.ditamapVoir la carte .ditamap

1. 1
   Concept : Tondeuse à gazonconcept

   Principes fondamentaux et variétés de tondeuses.

   lawnmower.dita
2. 2
   Tâche : Vidange d’huile moteurtask

   Procédure pas-à-pas pour changer l’huile moteur.

   changingtheoil.dita
3. 3
   Référence : Configuration de plug-inreference

   Spécifications de référence pour les fichiers plugin.xml.

   plugin-configfile.dita

Précision sur la provenance de la carte : Alors que les trois fichiers topics XML (lawnmower.dita, changingtheoil.dita, plugin-configfile.dita) sont issus directement du corpus officiel de DITA-OT et vérifiés à l’octet près, dita-astro.ditamap est un fixture d’intégration local rédigé pour les besoins de cette démonstration. En effet, dans le dépôt upstream dita-ot/dita-ot, les exemples de garage (hierarchy.ditamap) et le guide d’extension (dev_ref.ditamap) sont situés dans deux répertoires disjoints sans carte racine commune reliant les trois archétypes.

Sources canoniques et provenance

Les trois fichiers sources sont issus du dépôt officiel DITA-OT, préservés à l’octet près, et vérifiables par leur empreinte cryptographique SHA-256 :

Archétype / Ressource	Fichier source local	Origine amont (dita-ot/dita-ot)	Auteur / Licence	Endpoints sources
Concept	lawnmower.dita	src/main/samples/concepts/lawnmower.xml	IBM Corp. (2001, 2005) / CPL 1.0 & Apache 2.0	.dita ·.xml
Tâche	changingtheoil.dita	src/main/samples/tasks/changingtheoil.xml	IBM Corp. (2001, 2005) / CPL 1.0 & Apache 2.0	.dita ·.xml
Référence	plugin-configfile.dita	src/main/doc/dev_ref/plugin-configfile.dita	DITA-OT / Arbortext / Apache 2.0 & CPL 1.0	.dita ·.xml
DITA Map	dita-astro.ditamap	Fixture d’intégration local (voir note ci-dessus)	redaction-technique.org (Fixture de démonstration)	.ditamap ·.xml

Pipeline d’ingestion XML et niveaux de validation

Le parseur XML applique une politique de sécurité stricte et une validation à trois niveaux clairement séparés :

1. Niveau A — Conformité syntaxique XML (Well-Formedness) : Le document XML doit respecter la syntaxe XML 1.0. Avant l’analyse, toute déclaration d’entité (<!ENTITY) et toute directive SYSTEM vers des protocoles distants ou locaux sont bloquées pour neutraliser les attaques XXE et l’expansion Billion Laughs.
2. Niveau B — Sous-ensemble applicatif supporté : La racine doit être un élément <concept>, <task> ou <reference> avec un attribut id valide. Le titre et le corps spécifique à l’archétype (<conbody>, <taskbody> avec étapes ordonnées et commandes obligatoires, ou <refbody> avec sections et tableaux) sont requis et validés.
3. Niveau C — Conformité formelle DITA (Hors périmètre) : La validation formelle de grammaire DITA complète (résolution de DTD/XSD, validation de catalogues OASIS, règles de spécialisation) n’est volontairement pas effectuée dans cette démonstration afin de préserver une empreinte d’exécution légère et autonome dans Astro.

Correspondance DITA XML vers HTML sémantique

Archétype	Balise DITA XML	Rendu HTML sémantique
Tous	<title> / <shortdesc>	<h1> (titre unique) / <p class="lead"> (description courte unique)
Concept	<conbody> / <p>	<div class="dita-conbody"> / <p>
Tâche	<taskbody> / <steps> / <cmd>	<div class="dita-taskbody"> / <ol class="dita-steps"> / <li><div class="dita-cmd">
Référence	<refbody> / <section> / <simpletable>	<div class="dita-refbody"> / <section> / <table class="dita-simpletable">

Éléments supportés et limites

• Éléments pris en charge :<map> (avec collection-type="sequence"), <topicref>, <topicmeta>, <concept>, <task>, <reference>, <title>, <shortdesc>, <conbody>, <taskbody>, <context>, <prereq>, <stepsection>, <steps>, <step>, <cmd>, <info>, <substeps>, <stepxmp>, <choices>, <stepresult>, <result>, <example>, <postreq>, <note>, <ul>, <ol>, <dl>, <refbody>, <section>, <simpletable>, <sthead>, <strow>, <stentry>, <codeblock>, <codeph>, <filepath>, <related-links>.
• Fonctionnalités DITA non implémentées : Transclusion conref/conkeyref, cartes imbriquées complexes et récursion d’arbre profonde, filtrage conditionnel ditaval (profiling), spécialisation de domaines, et génération PDF/XSL-FO.

Différences avec DITA-OT

Ce module ne remplace pas DITA-OT pour de grands corpus industriels nécessitant publication multicanale (PDF, Eclipse Help, RTF) et transclusions complexes. Son objectif est de prouver qu’un site moderne en JAMstack (Astro) peut ingérer des topics DITA XML natifs et les intégrer harmonieusement dans une expérience web ultra-rapide sans dépendre de la machine virtuelle Java.