Configuration : encadrés

#Styles d’encadré

La propriété calloutStyles déclare les styles d’encadré nommés qu’un document applique avec un conteneur :::callout{type="…"} : notes, conseils, avertissements, objectifs d’apprentissage, tout contenu mis à part du texte courant dans un cadre teinté ou bordé. Un style neutre, note, est fourni par défaut (fond gris clair, sans bordure, sans bande, sans icône, sans titre), si bien que :::callout fonctionne sans aucune configuration ; déclarer calloutStyles remplace cette liste par défaut.

const config: PostextConfig = {
  calloutStyles: [
    { id: 'note', name: 'Note' },
    {
      id: 'objectives',
      name: 'Learning objectives',
      title: 'Objectives',
      stripe: { enabled: true, side: 'left' },
      icon: { kind: 'glyph', glyph: '✓' },
      titleStyle: { textTransform: 'uppercase' },
      lists: { bulletChar: '–' },
    },
    {
      id: 'warning',
      title: 'Warning',
      backgroundEnabled: false,
      border: { enabled: true, color: { hex: '#AA0000', model: 'hex' }, width: { value: 1, unit: 'pt' } },
      borderRadius: { value: 1, unit: 'mm' },
      titleStyle: { color: { hex: '#AA0000', model: 'hex' } },
    },
  ],
};

:::callout{type="objectives"}
- Describe the parts of the lantern.
- Trim the wick at dusk.
:::
 
:::callout{type="warning" title="Do not touch the lens"}
The glass stays hot for an hour after the flame is out.
:::

#Le conteneur :::callout

Une ligne :::callout{type="<id>"} ouvre l’encadré et une ligne ::: seule le ferme. La clôture accepte cinq attributs : type (l’id du style), title (remplace le titre du style), span, placement et columns (remplacent les valeurs du style) ; le contenu placé entre les deux est mis en page dans l’encadré : un titre facultatif, puis les paragraphes, listes, citations, formules ou ressources intégrées, chacun composé avec la typographie body / lists du style (les titres gardent leurs styles habituels). Les marges entre enfants fusionnent comme dans le texte courant ; l’intérieur quitte la grille de ligne de base, et le flux y revient après l’encadré avec au moins marginBottom en dessous (la grille l’emporte ; la marge est un minimum, la même convention que suivent les ressources). Un style avec snapToGrid: false garde plutôt le marginBottom exact, et le texte qui suit l’encadré reste hors de la grille jusqu’au titre suivant ou à la fin d’une liste. Un titre placé juste avant un encadré reste avec lui.

Limites de cette version :

