Configuration : texte et titres

#Texte courant

La propriété bodyText règle la typographie de tout le texte des paragraphes.

#Citations

Une citation (lignes qui commencent par >) reprend la famille, le corps, l’interlignage, les graisses, l’alignement et la césure du texte courant. bodyText.blockquote règle le reste ; non défini, une citation a l’aspect qu’elle avait jusqu’à postext 1.4 : grise, en italique, avec le retrait de première ligne du texte courant et sans retrait latéral.

bodyText: {
  firstLineIndent: { value: 1.5, unit: 'em' },
  // Upright verse in the body colour, set in by 2 em, no first-line indent.
  blockquote: { color: { hex: '#241f26', model: 'hex' }, italic: false, indent: { value: 2, unit: 'em' }, firstLineIndent: { value: 0, unit: 'em' } },
}

Dans le Sandbox, ces réglages forment le groupe Citations de la section Texte courant.

#Vers

Un poème :::verse dont les vers ne portent pas de séparateur d’hémistiches est composé vers par vers (voir Format du document › :::verse). bodyText.verse donne les valeurs par défaut de ces poèmes ; un attribut du même nom sur la clôture d’ouverture d’un poème le règle pour ce poème.

bodyText: {
  // Turnovers flush right behind a bracket; tankas kept whole.
  verse: { turnover: 'right', keepStanzas: 5 },
}

Une configuration enregistrée avant ces réglages (configVersion 8 ou antérieure) qui met en page un poème sans séparateur est lue avec layout: 'bayt' : le poème garde les lignes centrées que lui donnait postext 1.22. Une configuration enregistrée par postext 1.23 (configVersion 9) qui compose un poème vers par vers est lue avec tighten: false : ses vers passent à la ligne là où la 1.23 les faisait passer.

Dans le Sandbox, ces réglages forment le groupe Vers de la section Texte courant.

#Taquets de tabulation

bodyText.tabStops énumère les taquets vers lesquels va une tabulation : :tab, ou un caractère de tabulation dans un paragraphe qui a des taquets (voir Format du document › Tabulations et taquets pour le balisage et la composition d’une ligne). Les tabStops d’un style de paragraphe les remplacent pour ses paragraphes, et le body.tabStops d’un style d’encadré à l’intérieur de ses encadrés ; une liste vide n’en définit aucun. Chaque taquet est un TabStop :

bodyText: {
  tabStops: [
    { position: { value: 30, unit: 'mm' } },
    { position: 'end', align: 'end', leader: '.', leaderGap: { value: 2, unit: 'pt' } },
  ],
  tabInterval: { value: 10, unit: 'mm' },
}

tabInterval ajoute des taquets à chaque intervalle depuis le début de la ligne, au-delà du dernier taquet de la liste ; sans lui, une tabulation située après le dernier taquet est une espace entre les mots. Un caractère de tabulation saisi dans le texte n’est une tabulation que dans un paragraphe dont le style a des taquets ou un intervalle, les siens ou ceux du texte courant ; partout ailleurs il reste l’espace entre les mots qu’il a toujours été : un document enregistré se met en page comme avant et n’a besoin d’aucun verrouillage.

Les taquets sont vérifiés avec le reste de la configuration (voir Avertissements de configuration) : une clé inconnue dans un taquet (leaders) est signalée comme unknownConfigKey avec la clé la plus proche ; un align qui n’est aucun des quatre comme unknownConfigValue, et le taquet est composé en 'start' ; une position qui n’est ni une longueur, ni 'end', ni un pourcentage comme unknownConfigValue avec used: 'none', et le taquet est ignoré.

La couleur et la police des points de conduite sont celles du paragraphe ; il n’existe pas encore de réglage qui leur soit propre.

#Lettrines

Un paragraphe du texte courant peut s’ouvrir sur une lettrine : sa première lettre composée en grand à côté de ses premières lignes, raccourcies de la largeur de la lettre et d’un blanc, et composées comme toutes les autres lignes (coupées par Knuth–Plass, justifiées, avec césure). Un style de paragraphe en donne une au premier paragraphe de chaque groupe :::paragraphs de ce style (à chaque paragraphe avec each: true, pour un catalogue d’entrées) ; un niveau de titre ou un style de titre en donne une au premier paragraphe de texte courant qui suit le titre (voir le champ dropCap de Réglages par niveau, de Styles de paragraphe et de Styles de titre). Le paragraphe qui suit le titre est trouvé au-delà des clôtures de conteneurs, des directives, des encadrés sortis du flux et des figures flottantes, comme le trouve indentAfterHeading ; un paragraphe à l’intérieur d’un encadré, d’un élément de liste, d’une citation, d’un poème ou d’une note n’en prend jamais. Dans le texte, {dropcap}, {dropcap=false} et {dropcap=N} sur une ligne de titre ou sur une clôture :::paragraphs l’activent, la désactivent ou règlent son nombre de lignes pour ce chapitre ou ce groupe (voir Format du document › Lettrines). Depuis postext 1.23.

headings: {
  levels: [
    { level: 1, dropCap: { lines: 3, fontFamily: 'Libre Bodoni', fontWeight: 700, color: { hex: '#8b2e2a', model: 'hex', paletteId: 'accent' }, leadIn: { words: 3 } } },
  ],
},

Comment la lettre est composée :

• Corps. Les deux hauteurs de capitale, celle du texte et celle de l’initiale, sont mesurées sur leurs caractères (l’encre d’un H ; de l’initiale elle-même dans un texte chinois ou japonais), et une police qui ne fournit pas de métriques d’encre compte ses capitales à 0,72 de son corps. Le corps par défaut convient à toute paire de caractères : aucune correction par police n’est nécessaire. Le dropCap d’un texte de maquette garde sa valeur fixe de 0,72 (voir Éléments de texte).
• La lettre et son mot. L’initiale prend des grappes de graphèmes entières. Le reste du premier mot la suit sans espace ; un mot d’une seule lettre (A, Y) garde son espace au début de la première ligne. Le retrait de première ligne du paragraphe est supprimé. La copie, la recherche, la table de correspondance avec la source et le curseur du Sandbox lisent le paragraphe tel qu’il est écrit : le texte brut du bloc inclut la lettre, le plainStart de la première ligne compte au-delà d’elle, et VDTBlock.dropCap contient son étendue et sa géométrie sur le fragment qui porte la première ligne.
• Une initiale montante (lines: 1 avec un fontSize plus grand, ou sink inférieur à lines) s’élève au-dessus de la première ligne, et le paragraphe garde ce dépassement dégagé au-dessus de lui, en lignes de grille entières, pour qu’il ne chevauche pas le texte situé au-dessus.
• Coupure. Le paragraphe ne se coupe jamais avant la ligne sink : il passe entier à la colonne ou à la page suivante, sauf s’il est seul dans une colonne vide qui ne peut pas contenir ces lignes ; il se coupe alors quand même et émet un avertissement dropCap. Un titre gardé avec son texte garde ces lignes sous lui. La partie qui continue dans la colonne suivante n’a ni initiale ni lignes raccourcies ; recoupé pour une colonne d’une autre largeur, les premières lignes gardent leur retrait. L’équilibrage des colonnes peut composer le paragraphe plus lâche ou plus serré comme tout autre, et n’ajoute jamais d’espace entre les lignes raccourcies.
• Écritures. Les lignes sont raccourcies du côté du début : à gauche dans un texte latin, à droite en arabe et en hébreu. Une lettre qui se lie à la suivante (arabe, syriaque, n’ko) n’est pas détachée, et le paragraphe émet un avertissement dropCap ; le chinois et le japonais horizontaux prennent une initiale d’un caractère (首字下沉). Le texte vertical n’en prend pas (avertissement). Un paragraphe qui ne s’ouvre ni sur une lettre ni sur un chiffre (un renvoi, une formule, un appel de note) n’en prend pas non plus (avertissement).
• Sorties. Le canvas, la visionneuse HTML et l’EPUB à mise en page fixe peignent l’initiale à côté des lignes ; le HTML l’écrit juste avant le texte de la première ligne, sans rien entre les deux, pour qu’un lecteur d’écran lise le mot entier. Dans un PDF balisé, l’initiale fait partie du P du paragraphe et forme, avec le reste de son mot, un Span dont l’/ActualText est le mot : l’extraction du texte lit Long before, jamais L ong before. Un EPUB recomposable la compose comme un initial-letter CSS (lines, sink), flottante là où le système de lecture ne le prend pas en charge.

Les réglages sont vérifiés avec le reste de la configuration (voir Avertissements de configuration) : une clé inconnue dans une lettrine ou dans son attaque est signalée comme unknownConfigKey ; une punctuation ou un shortParagraph qui n’est aucun de ses mots, ou un lines, sink ou characters qui n’est pas un nombre entier à partir de 1, comme unknownConfigValue, et la valeur par défaut est utilisée. Les lettrines sont désactivées par défaut : aucun document enregistré ne change.

#Une seule famille par fontFamily

fontFamily (ici et dans tous les autres champs de famille de caractères : headings.fontFamily, tableStyle.bodyFontFamily, separatorFontFamily, le fontFamily d’un style de pastille ou d’un élément de maquette…) nomme une seule famille. Le canvas, la sortie HTML et le PDF doivent composer le même caractère, et le PDF incorpore une police par famille sans chaîne de repli : une pile de polices CSS n’a donc rien sur quoi se replier. Une pile est composée dans sa première famille et signalée par un avertissement de configuration :

bodyText: { fontFamily: "'EB Garamond', Georgia, serif" } // set in EB Garamond

Chargez cette famille avant la mise en page (voir Polices personnalisées et le fournisseur de polices dans Générer des PDF) ; si elle manque, le navigateur mesure avec sa police par défaut, quoi que dise le reste de la pile. Une virgule entre guillemets fait partie d’un nom ('"Foo, Bar"' est une seule famille).

#Césure

Quand l’alignement du texte vaut 'justify', la césure évite un espacement excessif entre les mots en coupant les mots longs aux limites de syllabes. Le moteur utilise les motifs TeX/Liang pour trouver les points de coupure naturels aux limites de syllabes. Voir Césure et justification pour une explication détaillée. Le texte en drapeau ne reçoit de césure que si vous la demandez : voir Texte en drapeau plus bas.

Langues prises en charge : 'en-us' (anglais), 'es' (espagnol), 'fr' (français), 'de' (allemand), 'it' (italien), 'pt' (portugais), 'ca' (catalan), 'nl' (néerlandais).

Les sous-étiquettes de région, d’écriture et de variante sont ignorées au moment de choisir les motifs, de même que la casse et les séparateurs _ : 'es-ES', 'es-MX' et 'es_419' coupent avec 'es', 'pt-BR' avec 'pt', et toute étiquette anglaise ('en', 'en-GB') avec 'en-us', les seuls motifs anglais fournis : un texte britannique reçoit donc des coupures américaines. Une langue sans motifs fournis ('sv', 'pl', 'fi'…) est coupée avec les motifs 'en-us', ce qui donne de mauvaises coupures plutôt qu’aucune ; le moteur le signale une fois par étiquette avec un console.warn, et le Sandbox l’affiche dans son panneau Vérifications. Réglez enabled: false pour un tel document ; cela fait aussi taire l’avertissement. Le chinois, le japonais et le coréen (zh, ja, ko, quelles que soient la région ou l’écriture) n’ont pas besoin de motifs et n’affichent aucun avertissement : un document dans l’une de ces langues est composé sans césure. Pour couper les mots latins qui y sont cités, réglez enabled: true et nommez leur langue dans locale ('en-us' pour l’anglais). enabled: true sans locale, ou avec une locale chinoise, japonaise ou coréenne, laisse la césure désactivée et l’indique une fois dans la console. matchHyphenationLocale(tag) renvoie la langue fournie qui correspond à une étiquette (undefined s’il n’y en a aucune), et HYPHENATION_LOCALES énumère les langues fournies. La configuration résolue (doc.config.bodyText.hyphenation) nomme dans locale les motifs réellement utilisés, et garde dans tag l’étiquette que vous avez donnée quand elle diffère. Le moteur PDF déclare la langue du document d’après la locale de premier niveau, et d’après cette étiquette seulement quand locale n’est pas définie (voir Langue du document).

