Configuration : listes et mathématiques

#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.