Configuració: estils i parts

#Estils de paràgraf

La propietat paragraphStyles declara estils amb nom que el document aplica a una sèrie de paràgrafs mitjançant un contenidor :::paragraphs{style="…"} — bibliografies, glossaris, notes, qualsevol bloc d'entrades que vulgui la seva pròpia tipografia, pes, cursiva, mida, interlineat, majúscules, versaletes o un sagnat francès. Tots els camps tipogràfics són opcionals i hereten del text del cos quan no s'indiquen, de manera que un estil només descriu el que difereix del text corrent.

const config: PostextConfig = {
  paragraphStyles: [
    {
      id: 'bibliography',
      name: 'Bibliografia',
      fontSize: { value: 7, unit: 'pt' },
      lineHeight: { value: 1.2, unit: 'em' },
      hangingIndent: { value: 2, unit: 'em' },
      spaceBetween: { value: 0.25, unit: 'em' },
      marginTop: { value: 1, unit: 'em' },
      marginBottom: { value: 1, unit: 'em' },
    },
  ],
};

## Referències
 
:::paragraphs{style="bibliography"}
Knuth, D. E. (1984). *The TeXbook*. Addison-Wesley.
 
Bringhurst, R. (2004). *The Elements of Typographic Style*. Hartley & Marks.
:::

Una obra de teatre compon les acotacions en cursiva i el repartiment en versaletes:

paragraphStyles: [
  { id: 'acotacion', italic: true, fontSize: { value: 9, unit: 'pt' } },
  { id: 'reparto', smallCaps: true, textAlign: 'center', fontWeight: 600 },
],

:::paragraphs{style="acotacion"}
Elsinor. Una esplanada davant del castell. *Francisco* al seu lloc.
:::

L'acotació s'imprimeix en cursiva i el nom que conté, en rodona; els pesos, italic i smallCaps d'un estil també s'apliquen dins de les caixes d'avís.

Un llibre de poemes sagna alguns versos i, quan un vers no cap a la mesura, porta el que sobra més endins que el mateix vers. indent desplaça cap endins totes les línies del paràgraf, i el sagnat francès es compta des d'aquí:

paragraphStyles: [
  { id: 'verso', textAlign: 'left', firstLineIndent: { value: 0, unit: 'em' }, hangingIndent: { value: 4, unit: 'em' } },
  { id: 'verso-sangrado', textAlign: 'left', indent: { value: 1.5, unit: 'em' }, hangingIndent: { value: 2.5, unit: 'em' } },
],

Un vers en verso-sangrado comença a 1,5 em i la seva continuació a 4 em, a l'altura de les continuacions dels versos en verso. Sense indent, un estil pot sagnar la primera línia o les altres, no totes dues: firstLineIndent s'ignora tan bon punt hi ha hangingIndent.

Un menú posa cada preu arran del final de la mesura, darrere d'una línia de punts:

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

:::paragraphs{style="menu"}
Sopa de ceba :tab 8,50
 
Orada a la brasa amb fonoll i llimona :tab 21,00
:::

Els punts de cada línia acaben mig quadratí abans del preu (leaderGap). Un plat massa llarg per a la seva línia salta de línia, i la seva última línia conserva el farciment i el preu; quan el preu no cap al costat de l'última paraula, aquesta paraula baixa amb ell.

#El contenidor :::paragraphs

Una línia :::paragraphs{style="<id>"} obre el contenidor i una línia ::: tota sola el tanca; tots els paràgrafs del mig prenen l'estil indicat, mentre que els encapçalaments, les llistes i els altres blocs de l'interior conserven el seu estil habitual. Els contenidors es poden niar dins d'altres contenidors. Un style desconegut no és un error: els paràgrafs es componen com a text de cos normal.

La tanca admet també align (start, end, left, right, center, justify), indent i endIndent (els nombres sense unitat són em), amb estil o sense: amb estil, manen sobre el que fixa l'estil; sense estil, s'apliquen sobre l'estil del contenidor que l'envolta, o sobre l'estil de text del lloc on és la tanca (el cos, una part, una secció amb estil o un requadre). :::paragraphs{align=end} compon un bloc arran del final de la línia (地付き) i :::paragraphs{align=end endIndent=1}, a un caràcter d'aquest. Des de postext 1.16.