• Un encadré est gardé entier, sauf si son style fixe keepTogether: false. Quand il ne tient pas dans l’espace restant de la colonne, il passe en entier à la colonne ou à la page suivante, y compris hors d’une colonne vide que des bandes de flottants ou un plafond de bande ont raccourcie, pourvu qu’une colonne pleine puisse le contenir. Un encadré plus haut qu’une colonne pleine se coupe au contraire, comme un encadré sécable ; seul celui qu’aucune coupe ne peut diviser (une figure ou un tableau plus haut que la colonne, ou un splitMinLines qu’aucune coupe ne satisfait) est placé malgré tout et déborde ; la mise en page enregistre alors un avertissement calloutOverflow (VDTDocument.warnings), que le Sandbox liste. Un groupe :::columns se coupe comme l’encadré qui l’entoure, entre ses sous-colonnes (depuis postext 1.25) ; il reste entier, et peut déborder de la même façon, seulement avec layout.flowColumns: false ou à l’intérieur d’un encadré imbriqué. Un encadré sécable laisse derrière lui la partie qui tient (des enfants entiers, ou les lignes d’un paragraphe jusqu’à splitMinLines de chaque côté ; une figure, un tableau ou une formule centrée suffisent à eux seuls pour un côté) et continue dans un encadré sans icône sur la colonne ou la page suivante, sans le titre sauf si le style le répète, et éventuellement avec une marque sous la partie qu’il laisse (voir Marques sur un encadré coupé).
• Les flottants cèdent la place à un encadré insécable. Quand le bloc qui suit immédiatement la référence d’une figure est un encadré keepTogether, un emplacement qui ne laisserait à l’encadré aucune colonne de la bande en cours où se poser (la colonne de la référence ou une colonne vide après elle, qui le contenait avant le flottant) n’est pas pris : la figure passe à son emplacement suivant, en général la page suivante, et l’encadré reste dans le flux, comme le composerait un compositeur, plutôt que de chasser l’encadré de la page et de laisser la colonne avec la figure seule.
• span: 'page' dans une mise en page à plusieurs colonnes fait de l’encadré un bloc pleine largeur : il est mis en page sur toute la largeur de contenu et découpe la page en bandes de colonnes ; les colonnes de texte au-dessus sont fermées à la ligne de coupe, l’encadré occupe sa propre colonne pleine largeur, et une nouvelle bande de colonnes de texte s’ouvre en dessous, si bien que le flux continue sous l’encadré dans chaque colonne. Là où les colonnes sont à niveau (en haut d’une page, juste sous un titre d’ouverture span: 'page', juste sous un autre bloc pleine largeur, ou juste sous une bande de flottants de tête), l’encadré coupe simplement à cet endroit. S’il arrive en milieu de page, avec des colonnes inégales, il est composé comme le ferait un compositeur : le texte au-dessus est coupé à niveau sur toutes les colonnes (le moteur relance le placement avec les colonnes de la bande raccourcies au même nombre de lignes de grille, si bien que le texte passe naturellement d’une colonne à l’autre et que chaque règle d’orpheline, de veuve et de maintien avec le suivant s’applique toujours), l’encadré couvre la page et les colonnes reprennent en dessous. La coupe demande quelques passes de placement supplémentaires ; quand la ligne de coupe ne laisserait pas de place pour l’encadré plus le minimum de lignes de texte contre les veuves en dessous, ou qu’aucune disposition ne convient après quelques essais, l’encadré passe en haut de la page suivante. Le texte au-dessus respecte la coupe : un paragraphe qui ne peut pas commencer dans les quelques lignes qu’une colonne garde sous une figure au-dessus de la coupe passe à la colonne suivante (la figure reste alors seule dans sa colonne), et quand un bloc dépasserait encore la coupe, la coupe est prise une ligne plus bas plutôt qu’à la fin de ce bloc. Un encadré coupé qui ouvre la bande est coupé là aussi, si bien que son reste ne dépasse jamais la coupe. Avec headings.balancing.beforeSpan (la valeur par défaut), la bande qu’il quitte est coupée à niveau derrière lui (comme la bande qui clôt un chapitre) et, quand le style permet la coupe (keepTogether: false), la partie de l’encadré qui tient sous les colonnes mises à niveau ferme la page et le reste ouvre la suivante ; avec beforeSpan: false, la page qu’il quitte est simplement équilibrée comme d’habitude, sans forcer de saut de page. Un titre placé juste avant un bloc pleine largeur ne voyage pas avec lui. Dans les mises en page à une colonne, span: 'page' est simplement en ligne.
• placement: 'fixed' retire l’encadré du flux : il est mis en page (width: 'auto' s’ajuste au titre ; 'fill' prend la largeur de la colonne de texte sous le point d’ancrage) et épinglé sur la page où il apparaît dans le flux, à la position que décrivent fixed.anchor / fixed.offset (par défaut, le coin inférieur gauche de la zone de contenu). Les colonnes de texte qu’il recouvre lui cèdent cette zone (coupée par le bas, ou par le haut quand la colonne est encore vide), exactement comme une bande de flottants ; quand la zone contient déjà du texte, un flottant ou un bloc pleine largeur, l’encadré passe à la page suivante. Un encadré fixe qui clôt le chapitre (le bloc suivant est une ouverture de chapitre, un :::part, un encadré barrière pour les flottants ou la fin du document) met d’abord à niveau les colonnes au-dessus de lui (headings.balancing.trailing), si bien qu’une dernière page courte se termine à niveau avec le badge en dessous. Le cadre et les enfants vivent dans page.floats et sont rendus hors du découpage des colonnes dans tous les moteurs de rendu.
• placement: 'top' | 'bottom' fait flotter l’encadré comme une ressource : il quitte le flux là où il apparaît et prend la première bande libre après ce point (le pied de la page en cours ('bottom'), ou la tête / le pied de la page suivante qu’ouvre le flux), à la largeur de la colonne (span: 'column') ou sur toute la largeur de contenu (span: 'page') ; le texte qui le suit remplit la page qu’il a quittée. Son cadre et ses enfants vont dans page.floats, comme pour un encadré fixe. Un encadré flottant en tête d’une nouvelle page est placé avant les figures qui attendent cette page, et une figure citée sur une page précédente qui tient ensuite sous lui prend le reste de cette page même quand il resterait moins de trois lignes de texte (une page de galerie : encadré plus figure, sans texte entre eux). Un encadré span: 'side' ne flotte jamais : il s’empile à côté du texte quel que soit son placement. Avec columns supérieur à 1 (dans le style ou comme attribut de la clôture, depuis postext 1.18), un encadré span: 'column' occupe autant de colonnes adjacentes : la tête d’une suite de colonnes vides qui commencent à niveau, ou le pied de la colonne en cours et des colonnes vides qui la suivent, comme dans :::callout{placement="top" columns="2"}.
• width: 'auto' s’ajuste au titre seulement ; les enfants sont ignorés.
• Un :::callout imbriqué dans un autre encadré est un encadré à part entière : il est mis en page avec son propre style (fond, bordure, rayon, marge intérieure, bande, titre, icône, marque, onglet, typographie) sur toute la largeur intérieure de son parent et s’empile comme un enfant de celui-ci, ses marginTop / marginBottom fusionnant avec ses voisins. Son span et son placement (de la clôture ou du style) sont ignorés (un encadré imbriqué suit toujours le flux de son parent), tout comme floatBarrier et snapToGrid. Les encadrés s’imbriquent à toute profondeur et peuvent se trouver dans un groupe :::columns (chacun entier, dans une colonne). Quand le parent se coupe, la coupe tombe avant ou après un encadré imbriqué, ou à l’intérieur quand le style imbriqué permet la coupe ; chaque fragment redessine les cadres qu’il traverse, et un encadré imbriqué qui continue depuis le fragment précédent perd son titre et son icône, comme une suite de premier niveau.
• Un groupe :::columns{count=N} … ::: parmi les enfants dispose ces enfants en N colonnes de même largeur, séparées de columnGap, dans l’encadré : la suite est coupée aux limites de bloc ou de ligne qui mettent le mieux les colonnes à niveau (un paragraphe ou un élément de liste coupé au milieu continue en tête de la colonne suivante sans sa puce), chaque colonne commence en haut du groupe et le groupe est aussi haut que sa colonne la plus haute ; les enfants qui le suivent reviennent à toute la largeur. Un encadré qui se coupe (keepTogether: false, ou plus haut qu’une colonne) coupe aussi à l’intérieur d’un groupe, entre ses colonnes : un groupe en serpentin remplit ses colonnes tour à tour et continue dans le fragment suivant, un groupe parallèle (breaks) continue flux par flux (depuis postext 1.25 ; voir Format du document › :::columns). Un gap sur la clôture remplace columnGap pour ce groupe, et rule trace un filet dans chaque gouttière. Utilisez-le pour un résumé des points clés sur deux colonnes, ou pour les tableaux d’un large encadré placés côte à côte.
• Le sixième attribut de la clôture, label, s’imprime sur l’onglet du style (voir label plus haut) : :::callout{type="box" label="BOX 1-1" title="The octet rule"} ; sans style label, l’attribut est ignoré.

