Aide:Transclusion

La bibliothèque libre.
Aller à la navigation Aller à la recherche
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 />.

La balise <pages />[modifier]

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

La balise <pages /> admet deux types de paramètres :

  • les paramètres permettant de définir la plage de texte à transclure ;
  • les paramètres permettant d’insérer et de modifier la boîte de titre.

Définir la plage de texte à transclure : les paramètres from, to et associés[modifier]

On utilise pour indiquer les pages à transclure les paramètres from= et to= de la balise <pages /> ; lorsqu’on veut ne transclure une page qu’en partie, il faut aussi préciser un ou plusieurs des paramètres fromsection=, tosection= ou onlysection=. Les premiers paramètres n’acceptent pour argument que des numéros de page d’index du fichier « Livre » ; les seconds acceptent tout texte, pourvu qu’il soit encadré de guillemets s’il contient une espace.

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

Les paramètres utiles pour indiquer les pages à transclure sont les suivants :

Paramètre Description Exemple
index Nom de la page d’index du livre, sans le préfixe « Livre: » au début du nom Baudelaire - Les Fleurs du mal 1857.djvu
from Début de l’intervalle des pages à transclure.
Omettre cet attribut et l’attribut « to » pour transclure le sommaire ;
5
fromsection Pour la page indiquée dans « from »,
transclure à partir de la section indiquée (section incluse)
chap2
to Fin de l’intervalle des pages à transclure 38
tosection Pour la page indiquée dans « to »,
transclure jusqu'à la section indiquée (section incluse)
chap2
onlysection Transclure uniquement la section indiquée pour toutes les pages schéma
header Voir la section Modifier la boîte de titre
header_type Voir la section Modifier la boîte de titre
step Ne transclure qu’une page sur N, en comptant à partir de la première 2
exclude À la transclusion, omettre des pages 10-16
include À la transclusion, insérer des pages 2-3


Transclure des pages entières : from, to, exclude, include[modifier]

Pour transclure un fichier depuis la page d’index numérotée x, jusqu’à la page d’index numérotée y, on précise from="x" to="y".

Si l’attribut from= est précisé et que l’attribut to= ne l’est pas, les pages sont transcluses jusqu’à la fin du livre.

Si ni from= ni to= ne sont précisés, alors on obtient une « page de garde », contenant une boîte de titre avec les informations de cette page (voir la section suivante) et le sommaire du livre tel qu’il apparaît sur la page d’index de l’espace « Livre ».

Pour ne transclure qu’une page sur deux entre les pages from= et to= (par exemple dans les éditions bilingues avec texte en regard), on précise step=2.

Entre les pages from= et to=, on peut exclure des pages grâce à exclude=. Inversement, on peut ajouter des pages à la transclusion avec include=.

Exemples de wikicode
Code wiki Description du rendu
<pages index="Baudelaire - Les Fleurs du mal 1857.djvu" from="106" to="107" /> Transclure les pages d’index 106 à 107 du livre Baudelaire - Les Fleurs du mal 1857.djvu.
<pages index="monFacsimile.djvu" from="1" to="10" step=2 /> Transclure les pages d’index 1, 3, 5, 7 et 9 du livre Livre:monFacsimile.djvu.
<pages index="monFacsimile.djvu" from="1" to="10" exclude="2-5,9" /> Transclure les pages d’index 1, 6, 7, 8 et 10 du livre Livre:monFacsimile.djvu.
<pages index="monFacsimile.djvu" include="2-5,9" /> Transclure les pages d’index 2, 3, 4, 5 et 9 du livre Livre:monFacsimile.djvu.

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.

Transclure une page en partie : fromsection, tosection, onlysection[modifier]