Dins del contenidor el flux abandona la retícula de base — una entrada de 7pt amb interlineat 1.2em no es pot assentar en una retícula de 8pt/1.5em — i l'últim paràgraf torna el flux a la retícula (la retícula mana; l'espai de sota és un mínim, la mateixa convenció que segueixen els encapçalaments). Les entrades es parteixen entre columnes i pàgines com els paràgrafs del cos, amb la mateixa protecció de vídues i òrfenes; un encapçalament immediatament anterior al contenidor es manté unit al seu primer paràgraf.

L'espai sota el contenidor és el més gran entre el spaceBetween i el marginBottom de l'estil i la separació entre paràgrafs del text que l'envolta (una línia quan bodyText.paragraphSpacing està activat), i es fon amb l'espai que el bloc següent deixa a sobre seu, com l'espai entre dos paràgrafs del cos: un encapçalament després d'una bibliografia queda al seu propi marginTop de l'última entrada (o a l'espai de l'estil, si és més gran), i un paràgraf després d'un grup d'entrades més atapeïdes conserva la separació entre paràgrafs del text. El flux torna primer a la retícula sota el text, i el que l'ajust no ha cobert s'arrossega en línies senceres de la retícula, perquè el text que segueix el contenidor hi caigui. Fins a postext 1.4, l'espai de l'estil es posava sota l'última línia abans de l'ajust, l'espai del bloc següent s'hi sumava a sota i la separació entre paràgrafs no comptava; bodyText.paragraphContainerSpacing: 'add' manté aquella regla, i les configuracions desades abans es llegeixen amb ella. Un estil amb snapToGrid: false no s'ajusta: el text que segueix el contenidor en queda a l'espai exacte, fora de la retícula fins al bloc següent que s'ajusti. Un contenidor que es tanca amb una llista es compon com a la 1.4 amb qualsevol de les dues regles: la llista conserva el seu propi espai a sota, i el marginBottom va a continuació d'aquest espai i es fon amb el del bloc següent.

Dins d'un :::callout el contenidor aplica els marges del seu estil de la mateixa manera: marginTop i marginBottom es fonen amb l'espaiat dels blocs que l'envolten (un de negatiu els acosta), i un contenidor que obre el requadre no porta marge superior, igual que a dalt de tot d'una columna. El requadre no té retícula de base on tornar, així que l'espai sota l'últim paràgraf és el més gran de marginBottom, spaceBetween i la separació entre paràgrafs del mateix requadre (el seu body.paragraphSpacing, una línia del seu text; no compta amb paragraphContainerSpacing: 'add'), o el marge superior del bloc següent, si encara és més gran; un marginBottom negatiu, en canvi, acosta el bloc següent. (Fins a postext 1.4, un contenidor dins d'un requadre no aplicava cap dels dos marges.)

const resolved = resolveParagraphStylesConfig(config.paragraphStyles, resolvedBodyText);
// => cada camp no indicat s'omple des del text de cos resolt
 
const minimal  = stripParagraphStylesDefaults(config.paragraphStyles);
// => undefined quan la llista és buida; s'eliminen els marges a zero i `name === id`

#Estils de xip

La propietat chipStyles declara els estils amb nom del :chip[texto]{style="…"} en línia: les caixes arrodonides i tintades d'un banc de paraules, una tecla, una etiqueta (la sintaxi i les seves regles de tall de línia són a la referència del format de document). Ve amb un estil per defecte, chip (emplenament blau pàl·lid amb un filet del color principal, cantonades una mica arrodonides i el text com les paraules que l'envolten), així que :chip[…] funciona sense configurar res; declarar chipStyles substitueix aquesta llista. Un xip sense style, o amb un id que cap estil no declara, pren el primer estil.