Dans le VDT, l’encadré est un bloc cadre type: 'callout' dont la décoration (fond, bande, icône, titre) vit dans designOverlay, suivi de ses blocs enfants dans la même colonne ; le cadre et chaque enfant portent le containerId de la clôture. Un encadré imbriqué est un cadre type: 'callout' à part parmi les enfants, suivi de ses blocs ; ceux-ci gardent le containerId de la clôture de premier niveau (le placement et l’équilibrage voient toujours une seule unité) et ajoutent calloutPath, les id de conteneur des clôtures imbriquées qui les entourent, de la plus extérieure à la plus intérieure (l’id propre d’un cadre imbriqué est la dernière entrée). Le PDF balisé donne à chaque encadré imbriqué un Div à l’intérieur de celui de son parent. Les images d’icône se résolvent comme les images de ressource : le registre d’images du canvas, l’option HTML resourceImageUrl et le fournisseur PDF resourceBytes.

const resolved = resolveCalloutStylesConfig(config.calloutStyles, resolvedBodyText, resolvedHeadings, resolvedUnorderedLists, config.locale);
// => every inherited field filled from the resolved sections; the optional
//    locale picks the language of the continuation strings
 
const minimal  = stripCalloutStylesDefaults(config.calloutStyles);
// => undefined for the built-in `note` default; static defaults dropped