Imaginons que sur une même page finisse le premier chapitre d’un livre, et commence le second. Pour transclure seulement la fin du premier chapitre, il faut l’encadrer par des balises de section dans l’espace Page: (point 1), puis indiquer cette section dans la balise <pages/> de l’espace principal (point 2). Sur une page, chaque section porte un nom distinct ; les noms de sections peuvent contenir des espaces, mais à condition d’entourer le nom de guillemets lorsqu’ils seront passés en argument de fromsection=, tosection= ou onlysection=.

1. Pour insérer les balises de section dans l’espace Page:, il existe deux syntaxes possibles :

  • Si le gadget Easy LST est activé (ce qui est le cas par défaut[1]), la syntaxe simplifiée peut être utilisée. Au début de la partie de page à transclure, il faut ajouter le code ## chap1 ## sur une ligne blanche ; à la fin de cette partie, il faut ajouter, soit #### sur une ligne blanche pour indiquer la fin de la section, soit une balise d’ouverture d’une autre section, dans notre cas ## chap2 ##. Cela donne donc :
## chap1 ##
Voici la fin du chapitre I.

## chap2 ##
Voici le début du chapitre II.
Le robot rétablira à partir de cette syntaxe abrégée la syntaxe complète de la délimitation des sections. Attention ! Lorsque la coloration syntaxique est activée, le robot ne fonctionne plus : il est recommandé de désactiver cet outil en cliquant sur l’icône en forme de feutre située dans la barre au haut de la fenêtre d’édition.
  • On peut préférer utiliser directement la syntaxe complète sans passer par la syntaxe abrégée. Voici cette syntaxe : il faut pour chaque section, disons chap1, en indiquer le début avec <section begin=chap1 />, et la fin avec <section end=chap1 />. Cela donne donc :
<section begin=chap1 />
Voici la fin du chapitre I.
<section end=chap1 />

<section begin=chap2 />
Voici le début du chapitre II.
<section end=chap2 />

Il est à noter que, dans les deux cas, chaque début de section se comporte comme un début de Page: ; il faut entendre par là que les lignes blanches qui les suivent sont supprimées, etc. Pour contrer ces effets, la solution est la même qu’au début d’une page : il faut ajouter <nowiki/> après l’ouverture de section.

2. Pour transclure dans l’espace principal les pages d’index x à y du livre, mais en ne transcluant que jusqu’à la section chap1 incluse de la page y, on utilise le paramètre tosection=. Par exemple :

<pages index="monFacsimile.djvu" from="x" to="y" tosection="chap1" header=1 />

Pour transclure dans l’espace principal les pages d’index y à z du livre, mais en ne transcluant qu’à partir de la section chap2 incluse de la page x, on utilise le paramètre fromsection=. Par exemple :

<pages index="monFacsimile.djvu" from="y" fromsection="chap2" to="z" header=1 />

Pour transclure dans l’espace principal la seule section chap1 de la page d’index x, on utilise le paramètre onlysection=. Par exemple :

<pages index="monFacsimile.djvu" from="x" to="x" onlysection="chap1" header=1 />
Exemple de wikicode
Code wiki Description du rendu
<pages index="Dickens - La Petite Dorrit - Tome 2.djvu" from="16" fromsection="chap2" to="20" tosection="chap2" /> Transclure les pages d’index 16 à 20 du livre Dickens - La Petite Dorrit - Tome 2.djvu. Pour la page 16, transclure uniquement à partir de la section « chap2 » inclue ; pour la page 20 transclure uniquement jusqu’à la section « chap2 » inclue.

Modifier la boîte de titre : le paramètre header[modifier]

L’attribut header permet d’afficher une boîte de titre au-dessus des pages transcluses. Cette boîte de titre est codée dans Modèle:Proofreadpage header template. Elle reprend les informations présentes sur la page d’index du livre d’où proviennent les pages transcluses : titre, auteur, édition…


Modifier le type de la boîte de titre[modifier]

La boîte de titre est susceptible de prendre trois formes différentes, selon la valeur du champ header=. Les valeurs possibles de 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 : aucune boîte de titre. Cela 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 où 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
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.

