Format du document

Postext lit un dialecte Markdown volontairement restreint.

L’analyseur est un tokeniseur écrit à la main, et non une implémentation complète de CommonMark : le format source est donc étroit et prévisible. Le but est double : garder le moteur petit et rapide, et rendre les documents faciles à échanger entre Postext et n’importe quel autre lecteur CommonMark (Obsidian, Pandoc, VS Code…). Tout ce qui ne figure pas sur cette page est traité comme du texte brut ou retiré du flux en ligne.

Si vous construisez un document par programme, la fonction parseMarkdown (voir Configuration › Analyse) vous donne exactement la structure de blocs que consomme le moteur de mise en page.

#Frontmatter

Un document peut commencer par un bloc de frontmatter YAML facultatif, délimité par des marqueurs --- :

---
title: Chapter One
author: Jane Doe
publishDate: 2026-04-15
---
 
# Chapter One
 
The story begins here…

Appelez extractFrontmatter(source) pour séparer le frontmatter du corps. L’objet de métadonnées analysé est renvoyé avec le Markdown restant et la position (en caractères) où commence le corps : utile si vous devez rapporter des erreurs ou des positions du curseur à la source d’origine.

Le frontmatter est analysé avec gray-matter, donc tout YAML est accepté, quelle que soit sa forme. Postext lui-même ne regarde que title, subtitle, author et publishDate ; les autres clés sont conservées dans PostextContent.metadata et vous pouvez en faire ce que vous voulez.

Un bloc qui n’est pas du YAML valide (un guillemet non fermé, du texte après une valeur entre guillemets) n’arrête pas la mise en page : extractFrontmatter ne renvoie aucune métadonnée, le texte situé après le --- de fermeture comme corps, et la raison donnée par l’analyseur dans error. Le document est composé sans ses métadonnées, et la construction ajoute une entrée invalidFrontmatter à contentWarnings (le Sandbox l’affiche sous le nom Frontmatter non valide).

YAML donne un type à ses valeurs : 1984 est un nombre, 2026-04-15 une date, [Ana Gil, Luis Paz] une liste. Postext imprime chacun de ces quatre champs comme du texte, quel que soit son type :

• un nombre sous sa forme décimale simple, et un booléen sous la forme true ou false (title: 1984 imprime 1984). YAML lit un nombre comme une valeur, pas chiffre par chiffre : 1.50 imprime 1.5, 017 (octal) 15, 1:30 (base 60) 90 ;
• une date sous la forme de son jour du calendrier, écrit dans la langue du document (le réglage locale, à défaut la langue de césure) : publishDate: 2026-04-15 imprime April 15, 2026 en anglais, 15 de abril de 2026 en espagnol, 15. April 2026 en allemand. Les dates arabes suivent le calendrier grégorien, sauf si l’étiquette en nomme un autre (ar-u-ca-islamic imprime la date de l’hégire), avec les chiffres qu’implique l’étiquette (ar-EG : ١٥ أبريل ٢٠٢٦ ; ar-u-nu-latn : 15 أبريل 2026). Une date accompagnée d’une heure imprime le jour de son heure UTC et omet l’heure : 2026-09-24T23:30:00-05:00 correspond à 04:30 UTC le 25 et imprime September 25, 2026 ;
• une liste sous la forme de ses éléments séparés par des virgules (author: [Ana Gil, Luis Paz] imprime Ana Gil, Luis Paz).

Mettez une valeur entre guillemets pour l’imprimer exactement telle qu’elle est écrite : un nombre qui doit garder ses chiffres, une date qui doit garder son jour, publishDate: "15/04/2026", title: "1984". Le texte arrive dans doc.metadata, dans les variables ({title}, {publishDate}…) et dans le titre et l’auteur du PDF. Celui des quatre champs qui n’a pas de forme texte (une table imbriquée, un title: vide) est omis de doc.metadata. extractFrontmatter renvoie toujours les valeurs avec le type que YAML leur a donné ; metadataText(value, locale) donne le texte que Postext imprime pour l’une d’elles.

#Constructions de bloc

Postext reconnaît sept types de blocs de texte et les listings de code, en plus des directives et des ressources intégrées décrites plus loin sur cette page. Un bloc se termine toujours par une ligne vide ou par le début d’un autre bloc.

Une seule ligne vide entre deux éléments de liste est tolérée : la liste reste d’un seul tenant. Deux lignes vides ou plus terminent la liste.

Les listes de types différents à la même profondeur sont acceptées (vous pouvez passer d’une liste à puces à une liste numérotée en cours de route), mais le moteur traite ces suites comme distinctes pour la numérotation. En pratique, gardez un seul type par profondeur, sauf si vous avez une raison de les mélanger.

#Attributs de titre

Une ligne de titre peut se terminer par un bloc d’attributs entre accolades, avec la même syntaxe key="value" que celle des directives :

# The Long Road {author="I. Zango Martín" year=1998}