const config: PostextConfig = {
  chipStyles: [
    { id: 'chip', name: 'Banc de paraules' },
    {
      id: 'key',
      name: 'Tecla',
      background: { hex: '#fff4d6', model: 'hex' },
      borderColor: { hex: '#8a6d1f', model: 'hex' },
      borderRadius: { value: 2, unit: 'pt' },
      bold: true,
    },
  ],
};

Classifica: :chip[pila] :chip[cable] :chip[interruptor]
 
Prem :chip[Ctrl]{style="key"} + :chip[C]{style="key"}.

Les longituds en em de la caixa (paddingX, paddingY, borderRadius, borderWidth, gap) són relatives al cos del mateix xip. La caixa és una banda de 0,8 em per sobre i 0,25 em per sota de la línia de base, que creix amb paddingY i el contorn; es pinta fora de la caixa de línia i mai no canvia l'interlineat, així que la retícula es manté. Quan la caixa resulta més alta que l'interlineat, un xip pot envair un xip de la línia de sobre o de sota: el sandbox mostra l'avís «Els xips toquen la línia següent» quan dos xips de línies diferents se solapen, amb el solapament en punts, perquè redueixis paddingY, el contorn o fontSize. Un xip alt sense cap xip a sobre ni a sota no s'assenyala.

Al VDT un xip és un segment de línia de kind: 'chip' el camp chip del qual porta els trams de text (cadascun amb la seva cadena de font i la seva amplada), la geometria de la caixa (boxWidth, ascent, descent, paddingX, borderWidth, borderRadius, els marges del gap) i els seus colors; el text del segment és un marcador d'un caràcter, de manera que els desplaçaments de text pla i els mapes de font compten un xip com un caràcter.

const resolved = resolveChipStylesConfig(config.chipStyles);
// => l'estil `chip` integrat si no se'n declara cap; tots els camps plens
 
const minimal  = stripChipStylesDefaults(config.chipStyles);
// => undefined per al valor integrat; s'eliminen els valors per defecte
 
const style = pickChipStyle(resolved, 'key');
// => l'estil `key`, o el primer

#Llistats de codi

La propietat codeStyle fixa l'aspecte dels llistats de codi: les tanques ``` i ~~~ del text (vegeu Format del document › Blocs de codi), i el codi en línia quan demana una lletra de codi. Un llistat es compon línia a línia tal com està escrit, en una lletra monoespaiada, dins d'una caixa: cap línia no es parteix amb guionet ni es justifica, cada espai conserva la seva amplada i un tabulador avança fins a la tabulació següent. La caixa surt del mateix mecanisme que la d'un :::callout, de manera que un llistat es divideix entre línies a través de columnes i pàgines, cada part en una caixa pròpia, i una tanca dins d'un avís és una caixa niada dins seu. Totes les propietats són opcionals. Des de postext 1.23.

const config: PostextConfig = {
  codeStyle: {
    fontFamily: 'JetBrains Mono',
    fontSize: { value: 0.8, unit: 'em' },
    background: { hex: '#0e1116', model: 'hex' },
    color: { hex: '#d3d9df', model: 'hex' },
    padding: { top: { value: 4, unit: 'mm' }, right: { value: 5, unit: 'mm' }, bottom: { value: 4, unit: 'mm' }, left: { value: 5, unit: 'mm' } },
    borderRadius: { value: 2, unit: 'pt' },
    lineNumbers: true,
    tokens: {
      keyword: { color: { hex: '#f2b134', model: 'hex' }, bold: true },
      string: { color: { hex: '#3ddc84', model: 'hex' } },
      comment: { color: { hex: '#8a939d', model: 'hex' }, italic: true },
    },
    inline: { background: { hex: '#eef1f4', model: 'hex' } },
  },
};

#Colors de sintaxi