import { matchHyphenationLocale } from 'postext';
 
matchHyphenationLocale('es-MX'); // 'es'
matchHyphenationLocale('en-GB'); // 'en-us'
matchHyphenationLocale('sv');    // undefined: hyphenated with 'en-us', with a console warning

Les mots de moins de 5 caractères ne sont jamais coupés. Le moteur exige au moins 2 caractères avant et 3 caractères après un point de coupure.

Mots gardés entiers

Un dictionnaire coupe un nom comme n’importe quel mot : Al-ice, Áms-ter-dam, You-Tu-be. Trois réglages gardent des mots entiers, et tous trois valent par défaut ce que fait le dictionnaire.

hyphenation.exceptions est une liste de mots, comme le \hyphenation{…} de TeX. Une entrée écrite sans trait d’union n’est jamais coupée ; une entrée écrite avec des traits d’union n’est coupée qu’à ces endroits : 'You-Tube' donne You- · Tube et rien d’autre. Une entrée correspond à une suite de lettres, quoi qui l’entoure : 'Alice' couvre (Alice, et Alice’s, et un composé est comparé partie par partie (Blender-based correspond à 'Blender'). Une forme fléchie est un autre mot et demande sa propre entrée. Une entrée en minuscules correspond au mot quelle que soit sa casse ('blender' couvre Blender et BLENDER) ; une entrée à capitale initiale ne correspond qu’aux occurrences qui commencent par une capitale : 'Rose' garde le nom entier et laisse rose au dictionnaire. Les entrées ne contiennent que des lettres et des traits d’union ; tout le reste est supprimé.

hyphenation.capitalized: false garde entier tout mot qui commence par une capitale : les noms, les sigles, et aussi le premier mot de chaque phrase. C’est l’option « Césure des mots en majuscules » d’InDesign désactivée, et le \uchyph=0 de TeX. Une entrée de exceptions avec des traits d’union coupe toujours son mot à ces endroits. L’allemand met une capitale à tous les noms : l’option laisserait à un texte allemand à peine un mot à couper. Nommez-y plutôt les mots dans exceptions, ou utilisez citations.hyphenateNames.

citations.hyphenateNames: false garde entiers les noms de famille des auteurs que le document cite, où qu’ils se trouvent : dans une citation, dans le texte courant et dans la liste des références. Voir Citations.

const config: PostextConfig = {
  locale: 'es',
  bodyText: {
    hyphenation: { exceptions: ['Ámsterdam', 'Blender', 'You-Tube'] },
  },
};

Les trois atteignent tout texte que coupe le dictionnaire : texte courant, titres, listes, encadrés, légendes, cellules de tableau, notes, titres courants et les autres textes de maquette. C’est plus large que compounds, que les légendes, les notes, les cellules et la table des matières ignorent. Deux choses restent telles quelles. Un trait d’union conditionnel saisi dans une occurrence d’un mot décide toujours de cette occurrence, et un trait d’union conditionnel placé avant la première lettre garde une occurrence entière sans liste (voir Là où une ligne ne se coupe jamais). Et un mot plus large que toute sa ligne est toujours coupé : aux points de son entrée s’il en a, sinon aux syllabes du dictionnaire. Moins de mots coupés laissent à une colonne justifiée étroite moins de façons de remplir ses lignes : examinez l’espacement des mots après avoir désactivé capitalized sur une page à trois colonnes. L’EPUB recomposable laisse la césure au système de lecture, qui ignore tout de ces règles.

Texte en drapeau

Par défaut, seul le texte justifié reçoit la césure : avec textAlign: 'left', et dans les styles de paragraphe alignés à gauche, centrés ou à droite, chaque mot reste entier, aussi irrégulier que devienne le bord, sauf à un trait d’union conditionnel (U+00AD) saisi dans le texte. Réglez hyphenation.ragged: true pour appliquer aussi la césure au texte en drapeau.

Une ligne en drapeau n’est jamais étirée : couper chaque mot qui ne tient pas frangerait le bord de traits d’union. La zone de césure le limite, comme le fait le compositeur ligne à ligne d’un logiciel de PAO. Quand un mot ne tient pas en fin de ligne, le moteur regarde le blanc que laisserait son envoi entier à la ligne suivante. Si ce blanc est plus large que zone, le mot est coupé à la dernière syllabe qui tient ; sinon il descend entier. Une zone en em se rapporte au corps propre du texte. La valeur par défaut, 3em, ne coupe que les mots qui laisseraient une ligne nettement courte. Une zone plus large donne moins de traits d’union et un bord plus irrégulier ; 0 coupe tout mot qui ne tient pas. En composition ligne par ligne, pas plus de deux lignes consécutives ne se terminent sur une syllabe. Les traits d’union durs (enseñanza-aprendizaje), les jointures d’URL, les traits d’union conditionnels saisis dans le texte et les mots plus larges que toute la ligne se coupent comme toujours : la zone et la limite de deux lignes ne régissent que les syllabes du dictionnaire.

Le réglage vaut pour tout le document. Il s’applique au texte courant et aux citations quand ils sont en drapeau, et à tout style de paragraphe et corps d’encadré en drapeau dont la propre hyphenation est activée (elle vaut par défaut le hyphenation.enabled du texte courant) : hyphenation: false garde donc entiers les mots d’un style. Les titres, les légendes, les notes, les cellules de tableau et la table des matières ne reçoivent pas de césure ; là, comme partout, seul un mot plus large que toute la ligne est coupé. Le texte de maquette (titres courants, ouvertures, pages de partie) suit l’option hyphenate propre à chaque élément de texte, que règlent les ouvertures pleine page et les pages de partie intégrées, et utilise aussi le dictionnaire du document. Le texte justifié ignore ragged et zone.

const config: PostextConfig = {
  locale: 'es',
  bodyText: {
    textAlign: 'left',
    // A little more hyphenation than the 3 em default.
    hyphenation: { ragged: true, zone: { value: 2, unit: 'em' } },
  },
};

Avec optimalRagged (la valeur par défaut), le texte courant en drapeau est coupé avec Knuth-Plass, et la zone y garde son sens : un mot n’est coupé que s’il ne tient pas dans le reste de la ligne et que l’envoyer entier à la ligne suivante laisserait vide plus que la zone. Deux syllabes consécutives ne sont pas refusées, mais coûtent ce que coûtent deux traits d’union consécutifs dans le texte justifié : une troisième est donc rare. Avec optimalRagged: false, ou optimalLineBreaking: false, chaque ligne est remplie avant la suivante, comme jusqu’à postext 1.4.

La césure en drapeau met les paragraphes en page avec le moteur de coupure qu’utilisent toujours les paragraphes à mise en forme en ligne (gras, italique, liens, mathématiques) : l’activer peut donc déplacer quelques coupures autres que des traits d’union. Sur une ligne en drapeau, outre les espaces et les syllabes du dictionnaire, ce moteur coupe après un trait d’union dur ou un tiret entre deux mots (largas—separadas ; avec breakAfterDashes, tout tiret collé entre deux mots, riddles.—I et riddles—*and* aussi), aux jointures d’URL et entre idéogrammes, et il garde ensemble un mot composé en plusieurs passages (**Nota**:, (*véase*). Sans césure en drapeau, un paragraphe en drapeau sans mise en forme est coupé par Knuth-Plass quand optimalRagged est activé (la valeur par défaut) : aux espaces entre les mots, après un trait d’union dur entre deux lettres (meta- · analyses), comme le fait l’autre moteur, et, avec breakAfterDashes, après les tirets collés. Composé ligne par ligne, il passe par le moteur de coupure de pretext, qui diffère sur trois points : il peut aussi couper avant un tiret qui ferme une incise ou après un tiret qui l’ouvre (él · — y), après une barre oblique quand il applique la césure (km/ · h), et il coupe un mot plus large que la ligne à n’importe quel caractère sans trait d’union, là où l’autre moteur le coupe d’abord à une syllabe.

Dans le Sandbox, l’option s’appelle Césure du texte en drapeau ; elle se trouve sous l’alignement des paragraphes de la section Texte courant, avec la zone en dessous. Quand le texte courant est justifié, la même option se trouve avec les réglages de justification, pour les styles de paragraphe et les encadrés en drapeau.

#Langue du document

La locale de premier niveau est la langue du document dans son ensemble. Elle prend les mêmes valeurs que hyphenation.locale et sert de valeur de repli quand ce champ n’est pas défini : un livre espagnol n’a besoin que de locale: 'es' pour recevoir une césure espagnole. Elle choisit aussi la langue des chaînes de continuation intégrées des tableaux et des encadrés coupés ((cont.) / Continued contre Continúa, voir Tableaux plus hauts que la page et Marques sur un encadré coupé) et des numéros de titre écrits en toutes lettres (Chapter One contre Capítulo uno, voir Numéros en toutes lettres), et c’est la langue balisée dans un PDF accessible. Non définie, le moteur suppose 'en-us' ; le Sandbox se replie sur la langue de l’interface et règle le champ sous Maquette › Système d’écriture.

Elle choisit aussi les types de ressources intégrés. Quand resourceTypes n’est pas défini, buildDocument numérote et légende avec defaultResourceTypes(locale) : locale: 'de' seul donne Abbildung 1.1 et Tabelle 1.1. Quand locale n’est pas définie, la langue de césure la remplace, pour les types de ressources comme pour les chaînes des tableaux. Une liste resourceTypes explicite l’emporte toujours. Les versions antérieures utilisaient les types anglais quelle que soit la locale, sauf si vous passiez vous-même defaultResourceTypes(locale) ; un document qui définit locale et veut garder les étiquettes anglaises passe resourceTypes: defaultResourceTypes('en'). Les livres du Sandbox et les paquets portent leur propre liste : ils ne sont pas concernés.

Toute étiquette BCP 47 fonctionne ici comme dans hyphenation.locale : 'de-AT' reçoit les chaînes allemandes. Les chaînes intégrées existent dans les huit langues que la césure prend en charge, en chinois (en caractères simplifiés et en caractères traditionnels), en japonais et en arabe ; toute autre langue reçoit les chaînes anglaises.

Le chinois accepte zh, zh-Hans, zh-Hant, zh-CN, zh-SG, zh-TW, zh-HK, zh-MO et les formes longues (zh-Hant-TW), quelle que soit la casse et avec - ou _. Les chaînes suivent l’écriture, lue avec Intl.Locale(tag).maximize() : zh, zh-CN et zh-SG sont en caractères simplifiés, zh-TW, zh-HK et zh-MO en caractères traditionnels. Les valeurs typographiques par défaut qui dépendent de la langue suivent plutôt la région, comme le recommande clreq §1.2 : CN, SG et MY comptent comme la Chine continentale, TW comme Taïwan, HK et MO comme Hong Kong, et une étiquette sans région se règle sur son écriture (zh-Hant est Taïwan, zh et zh-Hans la Chine continentale). Le japonais accepte ja, ja-JP, ja-Jpan et toute autre étiquette ja (isJapaneseLanguage(tag)) ; depuis postext 1.16, il a ses propres chaînes et sa propre région, japan, dont les valeurs typographiques par défaut suivent la JLReq (voir Mise en page japonaise). Une table de chaînes sans entrée japonaise donne l’anglais, jamais le chinois. localeScript(tag), cjkRegionOf(tag), stringsKeyOf(tag) et sameContentLocale(a, b) donnent ces lectures, et DOCUMENT_LANGUAGES énumère les langues qui ont des chaînes intégrées, chacune nommée dans sa propre langue (日本語 entre les entrées chinoises et العربية), telles que les affiche le sélecteur Langue du document du Sandbox.

Le préfixe de légende est le nom du type (Figure 1.1.). Les types chinois numérotent dans le chapitre avec un trait d’union, {h1}-{n} (图 1-1) ; avec les réglages de légende labelNumberGap: '' et labelSeparator: '　', la légende se lit 图1-1　标题 (voir Style de légende). L’index suit lui aussi la langue : 见 et 另见 devant un renvoi, 符号 et 数字 au-dessus des symboles et des nombres en chinois simplifié ; 見, 另見, 符號 et 數字 en chinois traditionnel. Le japonais numérote ses types de la même façon et compose ses légendes 図1-1　題 sans ces deux réglages, écrit les renvois 第3章, 2.3節 et 12ページ, intitule la bibliographie 参考文献, et son index imprime 記号 et 数字 au-dessus des symboles et des nombres et écrit ses renvois avec une flèche, →夏目漱石 pour voir et →夏目漱石、森鷗外も見よ après les pages pour voir aussi, les étiquettes en romain. L’arabe numérote ses types de la même façon, {h1}-{n} (شكل 2-3), écrit les renvois الفصل 3, القسم 2-1 et ص 12, intitule la bibliographie المراجع, et son index imprime انظر / انظر أيضًا, رموز et أرقام, avec la virgule et le point-virgule arabes (، ؛).

Un document chinois, japonais ou coréen déclare sa langue dans la sortie HTML (lang sur la racine .pt-doc, zh-Hant-TW gardé entier) et sur le canvas qu’il peint (ctx.lang, dans Chrome 136 et ultérieur) : le navigateur dessine ainsi les formes de glyphes de la région. Unicode unifie les caractères han, et un même point de code n’a pas le même aspect dans une police taïwanaise et dans une police japonaise. Depuis postext 1.30, tous les autres documents le font aussi, dans la langue dans laquelle leur texte est mis en forme (bodyText.shapingLanguage: 'document', la valeur par défaut) ; avec 'host', les autres documents ne portent pas de lang, et chaque canvas peint dans la langue de la page qui l’héberge. Le PDF déclare /Lang d’après locale pour tout document, balisé ou non, avec son écriture et sa région. Un document dans une langue écrite de droite à gauche (arabe, persan, ourdou, hébreu…) déclare aussi sa langue : les formes propres à la langue de la police (locl) et la police de repli la suivent.

const config: PostextConfig = {
  locale: 'es',
  bodyText: { textAlign: 'justify', hyphenation: { enabled: true } }, // hyphenates in Spanish
};

Chiffres du document

Le numerals de premier niveau règle les chiffres de chaque nombre que le moteur écrit : numéros de page et étiquettes de page de la table des matières, de l’index et des renvois de page ; numéros des listes ordonnées et des notes de bas de page ; compteurs de titres et de chapitres, {chapterNumber} ; le {h1} et le {n} d’un numéro de figure et d’un renvoi vers elle ; {totalPages}, {bookTotalPages} et {numberDecimal}. 'latn' écrit 0–9, 'arab' les chiffres arabes orientaux ٠–٩ et 'arabext' les chiffres persans ۰–۹. Seul le format décimal change (decimal, le arabic des listes, ou un réglage laissé à sa valeur par défaut) : un format que l’auteur nomme s’imprime tel qu’il est nommé. lower-roman reste i, ii, iii, et arabic-indic dans un document latin écrit toujours ١, ٢, ٣. Le texte du document n’est jamais réécrit.

La valeur par défaut, 'auto', prend les chiffres de locale (defaultNumeralsFor(tag)) : 'arab' pour l’arabe sans région ou avec toute région hors du Maghreb (ar, ar-EG, ar-SA, ar-AE…), 'latn' pour ar-MA, ar-DZ, ar-TN, ar-LY, ar-MR et ar-EH, 'arabext' pour le persan (fa), le pachto (ps) et l’ourdou de l’Inde (ur-IN), et 'latn' pour tout le reste, y compris l’ourdou du Pakistan. Le CLDR donne latn pour un ar seul et pour ar-AE ; les livres arabes du Machrek et du Golfe impriment ٠–٩, et c’est ce que suit Postext. Une étiquette qui nomme ses chiffres les garde : ar-MA-u-nu-arab. Une page numérotée avec les chiffres du document enregistre arabic-indic ou persian comme pageNumberFormat : les étiquettes de page du PDF montrent les mêmes chiffres. Une valeur inconnue suit la langue et est signalée comme unknownNumerals.

Les nombres que l’auteur saisit sont lus dans n’importe lequel des trois systèmes : un élément de liste ٣. commence à 3, et {startAt=٥}, :::numbering{startAt=٥}, :::space{lines=٢} et :::part{number="٣"} (pour {numberDecimal}) lisent la valeur.

const config: PostextConfig = { locale: 'ar' };                     // ١، ٢، ٣
const maghreb: PostextConfig = { locale: 'ar-MA' };                 // 1, 2, 3
const forced: PostextConfig = { locale: 'ar', numerals: 'latn' };   // 1, 2, 3

Sens du texte

La direction de premier niveau règle le sens de base du document : 'ltr', 'rtl', ou 'auto' (la valeur par défaut), qui vaut 'rtl' quand l’écriture de locale s’écrit de droite à gauche (arabe, persan, ourdou, hébreu, syriaque, thâna, n’ko, adlam…, lu par directionOf(tag)) et 'ltr' sinon. Un document de droite à gauche est mis en page dans un cadre en miroir : ses lignes commencent à droite, sa première colonne est celle de droite, ses retraits, marques de liste, flottants, notes de bas de page et encadrés se placent à droite, et page.binding: 'auto' le relie à droite. La configuration résolue ne porte direction: 'rtl' que pour un tel document : un document de gauche à droite se résout comme avant. Une valeur inconnue est lue comme 'auto' et signalée comme unknownConfigValue. L’algorithme bidirectionnel Unicode (UAX #9) ordonne les passages de chaque ligne dans les deux sens : une citation arabe dans un livre anglais se lit de droite à gauche à sa place.

Dans le document, un titre ou un conteneur ::: prend {dir=ltr} ou {dir=rtl}, et les isolats en ligne :ltr[…] et :rtl[…] isolent un passage de texte (voir Le sens du texte dans le balisage) ; une ressource de tableau prend table.direction. Un bloc composé à contresens du document garde son propre côté de début : son retrait, ses marques de liste et l’extrémité de sa dernière ligne passent du côté où commence son texte.

Un réglage qui nomme un côté désigne un côté du texte ou du flux du texte courant, jamais de la feuille : une maquette conçue pour un livre anglais fonctionne quand le livre passe à l’arabe. 'start' et 'end' sont acceptés comme noms explicites :

placement.rotate garde son sens physique sur une page en miroir : une figure tournée dans le sens horaire est tournée dans le sens horaire sur la feuille. Un hôte qui lit la mise en page trouve le cadre en miroir sur chaque page (VDTPage.flow avec direction: 'rtl', pageIsMirrored(page)) et l’ordre visuel des segments de chaque ligne dans VDTLine.order ; flowToPage et pageToFlow font la correspondance entre le flux et la feuille. Voir Mise en page arabe.

const arabic: PostextConfig = { locale: 'ar' };                        // right to left, bound on the right
const english: PostextConfig = { locale: 'en', direction: 'rtl' };     // forced; rarely what you want

#Langues et écritures

Postext compose les écritures alphabétiques de gauche à droite, ainsi que le chinois et le japonais horizontalement et verticalement. Mise en page chinoise et Mise en page japonaise expliquent comment ils sont composés et quels réglages les contrôlent ; les clés se trouvent sous Typographie d’Asie de l’Est, Écriture verticale et Reliure. Ce que reçoit chaque écriture :

• Le chinois est composé par le compositeur CJC quand un paragraphe contient plus de caractères CJC que d’espaces entre les mots : ses lignes se coupent entre les caractères selon les règles de début et de fin de ligne de cjk.lineBreak (aucune ligne ne commence par 。、」 ou ー, aucune ne se termine par 「 ou （), gardent entiers —— et ……, un nombre avec ses signes et un mot latin, et une ligne justifiée est étirée entre ses caractères jusqu’à la largeur de ligne. Les largeurs de ponctuation, la ponctuation suspendue, l’espace entre han et latin, la grille de caractères, les points d’emphase, les marques de nom propre et de titre d’ouvrage, les ruby et les notes warichu suivent la région de locale, à l’horizontale comme à la verticale (layout.writingMode: 'vertical-rl'). Un paragraphe latin qui cite quelques mots CJC garde la coupure optimale des lignes et peut couper à côté d’eux ; un crochet CJC, le point médian ou un signe pleine chasse cité dans un texte latin (〈h〉, ％) ne change rien.
• Le japonais passe par le même compositeur avec ses propres règles depuis postext 1.16, celles des Requirements for Japanese Text Layout du W3C (JLReq) et de la JIS X 4051 : une locale ja donne la région japan, dont les valeurs automatiques règlent les niveaux de kinsoku de la JLReq (les petits kana et ー n’ouvrent jamais une ligne), la ponctuation pleine chasse avec compression des paires, un cadratin après ？！, le crochet qui ouvre un paragraphe dans la seconde moitié du retrait, les points d’emphase en sésame au-dessus du texte, les titres d’ouvrage en 『』, les furigana espacés en 1:2:1, les compteurs japonais, les notes et un index trié par lecture. Les versions antérieures composaient le japonais avec les valeurs par défaut de la Chine continentale.
• Le coréen passe par le même compositeur et est composé sans césure, mais avec les valeurs par défaut de la Chine continentale : ses propres règles (KLREQ) ne sont pas implémentées. Le texte coréen se coupe entre les syllabes ainsi qu’à ses espaces.
• L’arabe et les autres écritures de droite à gauche (persan, ourdou, hébreu…) sont composés de droite à gauche : Mise en page arabe explique comment. La direction du document vient de l’écriture de locale, l’algorithme bidirectionnel Unicode ordonne les mots latins et les nombres à l’intérieur de chaque ligne, le livre est relié à droite avec sa première colonne à droite, et chaque nombre que le moteur écrit prend les chiffres de la région. Un mot qui contient une lettre d’écriture arabe n’est jamais coupé en fin de ligne, interlettré ni tronqué, et une ligne arabe justifiée est étirée à ses espaces et par des kachidas. Les signes vocaliques, l’emphase, les notes de bas de page et les chaînes de l’arabe se trouvent sous Texte arabe. Le persan, l’ourdou et l’hébreu reçoivent le sens, les chiffres et les règles des mots entiers, mais aucune chaîne intégrée qui leur soit propre.

Les motifs de césure sont fournis pour huit langues (en-us, es, fr, de, it, pt, ca, nl) ; les types de ressources intégrés et les chaînes de continuation existent dans ces huit langues, en chinois, en japonais et en arabe. Le chinois, le japonais, le coréen et les langues écrites de droite à gauche sont composés sans césure. Toute autre langue est coupée avec les motifs de l’anglais américain, avec un avertissement dans la console, et reçoit les chaînes anglaises. Pour un tel document, réglez hyphenation.enabled: false et passez resourceTypes et les chaînes de continuation de tableStyle dans sa langue.

#Texte arabe

Ces réglages servent le texte en écriture arabe ; aucun ne change un document écrit dans une autre écriture. Mise en page arabe les explique avec le reste d’un livre arabe : sens, reliure, chiffres, vers, table des matières et index.

• Signes vocaliques et interlignage. Les signes vocaliques d’un texte vocalisé (fatḥa, kasra, chadda, tanwīn, l’alif suscrit, les signes coraniques) s’empilent au-dessus et au-dessous des lettres, dans l’interlignage, qui ne grandit jamais pour eux. Chaque ligne qui contient des signes enregistre jusqu’où va leur encre (VDTLine.markInk), et le détourage de colonne des moteurs de rendu englobe les signes des première et dernière lignes d’une colonne. Quand un signe au-dessus d’un mot rencontre les lettres ou les signes qui pendent sous le mot du dessus, la construction signale le paragraphe (arabicMarksExceedLeading, dans le panneau Vérifications du Sandbox). Seuls les mots placés l’un au-dessus de l’autre sont comparés. Un texte partiellement vocalisé demande environ 1,7–1,85 em de lineHeight, des vers entièrement vocalisés 1,9–2,1 em.
• Emphase. Le caractère arabe n’a pas d’italique : dans un document dont la locale s’écrit en écriture arabe, *…* est composé en gras par défaut (bodyText.emphasis: 'auto'). 'color' le compose en romain dans la couleur italicColor, et 'overline' trace un filet au-dessus des mots, le khaṭṭ fawqī des livres arabes. Le réglage atteint tout texte composé dans les caractères du texte courant : paragraphes, listes, citations, styles de paragraphe, corps d’encadrés, notes et titres. Les légendes, les cellules de tableau, la table des matières et l’index gardent leurs propres réglages d’italique. Quel que soit le choix, le moteur n’incline jamais les lettres arabes : les mots arabes d’un passage composé en italique restent droits et ses mots latins gardent leur italique. Une citation est en romain par défaut dans un tel document.
• Tashkīl. bodyText.tashkil: 'strip' retire les signes vocaliques et coraniques du texte que compose la mise en page, pour une édition non vocalisée tirée d’une source vocalisée : fatḥa, ḍamma, kasra et leurs tanwīn, sukūn, chadda, l’alif suscrit (هٰذا devient هذا) et les signes U+0656–U+065F et U+06D6–U+06ED. 'strip-vowels' garde la chadda, comme l’impriment la plupart des livres modernes. La hamza et la madda restent (أ إ آ sont des lettres, y compris quand elles sont saisies avec des signes combinants). La source garde ses signes ; les lignes, les titres et la table des matières sont composés sans eux, et chaque caractère composé renvoie toujours à sa place dans la source.
• Notes de bas de page. footnotes.markerTemplate: '({n})' écrit les appels « (١) » dans les chiffres du document, numbering: 'page' les fait repartir à chaque page, et noteNumberPosition: 'inline' place le numéro de la note sur la ligne. Le filet de séparation et les numéros des notes se placent au début de la colonne, à droite dans un livre de droite à gauche.
• Mots entiers. Un mot qui contient une lettre d’écriture arabe n’est jamais coupé en fin de ligne, tronqué ni interlettré, dans un livre arabe comme cité dans un autre. Un style qui applique un letterSpacing à du texte arabe est signalé (joiningScriptLetterSpacing), et un mot plus large que sa ligne en déborde et est signalé (unbreakableWordOverflow). Voir Mise en page arabe.
• Kachida et vers. Une ligne arabe justifiée est étirée par des kachidas en plus de ses espaces (bodyText.kashida, voir La kachida dans le texte arabe), et un poème classique est composé à raison d’un bayt par ligne, en deux hémistiches de même largeur, avec :::verse (voir :::verse).
• Index. Un index en arabe trie dans l’ordre alphabétique et ignore l’article ال (index.ignoreArticle), les signes vocaliques et les supports de la hamza ; voir Index.

#Orphelines, veuves, lignes creuses et règles de maintien

Voir Césure et justification pour le mécanisme de ces pénalités. Cette section est la référence des clés de bodyText qui les pilotent.

Au-delà de la césure et des limites d’espacement, la configuration du texte courant expose les règles souples qui empêchent les coupures de paragraphe maladroites du point de vue de la structure. Toutes sont injectées comme pénalités (demerits) dans l’algorithme de coupure des lignes de Knuth-Plass : elles orientent la mise en page vers des coupures propres sans jamais imposer de règle stricte. Réglez les valeurs *Penalty sur 0 pour désactiver en pratique l’une d’entre elles.

À propos des lignes creuses. Une ligne creuse est la dernière ligne d’un paragraphe trop courte pour passer pour une vraie ligne de texte : en général un ou deux mots courts échoués en fin de paragraphe. Comme la vérification repose sur la longueur en pixels de la ligne rapportée à la largeur normale de l’espace, runtMinCharacters s’adapte automatiquement au corps en cours. Un mot court visuellement plus large que runtMinCharacters × spaceWidth ne pose pas de problème ; un mot plus étroit (ou vraiment isolé) attire la pénalité de ligne creuse. Le seuil compte des espaces entre les mots, qui sont environ deux fois moins larges que les lettres : la valeur par défaut de 20 correspond à une dernière ligne d’environ 8 à 12 lettres. Toute ligne creuse coûte la pénalité entière : entre deux fins sous le seuil, le moteur de coupure garde les lignes plus serrées au-dessus ; gradedRuntPenalty évalue plutôt chacune selon ce qui lui manque, et la fin la plus longue l’emporte. Pour les esprits mathématiques : avec la runtPenalty par défaut de 1000, éviter une ligne creuse l’emporte sur tout autre jeu de coupures qui demanderait un étirement de l’espacement des mots allant jusqu’à environ r≈2,15.

Souples, pas strictes. Aucune de ces règles ne peut empêcher une coupure : le moteur produit toujours une mise en page. Ce sont des pénalités : l’algorithme met en balance la « badness », le coût de la césure, la régularité des classes d’ajustement et ces pénalités structurelles dans une seule optimisation globale, et retient le jeu de coupures au coût total le plus bas. Si vous avez besoin d’une garantie plus ferme, augmentez la pénalité ; si un document se lit mieux avec une pénalité relâchée, diminuez-la.

#Titres

La propriété headings règle la typographie de tous les niveaux de titre (H1 à H6). Vous pouvez définir des valeurs générales qui s’appliquent à tous les niveaux, puis redéfinir certaines propriétés niveau par niveau.

#Valeurs générales

Des titres centrés pour des poèmes ou les actes d’une pièce, sans emplacement de maquette :

headings: {
  textAlign: 'center',
  levels: [{ level: 2, textTransform: 'uppercase' }],
}

Passer un objet headings conserve toutes les valeurs par défaut des niveaux que vous ne redonnez pas, saut de page du H1 compris (voir Réglages par niveau).

#Équilibrage des colonnes

Les éditeurs attendent que chaque colonne commence en haut de la page et se termine au ras de son bas. Les règles de coupure (protection contre les veuves et les orphelines, titres gardés avec leur texte, figures indivisibles) laissent naturellement des colonnes courtes, avec une ou plusieurs lignes vides de la grille de ligne de base en bas. Quand l’équilibrage est activé, le moteur fait ce que ferait un compositeur, en appliquant ses leviers par ordre de priorité éditoriale :

1. Un encadré qui ferme la colonne : un encadré qui termine une colonne courte est descendu exactement de la place libre sous son pied, si bien que son bord inférieur tombe sur la dernière case de la grille de la page, à la hauteur de la dernière ligne de la colonne voisine. Il prend cette place même quand elle fait moins d’une ligne, tant que rien ne passe dans une autre colonne. Par défaut, ce levier passe avant tous les autres et prend tout l’écart, si bien qu’un encadré qui annote le paragraphe au-dessus de lui peut se retrouver plusieurs lignes plus bas ; closingBox: 'last' laisse les titres, les fins de liste et les autres leviers d’espacement prendre d’abord les lignes entières, l’encadré ne prenant que ce qu’ils laissent, et closingBox: 'off' ne le déplace jamais.
2. Images avec zone sûre : une image dotée d’une zone sûre (Resource.safeArea, voir Format de document › Zone sûre) placée en ligne dans la colonne courte, ou flottant en tête ou au pied de cette seule colonne, grandit par lignes entières de la grille, recadrée dans sa zone sûre, jusqu’à ce que la colonne soit pleine ou que le recadrage atteigne la zone sûre. Une image plus haute ne laisse aucun trou sur la page : ce levier passe donc avant tout ajout d’espace ; un flottant en tête de colonne sur une page ou une bande dont les têtes de colonne restent alignées (voir plus bas) ne grandit pas. Enregistré comme flexFigure. Il n’a pas de réglage propre : seule une image dont la ressource marque une zone sûre peut grandir.
3. Titres : des lignes entières de la grille sont ajoutées à la marge supérieure des titres de la colonne courte. Quand plusieurs lignes sont nécessaires et que la colonne contient plusieurs titres, les lignes sont réparties entre eux, la plus grande part allant toujours au titre le plus important (un h2 reçoit plus qu’un h3). Les titres placés tout en haut d’une colonne ne reçoivent jamais d’espace supplémentaire, pour que les colonnes continuent de commencer en haut de la page, sauf un titre placé juste sous une figure ou un tableau qui ouvre sa colonne sur une page dont le flux continue : la place va au-dessus de ce titre, sous la figure. Un titre prend au plus maxLinesBeforeLoose lignes de cette façon (deux par défaut) avant que les leviers suivants soient essayés, et ses lignes supplémentaires, jusqu’à maxLinesPerHeading, seulement quand ceux-ci n’ont plus rien à donner.
4. Fins de liste : quand les titres ne peuvent pas absorber tout l’écart, une ligne de la grille est ajoutée là où se termine une liste ou une énumération (un espace après une liste se lit naturellement), avec un plafond par fin de liste.
5. Sous les formules, les encadrés et les figures : ensuite, une ligne de la grille va sous une formule hors texte ou un encadré après lesquels le texte reprend (stretchAfterDisplays ; elle se lit comme la marge propre de l’élément), et sous une figure ou un tableau qui ouvre la colonne (stretchAfterFloats, plafonné par maxLinesAfterFloat).
6. Paragraphes lâches : en dernier recours, un paragraphe de la colonne est recoupé avec une ligne de plus (le \looseness=+1 de TeX), en choisissant le paragraphe le plus long pour que l’espacement supplémentaire entre les mots se dilue de façon invisible. La solution lâche n’est acceptée que si chaque ligne reste sous bodyText.maxWordSpacing : le gris typographique ne dépasse jamais la limite que vous avez déjà configurée. Nécessite bodyText.optimalLineBreaking.

Sur une grille de caractères (cjk.grid, voir Composition chinoise › La grille de caractères), chaque caractère occupe une case d’un em de large et chaque ligne suit le pas de ligne de la grille, qui est aussi la grille de ligne de base. L’équilibrage y est désactivé par défaut, comme en texte vertical : une page composée ligne à ligne sur une grille, à la manière dont GB/T 9704 compte 22 lignes de 28 caractères, laisse une colonne courte telle quelle. Une configuration qui pose enabled: true obtient des leviers qui respectent la grille : les titres, les fins de liste, les formules hors texte et les figures prennent des lignes entières de la grille, de sorte que le texte qui les suit se déplace par rangées entières, et gridLines: 'off' les exclut pour une norme qui n’a aucune rangée vide à donner. Un paragraphe chinois ou japonais ne s’allonge d’une ligne que si aucun intervalle entre deux de ses caractères ne s’élargit au-delà de maxTracking, et ses lettres ne reçoivent aucune approche : une ligne à qui il manque un caractère répartit un em sur ses intervalles, bien au-delà des 0,01 em par défaut, si bien que sur une grille de cases entières le levier des paragraphes lâches ne trouve généralement rien. L’encadré qui ferme une colonne et les images avec zone sûre sont hors grille par conception et fonctionnent comme partout ailleurs.

La dernière colonne d’une page n’est équilibrée que si la page se poursuit naturellement sur la suivante : la page de fin d’un chapitre se termine légitimement plus court. Une telle page, ainsi qu’une bande finale coupée à niveau par trailing, garde aussi ses têtes de colonne alignées : aucune ligne n’est ajoutée sous une figure ou un tableau qui ouvre l’une de ses colonnes (le levier après flottant), et un titre ou un encadré qui ouvre une colonne sous une telle figure reste en tête, quoi que dise stretchAfterFloats, de même que le titre placé juste sous une ouverture span: 'page' dans la colonne de l’ouverture, de sorte qu’une colonne ne commence jamais plus bas que sa voisine dans le seul but d’aligner les pieds.

Quel levier a agi

La mise en page enregistre chaque levier qu’elle a appliqué, sur le bloc auquel elle l’a appliqué : block.balancing dans le VDT que renvoie buildDocument. Une épreuve, un test ou un rapport peut ainsi dire pourquoi une colonne se termine au ras du bas, et quelles colonnes aucun levier n’a pu fermer. Les blocs que l’équilibrage n’a pas touchés ne portent pas de balancing, et un document construit avec enabled: false n’en a aucun.

Sur une grille de caractères, le document dit pourquoi une colonne peut se terminer court : doc.gridBalancing vaut { off: true } quand l’équilibrage est désactivé parce que la page est sur une grille et que la configuration ne l’active pas, et { gridLines: 'off' } quand il tourne sans les leviers à lignes entières ; une colonne restée courte porte column.gridRefused, les leviers que la grille lui a refusés ('looseParagraph' quand un paragraphe ne pouvait gagner sa ligne qu’en écartant ses caractères hors de leurs cases, les leviers à lignes entières avec gridLines: 'off'). Les deux sont absents hors grille.

interface VDTBalancing {
  levers: BalanceLever[]; // usually one: a paragraph after a list can take the list-end line and run a line long too
  spaceAbove: number;     // px the spacing levers added above the block (0 when only looseParagraph or flexFigure fired)
  bodyGrowth?: number;    // flexFigure: px the picture grew, cropped within its safe area
  extraLines?: number;    // looseParagraph: lines the paragraph gained
  tracking?: number;      // looseParagraph: the tracking that gained them, in thousandths of an em (0 = word spacing alone)
}
type BalanceLever = 'trailingCallout' | 'flexFigure' | 'heading' | 'listEnd' | 'afterDisplay' | 'afterFloat' | 'looseParagraph';

Les coupes à niveau sont enregistrées sur les colonnes qu’elles coupent : column.bandCapped vaut true sur chaque colonne coupée à niveau (la bande qu’un encadré sur toute la largeur de la page laisse derrière lui, une bande finale), et column.trailingCap marque en plus la bande finale d’un chapitre ou du document (trailing).

import { buildDocument } from 'postext';
 
const doc = buildDocument(content, config);
for (const page of doc.pages) {
  page.columns.forEach((column, i) => {
    const levers: string[] = column.blocks.flatMap((block) => block.balancing?.levers ?? []);
    if (column.trailingCap) levers.push('closing band cut level');
    else if (column.bandCapped) levers.push('band cut level');
    if (levers.length > 0) console.log(`page ${page.index + 1}, column ${i + 1}: ${levers.join(', ')}`);
  });
}
// page 3, column 1: heading, heading
// page 3, column 2: listEnd, looseParagraph

#Réglages par niveau

Chaque niveau de titre peut redéfinir les valeurs générales par le tableau levels. Seul fontSize (plus le breakBefore du H1, signalé plus bas) diffère par défaut ; toutes les autres propriétés héritent des réglages généraux des titres.

Le défaut du H1 reproduit la mise en page d’un livre par chapitres : chaque titre de premier niveau s’ouvre sur une nouvelle page de droite (impaire), avec une page blanche de séparation obligatoire après le chapitre précédent. Redéfinissez-le dans levels[0].breakBefore si votre document est moins structuré qu’un livre.

Le breakBefore d’un niveau est fusionné champ par champ avec ce défaut, et un objet headings qui ne le mentionne pas le conserve. { parity: 'odd' } sur le H1 garde le saut et ne change que la parité ; { enabled: false } fait s’enchaîner les chapitres :

headings: {
  fontFamily: 'Merriweather',                               // H1 still breaks to a fresh recto (always-odd)
  levels: [{ level: 1, breakBefore: { parity: 'odd' } }],    // …or: a recto, with no mandatory blank
}
 
headings: { levels: [{ level: 1, breakBefore: { enabled: false } }] } // chapters run on

Modifié dans postext 1.5. Jusqu’à postext 1.4, tout objet headings désactivait le saut du H1 à moins de redonner levels[0].breakBefore, et un breakBefore partiel complétait son champ manquant à partir du défaut sans saut. Une configuration écrite en code pour la 1.4 avec un objet headings et sans saut de H1 ouvre donc désormais chaque chapitre sur un nouveau recto, avec des versos blancs si nécessaire. Pour garder des chapitres qui s’enchaînent, donnez un champ à l’entrée H1 de levels :

headings: { fontFamily: 'Merriweather', levels: [{ level: 1, breakBefore: { enabled: false } }] } // as 1.4 laid it out

Là où la configuration a été enregistrée, le moteur le détecte et s’en charge pour vous : le Sandbox pour les livres et les configurations qu’il a enregistrés à cette époque (voir Sandbox → Persistance), et openBundle / readBundle pour un paquet .postext écrit par postext 1.4 ou antérieur (voir Paquets écrits par postext 1.4 ou antérieur). Une configuration que vous avez enregistrée vous-même peut passer par migrateConfig(config) de postext/bundle, qui écrit explicitement les sauts que posait la 1.4 (pinLegacyHeadingBreaks) : enabled: false sur un H1 qui n’avait pas de saut, et parity: 'any' à côté d’un enabled: true qui ne nommait aucune parité, sur le H1 et sur les styles de titre. Elle fige aussi la taille des mathématiques, l’espace autour des figures en ligne (dans les encadrés aussi), les marques en ligne des titres, la taille des lettrines, la place sous une ligne terminée par un deux-points qui introduit une liste, les lignes qu’une coupe d’encadré laisse d’un paragraphe ou d’un élément de liste, les sauts de ligne aux tirets, la coupure ligne par ligne du texte en drapeau, la division d’un paragraphe sous un titre, les sauts de ligne au trait d’union d’un mot composé et l’espace sous les conteneurs :::paragraphs, tels que la 1.4 les composait. Passez le Markdown du livre en troisième argument, { content }, et elle omet le figeage des mathématiques quand le texte n’a pas de $, les figeages d’espacement quand aucune ligne n’incorpore de ressource (celui des encadrés quand aucune n’en incorpore dans un encadré), le figeage des marques de titre quand aucun titre ne porte de marque, celui des lignes à deux-points quand aucune liste ne suit une ligne terminée par un deux-points, celui des coupes d’encadré quand le texte n’ouvre aucun :::callout, celui des tirets quand aucun tiret n’est composé collé entre deux mots, celui de la division sous un titre quand le texte n’a pas de titre, celui des conteneurs quand le texte n’ouvre aucun conteneur :::paragraphs, et celui des mots composés quand aucun trait d’union ne se trouve entre deux lettres ; le figeage de la coupure en drapeau ne va qu’à une configuration qui compose du texte courant en drapeau, et celui des conteneurs qu’à une configuration qui déclare un style de paragraphe (voir Paquets écrits par postext 1.4 ou antérieur). Pour les sauts seuls, appelez pinLegacyHeadingBreaks(config).

Les réglages par niveau acceptent les mêmes propriétés que les valeurs générales (fontSize, lineHeight, fontFamily, color, fontWeight, marginTop, marginBottom, snapToGrid), plus ces champs propres aux niveaux (un style de titre les accepte aussi) :

headings: {
  fontFamily: 'Merriweather',
  levels: [
    // Canonical book preset: chapters on a right-hand (odd) page.
    { level: 1, fontSize: { value: 24, unit: 'pt' }, breakBefore: { enabled: true, parity: 'odd' } },
    { level: 2, fontSize: { value: 18, unit: 'pt' }, italic: true },
  ]
}

snapToGrid fonctionne aussi par niveau. Non défini, un niveau suit headings.snapToGrid ; défini, il le remplace. Un même document peut ainsi placer ses H2 une ligne et demie au-dessus de leur texte, hors de la grille jusqu’au point de calage suivant, tandis que ses H3 arrondissent l’espace qui les suit à des lignes entières de la grille. Un style de titre peut aussi le régler, pour les titres qui l’utilisent.

headings: {
  marginBottom: { value: 1.5, unit: 'em' },
  levels: [
    { level: 2, snapToGrid: false }, // exactly 1.5 em under every H2
    { level: 3 },                    // inherits headings.snapToGrid: true
  ],
}

#Saut avant

breakBefore est indépendant des réglages de numérotation : l’activer force un saut de page, mais le compteur numérique n’est remis à zéro que si vous insérez explicitement une directive :::numbering. Les pages blanches de parité comptent comme de vraies pages dans la séquence et reçoivent en-têtes et pieds de page selon leurs règles habituelles de pages paires et impaires.

Un :::pagebreak placé juste avant un tel titre ne remplace pas son saut : le titre applique quand même sa parité après la page que la directive a ouverte, ce qui peut ajouter une page blanche. Voir Styles de titre pour un titre qui doit commencer juste après un saut manuel.

Valeurs de parité

À qui appartiennent les pages blanches

Les pages blanches insérées par breakBefore portent des en-têtes avec le titre du chapitre selon la raison de leur insertion :

• Les pages insérées pour respecter une contrainte de parité ('odd', 'even', ou la fin de parité de 'always-*') appartiennent au chapitre à venir. L’espace réservé {chapterTitle} de leur en-tête se résout en titre du nouveau chapitre, puisque la page blanche n’existe que pour amener le nouveau chapitre sur la bonne parité.
• La page de séparation obligatoire insérée par 'always-odd' / 'always-even' appartient au chapitre précédent. C’est une respiration voulue en fin de chapitre : l’en-tête {chapterTitle} affiche donc encore le titre de l’ancien chapitre.

Les titres courants et la palette d’une section stylée (voir Styles de titre) suivent les deux mêmes règles sur les pages blanches.

Exception du début de document

Quand le tout premier bloc du document est un titre dont le breakBefore est activé, ou que la source s’ouvre sur :::pagebreak, la contrainte de parité est ignorée tant que la première page est encore vide. Le titre tombe en page 1, comme écrit, quelle que soit la parité configurée : un document qui commence par un # Chapter 1 configuré avec parity: 'odd' n’hérite donc pas d’une page blanche parasite en tête. Dès qu’un contenu a été placé, la contrainte de parité se comporte normalement.

#Étendue et maquette avancée

Chaque niveau de titre accepte deux champs supplémentaires qui règlent la manière dont le titre se rend comme ouverture de chapitre sur toute la largeur de la page.

Une ouverture aussi haute que la page. Quand la hauteur réservée dépasse le pied de la colonne (une couverture dont le minHeight est la hauteur de la page, une image ou un encadré ancré à la page ou au fond perdu et qui descend jusqu’au format rogné), l’ouverture réclame le reste de la page : le texte qui la suit commence à la page suivante, dans chaque colonne d’une maquette à deux colonnes comme d’une maquette à colonne et demie. Une couverture n’a donc pas besoin d’un :::pagebreak après elle (en mettre un ne fait pas de mal : il n’ajoute pas de page blanche). Un titre dans la colonne (span: 'column') dont la maquette est plus haute que sa colonne réclame cette colonne, et le texte commence en tête de la suivante. Le bloc du titre descend alors jusqu’au pied de la colonne qu’il réclame, et sa maquette est mise en page par rapport à cette bande : les éléments ancrés en haut restent là où ils sont ancrés, et ceux qui suivent la bande (ancrés à son milieu ou à son pied, ou de hauteur 'fill') se tiennent dans la place que réclame le titre, comme ils se tiennent dans la hauteur réservée quand elle suffit (jusqu’à postext 1.4, le bloc gardait la hauteur de son texte : ces éléments étaient donc mis en page par rapport à une bande de la hauteur d’un titre, et le texte qui suivait passait sous la maquette). Les éléments d’habillage de page qui ne doivent pas réclamer la page (une bande le long de la tranche de gouttière sur toute la hauteur de la page, un ornement au pied de la page) ont plutôt leur place dans la maquette de l’en-tête ou du pied de page : ancrés à 'page' ou 'bleed' et affichés avec pages: 'opener', ils se peignent sur la page d’ouverture et ne réservent aucune place dans le texte.

Exemple : une ouverture de chapitre minimaliste qui affiche « Chapter N » au-dessus du titre :

{
  "headings": {
    "levels": [
      {
        "level": 1,
        "span": "page",
        "breakBefore": { "enabled": true, "parity": "always-odd" },
        "advancedDesign": {
          "enabled": true,
          "slot": {
            "elements": [
              {
                "kind": "text",
                "id": "chapterLabel",
                "placement": {
                  "anchor": { "to": "container", "edge": "top" },
                  "offset": { "y": { "value": 48, "unit": "pt" } },
                  "size": { "width": "fill" }
                },
                "content": "Chapter {numberRoman}",
                "fontSize": { "value": 10, "unit": "pt" },
                "align": "center",
                "overflow": "ellipsis-end"
              },
              {
                "kind": "text",
                "id": "chapterTitle",
                "placement": {
                  "anchor": { "to": "#chapterLabel", "edge": "below" },
                  "offset": { "y": { "value": 12, "unit": "pt" } },
                  "size": { "width": "fill" }
                },
                "content": "{titleText}",
                "fontSize": { "value": 24, "unit": "pt" },
                "fontWeight": 700,
                "align": "center",
                "overflow": "wrap",
                "hyphenate": true
              }
            ]
          }
        }
      }
    ]
  }
}

Espaces réservés de titre disponibles dans l’emplacement de maquette d’un niveau :

• {titleText} : le texte brut du titre (sans préfixe de numérotation). Un saut forcé dans le titre (\\) y est un saut de ligne, dans une bande d’ouverture comme dans une maquette dans la colonne (jusqu’à postext 1.4, une maquette dans la colonne imprimait une espace à cet endroit, alors que sa hauteur était mesurée avec le saut). Les lignes sur lesquelles le titre masqué se coupe dans sa colonne sont rassemblées dans le titre tel qu’il est écrit : un mot coupé après son propre trait d’union garde le trait d’union sans espace après lui, un mot que la colonne a divisé redevient entier sans le trait d’union ajouté par la coupure, un groupe soudé par une espace insécable plus large que la colonne et séparé à cette espace retrouve son espace insécable (Capítulo XVIII, pas CapítuloXVIII), et chaque autre coupure rend son espace unique. Jusqu’à postext 1.4, chaque saut de ligne devenait une espace : un titre coupé à un trait d’union imprimait donc Word- Book, et un saut forcé dans un tel titre était perdu.
• {number} : le numéro formaté selon le numberingTemplate du niveau.
• {numberDecimal}, {numberRoman}, {numberRomanLower}, {numberAlpha}, {numberAlphaLower} : le compteur du titre (le décompte courant de son niveau, quoi qu’imprime le modèle) dans d’autres formats de numération : le troisième chapitre donne 3, III, iii, C, c, avec ou sans numberingTemplate. Un titre non numéroté (un style avec numbered: false) les laisse vides.
• {numberWords}, {numberWordsLower}, {numberOrdinalWords}, {numberOrdinalWordsLower} : le même compteur en toutes lettres, avec une capitale ou en minuscules : Three / three, Third / third (voir Numéros en toutes lettres).
• {numberHan} : le même compteur en chiffres chinois, dans l’écriture de la locale du document : une ouverture composée avec 第{numberHan}回 imprime 第十二回 pour le douzième chapitre tandis que la table des matières affiche 12.
• {chapterNumber}, {chapterTitle}, {pageNumber}, {totalPages}, {bookTotalPages}, {title}, {subtitle}, {author}, {publishDate} : espaces réservés de métadonnées partagés.
• {attr.<key>} : un attribut écrit sur la ligne du titre elle-même (# Title {author="I. Zango Martín"}), avec repli sur l’attribut du H1 du chapitre en cours. Les attributs absents se résolvent en chaîne vide, sans avertissement.

{chapterNumber} imprime ce que les titres courants impriment pour le chapitre : le numéro du H1 quand son niveau (ou son style) a un numberingTemplate, sinon le rang du chapitre (1, 2…, en continuant après les chapitres mis en page avant celui-ci), et rien pour un chapitre non numéroté ou un style dont le modèle est ''. Une maquette de titre lit le chapitre auquel appartient son titre : un titre de niveau 1 le sien, un titre inférieur le dernier titre de niveau 1 qui le précède. Cela vaut aussi là où deux chapitres se rencontrent sur une même page, tandis que les titres courants de cette page impriment le chapitre suivant. La hauteur que réserve une ouverture est mesurée avec cette même valeur. Jusqu’à postext 1.4, elle était mesurée avec le préfixe de numéro du titre (vide sans modèle), si bien qu’une maquette dont la hauteur dépend de {chapterNumber} pouvait se peindre plus haute que la place qu’elle prenait ; et la maquette imprimait le chapitre de la page, si bien que le premier de deux chapitres partageant une page affichait le numéro du second.

Les espaces réservés de compteur suivent le livre d’un chapitre à l’autre quand les chapitres sont mis en page un par un (les compteurs que transmet continuationAfter()), et l’attribut startAt d’un titre les fait repartir (voir Format de document → Attributs de titre). Une ouverture qui affiche Chapter III au-dessus d’un titre numéroté 3. dans le flux et dans la table des matières :

{
  level: 1,
  span: 'page',
  numberingTemplate: '{1}.',
  advancedDesign: {
    enabled: true,
    slot: { elements: [
      { kind: 'text', id: 'label', content: 'Chapter {numberRoman}', fontSize: { value: 10, unit: 'pt' }, overflow: 'ellipsis-end',
        placement: { anchor: { to: 'container', edge: 'top-left' }, size: { width: 'fill', height: 'auto' } } },
      { kind: 'text', id: 'title', content: '{titleText}', fontSize: { value: 24, unit: 'pt' }, overflow: 'wrap',
        placement: { anchor: { to: '#label', edge: 'below' }, size: { width: 'fill', height: 'auto' } } },
    ] },
  },
}

Hauteur réservée

Un titre doté d’une maquette avancée occupe de la place dans la colonne comme n’importe quel bloc : le texte courant qui le suit commence sous cette place. Cette place est la plus grande de trois hauteurs, toutes mesurées vers le bas depuis le haut du titre (le haut de la zone de contenu pour une ouverture qui commence sa page) :

1. le texte propre du titre, composé dans la typographie du niveau (il est masqué sous la maquette, mais garde ses lignes) ;
2. le bas du contenu de la maquette, c’est-à-dire le bord inférieur le plus bas parmi les éléments qui comptent (voir plus bas) ;
3. advancedDesign.minHeight.

Le marginBottom du titre s’y ajoute (de son style de titre, de son niveau ou de headings.marginBottom ; 0,5 em par défaut), et le résultat est arrondi vers le haut à la grille de ligne de base quand les titres se calent. Pour une ouverture (span: 'page'), la même bande est laissée libre dans chaque colonne de la page. Pour un titre dans la colonne qui tient dans sa colonne, la maquette est mise en page dans la boîte du titre, qui a exactement cette hauteur.

Quels éléments comptent. Tous les éléments de la maquette comptent, textes, filets, boîtes et images confondus (jusqu’à postext 1.4, un élément image ne comptait jamais, si bien que le texte pouvait commencer par-dessus une image de bande, sauf si minHeight l’en tenait éloigné), à l’exception :

• des éléments avec reserve: false : une décoration qui peut se trouver sous le texte ;
• des éléments qui suivent la bande elle-même : ancrés à la rangée du milieu du conteneur (left, center, right) ou à sa rangée du bas (bottom-left, bottom, bottom-right), avec une hauteur 'fill' par rapport au conteneur (une boîte ou un filet vertical sans hauteur le remplit par défaut), et de tout élément ancré à l’un d’eux. Le conteneur est la bande réservée : ces éléments se posent donc sur son pied ou la couvrent, comme un filet sous la bande ou un panneau teinté derrière le titre. Ils suivent la hauteur ; ils ne la fixent jamais. Un texte parmi eux qui garde sa propre hauteur a quand même besoin de place : un titre ancré au pied de la bande rend la bande au moins aussi haute que lui, si bien qu’il ne commence jamais au-dessus du haut du titre. Avec minHeight: 36mm et le titre ancré bottom-left, la boîte du titre mesure 36 mm plus son marginBottom, arrondis vers le haut à la grille, et le titre se pose au pied de cette boîte, juste au-dessus du texte qui suit ; sans minHeight, un titre qui prend plus de lignes que le texte propre du titre rend la bande aussi profonde que lui. Jusqu’à postext 1.4, un tel titre était peint vers le haut, par-dessus le texte placé au-dessus du titre. Les boîtes, filets et images qui suivent la bande ne fixent pas un tel plancher : un panneau ancré au pied peut donc monter au-dessus du titre.

Les éléments ancrés à la page ou au fond perdu comptent selon la distance à laquelle ils descendent sous le haut du titre. Une bande en haut de la page qui s’arrête au-dessus du titre ne compte pour rien ; une image à fond perdu qui le dépasse repousse le texte jusqu’à son bord inférieur. De même pour tout ce qui se trouve bas sur la page : un sceau à 25 mm du pied de page, une bande latérale sur toute la hauteur ou un cadre réserve la page jusqu’à son bord inférieur, et le texte commence en général à la page suivante. Marquez une telle décoration reserve: false (elle se peint toujours et les éléments peuvent toujours s’y ancrer), et donnez au titre la place dont il a besoin avec ses éléments de texte ou minHeight :

{
  "kind": "image", "id": "seal", "resourceId": "seal", "reserve": false,
  "placement": {
    "anchor": { "to": "page", "edge": "bottom-right" },
    "offset": { "x": { "value": -25, "unit": "mm" }, "y": { "value": -25, "unit": "mm" } },
    "size": { "width": { "value": 30, "unit": "mm" } }
  }
}

Un élément ancré à un élément qui ne réserve pas compte quand même, sauf s’il est marqué lui aussi (une légende posée sur le sceau a besoin de son propre reserve: false).

Où elle se peint. La maquette d’une ouverture (span: 'page') est dessinée avant le texte, si bien qu’une décoration qui ne réserve rien se trouve sous le texte. La maquette d’un titre dans la colonne est dessinée avec le bloc du titre (par-dessus les blocs qui le précèdent dans la colonne, sous ceux qui le suivent), où qu’elle soit placée au-dessus du pied de sa colonne : dans les marges latérales, la marge supérieure, le fond perdu et les colonnes voisines aussi. Le pied de la colonne la coupe, sur le canvas et dans le PDF, puisque le flux s’y arrête (voir Plus haute que la colonne plus bas). Jusqu’à postext 1.4, le canvas et le PDF la coupaient aussi en haut de sa colonne, si bien qu’une bande ancrée en haut de la page ou du fond perdu débordait dans les marges latérales mais s’arrêtait à la marge supérieure. Une décoration ancrée au pied de la page a sa place dans une ouverture, ou dans la maquette du pied de page avec pages: 'opener'.

Plus haute que la colonne. Quand la place dépasse le pied de la colonne (un minHeight aussi haut que la page, une image ou un cadre qui descend jusqu’au format rogné), le titre réclame le reste de sa page (une ouverture, dans chaque colonne) ou de sa colonne (un titre dans la colonne), et le texte qui le suit commence à la page ou à la colonne suivante. Son bloc descend alors jusqu’au pied de la colonne, sans jamais être ramené à la hauteur de son texte, si bien que la bande par rapport à laquelle sa maquette est mise en page est la place qu’il réclame (minHeight compris, jusqu’au pied). Une maquette plus haute que la page elle-même (un long chapeau sur une petite page d’écran) est quand même coupée au pied de la page (une maquette dans la colonne, au pied de sa colonne) : le Sandbox la signale dans le panneau Vérifications sous le nom Maquette de titre coupée. La mise en page ne lève aucun avertissement pour cela (une couverture qui réclame sa page est le cas habituel et ne perd rien), mais tout hôte peut lancer la même vérification sur la mise en page terminée : collectHeadingDesignCuts(doc) renvoie un { kind: 'headingDesignCut', pageIndex, level, where, overflowPx, sourceStart, sourceEnd } pour chaque titre dont le texte de maquette dépasse le pied du format rogné de la page (where: 'page', une ouverture) ou de sa colonne (where: 'column'), et formatWarning décrit chacun d’eux. Voir Une ouverture aussi haute que la page sous Étendue et maquette avancée.

La colonne latérale. Dans une maquette à colonne et demie dont la colonne latérale reçoit les flottants (sideColumnRole: 'floats'), un élément de la maquette d’un titre dans la colonne qui se trouve dans la colonne latérale (un numéro de chapitre ancré à la page dans la colonne de marge extérieure d’une ouverture de manuel) en tient la pile latérale éloignée. Chaque figure, tableau ou encadré span: 'side' que la page compose après le titre garde un écart de flottant libre autour de chacun de ces éléments : il reste là où la pile le place quand il tient au-dessus de l’élément, et passe sinon dessous, ou attend la page suivante quand le reste de la colonne latérale ne peut pas l’y contenir. Un numéro en tête du couloir latéral tient donc toute la pile sous lui, tandis qu’un numéro de section suspendu dans la marge à côté d’un titre plus bas sur la page laisse la tête du couloir aux figures que la page cite (la figure marginale se place toujours en haut de sa page). Ce que la colonne latérale contient déjà quand le titre est placé n’est pas déplacé : une figure empilée plus tôt sur la page qui descend jusqu’à l’élément du titre reste où elle est, sous l’élément ; une maquette dont l’élément se trouve dans la colonne latérale au milieu de la page veut donc ses figures citées après le titre. Les éléments avec reserve: false laissent la colonne latérale libre, comme ils laissent le texte. Une ouverture (span: 'page') n’a besoin de rien de tel : sa bande est réservée dans chaque colonne, colonne latérale comprise. Jusqu’à postext 1.4, une figure latérale citée sur une telle ouverture était placée en tête de la colonne latérale, par-dessus le numéro.

Couvertures. Un titre de couverture qui remplit sa page (minHeight aussi haut que la page, ou une image pleine page dans sa maquette) envoie donc de lui-même le texte qui le suit à la page suivante, dans les maquettes à une ou à plusieurs colonnes. Un :::pagebreak juste après lui est facultatif et ne fait pas de mal : un saut de page sur une page encore vide ne fait rien, il n’ajoute donc jamais de page blanche. Il n’est nécessaire que lorsque la maquette de la couverture s’arrête avant le pied de la page et que le texte doit quand même commencer sur une nouvelle page.

# Annual report 2026 {style="cover"}
 
:::pagebreak
 
# Letter from the chair

#Numéros en toutes lettres

Deux suffixes de modèle de numérotation écrivent un compteur en toutes lettres, dans la langue du document (la locale de premier niveau, sinon la langue de césure ; voir Langue du document) : words pour le cardinal et ordinal pour l’ordinal. La casse du suffixe fixe la casse des mots, comme A / a le fait pour les lettres :

L’anglais, l’espagnol, le chinois et l’arabe sont écrits en toutes lettres ; toute autre langue prend les mots anglais, comme le font les chaînes de continuation de tableau intégrées. Le chinois écrit les chiffres informels de simp-chinese-informal ou de trad-chinese-informal, selon l’écriture de la locale (一万 / 一萬), avec 第 devant un ordinal ; les caractères Han n’ont pas de casse, les trois graphies d’un suffixe s’impriment donc de la même façon. L’anglais suit l’usage américain (one hundred five, sans and). L’espagnol emploie les formes masculines, comme on numérote un capítulo ou un libro (capítulo primero, tercero, veintiuno), et écrit les ordinaux de 13 à 29 en un seul mot, comme le préfère la RAE (decimotercero, vigesimoprimero). Les cardinaux sont écrits en toutes lettres jusqu’à 999 999 et les ordinaux espagnols jusqu’à 999 ; les nombres plus grands s’impriment en chiffres.

Les nombres arabes s’accordent en genre avec le nom qu’ils comptent : le suffixe accepte donc un modificateur : -feminine (ou -f) pour un nom féminin, -masculine (-m, le défaut) pour un nom masculin ; -classical écrit les centaines مائة, comme le font Boulaq et la plupart des imprimés égyptiens, au lieu du moderne مئة. {1:ordinal} écrit l’ordinal défini au nominatif qu’emploie un titre : الفصل {1:ordinal} donne الفصل الأول, الفصل الحادي عشر, الفصل الحادي والعشرون ; الليلة {1:ordinal-feminine} donne الليلة الأولى, الليلة الحادية عشرة, الليلة الحادية والعشرون, الليلة المئتان, et au-delà de cent la formule classique « après » : الليلة الخامسة والأربعون بعد الثلاثمئة, الليلة الحادية بعد الألف. {1:words} écrit le cardinal (واحد وعشرون ; au féminin إحدى عشرة, واحدة وعشرون). Les ordinaux sont écrits en toutes lettres jusqu’à 9 999 et les cardinaux jusqu’à 99 999 ; les modificateurs se combinent ({1:ordinal-f-classical}), et les autres langues les ignorent. L’arabe n’a pas de capitales : la casse du suffixe ne change donc rien. Les espaces réservés de maquette {numberWords} et {numberOrdinalWords} écrivent les formes masculines ; pour une ouverture au féminin, mettez l’ordinal dans le modèle du niveau et imprimez-le avec {number}.

Dans une maquette de titre, {numberWords} / {numberWordsLower} et {numberOrdinalWords} / {numberOrdinalWordsLower} écrivent le compteur du titre de la même façon, si bien que l’ouverture peut afficher Chapter One tandis que la table des matières affiche 1. Le textTransform: 'uppercase' d’un élément de texte donne les capitales :

// Spanish novel: "CAPÍTULO PRIMERO" above the title, "1." in the contents.
{ level: 1, numberingTemplate: '{1}.', span: 'page',
  advancedDesign: { enabled: true, slot: { elements: [
    { kind: 'text', id: 'n', content: 'Capítulo {numberOrdinalWordsLower}', textTransform: 'uppercase', /* … */ },
    { kind: 'text', id: 't', content: '{titleText}', /* … */ },
  ] } } }

#Listes à puces

La propriété unorderedLists règle le rendu des listes à puces (-, *, +) et des listes de tâches GFM (- [ ], - [x]). Jusqu’à cinq niveaux d’imbrication sont pris en charge.

#Valeurs par défaut des listes à puces

#Extensions pour les listes de tâches

Les éléments de tâche GFM (- [ ] …, - [x] …) sont rendus comme des éléments à puces avec une case à cocher à la place de la puce. Le moteur dessine lui-même la case, un carré au trait, coché quand l’élément est fait : aucune police n’est sollicitée, elle est donc identique sur toutes les machines, sur le canvas, dans le PDF, dans le HTML et dans l’EPUB, et les technologies d’assistance lisent ☐ ou ☑. Son côté mesure 0,6 em de la taille de la marque (bulletFontSize, ou le fontSize du niveau), et c’est la place qu’elle occupe avant le gap ; à la taille du texte, elle repose sur la ligne de base de la première ligne de l’élément. Son trait suit la fontWeight de la marque et sa couleur la color de la marque. Les champs suivants ne concernent que les éléments de tâche :

#Réglages par niveau des listes à puces

Chaque entrée de levels vise une profondeur (1 à 5) et peut redéfinir n’importe lequel des champs suivants :

Cascade des retraits. Le niveau 1 commence toujours à la valeur générale indent (par défaut 0 em : les puces sont calées sur le bord de la colonne). Pour les niveaux 2 à 5, si vous laissez indent indéfini, le moteur place la puce au début du texte du niveau précédent (retrait du parent + largeur de la puce + gap). Donnez un indent explicite à un niveau pour rompre la cascade et caler cette profondeur où vous voulez.

unorderedLists: {
  bulletChar: '—',
  gap: { value: 0.4, unit: 'em' },
  hangingIndent: true,
  levels: [
    { level: 2, bulletChar: '·' },
    { level: 3, bulletChar: '◦', color: { hex: '#666666', model: 'hex' } },
  ],
}

#Listes numérotées

La propriété orderedLists règle les listes numérotées (1., 2), etc.). Jusqu’à cinq niveaux d’imbrication sont pris en charge, et chaque profondeur peut utiliser un format de numéro différent.

#Valeurs par défaut des listes numérotées

#Réglages par niveau des listes numérotées

Chaque entrée de levels peut redéfinir numberFormat, prefix, separator, fontFamily, fontSize, color, fontWeight, italic, indent, verticalOffset et le style du séparateur (separatorFontFamily, separatorFontWeight, separatorItalic, separatorColor, separatorGap) ; la même cascade des retraits que pour les listes à puces s’applique. Le style du séparateur d’un niveau hérite du style de son propre numéro, sauf si le réglage du séparateur est donné pour toute la liste.

Alignement à droite. La chaîne de traitement mesure le numéro formaté le plus large d’une série et applique à tous les éléments de cette série un retrait qui aligne les numéros sur leur bord droit. Dans une liste de dix éléments rendus de 1. à 10., les numéros à un chiffre sont complétés à droite pour que le séparateur reste dans la même colonne.

orderedLists: {
  numberFormat: 'arabic',
  separator: '.',
  levels: [
    { level: 2, numberFormat: 'lower-alpha' },
    { level: 3, numberFormat: 'lower-roman', separator: ')' },
  ],
}

On obtient le mélange imbriqué classique :

1. First item
   a. Sub-item
      i) Deep note
   b. Sub-item
2. Second item

La hiérarchie des documents chinois (GB/T 15834—2011, annexe B.3) compte cinq niveaux : 一、 puis （一） puis 1. puis （1） puis ① :

orderedLists: {
  levels: [
    { level: 1, numberFormat: 'simp-chinese-informal', separator: '、' },
    { level: 2, numberFormat: 'simp-chinese-informal', prefix: '（', separator: '）' },
    { level: 3, numberFormat: 'arabic', separator: '.' },
    { level: 4, numberFormat: 'arabic', prefix: '（', separator: '）' },
    { level: 5, numberFormat: 'circled-decimal', separator: '' },
  ],
}

#Mathématiques

La propriété math règle l’analyse et le rendu des formules LaTeX placées entre les délimiteurs $...$ (en ligne) et $$...$$ (hors texte). Le moteur sous-jacent est MathJax (le paquet mathjax-full) en sortie SVG, rastérisé sur le canvas et incorporé au PDF sous forme de glyphes vectoriels.

interface MathConfig {
  enabled?: boolean;        // Render LaTeX. When false, spans pass through as literal TeX.
  fontSizeScale?: number;   // × the surrounding text's size (the body size for display maths).
  color?: ColorValue;       // Formula colour; inherits body colour if omitted.
  marginTop?: Dimension;    // Space above display math blocks.
  marginBottom?: Dimension; // Minimum space below; baseline grid snap may enlarge it.
  indentAfterDisplay?: boolean; // Indent a paragraph that follows a display formula.
  keepWithLeadIn?: boolean; // Keep a display formula with the line that leads into it.
  equationNumbering?: {      // Number the display formulas that carry a \label.
    enabled?: boolean;           // default true
    numberingTemplate?: string;  // '{n}'; '{h1}.{n}' numbers by chapter
    resetOn?: ResourceCounterReset; // 'never' | 'h1' … 'h6'
    counterFormat?: ResourceCounterFormat; // 'decimal'
    format?: string;             // '({n})': what the formula and \eqref print
  };
}

math: {
  enabled: true,
  fontSizeScale: 1.0,
  color: { hex: '#295AA3', model: 'hex' },
  marginTop: { value: 1, unit: 'em' },
  marginBottom: { value: 1, unit: 'em' },
}

Taille des formules, modifiée dans postext 1.5. MathJax donne la boîte d’une formule en ex, et un ex de sa police TeX vaut 0,442 em. Jusqu’à postext 1.4, le moteur le prenait pour un demi-em, si bien que chaque formule était composée environ 13 % plus grande que bodyText.fontSize × fontSizeScale. Les formules sortent désormais à la taille documentée, et les lignes et les pages qui contiennent des mathématiques se recomposent. Une configuration écrite en code pour la 1.4 garde la taille de formule de la 1.4 en passant par pinLegacyMathSize de postext/bundle, une seule fois, telle qu’elle est écrite :

import { pinLegacyMathSize } from 'postext/bundle';
 
config = pinLegacyMathSize(config); // formulas, and the space around display formulas, as 1.4 set them

D’autres changements de règles de la 1.5 peuvent aussi déplacer ses pages : les coupures des titres, l’espace autour d’une figure en ligne (dans le texte courant et dans les encadrés), les marques en ligne de ses titres, la taille de ses lettrines, la place gardée sous une ligne terminée par un deux-points pour la liste qu’elle introduit, les lignes qu’une coupe d’encadré laisse d’un paragraphe ou d’un élément de liste, les sauts de ligne après un tiret, la coupure du texte en drapeau, la division d’un paragraphe sous un titre, les sauts de ligne après le trait d’union d’un mot composé et l’espace sous un conteneur :::paragraphs. migrateConfig, lancé une fois avec le Markdown que la configuration met en page, fige celles dont ce texte a besoin, taille des formules comprise (voir Paquets écrits par postext 1.4 ou antérieur) :

import { migrateConfig } from 'postext/bundle';
 
config = migrateConfig(config, undefined, { content: markdown }); // heading breaks, formulas, inline gaps, heading marks, drop caps, colon lines, box cuts, dash breaks, compound breaks, ragged breaking, splits under a heading and container space as 1.4 set them

Cela retient ce que ces changements de règles déplaceraient, mais ne conserve pas toutes les pages de la 1.4. La version 1.5 corrige aussi des défauts de mise en page, et une correction ne se fige pas : une ancienne configuration en profite comme une nouvelle, si bien qu’une page qu’elle touche peut encore bouger. Parmi elles : un titre sur toute la largeur de la page sans maquette propre est mesuré sur la largeur de la page et composé avec l’interlignage de son niveau ; rien n’est réservé sous la ligne de base d’une lettrine dans une maquette de titre ; une lettrine prend la couleur de palette de la section, et est composée même sur un texte de maquette dont l’overflow n’est pas 'wrap', qui passe alors à la ligne ; un paragraphe dans un encadré peint l’approche avec laquelle il a été mesuré ; un encadré divisé garde sa colonne d’icône sur chaque fragment ; une ligne d’encadré qui étirerait ses espaces au-delà de 3× est composée en drapeau, comme dans le texte courant ; le levier des paragraphes lâches ne compose jamais une ligne justifiée plus large que ne le permet maxWordSpacing ; un encadré flottant garde un marginBottom (dans une bande du haut) ou un marginTop (dans une bande du bas) plus large que l’écart des flottants ; un texte de maquette centré ou aligné à droite avec de l’approche (un titre courant, un titre d’ouverture) est placé d’après ses lettres, sans l’approche qui suit la dernière ; sous une ouverture sur toute la largeur de la page, le texte qui ouvre la deuxième colonne commence là où commencerait un texte placé juste sous l’ouverture, y compris quand un titre suit l’ouverture ; les points de conduite de la table des matières s’arrêtent avant le numéro de page dans un caractère dont le crénage écarte une suite de points ; un titre courant lit un titre tel qu’il est écrit, sans espace là où l’une de ses lignes se termine après un trait d’union ou un tiret, ou à l’intérieur d’un mot coupé faute de place (MEDIOAMBIENTALES, pas MEDIOAMBIENTALE S), et le {titleText} d’une maquette de titre le lit de la même façon (thousand-colour, pas thousand- colour) ; un texte ancré au pied ou au milieu de la bande d’une maquette de titre garde la bande assez haute pour le contenir, et ne remonte donc plus sur le texte au-dessus du titre ; un mot plus large que sa ligne, coupé près d’un trait d’union qu’il porte, est coupé après ce trait d’union et n’en reçoit pas un second ; l’élément qui suit une liste imbriquée dans une autre prend l’itemSpacing de sa propre liste, pas celui de la liste imbriquée ; et le reste d’un mot coupé parce qu’il était plus large que sa ligne garde ses propres points de coupure, si bien qu’une adresse web continue de se couper à ses jointures et un mot composé à ses traits d’union, au lieu des syllabes du dictionnaire.

pinLegacyMathSize multiplie l’échelle par 1,1312 (0,5 ÷ 0,442) et divise par le même facteur les marges hors texte exprimées en em. L’échelle seule ne suffit pas pour un livre qui contient des formules hors texte : leurs marges sont des longueurs à la taille de la formule elle-même, elles grandiraient donc des mêmes 13 % et repousseraient vers le bas le texte qui les suit. Écrites pour les marges par défaut, les trois valeurs sont :

math: {
  fontSizeScale: 1.131,
  marginTop: { value: 0.7072, unit: 'em' },
  marginBottom: { value: 0.7072, unit: 'em' },
} // formulas as large as 1.4 set them, with the space 1.4 left around them

Là où la configuration a été enregistrée, le moteur le détecte et s’en charge pour vous : openBundle / readBundle pour un paquet .postext écrit avant la 1.5 (voir Paquets écrits par postext 1.4 ou antérieur), et le Sandbox pour les livres, la copie de travail et les fichiers postext-config.json enregistrés à cette époque (voir Sandbox → Persistance). Ils sont lus par migrateConfig, qui fige la taille (pinLegacyMathSize) : fontSizeScale devient l’échelle enregistrée (1 si elle n’est pas définie) × 1,1312, et une marge hors texte en em ou en rem (une longueur à la taille de la formule elle-même) est divisée par le même facteur, de sorte que l’espace autour d’une formule hors texte reste celui que laissait la 1.4 (les 0,8 em par défaut deviennent 0,7072 em). Une marge dans une unité de page (pt, mm…) reste telle quelle, de même qu’une configuration avec enabled: false ou dont le livre ne contient aucun $. L’ancien livre se met alors en page comme le faisait la 1.4, et sa section math affiche la taille à laquelle il est composé. Pour composer un tel livre à la taille actuelle, réinitialisez ces valeurs : Formules → Échelle de taille, Marge supérieure hors texte et Marge inférieure hors texte dans le Sandbox, ou en code :

math: { ...config.math, fontSizeScale: 1, marginTop: undefined, marginBottom: undefined } // today's size and margins

Équations numérotées. Une formule hors texte numérotée occupe toute sa justification (la colonne, ou la largeur intérieure de l’encadré qui la contient) : l’équation est centrée et son numéro aligné à droite sur la ligne de l’équation, sur chaque ligne numérotée d’un align. Un numéro vient d’un \label{eq:x} (depuis postext 1.19) : les formules étiquetées, et les lignes étiquetées d’un align, gather, alignat, flalign ou eqnarray, sont numérotées dans l’ordre de lecture selon equationNumbering, sauf si une ligne porte \nonumber ou \notag. Les environnements comme equation ne sont pas numérotés d’eux-mêmes : une formule sans étiquette n’a pas de numéro. \tag{…} imprime l’étiquette que vous lui donnez, entre parenthèses, et \tag*{…} telle qu’elle est écrite ; aucun des deux n’est compté, et un \label placé à côté lui donne un nom. Une équation numérotée plus large que sa justification déborde à droite, comme toute formule hors texte. (Jusqu’à postext 1.4, une formule avec \tag n’était pas dessinée du tout ; jusqu’à la 1.18, seul \tag en numérotait une.)

\eqref{eq:x} dans le texte imprime le numéro dans son format, (3), et \ref{eq:x} le numéro nu ; :ref{id="eq:x"} et @eq:x font de même (voir Renvois), et à l’intérieur d’une formule \eqref l’imprime comme du texte. Dans un livre mis en page chapitre par chapitre, le compteur reprend là où le chapitre précédent l’a laissé : continuationAfter le transporte dans LayoutContinuation.statementCounters (equation), et le plan du livre donne à chaque étiquette son numéro (OutlineEntry.numberLabel), si bien qu’un renvoi vers une équation d’un autre chapitre l’imprime.

math: {
  equationNumbering: { numberingTemplate: '{h1}.{n}', resetOn: 'h1' }, // (1.1), (1.2)… (2.1)
}

Le résolveur et le nettoyeur suivent le modèle des autres sections :

import {
  DEFAULT_MATH_CONFIG,
  resolveMathConfig,
  stripMathDefaults,
} from 'postext';
 
const resolved = resolveMathConfig(config.math);
const minimal  = stripMathDefaults(config.math);

#Démarrer le moteur mathématique

MathJax est chargé à la demande, et non avec le reste du moteur. Quand vous mettez en page sur le thread principal, démarrez-le avant de construire un document qui contient des formules :

import { buildDocument, initMathEngine, renderPage } from 'postext';
 
await initMathEngine(); // loads MathJax once; later calls resolve at once
const doc = buildDocument({ markdown: 'Euler: $e^{i\\pi}+1=0$.' }, config);
document.body.append(renderPage(doc.pages[0], doc));

• Tant que le moteur ne tourne pas, les formules sont des espaces réservés. Chacune est mise en page comme une boîte grise de taille estimée. Si un document contenant des mathématiques est mis en page avant tout appel à initMathEngine(), la console affiche un avertissement qui le signale.
• Le worker de mise en page le démarre pour vous. Une construction dans postext/worker appelle elle-même initMathEngine() quand le Markdown contient un $.
• Mettre en page tout de suite, puis de nouveau quand il est prêt. isMathReady() indique si le moteur tourne. onMathReady(fn) appelle fn dès qu’il tourne (immédiatement s’il tourne déjà) et renvoie une fonction qui annule l’appel. Un éditeur peut afficher des espaces réservés tout de suite et remettre en page à l’arrivée de MathJax ; aucun avertissement n’est affiché tant que initMathEngine() est en cours.
• Échec. initMathEngine() rejette sa promesse quand MathJax ne peut pas être chargé, et un appel ultérieur réessaie.
• N’importe quel bundler, Node ou un CDN. MathJax est livré dans le paquet sous forme d’un module pré-empaqueté (environ 1,8 Mo avant compression, récupéré uniquement par initMathEngine). Le simple import { initMathEngine } from 'https://esm.sh/postext' fonctionne ; aucun ?bundle n’est nécessaire. Le paquet mathjax-full ne sert qu’à construire postext, installer postext ne l’installe donc pas. MathJax et l’analyseur mhchem qu’il embarque sont sous licence Apache-2.0 : leurs mentions et le texte de la licence sont livrés à côté du module, dans dist/math/THIRD_PARTY_LICENSES.txt.
• Un seul moteur par page. Le moteur et son cache de formules rendues sont partagés par tout ce qui importe postext dans le même domaine d’exécution JavaScript (voir État global partagé dans une page).

Pour la grammaire côté document ($...$, $$...$$, échapper un dollar littéral), voir Format de document.