#Énoncés numérotés et démonstrations

Un style doté de numbering compte ses encadrés, comme amsthm de LaTeX compte les environnements de théorème (depuis postext 1.19). Chaque encadré imprime son étiquette et son numéro (« Theorem 2. » en ouverture de son premier paragraphe), et le title de la clôture suit le numéro entre parenthèses : :::callout{type="theorem" title="Bradley–Terry"} s’ouvre sur « Theorem 2 (Bradley–Terry). ». Un encadré ouvert avec un identifiant ({#thm:main}) est une cible de renvois, qui impriment « Theorem 2 » (:ref{id="thm:main"}), et \ref{thm:main} ou style=number imprime 2.

Une démonstration est un style avec une étiquette non numérotée et une marque de fin :

calloutStyles: [
  { id: 'theorem', numbering: { label: 'Theorem' }, body: { italic: true } },
  { id: 'lemma', numbering: { label: 'Lemma', counter: 'theorem' }, body: { italic: true } },
  { id: 'definition', numbering: { label: 'Definition' } },
  { id: 'proof', backgroundEnabled: false, endMark: '□',
    numbering: { label: 'Proof', counter: false, bold: false, italic: true } },
]

Dans un livre mis en page chapitre par chapitre, les compteurs reprennent depuis le chapitre précédent (LayoutContinuation.statementCounters, que remplit continuationAfter), et le plan du livre donne à l’ancre de chaque encadré numéroté son étiquette (OutlineEntry.numberLabel), si bien qu’un renvoi depuis un autre chapitre l’imprime.

#Typographie dans un encadré

Un encadré compose son contenu avec sa propre typographie body et lists ; tout le reste garde les styles du document :

• Les paragraphes prennent le body de l’encadré : caractère, taille, interlignage, couleur, couleurs d’emphase, graisses, italic, smallCaps, alignement, césure, retrait et espacement des paragraphes. Un champ non défini hérite de bodyText. Une couleur d’emphase héritée garde son lien à la palette, si bien que le gras, l’italique et les étiquettes :ref d’un encadré changent avec colorPalette comme à l’extérieur. (Jusqu’à postext 1.4, le gras d’un encadré restait #295AA3 quelle que soit la Main Color.)
• Les listes à puces prennent les lists de l’encadré (caractère de puce, couleur, taille et graisse du glyphe, retrait, écart, espacement des éléments) par-dessus unorderedLists, et leur texte est le texte de l’encadré. Un lists.bulletChar ou un lists.color différent de celui du document (unorderedLists) remplace la puce ou la couleur de tous les niveaux ; s’il le répète, ou s’il n’est pas défini, chaque niveau garde la sienne (unorderedLists.levels), si bien que les tirets imbriqués survivent dans l’encadré.
• Les listes numérotées prennent lists.indent, gap et itemSpacing, et lists.color dès que le style le fixe, y compris quand c’est la couleur de puce du document ; un style qui ne le fixe pas garde les numéros dans orderedLists.color. (Jusqu’à postext 1.4, la couleur n’atteignait les numéros que si elle différait de unorderedLists.color, si bien que lui donner cette couleur même n’avait aucun effet.) Le numéro lui-même (son caractère, sa taille et son séparateur) vient du orderedLists global, puisque lists n’a que des champs de puce : c’est là qu’il faut styler les numéros d’un encadré.
• Les :::paragraphs dans un encadré utilisent leur style de paragraphe, dans les encadrés imbriqués aussi. Les champs que le style laisse non définis héritent du bodyText du document, non du body de l’encadré (ni de son italique ou de ses petites capitales).
• Les groupes :::columns n’ont pas de style propre : toutes les colonnes partagent la typographie du texte et des listes de l’encadré, et columnGap fixe l’écart entre elles.
• Les citations prennent le caractère, la taille et les graisses du texte de l’encadré (en italique et en gris, comme dans le texte courant), ainsi que ses petites capitales. Les titres gardent les styles de titre ; les formules centrées, les réglages mathématiques.
• Les figures et tableaux gardent les styles de légende et de tableau du document, à la largeur intérieure de l’encadré ; leurs graisses normale et grasse suivent les graisses du body de l’encadré.
• Les pastilles gardent leur style de pastille ; une taille en em se lit par rapport à la taille du texte de l’encadré.
• :::space se mesure en lignes du texte de l’encadré (voir :::space pour les cas où il est supprimé).
• Un encadré imbriqué prend entièrement son propre style ; ses span, placement, floatBarrier et snapToGrid sont ignorés.

#Marques sur un encadré coupé

Quand un encadré se coupe entre colonnes ou pages (keepTogether: false, ou un encadré plus haut qu’une colonne), chaque partie après la première s’ouvre sans le titre ni l’icône, et par défaut rien n’indique au lecteur que l’encadré continue. Deux options ajoutent les marques qu’emploie un livre ou un scénario :

• repeatTitle: true répète le titre en tête de chaque suite, suivi de continuedSuffix (« Key points (cont.) » par défaut). La répétition prend le style du titre : avec textTransform: 'uppercase', elle donne le « HAMLET (CONT'D) » d’un scénario. L’icône et l’onglet restent sur la première partie.
• continuesMarkerEnabled: true place continuesMarker (« Continued », ou « Continúa » dans un document espagnol) sous la dernière ligne de chaque partie qui se poursuit, à l’intérieur de l’encadré, dans le caractère et la taille du texte de l’encadré : en italique sauf si continuesMarkerItalic vaut false, au fer à droite sauf si continuesMarkerAlign indique 'left' ou 'center'. La marque prend de la place dans la partie qu’elle clôt, et la coupe est choisie pour qu’elle tienne.

calloutStyles: [{
  id: 'speech',
  keepTogether: false,
  titleStyle: { textTransform: 'uppercase' },
  repeatTitle: true,
  continuedSuffix: "(CONT'D)",
  continuesMarkerEnabled: true,
  continuesMarker: '(MORE)',
  continuesMarkerAlign: 'center',
  continuesMarkerItalic: false,
}],

:::callout{type="speech" title="Hamlet"}
A speech long enough to run over the foot of the page…
:::

La partie qui clôt la page se termine par « (MORE) », et la page suivante s’ouvre sur « HAMLET (CONT'D) ». Les deux relèvent de l’habillage de pagination : dans un PDF accessible, ce sont des artefacts, et dans le HTML elles sont masquées aux technologies d’assistance, si bien que le titre n’est lu qu’une fois. Dans le VDT, ce sont des blocs de texte designOverlay marqués artifact: true.