Un petit analitzador integrat al motor identifica els elements de js i ts (javascript, jsx, typescript, tsx), json, python, bash (sh, zsh, shell), console (una sessió de terminal), css, html i xml (svg), markdown i sql; un llistat en qualsevol altre llenguatge, o sense llenguatge, es compon en color. Llegeix tot el llistat, de manera que un comentari o una cadena que ocupa diverses línies continua sent un sol element. En un llistat console, una línia que comença amb un indicador d'ordres ($ , % , # , > , >>> , PS …> ) és el que ha escrit l'usuari (prompt), i totes les altres són el que han imprès els programes (output).

Una aplicació amfitriona connecta el seu propi ressaltador (Shiki, Prism, highlight.js) amb registerCodeHighlighter. Les configuracions són dades serialitzables, així que la funció es registra al motor, no s'escriu a codeStyle:

import { registerCodeHighlighter } from 'postext';
 
// fn(code, lang) retorna les línies del llistat, cadascuna com a trams els textos dels quals, units, formen la línia.
registerCodeHighlighter('rust', (code) => code.split('\n').map((line) => [
  { text: line, token: line.trimStart().startsWith('//') ? 'comment' : undefined },
]));
registerCodeHighlighter('*', null); // treu el registrat per a tots els llenguatges

Un ressaltador registrat per a un llenguatge té preferència sobre un de registrat per a '*', que té preferència sobre l'analitzador integrat. Un tram indica un tipus d'element token (acolorit per tokens) o un color propi (un hexadecimal CSS). Un ressaltador que retorna undefined, que llança una excepció o que retorna línies que, unides, no donen les del llistat es descarta. La composició consulta el registre quan compon un llistat: registra'l abans de compondre, i en un web worker (el Sandbox compon en un) registra'l dins del worker.

#Codi en línia

codeStyle.inline compon el text entre accents greus en una lletra de codi: com una sola unitat, igual que un xip, que una línia no parteix mai. Sense fixar, el codi en línia conserva la lletra del text.

#Com es compon un llistat

• Una línia per línia de la font. Les línies es construeixen amb els avanços propis de la lletra del codi, no amb el divisor de paràgrafs: els espais conserven la seva amplada, una sèrie d'espais es manté i els espais del principi sagnen. Un llistat en un llibre de dreta a esquerra es llegeix d'esquerra a dreta, amb les línies compostes des del costat més allunyat de la caixa com una cita d'esquerra a dreta, i els números al marge de la seva esquerra. En un llibre vertical, un llistat segueix el flux vertical (amb el text llatí ajagut, com el compon el text vertical) i no porta números de línia.
• Divisió. Un llistat més alt que l'espai que queda es divideix entre línies a través de columnes i pàgines, cada part emmarcada en una caixa pròpia, sense deixar mai menys de splitMinLines línies a cap costat; la resta d'una línia partida es queda amb ella si hi cap un altre tall.
• Sortides. El llenç, el visor HTML i el PDF pinten les línies i la caixa tal com s'han compost. El visor HTML conserva els espais (white-space: pre), de manera que una selecció copia el llistat amb el seu sagnat i un salt de línia després de cada línia de la font, sense números ni marques de continuació. Un PDF etiquetat compon cada llistat com un paràgraf que conté un element Code, amb glifs d'espai reals, i els números i les marques de continuació com a artefactes. L'EPUB adaptable escriu <pre><code class="language-…"> amb els colors dels elements i un full d'estil a partir de codeStyle; l'EPUB de maquetació fixa és el de la impressió.
• Fonts. El Sandbox i configFontFamilies carreguen la lletra del codi quan el text té una tanca (o la configuració té una secció codeStyle), en els pesos normal i negreta, rodona i cursiva; el PDF incrusta les lletres que fan servir les línies.

#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, taula o grup :::columns més alt 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. 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.

#Parts

La propietat parts configura les pàgines separadores de part que un document obre amb un contenidor :::part{number="…" title="…"} — la pàgina «Part I — Fonaments» que agrupa una sèrie de capítols. Una part ocupa sempre una pàgina pròpia: el contenidor salta a una pàgina nova amb la paritat configurada, la converteix en una pàgina d'una sola columna l'àrea de cos de la qual surt de parts.margins, compon el disseny d'obertura sobre la pàgina sencera i torna a saltar després de la tanca final perquè el capítol següent (amb el seu propi breakBefore.parity) comenci net — amb els valors per defecte d'H1 això produeix la seqüència clàssica: pàgina de part en recto, verso en blanc, capítol al recto següent.