Les accolades et leur contenu sont retirés du texte du titre (le titre ci-dessus s’affiche The Long Road) et stockés sur le titre sous attrs. Ils sont exposés aux emplacements de design sous forme de variables {attr.<key>} : dans l’emplacement de design avancé du titre lui-même, et dans les en-têtes et pieds de page, où ils sont résolus à partir du H1 du chapitre en cours. Seul un bloc équilibré, sans accolade interne, placé tout à la fin de la ligne est reconnu, après une espace ou, puisque les titres chinois s’écrivent sans espace, juste après un caractère chinois ou japonais (# 回目{style="x"}). Le bloc n’est pris que si la syntaxe d’attributs décrite ci-dessous le lit en entier : {x, y}, {紅樓|hóng lóu} et un {} isolé restent dans le titre, de même que des drapeaux seuls collés au titre (# 第一回{draft}). Les attributs sont séparés par des espaces : un bloc avec des virgules ({a="1", b="2"}) et le {.class} de Pandoc restent donc eux aussi dans le titre. L’identifiant {#id} de Pandoc est lu : il équivaut à id="…" et nomme le titre pour les renvois. Une clé écrite dans une autre écriture est lue puis écartée avec un avertissement (voir plus bas), si bien que # 回目{style="x" 作者=曹雪芹} prend quand même style. Voir Configuration → En-têtes et pieds de page.

Une valeur imprimée par un texte de design peut s’étendre sur plusieurs lignes : les deux caractères \n y commencent une nouvelle ligne, quel que soit le overflow de l’élément (to="Firma X\nStrasse 1\n10115 Berlin" imprime une adresse sur trois lignes). Avec inlineMarks sur l’élément, les marques en ligne de la valeur s’appliquent aussi : authors="Ana Ruiz^1^, Luis Gil^2^" compose les numéros d’affiliation en exposant. Cet échappement est propre aux valeurs d’attribut (et aux modèles du design lui-même) : les caractères \n dans le texte d’un titre, par exemple dans un fragment de code, s’impriment tels quels.

Deux attributs ont un sens particulier. style="<id>" applique au titre un style de titre nommé : une préface ou une liste d’auteurs avec son propre design d’ouverture, ses titres courants, sa géométrie de page et sa typographie de corps, et sans numéro de chapitre quand le style indique numbered: false. toc="false" (ou "true") décide si le titre est listé par :::toc :

# Preface {style="front-matter"}
 
# Contents {style="front-matter" toc="false"}

Deux autres changent ce qu’imprime un titre et la façon dont il compte. hidden="true" (ou "false") remplace le hidden du niveau ou du style du titre : un titre masqué n’imprime rien et ne prend aucune place (dans le flux comme dans un encadré :::callout), mais il ouvre quand même sa page, compte dans la numérotation et figure dans la table des matières, dans les titres courants {chapterTitle} et dans les signets du PDF. jidori=N espace régulièrement un titre d’une ligne sur la largeur de N de ses propres caractères (字取り : # 序章 {jidori=3} imprime 序　章), et jidori=0 désactive l’espacement régulier que définit son niveau ou son style (voir Configuration › Réglages par niveau). indent=N décale un seul titre de N caractères du texte courant depuis le début de la ligne (字下げ : ## 一 {indent=5}), en remplaçant l’indent de son niveau ou de son style ; un nombre seul compte en cadratins du corps, 0 place le titre en début de ligne, et cela fonctionne de la même façon en texte vertical et horizontal. firstLineIndent=N met en retrait la première ligne d’un seul titre, en remplaçant le firstLineIndent de son niveau ou de son style, ses autres lignes commençant là où les place indent (les intitulés de la norme GB/T 9704 : ## 关于加强管理的通知 {firstLineIndent=2}) ; il lit les longueurs comme indent, et 0 désactive celui du niveau. startAt=N, un entier positif, fixe le compteur du niveau du titre à N au lieu de l’incrémenter ; les titres suivants comptent à partir de là, y compris dans les chapitres suivants, et les niveaux inférieurs repartent de zéro sous lui comme d’habitude. Avec un style de titre qui numérote les annexes par des lettres (numberingTemplate: 'Appendix {1:A}'), la première annexe relance le compte pour se lire Appendix A au lieu de prolonger la numérotation des chapitres :

# To my mother {hidden="true" toc="false"}
 
# Survey instrument {style="appendix" startAt=1}
 
# Raw data {style="appendix"}

#Lettrines

Un paragraphe s’ouvre sur une lettrine quand le niveau ou le style de son titre, ou le style de paragraphe de son groupe :::paragraphs, en définit une (voir Configuration › Lettrines) : la première lettre est composée en grand à côté des premières lignes, qui sont raccourcies autour d’elle. Il n’y a aucun balisage dans le paragraphe lui-même ; le texte s’écrit comme d’habitude, et la lettre reste dans son mot pour la copie, la recherche et la carte des sources. Un attribut dropcap la règle pour un chapitre ou un groupe :

# Lost {dropcap=false}
 
# The mines {dropcap=2}
 
:::paragraphs{style="entry" dropcap}
The lamp of the first entry opens with an initial.
:::

Sur une ligne de titre, dropcap=false laisse le paragraphe qui suit ce titre sans la lettrine que définit son niveau ou son style, dropcap=N la compose sur N lignes, et un dropcap seul en donne une à ce paragraphe (sur trois lignes, dans le caractère du paragraphe) quand le niveau n’en définit pas. Sur un délimiteur :::paragraphs, l’attribut fait de même pour le premier paragraphe du groupe, ou pour chaque paragraphe quand le style indique each: true. Le paragraphe qui suit un titre est cherché au-delà des délimiteurs, des directives, des encadrés sortis du flux et des figures flottantes ; un paragraphe placé dans un encadré, un élément de liste, une citation ou un poème ne prend jamais de lettrine. Depuis postext 1.23.

#Blocs de code

Un listing se place entre deux délimiteurs de trois accents graves ou plus (ou de trois tildes ou plus), chacun sur sa propre ligne, avec au plus trois espaces de retrait. Tout ce qui se trouve entre eux est conservé tel quel : espaces en début de ligne et suites d’espaces, tabulations, lignes vides, et lignes qui commencent par #, -, 1., >, $ ou :::. Rien à l’intérieur n’est lu comme du Markdown : ni emphase, ni :ref, ni mathématiques, ni pastilles, ni directives, ni titres. Le délimiteur de fermeture utilise le caractère de celui d’ouverture et est au moins aussi long ; un listing qui montre un délimiteur se place donc dans un délimiteur plus long ou en tildes :

```bash {title="backup.sh" lineNumbers start=12 highlight="3,5-7"}
#!/usr/bin/env bash
# Copy the photos to the backup disk
rsync -a --delete ~/Photos/ /Volumes/Backup/Photos/
echo "done: $(date)"
```

La chaîne d’information qui suit le délimiteur d’ouverture nomme le langage (son premier mot : js, ts, python, bash, console, json…), et le reste est lu comme des attributs selon la syntaxe d’attributs, entre accolades ou non (title="app.js" lineNumbers). Tout autre texte après le langage est le titre : ```console Terminal et ```python normalize.py impriment Terminal et normalize.py au-dessus du listing.

Un délimiteur termine le paragraphe situé au-dessus de lui, avec ou sans ligne vide, et le texte qui suit le délimiteur de fermeture commence un nouveau paragraphe. Un délimiteur laissé ouvert court jusqu’à la fin du texte et est signalé (unclosedCodeBlock). Un délimiteur placé dans un :::callout est un encadré imbriqué dans celui-ci ; dans :::paragraphs, le listing garde le style du code, pas le style de paragraphe. Postext n’a pas de continuation d’élément de liste : un délimiteur qui suit un élément de liste ferme donc la liste. Les marques d’index et les ancres écrites dans un listing restent telles quelles.

Le code en retrait (quatre espaces ou une tabulation, après une ligne vide) n’est lu comme un listing que si codeStyle.indentedCode est activé : le texte Postext est souvent mis en retrait avec des espaces, et les éléments de liste imbriqués lisent les espaces en début de ligne.

L’aspect d’un listing (son caractère, son encadré, la largeur des tabulations, ce qui arrive à une ligne plus large que l’encadré, les numéros de ligne, les couleurs de ses jetons) est défini par codeStyle ; voir Configuration › Listings de code. Le code en ligne (`x`) reste dans le caractère du texte, sauf si codeStyle.inline lui en donne un. Un livre enregistré avant postext 1.23 et dont le texte contient des délimiteurs les lit comme à l’époque, c’est-à-dire comme du Markdown (codeStyle.blocks: false). Depuis postext 1.23.

#Directives

Les directives sont des balises de contrôle d’une seule ligne, écrites :::name ou :::name{attrs} sur une ligne à part. Elles ne produisent rien de visible : elles pilotent le placement et la numérotation.

Les valeurs d’attribut peuvent être entre guillemets doubles ("…"), entre guillemets simples ('…') ou nues (startAt=17). Une clé seule sans = est traitée comme un drapeau présent mais vide.

Seules pagebreak, numbering, columnbreak, space, toc et index sont reconnues aujourd’hui comme directives d’une ligne (et references, verse, page et strip comme blocs délimités) : toute autre ligne :::name qui n’est pas un conteneur (voir plus bas) est analysée comme un paragraphe et déclenche un avertissement Directive inconnue dans le Sandbox. Le moteur l’enregistre aussi, sous forme d’une entrée unknownDirective dans les contentWarnings du document (voir Configuration › Avertissements dans le document).

#Valeurs d’attribut

La même syntaxe key="value" est lue par les attributs de titre, les délimiteurs de directive et de conteneur (:::name{…}), les renvois en ligne (:ref{…}), les pastilles (:chip[…]{…}), les pastilles de couleur (:swatch{…}) et les marques d’index (:index[…]{…}). Ses règles :

• Clés. Elles commencent par une lettre ASCII ou _ et se poursuivent par des lettres ASCII, des chiffres, _ ou -. Les espaces autour de = sont admises, le ＝ pleine chasse que tape une méthode de saisie chinoise vaut =, une clé répétée garde sa dernière valeur, et une clé sans = est un drapeau à valeur vide. Une clé dans une autre écriture (作者=曹雪芹) n’est pas lue et déclenche un avertissement attributeKeyInvalid ; les autres clés du bloc s’appliquent quand même. Les valeurs peuvent être dans n’importe quelle écriture.
• Valeurs entre guillemets. Une valeur entre guillemets doubles peut contenir n’importe quoi sauf ", y compris des guillemets simples ; une valeur entre guillemets simples, n’importe quoi sauf '. Une valeur qui contient des guillemets doubles se place donc entre guillemets simples : lead='He said "hi"'. Il n’y a pas d’échappement (une barre oblique inverse est un caractère ordinaire) : une valeur qui a besoin des deux guillemets ASCII prend des guillemets typographiques (“…”, ’). Une valeur peut aussi s’ouvrir par le guillemet courbe “ ou le crochet d’angle 「 que tape une méthode de saisie chinoise, et court alors jusqu’au ” ou au 」 correspondant, espaces comprises : title=“甲戌本 眉批”, title=「脂批」.
• Valeurs nues (startAt=17, year=1998). Elles courent jusqu’à l’espace suivante : title=Hello world équivaut à title="Hello" plus un drapeau world.
• Pas d’accolades. { et } ne vont jamais dans une valeur. La première } termine le bloc : un délimiteur dont la valeur en contient une n’est plus une directive mais un paragraphe, et en ligne le reste de la valeur déborde dans le texte. Dans un titre, une accolade dans une valeur laisse tout le bloc dans le titre : # Title {note="a {b"} est composé tel qu’il est écrit. (Jusqu’à postext 1.8, une { après une espace faisait recommencer le bloc et b était lu comme un drapeau.)
• Les signes dollar sont du texte simple. Les attributs sont lus avant les mathématiques en ligne : lead="from $5 to $6" n’est donc que du texte.
• Une seule ligne. Un bloc d’attributs ne s’étend jamais sur plusieurs lignes.

# The Long Road {lead='A "road novel", they said' price="$18"}
 
:::callout{type="note" title='The "fast" path'}
…
:::

::resource{id="…"} est plus strict : l’identifiant entre guillemets doubles et aucun autre attribut (voir Ressources).

#Conteneurs

Un conteneur enveloppe une suite de blocs entre deux délimiteurs : une ligne d’ouverture :::name ou :::name{attrs}, puis n’importe quel contenu ordinaire (paragraphes, titres, listes, citations, formules, et même d’autres directives), et une ligne de fermeture contenant un ::: seul. Les conteneurs peuvent s’imbriquer ; chaque ::: de fermeture ferme le conteneur ouvert le plus intérieur.

:::callout{type="note"}
Keep the lantern lit **every** night.

- Check the wick.
- Trim it at dusk.
:::

Cinq noms de conteneur sont reconnus dans le flux du texte. Ce que chacun produit se règle dans sa propre section de la configuration :

Les attributs acceptés par chaque conteneur, et la façon dont il est stylé, sont documentés dans la Configuration. Les valeurs d’attribut suivent la même grammaire que celles des directives. Un délimiteur :::callout accepte type (l’identifiant d’un style d’encadré configuré ; un type inconnu ou absent se rabat sur le premier style), title (remplace le titre par défaut du style) et span / placement (column, page ou side ; here, top, bottom ou fixed) pour remplacer l’étendue et la position du style pour cet encadré :

:::callout{type="objectives" title="What you will learn" span="page" placement="top"}
- Name the parts of the lantern.
- Trim the wick without touching the glass.
:::

Un encadré flottant (placement auto, top ou bottom) accepte aussi columns, le nombre de colonnes adjacentes qu’il couvre sur une page à plusieurs colonnes, comme dans :::callout{placement="top" columns="2"} (depuis postext 1.18).

Un encadré peut aussi faire couler à côté de lui le texte qui le suit : wrap (left, right, start ou end), width (sa part de la colonne, de 0 à 1 ; layout.wrap.defaultWidth si non défini) et wrapGap (une longueur, comme 6pt), comme dans :::callout{wrap="right" width=0.4} (voir Habillage ; depuis postext 1.24).

Un encadré est mis en page comme une boîte : un titre facultatif, puis son contenu composé avec la typographie de corps et de liste propre au style. Par défaut, il reste d’un seul tenant et passe entier à la colonne ou à la page suivante quand il n’y tient pas (un encadré plus haut qu’une colonne entière est quand même coupé, plutôt que de déborder) ; un style avec keepTogether: false permet de le couper entre ses blocs, ou entre deux lignes, en laissant au moins splitMinLines lignes de texte (ou une figure, un tableau, une formule centrée ou un encadré imbriqué) de chaque côté de la coupure (une coupure à l’intérieur d’un paragraphe ou d’un élément de liste laisse aussi au moins layout.boxChildSplitMinLines de ses lignes de chaque côté : deux par défaut, splitMinLines quand cette valeur est plus petite ; les livres enregistrés avant la 1.5 dont les chapitres contiennent un encadré sont lus avec 1, la coupure de la 1.4). Chaque partie après la première s’ouvre sans l’icône, même si son texte garde la colonne de l’icône, et sans le titre, sauf si le style le répète (repeatTitle : « Key points (cont.) ») ; un style peut aussi placer une mention « Suite » sous chaque partie qui continue (continuesMarkerEnabled) : voir Marques sur un encadré coupé. Les encadrés sur toute la largeur (span="page") découpent la page en bandes de colonnes ; les encadrés span="side" quittent le flux pour la colonne latérale réservée aux flottants d’une mise en page à colonne et demie (layout.sideColumnRole: 'floats'), empilés à côté du texte qu’ils interrompent, et se composent comme des encadrés de colonne là où cette colonne n’existe pas ; les encadrés placement="fixed" quittent le flux et sont fixés à des coordonnées de la page (par exemple un badge d’auto-évaluation dans le coin inférieur gauche de la dernière page d’un chapitre), les colonnes qu’ils recouvrent cédant cette zone ; les encadrés flottants (placement="top" / "bottom") quittent le flux là où ils apparaissent et prennent la première bande libre après cette position (le pied de la page, ou la tête ou le pied de la suivante), tandis que le texte qui les suit remplit la page qu’ils ont quittée. Un style avec floatBarrier: true (typiquement l’encadré « points clés » qui clôt un chapitre) fait de l’encadré une barrière de flottants : chaque figure ou tableau référencé avant lui est placé avant lui (dans les emplacements libres de la page, ou sur des pages ouvertes avant l’encadré), si bien qu’aucun flottant ne s’échappe au-delà de la fin de son chapitre. Un délimiteur :::name inconnu n’est pas un conteneur : la ligne est traitée comme du texte, exactement comme une directive inconnue.

Un délimiteur :::part accepte number (tel que vous voulez le voir imprimé : "I", "IV", "3" ; il est aussi analysé pour que le design puisse le reformater) et title ; les deux sont facultatifs. Un troisième attribut, palette="band=#hex" (plusieurs paires id=#hex séparées par des virgules), recolore chaque couleur du design liée à ces identifiants de palette (titres courants, bandeau d’ouverture, designs de partie) ainsi que les couleurs du flux de texte qui partagent leur valeur de base (titres, gras, renvois, puces, légendes, tableaux, encadrés, pastilles) pour la partie et les chapitres qui la suivent, jusqu’à la partie suivante ; voir Configuration › Parties. Le conteneur ouvre toujours une page à part : un saut de page de la parité configurée avant lui, une seule colonne de corps aux marges parts.margins, le design d’ouverture sur toute la page, et un autre saut de page après le délimiteur de fermeture. Le corps (en général la liste des chapitres que regroupe la partie, ou rien du tout) est composé avec parts.bodyStyle :

:::part{number="I" title="Foundations"}
1. The lantern and its parts
2. Trimming the wick
:::

# The lantern and its parts

Avec les réglages de titre par défaut, on obtient la séquence classique : page de partie sur une belle page, page de gauche blanche, chapitre sur la belle page suivante. La page est signalée avec role: 'part' pour que les en-têtes et pieds de page puissent l’ignorer, et {partTitle} / {partNumber} renvoient à la partie en cours sur toutes les pages suivantes. Voir Parties dans la référence de configuration.

Un délimiteur n’a pas besoin d’une ligne vide avant lui : un délimiteur d’ouverture ou de fermeture collé juste sous un paragraphe, une liste ou une citation termine ce bloc. Un conteneur resté ouvert à la fin du document y est fermé automatiquement, et le Sandbox signale un avertissement Conteneur non fermé qui pointe vers la ligne d’ouverture. Un ::: isolé sans conteneur ouvert reste dans le texte sous forme de paragraphe visible au lieu d’être supprimé en silence.

#:::columns

Un groupe :::columns{count=2} … ::: compose les blocs placés entre ses délimiteurs en count colonnes de même largeur (de 2 à 6), le texte qui le suit reprenant toute la largeur. Dans un :::callout, les colonnes se partagent la largeur intérieure de l’encadré, séparées par le columnGap du style, dans la typographie de corps et de liste de l’encadré, et l’encadré grandit jusqu’à la colonne la plus haute. Dans le texte courant (depuis postext 1.25), elles se partagent la colonne de texte, séparées d’une ligne de corps, et les blocs gardent la typographie propre au texte ; avec span="page", sur une page à plusieurs colonnes, le groupe découpe la page en une bande comme le fait un encadré sur toute la largeur : les colonnes au-dessus de lui se terminent à la même hauteur, le groupe est composé sur toute la largeur du contenu (séparé par la gouttière) et le texte reprend dans chaque colonne sous lui. Sur une page à une colonne, span="page" le compose dans la colonne. Les titres placés dans un groupe gardent leur style, leur numéro et leur entrée dans la table des matières, une note de bas de page appelée dans le groupe va au pied de la colonne de texte, et les figures qu’il cite flottent comme d’habitude.

Un groupe composé en entier est coupé là où ses colonnes s’équilibrent le mieux (entre deux blocs, ou entre les lignes d’un paragraphe ou d’un élément de liste, dont la fin reprend en tête de la colonne suivante sans sa puce), sauf si breaks fixe le début des colonnes, sans coupure à l’intérieur d’un paragraphe : une colonne de texte à côté d’une colonne de figures.

L’espace autour d’un groupe. Dans le texte courant, un groupe est suivi de l’espacement entre paragraphes du corps (une ligne avec bodyText.paragraphSpacing, rien sans lui), et dans un encadré d’aucun espace propre. marginTop et marginBottom sur le délimiteur le règlent : :::columns{count=3 span="page" marginBottom="0.75em"}. Chacun est un minimum qui se fond avec l’espace que le bloc voisin réserve pour lui-même, comme le font les marges d’un encadré. Dans le texte courant, le flux revient sur la grille de ligne de base sous le groupe, l’espace se compte donc en lignes entières, et un groupe réparti entre plusieurs colonnes ou pages garde la marge du haut pour sa première partie et celle du bas pour sa dernière. Un em correspond à la taille du texte dans lequel se trouve le groupe ; une valeur qui n’est pas une longueur, ou une valeur négative, est ignorée.

:::callout{type="summary"}
:::columns{count=2}
- Every element is one kind of atom.
- Electrons live in orbitals.
- A bond shares or transfers electrons.
:::
:::

Comment compte breaks. breaks numérote dans l’ordre les blocs du groupe (paragraphes, éléments de liste, un bloc chacun, formules centrées, figures et tableaux), et un :::callout imbriqué compte pour un bloc, quel que soit son contenu. Les directives ne sont pas des blocs : un :::space entre deux strophes ne décale pas le compte. Un numéro inférieur à 2, au-delà du dernier bloc du groupe ou qui ne suit pas la coupure précédente est ignoré. Dans un groupe, :::space sépare deux blocs comme partout ailleurs dans un encadré, et disparaît en haut du groupe et en tête de chacune de ses colonnes (une position breaks ou une coupure d’équilibrage) : pour faire commencer le groupe plus bas, placez l’espace avant le délimiteur :::columns. Deux colonnes qui portent le même espacement s’alignent donc strophe par strophe :

:::callout{type="verse"}
:::columns{count=2 breaks="4"}
The lamp is lit at dusk,
 
and trimmed before the dawn.
 
:::space
 
The keeper sleeps by day.
 
La lámpara se enciende al anochecer,
 
y se despabila antes del alba.
 
:::space
 
El farero duerme de día.
:::
:::

Ici, le quatrième bloc, « La lámpara… », ouvre la deuxième colonne ; les deux lignes :::space ne sont pas comptées et laissent le même blanc dans les deux colonnes.

Couper un groupe

Depuis postext 1.25, un groupe qui ne tient pas dans la place dont il dispose (le reste de sa colonne dans le texte courant, ou la partie d’un encadré qui se coupe, avec keepTogether: false ou un encadré plus haut qu’une colonne) est coupé entre ses colonnes et se poursuit dans la colonne ou la page suivante, dans un encadré à part pour un groupe placé dans un encadré :

• flow="snake", par défaut sans breaks : les blocs du groupe courent comme une seule galée, à la manière du texte d’un article de journal. Une partie qui continue remplit ses colonnes l’une après l’autre, aussi équilibrées que les coupures le permettent, en coupant entre deux blocs ou entre les lignes d’un paragraphe ou d’un élément de liste (au moins layout.boxChildSplitMinLines de ses lignes de chaque côté, deux par défaut) ; la dernière partie est équilibrée comme l’est un groupe entier.
• flow="parallel", par défaut avec breaks : chaque suite que commencent les coupures est un flux qui garde sa propre colonne. Une partie remplit chaque flux jusqu’à la place dont elle dispose, et chacun reprend dans la même colonne de la partie suivante : un poème et sa traduction placés côte à côte restent ainsi alignés strophe par strophe. Un groupe parallèle sans breaks se poursuit comme un groupe en serpent.

Un encadré imbriqué dans un groupe reste entier et passe à la partie suivante, et un groupe placé dans un encadré imbriqué n’est jamais coupé. Un groupe qui tient est composé exactement comme avant. layout.flowColumns: false garde les règles de postext 1.24 : un délimiteur hors d’un encadré est ignoré et un groupe n’est jamais coupé ; les livres enregistrés avant la 1.25 qui contiennent un groupe :::columns sont lus de cette façon. Le Sandbox signale un flow qu’il ne connaît pas (Flux de colonnes inconnu) et les colonnes plus étroites que six cadratins de leur texte (Colonnes trop étroites).

## Briefs
 
:::columns{count=3 span="page" rule}
**Harbour.** The new pier opens on Monday…
 
**Market.** Stall rents stay as they are…
 
**Weather.** Rain from the west by the evening…
:::

Un délimiteur :::callout accepte aussi label="…" : le texte qu’un style doté d’un onglet label imprime dans le coin supérieur de l’encadré (:::callout{type="box" label="BOX 1-1" title="The octet rule"}).

Un :::callout placé dans un autre est un encadré à part entière : une fiche d’exercice contenant des cases de réponse, par exemple. Il prend son propre style (fond, bordure, rayon, marge intérieure, titre, icône) sur toute la largeur intérieure de l’encadré extérieur et s’empile parmi ses autres blocs ; son span et son placement sont ignorés, puisqu’un encadré imbriqué coule toujours à l’intérieur de son parent. Chaque délimiteur ferme l’encadré le plus intérieur encore ouvert :

:::callout{type="card"}
The statement of the exercise.
 
:::callout{type="answer"}
A white answer box with its own border and padding.
:::
 
:::callout{type="answer"}
A second answer box.
:::
:::

Quand l’encadré extérieur se coupe sur plusieurs colonnes ou pages (keepTogether: false, ou plus haut qu’une colonne), un encadré imbriqué passe entier au fragment suivant, sauf si son propre style l’autorise à se couper lui aussi ; chaque fragment redessine les cadres qu’il contient, et un encadré imbriqué qui continue perd son icône, ainsi que son titre sauf si son style le répète (repeatTitle).

#:::paper

Un livre peut changer de papier pour une suite de pages : un cahier de planches sur couché brillant dans un livre imprimé sur un papier vélin non couché, un encart cartonné, quelques feuillets de papier teinté. Enveloppez ce contenu dans un conteneur :::paper :

:::paper{type=coatedGloss grammage=130}
## Plates
::resource{id="plate-1"}
::resource{id="plate-2"}
:::

Un papier couvre des feuilles entières : le contenu placé entre les délimiteurs commence donc sur une nouvelle page, et ce qui suit le ::: de fermeture commence aussi sur une nouvelle page. Une suite qui termine le document ne laisse aucune page blanche après elle. Les figures et tableaux cités dans la suite sont placés avant qu’elle ne se ferme. Chaque page composée avec du contenu issu du conteneur porte le papier dans la mise en page (VDTPage.paper, avec les attributs tels que les écrit le délimiteur) ; les pages hors du conteneur ne portent rien. La visionneuse Folio le lit et dessine ces feuillets avec la couleur, la surface, l’épaisseur et la rigidité du papier. Les sorties canvas, PDF et HTML l’ignorent : les pages sont composées et imprimées comme les autres.

Les attributs sont ceux des réglages folio.paper, et tous sont facultatifs. Un attribut que le délimiteur omet suit le papier du document, et à défaut les valeurs par défaut du papier :

Un :::paper placé dans un autre ne remplace que les attributs qu’il définit, et il commence et se termine lui aussi par un saut de page. Dans un :::callout, les délimiteurs sont ignorés. Une valeur que le moteur ne sait pas lire est écartée, et le Sandbox la signale par un avertissement Attribut de papier non valide (paperAttributeInvalid dans les contentWarnings du document).

#:::pagebreak

La directive n’impose pas de parité à elle seule : elle n’agit que sur la mise en page du bloc suivant. Utilisez-la pour terminer une préface, placer une dédicace seule sur sa page, ou marquer la fin d’une section. Quand on veut à la fois un saut de page et une remise à zéro de la numérotation au même endroit, enchaînez :::pagebreak puis :::numbering : le changement de numérotation s’applique à la nouvelle page que :::pagebreak vient de créer.

Un saut de page sur une page encore vide ne fait rien : il n’ajoute donc jamais de page blanche. Il ne remplace pas non plus le breakBefore d’un titre qui le suit immédiatement (le niveau 1 en a un par défaut) : le titre applique quand même sa parité, ce qui peut ajouter une page blanche après celle qu’a ouverte la directive. Pour faire commencer un titre exactement là, désactivez son saut (voir Configuration → Styles de titre). Après un titre de couverture qui remplit sa page, le saut est facultatif : la couverture occupe déjà le reste de sa page, en mise en page à une ou à plusieurs colonnes, et un :::pagebreak juste après ne fait pas de mal. Il n’est nécessaire qu’après une couverture dont le design s’arrête avant le pied de la page, quand le texte doit malgré tout commencer à la page suivante (voir Configuration → Hauteur réservée).

The old chapter ends here.
 
:::pagebreak{parity="odd"}
 
# A new chapter

Le drapeau center (:::pagebreak{center}, désactivé avec center=false) centre le texte de la page qu’ouvre le saut entre la tête et le pied du bloc de texte, et dans la largeur de la page en texte vertical : le ページの左右中央 d’un titre de partie ou d’une dédicace japonaise. Les flottants, les notes et les titres courants restent à leur place, et une page déjà pleine n’est pas touchée. Le drapeau ne termine pas la page : fermez-la avec un autre :::pagebreak.

:::pagebreak{center}
 
# 上　先生と私
 
:::pagebreak

Attribut de parité

L’attribut parity accepte les cinq mêmes valeurs que headings.levels[*].breakBefore.parity :

• 'any' : la valeur par défaut, sans contrainte de parité ; le saut ouvre simplement une nouvelle page.
• 'odd' / 'even' : la nouvelle page s’ouvre du côté demandé de la double page ; une seule page blanche n’est insérée que lorsque la page suivante naturelle tombe du mauvais côté.
• 'always-odd' / 'always-even' : garantit au moins une page blanche de séparation obligatoire entre le contenu précédent et la nouvelle page, puis impose la parité. La page blanche de séparation appartient au chapitre précédent ; toute page de remplissage supplémentaire due à la parité appartient à ce qui suit.

À qui appartient la page blanche

Les deux sortes de pages blanches que :::pagebreak (et breakBefore) peuvent introduire sont distinguées dans le modèle VDTPage :

• blankForParity: true : insérée pour satisfaire une contrainte de parité. Dans les en-têtes {chapterTitle}, cette page porte le titre du chapitre à venir, car la page blanche n’existe que pour placer ce chapitre sur la bonne parité.
• blankForForce: true : la page de séparation obligatoire d’un mode 'always-*'. Elle appartient au chapitre précédent : une respiration voulue en fin de chapitre, pas un remplissage de parité pour le chapitre suivant.

Ces deux mêmes règles donnent à une page blanche les titres courants et la palette d’une section stylée : voir Configuration › Styles de titre.

Exception en début de document

Quand :::pagebreak est la toute première construction d’un document (ou qu’un titre avec breakBefore en ajouterait un), la parité n’est pas imposée tant que la première page est encore vide. Le bloc suivant tombe en page 1 tel qu’il est écrit, quelle que soit la parité demandée : pas de page blanche parasite au début.

#:::numbering

:::numbering est la façon de relancer le compteur de pages en cours de document. L’exemple de livre classique :

---
title: "A Book With Front Matter"
---
 
# Preface
 
…
 
:::pagebreak{parity="odd"}
:::numbering{format="decimal" startAt=1}
 
# Chapter 1

Les pages de la préface sont numérotées i, ii, iii, … ; le premier chapitre s’ouvre sur une belle page numérotée 1.

Les changements de format seuls (sans startAt) laissent le compteur continuer : utile, par exemple, pour passer de lower-alpha à upper-alpha sans remise à zéro.

format accepte n’importe quelle graphie d’un format de numérotation : roman-lower et i fonctionnent aussi bien que lower-roman, arabic aussi bien que decimal, 一 et あ aussi bien que japanese-informal et hiragana (voir Configuration › Graphies des formats de numérotation). Une valeur qui n’est aucune d’elles laisse le format inchangé, et le Sandbox la signale.

lines relance le compte des numéros de ligne, pas le compteur de pages : la ligne comptée suivante prend le numéro donné, quoi qu’indique lineNumbers.restart. Une valeur qui n’est pas un nombre entier supérieur ou égal à 0 est ignorée.

## Act II
 
:::numbering{lines=1}

#:::space

:::space laisse un espace vertical entre deux blocs : pour détacher une ligne de conclusion du texte qui la précède, pour descendre un peu une épigraphe ou une signature, ou pour ouvrir un blanc de séparation entre deux parties d’un texte. Les lignes vides supplémentaires dans le Markdown ne le font pas : comme dans tout Markdown, une suite de lignes vides n’est qu’un séparateur de paragraphes, ce qui évite qu’un document change de mise en page quand un éditeur ou un formateur ajoute ou retire des blancs.

The last paragraph of the scene.
 
:::space
 
A new scene begins one line lower.
 
:::space{lines=2}
 
Two lines lower still.

• lines : la quantité d’espace, en lignes de corps (la grille de ligne de base). Par défaut 1. Les nombres entiers gardent chaque ligne de texte sur la grille, de sorte que les colonnes restent alignées d’un bout à l’autre de la page ; une fraction (lines=0.5) est respectée exactement, au prix de cet alignement jusqu’au prochain bloc qui se cale sur la grille. Une valeur qui n’est pas un nombre supérieur à 0 et inférieur ou égal à 20 revient à une ligne, et le Sandbox la signale (Taille d’espace non valide).
• Il s’additionne. L’espace s’ajoute à la marge qui sépare déjà les deux blocs (la marge haute d’un titre, la marge basse d’une liste) au lieu de se fondre avec elle. Deux lignes :::space d’affilée ajoutent deux lignes.
• Il disparaît à une coupure, comme le \vspace de LaTeX : en haut d’une colonne ou d’une page il s’efface, si bien qu’une page ne s’ouvre jamais sur un trou ; et quand il ne tient pas au pied d’une colonne, il termine simplement cette colonne, sans reporter le reste.
• Le paragraphe qui le suit est composé sans retrait. Quand bodyText.indentAfterHeading est désactivé, un paragraphe qui suit immédiatement :::space perd son retrait de première ligne, comme après un titre : la convention habituelle pour un texte qui reprend après une ligne blanche.
• Dans un encadré (ou un groupe :::columns), il sépare de la même façon les enfants de l’encadré, mesuré en lignes de corps propres à l’encadré. Avant le premier bloc de l’encadré, il disparaît, comme en haut d’une colonne (la marge intérieure détache déjà le contenu du cadre), sauf dans deux cas où il ouvre cette place : juste sous le titre de l’encadré, et dans un encadré qui ne contient rien d’autre (une case de réponse, un espace pour écrire, dimensionné en lignes). Il disparaît toujours en haut d’un groupe :::columns, en tête de chacune de ses colonnes, et en haut de la partie d’un encadré coupé qui continue dans la colonne ou la page suivante. Dans un conteneur :::paragraphs, il fonctionne comme entre deux paragraphes du corps.
• Garder avec le suivant en tient compte : un titre suivi de :::space passe plus loin quand l’espace et les premières lignes de son texte ne tiennent pas sous lui.

La case de réponse d’une fiche d’exercice est un encadré dont le seul contenu est de l’espace : la question dans son titre, quatre lignes de place en dessous.

:::callout{type="answer" title="1. Name the three parts of the lantern."}
:::space{lines=4}
:::

Pour une coupure fixe plutôt qu’un espace, utilisez :::columnbreak ou :::pagebreak.

#:::verse

Un poème. :::verse le compose selon l’une de deux dispositions : vers par vers, comme on imprime la plupart des poèmes, ou dans la disposition arabe classique d’une qaṣīda, chaque bayt en deux hémistiches côte à côte. Un poème dont les vers portent un séparateur d’hémistiches (||, ou un \\ entouré d’espaces) prend la disposition arabe, et tout autre la disposition vers par vers ; layout=lines ou layout=bayt sur le délimiteur en impose une.

Vers par vers

Écrivez le poème tel qu’il s’imprime : un vers par ligne de Markdown, une ligne vide entre les strophes, et des espaces avant un vers pour le mettre en retrait.

:::verse
Whose woods these are I think I know.
His house is in the village though;
  He will not see me stopping here
  To watch his woods fill up with snow.
 
My little horse must think it queer
To stop without a farmhouse near
:::

• Vers. Chaque ligne non vide est un vers, lu à part comme du Markdown en ligne : l’italique, les petites capitales, les notes et les renvois fonctionnent tous. Une suite de lignes vides forme un seul changement de strophe.
• Retraits. Chaque espace en début de ligne mesure indentStep, 0,5 cadratin par défaut : deux espaces mettent donc un vers en retrait d’un cadratin ; une tabulation compte pour quatre espaces et une espace idéographique (U+3000) pour deux.
• Rejets. Un vers un peu plus large que la justification resserre d’abord ses espaces entre mots, jusqu’à bodyText.minWordSpacing de leur largeur naturelle (la limite jusqu’à laquelle se resserre le texte justifié), et reste sur une ligne ; tighten=false sur le délimiteur, ou bodyText.verse.tighten: false, le fait plutôt passer à la ligne. Un vers encore plus large passe à la ligne à une espace entre mots. Avec turnover=hang (par défaut), la suite pend sur la ligne suivante, en retrait de hang par rapport au début du vers : le hangingIndent du style de paragraphe du poème, à défaut 2 cadratins (bodyText.verse.hang). Avec turnover=right, elle est alignée sur la fin de la justification derrière un crochet ouvrant (turnoverMark, [ par défaut), l’usage des éditions anglaises et espagnoles. Les vers ne sont pas coupés par la césure, sauf si leur style de paragraphe définit lui-même hyphenation: true. Un vers et son rejet ne sont jamais séparés par une coupure de colonne ou de page.
• Strophes. L’espace entre deux strophes vaut une ligne de l’interlignage du poème ; stanzaSpace=0.5 le réduit à une demi-ligne, et une longueur (stanzaSpace=6pt) le fixe exactement. Sur la grille de ligne de base, il se compte en lignes entières de la grille. Les colonnes et les pages se coupent d’abord entre les strophes ; à l’intérieur d’une strophe, elles se coupent selon les règles des orphelines et des veuves, qui comptent alors les vers de la strophe. keepStanzas=N garde entière toute strophe de N vers ou moins : un haïku prend keepStanzas=3, un tanka keepStanzas=5.
• Placement. Le poème est centré dans la justification sur son vers le plus long, tous les vers alignés sur le début du poème (align=center, le réglage habituel pour un poème cité dans de la prose) ; align=start l’aligne sur le début de la justification, ce qui est le réglage par défaut en texte vertical. Le paragraphe qui introduit le poème garde sa dernière ligne avec les premiers vers.
• Vers en escalier. Un vers écrit + … commence là où s’arrêtait le vers du dessus, une espace entre mots plus loin, comme un vers de théâtre partagé entre deux personnages. Écrivez \+ pour un vers qui commence par un signe plus.
• Césures. Avec keepSpaces sur le délimiteur, une suite de deux espaces ou plus à l’intérieur d’un vers garde sa largeur ; sans lui, les espaces se réduisent comme dans n’importe quel paragraphe.
• Caractère et sens d’écriture. style nomme un style de paragraphe, qui donne le caractère, le corps, l’interlignage, indent, et l’espace au-dessus et au-dessous du poème. dir et lang règlent son sens d’écriture et sa langue : un poème latin dans un livre arabe (dir=ltr) est mis en retrait depuis son propre côté de début. En texte vertical, chaque vers est une colonne, en retrait depuis la tête.

bodyText.verse fixe les valeurs par défaut pour tous les poèmes (voir Configuration › Vers). Le texte brut garde le poème tel qu’il est écrit, un saut de ligne entre les vers et une ligne vide entre les strophes, de sorte qu’un passage copié ou une recherche le lisent vers par vers ; l’EPUB recomposable fait de chaque strophe un élément dont les vers font pendre leurs rejets, et le PDF balisé balise chaque strophe comme un paragraphe.

Numéros de ligne. Avec lineNumbers activé, les vers d’un poème sont comptés (voir Configuration › Numéros de ligne). Chaque vers compte une fois : un rejet ne prend pas de numéro, et l’espace entre les strophes n’est pas compté. Par défaut, un vers sur cinq imprime son numéro dans la marge extérieure, et le compte repart à chaque poème. Un poème en disposition arabe classique compte une ligne par bayt. Le délimiteur règle un poème en particulier : lineStart=N donne un numéro à son premier vers, interval=N son propre intervalle, et numbered=false l’exclut.

:::verse{lineStart=37}
…
:::

Avec l’intervalle par défaut de 5, ce poème imprime 40, 45 et ainsi de suite à côté de ses vers.

Disposition arabe classique

Un poème en disposition arabe classique (une qaṣīda, une qiṭʿa) : chaque vers, le bayt, sur une ligne en deux moitiés, le ṣadr du côté du début (à droite en arabe) et le ʿajuz du côté de la fin, avec un blanc entre eux. Écrivez un bayt par ligne, ses hémistiches séparés par || (un \\ entouré d’une espace de chaque côté, comme dans les textes de Wikisource, fonctionne aussi). Une ligne sans séparateur est un hémistiche seul, centré sur le poème.

فأنشد يقول:
 
:::verse
يَا حُرْقَةَ الدَّهْرِ كُفِّي || إِنْ لَمْ تَكُفِّي فَعِفِّي
فَلَا بِحَظِّيَ أُعْطِي || وَلَا بِصَنْعَةِ كَفِّي
:::

• Une seule largeur. Chaque hémistiche du poème est composé à la même largeur : chaque ṣadr commence donc sur la même verticale et chaque ʿajuz finit sur une autre, et les lettres de la rime s’alignent tout au long du poème. Cette largeur est celle de l’hémistiche le plus large, au plus la moitié de la justification moins le blanc ; width la fixe (width=55mm). Chaque hémistiche y est amené d’abord par des kashidas (les vers s’allongent plus que la prose : deux fois bodyText.kashidaMaxLength), puis par ses espaces entre mots ; un hémistiche d’un seul mot qui ne peut pas la remplir laisse le reste dans le blanc.
• Le blanc mesure 2 cadratins par défaut ; gap le fixe (gap=3em, un nombre seul s’exprime en cadratins). ornament imprime un signe en son milieu (ornament="٭"), qui ne fait pas partie du texte.
• Trop large. Un hémistiche plus large que la largeur commune resserre d’abord ses espaces entre mots jusqu’à bodyText.minWordSpacing. S’il ne tient toujours pas, son bayt est composé en décalé : le ṣadr aligné sur le côté du début, sur sa propre ligne, le ʿajuz aligné sur le côté de la fin, sur la suivante.
• Placement. Le poème est centré dans la colonne ; align=start l’aligne sur le côté du début. Un bayt n’est jamais coupé entre deux colonnes ou deux pages, et le poème suit les règles des orphelines et des veuves des paragraphes (un poème de trois bayts ou moins reste entier). Le paragraphe qui précède le poème et l’introduit (« فأنشد يقول: ») garde sa dernière ligne avec les premiers bayts.
• Caractère. Le poème prend le caractère, le corps et l’interlignage du texte courant ; style lui attribue un style de paragraphe (style="verse"), ce qui permet de donner à un poème vocalisé l’interlignage supplémentaire dont ses harakat ont besoin. dir=ltr ou dir=rtl règle son sens d’écriture comme pour n’importe quel bloc ; un poème en écriture latine dans un livre de gauche à droite a son ṣadr à gauche.

Le texte brut du poème garde les hémistiches et les bayts séparés (une tabulation et un saut de ligne), de sorte qu’une recherche ou un passage copié le lisent tel qu’il est écrit ; les kashidas et l’ornement sont omis.

#:::toc

:::toc imprime la table des matières là où il se trouve. Il se développe en blocs ordinaires (un par titre des niveaux que liste toc.levels, le niveau 1 par défaut, et un par :::part), si bien que la table des matières coule à travers les colonnes et les pages comme n’importe quel autre texte, et qu’un clic sur une entrée mène à la ligne de la directive. Une entrée affiche le numéro du titre (la sortie de son numberingTemplate, à défaut le rang du chapitre), son titre, des points de conduite et le numéro de la page où il commence, et, quand toc.subtitle est activé, une deuxième ligne avec un attribut du titre, comme le {author="…"} du chapitre. Une partie a sa propre ligne, dessinée par toc.parts.design et colorée avec la palette propre à la partie. Les titres dont le style indique numbered: false sont listés sans numéro ; {toc="false"} sur un titre l’exclut (typiquement le titre de la table des matières elle-même).

# Contents {style="front-matter" toc="false"}
 
:::toc

Les numéros de page sont ceux que le document imprime réellement. Un document mis en page seul est remis en page avec les numéros de la passe précédente jusqu’à ce qu’ils ne bougent plus : avec une numérotation qui repart après les pages liminaires (la recette :::numbering ci-dessus), une passe supplémentaire suffit. Un chapitre mis en page seul (les aperçus du Sandbox) reçoit à la place le plan du livre entier de son hôte. Voir Table des matières dans la référence de configuration.

#:::index

:::index imprime l’index là où il se trouve : les termes marqués avec :index[…] ou :index{term="…"} dans tout le livre, avec leurs pages, qui suivent le texte quand il se déplace. Il est décrit avec les marques dans Index. Une colonne ne se termine jamais après la première entrée d’un groupe, ni avant sa dernière : deux entrées du groupe restent et deux passent plus loin, ou le groupe passe entier (index.groups.splitMinEntries).

# Index {style="index"}
 
:::index

#Sauts de ligne

Les lignes d’un paragraphe sont jointes par une espace. Pour terminer une ligne à l’intérieur d’un paragraphe sans en commencer un nouveau (une adresse, la formule d’appel d’une lettre, une dédicace), terminez la ligne source par une barre oblique inverse, le saut forcé de CommonMark, ou écrivez \\ suivi d’une espace :

To the keeper of the lighthouse,\
at the end of the northern pier.
 
Ana Ruiz \\ Calle Mayor 4 \\ 28013 Madrid

• La ligne qui précède un saut est composée à sa largeur naturelle, comme la dernière ligne d’un paragraphe, jamais étirée jusqu’à la justification. Le texte qui le suit ouvre une nouvelle ligne du même paragraphe, sans retrait de première ligne ni espace au-dessus ; sous un retrait suspendu, elle pend comme toute ligne après la première.
• Les paragraphes, les citations (> First line\ au-dessus de > second line), les notes de bas de page et les éléments de liste l’acceptent. Un élément de liste occupe une seule ligne de source : il se coupe donc avec \\.
• Une barre oblique inverse qui termine le paragraphe s’imprime, comme dans CommonMark, et deux sauts d’affilée n’en font qu’un : pour une ligne vide, commencez un nouveau paragraphe ou ajoutez un :::space.
• Un \\ collé au caractère suivant n’est pas un saut : \\* imprime une barre oblique inverse et un astérisque échappé, C:\\Temp les deux barres obliques inverses. Dans le code en ligne et dans une formule, les barres obliques inverses appartiennent au code et à la formule.
• Deux espaces en fin de ligne, l’autre saut forcé de CommonMark, n’en sont pas un : elles sont invisibles dans un éditeur, et beaucoup d’éditeurs les laissent traîner, elles couperaient donc des lignes sans que personne ne l’ait voulu.
• Le texte copié depuis la visionneuse HTML contient un saut de ligne à cet endroit, l’EPUB recomposable un <br/>, le texte du PDF une fin de ligne, et un export Word un saut de ligne manuel (Maj+Entrée), que l’import Word relit comme un saut.
• Un poème garde ses vers, ses retraits et ses strophes dans un bloc :::verse, sans barre oblique inverse à chaque ligne.

Jusqu’à postext 1.22, la barre oblique inverse s’imprimait et les lignes étaient jointes par une espace. Un livre enregistré à cette époque dont le texte termine une ligne par une barre oblique inverse, ou place \\ devant une espace, garde cette lecture (bodyText.hardLineBreaks: false, voir Configuration › Paquets écrits par postext 1.4 ou antérieur).

#Sauts de ligne dans les titres

Écrivez \\ dans un titre (ou dans l’attribut title d’une partie) pour forcer un saut de ligne là où le titre est affiché comme un titre : le titre dans la colonne continue de couler et y montre une espace, tandis que le {titleText} d’un design d’ouverture coupe la ligne à cet endroit (dans chaque mode overflow de l’élément de texte). Les titres courants, {chapterTitle}, {partTitle} et les signets du PDF affichent toujours le titre sur une seule ligne. En chinois ou en japonais, le saut se lit comme une espace idéographique entre deux caractères de cette écriture (un titre en distique) ; là où l’un d’eux touche un chiffre ou du texte latin (关于举办 \\ 2026年…), la page place l’espace entre han et latin, et les signets du PDF et le titre du document joignent les deux moitiés sans rien, comme s’écrit le chinois courant.

# Concepts of health and illness. \\ Community health {author="I. Zango Martín"}

#Mise en forme en ligne

Le balisage en ligne est reconnu dans tout bloc de texte (titres, paragraphes, citations, éléments de liste). Dans un titre, il suit headings.inlineMarks, activé par défaut : l’italique, le gras, les exposants et indices, les petites capitales et les liens du titre s’impriment comme dans un paragraphe, et un passage en italique dans un titre en italique sort en romain. Désactivé, les marqueurs sont supprimés et le titre s’imprime dans le style propre au titre ; les configurations enregistrées par postext 1.4 ou antérieur dont les titres portent des marques sont lues de cette façon (voir Configuration › Titres). Une maquette de titre imprime {titleText} en texte brut dans les deux cas.

Balisage	Syntaxe	Remarques
Gras	bold ou bold	Rendu avec bodyText.boldFontWeight. Un bodyText.boldColor facultatif remplace la couleur du texte courant pour les passages en gras.
Italique	italic ou italic	Rendu avec la variante italique de la famille de caractères en cours. Un bodyText.italicColor facultatif remplace la couleur du texte courant pour les passages en italique. Un tiret bas ne marque l’emphase qu’en limite de mot, comme en CommonMark : placé entre deux lettres ou deux chiffres (snake_case_name, le SR_AIR_EN.pdf d’une URL), c’est du texte (de même pour bold) ; à l’intérieur d’un mot, utilisez des astérisques (unbelievable). Les caractères chinois, japonais et coréens ne comptent pas ici, puisque ces écritures n’ont pas d’espaces : 中文_斜体_中文 et 中文__粗体__中文 sont en italique et en gras. Un __ qui ne produit pas de gras ne devient jamais de l’italique : foo__bar__baz reste du texte.
Gras italique	both ou both	Les deux attributs se combinent.
Exposant	^text^	Composé à 58 % de la taille du texte et surélevé d’un tiers de celle-ci : un exposant (10^-8^), la charge d’un ion (Na^+^). Le texte marqué commence et se termine par un caractère autre qu’une espace ; un accent circonflexe isolé dans la prose reste littéral, de même que les émoticônes ^_^ et ^o^ (n.^o^ et 1^o^ restent des exposants).
Indice	~text~	Même taille, abaissé de 0,15 de la taille du texte, pour rester dans les descendantes : un indice chimique (H~2~O, pK~a~). Un tilde encadré de deux chiffres est un intervalle et reste littéral : 3~5 days, 需要3~5天. De même pour un tilde entre deux mots chinois, qui n’ouvre aucun indice : 周一~周五, 北京~上海 ; un indice se ferme néanmoins devant un caractère chinois (F~合~等于). Se combine avec le gras et l’italique (H~2~O). Un indice et un exposant écrits ensemble, sans rien entre eux, sont superposés comme dans une formule : T~0~^2^ place le 2 au-dessus du 0, quel que soit l’ordre d’écriture, l’indice étant abaissé de 0,25 de la taille du texte pour dégager l’exposant, et la paire prend la largeur du plus large des deux. Une espace ou une lettre entre eux les compose l’un après l’autre ; un gluon de mots (U+2060) aussi, sans rien de visible entre eux. Une paire superposée n’est jamais séparée par un saut de ligne : un mot trop large pour la ligne est coupé avant la paire.
Petites capitales	:smallcaps[text]	Les minuscules sont composées en capitales à 70 % de la taille du texte : le nom d’un personnage dans une pièce de théâtre, un sigle dans le texte courant. Accepte d’autres marques à l’intérieur et autour ; voir Petites capitales.
Orientation dans le texte vertical	:tcy[12], :upright[GDP], :sideways[12]	Dans le texte vertical : une seule cellule debout (tate-chu-yoko), chaque caractère debout dans sa propre cellule, ou tout le passage pivoté. Sans effet dans le texte horizontal ; voir Orientation dans le texte vertical.
Marques chinoises	:dots[不可], :name[賈寶玉], :book[石頭記]	Les points d’emphase (着重号), le trait des noms propres (专名号) et la marque de titre d’ouvrage (书名号 : 《》 ou une ligne ondulée, selon cjk.bookTitleMark). Le texte reste tel qu’il est écrit ; voir Marques chinoises, ruby et warichu.
Ruby	:ruby[紅樓]{rt="hóng lóu"} ou {紅樓|hóng|lóu}	Lectures en pinyin ou en zhuyin au-dessus (ou à côté) des caractères de base. La forme compacte exige une base en caractères han, en kana ou en bopomofo, si bien que {x|x>0} reste du texte.
Warichu	:warichu[note]{open="〔" close="〕"}	Une note composée sur deux rangées à demi-taille à l’intérieur de la ligne (双行夹注), coupée d’une ligne et d’une page à l’autre.
Code en ligne	code	Les accents graves sont retirés ; le passage est rendu en texte brut, exactement comme il est écrit : un , une pastille, une formule, un lien ou un marqueur d’emphase qu’il contient s’imprime littéralement, ce qui permet à un texte de montrer la syntaxe. Il est composé dans le caractère du texte ou, avec codeStyle.inline, dans le caractère du code, comme une seule unité (voir Configuration › Listings de code). Un listing se place dans un bloc de code.
Échappement	, , , , ,	Une barre oblique inverse compose le caractère marqueur lui-même (l’astérisque d’une note de tableau, , un accent circonflexe littéral, un signe dollar qui n’ouvre aucune formule) au lieu d’ouvrir un passage. Fonctionne dans le corps du texte, dans les pastilles ainsi que dans les légendes, les cellules et les notes. (Jusqu’à postext 1.4, les légendes, les cellules, les notes et les pastilles imprimaient la barre oblique inverse de .)
Espace insécable	le caractère lui-même : U+00A0, U+202F, U+2007	Lie les mots de part et d’autre, si bien qu’une ligne n’est jamais coupée entre eux : un nombre et son unité (37 °C), un renvoi de page (p. 12), une tranche de milliers (225 000). L’espace insécable (U+00A0), l’espace fine insécable (U+202F) et l’espace tabulaire (U+2007) lient toutes les trois (dans le corps du texte, les légendes, les cellules, les encadrés et les titres courants) et chacune garde sa propre largeur : la justification n’étire que les espaces entre les mots. Beaucoup de caractères n’ont pas de glyphe pour l’espace fine insécable ou pour l’espace tabulaire ; elles sont alors composées comme les navigateurs les composent, dans le canvas, le HTML et le PDF à l’identique : une demi-espace de mot et la largeur d’un chiffre. Pratiquement tous les caractères ont U+00A0, c’est donc le choix sûr. Un groupe ainsi lié qui est plus large que la ligne entière est coupé à sa dernière espace insécable plutôt qu’à l’intérieur d’un mot. Le gluon de mots (U+2060) lie sans occuper de place. Tapez le caractère lui-même : une entité HTML comme s’imprime telle qu’elle est écrite. Voir Là où une ligne n’est jamais coupée.
Trait d’union conditionnel	le caractère lui-même : U+00AD	Un endroit où le mot peut être divisé, avec un trait d’union ajouté si une ligne s’y termine : seulement entre deux lettres ou deux chiffres. Un mot qui en porte un ne reçoit aucune autre coupure du dictionnaire, si bien que le trait d’union conditionnel est sa seule division ; tapé avant la première lettre d’un mot, il ne divise rien et garde cette occurrence entière. À côté d’une parenthèse, d’un guillemet ou d’une ponctuation, il n’a aucun effet. Voir Là où une ligne n’est jamais coupée.
Lien	text	Le texte visible reste dans le flux, composé exactement comme sans le lien. L’URL fait des mots un lien actif dans les sorties HTML et PDF ; voir Liens.
Image		Le Markdown d’image en ligne est supprimé du texte. Les images doivent être déclarées dans PostextContent.resources pour que le moteur de mise en page puisse les placer selon les règles de resourcePlacement.
Pastille	:chip[text]	Un passage de texte encadré qui passe à la ligne comme une seule unité : une banque de mots, une touche, une étiquette. Mis en forme par chipStyles ; voir Pastilles en ligne.
Tabulation	:tab, :tab{at=120mm align=end leader="."}	Envoie les mots qui la suivent au taquet de tabulation suivant : l’un des taquets du style du paragraphe, ou celui que fixent ses attributs. Un caractère de tabulation tapé dans le texte n’est une tabulation que là où le style définit des taquets. Voir Tabulations et taquets.
Formule en ligne	$…$	Une formule LaTeX qui suit le flux du texte environnant, par exemple $e^+1=0$. Composée par MathJax et rendue en tracés vectoriels sur tous les moteurs de rendu. Utilisez \$ pour un signe dollar littéral. La mise à l’échelle, la forme en display ($$ … $$) et le traitement des erreurs sont décrits dans Formules mathématiques.

#Liens

Un lien Markdown, [text](url), garde son texte dans le flux exactement comme le texte serait composé sans lui : le lien ne change jamais les sauts de ligne, l’espacement ni la couleur. Il conserve son URL pour les sorties qui peuvent la suivre :

• HTML (renderToHtml) : les mots liés sont enveloppés dans <a href="…" rel="noopener noreferrer">, qui prend la couleur du texte et n’est pas souligné. Il y a une ancre par suite de mots liés sur une ligne.
• PDF (postext-pdf) : chaque suite de mots liés sur une ligne devient une annotation de lien URI cliquable. Dans un PDF balisé, c’est un élément Link dont le texte est celui des mots liés.
• Canvas : peint comme du texte brut, puisqu’un canvas n’a pas de surface cliquable.

Read the [configuration guide](https://postext.dev/en/docs/configuration "Configuration")
or write to [the team](mailto:team@example.com).

• La destination peut porter un titre, qui est ignoré ([text](https://example.com "Title")). Elle peut aussi être placée entre chevrons, où les espaces deviennent %20 ([text](<https://example.com/a b>)).
• Seules les cibles sûres sont conservées : http:, https:, mailto:, tel:, ftp: et les URL relatives (../guide, #top). Tout autre schéma (javascript:, data:, file:…) compose le texte sans lien. Le PDF ne lie que les URL absolues.
• La destination peut contenir des parenthèses tant qu’elles sont équilibrées, comme en CommonMark : [photo](https://commons.wikimedia.org/wiki/File:Bike_(Unsplash).jpg) lie l’URL entière. Une barre oblique inverse échappe un caractère (\(, \_). Quand les parenthèses ne sont pas équilibrées, la destination s’arrête à sa première ) et le texte est composé sans lien ; encodez une parenthèse isolée en %28 ou %29. Une espace termine aussi la destination, sauf si celle-ci est placée entre chevrons.
• Un mot collé au texte du lien partage le lien. Dans see [the site](https://example.com)., le point final fait partie de la zone cliquable.
• Le texte du lien peut porter une emphase ([**bold** words](…)) et peut se trouver à l’intérieur d’une emphase (**[words](…)**).
• Les liens fonctionnent dans les paragraphes, les éléments de liste, les citations, les encadrés, les légendes, les notes et les cellules de tableau, ainsi que dans les titres tant que headings.inlineMarks est activé (par défaut). Les titres courants, le plan et les lignes de la table des matières tirés d’un titre ne gardent que le texte, de même que le texte d’un :chip[…].
• Les liens par référence ([text][id]) et les liens automatiques (<https://…>) ne sont pas reconnus (voir Ce qui n’est PAS pris en charge).

Dans le VDT, la cible se trouve sur chaque segment lié, sous la forme VDTLineSegment.href. L’analyseur conserve les liens d’un passage comme des plages de son texte, dans InlineSpan.links, et ne scinde jamais un passage à cause d’un lien : c’est pourquoi un lien ne peut pas modifier la mise en page.

#Pastilles en ligne

:chip[text] compose text dans une boîte (une « pastille » arrondie et teintée) qui suit le flux de la ligne : les mots d’une banque de mots ou d’un exercice de classement, les touches du clavier, les étiquettes. :chip[text]{style="key"} choisit un style nommé dans chipStyles (voir la référence de configuration) ; sans style, ou avec un identifiant qu’aucun style ne déclare, la pastille prend le premier style (un style chip intégré quand la configuration n’en a aucun ; le Sandbox signale un identifiant inconnu).

Classify: :chip[battery] :chip[cable] :chip[switch] :chip[bulb]
 
Press :chip[Ctrl]{style="key"} + :chip[C]{style="key"} to copy.

• Une seule unité. Une pastille n’est jamais coupée ni divisée par une césure à l’intérieur ; la ligne est coupée entre les pastilles, aux espaces qui les entourent. Une pastille plus large que la ligne entière déborde plutôt que de se scinder.
• Largeur. Sa chasse est celle du texte plus la marge intérieure horizontale et le contour des deux côtés. La justification n’étire que les espaces entre les mots, jamais l’intérieur d’une pastille. Le gap du style est l’espace minimal conservé entre la boîte et un mot ou une pastille voisins de l’autre côté d’une espace ; une espace plus étroite est complétée (pas en bord de ligne, ni contre une ponctuation collée comme :chip[a],).
• Hauteur. La boîte est une bande autour de la ligne de base, 0,8 em au-dessus et 0,25 em en dessous à la taille de la pastille, agrandie de la marge intérieure verticale et du contour. La marge intérieure verticale est peinte hors de la boîte de ligne et ne change jamais la hauteur de ligne, si bien que la grille de ligne de base tient ; une boîte plus haute que le pas de ligne peut empiéter sur une pastille de la ligne au-dessus ou en dessous, et le Sandbox signale deux pastilles de lignes différentes qui se chevauchent (« Chips touch the next line ») pour que vous puissiez réduire la marge intérieure, le contour ou la taille.
• Texte. Le texte de la pastille accepte ses propres marques en ligne (:chip[**bold** word], :chip[x^2^]) et l’emphase qui l’entoure (**:chip[a]**) ; le style peut fixer sa famille, sa taille, sa couleur, le gras et l’italique. Écrivez \] pour un crochet littéral à l’intérieur. Les renvois, les pastilles de couleur et les formules à l’intérieur d’une pastille restent littéraux, et \$ imprime un signe dollar (jusqu’à postext 1.4, il imprimait aussi la barre oblique inverse).
• Vide. Une pastille composée seulement d’espaces (:chip[ ], espaces insécables comprises) est une boîte vide (un blanc à remplir, une marque de fin) : aussi large que la marge intérieure horizontale et le contour de son style, aussi haute qu’une pastille contenant des mots. Dimensionnez le blanc avec le paddingX d’un style (:chip[ ]{style="blank"}). Sans rien du tout entre les crochets, :chip[] reste du texte littéral.
• Où. Paragraphes, éléments de liste, citations, encadrés, cellules de tableau, légendes et notes. Les titres gardent :chip[…] comme texte littéral.
• Sortie. Le canvas, le HTML et le PDF peignent la boîte et composent les mots comme du vrai texte : sélectionnable dans le HTML, extractible et dans l’ordre de lecture dans le PDF (dans un PDF balisé, la boîte est un artefact de mise en page et les mots appartiennent au paragraphe).

#Petites capitales

:smallcaps[text] compose text en petites capitales : les noms des personnages d’une pièce de théâtre, un sigle dans le texte courant, les premiers mots d’un chapitre. Les minuscules sont composées en capitales à 70 % de la taille du texte, tandis que les capitales, les chiffres et la ponctuation gardent la taille entière, si bien que :smallcaps[Hamlet] imprime un H en pleine taille suivi de AMLET en petites capitales.

Enter :smallcaps[Hamlet] and :smallcaps[Horatio], reading.
 
The :smallcaps[unesco] report and the :smallcaps[who] guidelines.

• Synthétisées. Les petites capitales sont dessinées à partir des capitales du caractère lui-même, de la même façon dans le canvas, dans le HTML et dans le PDF, si bien que le texte se mesure et se coupe à l’identique partout. Les vraies petites capitales d’un caractère (la fonctionnalité OpenType smcp) ne sont pas utilisées ; pour les obtenir, composez le texte dans une famille de petites capitales (une famille dont le nom se termine par « SC », par exemple) au moyen d’un style de paragraphe.
• Marques. Le texte accepte ses propres marques en ligne (:smallcaps[**Ophelia**]) et l’emphase qui l’entoure (*:smallcaps[Act I]*) ; écrivez \] pour un crochet littéral à l’intérieur. Un renvoi ou une pastille à l’intérieur est aussi composé en petites capitales, et un renvoi reste un seul lien dans le HTML et le PDF ; une formule, non.
• Coupure. Les mots passent à la ligne et reçoivent la césure comme d’habitude ; la césure lit chaque mot dans sa propre casse.
• Où. Paragraphes, éléments de liste, citations, encadrés, cellules de tableau, légendes et notes, ainsi que les titres tant que headings.inlineMarks est activé (par défaut) ; désactivé, le balisage est retiré du titre et le texte s’imprime tel qu’il est écrit.
• Paragraphes entiers. Un style de paragraphe ou le corps d’un encadré avec smallCaps: true compose tout son texte de cette façon (voir Styles de paragraphe).
• Texte. Le canvas, le HTML et le PDF portent les lettres telles qu’elles sont peintes : copier :smallcaps[Hamlet] donne « HAMLET ».

#Tabulations et taquets

Une tabulation envoie les mots qui la suivent à un taquet de la ligne : le prix d’un plat aligné sur la fin de la justification derrière une ligne de points, l’acteur après le rôle dans une distribution, le barème d’une question d’examen dans la marge. Écrivez :tab là où va la tabulation ; les espaces qui l’entourent y sont absorbées. Les taquets se définissent dans la configuration : bodyText.tabStops pour chaque paragraphe, élément de liste et citation, le tabStops d’un style de paragraphe pour les paragraphes d’un groupe :::paragraphs, et le body.tabStops d’un style d’encadré dans ses boîtes (voir Configuration › Taquets de tabulation). Un menu dont les prix s’alignent sur la fin de la justification, derrière des points :

paragraphStyles: [
  { id: 'menu', firstLineIndent: { value: 0, unit: 'em' }, tabStops: [{ position: 'end', align: 'end', leader: '. ' }] },
],

:::paragraphs{style="menu"}
Onion soup :tab 8.50
 
Grilled sea bream with fennel and lemon :tab 21.00
:::

:tab{…} définit un taquet pour cette seule tabulation, sans style : le blanc d’un formulaire jusqu’à la fin de la ligne, un montant aligné sur sa virgule décimale.

Name and surname :tab{at=end leader=rule}
 
Total due :tab{at=80% align=decimal} 1,234.50

• Où va une tabulation. Au premier taquet situé au-delà du texte qui la précède, parmi les taquets qui suivent celui qu’a pris la tabulation précédente de la ligne, si bien que la deuxième tabulation d’une ligne prend en général le deuxième taquet. Au-delà du dernier taquet, tabInterval ajoute des taquets à chaque intervalle depuis le début de la justification ; sans lui, la tabulation est une espace de mot.
• Caractères de tabulation. Une tabulation tapée dans le texte (U+0009) n’est une tabulation que dans un paragraphe dont le style définit tabStops ou tabInterval. Partout ailleurs, c’est l’espace de mot qu’elle a toujours été, si bien qu’un document écrit avec des tabulations en guise d’espaces conserve sa mise en page. Plusieurs caractères de tabulation à la suite avancent d’autant de taquets. Une tabulation en début de ligne source est supprimée avec les autres blancs de tête de la ligne : écrivez :tab pour commencer une ligne à un taquet.
• Ce qui reste du texte. Un :tab suivi d’une lettre (3:table), et un :tab dans du code en ligne, dans une formule, dans l’adresse d’un lien ou dans les attributs d’une directive.
• Où. Paragraphes, éléments de liste, citations, encadrés et groupes :::paragraphs. Les titres, les légendes, les cellules de tableau et le texte des maquettes (ouvertures, titres courants) n’ont pas de taquets.
• Texte au-delà du taquet. Quand le texte qui précède une tabulation a déjà dépassé tous les taquets restants de sa ligne, un taquet end, center ou decimal emmène le dernier mot avant la tabulation à la ligne suivante avec le texte au taquet, et le texte qui le précède est composé plus étroit, comme une ligne de la table des matières fait passer son titre à la ligne pour garder le numéro de page. Un taquet start coupe la ligne avant la tabulation, et le texte qui la suit commence la ligne suivante à son taquet. Une tabulation qui ouvre sa ligne et ne trouve toujours pas de taquet n’occupe aucune place.
• Points de conduite. Les points de conduite remplissent l’espace qui précède leur taquet et se terminent alignés sur la fin de cet espace, si bien que les points de plusieurs lignes s’alignent quel que soit le texte qui les précède. gap les tient à l’écart du texte des deux côtés ; il n’y a pas d’écart avant eux quand la tabulation ouvre la ligne, ni après eux quand rien ne suit. Les points de conduite sont composés à partir de trois répétitions ; un espace qui n’en contient qu’une ou deux est laissé vide, comme dans la table des matières.
• Coupure des lignes. Un paragraphe qui contient une tabulation est composé ligne par ligne, jamais avec Knuth–Plass. Dans un texte justifié, seules les espaces de mot qui suivent la dernière tabulation d’une ligne absorbent le jeu, et la dernière ligne du paragraphe n’est pas étirée (voir Justification › Lignes tabulées). Un paragraphe centré ou aligné à droite compose ses lignes tabulées depuis le côté de début, puisque les taquets sont des positions sur la justification. De droite à gauche, les taquets se mesurent depuis la droite et un taquet end se place à gauche (voir Mise en page arabe). Dans le texte vertical, une tabulation est une espace de mot, et un :tab y déclenche l’avertissement de contenu tabInVerticalText.
• Texte et sorties. Le texte brut contient un caractère de tabulation (\t) à chaque tabulation ; les points de conduite ne sont pas du texte, et les copies, les recherches et la table de correspondance des sources les laissent de côté. Le canvas, la visionneuse HTML et l’EPUB à mise en page fixe les peignent (masqués aux lecteurs d’écran dans le HTML) ; un PDF balisé les marque comme artefacts, si bien que son texte se lit Onion soup 8.50. L’EPUB recomposable ne peut pas conserver les taquets exactement : chaque ligne d’un paragraphe tabulé devient une rangée des parties comprises entre ses tabulations, où un taquet end, center ou decimal, ou un taquet avec points de conduite, repousse la partie suivante à la fin de la rangée (ses points de conduite devenant une bordure pointillée ou pleine), et un taquet start garde la partie qui le précède à sa largeur imprimée. Un export Word écrit :tab sous forme de tabulation Word, et l’import Word relit une tabulation du corps du texte comme un :tab avec le taquet que Word lui a attribué (voir Sandbox › Documents Word).

#Orientation dans le texte vertical

Dans le texte vertical (layout.writingMode: 'vertical-rl'), les caractères chinois sont debout, les mots latins et les nombres longs sont pivotés sur le côté, et un nombre d’au plus deux chiffres se tient debout dans une seule cellule, sauf s’il se trouve dans une phrase latine, dont il suit alors les mots (voir Configuration › Nombres dans le texte vertical). Trois marques permettent de distinguer un passage à la main :

第:tcy[120]回，:upright[GDP]增長:sideways[12]倍。

• :tcy[…] (tate-chu-yoko, 縱中橫) compose son texte côte à côte dans une seule cellule debout d’un em, resserrée en largeur quand elle est plus large : :tcy[120], :tcy[3.0], :tcy[A+]. Jusqu’à environ quatre caractères se lisent bien.
• :upright[…] place chaque caractère debout dans sa propre cellule, les lettres latines centrées dedans : un sigle lu lettre par lettre le long de la colonne. Une ligne n’est jamais coupée à l’intérieur.
• :sideways[…] fait pivoter tout le passage avec la ligne, caractères chinois compris : un nombre de deux chiffres que l’auteur veut voir couché.
• Le texte reste dans le texte brut ; les marques acceptent à l’intérieur d’autres marques en ligne (:tcy[**12**]), un lien (:sideways[[iPhone](https://…)]) et les unes les autres, la plus intérieure l’emportant (:tcy[:upright[AB]] met A et B debout), et \] s’écrit pour un crochet littéral. Dans le texte horizontal, elles ne changent rien.
• Un renvoi, un appel de note, une formule, une pastille ou une pastille de couleur à l’intérieur d’une marque garde sa propre composition : :sideways[iPhone[^1]] fait pivoter iPhone et laisse le numéro de note composé comme tous les numéros de note ; le numéro d’un renvoi se tient debout dans une cellule selon cjk.uprightDigits, comme tout nombre court.
• Un élément de texte de maquette avec inlineMarks: true les accepte aussi quand il est composé verticalement (voir Configuration › Éléments de texte vertical).
• Pour la coupure et la justification, une cellule :tcy et chaque caractère :upright comptent comme des caractères chinois, et aucune espace han–latin n’est placée à côté d’eux.

#Marques chinoises, ruby et warichu

Les éditions chinoises et japonaises marquent le texte dans l’interligne plutôt qu’avec l’italique ou le soulignement, glosent les caractères avec leur lecture et placent le commentaire à l’intérieur de la ligne. Sept directives s’en chargent. Mise en page chinoise et Mise en page japonaise expliquent les conventions sur lesquelles elles reposent. Elles conservent leur texte : les caractères entre les crochets restent dans le paragraphe (la recherche, la table des matières, les ancres d’index et le texte copié les lisent tels qu’ils sont écrits), et les directives acceptent les autres marques en ligne à l’intérieur et autour d’elles, y compris imbriquées. Écrivez \] pour un crochet littéral.

此事:dots[不可]輕忽。:name[賈寶玉]與:name[林黛玉]讀:book[西廂記]。
 
{滿紙|mǎn|zhǐ}荒唐言，:ruby[一把]{rt="yì bǎ"}辛酸淚！:ruby[都]{rt="ㄉㄡ"}云作者痴。
 
寶玉:warichu[甲戌側批：此是第一首標題詩。]{open="〔" close="〕"}道：……
 
{東京|とう|きょう}の:ruby[紫陽花]{rt="あじさい"}は*とんと*:sideline[見事]だ。:book[こころ]を読む。
 
:kunten[學]{okuri="ビテ"}而:kunten[時]{okuri="ニ"}:kunten[習]{kaeri="二" okuri="フ"}:kunten[之]{kaeri="一" okuri="ヲ"}。

• :dots[text] place un point d’emphase (着重号) sous chaque caractère dans le texte horizontal, à sa droite dans le texte vertical, et aucun sur la ponctuation ni sur les espaces. style="dot|circle|sesame" (par défaut dot), fill="open" pour un contour, pos="over|under" pour l’autre côté. L’emphase Markdown *…* sur des caractères chinois ou japonais fait de même avec cjk.emphasis: 'dots', la valeur par défaut dans un document chinois ou japonais ; les lettres latines de la même emphase restent en italique. Les attributs omis prennent cjk.emphasisMark : un point sous le texte en chinois, un sésame au-dessus (à sa droite dans le texte vertical) en japonais.
• :name[text] trace le trait des noms propres (专名号) sous le texte (à sa gauche dans le texte vertical), et :book[text] la marque de titre d’ouvrage (书名号) : 《》 autour du titre (〈〉 pour un titre à l’intérieur d’un autre), la ligne ondulée des éditions classiques et taïwanaises, ou rien, selon cjk.bookTitleMark (par défaut des crochets en Chine continentale et au Japon, la ligne ondulée à Taïwan et à Hong Kong). Dans un document japonais, les crochets sont 『』, et 「」 pour un titre à l’intérieur d’un autre (cjk.bookTitleBrackets). Une même source sert une édition moderne de Chine continentale et une édition classique. Deux noms ou titres côte à côte gardent leurs traits séparés.
• :ruby[base]{rt="…"} compose les lectures au-dessus de la base (pinyin), ou à droite de chaque caractère (zhuyin, la valeur par défaut pour les lectures en bopomofo). Avec autant de lectures que de caractères, séparées par des espaces ou par |, chaque caractère reçoit la sienne et une ligne peut être coupée entre eux (mono ruby) ; group, ou un nombre qui ne correspond pas, compose une seule lecture centrée sur toute la base, qui n’est jamais coupée. pos="over|under|right" choisit le côté. La forme compacte {紅樓|hóng|lóu} (une lecture par |) ou {紅樓|hónglóu} (une lecture pour toute la base) se lit de la même façon, seulement quand la base contient un caractère han, kana ou bopomofo, en dehors des formules, du code et des attributs, si bien que {x|x>0} dans une prose latine reste du texte. Une barre oblique inverse devant l’accolade ou la barre verticale garde une forme chinoise comme texte : \{紅|hóng} et {紅\|hóng} impriment {紅|hóng}. Une base qui ouvre ou ferme une ligne s’aligne sur ce bord avec sa lecture. mode=mono|group|jukugo choisit la façon dont les lectures se placent sur la base (mode=group équivaut à group), et align=center|jis|start la façon dont est espacée une lecture plus courte que sa base. Dans un document japonais, la forme par caractère d’un mot de deux caractères ou plus ({東京|とう|きょう}, rt="とう|きょう") est un ruby jukugo : chaque caractère garde sa lecture, qui peut déborder sur le caractère suivant du mot, la ligne peut être coupée entre eux, et les lectures sont espacées et débordent sur les kana selon cjk.ruby.align et cjk.ruby.overhang ; une seule lecture pour toute la base ({紫陽花|あじさい}, le 《》 d’Aozora) est un ruby de groupe ; mode=mono garde une lecture par caractère sans débordement sur les voisins.
• :sideline[text] trace un trait latéral (傍線) à côté du texte, ponctuation et espaces compris : en dessous dans le texte horizontal et à droite dans le texte vertical. style="solid|double|wavy|dotted" (par défaut solid), pos="over|under" (dans le texte vertical, over correspond à la droite et under à la gauche ; position= fonctionne aussi). Il fonctionne dans toutes les écritures, y compris pour une expression anglaise soulignée.
• :warichu[note] compose une note (双行夹注) sur deux rangées à la moitié de la taille du texte à l’intérieur de la ligne, la rangée supérieure se lisant en premier (celle de droite dans le texte vertical). Une note longue remplit ce qui reste de la ligne et se poursuit sur la ligne, la colonne ou la page suivante, avec au moins deux de ses caractères de chaque côté de la coupure (cjk.warichu.minChars). open et close l’encadrent de crochets à la taille du texte ; cjk.warichu fixe la taille, la couleur et les crochets par défaut (（） dans un document japonais). Une note en écriture latine est coupée entre ses mots.
• :kunten[字]{kaeri="…" okuri="…" tate} compose les marques kanbun du dernier caractère entre les crochets : kaeri la marque de retour (レ, 一 二 三, 上 中 下, 甲 乙 丙, 天 地 人, et 一レ 上レ 甲レ 天レ ; les points de code ㆑ ㆒ … se lisent de la même façon), okuri les okurigana (les parenthèses d’Aozora （ヲ） sont supprimées), et l’indicateur tate le tatesen qui le relie au caractère suivant. Le texte n’est pas réordonné : les marques sont composées à demi-taille à côté de lui (cjk.kunten), et le texte copié se lit 學ビテ而時ニ習フ之ヲ, avec les okurigana et sans les marques de retour. Un ruby à l’intérieur convient aux caractères lus deux fois : :kunten[:ruby[未]{rt="ザル" pos=under}]{kaeri="レ" okuri="ダ"}.

Le pas de ligne ne change jamais : les marques et les lectures se logent dans l’interlignage, et la composition émet un avertissement quand l’interligne d’un paragraphe est trop étroit pour elles (cjkMarksExceedLeading, rubyExceedsLeading, kuntenExceedsLeading), et quand les marques sous une ligne et les lectures au-dessus de la suivante ne tiennent pas dans l’interligne qu’elles partagent, dans un même paragraphe ou entre deux paragraphes. Donnez aux paragraphes annotés un style de paragraphe avec un interlignage plus grand. Les marques, les lectures et les notes sont dessinées dans les paragraphes, les titres, les éléments de liste, les citations et les encadrés, ainsi que dans les légendes, les cellules de tableau et les notes, dont l’interlignage est vérifié de la même façon ; dans les titres courants et les maquettes, le texte s’imprime sans elles. Avec cjk.bookTitleMark: 'brackets', les 《》 d’un titre sont une ponctuation du texte : les légendes, les cellules, les notes, les lignes de la table des matières, les signets et les entrées d’index les conservent. Voir Configuration › Marques, ruby et warichu.

#Sens du texte dans le balisage

Un document s’écrit dans le sens qu’implique sa locale (direction dans la configuration : de droite à gauche pour l’arabe, le persan, l’ourdou ou l’hébreu). À l’intérieur, le balisage fixe le sens d’un bloc ou d’un passage de texte, pour une citation anglaise dans un livre arabe ou une citation arabe dans un livre anglais.

• Un titre ou un conteneur : {dir=ltr} ou {dir=rtl} dans ses attributs, # Introduction {dir=ltr}, :::paragraphs{dir=ltr}, :::callout{dir=rtl}. Chaque bloc à l’intérieur d’un conteneur prend ce sens, jusqu’à un conteneur imbriqué ou un titre qui en fixe un autre. Un paragraphe simple, une liste ou une citation n’a pas d’attributs propres : enveloppez-le dans :::paragraphs{dir=…}. Les autres valeurs sont ignorées. Le lang d’un conteneur (:::paragraphs{dir=ltr lang=en}) nomme de la même façon la langue des blocs qu’il contient : leurs listes ordonnées sont numérotées avec les chiffres de cette langue.
• Un passage de texte : :ltr[…] et :rtl[…] isolent leur texte (les LRI…PDI et RLI…PDI de l’algorithme bidirectionnel Unicode) : il est ordonné à l’intérieur, et le paragraphe qui l’entoure n’y voit qu’un caractère neutre. {lang=…} indique la langue du passage dans le HTML et le PDF. Un appel de note, un :ref ou une formule à l’intérieur fait partie de l’isolat, et les isolats s’imbriquent.

:::paragraphs{dir=ltr}
The opening of the *Nights* in Lane's translation.
:::
 
ترجمها :ltr[Edward William Lane]{lang=en} سنة ١٨٣٩.

Un bloc composé à l’inverse du sens du document garde son propre côté de début : son retrait, ses marqueurs de liste et la fin alignée de sa dernière ligne passent du côté où commence son texte. Utilisez un isolat quand un titre latin se termine par un caractère neutre (un point, une parenthèse) qui sinon se joindrait à l’arabe qui l’entoure. Les caractères de contrôle Unicode eux-mêmes (U+2066–2069, U+202A–202E, U+200E, U+200F, U+061C) sont aussi respectés. Dans l’éditeur du Sandbox, chaque ligne s’écrit dans le sens de sa première lettre. Voir Mise en page arabe.

#Notes de bas de page

Une note de bas de page a deux parties : l’appel [^id] là où la note est citée, et la définition, un paragraphe à part qui commence par [^id]: n’importe où dans le chapitre.

The keeper climbed the tower every evening.[^steps] The wind put out his candle,
so he learned to count the steps in the dark.
 
[^steps]: The cast-iron staircase has 112 steps; the tower was built in 1861.

• Appel. [^id] imprime le numéro de la note en exposant, collé au mot qui le précède (écrivez-le après la ponctuation, comme ci-dessus). L’identifiant accepte les lettres, les chiffres, -, _, . et :. L’appel fonctionne dans les paragraphes, les éléments de liste, les citations et les encadrés ; dans les titres, les légendes et les cellules de tableau, il s’imprime tel qu’il est écrit.
• Définition. Un paragraphe qui commence par [^id]: ; son texte court jusqu’à la ligne vide suivante et accepte les marques en ligne habituelles (gras, italique, liens, :ref, formules, pastilles). Les définitions sortent du flux où qu’elles soient écrites : elles peuvent donc se trouver sous le paragraphe qui les cite ou toutes ensemble à la fin du chapitre. La première définition d’un identifiant l’emporte.
• Numéros. Les notes sont numérotées dans l’ordre de leur première citation, en recommençant à chaque chapitre (un titre de niveau 1, et chaque document d’un livre) ; une note citée deux fois garde son premier numéro et n’est composée qu’une fois. footnotes.numbering: 'document' continue la numérotation dans tout le livre, et 'page' la recommence à chaque page, comme le font les livres chinois ; footnotes.numberFormat: 'circled-decimal' écrit ① ② ③ sur la ligne de base. footnotes.numberFormat: 'symbols' les marque *, †, ‡, §, ‖, ¶, puis doublés, en recommençant à chaque page, comme le font les revues.
• Texte japonais. Écrivez l’appel avant un 。 de fin de phrase (先生[^1]。) : il reste avec le caractère qui le précède, et 。 n’ouvre jamais une ligne. Un livre japonais vertical compose par défaut ses appels （1） à droite de la ligne et ses notes après le chapitre ; footnotes.markerPosition: 'side' place un petit appel à côté du mot, sans prendre de place dans la ligne, et footnotes.placement: 'spread' compose les notes à côté du texte de chaque double page (voir Configuration › Notes de bas de page).
• Où va la note. Par défaut, au pied de la colonne qui contient la ligne qui la cite, sous un court filet : la ligne et sa note partagent toujours une colonne, et une ligne dont la note ne tient pas passe plus loin avec elle. Dans une mise en page à une colonne, c’est le pied de la page. footnotes.placement: 'chapterEnd' compose plutôt toutes les notes d’un chapitre après son dernier bloc, par défaut au pied de la colonne qu’elles terminent. Voir Notes de bas de page dans la référence de configuration pour les tailles, le filet et l’espacement.
• Vérifications. Un appel sans définition (undefinedFootnote) imprime son numéro au-dessus d’une note vide ; une définition qu’aucun appel ne cite (unusedFootnote) n’est pas composée. Le Sandbox liste les deux dans le panneau Vérifications.

#Renvois et ancres

Un renvoi désigne un endroit du livre et imprime son numéro, son titre ou sa page : voir la section 3.2, comme l’explique le chapitre 4, à la p. 112. Les mots et les numéros suivent le texte : déplacer une section, renuméroter les chapitres ou recomposer le livre met à jour tous les renvois. Dans le PDF, le HTML et les aperçus du Sandbox, chaque renvoi est un lien : un clic mène le lecteur à sa cible, y compris dans un autre chapitre.

Ancres. Un renvoi a besoin d’une cible :

• Un titre avec un identifiant : ## Method {#sec-method} (la forme de Pandoc ; id="sec-method" fonctionne aussi).
• Un encadré ou un autre conteneur ouvert avec un identifiant : :::callout{#box-safety title="Safety"}. Un encadré d’un style numéroté (un théorème) est désigné par son libellé et son numéro : Théorème 2.
• Une formule en display avec un \label{eq:x} (voir Formules mathématiques) : un renvoi imprime son numéro comme le fait la formule, (3).
• Un point du texte : :anchor{#key-idea} pose une ancre invisible ; [the key idea]{#key-idea} garde ses mots et leur donne un nom.

Un identifiant accepte les lettres, les chiffres, -, _, . et :. Il doit être unique dans le livre : le panneau Vérifications liste un identifiant défini deux fois (duplicateAnchor), et les renvois mènent à sa première définition.

Renvois. :ref{id="…"} désigne une ancre de la même façon qu’il désigne une figure ou un tableau :

## Method {#sec-method}
 
The results of :ref{id="sec-method"} hold on :ref{id="sec-method" style=page}.

Les commandes LaTeX \eqref{x} et \ref{x} fonctionnent aussi dans le texte : \eqref comme un renvoi sans style, \ref comme style=number, si bien que \ref{thm:main} imprime 2 et \ref{fig:map} le numéro d’une figure. Un ~ placé juste avant est une espace insécable (Theorem~\ref{thm:main}). À l’intérieur de $…$, elles appartiennent à la formule.

text="…" imprime vos propres mots et reste un lien ; case=capitalize commence le libellé par une capitale (Section 3.2 en début de phrase). Les mots suivent la langue du document (sección 3.2, 第3.2节, S. 112) et peuvent être modifiés dans Renvois dans la configuration ; un numéro de titre que son modèle écrit déjà en toutes lettres (Chapitre 4, 第四章) s’imprime tel quel.

Sauts de ligne. Un renvoi qui imprime des mots est coupé à ses espaces comme le texte qui l’entoure : le texte d’une ancre ([close the lever so that it points backwards]{#step}), un titre, votre propre text="…". Ses espaces sont des espaces de la ligne : sur une ligne justifiée, elles s’étirent avec les autres, et le renvoi reste un seul lien, en deux morceaux quand il court sur deux lignes. Ses mots ne reçoivent jamais de césure. Dans un tel libellé, un nombre, un chiffre romain ou une lettre seule reste avec le mot qui le précède, si bien que text="Fig. 1a" ou text="plate IV" n’est jamais séparé. Un libellé qui porte un numéro ou une page (section 3.2, p. 112, Fig. 1.7, Théorème 2) n’est jamais coupé, quelle que soit l’espace que contient son modèle, et une espace insécable dans un libellé lie comme partout ailleurs. crossRefs.breakLabels: false garde chaque libellé entier, comme jusqu’à postext 1.27, quand un libellé était un seul mot qui ne pouvait pas remonter sur la ligne précédente ; voir Renvois.

Les renvois de page ne sont connus qu’une fois le livre mis en page. Le moteur remet le document en page avec les pages de la passe précédente jusqu’à ce qu’elles se stabilisent, comme il le fait pour la table des matières ; d’ici là, une page s’imprime ?.

pandoc-crossref. Un texte écrit pour pandoc-crossref se lit de la même façon : @sec:method, [@fig:map], et [-@tbl:data] pour le numéro seul. Le préfixe (sec, fig, tbl, eq, lst) peut faire partie de l’identifiant ({#sec:method}) ou en être omis ({#method}). Un @ collé à un mot, comme dans une adresse électronique, reste du texte.

Un renvoi vers un identifiant que rien ne définit imprime ? et le panneau Vérifications le liste (unknownResourceId). Dans l’éditeur du Sandbox, @ propose les figures, les tableaux, les titres munis d’un identifiant et les ancres du livre.

#Citations et bibliographie

Écrivez les citations comme Pandoc les lit, gardez les références dans le document et choisissez le style de citation dans les réglages : passer d’APA à IEEE, ou aux notes Chicago, change le réglage de style, pas le texte. Chaque citation renvoie par un lien à son entrée dans la bibliographie.

#Citer

As [@garcia2020, p. 33] shows, reading on paper is faster [see @lopez2019, chap. 2; @bringhurst2004].
@garcia2020 [p. 4] says it plainly; the 2020 study [-@garcia2020] agrees.

• [@key] cite entre parenthèses ; plusieurs ouvrages se placent dans une même paire de crochets, séparés par ;.
• Localisateur : après une virgule, p. 33, pp. 4–6, chap. 2, sec. IV, fig. 3, vol. 2, n. 12, l. 4, § 4.2 ; un nombre seul est une page. Les termes espagnols (pág., cap.) et chinois (页, 章) fonctionnent aussi. Un intervalle prend un tiret demi-cadratin ou les deux traits d’union de TeX : pp. 4--6 imprime 4–6.
• Préfixe et suffixe : du texte avant le @ (see) et après la clé ou le localisateur (, emphasis added). Le suffixe garde la virgule écrite devant lui, avec ou sans localisateur : [@brown2020, inter alia] imprime (Brown et al., 2020, inter alia), comme le fait Pandoc ; écrit sans virgule ([@brown2020 inter alia]), il n’en a pas. L’emphase dans un préfixe ou un suffixe est composée en emphase dans tous les styles : [*e.g.*, @brown2020, *inter alia*].
• [-@key] omet l’auteur, pour une phrase qui le nomme déjà.
• @key cite dans la phrase (García (2020)) ; @key [p. 4] ajoute un localisateur.
• Dans les légendes : la légende d’une figure ou d’un tableau, et sa note, citent comme le fait le texte (Prior best from [@cobbe2021].). Leurs ouvrages entrent dans la bibliographie sans nocite, et un style numéroté les numérote là où la ressource est placée : après les citations du paragraphe qui y fait référence en premier (son bloc ::resource ou son premier :ref). Une citation dans une cellule de tableau reste du texte.
• Un @ collé à une lettre ou à un chiffre (une adresse électronique), un @ dans du code en ligne et \@ sont du texte. Une citation pour laquelle le livre n’a pas de référence s’imprime telle qu’elle est écrite, si bien qu’un document sans références se lit comme avant. Dans une citation de plusieurs ouvrages, une clé qu’aucune référence ne définit est imprimée en gras après les autres ((Glen, 1955) **@nye1953**), pour que l’ouvrage manquant apparaisse sur la page autant que parmi les avertissements. Un deux-points après une citation est du texte : [@french2018]: the land….
• Dans un texte chinois, japonais ou coréen, une citation suit le dernier caractère sans espace (周明远@zhou2019认为), et une citation auteur-date prend les signes pleine chasse du texte qui l’entoure : （施雅风等，1988；刘时银等，2015）.

#Références

Les références s’écrivent dans le document, au format CSL (le modèle de données de Zotero et de Pandoc) :

---
references:
  - id: garcia2020
    type: book
    author: [{family: García, given: Ana}]
    title: Tipografía y lectura
    issued: 2020
    publisher: Trea
nocite: "@lopez2019"
---

ou dans un bloc :::references, en BibTeX (un export de Zotero, JabRef ou Google Scholar), en CSL-JSON ou en CSL-YAML :

:::references{format=bibtex}
@article{lopez2019, author = {López, Luis and Ruiz, Eva}, title = {Leer en pantalla},
  journal = {Revista de Letras}, year = 2019, volume = 12, pages = {45--67}, doi = {10.1000/xyz}}
:::

Le bloc n’imprime rien. nocite liste des ouvrages sans les citer (@* : tous). Dans un livre, les références écrites dans n’importe quel chapitre valent pour tout le livre.

Dans une liste de noms BibTeX, and others représente les noms omis (author = {Tan, Wei and others}) : tous les styles impriment et al. à leur place. En YAML, écrivez others comme dernier nom de la liste.

#La bibliographie

:::bibliography compose la liste des ouvrages cités là où il se trouve ; en son absence, la liste suit le dernier chapitre, avec un titre dans la langue du document (References, Referencias, 参考文献). :::bibliography{title="Works cited"} change le titre et title="" le supprime ; scope=chapter liste les ouvrages que cite le chapitre (un ouvrage collectif). Chaque entrée est une ancre (ref-<key>) : un lien Markdown vers #ref-garcia2020 y mène, et le PDF la balise comme BibEntry.

scope=new liste les ouvrages cités jusque-là dans le document qu’aucune liste précédente n’a imprimés, dans l’ordre du style et avec ses numéros : un :::bibliography{scope=new} après le texte principal et un autre après les Methods donnent les deux listes d’un article de Nature, la seconde numérotée à la suite de la première. Un style numéroté compte ses citations sur tout le livre ; avec citations.numbering: 'chapter', chaque chapitre (chaque document, et chaque titre de niveau 1 placé après une citation) numérote les siennes à partir de 1, et sa liste de chapitre reprend ces numéros, comme le font les rapports d’un bulletin ou les communications d’actes de colloque.

#Styles

Le style décide de ce que disent une citation et une entrée. Les styles fournis sont listés ci-dessous ; tout autre style CSL (il y en a plus de dix mille dans le dépôt de styles de Zotero) peut être chargé depuis son fichier .csl dans Réglages → Citations.

Avec un style à notes, chaque citation devient une note de bas de page, placée et numérotée selon les réglages des notes de bas de page ; les citations ultérieures du même ouvrage prennent une forme abrégée. Dans un texte chinois, citations.notes: 'warichu' les compose comme des notes sur deux rangées à l’intérieur de la ligne (夹注) ; une note suivie d’un signe chinois (，, 。) perd son propre point final.

Chinois. Les styles GB/T 7714-2015 écrivent les codes de type de document ([M], [J], [D], [EB/OL]), gardent les noms chinois entiers et écrivent 等 après trois auteurs d’un ouvrage chinois et et al. après ceux d’un ouvrage occidental, en choisissant selon la language de chaque ouvrage. Dans le texte vertical, un numéro en exposant se place à droite de son caractère ; citations.marker: 'corner' écrit 〔1〕, qui reste debout.

Moteur. Les citations sont mises en forme par le paquet postext-citeproc (citeproc-js et les styles CSL). Le Sandbox le charge pour les documents qui citent ; dans votre propre code, enregistrez-le avant la mise en page :

import 'postext-citeproc/register';

Le panneau Vérifications liste une clé qu’aucune référence ne définit (unknownCitationKey) et un bloc de références illisible (referencesUnreadable).

#Index

Un index liste les termes d’un livre avec les pages où ils apparaissent. Marquez chaque terme là où le texte en traite et imprimez l’index avec :::index là où il doit se trouver, en général dans un chapitre à part à la fin. Le moteur trouve la page de chaque marque après la mise en page, si bien que les numéros suivent le texte : ajoutez un paragraphe, déplacez un chapitre ou changez le format, et l’index imprime les nouvelles pages.

Iron-deficiency :index[anaemia] is the most common kind.
The pulse is taken at the wrist.:index{term="Pulse!radial" main}
 
# Index {style="index"}
 
:::index

#Marques d’index

• :index[text] imprime text et le classe sous ses propres mots. Les marques en ligne qu’il contient s’impriment et sont retirées de l’entrée. Des attributs après le crochet le classent ailleurs : :index[iron deficiency]{term="Anaemia!iron-deficiency"}.
• :index{term="…"} n’imprime rien. La marque prend la page du mot écrit juste avant elle sur sa ligne ou, quand elle ouvre une ligne, celle du mot qui la suit. Une ligne qui ne contient que des marques est supprimée : une marque sur une ligne à part ne scinde donc jamais un paragraphe et n’ajoute pas d’espace.
• Où. Paragraphes, titres, éléments de liste, citations, encadrés et définitions de notes de bas de page. Dans les légendes, les cellules de tableau et les éléments de maquette, une marque s’imprime telle qu’elle est écrite. Dans du code en ligne, et après une barre oblique inverse (\:index), c’est du texte.

Une marque sans terme (:index{} ou :index{see="…"} seul) n’indexe rien et déclenche indexMarkInvalid.

#Imprimer l’index

:::index imprime l’index principal là où il se trouve, et :::index{index="names"} un index nommé. La directive se développe en blocs ordinaires, un par entrée, qui suivent le flux des colonnes et des pages comme du texte : sous un titre dont le style de titre définit un layout à deux colonnes, elle donne l’index habituel sur deux colonnes. Un clic sur une entrée mène à la ligne de la directive.

# Index of names {style="index"}
 
:::index{index="names"}
 
# Index of subjects {style="index"}
 
:::index

• Ordre. Les entrées se trient dans l’ordre alphabétique de la langue du document (locale, ou index.locale) : une lettre accentuée se classe avec sa lettre de base (Árbol sous A), et en espagnol ñ vient après n, sous une lettrine de groupe à part. Les entrées qui commencent par un symbole viennent en premier, puis celles qui commencent par un chiffre, puis les lettres. Les sous-entrées se trient de la même façon sous leur entrée, en retrait d’un cran par niveau. Un index japonais trie selon la lecture dans l’ordre de JIS X 4061 et regroupe par rangée du gojūon (あ行, か行…), ses entrées latines avant les kana (voir Mise en page japonaise › Index dans l’ordre du gojūon).
• Groupes. Chaque nouvelle initiale ouvre un groupe : une lettre d’en-tête (index.groups) et une ligne d’espace au-dessus (aucune au-dessus du premier groupe). La lettre d’en-tête est composée en un seul bloc avec la première entrée du groupe, si bien qu’elle ne termine jamais seule une colonne ; une entrée sans page propre (qui ne sert que de tête à ses sous-entrées) est composée avec sa première sous-entrée pour la même raison.
• Numéros de page. Les libellés qu’impriment les pages, y compris les chiffres romains des pages liminaires. Les pages d’une entrée sont triées et chacune n’est listée qu’une fois ; les pages consécutives se regroupent en un intervalle (12–14, index.mergeRanges), une page qui tombe dans un intervalle de la même entrée s’y fond (une page principale à cet endroit met l’intervalle en gras), et index.rangeFormat: 'chicago' abrège le second nombre (234–37). Les pages en gras (principales) restent séparées. Dans le PDF, chaque numéro renvoie par un lien à sa page.
• Les renvois terminent l’entrée : Terme. Voir Cible quand l’entrée n’a pas de pages, Terme, 12. Voir aussi Cible quand elle en a. Les libellés suivent la langue du document (See, Véase…) et peuvent être définis dans index.see.
• Livres. Dans un livre mis en page chapitre par chapitre (le Sandbox, buildBundle), le chapitre qui imprime l’index reçoit les marques de tous les chapitres avec leurs pages, et il n’est remis en page que lorsque l’une d’elles se déplace. Un document qui contient à la fois ses marques et son index est remis en page jusqu’à ce que les numéros se stabilisent, comme avec :::toc.

Voir Index dans la référence de configuration pour la typographie, les retraits et les séparateurs.

#Formules mathématiques

Les formules mathématiques font pleinement partie du format de document. Postext analyse $…$ pour les formules en ligne et $$…$$ pour les formules en display (en bloc), et les rend avec MathJax en mode SVG. Les mêmes tracés vectoriels alimentent les trois moteurs de rendu, si bien que l’aperçu canvas, l’export HTML et la sortie PDF sont identiques au pixel près, et le PDF reste entièrement vectoriel quel que soit le niveau de zoom.

• En ligne : $…$. Reconnue dans tout bloc de texte (paragraphe, titre, citation, élément de liste). Ajoute à la ligne une seule boîte atomique et insécable ; Knuth-Plass la traite comme un mot qui ne doit pas être coupé. Si la hauteur naturelle de la formule devait rompre la boîte de ligne, elle est réduite uniformément pour préserver la grille de ligne de base ; les expressions très hautes relèvent du mode display.
• Display : $$…$$. Soit sur une ligne à part ($$\int_0^1 x^2\,dx$$), soit répartie sur plusieurs lignes entre des marqueurs $$ placés sur leur propre ligne. Rendue centrée sur la colonne et calée sur la grille de ligne de base avec des marges haute et basse configurables (math.marginTop, math.marginBottom) : exactement le même mécanisme de correction que celui des titres, si bien que le paragraphe qui suit la formule retombe sur la grille.
• Texte autour d’une formule en display : une formule en display sur une ligne à part interrompt un paragraphe même sans ligne vide au-dessus. Le texte qui la précède est un paragraphe qui l’introduit ; le texte écrit juste sous le $$ de fermeture, sans ligne vide, continue le paragraphe interrompu et est composé sans retrait de première ligne, comme TeX compose le « où … » qui suit une formule en display. Une formule séparée du texte qui la précède par une ligne vide (ou qui suit une liste, une citation ou un titre) n’interrompt rien : le texte qui la suit est un nouveau paragraphe, en retrait comme d’habitude, avec ou sans ligne vide (math.indentAfterDisplay: false le compose aussi sans retrait). Seule une formule en display entière interrompt un paragraphe : une seule formule sur la ligne, ou une clôture $$ refermée avant la ligne vide suivante ; une ligne comme $$a$$ and $$b$$ reste du texte. math.keepWithLeadIn garde une formule dans la colonne de la ligne qui l’introduit. (Jusqu’à postext 1.4, une ligne $$…$$ sans ligne vide au-dessus était lue comme faisant partie du paragraphe et s’imprimait telle qu’elle était écrite.)
• Numéros d’équation : \label{eq:x} dans une formule en display la numérote, dans l’ordre de lecture : (1), (2)… Une formule numérotée occupe toute la largeur de la colonne (ou la largeur intérieure de l’encadré), l’équation centrée et son numéro aligné à droite sur sa ligne. Dans un align, gather, alignat, flalign ou eqnarray, chaque rangée qui porte un \label reçoit son propre numéro, sauf si la rangée indique \nonumber ou \notag. Une formule sans \label n’est pas numérotée, comme $$…$$ ne l’a jamais été. \tag{…} numérote toujours une formule avec le texte que vous fournissez (\tag*{…} sans les parenthèses) et n’est pas compté ; un \label à côté désigne ce texte. Le format, les numéros de chapitre ou de section (2.3) et les remises à zéro se règlent dans math.equationNumbering. Placez le \label au niveau supérieur de la formule ou de sa rangée : pas à l’intérieur de aligned, split ou cases.
• Renvois aux équations : \eqref{eq:x} dans le texte imprime le numéro comme le fait la formule, (3), et \ref{eq:x} le numéro seul, 3 ; tous deux sont des liens, comme tout renvoi. Eq.~\eqref{eq:x} conserve le ~ comme le fait LaTeX : une espace insécable. :ref{id="eq:x"} et @eq:x impriment aussi (3). À l’intérieur d’une formule, \eqref et \ref impriment le numéro (sans lien). Une étiquette que rien ne définit imprime ? et figure dans le panneau Vérifications.
• Échappement : \$ est un signe dollar littéral. Les délimiteurs $ ou $$ non appariés produisent une entrée unclosedMath dans le panneau Vérifications du Sandbox, avec une ancre vers la source qui y mène d’un clic.
• Légendes, notes et cellules de tableau composent aussi les formules en ligne (depuis postext 1.19), dans la ligne avec le texte et avec l’alignement de la cellule, à la taille de l’extrait. Là, un $ n’ouvre une formule que selon la règle de Pandoc : pas d’espace après le $ ouvrant, pas d’espace avant celui de fermeture et pas de chiffre juste après celui-ci, si bien que les prix de $5 to $10 restent du texte ; \$ imprime un signe dollar, si bien qu’une même chaîne échappée se lit de la même façon dans le texte et dans un tableau. Le libellé d’une pastille n’accepte pas de formule. Jusqu’à postext 1.18, un $ à ces endroits s’imprimait toujours tel quel.
• Erreurs : une source TeX que MathJax rejette (macros non définies, erreurs de syntaxe) remonte sous la forme d’un avertissement invalidMath. La formule est remplacée par un petit espace réservé rouge pour que la géométrie de la mise en page reste valide.
• Configuration : la section math de la configuration expose enabled, fontSizeScale (relatif à la taille du texte environnant : à 1,0, un em de la formule vaut cette taille, soit la taille du texte courant pour les formules en display et pour les formules en ligne dans le texte courant ; depuis postext 1.5, qui compose les formules environ 13 % plus petites que la 1.4, tandis que les paquets et les livres du Sandbox enregistrés par la 1.4 gardent leur taille ; voir Taille des formules), color (hérite de la couleur du texte courant quand elle n’est pas définie) et les marges des formules en display.
• Le moteur : MathJax se charge à la demande. Le Sandbox et le worker de mise en page le démarrent eux-mêmes ; dans votre propre code, appelez await initMathEngine() avant buildDocument, sinon chaque formule est mise en page comme une boîte grise de substitution (voir Démarrer le moteur mathématique).

The Euler identity $e^{i\pi}+1=0$ links the five fundamental constants.
 
$$
\int_0^{\infty} e^{-x^2}\,dx = \frac{\sqrt{\pi}}{2}
$$

Une formule au milieu d’une phrase, et la phrase qui se poursuit après elle sans retrait :

For a pendulum of length $L$ the period is
$$T_0 = 2\pi\sqrt{L/g}$$
where $g$ is the acceleration of free fall.

Des équations numérotées et les renvois qui y mènent :

The energy is conserved,
$$
\begin{align}
E &= T + V \label{eq:energy} \\
  &= \tfrac12 m v^2 + m g h \nonumber
\end{align}
$$
and Eq.~\eqref{eq:energy} holds at every instant.

Théorèmes, lemmes et démonstrations. Un style d’encadré avec numbering compte ses boîtes, comme le amsthm de LaTeX compte les environnements de théorème : chaque boîte s’ouvre sur son libellé et son numéro en gras, « Théorème 2. », le title de la clôture suivant le numéro entre parenthèses, « Théorème 2 (Bradley–Terry). », et un renvoi à son {#id} imprime « Théorème 2 » (\ref{thm:x} ou style=number le 2 seul). Les styles qui nomment un même compteur le partagent : un lemme qui suit un théorème est donc le Lemme 3. Le endMark d’un style de démonstration termine ses boîtes par ∎ ou □, aligné à droite sur la dernière ligne. Voir Énoncés numérotés et démonstrations pour les styles.

:::callout{type="theorem" #thm:main title="Bradley–Terry"}
Every reward class holds one reparameterised reward.
:::
 
:::callout{type="proof"}
Apply the projection of \eqref{eq:projection} to any member of the class.
:::
 
By :ref{id="thm:main"}, the objective is unchanged.

#Ressources

Les images, les SVG, les tableaux et les vidéos ne s’écrivent pas dans le texte. On les déclare une fois comme ressources (gérées dans le panneau Ressources du Sandbox, qui prend en charge l’import d’images et de SVG, un éditeur de tableaux interactif, les vidéos YouTube, Vimeo et importées, et l’édition des légendes et du placement), puis on les relie à la prose par leur id. Renvoyer à une ressource suffit à l’intégrer : vous la mentionnez une fois avec un :ref{id="…"} dans le texte, et le moteur fait flotter la figure ou le tableau dans le premier emplacement libre après ce renvoi (le pied de la colonne où vous la mentionnez, le haut de la colonne suivante, une bande de la page suivante), exactement comme le ferait un compositeur pour l’imprimé. Vous ne la placez pas une seconde fois.

Les deux formes ci-dessous sont une syntaxe nouvelle qui n’entre pas en conflit avec CommonMark ; un document qui les utilise se lit donc toujours comme du texte brut dans n’importe quelle autre visionneuse Markdown.

#Renvoi dans le texte (la forme principale)

Renvoyez à une ressource depuis la prose avec :ref{id="…"}. Le premier renvoi intègre la ressource (elle est donc placée sur la page) et affiche son numéro calculé, précédé par défaut du libellé court du type :

As shown in :ref{id="lighthouse-diagram"}, the lantern room sits above the gallery.

s’affiche ainsi : As shown in Fig. 1.7, the lantern room sits above the gallery. Le diagramme lui-même flotte vers l’emplacement libre le plus proche après la phrase (le pied de cette colonne, le haut de la suivante ou une bande de la page suivante), tandis que cette phrase et le texte qui la suit continuent sans interruption.

Le texte courant n’est jamais coupé à l’endroit du renvoi. L’endroit où arrive la ressource (le premier emplacement libre, ou seulement un emplacement en haut ou en bas ; dans une seule colonne ou sur toute la largeur) dépend de son placement (voir Placement plus bas) et de l’endroit où vous la mentionnez : la recherche commence juste après le renvoi.

#Insertion en bloc (facultative, placement explicite dans le texte)

Il arrive que vous vouliez qu’une ressource se tienne à un point précis du flux au lieu de flotter. Renoncez au flottement en donnant à la ressource placement.position: "here" et en l’insérant avec ::resource{id="…"} sur une ligne à part :

Here is the floor plan we discussed.
 
::resource{id="lighthouse-diagram"}
 
The keeper's quarters occupy the eastern wing.

Pour une ressource flottante, la directive ::resource est inutile : le :ref l’a déjà placée, et un ::resource redondant pour le même id est simplement traité comme un renvoi de plus, pas comme une seconde copie. Un ::resource n’affiche la ressource dans le texte que si son placement résolu est "here". Une ressource dans le texte garde une ligne d’espace au-dessus d’elle (l’espace des flottants), comme un flottant, sauf si le bloc précédent en demande davantage. Dans le texte courant, elle garde le même espace en dessous ; puis le texte qui la suit revient sur la grille de ligne de base, ce qui peut ajouter jusqu’à une ligne de plus. Un titre, une liste, un encadré ou une autre ressource dans le texte placés juste après partagent cet espace avec leur propre espace au-dessus : le plus grand des deux s’applique, pas les deux. (Jusqu’à postext 1.4, l’espace en dessous n’était que ce que laissait l’alignement sur la grille, de rien à une ligne ; layout.inlineResourceGap: 'above' conserve cette règle, et les livres enregistrés avant la 1.5 sont lus avec elle.) Dans un encadré (:::callout), la ressource garde le même espace, une ligne du texte propre à l’encadré au-dessus d’elle et, avec 'around', en dessous ; en haut ou au pied de l’encadré, c’est la marge intérieure qui la sépare. (Jusqu’à postext 1.4, elle touchait le texte de l’encadré ; layout.inlineResourceGapInBoxes: false conserve ce comportement, et les livres enregistrés avant la 1.5 dont les encadrés insèrent une ressource sont lus avec lui.)

Une ressource dans le texte dont le placement indique aussi span: 'page' (placement: { position: 'here', span: 'page' }) s’étend sur toute la largeur de la page à l’endroit de sa directive dans une mise en page à plusieurs colonnes, comme le fait un encadré sur toute la largeur de la page : les colonnes au-dessus se ferment à niveau (équilibrées, ou la ressource passe en tête de la page suivante quand elles ne peuvent pas l’être), elle est composée sur toute la largeur du contenu avec le même espace au-dessus et en dessous, et le texte reprend dans chaque colonne sous elle. Sur une page à une colonne, elle est composée comme avant, à pleine justification. Une ressource span: 'column' dont columns est défini reste dans sa colonne quand elle est insérée dans le texte : les colonnes ne comptent que pour les flottants. Depuis postext 1.19.

L’id doit correspondre à une ressource définie dans le panneau Ressources. Le moteur affiche la ressource (bitmap, SVG ou tableau) avec sa légende dessinée en dessous, comme pied de figure ou de tableau. Le texte de la légende est composé à partir du captionPrefix du type de ressource, du numéro calculé et de la légende propre à la ressource, par exemple Figure 1.7. Le plan d’origine du phare. Sa typographie dépend de Configuration › Style des légendes : le libellé et la description partagent un même caractère et un même corps, tandis que le libellé garde ses propres réglages de gras, d’italique et de couleur ; l’espace au-dessus de la légende vaut 0.75em par défaut et l’alignement est à gauche. La légende peut aussi se placer au-dessus de la ressource (captionStyle.position: 'above', globalement ou par type de ressource), éventuellement sur une barre de couleur. Une ressource peut également porter une note (une courte ligne de source ou de crédit, avec la même mise en forme en ligne et les mêmes marques :ref que la légende), composée en plus petit sous la ressource (sous la légende quand la légende est en dessous, sous le corps quand elle est au-dessus) et stylée par captionStyle.note.

Sauts de ligne dans les légendes et les notes. Une légende ou une note est un paragraphe composé à la justification de son emplacement, et un retour à la ligne tapé dedans vaut une espace. Pour commencer une nouvelle ligne, écrivez \\ (le saut forcé des titres) ou terminez la ligne par une barre oblique inverse, le saut de ligne forcé du Markdown : ¹ Measured at 20 °C. \\ ² Mean of three runs. place chaque note d’un tableau large sur sa propre ligne. La ligne qui précède un saut garde sa largeur naturelle, sans jamais être étirée à la justification, et deux sauts à la suite ne font pas de ligne vide (une espace insécable entre eux, si). Dans une cellule de tableau, \\ fait ce que fait un retour à la ligne : il ouvre un nouveau paragraphe ; le retrait de la ligne suivante est conservé, si bien que deux espaces en tête imbriquent toujours un élément de liste. Dans le texte lui-même, les deux barres obliques inverses sont toujours un saut, sans échappement : pour les imprimer, mettez-les dans du code en ligne, où les barres obliques inverses s’impriment telles qu’elles sont écrites. Dans la destination d’un lien, elles restent dans l’URL, et dans les attributs d’une directive (le text d’un :ref), dans la valeur ; dans une pastille, composée sur une seule ligne, un saut vaut une espace. (Jusqu’à postext 1.4, les barres obliques inverses s’imprimaient, et une légende ou une note ne passait à la ligne que là où la justification était atteinte.)

Les ressources de type tableau dessinent leur propre grille, stylée par Configuration › Style des tableaux : les cellules du corps et de l’en-tête ont des typographies entièrement indépendantes, le fond de l’en-tête vaut #f0f0f0 par défaut, les bordures 0.75pt et cellPadding 0.375em ; tout champ non défini hérite du texte courant. Les largeurs de colonne font partie du tableau lui-même : TableModel.columnWidths contient un poids relatif par colonne ([2, 1, 1] donne à la première colonne la moitié de la largeur) ; sans lui, les colonnes se partagent la largeur à parts égales. Un tableau peut aussi être composé dans une variante nommée : table.styleId choisit l’un des tableStyles du document (voir Configuration › Styles de tableau nommés), dont les champs non définis héritent de tableStyle ; un id inconnu ou absent conserve tableStyle.

Une cellule place son contenu avec TableCell.align (left, center, right ; les éléments de liste restent alignés à gauche) et TableCell.verticalAlign (top, la valeur par défaut, middle ou bottom). L’alignement vertical déplace tout le contenu de la cellule (l’image et le texte qui la suit, comme un seul bloc) à l’intérieur d’une cellule plus haute que lui : une rangée étirée par une voisine plus longue, ou les rangées que couvre un rowSpan. Il s’applique à toutes les sorties (canvas, HTML, PDF), dans les tableaux pivotés et dans chaque tranche d’un tableau scindé sur plusieurs pages. Les deux se règlent par cellule avec les boutons d’alignement de la barre d’outils de l’éditeur de tableaux du Sandbox.

Une cellule de tableau peut aussi contenir une image. TableCell.image désigne une ressource bitmap ou SVG par son id ({ "resourceId": "fig-arm", "width": 0.7 }) : l’image est dessinée dans la cellule (jamais numérotée, flottante ni légendée), ajustée à la largeur intérieure de la cellule (ou à la fraction de celle-ci donnée par width, 1 par défaut) en conservant ses proportions, alignée comme le texte de la cellule, et tout texte de la cellule passe en dessous. La rangée grandit pour la contenir. Dans l’éditeur de tableaux du Sandbox, le bouton image de la barre d’outils choisit la ressource pour la cellule active et un champ de largeur fixe la fraction. Un id qui ne correspond à aucune ressource image laisse la cellule en texte seul.

Une cellule peut porter son propre fond. TableCell.background est une valeur de couleur ({ "hex": "#c1dfd6", "model": "hex" }, éventuellement liée à une entrée de la palette du document avec paletteId) peinte à la place du fond d’en-tête ou de corps du style : c’est ainsi qu’une matrice de compatibilité colore ses cellules en vert, rouge et jaune. L’éditeur de tableaux du Sandbox la règle depuis la commande de remplissage de la barre d’outils. Pour légender ces fonds, la légende, la note et tout bloc de texte acceptent une pastille de couleur en ligne : :swatch{color="#c1dfd6"} (une valeur hexadécimale, ou l’id d’une entrée de palette : :swatch{color="table-compatible"}) pose sur la ligne de base un petit carré de trois quarts du corps, rempli de la couleur et cerné de la couleur du texte, si bien qu’une note peut se lire :swatch{color="ok"}: compatible; :swatch{color="no"}: incompatible. Une couleur qui ne se résout en rien dessine un contour vide. La valeur hexadécimale peut porter un canal alpha (#rrggbbaa, #rgba), et les couleurs rgb() / rgba() fonctionnent aussi : un fond de cellule translucide a donc une pastille translucide assortie (voir Configuration › Transparence).

Les ressources SVG peuvent en outre être recolorées pour une impression en une seule couleur d’accompagnement grâce à diagramStyle.singleInk (false par défaut). Une fois activé, chaque couleur d’un diagramme SVG est ramenée à une teinte de diagramStyle.inkColor (par défaut la couleur principale de la palette, #295AA3) selon sa luminance : le blanc devient le papier, le noir l’encre pleine. Les figures se reproduisent ainsi fidèlement quand le document est imprimé avec une seule couleur d’accompagnement. Voir Configuration › Style des diagrammes.

Une insertion mal formée (id absent ou vide, id sans guillemets ou entre apostrophes, attributs en trop) n’est pas promue en bloc de ressource ; elle retombe dans l’analyse ordinaire des paragraphes et reste visible dans la sortie. Il en va de même d’une ligne d’insertion bien formée collée sous une ligne de paragraphe sans ligne vide entre elles : elle est lue comme faisant partie de ce paragraphe. Les deux cas déclenchent un avertissement malformedEmbed, une entrée Insertion composée comme du texte dans le panneau Vérifications du Sandbox.

Les renvois sont reconnus dans n’importe quel bloc de texte (paragraphes, titres, citations et éléments de liste) et peuvent côtoyer le gras, l’italique, le code en ligne et les mathématiques en ligne.

Options du renvoi

La directive :ref accepte trois attributs facultatifs, dans n’importe quel ordre. style choisit l’affichage du libellé calculé : style="number" imprime le numéro seul (1.7), style="full" imprime le nom complet du type suivi du numéro (Figure 1.7), et sans style on utilise le shortLabel du type suivi du numéro (Fig. 1.7). case change la casse de la seule partie libellé (lower, upper ou capitalize) sans toucher au numéro. text est un remplacement littéral qui se substitue à tout libellé calculé et l’emporte à la fois sur style et sur case. Les options d’affichage côte à côte :

Si un :ref (ou un ::resource) désigne un id sans ressource correspondante, le libellé se rabat sur ? (un libellé text= est imprimé à la place, toujours sans numéro ni lien) et le Sandbox émet un avertissement ressource inconnue. Le moteur l’enregistre comme une entrée unknownResourceId dans les contentWarnings du document, avec la plage source du renvoi et sa page, y compris pour un :ref placé dans une légende, une note ou une cellule de tableau d’une ressource utilisée par le texte.

#Numérotation au premier renvoi

Le numéro d’une ressource est attribué la première fois qu’elle est mentionnée dans l’ordre de lecture, que cette première mention soit une insertion en bloc ::resource ou un :ref dans le texte. Ensuite, chaque renvoi au même id imprime ce même numéro.

Les numéros suivent donc l’ordre dans lequel le lecteur rencontre les ressources, et non l’ordre dans lequel elles ont été créées dans le panneau :

• Si vous renvoyez par :ref à une figure dans l’introduction et ne l’insérez (::resource) que deux pages plus loin, elle prend malgré tout le numéro de l’introduction : le renvoi est venu en premier.
• Ajouter un nouveau renvoi plus tôt dans le document renumérote automatiquement tout ce qui suit. Il n’y a aucune numérotation manuelle à tenir à jour.

La numérotation est propre à chaque type de ressource et respecte la portée de remise à zéro et le format de compteur de chaque type ; voyez Configuration › Types de ressources pour les jetons de modèle ({h1}, {n}), resetOn et counterFormat.

Seul ce à quoi le texte renvoie est compté : une ressource que seule une maquette dessine (un élément image d’une ouverture de chapitre, par exemple) ne reçoit pas de numéro et laisse le compteur tel quel. Et {h1} compte chaque titre de niveau 1 dont le style n’est pas numbered: false, même celui dont le numberingTemplate est vide ; un article dont le seul H1 est son titre numérote donc par défaut ses figures 1.1, 1.2… Configuration › Ce qui est numéroté donne les deux règles et les réglages pour obtenir Figure 1, 2…

#Placement

Chaque ressource a un placement qui décide où arrive son flottant. Il se résout pour chaque ressource (son propre placement), puis selon le defaultPlacement de son type, puis selon la valeur intégrée par défaut, auto / column :

Un flottant va dans le premier emplacement libre après son premier renvoi, dans l’ordre de lecture : le pied de la colonne où se trouve le renvoi, puis le haut et le pied de la colonne vide suivante de la même page, puis les bandes de la page suivante qu’ouvre le flux (un flottant sur toute la largeur de la page prend le bas de la page quand chaque colonne a encore la place de l’accueillir, sinon une bande de la page suivante). Une page qu’ouvre une figure ou un tableau dans le texte compte aussi : un flottant qui attend cette page en prend la tête, au-dessus de la figure ou du tableau, quand les deux y tiennent ; sinon, la figure ou le tableau garde la page et le flottant attend la suivante. Jusqu’à postext 1.4, une telle page était sautée, et le flottant attendait la page d’après même quand les deux tenaient. Il est composé à sa taille, sauf si son shrink lui permet de se réduire à la place d’un emplacement (voir le tableau ci-dessus), et il n’arrive jamais avant son renvoi. Les flottants d’une même séquence de numérotation apparaissent dans l’ordre des renvois : une figure qui ne trouve de place nulle part sur une page retient les figures qui la suivent (un tableau en attente ne retient pas une figure, ni l’inverse), si bien que la figure 12 n’apparaît jamais avant la figure 11. Un tableau qui devrait sinon attendre est plutôt coupé : quand on lui offre la tête d’une colonne vide, il prend les rangées qui y tiennent et se poursuit dans l’emplacement suivant (la colonne voisine ou la page suivante) avec ses rangées d’en-tête répétées (voir tableStyle.overflow). Un flottant top ou auto avec citingPage activé peut au contraire prendre la tête de la page (ou de la colonne) où arrive sa ligne qui cite, le texte au-dessus du renvoi descendant sous lui : il est alors peint au-dessus de son renvoi sur la même page, jamais sur une page antérieure, et reste lu après celui-ci dans un PDF balisé et dans le HTML. Le moteur règle cela en quelques passes supplémentaires et ne le conserve que tant que la ligne qui cite reste sur cette page.

Les flottants ne sortent jamais de leur chapitre : à une ouverture de chapitre (un niveau de titre avec breakBefore ou span: 'page'), à un :::part, à un style d’encadré avec floatBarrier: true (l’encadré « points clés » qui clôt un chapitre) et à la fin du document, chaque flottant encore en attente est d’abord placé, dans les emplacements libres de la page ou sur des pages ouvertes avant la limite. Un flottant cité pour la première fois par l’ouverture elle-même (un titre de chapitre qui nomme sa figure), ou par le premier bloc qui suit un :::part, appartient au nouveau chapitre : il arrive après cette ligne, comme n’importe quel autre. Une figure ou un tableau qui demandait la tête d’une page peut alors prendre le pied de la page qui clôt le chapitre, sous ses colonnes équilibrées, plutôt qu’une page à lui. Un :::pagebreak envoie simplement les flottants en attente sur la page qui le suit.

Sous une ouverture sur toute la largeur de la page composée au-dessus de deux colonnes de texte ou plus, la colonne propre à l’ouverture compte comme vide en sa tête tant que rien n’y suit l’ouverture : un encadré flottant délimité juste après l’ouverture, ou une ressource insérée là avec ::resource, prend la tête de la première colonne, sous l’ouverture et à niveau avec la tête des autres colonnes (sur plusieurs colonnes à partir d’elle avec columns), et le texte de la colonne commence en dessous. Un flottant cité dans le texte courant suit toujours sa ligne qui cite. Jusqu’à postext 1.24, la première colonne n’offrait pas d’emplacement à cet endroit et un tel flottant n’arrivait qu’à partir de la deuxième colonne ; layout.floatsUnderOpener: false conserve ce comportement (voir Configuration › Mise en page).

Les encadrés latéraux (span="side") restent eux aussi dans leur chapitre. Un encadré que la colonne latérale de sa page ne peut pas contenir prend la colonne latérale de la page suivante ; là où le chapitre, ou le document, se termine d’abord, chaque encadré encore en attente est composé dans la colonne latérale d’une page ouverte après le texte, dans l’ordre de leurs délimiteurs, et une figure latérale citée après eux se place derrière eux. Une telle page ne contient pas de texte ; la compilation signale donc chaque encadré et chaque figure qui s’y trouve (afterText). Un encadré plus haut qu’une colonne latérale vide est composé malgré tout et signalé (calloutOverflow), et tout ce qui ne trouve toujours aucune page est signalé aussi (unplaced) au lieu d’être abandonné. Jusqu’à postext 1.24, seule la première de ces pages était ouverte, et les encadrés restants étaient perdus sans avertissement.

Les bandes de flottants sont corrigées par rapport à la grille de ligne de base, pour que le texte autour garde le rythme vertical de la page. Une bande en haut agrandit sa marge inférieure jusqu’à la ligne de grille suivante, si bien que le texte sous le flottant reste aligné sur les colonnes voisines et sur la page en regard. Un flottant en bas est ancré de sorte que la dernière ligne de sa légende partage une ligne de base avec la dernière ligne de texte des autres colonnes (un contenu sans légende aligne son bord inférieur sur le dernier emplacement de la grille) : les pages pleines se terminent donc à la même hauteur d’une colonne à l’autre et d’une page à la page en regard.

Sur la page qui clôt un chapitre, et le document, rien ne suit les figures et tableaux sur toute la largeur de la page composés sous la dernière bande de texte ; ils remontent donc pour se placer à un espace de flottant sous celle-ci, empilés dans leur ordre, au lieu de laisser du blanc entre le texte et une figure au pied de la page. Cela vaut aussi pour un flottant position: 'bottom'. Pour les garder au pied, comme sur toutes les autres pages, réglez layout.hugClosingFloats: false (voir Configuration › Mise en page). Les pages qui ont une colonne latérale ne les déplacent jamais.

Les trois moteurs de rendu (l’aperçu canvas, la visionneuse HTML et la sortie PDF) affichent les ressources. Dans le moteur HTML, les données des images sont tenues à part ; l’hôte les fournit donc par l’option de résolution resourceImageUrl(fileId). Quand cette fonction manque (ou ne renvoie rien pour un fichier), la ressource s’affiche sous forme d’un cadre neutre de substitution, pour que la mise en page reste stable. Le fichier propre d’une vidéo passe de la même façon par resourceVideoUrl(fileId) (voir Vidéos).

Où un flottant peut se placer

« Jamais avant son renvoi » se compte à partir de la ligne qui cite le flottant : le flottant attend que cette ligne soit composée, et prend le premier emplacement libre après elle dans l’ordre de lecture ; la tête de la page où cette ligne est composée vient avant elle. Un flottant latéral (span: 'side', dans la colonne latérale réservée aux flottants d’une mise en page à une colonne et demie) fait exception : il s’empile dans la colonne latérale à côté du texte qui le cite, et peut se placer plus haut sur la page que la ligne qui cite. Pour une figure citée en page 5 :

• Une page d’ouverture de chapitre suit les mêmes règles : un flottant auto ou bottom sur toute la largeur de la page, cité dans le premier paragraphe de l’ouverture, peut prendre la bande du pied de cette page, sous son texte ; un flottant top ouvre la page suivante. Pour avoir l’image sur la page qui la cite, utilisez auto ou bottom, ou dessinez-la comme élément image de la maquette de l’ouverture.
• Deux flottants de colonne cités dans le même paragraphe prennent les deux emplacements suivants : en général, le premier le pied de la colonne qui cite, le second la tête de la colonne vide suivante, côte à côte sur la page.
• Dans une mise en page à une colonne, un flottant sur toute la largeur de la page est un flottant de colonne, et les mêmes règles valent : un flottant top cité sur une page arrive en tête de la suivante.
• Un paragraphe qui court d’une page sur la suivante se compte lui aussi à partir de sa ligne qui cite. Quand le paragraphe commence au pied de la page 5 et que le renvoi tombe en page 6 (ou que tout le paragraphe passe en page 6, faute d’assez de place pour ses lignes au pied de la page 5), le renvoi est en page 6 : un flottant top ouvre la page 7, et un flottant auto prend le pied de la page 6 quand il y a la place. Il en va de même entre les colonnes d’une page, et pour un encadré scindé sur plusieurs pages : une figure que cite sa seconde partie attend cette partie.
• Modifié dans postext 1.5. Jusqu’à postext 1.4, un flottant était mis en file d’attente quand la mise en page atteignait le paragraphe qui le cite ; la page sur laquelle ce paragraphe débordait (ou vers laquelle il passait) pouvait donc s’ouvrir sur le flottant, au-dessus de la ligne contenant le renvoi. Une telle figure arrive désormais une page plus loin, ou au pied de la page quand elle demande auto ; le nombre de pages peut s’en trouver modifié.

#Habillage du texte

Une image, un tableau ou un encadré plus étroit que sa colonne peut se tenir d’un côté de celle-ci, le texte courant à côté de lui, comme dans un magazine ou une lettre d’information. Donnez à son placement un côté wrap et, si vous le souhaitez, une width :

{ "id": "bed", "typeId": "figure", "kind": "svg", "caption": "The new planting bed.",
  "placement": { "position": "here", "wrap": "right", "width": 0.4 } }

• Dans le texte ("here"). La ressource se place de son côté de la colonne, son haut à niveau avec le haut de la ligne suivante à l’endroit de la ligne ::resource, et les paragraphes, citations et éléments de liste qui suivent courent à côté d’elle à la justification restante, puis sous elle à pleine justification. Un paragraphe qui commence à côté d’elle et se termine sous elle reste un seul paragraphe : pas de coupure, pas d’espace supplémentaire au pied de l’image. Chaque ligne reste sur la grille de ligne de base ; la place sous l’image est son espace arrondi au nombre entier de lignes de grille supérieur.
• Un flottant de colonne. Un flottant span: "column" large d’une colonne, en tête ("top", ou "auto" en tête d’une colonne) ou au pied ("bottom", "auto") d’une colonne, est placé dans sa bande comme tout flottant ; les premières lignes de la colonne, ou ses dernières, courent alors à côté de lui. Sur une page de deux colonnes, le flottant appartient à sa colonne, et l’autre reste à pleine justification.
• Un encadré. Un :::callout accepte les mêmes réglages sous forme d’attributs : :::callout{wrap="right" width=0.4} place une citation en exergue ou un encadré latéral là où il apparaît, avec le texte qui le suit à côté de lui, et placement="top" ou "bottom" avec wrap le fait flotter en tête ou au pied d’une colonne. Un encadré habillé est mis en page d’un seul tenant et ne se scinde jamais.
• Ce qui passe en dessous. Un titre, une formule centrée, une figure ou un tableau, un encadré et un poème ne courent pas à côté d’un élément habillé : ils passent sous lui, et le blanc à côté de lui au-dessus d’eux reste vide. Quitter la colonne (son pied, un :::columnbreak, un saut de page) met fin à l’habillage à cet endroit : l’élément appartient à sa colonne. Quand le bloc qui suit immédiatement une ressource dans le texte ne peut pas courir à côté d’elle, la ressource prend sa bande, comme sans wrap.
• Espace et limites. wrapGap (sinon layout.wrap.gap, sinon une ligne de texte courant) sépare l’élément, légende comprise, du texte à côté de lui et du texte en dessous. Là où le texte à côté serait plus étroit que layout.wrap.minTextWidth (12 em de texte courant), ou si l’élément est moins haut que layout.wrap.minLinesBeside lignes (2), il prend sa bande entière et un avertissement textWrap le signale. Un élément dans le texte trop haut pour la place restante dans sa colonne passe à la suivante avec son ancre, avec le même avertissement.
• Côtés. left et right sont des côtés du flux du texte, comme pour align : dans un livre de droite à gauche, left est la droite de la feuille. start et end désignent les mêmes côtés.
• Sorties. Le canvas, la visionneuse HTML, le PDF et l’EPUB à mise en page fixe composent les lignes telles qu’elles ont été mises en page ; un PDF balisé lit l’image ou l’encadré avant le paragraphe qui court à côté. Un EPUB recomposable le fait flotter de son côté en CSS, avec la même part de la largeur du texte.
• Pas encore. Le texte des deux côtés d’une image, l’habillage en contour, l’habillage à l’intérieur du contenu propre d’un encadré, et l’habillage dans un texte vertical (l’élément garde sa bande, avec un avertissement). Les colonnes qui contiennent un élément habillé sont exclues de l’équilibrage des colonnes.

#Taille des bitmaps

Un bitmap déclare ses pixels : bitmap.width et bitmap.height sont les nombres de pixels du fichier, pas une taille d’impression. Le nombre de pixels qu’on fait tenir dans un pouce décide de la taille à laquelle l’image est composée avant que son emplacement la plafonne. Il y a trois façons d’en fixer la taille :

• Ses pixels à la résolution de la page (par défaut). Sans résolution, un pixel de l’image est un pixel de la mise en page (page.dpi, 300 sauf réglage contraire) : une photographie de 2 400 px fait 8 pouces (203,2 mm) de large sur une page à 300 dpi, et le double sur une page à 150 dpi.
• Une résolution. bitmap.resolution est la résolution de l’image en ppi à sa taille d’impression naturelle ; sa largeur naturelle est donc width × page.dpi / resolution sur une page de n’importe quelle résolution : 2 400 px à resolution: 300 font 203,2 mm de large sur une page mise en page à 150 dpi comme à 300. layout.bitmapResolution donne une résolution à chaque bitmap qui n’a pas la sienne : un nombre (300), ou 'file', la résolution que déclare son fichier (bitmap.fileResolution : le pHYs d’un PNG, la densité JFIF ou EXIF d’un JPEG, l’EXIF d’un WebP ; pour une image importée de Word, la taille à laquelle Word l’imprimait). Les appareils photo, les captures d’écran et les exports web déclarent souvent 72 ou 96 ppi quand ils ignorent tout de la taille d’impression ; avec 'file', ces deux valeurs comptent donc comme absentes et l’image garde ses pixels à la résolution de la page ; un 72 déclaré sur la ressource elle-même est pris tel quel. 'document', la valeur par défaut, correspond à la première façon.
• Une part de la colonne. placement.width réduit un flottant ou une insertion dans le texte à une fraction de sa colonne (ou de la page), et une image plus grande que cette part est réduite à celle-ci, quels que soient ses pixels (voir Placement).

Dans tous les cas, l’emplacement plafonne l’image en gardant ses proportions, et une image plus petite n’est jamais agrandie. La même taille naturelle s’applique à une image dans une cellule de tableau et à un élément image de maquette de taille 'auto'. Le PDF incorpore le fichier tel quel, à sa taille de placement. Le contrôle en amont vérifie la résolution à laquelle s’imprime chaque image, et le panneau Ressources du Sandbox l’affiche pour chaque image. Depuis postext 1.24.

{ "id": "harbour", "typeId": "figure", "kind": "bitmap", "caption": "The harbour at dawn.",
  "bitmap": { "fileId": "harbour.jpg", "format": "jpeg", "width": 2400, "height": 1600, "resolution": 300 } }

bitmapInfo(bytes) (de postext et de postext/bundle) lit les pixels d’un fichier et la résolution qu’il déclare, { width, height, resolution?: { x, y, source } } ; un paquet ouvert avec 'file' en remplit fileResolution, et le Sandbox la conserve pour chaque image qu’il importe.

#Zone de sécurité

Une ressource bitmap ou SVG peut marquer une zone de sécurité : le rectangle de l’image qui contient l’essentiel (une personne et une bande du paysage derrière elle, la partie tracée d’un graphique) et qui est toujours montré. C’est le safeArea de la ressource, quatre fractions (0–1) de la taille intrinsèque de l’image mesurées depuis son coin supérieur gauche : x et width sont des fractions de sa largeur, y et height de sa hauteur. Le nom dit ce qu’il faut garder ; un cadre de recadrage dirait où couper.

const harbour: Resource = {
  id: 'harbour', typeId: 'figure', kind: 'bitmap', caption: 'The harbour at dawn.',
  createdAt: 0, updatedAt: 0,
  bitmap: { fileId: 'harbour.jpg', format: 'jpeg', width: 2400, height: 1600 },
  // the boats and the quay: 18–68 % of the width, 25–85 % of the height
  safeArea: { x: 0.18, y: 0.25, width: 0.5, height: 0.6 },
};

Seule une image dotée d’une zone de sécurité est recadrée. Le moteur peut alors la montrer selon n’importe quelles proportions comprises entre l’image entière et la zone de sécurité : plus haute que les proportions propres de l’image en rognant les côtés, au plus jusqu’à la largeur de la zone de sécurité, ou plus basse en rognant le haut et le bas, au plus jusqu’à sa hauteur. La largeur de la figure ne change jamais, seulement sa hauteur. Ce qui se trouve hors de la zone de sécurité est rogné des deux côtés en proportion des marges qui s’y trouvent, si bien qu’un sujet décentré à gauche reste décentré à gauche. Composé sur 60 mm de large, le port ci-dessus fait 40 mm de haut quand il est entier, et peut être montré sur une hauteur allant de 24 mm (haut et bas rognés jusqu’à 60 % de la hauteur) à 80 mm (côtés rognés jusqu’à la moitié de la largeur). Les valeurs qui dépassent les bords de l’image sont ramenées à ceux-ci ; une zone dont une valeur n’est pas un nombre ou dont un côté fait moins de 2 % de l’image, ou qui couvre l’image entière, est ignorée, de même que le champ sur un tableau. Sans zone de sécurité, une image est toujours montrée entière, comme avant.

Le moteur utilise cette latitude à quatre endroits :

• La place restante dans une colonne. Une image dans le texte (position: 'here') un peu trop haute pour la place restante dans sa colonne, y compris celle dont la légende dépasserait le pied de la page, est recadrée dans sa zone de sécurité pour y rester, au lieu de passer à la colonne ou à la page suivante en laissant celle-ci trop courte.
• Des pages moins hautes que la figure. Avec layout.fitFiguresToPage, une image trop haute pour la page est d’abord recadrée dans sa zone de sécurité, en gardant sa largeur, et n’est réduite que si elle reste trop haute (voir Configuration › Mise en page).
• Des bandes moins hautes que la figure. Un flottant dont le placement.shrink le met à l’échelle de la place de son emplacement est d’abord recadré dans sa zone de sécurité, en gardant sa largeur, puis seulement réduit ; le levier flexFigure ci-dessous ne l’agrandit jamais au-delà de cette place.
• L’équilibrage des colonnes. Une image dotée d’une zone de sécurité, placée dans le texte d’une colonne courte, ou flottant en tête ou au pied de cette colonne sur cette seule colonne, grandit d’un nombre entier de lignes de la grille de ligne de base pour remplir les lignes vides de la colonne. Une image plus haute ne laisse aucun trou visible ; ce levier, flexFigure, est donc essayé juste après l’encadré qui clôt la colonne et avant tout ajout d’espace au-dessus des titres ou après les listes. Un flottant en tête de colonne sur la page qui clôt un chapitre ou dans une bande de clôture ne grandit pas, car ces têtes de colonne restent à niveau (voir Configuration › Équilibrage des colonnes).

Le VDT enregistre le recadrage sur le bloc de la ressource : bodySource est la partie de l’image montrée dans bodyRect, dans les mêmes fractions (absente quand l’image entière la remplit), et bodyFlex donne les px dont le corps pourrait encore rétrécir et grandir, et les px dont les leviers l’ont déjà modifié ({ shrink, grow, delta }). L’aperçu canvas et le PDF découpent au corps et dessinent l’image entière à sa taille non recadrée ; la visionneuse HTML et l’EPUB à mise en page fixe placent l’image avec object-fit: cover et un object-position correspondant ; un EPUB recomposable, qui n’a pas de page à remplir, montre l’image entière. Un hôte qui dessine lui-même les images peut utiliser les fonctions utilitaires qu’exporte postext : resourceSafeArea et normalizeSafeArea (la zone telle que la lit le moteur, ou undefined), safeAreaHeightRange (le corps le plus bas et le plus haut à une largeur donnée), safeAreaSource (la partie montrée à une hauteur donnée) et uncroppedPictureBox (où dessiner l’image entière avant la découpe), avec le type ResourceSafeArea. Dans le Sandbox, le champ s’appelle Zone de sécurité sur une image du panneau Ressources.

La recette Nº 116 du livre de recettes, Des photos qui grandissent pour remplir une colonne courte, compose deux fois un article de magazine sur deux colonnes, sans puis avec zones de sécurité, pour que vous puissiez comparer les pages côte à côte.

#Ancres des personnages et zones à éviter

Une image qui sert de dessin à une case de bande dessinée peut aussi indiquer où se trouvent ses personnages, pour le lettrage (voir Bandes dessinées). anchors liste un point par personnage et avoid les régions qu’aucune bulle ne couvre, les deux en fractions de l’image comme la zone de sécurité :

const radio: Resource = {
  id: 'lh-radio', typeId: 'figure', kind: 'bitmap', createdAt: 0, updatedAt: 0,
  bitmap: { fileId: 'lh-radio.jpg', format: 'jpeg', width: 1000, height: 1000 },
  safeArea: { x: 0, y: 0.36, width: 0.62, height: 0.56 },
  anchors: [
    // the keeper: mouth, head (for thought balloons) and face
    { id: 'tomas', x: 0.345, y: 0.52, head: { x: 0.38, y: 0.44 }, face: { x: 0.29, y: 0.4, width: 0.16, height: 0.18 } },
  ],
  avoid: [{ x: 0, y: 0.44, width: 0.22, height: 0.26 }], // the radio
};

L’id d’une ancre est la clé de personnage du script (tomas: …), ou sfx pour le point où se regroupent les onomatopées de la case ; x et y sont la bouche vers laquelle pointe l’appendice d’une bulle de dialogue, head le point vers lequel pointent les petites bulles d’une bulle de pensée (la bouche s’il n’est pas défini) et face un rectangle qu’aucune bulle ne couvre. Le moteur fait passer chaque point par le recadrage et le miroir de la case, si bien qu’un appendice reste sur son personnage quelle que soit la forme que prend la case ; une ancre hors de la zone de sécurité déclenche comicAnchorOutsideSafeArea, car un recadrage peut la couper. Une troisième liste, faces, contient les visages des personnes qui ne parlent pas, sous forme de rectangles comme ceux d’avoid : aucune bulle ne les couvre, alors qu’une zone à éviter cède quand une case n’a pas d’autre place. Les ancres appartiennent à l’image et servent à toutes les traductions de la bande dessinée. Seules les cases de bande dessinée les lisent ; une figure les ignore. Dans le Sandbox, on les marque dans la boîte de dialogue Zone de sécurité et lettrage du panneau Ressources.

#Vidéos

Une ressource vidéo (kind: 'video') est une vidéo YouTube ou Vimeo, ou une vidéo à vous : un fichier conservé dans le livre (MP4, WebM) ou situé à une adresse web, un fichier sur un serveur ou un flux HLS (une liste de lecture .m3u8). Elle est placée, légendée, mise en flottant et citée comme une image, et numérotée dans une séquence à elle : le type intégré video imprime Vidéo 1.1, Vidéo 1.2… à côté de Figure 1.1 et de Tableau 1.1 (voir Configuration › Types de ressources). Chaque sortie la montre comme elle le peut :

const talk: Resource = {
  id: 'keeper-talk', typeId: 'video', kind: 'video',
  caption: 'The keeper explains the lamp.',
  altText: 'A lighthouse keeper beside the lamp',
  createdAt: 0, updatedAt: 0,
  video: {
    source: 'youtube',                        // 'youtube' | 'vimeo' | 'file'
    url: 'https://youtu.be/aqz-KE-bpKQ',
    poster: { fileId: 'talk.jpg', format: 'jpeg', width: 1280, height: 720 },
    start: 30,                                // plays from 0:30; the printed link starts there too
  },
};

Le texte cite une vidéo comme il cite une figure : :ref{id="keeper-talk"} imprime Vidéo 1.1 et fait flotter l’affiche vers le premier emplacement libre après le renvoi, et ::resource{id="keeper-talk"} avec placement.position: 'here' la place dans le texte. Les champs de Resource.video (ResourceVideo) :

L’affiche. Elle est composée à la justification de son emplacement (ou à la fraction placement.width de celle-ci), dans ses propres proportions, quelle que soit sa taille en pixels : une image de la taille d’un écran est agrandie plutôt qu’imprimée en petit. Comme un bitmap, elle peut porter une zone de sécurité et suivre placement.align. Une vidéo sans affiche imprime un cadre sombre aux proportions de la vidéo (16:9 si rien ne les indique) avec ses éléments superposés, et déclenche un avertissement de contenu videoWithoutPoster. Dans le Sandbox, l’affiche d’une vidéo YouTube ou Vimeo est récupérée auprès de la plateforme quand son adresse est saisie, et celle d’un fichier est une image que vous choisissez dans la vidéo.

L’adresse. Le code QR et le lien du PDF ouvrent la page de la vidéo, https://youtu.be/<id> ou https://vimeo.com/<id>, à partir de start. Un fichier n’a pas de page : ils ouvrent son adresse de production, qui est aussi l’adresse d’où joue une vidéo sans fichier propre (un MP4 sur un serveur, un flux HLS). Sans adresse, l’imprimé n’a ni code QR ni lien (videoWithoutUrl), et une sortie HTML ou EPUB qui n’emporte pas le fichier montre l’affiche. Une adresse YouTube ou Vimeo qui ne désigne aucune vidéo de cette plateforme déclenche videoUrlInvalid ; l’affiche est montrée à la place d’un lecteur.

Les lecteurs. Les options de lecteur (commandes, bouton de téléchargement, plein écran, menu de vitesse, image dans l’image, diffusion, lecture automatique, démarrage en sourdine, boucle, préchargement, intégrations à confidentialité renforcée) se règlent pour tout le livre dans videoStyle.player et pour une vidéo dans video.player ; chaque lecteur respecte ce qu’il peut (voir Configuration › Style des vidéos). Le moteur HTML reçoit l’URL lisible d’un fichier par l’option resourceVideoUrl(fileId), comme il reçoit les images par resourceImageUrl, et se rabat sur l’adresse de production. Son option videos: { files, streams, hls } choisit entre lecteur et affiche selon la source, par-dessus videoStyle.html (hls, une vidéo lue depuis une adresse HLS, suit files s’il n’est pas défini) ; le générateur EPUB l’utilise. Une <video> qui lit une adresse HLS porte data-pt-hls, pour qu’un hôte puisse lui fournir un lecteur dans les navigateurs sans HLS natif (Safari et les versions récentes de Chrome la lisent telle quelle). Dans un livre de droite à gauche, le lecteur et les éléments superposés à l’affiche sont remis à l’endroit comme une image, pour que le code QR reste lisible.

Dans le VDT. Le bloc de ressource d’une vidéo a kind: 'video', son affiche en fileId / format (dessinée comme un bitmap), et video (VDTResourceVideo) : le link vers lequel est envoyé un lecteur, l’embedUrl YouTube ou Vimeo avec les options de lecteur appliquées, le fileId d’un fichier, le mimeType d’une vidéo à vous (de son fichier ou de sa seule adresse, application/vnd.apple.mpegurl pour le HLS), la plage start / end, le player résolu, linkPoster, html, et les éléments superposés playMark et qr (les modules du QR en rangées de '0' / '1'), avec des rectangles relatifs au coin supérieur gauche du corps. Un hôte qui dessine lui-même les vidéos peut utiliser les fonctions utilitaires qu’exporte postext : parseVideoUrl, videoWatchUrl, resourceVideoLink, videoEmbedUrl, videoEmbedAllow, videoElementAttributes, mediaFragment, videoMimeType, videoFormatOfUrl, resourceVideoFormat, isHlsMimeType, HLS_MIME_TYPE, youtubePosterUrls, encodeQr, layoutVideo, playMarkTriangle et qrModuleRuns.

Dans un paquet. Un .postext emporte un fichier (resources/<id>.mp4) et l’affiche (resources/<id>.poster.jpg) : l’entrée du manifeste les nomme dans file et poster, donne la taille de l’affiche dans width / height, et garde le reste dans video sans id de fichier. bundleVideoUrl(bundle) est la fonction de résolution resourceVideoUrl sur les fichiers d’un paquet. Une vidéo lue depuis une simple adresse n’emporte aucun fichier : son entrée ne contient que l’affiche. Dans un paquet bilingue, une langue peut donner à une vidéo sa propre poster et sa propre video (un autre montage, à sa propre adresse) dans localized[…].resources.

Les vidéos sur les pages de Folio

Dans le livre en 3D, une vidéo à vous joue sur la page où elle est imprimée. Un clic sur l’affiche la lance à cet endroit, quoi que fasse le pointeur sur le livre (tourner les pages, faire pivoter la vue ou sélectionner du texte) : le shader de la page dessine les images de la vidéo par-dessus l’affiche, si bien que l’image se plie et s’enroule avec le papier pendant que le feuillet tourne, et la vidéo continue de jouer pendant le mouvement. Un clic sur une vidéo en cours de lecture la met en pause, un clic sur une vidéo en pause la relance, et Espace ou Entrée font de même pour la première vidéo de la double page ouverte. Lancer une autre vidéo arrête celle qui joue (elle revient à son affiche), et une vidéo s’arrête quand le livre s’immobilise sur une double page qui ne la montre plus, ou à son end. Le pointeur devient une main au-dessus d’une vidéo qu’il peut lancer ; un glisser qui commence sur l’une d’elles tourne toujours la page ou la vue. Une vidéo réglée pour démarrer seule (video.player.autoplay) se lance d’elle-même la première fois que le livre s’immobilise sur sa double page, une fois le livre stabilisé (y compris quand un hôte le met en page par étapes), et plus jamais ensuite dans cette visionneuse.

Une vidéo qui joue en même temps que les autres (video.player.exclusive: false, depuis postext 1.18) change ces deux règles. La lancer n’arrête que les vidéos exclusives, de sorte que plusieurs vidéos de ce genre jouent à la fois ; lancer une vidéo exclusive l’arrête aussi. Avec autoplay, elle démarre, en sourdine, chaque fois que le livre s’immobilise sur sa double page, et s’arrête quand on tourne la page : les boucles silencieuses (loop) d’une page jouent ensemble chaque fois que le lecteur y revient.

• Ce qui se lit. Un fichier (l’hôte transforme son fileId en URL avec l’option videoUrl, une URL d’objet dans le Sandbox) ou, à défaut, son adresse : MP4, WebM ou un flux HLS. Un flux HLS se lit avec hls.js partout où le navigateur dispose des Media Source Extensions (chargé à la première lecture ; une dépendance pair facultative de postext-folio), plafonné à la variante la plus proche de la taille de l’image à l’écran, si bien qu’une image haute de quelques centaines de pixels ne tire jamais une variante 4K ; le HLS propre au navigateur sert de solution de repli. Ses requêtes portent leur propre paramètre pt-cors, pour que le cache du navigateur ne leur serve jamais une copie qu’un autre lecteur a récupérée sans CORS. YouTube et Vimeo jouent dans des iframes, que WebGL ne peut pas dessiner : un clic sur leur affiche tourne la page comme partout ailleurs.
• Lectures inter-origines. WebGL ne dessine une vidéo que si son serveur autorise la lecture (CORS, Access-Control-Allow-Origin). Une vidéo qui ne peut pas être lue reste une affiche, et onVideo reçoit error.
• Le son. Le clic permet à la vidéo de jouer avec son son ; un navigateur qui refuse encore la reçoit en sourdine. Une vidéo qui démarre seule a son son dès que le lecteur a cliqué ou tapé sur la page (tourner la page jusqu’à elle compte) ; avant cela, elle démarre en sourdine, et un clic dessus rétablit le son avant que le suivant ne la mette en pause. video.player.muted la fait démarrer en sourdine, loop la rejoue, et start / end délimitent la partie lue.
• Sur chaque page. L’image est dessinée là où la mise en page la place : tournée avec une ressource pivotée, droite sur une page verticale, et non inversée dans un livre de droite à gauche, comme l’affiche. Une affiche recadrée dans sa zone de sécurité recadre la vidéo de la même façon.
• Sans WebGL2, ou avec les animations réduites, la vidéo joue dans une <video> HTML posée par-dessus la page.

const book = createFolioFromDocument(container, doc, {
  // An uploaded video's playable URL (an object URL over its bytes).
  videoUrl: (fileId) => urls.get(fileId),
  onVideo: ({ resourceId, state }) => console.log(resourceId, state), // playing | paused | stopped | error
});
book.stopVideo();

videos: false désactive cette fonction. toggleVideoAt({ page, x, y }) fait ce que fait un clic à cet endroit, et pageVideoSpots(page, doc) liste l’emplacement de chaque vidéo sur une page, pour un hôte qui dessine ses propres commandes.

Deux recettes du livre de recettes composent des vidéos : la Nº 131, Un programme de ciné-club avec des codes QR sur les affiches, imprime chaque film comme un carton-titre avec une marque de lecture et un code QR, et la Nº 132, Une fiche de TP dont les extraits jouent à l’écran et dans l’EPUB, règle les options de lecteur pour l’édition HTML et embarque ses propres extraits dans un EPUB à mise en page fixe.

#Bandes dessinées

Les planches, les strips et les doubles pages de bande dessinée s’écrivent dans deux blocs délimités dont le moteur lit lui-même le corps, ligne par ligne : :::page et :::strip. À l’intérieur, les lignes ::panel ouvrent les cases et les lignes de script les lettrent. Le guide, avec les règles de mise en page, le lettrage et les sorties, est Bandes dessinées ; les réglages se trouvent dans Configuration › Bandes dessinées.

#:::page

:::page{split="30 [30 | 20 | *] / *" gutter=4mm}
::panel{art=lh-arrive}
caption: Every summer, Maya spent a week at the lighthouse.
maya: Grandpa! I'm here!
::panel{art=lh-radio focus="40% 50%"}
tomas: Just in time.
::panel{art=lh-maya}
maya{thought}: That valve looks loose…
::panel{art=lh-beam bleed}
sfx{rotate=-8}: KRAK
:::

Un bloc :::page est une planche : il ouvre une nouvelle page, l’occupe tout entière, et le texte qui suit son ::: de fermeture commence sur la page suivante. Ses attributs sont split (la découpe de la page en cellules : des tailles en pourcentage séparées par / pour les bandes et par | pour les cases côte à côte, une liste entre crochets pour redécouper une cellule, * pour le reste, a~b pour un trait oblique), gutter (une longueur, ou deux : entre les bandes et entre les cases ; un nombre seul s’entend en millimètres), style (un style de case nommé), bleed, direction (ltr ou rtl, aussi écrit dir) et spread (voir Doubles pages). Sans split, les cases s’empilent en bandes égales. Les blocs Markdown, les conteneurs et les directives ne sont pas lus dans le bloc ; les <!-- comments --> le sont.

#Cases

Une ligne ::panel{…} ouvre une case, qui remplit la cellule suivante dans l’ordre de lecture et s’étend jusqu’à la ligne ::panel suivante ou jusqu’à la clôture du bloc :

#Lignes de script

Chaque ligne d’une case est une bulle, un récitatif ou une onomatopée, écrite key{attributes}: text :

maya: Grandpa! I'm here!
tomas{whisper}: Shh. Listen.
caption{at=bottom-end}: Three streets away.
sfx{at="62% 40%" rotate=-8 size=1.4}: KRAK
ben{tail=start}: (from off the panel) Over here!
sfx{vertical size=2.6 font="Dela Gothic One"}: ドン
maya: This line goes on
  on the next line,\
  and breaks here.

• La clé est un id de personnage (lettres, chiffres, _, ., -), le même dans toutes les traductions ; caption, sfx et note sont réservés. Les deux-points peuvent être le ： pleine chasse.
• Un mot seul entre les accolades est un style de bulle (thought, whisper, shout, radio, inner ou l’un de comics.balloonStyles) ; style= dit la même chose.
• at fixe la bulle : un point en pourcentages de l’image de la case (at="62% 40%"), ou un coin ou un bord (top-start, top-end, bottom-start, bottom-end, top, bottom). to dirige l’appendice vers un point de l’image ; tail=none le supprime et tail=top|bottom|start|end|left|right le dirige hors de la case. join et join=false rattachent la bulle à la précédente du même personnage ou la tiennent à part ; break la laisse franchir la bordure, et ce franchissement n’est pas signalé comme un débordement. rotate (en degrés), size (un facteur d’échelle, pour les onomatopées), color et font modifient son lettrage.
• vertical et horizontal (ou mode=vertical, mode=horizontal) fixent le sens d’écriture de la ligne, au-dessus de celui du livre : un ドン non traduit composé en colonne dans une édition horizontale, une enseigne écrite en travers composée en ligne dans une édition verticale. Une colonne dans un livre d’une autre langue suit les règles de son propre texte (avec des kana, celles du japonais). Dans un livre vertical, une ligne sans caractères chinois ni japonais est de toute façon composée en ligne.
• Une ligne en retrait de deux espaces ou d’une tabulation prolonge la bulle du dessus ; une barre oblique inverse en fin de ligne y coupe le texte. Les lignes vides sont ignorées.
• Le texte est du Markdown en ligne : mise en relief (lettrée en gras italique), :tcy, :ruby (sa lecture composée au-dessus de la base, sauf au-dessus d’une base de droite à gauche), :ltr et :rtl (un passage maintenu dans son propre sens). Les notes de bas de page et les marques :ref ne sont pas lues.

#:::strip

:::strip{split="* | * | *" aspect=3 span=page placement=top}
::panel{art=pip-1}
pip: Morning, Otto!
::panel{art=pip-2}
::panel{art=pip-3}
otto: Is it?
:::

Un :::strip a le corps d’une planche, mais se place dans le texte comme un seul bloc insécable, découpé en cases : span (column, la valeur par défaut, ou page), placement (here, la valeur par défaut, là où il est écrit ; ou top, bottom, auto, flottant comme une figure), et sa taille, soit height (une longueur ; un nombre seul s’entend en millimètres), soit aspect (largeur sur hauteur : 3, 4/1, 4:1 ; par défaut, les proportions qui rendent ses cases carrées). Un strip sur toute la largeur de la page placé here sur une page de plusieurs colonnes coupe les colonnes à l’endroit où il se trouve, comme le fait un bloc sur toute la largeur de la page. width le rend plus étroit que la justification qu’il couvre (60% de celle-ci, ou une longueur) et align le place au start, au center (par défaut) ou à l’end de cette justification, dans le sens du texte. caption="…" compose une légende en dessous dans le style des légendes ; avec type=figure (un type de ressource), la légende prend le libellé et le numéro du type et le strip compte dans la séquence de ce type, et avec id=… un :ref le désigne. Sans split, les cases sont côte à côte. Les strips ne sont lus qu’au premier niveau d’un chapitre.

#Doubles pages

:::page{spread} étend une planche sur deux pages en regard : la découpe couvre les deux blocs de texte réunis au dos, sans leurs marges intérieures, et une case peut franchir le pli. La double page s’ouvre sur une page paire, après une page blanche si nécessaire. Voir Bandes dessinées › Doubles pages.

#Ce qui n’est PAS pris en charge

Postext ne reconnaît pas les fonctionnalités CommonMark suivantes. Elles sont soit traitées comme du texte brut (et apparaissent donc telles quelles dans la sortie), soit ignorées sans avertissement :

• Titres de style Setext : la forme soulignée par === / ---. Utilisez des titres ATX (#).
• HTML brut : les balises <tags> brutes ne sont pas interprétées. Les balises de style MDX ne sont pas prises en charge non plus ; la source Postext est du Markdown pur.
• Filets horizontaux : ---, ***, ___.
• Tableaux : les tableaux à barres verticales ne sont pas analysés. Les tableaux sont modélisés comme des ressources structurées dans PostextContent.resources.
• Liens par référence : [text][id] accompagné d’un bloc de définition.
• Liens automatiques : <https://example.com>.
• Sauts de ligne forcés par deux espaces en fin de ligne : les espaces sont supprimées. Terminez plutôt la ligne par une barre oblique inverse (voir Sauts de ligne).
• Texte barré : ~~text~~. Le rendu barré est pour l’instant réservé aux tâches terminées.
• Notes marginales : non implémentées, et PostextContent.notes, que les types acceptent, est ignoré par le moteur. Les notes de bas de page et les notes de fin de chapitre s’écrivent avec [^id] (voir Notes de bas de page) ; jusqu’à postext 1.5, il fallait les composer comme du texte.

Cette liste raccourcira avec le temps. D’ici là, tout ce qui n’est pas explicitement listé dans la partie consacrée aux éléments pris en charge doit être considéré comme du texte littéral.

Au-delà de la syntaxe, l’arabe et les autres écritures de droite à gauche sont composés de droite à gauche, avec l’algorithme bidirectionnel et une reliure à droite (voir Mise en page de l’arabe). Le chinois est composé horizontalement et verticalement, avec la coupure des lignes, les chasses de ponctuation, la justification entre les caractères, les marques, le ruby et le warichu qu’attend sa région (voir Mise en page du chinois). Le japonais est composé selon ses propres règles : kinsoku, espacement des yakumono, furigana, points d’emphase, marques kanbun et notes (voir Mise en page du japonais) ; le coréen passe par le même compositeur avec les règles du chinois continental. Des motifs de césure sont fournis pour huit langues, et des libellés intégrés pour ces huit langues, le chinois, le japonais et l’arabe. Voir Langues et écritures.

#Conventions de rédaction

Quelques conventions font la différence entre un document qui s’analyse proprement et un document qui vous réserve des surprises :

• Laissez une ligne vide entre les blocs. Deux paragraphes séparés par une ligne vide sont deux paragraphes. Deux paragraphes sur des lignes consécutives n’en font qu’un : chaque ligne se fond dans le paragraphe précédent.
• Les lignes vides supplémentaires n’ajoutent pas d’espace. Trois lignes vides séparent deux blocs exactement comme une seule. Pour plus d’espace entre eux, écrivez une ligne :::space.
• Alignez un élément imbriqué sur le texte de l’élément du dessus. Deux espaces sous une puce (- ), trois sous 1. , quatre sous 10. , comme CommonMark imbrique les listes ; deux espaces sous 1. imbriquent aussi. Un élément s’imbrique sous l’élément ouvert le plus proche dont le marqueur se trouve au moins deux colonnes à sa gauche ; une seule espace n’imbrique donc rien et aucun niveau n’est jamais sauté, quel que soit le pas (jusqu’à postext 1.15, la profondeur valait floor(spaces / 2) + 1, et un 1. sous 1. sortait au niveau 4). Une tabulation va jusqu’au multiple de quatre colonnes suivant. La profondeur est plafonnée à 5.
• N’indentez pas le premier élément d’une liste. Les éléments de niveau 1 commencent à la colonne 0. Le premier élément d’une liste ouvre le niveau 1 quel que soit son retrait (jusqu’à postext 1.15, ses espaces de tête augmentaient la profondeur) ; pour imbriquer, il faut donc un élément au-dessus sous lequel s’imbriquer.
• Les marqueurs de tâche s’écrivent entre crochets avec une seule espace. [ ], [x], [X], sans variante. [*] ou [-] ne sont pas des marqueurs de tâche ; ils s’affichent comme du texte littéral.
• Les citations dans les listes ne sont pas prises en charge. Commencez la citation à la colonne 0, hors de la liste.
• Les images et les tableaux vivent dans resources. Le ![alt](src) en ligne est supprimé, justement parce que les images en ligne empêchent un placement qui tienne compte des colonnes. Déclarez chaque image comme une ressource et désignez-la par son id : le moteur décide alors si elle flotte, interrompt la colonne ou passe en haut de la page suivante.
• Échappez le signe dollar avec \$ quand il ne s’agit pas de mathématiques. Postext interprète $…$ comme du LaTeX en ligne ; un $ brut dans la prose ouvre donc une formule. Les prix, les invites de shell et tout ce qui comporte un signe dollar isolé doivent s’écrire \$.
• Tapez le balisage en ASCII, y compris dans un texte chinois ou japonais. Une méthode de saisie chinoise ou japonaise produit des formes pleine chasse : ：：： pour une clôture, ＃ pour un titre, ［＾1］ pour un appel de note, ｛…｝ pour des attributs, ＊＊ pour le gras. Elles s’impriment comme du texte, et la compilation signale la ligne par un avertissement fullwidthMarkup qui indique la forme ASCII à taper. Les valeurs d’attribut peuvent être dans n’importe quelle écriture et entre “…” ou 「…」 ; les clés restent en ASCII.

#Exemple complet

Un court document qui utilise chacune des constructions prises en charge :

---
title: The Typesetter's Craft
author: Anon
---
 
# Opening
 
A good book reads itself. The **reader** should never notice the
typesetter's work — only the author's voice.
 
## What makes text readable
 
Three properties matter most:
 
1. Line measure — 40 to 75 characters per line.
2. Leading — 1.3 to 1.5 times the font size.
   a. Tighter at short measures.
   b. Looser at long measures.
3. Contrast between body and headings.
 
Common failure modes include:
 
- Lines that stretch across the whole page.
- Headings that float without a following paragraph.
- Orphans and widows at column boundaries.
 
> Typography is the craft of endowing human language with a durable
> visual form.
> — Robert Bringhurst
 
### Review checklist
 
- [x] Column width under 75 characters
- [x] Leading set to 1.5
- [ ] Orphan and widow pass
- [ ] Final proofread
 
### A note on formulas
 
Inline math such as $a^2 + b^2 = c^2$ flows with the surrounding text, and
display math sits centred on the baseline grid:
 
$$
\int_0^1 x^2\,dx = \tfrac{1}{3}
$$

Ce même document, passé par le moteur de mise en page, produit un VDTDocument structuré dont les pages portent chacun de ces blocs sous forme d’entrées typées ; voyez la page Architecture pour comprendre comment les blocs deviennent de la géométrie.