Aide:Transclusion

Niveau débutant
Nous vous recommandons de lire auparavant Aide:Espace « Page » et Aide:Espace « Livre »
Cette page d’aide expose le principe général de la transclusion et sa mise en œuvre pratique au moyen de la balise <pages/>.
Voir aussi : Aide:Transcription
En résumé En résumé :
La transclusion permet d’inclure une page dans une autre.
Pour transclure, il faut utiliser la balise <pages/> dans l'espace principal.
On appelle « page(s)-source(s) » la (ou les) page(s) à inclure et nomme « page-feuille » la page qui reçoit la (ou les) « page(s)-source(s) ».
Aide : Manuel de Wikisource

La transclusion est, dans le domaine informatique, l’action d’inclure une page dans une autre de façon dynamique. La transclusion est différente de la copie : en effet, toute modification de la page incluse sera automatiquement et immédiatement répercutée sur la page hôte.

Sur Wikisource, la transclusion est utilisée principalement pour inclure des pages de l’espace page dans l’espace principal. La transclusion est donc le plus souvent effectuée après relecture dans l’espace page. Il permet de présenter aux lecteurs un texte suivant sa structure logique : par parties, par chapitres, par poèmes… et non suivant le découpage physique des pages-papier.

Cette transclusion s’effectue à l’aide de la balise <pages />.

Fonctionnement de la balise <pages />Modifier

La balise <pages /> permet de transclure une ou des pages-sources à l’endroit où elle est utilisée dans la page-feuille. La page-feuille transclue entièrement ou partiellement des pages-sources, issues d’un livre (qui est dans l’espace livre — appelé espace Index en anglais).

  Le numéro de page d’index du fichier, djvu ou pdf, est souvent différent du numéro de page du livre-papier.

Les attributs que l’on peut préciser à l’intérieur de la balise sont les suivantes :

Paramètres du modèle

La mise en forme sur une seule ligne est préférée pour ce modèle.

ParamètreDescriptionTypeStatut
Nom dans l'espace « Livre: »index

Nom de la page d’index du livre, sans le préfixe « Livre: » au début du nom

Exemple
Baudelaire - Les Fleurs du mal 1857.djvu
Fichierobligatoire
Page de débutfrom

Page du début de l’intervalle de pages à transclure. Omettre cet attribut et l’attribut « to » pour transclure le sommaire ;

Par défaut
1
Exemple
5
Nombrefacultatif
Page de finto

Dernière page de fin de l’intervalle de pages à transclure

Exemple
38
Nombrefacultatif
Début section à transcrirefromsection

Pour la page indiqué dans « from » commence la transclusion à partir de la section indiquée (section incluse)

Exemple
chap2
Contenufacultatif
Fin section à transcriretosection

Pour la page indiqué dans « to » transclure jusqu'à la section indiquée (section incluse)

Exemple
chap2
Contenufacultatif
Seulement la sectiononlysection

Transclure uniquement la section indiquée pour toutes les pages

Exemple
schéma
Contenufacultatif
Headerheader