const config: PostextConfig = {
  parts: {
    breakBefore: { parity: 'odd' },
    breakAfter: { enabled: true, parity: 'any' },
    margins: { top: { value: 9, unit: 'cm' }, left: { value: 3, unit: 'cm' }, right: { value: 3, unit: 'cm' } },
    design: {
      elements: [
        {
          kind: 'text', id: 'number', content: 'Part {numberRoman}',
          fontSize: { value: 12, unit: 'pt' }, fontWeight: 600, align: 'left',
          placement: { anchor: { to: 'page', edge: 'top-left' }, offset: { x: { value: 3, unit: 'cm' }, y: { value: 5, unit: 'cm' } }, size: { width: 'auto', height: 'auto' } },
        },
        {
          kind: 'text', id: 'title', content: '{titleText}',
          fontSize: { value: 28, unit: 'pt' }, fontWeight: 700, align: 'left', overflow: 'wrap',
          placement: { anchor: { to: '#number', edge: 'below' }, size: { width: { value: 15, unit: 'cm' }, height: 'auto' } },
        },
      ],
    },
    bodyStyle: { fontSize: { value: 11, unit: 'pt' }, numberColor: { hex: '#AA0000', model: 'hex' } },
  },
};

:::part{number="I" title="Fonaments"}
1. El fanal i les seves parts
2. Retallar el ble
3. Llegir el temps
:::
 
# El fanal i les seves parts

#Marcadors del disseny de part

El disseny resol el conjunt de marcadors d'encapçalament amb els valors propis de la part: {titleText} és el title de la tanca; {number} el number tal com s'ha escrit; {numberDecimal}, {numberRoman}, {numberRomanLower}, {numberAlpha}, {numberAlphaLower} el reformaten — el número s'interpreta com a decimal, com a numeral romà o com a numerals xinesos, amb les paraules que els envolten o sense ("IV", "iv", "4", "４", "四", "卷四" i "第四卷" donen {numberDecimal} = 4) i resolen a '' per a qualsevol altra cosa. També hi ha disponibles {partTitle} / {partNumber}, {chapterTitle} / {chapterNumber} (el capítol anterior a la part), {pageNumber}, {totalPages}, {bookTotalPages} i els marcadors de metadades. {attr.<key>} llegeix els atributs de l'H1 del capítol actual.

#El disseny del verso

versoDesign decora la pàgina que segueix la de part quan aquesta pàgina no té contingut: el revers del full separador. La part tota sola mai no deixa aquesta pàgina en blanc. breakAfter.parity val 'any' per defecte, així que el contingut després de la tanca comença a la pàgina següent tret que alguna cosa demani una paritat:

• El títol del capítol següent. El breakBefore per defecte de l'H1 és 'always-odd', i 'odd' fa el mateix després d'una pàgina de part en recto: el capítol passa al recto següent i el verso queda en blanc. El disseny del verso es pinta.
• parts.breakAfter: { enabled: true, parity: 'odd' }. La mateixa part demana el recto següent, faci el que faci el títol següent. Fes-lo servir quan els capítols puguin obrir en qualsevol cara (breakBefore.parity: 'any', o breakBefore.enabled: false).

Sense cap dels dos, el capítol obre al verso i no es dibuixa disseny de verso. Amb breakAfter.enabled: false el contingut continua a la mateixa pàgina de part. El verso pren la paleta de la part, així que un palette="band=#…" a la tanca també el recoloreja.

parts: {
  breakBefore: { parity: 'odd' },
  breakAfter: { enabled: true, parity: 'odd' },   // sempre queda un verso en blanc per pintar
  versoDesign: {
    elements: [{
      kind: 'box', id: 'campo',
      style: { backgroundColor: { hex: '#b07d2b', model: 'hex', paletteId: 'band' } },
      placement: { anchor: { to: 'page', edge: 'top-left' }, size: { width: 'fill', height: 'fill' } },
    }],
  },
}