Modifier les informations affichées par défaut dans la boîte de titre[modifier]

Les informations présentes dans la boîte de titre dépendent 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 important de bien renseigner ce type d'ouvrage à la fois pour l’affichage correct de la page de transclusion et pour l’import sur Wikidata de données provenant de Wikisource

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.

Liste des champs pour outrepasser les valeurs de l’index
Champ Description
titre Le titre du livre ou de l’article. Cas particulier pour les ouvrages de type recueil : indiquer titre=- dans la page de transclusion du sommaire du recueil pour éviter que le titre du recueil soit répété dans l’entête
sous_titre Sous-titre (ne s’affiche que pour le type header=Sommaire)
volume Le numéro 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
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.

Comment ajouter dans une transclusion des liens facilitant la navigation au sein d’une même page ?[modifier]

Habituellement, on transclut sur des pages distinctes les parties d’un livre (par exemple les chapitres d’un roman ou les poèmes d’un recueil) qui ont une certaine autonomie. Parfois cependant, on voudrait pouvoir permettre au lecteur de consulter directement une section plus courte de ces parties sans pour autant créer une nouvelle sous-page pour chacune de ces sections. Cette situation, et la solution donnée ci-dessus, est recommandée dans les cas suivants :

  • on transclut un acte d’une pièce de théâtre sur une seule page, et on veut pouvoir envoyer le lecteur vers une scène de cet acte ;
  • on transclut une nouvelle d’un recueil de nouvelles sur une seule page, et on veut pouvoir envoyer le lecteur vers un chapitre de cette nouvelle ;
  • on transclut un article d’une revue sur une seule page, et on veut pouvoir envoyer le lecteur vers une section de cet article.

Pour cela il faut insérer des ancres dans l’espace « Page » et faire des liens vers ces ancres. Voici un exemple : le sommaire des Mélanges d’histoire des religions de Hubert et Mauss contient deux types de liens :

On distingue les seconds en ce qu’ils contiennent un croisillon, qui introduit une ancre.

Pour qu’une ancre soit active, il faut l’insérer dans l’espace « Page » avec un modèle comme {{ancre}} ou {{refancre}} : ainsi, l’ancre I est insérée dans Page:Hubert, Mauss - Mélanges d’histoire des religions, 1909.djvu/59. Deux ancres d’une même page transcluse ne peuvent pas porter le même nom, et il faut absolument que le nom de l’ancre contiennent une lettre.

Pour faire un lien vers une ancre, on utilise, comme on l’a vu, le croisillon # suivi du nom de l’ancre : Mélanges d’histoire des religions/Essai sur la nature et la fonction du sacrifice#I envoie vers l’ancre I de la page Mélanges d’histoire des religions/Essai sur la nature et la fonction du sacrifice.

Pour plus d’information, consultez la documentation de {{ancre}}.

Comment transclure un tableau ou un élément à cheval sur plusieurs pages ?[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. Wsexport 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, Wsexport 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, Wsexport y recherche des liens menant à des sous-pages et étiquetés « ws-summary ». Si nécessaire, il construit une autre série de chapitres au-dessous des chapitres de premier niveau mais la cascade s’arrête là. Exemple de table des matières à deux niveaux : Charles et Éva.

Dans le cas où Wsexport 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 Wsexport 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 sont convertis en chapitres car le Module:Header template ajoute l’étiquette « ws-summary » à cause de la présence de header=Sommaire.
<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 sont 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 vers des pages ou vers des sous-pages sont 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 de noms Page lors de la création de la table des matières et n’affecter, par exemple, que les liens de premier niveau.

Voir aussi[modifier]

  1. Pour le désactiver, cocher « Utiliser l’ancienne syntaxe <section/> pour les transclusions de sections dans l’espace Page » dans Préférences -> Gadgets. Pour plus d’information, voir Help:Gadget-Easy LST (en anglais).