voir la section [[#Header]]

Inconnufacultatif
Header typeheader_type

voir la section [[#Header]]

Inconnufacultatif
Passtep

Permet de ne transclure qu’une page sur ''x'', en comptant à partir de la première

Exemple
2
Nombrefacultatif
Exclureexclude

Permet d’indiquer « d’oublier » de transclure une série de pages comprises entre « from » et « to »

Exemple
10-15
Contenufacultatif
Inclureinclude

Permet de transclure une série de pages en utilisant la même syntaxe que « exclude ».

Exemple
10-15
Contenufacultatif

Exemples de wikicodeModifier

Code wiki Description du rendu
<pages index="Baudelaire - Les Fleurs du mal 1857.djvu" from="106" to="107" /> Transclure les pages 106 à 107 du livre Baudelaire - Les Fleurs du mal 1857.djvu.
<pages index="Dickens - La Petite Dorrit - Tome 2.djvu" from="16" fromsection="chap2" to="20" tosection="chap2" /> Transclure les pages 16 à 20 du livre Dickens - La Petite Dorrit - Tome 2.djvu. Pour la page 16, transclure uniquement la section « chap2 », pour la page 20 transclure uniquement la section « chap2 ».
<pages index="" from="1" to="10" step=2 /> Affiche les pages 1, 3, 5, 7 et 9.
<pages index="" from="1" to="10" exclude="2-5,9" /> Affiche les pages 1, 6, 7, 8 et 10.
<pages index="" include="2-5,9" /> Affiche les pages 2, 3, 4, 5 et 9.

Les numéros de page affichés sur le côté des pages transcluses sont les numéros attribués à ces pages sur la page d’index du livre. Voir l’aide de l’espace « Livre » pour corriger éventuellement des décalages dans la numérotation.

Si l’attribut « from » est présent sans l’attribut « to », alors ce dernier est fixé par défaut à la dernière page du livre : les pages sont transcluses jusqu’à la fin du livre.

Si ni « from » ni « to » ne sont présents, alors on obtient une transclusion du sommaire du livre tel qu’il apparaît sur la page d’index de l’espace Livre, précédé d’une boîte de titre reprenant les informations de cette page (voir Header).

HeaderModifier

L’attribut header permet d’afficher une boîte de titre au-dessus des pages transcluses. Cette boîte de titre reprend les informations présentes sur la page d’index du livre d’où proviennent les pages transcluses : titre, auteur, édition… Les valeurs possibles pour l’attribut header sont :

  • header=1 : boîte de titre avec navigateur. On obtient en dessous de la boîte de titre un navigateur comportant un lien vers le texte précédent et un lien vers le texte qui suit le texte courant. Ces liens sont obtenus automatiquement depuis les liens figurant dans le sommaire présent sur la page d’index de l’espace Livre.
  • header=Sommaire : boîte de titre sans navigateur, seules les informations présentes sur la page d’index sont reprises. Il n’y a pas de liens vers les textes précédant et suivant le texte courant. Les numéros des pages transcluses ne sont pas non plus indiqués.
  • header_type=empty : permet d'éviter la génération de la boîte de titre, utile pour les sommaires sur plusieurs volumes, où à partir du second volume on veut le sommaire sans la boîte de titre. Voir par exemple sur la page Barnabé Rudge la transclusion du sommaire du tome II.

Comme mentionné plus haut, lorsque ni from ni to ne sont spécifiés dans la balise <pages />, on obtient une transclusion du sommaire du livre. La boîte de titre a alors la même apparence qu’avec header=Sommaire.

Exemples de headerModifier

Code wiki Description du rendu
<pages index="Dickens - La Petite Dorrit - Tome 2.djvu" from="16" to="20" header=1/> Transclure les pages 16 à 20 du livre Dickens - La Petite Dorrit - Tome 2.djvu, boîte de titre avec navigateur. Résultat. Noter que les liens vers le texte suivant et le texte précédent sont ceux qui apparaissent autour du texte dans le sommaire sur la page d’index du Livre.
<pages index="Verlaine - Œuvres complètes, Vanier, I.djvu" from="440" fromsection="s2" to="442" header=Sommaire /> Transclure les pages 440 à 442 du livre Verlaine - Œuvres complètes, Vanier, I.djvu. Boîte de titre sans navigateur. Résultat.
<pages index="Bloy - Les Dernières Colonnes de l’Église, Mercure de France, 1903.djvu"/> Transclure le sommaire du livre Bloy - Les Dernières Colonnes de l’Église, Mercure de France, 1903.djvu. Résultat.

L’apparence de la boîte de titre dépend du type de l’ouvrage indiqué dans le champ Type (menu déroulant) du formulaire de modification de la page d’index de l’ouvrage :

  • Journal ou revue (nom technique : journal) : auteur, nom de la page, titre, volume, année, intervalle de pages.
  • Recueil (nom technique : collection) : auteur, nom de la page, recueil, titre, éditeur scientifique, éditeur, année, intervalle de pages.
  • Autre : auteur, titre, traducteur, éditeur, année, volume, intervalle de pages.

Il est possible de définir les informations utilisées ci-dessus à l’intérieur de la balise <pages /> pour outrepasser la valeur définie dans la page d’index du livre. Cela peut être utile dans le cas d’un recueil d’ouvrages de différents auteurs : chaque texte du recueil doit redéfinir son propre auteur.

Exemple :

Code wiki Description du rendu
<pages header=1 auteur="[[Auteur:Victor Cousin|Victor Cousin]]" index="Journal des économistes, 1846, T16.djvu" from="147" to="152" /> Transclure les pages 147 à 152, l’auteur affiché sera Victor Cousin qui est différent de l’auteur indiqué dans la page d’index (non renseigné). Résultat.

Liste des champs pour outrepasser les valeurs de l’indexModifier

Exemple : Études sur l’Inde ancienne et moderne/04

titre
Le titre du livre ou de l’article
sous_titre
Sous-titre (ne s’affiche que pour le type header=Sommaire)
volume
Le n° du volume reproduit
auteur
Nom de l’auteur
traducteur
Nom du traducteur
illustrateur
Nom de l’illustrateur
editeur_scientifique
Nom de l'éditeur du texte
school
École ou université de publication (thèse…)
lieu
Lieu de publication
annee
Année de publication
publication
année de première publication
displayed_from
Numéro de page de début
displayed_to
Numéro de page de fin
prev
Lien vers le chapitre précédent
current
Lien vers le chapitre en cours
next
Lien vers le chapitre suivant
recueil
Titre du recueil

FAQModifier

Comment transclure une seule partie de la page ?Modifier

Deux syntaxes possibles  :

## chap2 ##

Le robot saura reconnaître ce qu’il faut délimiter, car la fin de la section sera signalée soit par le début d’une nouvelle section indiquée de la même manière (dans ce cas le robot ajoutera une fin de section avant de commencer la deuxième), soit par la syntaxe ci-dessous :

####

qui lui indiquera que c’est la fin de la section.

Il rétablira à partir de cette syntaxe abrégée la syntaxe complète de la délimitation des sections (mais vous pouvez si vous le préférez utiliser directement celle-ci sans passer par la syntaxe abrégée). Voici cette syntaxe :

<section begin=chap2 />Voici en exemple un chapitre <section end=chap2 />

À la place de « Voici en exemple un chapitre », vous pouvez mettre bien sûr toute la section de texte à marquer.

Comment inclure plusieurs pages dans un même tableau lors de la transclusion ?Modifier

Si un élément logique (par exemple un tableau) occupe plusieurs pages, il est possible d’utiliser des commandes noinclude et includeonly. Exemple : Œuvres de Fermat - I - Partie 2, voir question XXVIII.

Comment harmoniser Ebook et transclusion ?Modifier

L’outil utilisé par Wikisource pour produire un Ebook est Wikisource:Wsexport. Cet outil fonctionne à partir d’une page de l’espace principal considérée comme étant la source du Ebook. Ws-export parcourt cette page source à la recherche de liens.

Ce sont ces liens qui produiront les chapitres de premier niveau. Pour déterminer quels liens serviront à la création d’un chapitre, Ws-export ne considère que ceux qui sont encadrés d’une balise portant la mention class="ws-summary" apposée manuellement ou systématiquement lorsque header=1 ou encore id="ws-summary" apposée manuellement ou systématiquement lorsque header=Sommaire. Les autres liens ne seront pas convertis et dirigeront le lecteur non pas vers un chapitre du Ebook, mais vers une page de Wikisource.

En construisant les chapitres de première génération, Ws-export y recherche encore des liens à des sous-pages étiquetés ws-summary. Si nécessaire il construira une autre série de chapitres au-dessous des chapitres de premier niveau mais la cascade s’arrêtera là. Exemple de TDM à 2 niveaux : Charles et Éva.

Dans le cas où WS Export ne trouve aucun lien qui réponde aux critères ci-dessus, les chapitres de premiers niveaux seront les liens dont la racine est la même que la page principale. Par exemple, Vies et doctrines des philosophes de l’Antiquité/Livre II possède la même racine que Vies et doctrines des philosophes de l’Antiquité, cette sous-page sera donc un chapitre de premier niveau. Ce cas d’exception ne s’applique qu’aux chapitres de premier niveau.

Comportement de Ws-export selon le mode de transclusion
Contenu de la page de premier niveau Résultat obtenu à l’intérieur du Ebook
<pages index="Verne - Kéraban-le-Têtu, Hetzel, 1883, tome 1.djvu" volume="Tomes 1 & 2" header=sommaire /> Tous les liens du sommaire seront convertis en chapitres car le Module:Header template ajoutera de lui-même l’étiquette ws-summary lorsque header=Sommaire ou header=1.
<pages index="Verne - Kéraban-le-Têtu, Hetzel, 1883, tome 1.djvu" volume="Tomes 1 & 2" header=sommaire />
<pages index="Verne - Kéraban-le-Têtu, Hetzel, 1883, tome 2.djvu" include="321" onlysection="s1" />
<pages index="Verne - Kéraban-le-Têtu, Hetzel, 1883, tome 2.djvu" include="322" />
Seuls les liens contenus dans le premier tome seront considérés et convertis en chapitres.
<div class="ws-summary">
<pages index="Verne - Kéraban-le-Têtu, Hetzel, 1883, tome 1.djvu" volume="Tomes 1 & 2" header=sommaire />
<pages index="Verne - Kéraban-le-Têtu, Hetzel, 1883, tome 2.djvu" include="321" onlysection="s1" />
<pages index="Verne - Kéraban-le-Têtu, Hetzel, 1883, tome 2.djvu" include="322" /></div>
Tous les liens à des sous-pages seront convertis en chapitres dans le Ebook car ils portent tous l’étiquette ws-summary. N-B : Cette étiquette peut aussi être apposée dans l’espace page lors de la création de la TDM et n’affecter, par exemple, que les liens de premier niveau.

Voir aussiModifier