Una part que tanca el seu capítol. En un llibre maquetat capítol a capítol (el Sandbox, buildBundle), una tanca :::part pot ser un capítol tota sola, o el final d'un. La seva pàgina de part és llavors l'última del capítol, i el capítol següent assumeix el que la part encara deu: aplica breakAfter abans del seu primer bloc i pinta versoDesign a la seva primera pàgina quan aquesta queda en blanc. Les pàgines surten com sortirien amb el llibre sencer en un sol document. Després de la tanca només hi poden venir directives que no col·loquen res (:::numbering, :::space); qualsevol altra cosa és contingut del capítol, que llavors fa el salt per si mateix. Un capítol buit just després de la part és una pàgina pròpia: aquesta pàgina és el verso. Un amfitrió que maqueta els capítols pel seu compte ho obté de continuationAfter(), que retorna afterPartPage: true per a un capítol que acaba amb una part; passa-ho a la continuation del capítol següent.

#El contenidor :::part

Una línia :::part{number="…" title="…"} obre la part i un ::: tot sol la tanca; els dos atributs són opcionals (per defecte ''). Els blocs intermedis — normalment la llista de capítols — flueixen a la columna única de la pàgina de part amb bodyStyle, començant a margins.top; un cos més llarg que la pàgina continua en pàgines normals. La pàgina es classifica com a role: 'part' (VDTPage.partInfo porta el número i el títol), de manera que els elements de capçalera i peu poden adreçar-s'hi o saltar-se-la amb pages: 'part' / pages: 'body'; el backend PDF afegeix la part a l'esquema per sobre dels seus capítols. Un cos buit (:::part{…} seguit directament de :::) és el cas habitual i també produeix la pàgina — dues parts consecutives mai no en comparteixen una. Un :::part niat dins d'una altra part s'aplana a l'exterior.

Un tercer atribut, palette="<id>=<hex>[, <id>=<hex>…]", dona a la part els seus propis colors: a la pàgina de part i a totes les que la segueixen — fins a la part següent — cada color de disseny (capçalera, peu, banda d'obertura, dissenys de part i del seu verso) vinculat a un d'aquests ids de paleta pren el valor de la part en lloc del de la paleta del document. Així recoloregen les seccions d'un llibre la pestanya de la cantonada, el punt de la capçalera i la banda d'obertura de capítol sense un segon disseny: :::part{number="II" title="…" palette="band=#f6c297"}. El flux de text també ho segueix: en aquestes mateixes pàgines, tot color del flux igual al valor base d'una entrada de paleta substituïda —títols, colors de negreta, cursiva i referències, vinyetes i números de llista, etiquetes i barres de peu, text, filets i farciments de taules (capçalera, cos, files alternes i el farciment propi d'una cel·la), requadres (fons, vora, franja i títol) i xips (farciment, contorn i text)— pren el valor de la part, de manera que un headings.levels[1].color vinculat a band compon els títols de cada secció en el seu propi color. Les mostres de color en línia conserven el color que s'hi ha escrit. Els parells se separen amb comes, punts i comes o espais, = o : uneix id i color, i la # és opcional. Una part continua vigent un cop acabada la seva tanca: {partTitle}, {partNumber} i la paleta acompanyen el flux fins als capítols posteriors i — mitjançant continuation.part, que retorna continuationAfter() — fins als capítols compostos per separat, de manera que el segon capítol d'una secció mostra la secció a les capçaleres exactament igual que el primer.

Dues entrades de la paleta poden compartir valor base i tot i així prendre valors diferents en una part, quan la part en substitueix una i no l'altra o els dona colors diferents. El valor tot sol no indica de quina entrada ve un color del flux, així que cada color del flux s'aparella amb els ajustos dels quals pot venir i pren el valor al qual enllacen aquests ajustos. Es distingeixen:

• els colors del text d'un bloc: el color del text, els de negreta, cursiva i referències, la vinyeta o el número de llista i el separador que segueix el número. Amb bodyText.color vinculat a ink i bodyText.boldColor vinculat a accent, tots dos #1a1a1a, una part amb palette="accent=#b8413d" recoloreja les negretes i deixa el text; si el que es vincula a accent és unorderedLists.color, recoloreja les vinyetes i deixa el text dels elements;
• cada nivell d'encapçalament, i cada estil d'encapçalament que fixa un color;
• el text d'una fila de l'índex, el seu número, i el seu número de pàgina i el seu subtítol;
• en cada estil de requadre, els farciments (fons, franja, pestanya de l'etiqueta), la vora, els filets (del marcador i de l'etiqueta) i el text (títol, icona, glif del marcador, etiqueta);
• cada color de cada estil de taula, de xip i de peu. Un estil de taula amb nom es distingeix de tableStyle, i l'estil de peu d'un tipus de recurs de captionStyle. El farciment propi d'una cel·la segueix el seu propi enllaç.

Queda un cas que es resol per valor: ajustos de llocs diferents que fixen el mateix color d'un bloc. Per exemple, bodyText.color, bodyText.blockquote.color, el color d'un estil de paràgraf i el body.color d'un estil de requadre fixen tots el color del text d'un bloc. Quan dos d'ells enllacen a entrades que comparteixen valor base i la part les separa, el color pren la substitució (l'última escrita, si se substitueixen totes dues). Dona a aquestes entrades valors base propis.

const resolved = resolvePartsConfig(config.parts, resolvedPage, resolvedBodyText, resolvedUnorderedLists, resolvedOrderedLists);
// => marges omplerts des de la pàgina, bodyStyle des del cos / les llistes
 
const minimal = stripPartsDefaults(config.parts);
// => undefined quan només queden valors estàtics per defecte

#Estils d'encapçalament

La propietat headingStyles declara estils amb nom que un document aplica a un encapçalament amb # Título {style="<id>"}. Un estil fa dues coses. Sobreescriu la tipografia, el disseny i la numeració del nivell de l'encapçalament — qualsevol camp d'una entrada de nivell excepte level (font, cos, color, breakBefore, span, advancedDesign, textTransform, hidden, numberingTemplate…) — i governa la secció que obre l'encapçalament: les seves pàgines, fins al següent encapçalament del mateix nivell o superior, prenen les capçaleres, la geometria de pàgina, la tipografia de cos i la paleta de l'estil. Així els preliminars d'un llibre (un pròleg a una sola columna ampla, amb folis en romans i bandes blaves) conviuen en un manual a dues columnes i numeració decimal sense una segona configuració.

const config: PostextConfig = {
  headingStyles: [
    {
      id: 'preliminar',
      numbered: false,
      breakBefore: { enabled: true, parity: 'odd' },
      span: 'page',
      advancedDesign: { enabled: true, minHeight: { value: 52, unit: 'mm' }, slot: { elements: [/* bandes, `{titleText}` */] } },
      header: { elements: [/* foli | filet | `{title}. {subtitle}` */] },
      margins: { left: { value: 50, unit: 'mm' }, right: { value: 17, unit: 'mm' } },
      layout: { layoutType: 'single' },
      bodyStyle: { fontSize: { value: 10.5, unit: 'pt' }, textAlign: 'justify' },
      palette: { band: '#547396' },
    },
  ],
};

# Pròleg {style="preliminar"}

Una secció es tanca al següent encapçalament del mateix nivell o superior: un # sense estil després d'un amb estil torna a les capçaleres i la geometria del document; un amb estil obre la seva pròpia secció. Les pàgines que la secció deixa en blanc per paritat li pertanyen, com passa amb els títols de capítol.

