Capítol 5.1 · Part II · L'ofici
Format del document: directives
Les directives que comencen amb ::: (contenidors, columnes, paper, salts de pàgina, numeració, espai, vers, índex general i índex analític, salts de línia) i el marcatge de les pàgines de còmic
En poques paraules
Una directiva és un bloc que comença amb tres signes de dos punts seguits, com ara :::callout o :::columns. Aquesta pàgina explica totes les directives i què fa cadascuna. Algunes posen el text en un requadre, el componen en columnes o l'imprimeixen en una altra classe de paper. D'altres comencen una pàgina nova, canvien la numeració, afegeixen espai, componen un poema vers a vers o imprimeixen l'índex general i l'índex analític. L'última secció explica les marques de les pàgines de còmic, de les vinyetes i de les paraules dels personatges.
#Directives
Les directives són ordres de control d'una sola línia, escrites com a :::nom o :::nom{atributs} en una línia pròpia. La majoria no produeix res de visible i controla la col·locació i la numeració; :::toc, :::index i :::bibliography imprimeixen el sumari, l'índex analític i la bibliografia allà on són.
| Sintaxi | Efecte |
|---|---|
:::pagebreak | Força que el bloc següent comenci en una pàgina nova. |
:::pagebreak{parity="odd"} | Igual, i a més garanteix que la pàgina nova sigui senar (la de la dreta). Si cal, insereix una pàgina en blanc. |
:::pagebreak{parity="even"} | Igual, però amb una pàgina parella (la de l'esquerra). |
:::pagebreak{parity="always-odd"} | Garanteix com a mínim una pàgina en blanc de separació abans d'arribar a una pàgina senar. La pàgina de separació pertany al contingut anterior; qualsevol altra pàgina en blanc afegida per paritat pertany al que ve després. És útil quan cada capítol ha de començar en una doble pàgina nova. |
:::pagebreak{parity="always-even"} | Igual, però amb una pàgina parella. |
:::numbering{format="decimal" startAt=1} | Al límit de pàgina següent, canvia la seqüència de numeració. Tots dos atributs són opcionals: omet format per mantenir el format, i startAt, per continuar el comptador. |
:::columnbreak | Acaba aquí la columna actual: el bloc següent comença a la columna següent de la mateixa pàgina (o en una pàgina nova quan la directiva cau a l'última columna). No fa res en una columna buida, així que mai no genera una columna o una pàgina en blanc. La columna que acaba conserva el buit inferior: l'equilibratge de columnes no l'estira. En el text d'un marc d'una pàgina composta que continua en un altre (el marc següent de la seva cadena, o una altra pàgina), el que segueix la directiva obre aquest marc encara que cabés al primer (postext 1.78); un marc que no pot continuar compon el seu text seguit. |
:::space | Deixa aquí una línia de text en blanc: és la manera explícita de donar una mica d'aire entre dos blocs. :::space{lines=2} en deixa dues (també valen fraccions com 0.5). Se suma al marge entre els blocs i desapareix al principi d'una columna o pàgina. Vegeu més avall. |
:::toc | Imprimeix aquí l'índex general: una entrada per encapçalament dels nivells indicats (títol, número, número de pàgina i, opcionalment, els autors del capítol) i una fila per cada separador de part, compostes segons la configuració toc. Les entrades segueixen el document: si canvies el nom d'un capítol, el mous o el renumeres, l'índex s'actualitza. |
:::index | Imprimeix aquí l'índex analític: tots els termes marcats amb :index al llibre, ordenats i agrupats per inicial, amb les pàgines on cauen, compostos segons la configuració index. :::index{index="nombres"} imprimeix un índex amb nom. Vegeu Índex analític. |
:::bibliography | Imprimeix aquí la llista d'obres citades, en l'estil de citació. title en canvia el títol i scope, el que hi entra. Vegeu La bibliografia. |
:::page{…} … ::: | Una pàgina de còmic: les línies ::panel i les línies de guió que les segueixen, compostes com a vinyetes i bafarades retolades en una pàgina pròpia. Vegeu Còmics. |
:::strip{…} … ::: | Una tira còmica dins del flux del text, de l'amplada d'una columna o de la pàgina. Vegeu :::strip. |
:::verse … ::: | Un poema, compost línia a línia tal com s'escriu (cada línia, un vers; línies en blanc entre estrofes; espais inicials com a sagnat), o a la manera àrab clàssica quan les línies separen els hemistiquis amb ||. Vegeu més avall. |
Els valors dels atributs poden anar entre cometes dobles ("…"), cometes simples ('…') o sense cometes (startAt=17). Una clau sense = es tracta com un indicador present amb valor buit.
Avui només es reconeixen pagebreak, numbering, columnbreak, space, toc, index i bibliography com a directives d'una sola línia (i references, verse, page, strip i figure com a blocs delimitats); qualsevol altra línia :::nombre que no sigui un contenidor (més avall) s'analitza com a paràgraf i genera un avís Directiva desconeguda al Sandbox. El motor també ho registra, com una entrada unknownDirective als contentWarnings del document (vegeu Configuració › Avisos del document).
#Valors dels atributs
La mateixa sintaxi clave="valor" la fan servir els atributs d'encapçalament, les línies d'obertura de directives i contenidors (:::nombre{…}), les referències en línia (:ref{…}), els xips (:chip[…]{…}), les mostres de color (:swatch{…}) i les marques d'índex (:index[…]{…}). Les seves regles:
- Claus. Comencen per una lletra ASCII o
_i continuen amb lletres ASCII, dígits,_o-. S'admeten espais al voltant de l'=, l'=d'amplada completa que escriu un mètode d'entrada xinès val com a=, una clau repetida es queda amb l'últim valor, i una clau sense=és un indicador amb valor buit. Una clau en una altra escriptura (作者=曹雪芹) no es llegeix i genera un avísattributeKeyInvalid; les altres claus del bloc s'apliquen igualment. Els valors admeten qualsevol escriptura. - Valors entre cometes. Un valor entre cometes dobles pot contenir qualsevol cosa llevat de
", cometes simples incloses; un entre cometes simples, qualsevol cosa llevat de'. Així, un valor amb cometes dobles va entre simples:lead='Dijo "hola"'. No hi ha seqüències d'escapament (la barra inversa és un caràcter normal), així que un valor que necessiti els dos tipus de cometes ASCII ha de fer servir cometes tipogràfiques («…»,“…”,’). Un valor també es pot obrir amb la cometa“o el claudàtor de cantonada「que escriu un mètode d'entrada xinès, i llavors arriba fins a la”o el」corresponents, espais inclosos:title=“甲戌本 眉批”,title=「脂批」. - Valors sense cometes (
startAt=17,year=1998) arriben fins a l'espai següent:title=Hola mundoéstitle="Hola"més un indicadormundo. - Sense claus.
{i}no van mai en un valor. La primera}tanca el bloc: una línia d'obertura amb un valor que en contingui una deixa de ser una directiva i passa a ser un paràgraf, i, en línia, la resta del valor passa al text. En un encapçalament, una clau dins d'un valor deixa tot el bloc al títol:# Título {nota="a {b"}es compon tal com està escrit. (Fins a postext 1.8, una{després d'un espai tornava a començar el bloc ibes llegia com a indicador.) - El signe
$és text. Els atributs es llegeixen abans que les fórmules en línia, així quelead="de 5 $ a 6 $"és només text. - Una línia. Un bloc d'atributs no ocupa mai més d'una línia.
- Identificadors.
#idea-clau, l'abreviatura de Pandoc, equival aid="idea-clau":{#sec-metode}en un encapçalament,:::callout{#caixa-seguretat}en una línia d'obertura. Dona nom al bloc per a les referències creuades.
# El llarg camí {lead='Una "novel·la de carretera", van dir' precio="18 $"}
:::callout{type="note" title='El camí "ràpid"'}
…
:::::resource{id="…"} és més estricte: l'id entre cometes dobles i cap altre atribut (consulta Recursos). En una pàgina composta admet a més slot="…" (vegeu Pàgines compostes).
#Contenidors
Un contenidor embolcalla una sèrie de blocs dins d'un bloc delimitat: una línia d'obertura :::nombre o :::nombre{atributos}, després qualsevol contingut normal (paràgrafs, encapçalaments, llistes, cites, fórmules, fins i tot altres directives) i una línia de tancament amb un ::: sol. Els contenidors es poden niar; cada ::: de tancament tanca el més intern dels oberts.
:::callout{type="note"}
Mantén la llanterna encesa **totes** les nits.
- Revisa el ble.
- Retalla'l al capvespre.
:::
Al flux del text es reconeixen cinc noms de contenidor; :::frame i :::module contenen el contingut d'un marc i d'un mòdul en una pàgina composta, i :::figure i :::label, una figura i un rètol de diverses línies. El que renderitza cadascun es defineix a la seva secció de la configuració:
| Sintaxi | Efecte |
|---|---|
:::callout{…} … ::: | Contingut en una caixa: una nota, un consell o una advertència separats del cos en una caixa amb vora o amb fons de color. |
:::paragraphs{…} … ::: | Una sèrie de paràgrafs composts amb un estil de paràgraf amb nom (una entradeta, un epígraf, unes notes en lletra petita) en lloc de l'estil del cos. align, indent i endIndent fixen l'alineació i els sagnats, amb estil o sense: :::paragraphs{align=end endIndent=1} compon una data a un caràcter del final de la línia (地から1字上げ). dropcap activa o desactiva una caplletra al seu primer paràgraf. |
:::part{…} … ::: | Una obertura de part o de secció: l'encapçalament i el text que conté formen la pàgina d'obertura d'una divisió major. |
:::paper{…} … ::: | Una sèrie de pàgines impreses en un altre paper, com un quadern de làmines en estucat brillant dins d'un llibre en paper mat. Només ho mostra el visor Folio. |
:::columns{…} … ::: | Blocs compostos en diverses columnes pròpies: dins d'un requadre, a la columna de text o a tota l'amplada d'una pàgina de diverses columnes. Vegeu :::columns més avall. |
Els atributs que admet cada contenidor, i com s'estilitza, es documenten a Configuració. Els valors dels atributs segueixen la mateixa gramàtica que les directives. Una línia d'obertura :::callout admet type (l'id d'un estil de requadre configurat; els tipus desconeguts o absents fan servir el primer estil), title (substitueix el títol per defecte de l'estil) i span / placement (column, page o side; here, top, bottom o fixed) per sobreescriure l'extensió i la posició de l'estil en aquella caixa:
:::callout{type="objectives" title="Què aprendràs" span="page" placement="top"}
- Anomenar les parts de la llanterna.
- Retallar el ble sense tocar el vidre.
:::
Una caixa flotant (placement auto, top o bottom) admet a més columns, el nombre de columnes contigües que ocupa en una pàgina de diverses, com a :::callout{placement="top" columns="2"} (des de postext 1.18).
Una caixa també pot tenir al costat el text que la segueix: wrap (left, right, start o end), width (la fracció de la columna que ocupa, de 0 a 1; layout.wrap.defaultWidth si no s'indica) i wrapGap (una longitud, com 6pt), com a :::callout{wrap="right" width=0.4} (vegeu Ajust del text; des de postext 1.24).
Un requadre es compon com una caixa: un títol opcional i després el contingut, amb la tipografia de cos i de llistes pròpia de l'estil. Per defecte es manté sencer i passa a la columna o la pàgina següent quan no hi cap (una caixa més alta que una columna sencera es parteix igualment, en lloc de desbordar); un estil amb keepTogether: false en permet el tall entre blocs, o entre línies, deixant com a mínim splitMinLines línies de text (o una figura, una taula, una fórmula en bloc o una caixa niada) a cada costat del tall (un tall dins d'un paràgraf o d'un element de llista deixa, a més, almenys layout.boxChildSplitMinLines de les seves línies a cada costat: dues per defecte, splitMinLines si és menor; els llibres desats abans de la 1.5 amb capítols que tenen requadres es llegeixen amb 1, el tall de la 1.4). Cada part posterior a la primera comença sense la icona, encara que el text conserva la columna de la icona, i sense el títol llevat que l'estil el repeteixi (repeatTitle: «Punts clau (cont.)»); a més, un estil pot posar una marca «Continua» sota cada part que té continuació (continuesMarkerEnabled); vegeu Marques d'un requadre partit. Les caixes d'amplada completa (span="page") tallen la pàgina en bandes de columnes; les caixes span="side" surten del flux cap a la columna lateral només per a flotants d'una disposició de columna i mitja (layout.sideColumnRole: 'floats'), apilades al costat del text que interrompen, i es componen com a caixes de columna on no existeix aquesta columna; les caixes placement="fixed" surten del flux i es fixen a coordenades de pàgina (per exemple, un distintiu d'autoavaluació a la cantonada inferior esquerra de l'última pàgina del capítol), i les columnes que cobreixen cedeixen aquella zona; les caixes flotants (placement="top" / "bottom") surten del flux on apareixen i ocupen la primera banda lliure després d'aquella posició (el peu de la pàgina, o el capdamunt o el peu de la següent), mentre el text que les segueix omple la pàgina que han deixat. Un estil amb floatBarrier: true (normalment la caixa de «punts clau» que tanca el capítol) converteix la caixa en una barrera de flotants: totes les figures i taules citades abans es col·loquen abans que ella (als espais lliures de la pàgina, o en pàgines obertes abans de la caixa), de manera que cap flotant no passa del final del seu capítol. Una línia :::nombre desconeguda no és un contenidor: la línia es tracta com a text, exactament igual que una directiva desconeguda.
Una línia d'obertura :::part admet number (tal com el vulguis imprimir: "I", "IV", "3"; a més, s'interpreta perquè el disseny el pugui tornar a formatar) i title; tots dos són opcionals. Un tercer atribut, palette="band=#hex" (diversos parells id=#hex separats per comes), canvia tots els colors del disseny vinculats a aquests ids de paleta (capçaleres, banda d'obertura, dissenys de part) i els colors del flux de text que comparteixen el mateix valor base (encapçalaments, negreta, referències, vinyetes de llista, peus, taules, requadres, xips) per a la part i els capítols que la segueixen, fins a la part següent; vegeu Configuració › Parts. El contenidor sempre obre una pàgina pròpia: un salt de pàgina amb la paritat configurada abans, una única columna de cos als parts.margins, el disseny d'obertura sobre la pàgina sencera i un altre salt de pàgina després de la línia de tancament. El cos (normalment la llista dels capítols que agrupa la part, o res) es compon amb parts.bodyStyle:
:::part{number="I" title="Fonaments"}
1. El fanal i les seves parts
2. Retallar el ble
:::
# El fanal i les seves parts
Amb els valors per defecte dels encapçalaments això produeix la seqüència clàssica: pàgina de part en pàgina dreta, pàgina esquerra en blanc, capítol a la pàgina dreta següent. La pàgina es marca amb role: 'part' perquè les capçaleres i els peus de pàgina la puguin ometre, i {partTitle} / {partNumber} es resolen a la part actual en totes les pàgines següents. Consulta Parts a la referència de configuració.
Una línia d'obertura o de tancament no necessita cap línia en blanc al davant: si va just a sota d'un paràgraf, d'una llista o d'una cita, acaba aquell bloc. Un contenidor que queda obert al final del document es tanca automàticament allà, i el Sandbox mostra un avís Contenidor sense tancar que indica la línia d'obertura. Un ::: solt sense cap contenidor obert es deixa al text com un paràgraf visible en lloc de descartar-se en silenci.
#:::columns
Un grup :::columns{count=2} … ::: compon els blocs que hi ha entre les línies d'obertura i de tancament en count columnes d'igual amplada (de 2 a 6), i el text posterior recupera l'amplada completa. Dins d'un :::callout les columnes es reparteixen l'amplada interior de la caixa, separades pel columnGap de l'estil, amb la tipografia de cos i de llistes de la caixa, i la caixa creix fins a la columna més alta. Al text corregut (des de postext 1.25) es reparteixen la columna de text, separades per una línia del cos, i els blocs conserven la tipografia del mateix text; amb span="page", en una pàgina de diverses columnes, el grup talla la pàgina en una banda com una caixa a amplada completa: les columnes de sobre tanquen anivellades, el grup es compon a tota l'amplada del contingut (separat per l'espai entre columnes) i el text continua a totes les columnes per sota. En una pàgina d'una sola columna, span="page" el compon a la columna. Els encapçalaments dins d'un grup conserven l'estil, el número i l'entrada a l'índex general; una nota a peu de pàgina citada al grup va al peu de la columna de text, i les figures que cita floten com sempre.
| Atribut | Efecte |
|---|---|
count | Quantes columnes, de 2 a 6. Per defecte, 2. |
gap | L'espai entre les columnes, una longitud (12pt, 1em, 4mm). Per defecte: el columnGap de l'estil de requadre en un requadre, una línia del cos a la columna de text, layout.gutterWidth a tota l'amplada de la pàgina. |
rule | Traça un filet al llarg de cada separació, amb el color i el gruix de layout.columnRule: :::columns{count=3 rule}. |
breaks | Els blocs que obren cada columna a partir de la segona, en lloc d'anivellar-les: breaks="4" obre la segona columna al quart bloc del grup (una llista separada per comes per a més columnes). Més avall s'explica com compta. |
flow | Com continua un grup que no hi cap: snake (el valor per defecte sense breaks) o parallel (el valor per defecte amb breaks). Vegeu Partir un grup. |
span | Només al text corregut: column (el valor per defecte) o page. |
marginTop | L'espai sobre el grup, una longitud com la de gap. Es fon amb l'espai pendent sobre el grup; no n'hi ha cap al cap d'una columna, ni quan el grup obre el seu requadre. Des de postext 1.28. |
marginBottom | L'espai sota el grup, una longitud; 0 demana que no n'hi hagi cap. Al text corregut ocupa el lloc de la separació entre paràgrafs del cos; en un requadre és l'espai abans del bloc següent. Des de postext 1.28. |
Un grup compost sencer es talla allà on millor s'anivellen les columnes (entre blocs, o entre les línies d'un paràgraf o d'un element de llista, que continua al capdamunt de la columna següent sense la vinyeta), llevat que breaks fixi on comença cada columna, sense tallar dins d'un paràgraf: una columna de text al costat d'una columna amb una figura. Un tall dins d'un paràgraf o element de llista deixa com a mínim bodyText.widowMinLines de les seves línies al peu de la columna i bodyText.orphanMinLines al capdamunt de la següent (dues de cada per defecte; una quan avoidWidows o avoidOrphans està desactivat), i l'espai abans d'un bloc desapareix al capdamunt d'una columna. Dels talls que aquestes regles permeten, el grup tria el que deixa més baixa la columna més alta: dos paràgrafs de sis i cinc línies queden 6 | 5, mai 5 | 1 + 5 (des de postext 1.39).
L'espai al voltant d'un grup. Al text corregut, un grup va seguit de la separació entre paràgrafs del cos (una línia amb bodyText.paragraphSpacing, res sense), i dins d'un requadre de cap espai propi. marginTop i marginBottom a la línia d'obertura el fixen: :::columns{count=3 span="page" marginBottom="0.75em"}. Cadascun és un mínim que es fon amb l'espai que el bloc veí es reserva, com els marges d'un requadre. Al text corregut el flux torna a la retícula de base sota el grup, de manera que l'espai surt en línies senceres, i un grup dividit entre columnes o pàgines conserva el marge superior per a la primera part i l'inferior per a l'última. Un em és la mida del text on es troba el grup; un valor que no és una longitud, o un de negatiu, s'ignora.
:::callout{type="summary"}
:::columns{count=2}
- Cada element és un tipus d'àtom.
- Els electrons viuen en orbitals.
- Un enllaç comparteix o transfereix electrons.
:::
:::Com compta breaks. breaks numera els blocs del grup per ordre (paràgrafs, elements de llista, que compten com un bloc cadascun, fórmules en bloc, figures i taules), i un :::callout niat compta com un sol bloc, en tingui els que en tingui a dins. Les directives no són blocs: un :::space entre dues estrofes no altera el compte. Un nombre menor que 2, posterior a l'últim bloc del grup o que no va després del tall anterior s'ignora. Dins d'un grup, :::space separa dos blocs com en qualsevol altre punt del requadre, i desapareix al principi del grup i al capdamunt de cadascuna de les seves columnes (una posició de breaks o un tall d'anivellament); per començar el grup més avall, posa l'espai abans de la línia :::columns. Així, dues columnes amb els mateixos espais queden alineades estrofa a estrofa:
:::callout{type="verso"}
:::columns{count=2 breaks="4"}
La llàntia s'encén al capvespre,
i se li talla el ble abans de l'alba.
:::space
El faroner dorm de dia.
The lamp is lit at dusk,
and trimmed before the dawn.
:::space
The keeper sleeps by day.
:::
:::Aquí el quart bloc, «The lamp…», obre la segona columna; les dues línies :::space no compten i deixen el mateix buit a totes dues columnes.
Partir un grup
Des de postext 1.25, un grup que no cap en l'espai que té (el que queda de la columna al text corregut, o la part d'una caixa que es parteix, amb keepTogether: false o perquè és més alta que una columna) es talla entre les seves columnes i continua a la columna o la pàgina següent, en una caixa pròpia si el grup és en un requadre:
flow="snake", el valor per defecte sensebreaks: els blocs del grup corren com una sola galerada, com el text d'una notícia de diari. Una part que continua omple les columnes per torns, tan anivellades com permeten els talls, tallant entre blocs o entre les línies d'un paràgraf o element de llista (almenyslayout.boxChildSplitMinLineslínies seves a cada costat, dues per defecte); l'última part s'anivella com un grup sencer.flow="parallel", el valor per defecte ambbreaks: cada tram que obren els talls és un flux que conserva la seva pròpia columna. Una part omple cada flux fins a l'espai que té, i cadascun continua a la mateixa columna de la part següent, de manera que un poema i la seva traducció compostos un al costat de l'altre queden anivellats estrofa a estrofa. Un grup paral·lel sensebreakscontinua com un grup en serpentina.
Una caixa niada dins d'un grup queda sencera i passa a la part següent, i un grup dins d'una caixa niada no es talla mai. Un grup que hi cap es compon exactament com abans. layout.flowColumns: false conserva les regles de postext 1.24: un bloc fora d'un requadre s'ignora i un grup no es talla mai; els llibres desats abans de la 1.25 que tenen un grup :::columns es llegeixen així. El Sandbox dona un avís si troba un flow desconegut (Flux de columnes desconegut) o columnes més estretes que sis quadratins del seu text (Columnes massa estretes).
## Breus
:::columns{count=3 span="page" rule}
**Port.** El nou moll s'inaugura dilluns…
**Mercat.** El lloguer de les parades no canvia…
**Temps.** Pluja des de l'oest al vespre…
:::Una línia d'obertura :::callout també admet label="…": el text que un estil amb pestanya label imprimeix a la cantonada superior de la caixa (:::callout{type="recuadro" label="RECUADRO 1-1" title="La regla del octeto"}). Qualsevol altre atribut de la línia d'obertura el llegeix el disseny de l'estil, si en té: :::callout{type="targeta" kicker="Nota"} dona als seus textos {attr.kicker}, i {boxText} imprimeix el contingut del mateix requadre (vegeu Configuració › Dissenys de requadre).
Un :::callout dins d'un altre és una caixa independent (una fitxa d'exercici amb requadres de resposta, per exemple). Té el seu estil (fons, vora, radi, farciment, títol, icona), ocupa tota l'amplada interior de la caixa exterior i s'apila entre els altres blocs; el span i el placement s'ignoren, perquè una caixa niada sempre va dins de la caixa que la conté. Cada línia de tancament tanca la caixa oberta més interna:
:::callout{type="ficha"}
L'enunciat de l'exercici.
:::callout{type="respuesta"}
Un requadre blanc de resposta amb la seva pròpia vora i farciment.
:::
:::callout{type="respuesta"}
Un segon requadre de resposta.
:::
:::Quan la caixa exterior es parteix entre columnes o pàgines (keepTogether: false, o més alta que una columna), una caixa niada passa sencera al fragment següent llevat que el seu propi estil permeti partir-la també; cada fragment torna a dibuixar els marcs que conté, i una caixa niada que continua perd la icona, i també el títol, llevat que el seu estil el repeteixi (repeatTitle).
#:::paper
Un llibre pot canviar de paper en una sèrie de pàgines: un quadern de làmines en estucat brillant dins d'un llibre imprès en òfset de color os, un encart en cartolina, uns fulls de paper de color. Aquest contingut s'embolcalla en un contenidor :::paper:
:::paper{type=coatedGloss grammage=130}
## Làmines
::resource{id="plate-1"}
::resource{id="plate-2"}
:::Un paper ocupa fulls sencers, així que el contingut entre la línia d'obertura i la de tancament comença en una pàgina nova, i el que segueix el ::: de tancament també. Si la sèrie acaba el document, no deixa cap pàgina en blanc al darrere. Les figures i les taules citades dins de la sèrie es col·loquen abans que s'acabi. Cada pàgina maquetada amb contingut del contenidor porta el paper a la maquetació (VDTPage.paper, amb els atributs tal com s'escriuen a la línia d'obertura); les pàgines de fora no porten res. El visor Folio ho llegeix i dibuixa aquests fulls amb el color, la superfície, el gruix i la rigidesa del paper. Les sortides de canvas, PDF i HTML ho ignoren: les pàgines es componen i s'imprimeixen com qualsevol altra.
Els atributs són els de la configuració folio.paper, i tots són opcionals. El que la línia d'obertura no indica segueix el paper del document i, si no n'hi ha, els valors per defecte del tipus de paper:
| Atribut | Valor |
|---|---|
type | El paper: uncoated, bookWove, coatedMatte, coatedSilk, coatedGloss, bible, newsprint, cardStock, board. Fixa els valors per defecte dels atributs següents. |
grammage | Gramatge en g/m², un nombre més gran que 0. Un paper més pesant és més gruixut, més rígid i més opac. |
bulk | Mà en cm³/g, un nombre més gran que 0 (gruix en µm = gramatge × mà). |
finish | L'acabat de la superfície: auto, uncoated, matte, silk, gloss. |
texture | El relleu de la superfície: auto, smooth, vellum, wove, laid, linen, felt. |
textureStrength | Fins a quin punt es nota la textura, de 0 a 2. |
shade | El color del paper: #rgb, #rrggbb o l'id d'una entrada de colorPalette. |
showThrough | true o false: si la pàgina del revers es transparenta una mica. Un showThrough sense valor equival a true. |
Un :::paper dins d'un altre només canvia els atributs que escriu, i també comença i acaba amb un salt de pàgina. Dins d'un :::callout, les línies d'obertura i de tancament s'ignoren. Un valor que el motor no sap llegir es descarta, i el Sandbox el mostra com a avís Atribut de paper no vàlid (paperAttributeInvalid als contentWarnings del document).
#:::pagebreak
La directiva sola no força cap paritat: només afecta el bloc següent. Fes-la servir per acabar un pròleg, posar una dedicatòria en una pàgina pròpia o marcar el final d'una secció. Si vols els dos efectes (salt de pàgina i reinici de la numeració), escriu :::pagebreak seguit de :::numbering: el canvi de numeració s'aplica a la pàgina nova que acaba de crear :::pagebreak.
Un salt de pàgina en una pàgina encara buida no fa res, així que mai no afegeix una pàgina en blanc. Tampoc no substitueix el breakBefore d'un encapçalament que vingui just darrere (el nivell 1 el té per defecte): l'encapçalament aplica igualment la seva paritat, cosa que pot afegir una pàgina en blanc després de la que va obrir la directiva. Perquè un encapçalament comenci just allà, desactiva'n el salt (vegeu Configuració → Estils d'encapçalament). Després d'un encapçalament d'obertura que omple la pàgina, el salt és opcional: l'obertura ja ocupa la resta de la pàgina, tant en disposicions d'una columna com de diverses, i un :::pagebreak just a continuació no fa cap mal. Només cal després d'una obertura amb un disseny que acaba abans del peu de la pàgina, quan el text ha de començar igualment a la pàgina següent (vegeu Configuració → Alçada reservada).
El capítol anterior acaba aquí.
:::pagebreak{parity="odd"}
# Un capítol nouL'indicador center (:::pagebreak{center}, que es desactiva amb center=false) centra el text de la pàgina que obre el salt entre el capdamunt i el peu de la caixa de text, a l'ample de la pàgina en text vertical: el ページの左右中央 d'una portadella de part o d'una dedicatòria japonesa. Els flotants, les notes i les capçaleres es queden on són, i una pàgina ja plena no es toca. L'indicador no acaba la pàgina: tanca-la amb un altre :::pagebreak.
:::pagebreak{center}
# 上 先生と私
:::pagebreakAtribut parity
L'atribut parity accepta els mateixos cinc valors que headings.levels[*].breakBefore.parity:
'any': el valor per defecte, sense restricció de paritat; el salt simplement obre una pàgina nova.'odd'/'even': la pàgina nova s'obre al costat demanat de la doble pàgina; només s'insereix una pàgina en blanc quan la pàgina que tocaria cau al costat equivocat.'always-odd'/'always-even': garanteixen com a mínim una pàgina en blanc de separació entre el contingut anterior i la pàgina nova, i després forcen la paritat. La pàgina de separació pertany al capítol anterior; qualsevol altra pàgina en blanc afegida per paritat pertany al que ve després.
Pertinença de les pàgines en blanc
Els dos tipus de pàgines en blanc que :::pagebreak (i breakBefore) poden introduir es distingeixen al model VDTPage:
blankForParity: true: inserida per complir una restricció de paritat. Per al marcador{chapterTitle}, aquesta pàgina porta el títol del capítol que comença, perquè la pàgina en blanc només existeix per portar aquest capítol a la paritat correcta.blankForForce: true: la pàgina de separació obligatòria que afegeix un mode'always-*'. Pertany al capítol anterior: és una pausa deliberada al final del capítol, no una pàgina de paritat per al capítol següent.
Aquestes dues regles també determinen les capçaleres i la paleta d'una secció amb estil que rep una pàgina en blanc; vegeu Configuració › Estils d'encapçalament.
Excepció a l'inici del document
Quan :::pagebreak és el primer element del document (o el provoca un encapçalament amb breakBefore), la restricció de paritat no s'aplica mentre la primera pàgina continuï buida. El bloc següent va a la pàgina 1 tal qual, sigui quina sigui la paritat demanada: no s'insereix cap pàgina en blanc inicial innecessària.
#:::numbering
:::numbering és la manera de reiniciar el comptador de pàgines a mig document. Exemple canònic de llibre:
---
title: "Un llibre amb pàgines preliminars"
---
# Prefaci
…
:::pagebreak{parity="odd"}
:::numbering{format="decimal" startAt=1}
# Capítol 1Les pàgines del prefaci es numeren i, ii, iii, …; el primer capítol s'obre en una pàgina de la dreta numerada 1.
Els canvis només de format (sense startAt) mantenen el comptador: és útil, per exemple, per passar de lower-alpha a upper-alpha sense reiniciar.
format accepta qualsevol grafia d'un format de numeració: roman-lower i i funcionen igual que lower-roman, arabic igual que decimal, i 一 i あ igual que japanese-informal i hiragana (consulta Configuració › Grafies dels formats de numeració). Un valor que no és cap d'aquestes grafies deixa el format com estava, i el Sandbox en dona un avís.
lines reinicia el compte de la numeració de línies, no el comptador de pàgines: la línia següent que es compta porta el número donat, digui el que digui lineNumbers.restart. Un valor que no és un nombre enter igual o més gran que 0 s'ignora.
## Acte II
:::numbering{lines=1}#:::space
:::space deixa espai vertical entre dos blocs: per separar una línia de tancament del text que la precedeix, baixar una mica un epígraf o una signatura, o obrir un blanc de separació entre dos trams de text. Les línies en blanc de més al Markdown no ho fan: com en qualsevol Markdown, una sèrie de línies en blanc és un sol separador de paràgrafs, i així un document no canvia de maquetació quan un editor o un formatador afegeix o retalla espais.
L'últim paràgraf de l'escena.
:::space
Comença una escena nova, una línia més avall.
:::space{lines=2}
I aquí, dues línies més avall encara.lines: quant d'espai, en línies de text (la retícula de base). Per defecte,1. Els nombres enters mantenen cada línia de text a la retícula, de manera que les columnes continuen alineades a tota la pàgina; una fracció (lines=0.5) es respecta exactament, a costa d'aquesta alineació fins al bloc següent que s'ajusti a la retícula. Un valor que no sigui un nombre més gran que 0 i com a màxim 20 se substitueix per una línia, i el Sandbox en dona un avís (Mida d'espai no vàlida).- Se suma. L'espai s'afegeix al marge que ja separa els dos blocs (el marge superior d'un encapçalament, l'inferior d'una llista) en lloc de fondre-s'hi. Dues línies
:::spaceseguides sumen dues línies. - Desapareix als salts, com el
\vspacede LaTeX: al principi d'una columna o pàgina es descarta, perquè cap pàgina no comenci amb un buit; i si no cap al peu d'una columna, simplement l'acaba, sense arrossegar la resta a la següent. - El paràgraf que el segueix va sense sagnat. Amb
bodyText.indentAfterHeadingdesactivat, un paràgraf just després de:::spaceperd el sagnat de primera línia, igual que després d'un encapçalament: és la convenció habitual quan el text continua després d'una línia en blanc. - Dins d'un requadre (o d'un grup
:::columns) separa els fills del requadre de la mateixa manera, mesurat en les línies de text del mateix requadre. Abans del primer bloc del requadre es descarta, com al principi d'una columna (el farciment ja separa el contingut del marc), excepte en dos casos en què sí que deixa aquest espai: just a sota del títol del requadre i en un requadre que no conté res més (un requadre de resposta, un espai per escriure, mesurat en línies). Sempre desapareix al principi d'un grup:::columns, al capdamunt de cadascuna de les seves columnes i al principi de la part d'un requadre partit que continua a la columna o pàgina següent. Dins d'un contenidor:::paragraphsfunciona igual que entre paràgrafs de cos. - Mantenir amb el següent el té en compte: un encapçalament seguit de
:::spacepassa a la columna següent quan l'espai i les primeres línies del seu text no hi caben a sota.
El requadre de resposta d'una fitxa és un requadre que només conté espai: la pregunta al títol i quatre línies lliures a sota.
:::callout{type="respuesta" title="1. Anomena les tres parts del fanal."}
:::space{lines=4}
:::Per a un salt fix en lloc d'espai, fes servir :::columnbreak o :::pagebreak.
#:::verse
Un poema. :::verse el compon d'una de dues maneres: línia a línia, com s'imprimeixen la majoria dels poemes, o a la manera àrab clàssica d'una qaṣīda, cada bayt en dos hemistiquis l'un al costat de l'altre. Un poema amb línies que porten separador d'hemistiquis (||, o un \\ entre espais) es compon a la manera àrab, i qualsevol altre, línia a línia; layout=lines o layout=bayt a la línia d'obertura en tria una.
Línia a línia
Escriu el poema com s'imprimeix: un vers per línia de Markdown, una línia en blanc entre estrofes i espais davant d'un vers per sagnar-lo.
:::verse
Ja els passerells s'arreceren
a la vora del camí;
el sol de migdia empeny
la terra cap al ponent.
Tot calla dins la clariana,
tot dorm sota l'om antic.
:::- Versos. Cada línia no buida és un vers, llegit com a Markdown en línia per si sol: cursives, versaletes, notes i referències funcionen. Una sèrie de línies en blanc és un sol canvi d'estrofa.
- Sagnats. Cada espai inicial mesura
indentStep, 0,5 em per defecte, de manera que dos espais sagnen el vers un em; un tabulador en compta quatre i un espai ideogràfic (U+3000), dos. - Versos partits. Un vers una mica més ample que la mesura primer estreny els espais entre paraules, fins a
bodyText.minWordSpacingde la seva amplada natural (el límit fins on s'estreny el text justificat), i cap en una línia;tighten=falsea la línia d'obertura, obodyText.verse.tighten: false, el parteix directament. Un vers que continua sense cabre es parteix en un espai entre paraules. Ambturnover=hang(per defecte) la resta penja a la línia següent,hangcap a dins des de l'inici del mateix vers: lahangingIndentde l'estil de paràgraf del poema, o 2 em (bodyText.verse.hang). Ambturnover=rightes compon arran del final de la mesura, després d'un claudàtor d'obertura (turnoverMark,[per defecte), el costum de les edicions castellanes i angleses. El vers no es parteix amb guionet si el seu estil de paràgraf no fixa explícitamenthyphenation: true. Un vers i la seva resta no se separen mai en un salt de columna o de pàgina. - Estrofes. L'espai entre dues estrofes és una línia de l'interlineat del poema;
stanzaSpace=0.5el deixa en mitja línia, i una longitud (stanzaSpace=6pt) el fixa exacte. A la retícula de base surt en línies senceres. Les columnes i les pàgines es tallen primer entre estrofes; dins d'una estrofa, segons les regles de vídues i òrfenes, que llavors compten les línies de l'estrofa.keepStanzas=Nmanté sencera tota estrofa de N línies o menys: un haiku portakeepStanzas=3i una tankakeepStanzas=5. - Posició. El poema es centra a la caixa sobre el seu vers més llarg, amb tots els versos alineats a l'inici del poema (
align=center, l'habitual per a un poema citat en prosa);align=startl'alinea amb l'inici de la mesura, que és el valor per defecte en text vertical. El paràgraf que presenta el poema conserva la seva última línia amb els primers versos. - Versos esglaonats. Un vers escrit
+ …comença on va acabar el de dalt, un espai més enllà, com el vers compartit entre dos personatges al teatre en vers. Escriu\+per a un vers que comença amb un signe més. - Cesures. Amb
keepSpacesa la línia d'obertura, una sèrie de dos o més espais dins d'un vers conserva la seva amplada; sense, els espais es redueixen a un com en qualsevol paràgraf. - Tipus i direcció.
styleindica un estil de paràgraf, que dona la família, el cos, l'interlineat, laindenti l'espai damunt i davall del poema.dirilangen fixen la direcció i l'idioma: un poema llatí en un llibre àrab (dir=ltr) es sagna des del seu propi costat d'inici. En text vertical cada vers és una columna, sagnada des del capdamunt.
| Atribut | Per defecte | Descripció |
|---|---|---|
layout | auto | lines, bayt o auto: a la manera àrab quan una línia porta separador. |
indentStep | 0.5em | Amplada d'un espai inicial. |
turnover | hang | hang o right. |
hang | la hangingIndent de l'estil, o 2em | Sagnat de la resta penjada des de l'inici del seu vers. |
turnoverMark | [ | El signe davant d'una resta composta a la dreta. |
stanzaSpace | 1 | Espai entre estrofes: un nombre sol compta línies de l'interlineat del poema, una longitud és aquesta longitud. |
keepStanzas | 0 | No partir estrofes d'aquestes línies o menys; 0 ho desactiva. |
tighten | true | Estrènyer els espais entre paraules d'un vers una mica massa ample, fins a bodyText.minWordSpacing, abans de partir-lo. |
keepSpaces | desactivat | Conservar les sèries de dos o més espais dins d'un vers. |
align | center (start en text vertical) | Centrar el poema sobre el seu vers més llarg o alinear-lo a l'inici. |
style, dir, lang | — | Estil de paràgraf, direcció i idioma del poema. |
numbered | true | false deixa el poema fora de la numeració de línies: els seus versos no es compten. |
lineStart | — | El número de línia del primer vers del poema. El compte torna a començar aquí, digui el que digui lineNumbers.restart. |
interval | lineNumbers.interval | L'interval propi del poema: imprimir el número de cada enèsim vers. |
bodyText.verse fixa els valors per defecte de tots els poemes (vegeu Configuració › Vers). El text pla conserva el poema tal com es va escriure, un salt de línia entre versos i una línia en blanc entre estrofes, de manera que un passatge copiat i una cerca el llegeixen vers a vers; l'EPUB adaptable compon cada estrofa com un element amb versos que fan penjar la resta, i el PDF etiquetat marca cada estrofa com un paràgraf.
Numeració de línies. Amb lineNumbers activat, els versos d'un poema es compten (vegeu Configuració › Numeració de línies). Cada vers compta una vegada: la seva resta no porta número, i l'espai entre estrofes no es compta. Per defecte, cada cinc versos s'imprimeix el número al marge exterior i el compte torna a començar a cada poema. Un poema a la manera àrab clàssica compta una línia per bayt. La línia d'obertura ajusta un poema: lineStart=N dona un número al seu primer vers, interval=N li dona un interval propi i numbered=false el deixa fora.
:::verse{lineStart=37}
…
:::Amb l'interval per defecte, 5, aquest poema imprimeix 40, 45, etc. al costat dels seus versos.
Manera àrab clàssica
Un poema a la manera àrab clàssica (una qaṣīda, una qiṭʿa): cada vers, el bayt, en una línia i en dues meitats, el ṣadr al costat de l'inici (la dreta en àrab) i l'ʿajuz al costat del final, amb un buit entre totes dues. Escriu un bayt per línia, amb els hemistiquis separats per || (també val \\ amb un espai a cada banda, com als textos de Wikisource). Una línia sense separador és un hemistiqui solt, centrat al poema.
فأنشد يقول:
:::verse
يَا حُرْقَةَ الدَّهْرِ كُفِّي || إِنْ لَمْ تَكُفِّي فَعِفِّي
فَلَا بِحَظِّيَ أُعْطِي || وَلَا بِصَنْعَةِ كَفِّي
:::- Una sola amplada. Tots els hemistiquis del poema es componen amb la mateixa amplada, de manera que cada ṣadr comença a la mateixa vertical i cada ʿajuz acaba en una altra, i les lletres de la rima queden alineades al llarg del poema. L'amplada és la de l'hemistiqui més ample, com a màxim la meitat de la mesura menys el buit;
widthla fixa (width=55mm). Cada hemistiqui s'hi porta primer amb caixides (el vers s'allarga més que la prosa: el doble debodyText.kashidaMaxLength) i després amb els seus espais; un hemistiqui d'una sola paraula que no l'omple deixa la resta al buit. - El buit fa 2 em per defecte;
gapel fixa (gap=3em; un número sense unitat va en em).ornamentimprimeix una marca al centre (ornament="٭"), que no forma part del text. - Massa ample. Un hemistiqui més ample que l'amplada comuna estreny primer els espais fins a
bodyText.minWordSpacing. Si tot i així no hi cap, el seu bayt es compon esglaonat: el ṣadr alineat amb el costat de l'inici en una línia pròpia i l'ʿajuz alineat amb el costat del final a la següent. - Col·locació. El poema va centrat a la columna;
align=startl'alinea amb el costat de l'inici. Un bayt no es parteix mai entre columnes o pàgines, i el poema segueix les regles d'òrfenes i vídues dels paràgrafs (un poema de tres bayts o menys va sencer). El paràgraf anterior, que l'introdueix («فأنشد يقول:»), manté la seva última línia al costat dels primers bayts. - Tipus. El poema pren la font, el cos i l'interlineat del text;
styleli assigna un estil de paràgraf (style="vers"), que és com un poema vocalitzat obté l'interlineat addicional que demanen les seves harakat.dir=ltrodir=rtlen fixa la direcció com en qualsevol bloc; un poema en alfabet llatí en un llibre d'esquerra a dreta porta el ṣadr a l'esquerra.
El text pla del poema separa hemistiquis i bayts (un tabulador i un salt de línia), de manera que una cerca o un passatge copiat el llegeixen tal com es va escriure; les caixides i l'ornament en queden fora.
#:::toc
:::toc imprimeix l'índex general allà on és. Es converteix en blocs normals (un per encapçalament dels nivells que indica toc.levels, el nivell 1 per defecte, i un per :::part), de manera que l'índex passa per columnes i pàgines com qualsevol altre text, i un clic sobre una entrada porta a la línia de la directiva. Cada entrada mostra el número de l'encapçalament (el resultat del seu numberingTemplate o, si no n'hi ha, l'ordinal de capítol), el títol, una línia de punts i l'etiqueta de la pàgina on comença i, si toc.subtitle està activat, una segona línia amb un atribut de l'encapçalament, com els autors del capítol ({author="…"}). Cada part rep una fila pròpia, dissenyada per toc.parts.design i acolorida amb la palette de la part. Els encapçalaments amb un estil que declara numbered: false apareixen sense número; {toc="false"} en un encapçalament el deixa fora (normalment, el mateix encapçalament de l'índex).
En una pàgina composta, un marc amb takes: "toc", o un :::frame que conté la directiva, compon l'índex amb les files de part, els punts guia i keep (vegeu Pàgines compostes).
# Índex {style="preliminar" toc="false"}
:::tocDos atributs canvien el que imprimeix un índex concret, digui el que digui la configuració. levels indica els nivells d'encapçalament que recull: un interval (levels="1-2"), un sol nivell (levels="2") o una llista (levels="1,3"); un nivell al qual toc.levels no dona estil pren el del nivell més proper per damunt. keep manté cada bloc de l'índex en una sola columna i pàgina, com fa toc.groups.keepTogether: keep="part" manté una fila de part amb els seus capítols, keep="1" (fins a "6") un encapçalament d'aquest nivell amb les entrades que en depenen, i keep="none" desactiva l'agrupament configurat. Un bloc que no hi cap passa sencer a la columna o la pàgina següent; un de més alt que una columna es parteix, i la columna on continua s'obre de nou amb la seva fila de capçalera, seguida d'una marca de continuació com (cont.).
# Índex {style="preliminar" toc="false"}
:::toc{keep="part" levels="1-2"}Els números de pàgina són els que el document imprimeix realment. Un document maquetat tot sol es torna a maquetar amb les etiquetes de la passada anterior fins que deixen de canviar; amb la numeració reiniciada després dels preliminars (la recepta de :::numbering de més amunt), n'hi ha prou amb una passada addicional. Un capítol maquetat per separat (les previsualitzacions del Sandbox) rep en canvi l'esquema del llibre sencer des del seu amfitrió. Vegeu Índex general a la referència de configuració.
#:::index
:::index imprimeix l'índex analític allà on és: els termes marcats amb :index[…] o :index{term="…"} a tot el llibre, amb les seves pàgines, que segueixen el text quan es mou. Es descriu juntament amb les marques a Índex analític. Una columna no acaba mai després de la primera entrada d'un grup ni abans de l'última: en queden dues i en passen dues, o el grup passa sencer (index.groups.splitMinEntries).
# Índex analític {style="indice"}
:::index#Salts de línia
Les línies d'un paràgraf s'uneixen amb un espai. Per acabar una línia dins d'un paràgraf sense començar-ne un altre (una adreça, la salutació d'una carta, una dedicatòria), acaba la línia del text font amb una barra inversa, el salt forçat de CommonMark, o escriu \\ seguit d'un espai:
Al guardià del far,\
al final del moll nord.
Anna Puig \\ Carrer Major 4 \\ 08001 Barcelona- La línia anterior a un salt es compon amb l'amplada natural, com l'última línia d'un paràgraf, sense estirar-se fins a la mesura. El text que segueix obre una línia nova del mateix paràgraf, sense sagnat de primera línia ni espai a sobre; amb sagnat francès penja com qualsevol línia després de la primera.
- L'admeten els paràgrafs, les cites (
> Primera línia\sobre> segona línia), les notes a peu de pàgina i els elements de llista. Un element de llista ocupa una sola línia del text, així que es parteix amb\\. - Una barra inversa al final del paràgraf s'imprimeix, com a CommonMark, i dos salts seguits són un de sol: per a una línia buida, comença un paràgraf nou o afegeix un
:::space. - Un
\\enganxat al caràcter següent no és un salt:\\*imprimeix una barra inversa i un asterisc escapat,C:\\Temples dues barres. Al codi en línia i en una fórmula les barres són del codi i de la fórmula. - Dos espais al final d'una línia, l'altre salt forçat de CommonMark, no ho són: no es veuen en un editor i molts editors els hi deixen oblidats, així que partirien línies que ningú no volia partir.
- El text copiat del visor HTML porta un salt de línia en aquest punt, l'EPUB adaptable un
<br/>, el text del PDF un final de línia i una exportació a Word un salt de línia manual (Maj+Retorn), que la importació de Word torna a llegir com a salt. - Un poema conserva els versos, els sagnats i les estrofes en un bloc
:::verse, sense una barra a cada línia.
Fins a postext 1.22 la barra inversa s'imprimia i les línies s'unien amb un espai. Un llibre desat aleshores amb un text que acaba alguna línia amb una barra inversa, o que posa \\ davant d'un espai, conserva aquesta lectura (bodyText.hardLineBreaks: false, vegeu Configuració › Paquets escrits per postext 1.4 o anterior).
#Salts de línia als títols
Escriu \\ dins d'un encapçalament (o dins de l'atribut title d'una part) per forçar un salt de línia allà on el títol es mostra com a tal: l'encapçalament en columna continua fluint i mostra un espai, mentre que el {titleText} d'un disseny d'obertura salta de línia en aquest punt (en qualsevol mode d'overflow de l'element de text). Les capçaleres de pàgina, {chapterTitle}, {partTitle} i l'índex del PDF sempre componen el títol en una sola línia. En xinès o en japonès el salt es llegeix com un espai ideogràfic entre dos caràcters d'aquesta escriptura (un títol en dístic); on un d'ells s'ajunta amb una xifra o amb text llatí (关于举办 \\ 2026年…), la pàgina posa l'espai entre xinès i llatí, i els marcadors i el títol del PDF uneixen les dues meitats sense res, com s'escriu el xinès en text pla.
# Concepte de salut i malaltia. \\ Salut comunitària {author="I. Zango Martín"}#Còmics
Les pàgines de còmic, les tires i les dobles pàgines s'escriuen en dos blocs delimitats amb un contingut que el motor llegeix de la mateixa manera, línia per línia: :::page i :::strip. A dins, les línies ::panel comencen les vinyetes i les línies de guió les retolen. La guia, amb les regles de compaginació, la retolació i les sortides, és a Còmics; els paràmetres són a Configuració › Còmics.
#:::page
:::page{split="30 [30 | 20 | *] / *" gutter=4mm}
::panel{art=lh-arrive}
caption: Cada estiu, la Maya passava una setmana al far.
maya: Avi! Ja soc aquí!
::panel{art=lh-radio focus="40% 50%"}
tomas: Just a temps.
::panel{art=lh-maya}
maya{thought}: Aquesta vàlvula sembla fluixa…
::panel{art=lh-beam bleed}
sfx{rotate=-8}: CRAC
:::Un bloc :::page és una pàgina de còmic: obre una pàgina nova, l'ocupa sencera, i el text que ve després del seu ::: de tancament comença a la pàgina següent. Els seus atributs són split (com es talla la pàgina en cel·les: mides en percentatge separades per / per a les fileres i per | per a les vinyetes de costat, una llista entre claudàtors per tornar a tallar una cel·la, * per a la resta, a~b per a una línia inclinada), gutter (una longitud, o dues: entre fileres i entre vinyetes; un nombre sol és en mil·límetres), style (un estil de vinyeta amb nom), bleed, direction (ltr o rtl, també escrit dir) i spread (vegeu Dobles pàgines). Sense split les vinyetes s'apilen en fileres iguals. Dins del bloc no es llegeixen blocs Markdown, contenidors ni directives; els <!-- comentaris --> sí.
#Vinyetes
Una línia ::panel{…} comença una vinyeta, que omple la cel·la següent en ordre de lectura i arriba fins a la línia ::panel següent o fins a la línia de tancament:
| Atribut | Efecte |
|---|---|
art=<id> | El dibuix: un recurs bitmap o SVG. Sense ell la vinyeta queda buida. |
fit=cover, fit=contain | Retalla el dibuix per omplir la cel·la (mai dins de la seva zona segura), o el mostra sencer. |
focus="x% y%" | El punt que s'ha de mantenir centrat allà on la zona segura deixa marge. |
style=…, border=none, border=0.5mm, bg=#hex | Un estil de vinyeta amb nom, la vora, el fons (un color, un id de la paleta o none). |
bleed, bleed="top start", bleed=false | Estén els costats que toquen el marc fins al tall i la sang. |
pad="…" | Fa la vinyeta més petita que la seva cel·la: d'una a quatre longituds o percentatges (dalt, final, baix, inici). |
inset="x y w h" | Posa la vinyeta sobre l'anterior, en aquesta caixa en percentatges d'aquella, en lloc de donar-li una cel·la. |
text, valign=middle, shrink, box=<id> | Converteix la vinyeta en una vinyeta de text: el seu cos és Markdown compost al marc de la vinyeta (valign el situa), no un guió; box vesteix la vinyeta amb un estil de requadre. Vegeu Còmics › Vinyetes de text. |
pop=<id> | Un retall transparent dibuixat per sobre de la vora amb el retall del dibuix (una vora trencada). |
mirror, mirror=false | Reflecteix el dibuix, o el conserva tal com és en una pàgina en mirall. |
alt="…", id=… | L'alternativa textual (si no, l'altText del recurs) i un id d'àncora. |
#Línies de guió
Cada línia d'una vinyeta és una bafarada, una cartel·la o una onomatopeia, i s'escriu clau{atributs}: text:
maya: Avi! Ja soc aquí!
tomas{whisper}: Xxt. Escolta.
caption{at=bottom-end}: A tres carrers d'aquí.
sfx{at="62% 40%" rotate=-8 size=1.4}: CRAC
ben{tail=start}: (des de fora de la vinyeta) Soc aquí!
sfx{vertical size=2.6 font="Dela Gothic One"}: ドン
maya: Aquesta línia continua
a la línia següent,\
i es parteix aquí.- La clau és un id de personatge (lletres, xifres,
_,.,-), el mateix en totes les traduccions;caption,sfxinotesón reservades. Els dos punts poden ser els:d'amplada completa. - Una paraula sola entre claus és un estil de bafarada (
thought,whisper,shout,radio,innero un decomics.balloonStyles);style=diu el mateix. atfixa la bafarada: un punt en percentatges del dibuix de la vinyeta (at="62% 40%"), o una cantonada o una vora (top-start,top-end,bottom-start,bottom-end,top,bottom).toapunta la cua a un punt del dibuix;tail=nonela treu itail=top|bottom|start|end|left|rightl'apunta fora de la vinyeta.joinijoin=falseuneixen la bafarada a l'anterior del mateix personatge o la mantenen separada;breakli permet travessar la vora, i aquest encreuament no genera cap avís de desbordament.rotate(graus),skew(una inclinació en graus, per a un text sobre un objecte vist en perspectiva),size(una escala, per a les onomatopeies),colorifonten modifiquen la retolació.verticalihorizontal(omode=vertical,mode=horizontal) fixen la direcció d'escriptura de la línia per damunt de la del llibre: unドンsense traduir, compost en columna en una edició horitzontal; un rètol escrit de través, en filera en una de vertical. Una columna en un llibre d'una altra llengua segueix les regles del seu propi text (amb kana, les del japonès). En un llibre vertical, una línia sense caràcters xinesos ni japonesos es compon en filera igualment.- Una línia sagnada amb dos espais o un tabulador continua la bafarada de sobre; una barra inversa al final d'una línia hi parteix el text. Les línies en blanc s'ignoren.
- El text és Markdown en línia: èmfasi (retolat en negreta cursiva),
:tcy,:ruby(la lectura sobre la base, tret que la base vagi de dreta a esquerra),:ltri:rtl(un fragment que conserva el seu propi sentit). Les notes a peu de pàgina i les marques:refno es llegeixen.
#:::strip
:::strip{split="* | * | *" aspect=3 span=page placement=top}
::panel{art=pip-1}
pip: Bon dia, Otto!
::panel{art=pip-2}
::panel{art=pip-3}
otto: Tu creus?
:::Un :::strip té el cos d'una pàgina però va dins del text com una sola caixa que no es parteix, tallada en vinyetes: span (column, el valor per defecte, o page), placement (here, el valor per defecte, allà on està escrita; o top, bottom, auto, flotant com una figura) i la seva mida, sigui height (una longitud; un nombre sol és en mil·límetres) o aspect (l'amplada dividida per l'alçada: 3, 4/1, 4:1; per defecte, les proporcions que fan quadrades les seves vinyetes). Una tira a amplada de pàgina composta here en una pàgina de diverses columnes talla les columnes allà on és, com fa una caixa d'amplada de pàgina. width la fa més estreta que la mesura que ocupa (un 60% d'aquesta mesura, o una longitud) i align la situa a l'inici (start), al centre (center, el valor per defecte) o al final (end) d'aquesta mesura, segons la direcció del text. caption="…" hi posa un peu a sota amb l'estil de peus; amb type=figure (un tipus de recurs), el peu pren l'etiqueta i el número del tipus i la tira compta en la seqüència d'aquest tipus, i, amb id=…, un :ref hi pot fer referència. Sense split les vinyetes van l'una al costat de l'altra. Les tires només es llegeixen al nivell superior d'un capítol.
#Dobles pàgines
:::page{spread} estén una pàgina sobre dues pàgines enfrontades: la divisió cobreix les dues caixes de text unides al llom, sense els seus marges interiors, i una vinyeta pot travessar el llom. La doble pàgina s'obre en una pàgina parella, després d'una pàgina en blanc si cal. Vegeu Còmics › Dobles pàgines.
#Pàgines compostes
Una pàgina composta es maqueta a partir d'una plantilla de pàgina de la configuració (pageTemplates), i el contingut es reparteix entre els marcs de la plantilla segons el nom de cada marc. La guia, amb els avisos, és a Pàgines compostes.
::::page{template="…"}…::::és el bloc de pàgina: quatre signes de dos punts o més, i es tanca amb una línia que només conté el mateix nombre de signes. Les línies de tres signes de dos punts que hi ha a dins (:::frame,:::callout,:::figure…) funcionen com a tot arreu, i un:::sol mai no tanca la pàgina. Un:::pagede tres signes de dos punts continua sent una pàgina de còmic.:::frame{slot="…" label="…"}…:::conté el contingut del marc amb aquest nom: qualsevol Markdown.slot="…"en un encapçalament (## Retos {slot="retos-titulo"}), a::resource{id="…" slot="…"}, en la línia d'obertura d'un bloc de codi o en un contenidor:::envia només aquell bloc. El contingut sense ranura va al marc de flux de la plantilla.:::figure{resource="…" slot="…"}…:::col·loca un recurs amb les seves línies::label[TEXT]{at="…" style="…"}, onatés una àncora de la imatge o un punt"x% y%". Una figura també funciona al text corregut. Els seusalt,captioninote, com a atributs de la línia d'obertura o com a línies::alt[…],::caption[…]i::note[…], substitueixen els textos del recurs en aquell capítol (vegeu Pàgines compostes › Les paraules pròpies d'una figura).leaderen un::labeldibuixa una línia des del rètol fins al punt de la seva àncora, ileader="none"la treu.:::label{at="…" style="…"}…:::, dins d'una figura, escriu un rètol línia per línia, com demana la llegenda d'un mapa;:icon[alt]{glyph="…"},{resource="…"}o{line="dashed"}posa un símbol en un rètol, un peu, una nota o una cel·la de taula (vegeu Pàgines compostes › Línies de referència, llegendes i símbols). Des de postext 1.48.- En una pàgina amb una plantilla que repeteix una targeta en una graella, cada
:::frame{slot="<card>"}és una targeta, i un bloc de dins que indica un altre marc de la targeta va a aquell marc de la mateixa targeta (vegeu Pàgines compostes › Ranures repetides). Des de postext 1.48. :::module{template="…" name="…"}…:::conté el contingut d'un mòdul de la pàgina, un bloc que dibuixa una plantilla de mòdul i que s'apila al grup de mòduls de la pàgina; les ranures de dins són les del mòdul (vegeu Pàgines compostes › Mòduls en una pàgina). Des de postext 1.48.