Configuració: requadres d'avís

#Estils d'avís

La propietat calloutStyles declara els estils de caixa amb nom que el document aplica mitjançant un contenidor :::callout{type="…"} — notes, consells, advertiments, objectius d'aprenentatge, qualsevol contingut separat del text corregut en una caixa tintada o amb vora. Per defecte s'inclou un estil neutre, note (fons gris clar, sense vora, sense franja, sense icona, sense títol), de manera que :::callout funciona sense cap configuració; declarar calloutStyles substitueix aquesta llista per defecte.

const config: PostextConfig = {
  calloutStyles: [
    { id: 'note', name: 'Nota' },
    {
      id: 'objectives',
      name: "Objectius d'aprenentatge",
      title: 'Objectius',
      stripe: { enabled: true, side: 'left' },
      icon: { kind: 'glyph', glyph: '✓' },
      titleStyle: { textTransform: 'uppercase' },
      lists: { bulletChar: '–' },
    },
    {
      id: 'warning',
      title: 'Advertiment',
      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"}
- Descriure les parts del fanal.
- Retallar el ble en fer-se fosc.
:::
 
:::callout{type="warning" title="No toquis la lent"}
El vidre continua calent una hora després d'apagar la flama.
:::

#El contenidor :::callout

Una línia :::callout{type="<id>"} obre la caixa i una línia ::: tota sola la tanca. La tanca admet cinc atributs — type (l'id de l'estil), title (sobreescriu el títol de l'estil), span, placement i columns (sobreescriuen els valors de l'estil) — i el contingut intermedi es compon dins la caixa: un títol opcional i després els paràgrafs, llistes, cites, fórmules o recursos incrustats, cadascun amb la tipografia body / lists de l'estil (els encapçalaments conserven els seus estils habituals). Els marges entre fills es fonen com en el text corregut; l'interior abandona la retícula de base i el flux hi torna després de la caixa garantint com a mínim marginBottom per sota (la retícula mana; el marge és un mínim — la mateixa convenció que segueixen els recursos). Un estil amb snapToGrid: false conserva, en canvi, el marginBottom exacte, i el text després de la caixa queda fora de la retícula fins al següent encapçalament o final de llista. Un encapçalament immediatament anterior a un avís es manté unit a ell.

Límits d'aquesta versió:

• Un avís es manté sencer tret que el seu estil indiqui keepTogether: false. Quan no cap a l'espai que queda de la columna passa sencer a la columna o pàgina següent — també des d'una columna buida que les bandes de flotants o un topall de banda han escurçat, sempre que una columna completa l'allotgés. Una caixa més alta que una columna completa es parteix al seu lloc, com una de divisible; només la que cap tall no pot partir (una figura o taula més alta que la columna, o un splitMinLines que cap tall no compleix) es col·loca igualment i desborda; la maquetació registra llavors un avís calloutOverflow (VDTDocument.warnings), que el sandbox llista. Un grup :::columns es talla com la caixa que l'envolta, entre les seves subcolumnes (des de postext 1.25); es manté sencer, i pot desbordar de la mateixa manera, només amb layout.flowColumns: false o dins d'una caixa niada. Una caixa divisible deixa enrere la part que hi cap — fills sencers, o les línies d'un paràgraf fins a splitMinLines a cada costat (n'hi ha prou amb una figura, taula o fórmula en bloc en un costat) — i continua en una caixa sense icona a la columna o pàgina següent, sense títol tret que l'estil el repeteixi i, si es vol, amb un indicador sota la part que deixa (vegeu Marques d'un requadre partit).
• Els flotants cedeixen davant d'una caixa indivisible. Quan el bloc que segueix la referència d'una figura és un avís keepTogether, no s'agafa un buit que deixaria la caixa sense cap columna de la banda actual on anar a parar (la columna de la referència o una de buida posterior, que abans del flotant l'allotjava): la figura passa al seu buit següent, normalment la pàgina següent, i la caixa segueix en el flux — com la compondria un caixista, en lloc d'expulsar la caixa de la pàgina i deixar la columna amb la figura sola.
• span: 'page' en una disposició multicolumna converteix la caixa en un bloc d'amplada de pàgina: es compon a l'amplada completa de l'àrea de contingut i divideix la pàgina en bandes de columnes — les columnes de text que hi ha a sobre es tanquen a la línia de tall, la caixa ocupa la seva pròpia columna a tota l'amplada i a sota s'obre una banda nova de columnes de text, de manera que el flux continua sota la caixa a totes les columnes. On les columnes estan anivellades — al començament d'una pàgina, just sota un encapçalament d'obertura amb span: 'page', just sota un altre bloc d'amplada de pàgina o just sota una banda de flotants superior — la caixa simplement talla allà. Si arriba a mitja pàgina, amb les columnes desiguals, es compon com ho faria un caixista: el text que hi ha a sobre es talla anivellat a totes les columnes (el motor repeteix la col·locació amb les columnes de la banda escurçades al mateix nombre de línies de retícula, de manera que el text desborda de columna en columna de forma natural i continuen aplicant-se totes les regles d'òrfenes, vídues i encapçalaments units al seu text), la caixa ocupa l'amplada de la pàgina i les columnes continuen a sota. El tall costa un parell de passades de col·locació addicionals; quan la línia de tall no deixaria lloc per a la caixa més el mínim de línies vídues de cos per sota, o cap disposició no encaixa després d'uns quants intents, la caixa passa al començament de la pàgina següent. El text de sobre respecta el tall: un paràgraf que no pot començar a les poques línies que li queden a una columna sota una figura passa a la columna següent (la figura queda sola a la seva columna), i quan un bloc encara passaria del tall, el tall es baixa una línia en lloc de quedar-se on acaba aquell bloc. Una caixa partida que obre la banda també es talla allà, de manera que la seva resta mai no passa del tall. Amb headings.balancing.beforeSpan (el valor per defecte) la banda que deixa es talla anivellada després d'ella — com la banda de tancament d'un capítol — i, quan l'estil permet partir-la (keepTogether: false), la part de la caixa que cap sota les columnes anivellades tanca la pàgina i la resta obre la següent; amb beforeSpan: false la pàgina que deixa simplement s'equilibra com sempre, sense forçar un salt de pàgina. Un encapçalament just abans d'un bloc d'amplada de pàgina no viatja amb ell. En disposicions d'una columna span: 'page' és simplement en línia.
• placement: 'fixed' treu la caixa del flux: es compon (width: 'auto' s'ajusta al títol; 'fill' pren l'amplada de la columna de text sota el punt d'ancoratge) i es fixa a la pàgina on apareix en el flux, a la posició que descriuen fixed.anchor / fixed.offset — per defecte la cantonada inferior esquerra de l'àrea de contingut. Les columnes de text que cobreix cedeixen aquella zona (retallada per baix, o per dalt quan la columna encara és buida), exactament com una banda de flotants; quan la zona ja conté text, un flotant o un bloc d'amplada de pàgina, la caixa passa a la pàgina següent. Una caixa fixa que tanca el capítol (el bloc següent és una obertura de capítol, un :::part, una caixa barrera de flotants o el final del document) anivella primer les columnes que queden a sobre (headings.balancing.trailing), de manera que una pàgina de tancament curta acaba anivellada amb el distintiu a sota. La caixa i els seus fills viuen a page.floats i es pinten fora del retall de columna en tots els backends.
• placement: 'top' | 'bottom' fa flotar la caixa com un recurs: surt del flux on apareix i pren la primera banda lliure a partir d'aquest punt — el peu de la pàgina actual ('bottom'), o el cap / el peu de la pàgina següent que obre el flux — a l'amplada de la columna (span: 'column') o a l'amplada completa de l'àrea de contingut (span: 'page'); el text que la segueix omple la pàgina que ha deixat. El seu marc i els seus fills van a page.floats, com els d'una caixa fixa. Una caixa flotant que encapçala una pàgina nova es col·loca abans que les figures que esperen aquella pàgina, i una figura citada en una pàgina anterior que llavors hi cap a sota pren la resta d'aquella pàgina encara que quedessin menys de tres línies de text (una pàgina galeria: caixa més figura, sense text entre totes dues). Una caixa span: 'side' mai no flota: s'apila al costat del text sigui quin sigui el seu placement. Amb columns més gran que 1 (a l'estil o com a atribut de la tanca, des de postext 1.18), una caixa span: 'column' ocupa aquest nombre de columnes contigües: el cap d'una sèrie de columnes buides que comencen a la mateixa altura, o el peu de la columna en curs i de les buides que la segueixen, com a :::callout{placement="top" columns="2"}.
• width: 'auto' s'ajusta només al títol; els fills s'ignoren.
• Un :::callout niat dins d'un altre avís és una caixa pròpia: es compon amb el seu propi estil (fons, vora, radi, farciment, franja, títol, icona, marcador, pestanya, tipografia) a l'amplada interior completa de la seva caixa mare i s'apila com un fill més, i el seu marginTop / marginBottom es fon amb el dels veïns. El seu span i el seu placement (de la tanca o de l'estil) s'ignoren —una caixa niada sempre flueix dins la seva mare—, igual que floatBarrier i snapToGrid. Les caixes es nien a qualsevol profunditat i poden anar dins d'un grup :::columns (cadascuna sencera, en una columna). Quan la caixa mare es parteix, el tall cau abans o després d'una caixa niada, o dins d'ella si el seu estil permet partir-la; cada fragment torna a dibuixar els marcs que travessa el tall, i una caixa niada que continua del fragment anterior perd el títol i la icona, com una continuació de primer nivell.
• Un grup :::columns{count=N} … ::: entre els fills compon aquests fills en N columnes d'igual amplada, separades per columnGap, dins la caixa: la seqüència es talla pels límits de bloc o de línia que millor anivellen les columnes (un paràgraf o element de llista tallat a mitges continua al cap de la columna següent sense la vinyeta), cada columna comença a la part superior del grup i el grup fa l'alçada de la columna més alta; els fills posteriors recuperen l'amplada completa. Una caixa que es parteix (keepTogether: false, o més alta que una columna) també talla dins d'un grup, entre les seves columnes: un grup en serpentina omple les columnes per torns i continua al fragment següent, i un de paral·lel (breaks) continua corrent a corrent (des de postext 1.25; vegeu Format del document › :::columns). Un gap a la tanca substitueix columnGap per a aquell grup, i rule traça un filet al llarg de cada espai entre columnes. Serveix per a un resum de punts clau a dues columnes o per a les taules d'un requadre ample posades una al costat de l'altra.
• El sisè atribut de la tanca, label, s'imprimeix a la pestanya label de l'estil (vegeu més amunt): :::callout{type="recuadro" label="RECUADRO 1-1" title="La regla del octeto"}; sense estil de pestanya l'atribut s'ignora.

Al VDT la caixa és un bloc marc de type: 'callout' la decoració del qual (fons, franja, icona, títol) viu a designOverlay, seguit dels seus blocs fills a la mateixa columna; el marc i cada fill porten el containerId de la tanca. Una caixa niada és un marc type: 'callout' propi entre els fills, seguit dels seus blocs; conserven el containerId de la tanca de primer nivell (la col·locació i l'equilibrat continuen veient una sola unitat) i afegeixen calloutPath, els identificadors de contenidor de les tanques niades que els envolten, de la més externa a la més interna (el d'un marc niat és l'última entrada). El PDF etiquetat dona a cada caixa niada un Div dins del de la seva mare. Les imatges d'icona es resolen com les dels recursos: el registre d'imatges del canvas, l'opció resourceImageUrl de l'HTML i el proveïdor resourceBytes del PDF.

const resolved = resolveCalloutStylesConfig(config.calloutStyles, resolvedBodyText, resolvedHeadings, resolvedUnorderedLists, config.locale);
// => cada camp heretat s'omple des de les seccions resoltes; el locale
//    opcional tria la llengua de les cadenes de continuació
 
const minimal  = stripCalloutStylesDefaults(config.calloutStyles);
// => undefined per al `note` per defecte; s'eliminen els valors estàtics per defecte

#Enunciats numerats i demostracions

Un estil amb numbering compta les seves caixes, com el paquet amsthm de LaTeX compta els entorns de teorema (des de postext 1.19). Cada caixa imprimeix el seu rètol i el seu número —«Teorema 2.» al començament del primer paràgraf—, i el title de la tanca segueix el número entre parèntesis: :::callout{type="theorem" title="Bradley–Terry"} comença amb «Teorema 2 (Bradley–Terry).». Una caixa oberta amb un identificador ({#thm:main}) és destí de referències creuades, que imprimeixen «Teorema 2» (:ref{id="thm:main"}), i \ref{thm:main} o style=number imprimeixen 2.

Una demostració és un estil amb un rètol sense número i una marca final:

calloutStyles: [
  { id: 'theorem', numbering: { label: 'Teorema' }, body: { italic: true } },
  { id: 'lemma', numbering: { label: 'Lema', counter: 'theorem' }, body: { italic: true } },
  { id: 'definition', numbering: { label: 'Definició' } },
  { id: 'proof', backgroundEnabled: false, endMark: '□',
    numbering: { label: 'Demostració', counter: false, bold: false, italic: true } },
]

En un llibre compost capítol a capítol, els comptadors continuen des del capítol anterior (LayoutContinuation.statementCounters, que omple continuationAfter), i l'esquema del llibre dona a l'àncora de cada caixa numerada el seu rètol (OutlineEntry.numberLabel), de manera que una referència des d'un altre capítol l'imprimeix.

#Tipografia dins d'un requadre

Una caixa d'avís —un requadre, com l'anomenen el tauler Estils de requadre del sandbox i el format del document— compon el seu contingut amb la tipografia body i lists del seu estil; tota la resta conserva els estils del document:

• Els paràgrafs prenen el body de la caixa: font, cos, interlineat, color, colors d'èmfasi, gruixos, italic, smallCaps, alineació, partició de mots, sagnat i espaiat entre paràgrafs. Un camp sense definir hereta de bodyText. Un color d'èmfasi heretat conserva el seu vincle amb la paleta, així que les negretes, les cursives i les etiquetes de :ref d'una caixa canvien amb colorPalette igual que fora d'ella. (Fins a postext 1.4 la negreta d'una caixa es quedava en #295AA3 fos quin fos el color principal).
• Les llistes de vinyetes prenen el lists de la caixa (caràcter de vinyeta, color, mida i gruix del glif, sagnat, separació, espaiat entre elements) sobre unorderedLists, i el seu text és el del cos de la caixa. Un lists.bulletChar o un lists.color diferent del del document (unorderedLists) substitueix la vinyeta o el color de tots els nivells; un que el repeteix, o que no es defineix, deixa a cada nivell els seus (unorderedLists.levels), de manera que els guions dels nivells niats es conserven a la caixa.
• Les llistes ordenades prenen lists.indent, gap i itemSpacing, i lists.color sempre que l'estil el defineix, també quan coincideix amb el color de vinyeta del document; un estil que no el defineix deixa els números en orderedLists.color. (Fins a postext 1.4 el color només arribava als números si era diferent d'unorderedLists.color, així que donar-li justament aquest color no tenia efecte). El número —la seva font, el seu cos i el seu separador— ve dels orderedLists globals, perquè lists només té camps de vinyeta: és allà on es dona estil als números d'una caixa.
• Els :::paragraphs dins d'una caixa fan servir el seu estil de paràgraf, també en caixes niades. Els camps que l'estil no defineix hereten del bodyText del document, no del body de la caixa (ni de la seva cursiva ni de les seves versaletes).
• Els grups :::columns no tenen estil propi: totes les columnes comparteixen la tipografia de cos i de llistes de la caixa, i columnGap fixa la separació entre elles.
• Les cites prenen la font, el cos i els gruixos del text de la caixa (en cursiva i en gris, com en el text corregut) i les seves versaletes. Els encapçalaments conserven els seus estils; les fórmules en bloc, la configuració de matemàtiques.
• Les figures i les taules conserven els estils de peu i de taula del document, a l'amplada interior de la caixa; els seus gruixos normal i negreta segueixen els gruixos del body de la caixa.
• Els xips conserven el seu estil de xip; una mida en em es mesura sobre el cos del text de la caixa.
• :::space es mesura en línies del text de la caixa (vegeu :::space per saber on es descarta).
• Una caixa niada pren el seu propi estil complet; el seu span, el seu placement, el seu floatBarrier i el seu snapToGrid s'ignoren.

#Marques d'un requadre partit

Quan una caixa es parteix entre columnes o pàgines (keepTogether: false, o una caixa més alta que una columna), cada part posterior a la primera comença sense el títol ni la icona i, per defecte, res no avisa el lector que la caixa continua. Dues opcions afegeixen les marques que fan servir un llibre o un guió:

• repeatTitle: true repeteix el títol al començament de cada continuació, seguit de continuedSuffix — «Punts clau (cont.)» per defecte. La repetició pren l'estil del títol, així que amb textTransform: 'uppercase' dona el «HAMLET (CONT.)» d'un guió. La icona i la pestanya d'etiqueta es queden a la primera part.
• continuesMarkerEnabled: true posa continuesMarker — «Continúa» en un document en castellà, «Continued» en anglès — sota l'última línia de cada part que continua, dins la caixa, en la font i el cos del text de la caixa: en cursiva tret que continuesMarkerItalic sigui false, i alineat a la dreta tret que continuesMarkerAlign digui 'left' o 'center'. L'indicador ocupa lloc a la part que tanca, i el tall es tria perquè hi càpiga.

calloutStyles: [{
  id: 'parlamento',
  keepTogether: false,
  titleStyle: { textTransform: 'uppercase' },
  repeatTitle: true,
  continuedSuffix: '(CONT.)',
  continuesMarkerEnabled: true,
  continuesMarker: '(SEGUEIX)',
  continuesMarkerAlign: 'center',
  continuesMarkerItalic: false,
}],

:::callout{type="parlamento" title="Hamlet"}
Un parlament prou llarg per passar del peu de la pàgina…
:::

La part que tanca la pàgina acaba amb «(SEGUEIX)» i la pàgina següent comença amb «HAMLET (CONT.)». Totes dues són elements de paginació: en un PDF accessible són artefactes i a l'HTML s'amaguen a les tecnologies de suport, de manera que el títol es llegeix una sola vegada. Al VDT són blocs de text de designOverlay marcats amb artifact: true.