Un salt de pàgina no substitueix el salt del mateix encapçalament. Un estil hereta el breakBefore del seu nivell (el del nivell 1 és, per defecte, { enabled: true, parity: 'always-odd' }), i l'encapçalament l'aplica sigui on sigui, també just després d'un :::pagebreak. El salt de pàgina obre una pàgina nova, i l'encapçalament demana després, igualment, el seu costat del plec. Amb parity: 'odd', un salt que cau en una pàgina parella va seguit d'una pàgina en blanc, de manera que l'encapçalament obre a la següent senar. Amb 'always-odd' s'hi afegeix a més la pàgina separadora, i el salt de pàgina no canvia res, perquè l'encapçalament hauria obert aquesta pàgina de totes maneres. Un estil que ha de començar a la pàgina que obre un salt manual, com un índex darrere de la portada, desactiva el seu propi salt:

headingStyles: [
  // Comença on el deixa el text: a la pàgina que va obrir el `:::pagebreak` anterior.
  { id: 'contents', numbered: false, toc: false, breakBefore: { enabled: false } },
],

Per conservar una pàgina pròpia sense triar costat, fes servir en lloc d'això breakBefore: { parity: 'any' } i prescindeix del :::pagebreak.

A quina secció pertany una pàgina. Les capçaleres i la paleta es trien per pàgina, no per encapçalament. Una pàgina pren la secció vigent després de l'últim canvi de secció que hi ha: quan una secció acaba i una altra comença a la mateixa pàgina — dues lletres curtes d'un diccionari, per exemple —, la pàgina porta les capçaleres i la paleta de la segona; quan una secció amb estil acaba a mitja pàgina en un encapçalament sense estil, la pàgina torna a les del document. {chapterTitle} segueix la mateixa regla: una pàgina on es troben dos capítols mostra el títol del segon. Les pàgines en blanc segueixen la regla dels títols de capítol: una pàgina en blanc de paritat (blankForParity) pertany a la secció que s'obre després, i la separadora que afegeix un salt 'always-odd' / 'always-even' (blankForForce), a la secció anterior. Una pàgina divisòria de part tanca la secció oberta.

# A {style="letra"}
 
Abac, abella.
 
# B {style="letra"}
 
Babel, bavall… (continua a la pàgina següent)

Les dues lletres comencen a la pàgina 1, així que la pàgina 1 pren les capçaleres de la secció B: una pestanya d'osca posada a la capçalera de l'estil hi diu «B», i cap pàgina no porta la pestanya de l'«A». Dona a cada secció una pàgina pròpia (breakBefore) quan totes necessiten la seva pestanya. Apèndixs amb lletra després de capítols numerats, i una pàgina de dedicatòria que l'índex i els marcadors del PDF inclouen però que la pàgina no titula:

headingStyles: [
  { id: 'apendice', numberingTemplate: 'Apèndix {1:A}' },
  { id: 'silencioso', hidden: true, numbered: false },
],

# Dedicatòria {style="silencioso"}
 
Per a M., que va llegir tots els esborranys.
 
# Mètode
 
…
 
# Qüestionari {style="apendice" startAt=1}
 
# Dades en brut {style="apendice"}

Amb numberingTemplate: '{1}.' al nivell 1, els capítols imprimeixen 1., 2.…, i els apèndixs Apèndix A i Apèndix B. La dedicatòria obre la seva pàgina (el breakBefore del seu nivell), imprimeix només el seu paràgraf i continua apareixent com a Dedicatòria a :::toc, a les capçaleres amb {chapterTitle} i als marcadors del PDF; afegeix toc: false a l'estil per deixar-la fora de l'índex. Una làmina o un mapa que es compon com a H1 enmig d'un capítol demana el contrari que la dedicatòria: un estil amb runningChapter: false (normalment amb numbered: false i toc: false) manté les capçaleres en el capítol que interromp.

const resolved = resolveHeadingStylesConfig(config.headingStyles, resolvedPage, resolvedBodyText, resolvedUnorderedLists, resolvedOrderedLists);
// => sobreescriptures de nivell normalitzades, marges presos de la pàgina, bodyStyle del cos
 
const minimal = stripHeadingStylesDefaults(config.headingStyles);
// => undefined quan no queda cap estil