Configuració: notes i referències

#Notes a peu de pàgina

La propietat footnotes fixa on van les notes citades amb [^id], com es numeren i quin aspecte tenen. El marcatge es descriu a Format del document.

interface FootnotesConfig {
  placement?: 'column' | 'chapterEnd' | 'spread'; // Peu de la columna que cita, després del capítol, o al costat del text d'un plec.
  numbering?: 'chapter' | 'document' | 'page' | 'column' | 'spread'; // Reiniciar a cada capítol, continuar, o reiniciar a cada pàgina / columna / plec.
  numberFormat?: string;      // decimal, lower-roman, circled-decimal (①)…
  symbols?: string[];         // Els símbols de crida de numberFormat: 'symbols'.
  markerPosition?: 'auto' | 'superscript' | 'inline' | 'side' | 'right'; // Volada, sobre la línia de base, al costat de la paraula, o a la dreta d'una línia vertical.
  markerSize?: Dimension;     // Mida de la crida en línia, lateral o a la dreta; em és el text que l'envolta.
  numberGap?: 'en' | 'em';    // Espai després del número de la nota mateixa.
  chapterEndAlign?: 'foot' | 'text';   // chapterEnd: notes al peu de la columna, o sota el text.
  fontSize?: Dimension;       // Cos de la nota; em és el cos del text.
  lineHeight?: Dimension;     // Interlineat de la nota; em és el cos de la nota.
  color?: ColorValue;         // Color de la nota; sense valor, el del cos.
  textAlign?: TextAlign;      // Sense valor, l'alineació del cos.
  hangingIndent?: Dimension;  // Sagnat de les línies següents d'una nota.
  spaceBetween?: Dimension;   // Espai entre dues notes.
  spaceAbove?: Dimension;     // Espai entre el text i el filet; em és el cos del text.
  spaceBelowRule?: Dimension; // Espai entre el filet i la primera nota.
  separator?: {
    enabled?: boolean;        // Dibuixar el filet.
    width?: number;           // Longitud del filet, fracció de l'amplada de columna.
    lineWidth?: Dimension;    // Gruix del filet.
    color?: ColorValue;       // Sense valor, el color de les notes.
  };
}

footnotes: {
  fontSize: { value: 7.5, unit: 'pt' },
  lineHeight: { value: 9.5, unit: 'pt' },
  hangingIndent: { value: 0.8, unit: 'em' },
  separator: { width: 0.25, lineWidth: { value: 0.4, unit: 'pt' } },
}

Llibres japonesos. Un document japonès (locale: 'ja', des de postext 1.16) dona als camps que deixa sense fixar els valors de JLReq §4.2. Un llibre vertical compon les notes després del capítol (placement: 'chapterEnd', 後注), numerades per capítol, amb crides （{n}） a la dreta de la línia (markerPosition: 'right', amb les xifres dretes segons cjk.uprightDigits); un d'horitzontal les compon al peu de la pàgina, numerades a cada pàgina, amb crides volades. Tots dos tracen el filet amb un terç de la mesura (separator.width: 1/3), i les notes després del capítol porten numberGap: 'em' i un sagnat francès de dos quadratins. Un valor explícit mana i es conserva en desar (stripFootnotesDefaults compara amb els valors per defecte del mateix document); els documents xinesos, àrabs i llatins es resolen com abans. footnoteDocumentDefaults(locale, writingMode, placement?) retorna aquests valors. La crida s'escriu davant d'un 。 que tanca la frase (先生[^1]。): es queda amb el caràcter anterior, i 。 mai no obre una línia. Vegeu Composició japonesa › Notes.

Com es componen les notes al peu de columna:

• La nota i la seva crida comparteixen columna. Abans de col·locar una línia, la maquetació suma l'alçada de les notes que aquella línia cita per primer cop (i la del filet, en la primera nota de la columna). Una línia les notes de la qual no caben a sota passa a la columna següent amb la resta del seu paràgraf, segons les regles de vídues i òrfenes. L'àrea de text de la columna s'escurça en l'alçada de les notes, de manera que l'equilibrat de columnes i la banda de tancament d'un capítol només compten el text.
• Diverses notes en una columna s'apilen en l'ordre de cita sota un únic filet. Una nota citada de nou més endavant conserva el seu número i no es torna a compondre.
• Flotants al peu. Una figura que ocupa el peu d'una columna després que les seves notes s'hagin compost queda damunt d'elles; les notes compostes després de la figura queden damunt d'ella.
• Requadres. Una nota citada dins d'un requadre (en línia, flotant o fix) va al peu de la columna on continua el text després del requadre, normalment la mateixa. Un requadre que tanca el document deixa les seves notes al peu de la columna on ha acabat el text.
• Límits. Una nota mai no es parteix: una de més alta que la columna la desborda. Les crides en peus de figura, cel·les de taula i títols no es llegeixen (s'imprimeixen tal qual).
• Sortida. El canvas, l'HTML i el PDF pinten les notes, les crides (un número volat) i el filet. Al PDF cada crida enllaça amb la seva nota, i un PDF etiquetat marca cada nota com a element Note amb un /ID únic llistat a l'/IDTree de l'arbre d'estructura (PDF/UA-1). Les notes són VDTBlock amb footnoteNote, a page.floats; els filets són a page.footnoteAreas.
• Avisos. undefinedFootnote (una crida sense definició: el número s'imprimeix sobre una nota buida) i unusedFootnote (una definició que cap crida no cita: no es compon).

El resolutor i el depurador segueixen el patró de les altres seccions:

import { DEFAULT_FOOTNOTES_CONFIG, resolveFootnotesConfig, stripFootnotesDefaults, footnoteDocumentDefaults } from 'postext';
 
resolveFootnotesConfig(config.footnotes, 'ja', 'vertical-rl'); // els camps sense fixar prenen els valors japonesos verticals

#Numeració de línies

La propietat lineNumbers imprimeix al marge el número de cada cinquena línia (o de cada enèsima), al seu costat, com fan les edicions crítiques, les antologies de poesia, els textos legals i les edicions escolars. Compta els versos dels poemes :::verse, o totes les línies del text. Està desactivada per defecte. Cada número es pinta sobre la línia de base de la seva línia, amb un cos propi, i no mou mai cap línia: la pàgina es compon exactament igual que sense números. Des de postext 1.23.

interface LineNumbersConfig {
  enabled?: boolean;        // Desactivada per defecte.
  count?: 'verse' | 'all';  // Els versos dels poemes, o totes les línies del text.
  interval?: number;        // Imprimir els múltiples de N.
  numberFirst?: boolean;    // Imprimir també la primera línia després de cada reinici.
  restart?: 'document' | 'chapter' | 'section' | 'page' | 'poem'; // On torna a començar el compte.
  startAt?: number;         // El número de la primera línia després d'un reinici.
  position?: 'outer' | 'inner' | 'left' | 'right' | 'start' | 'end' | 'side';
  multiColumn?: 'each' | 'gutter' | 'outer-edges'; // Pàgines de dues columnes o més.
  gap?: Dimension;          // Del text al número; em és el cos del número.
  align?: 'auto' | 'left' | 'right';
  fontFamily?: string;      // La família del cos si no es fixa.
  fontSize?: Dimension;     // em és el cos del text.
  fontWeight?: number;      // El pes del cos si no es fixa.
  italic?: boolean;
  color?: ColorValue;       // El color del cos si no es fixa.
  format?: string;          // decimal, lower-roman, arabic-indic, 一…
}

lineNumbers: {
  enabled: true,
  count: 'verse',
  interval: 5,
  restart: 'document',          // un sol compte per a tot el llibre
  position: 'outer',
  fontSize: { value: 0.75, unit: 'em' },
  italic: true,
}

Què es compta i què no:

• No es compten mai els encapçalaments, els peus, les taules i les imatges, les fórmules en bloc, el text de disseny (obertures, capçaleres), les notes a peu de pàgina i les notes de final de capítol, l'índex de continguts, les entrades de l'índex alfabètic i de la bibliografia, ni les pàgines en blanc.
• Requadres i prosa. El text d'un requadre no es compta, i amb count: 'verse' tampoc la prosa, llevat que l'estil de paràgraf amb què es compon digui lineNumbers: true; un estil amb lineNumbers: false no es compta mai (vegeu Estils de paràgraf).
• Un poema. L'obertura d'un poema admet numbered=false (els seus versos no es compten), lineStart=N (el seu primer vers és l'N, i el compte torna a començar aquí) i interval=N. :::numbering{lines=N} dona el número N a la línia comptada següent, sigui on sigui. Vegeu Format del document › :::verse i :::numbering.

En un llibre compost capítol a capítol, restart: 'document' porta el compte d'un capítol al següent a continuation.lineNumber. continuationAfter compta els versos a partir del text; amb count: 'all' el compte depèn de la composició, així que l'aplicació passa el lastLineNumber del document del capítol anterior, com fa el Sandbox.

Amb position: 'side' els números comparteixen la columna lateral amb els requadres, els peus i les figures laterals. Un número que se superposa a un d'ells es pinta igualment, cap dels dos no es mou, i la composició dona un avís de contingut lineNumberOverlap que assenyala la línia numerada.

Sortida. El canvas, el PDF, el visor HTML i l'EPUB de maquetació fixa pinten els números. En un PDF etiquetat són artefactes de paginació i cadascun porta un /ActualText buit, de manera que el text copiat o extret passa d'una línia a l'altra sense ells. La sortida HTML els amaga a les tecnologies d'assistència (aria-hidden), a la selecció i al text copiat. L'EPUB de maquetació fluida, les línies del qual compon el sistema de lectura, conserva només els números dels versos: un span pt-line-number (també aria-hidden) al marge inicial de l'estrofa, al costat de cada vers que porta número a la versió impresa. Al VDT els números són una ranura de disseny de cada pàgina (page.lineNumbers, amb els blocs de text marcats artifact) i una llista de marques (page.lineNumberMarks: number, label, columnIndex, blockId, lineIndex); el document desa lastLineNumber.

No s'admeten: números de línia en text vertical, una referència creuada que imprimeixi el número d'una línia, notes enllaçades a números de línia, ni números per a les línies de cel·les de taula, peus o llistats de codi.

Al Sandbox aquests ajustos són la secció Numeració de línies del tauler de disseny. El resolutor i el depurador segueixen el patró de les altres seccions; la font, el pes i el color surten del text de cos:

import { DEFAULT_LINE_NUMBERS_CONFIG, resolveLineNumbersConfig, stripLineNumbersDefaults } from 'postext';
 
resolveLineNumbersConfig(config.lineNumbers, resolvedBodyText); // font, pes i color sense fixar segueixen el cos

#Referències creuades

La propietat crossRefs fixa les paraules que una referència creuada imprimeix al voltant d'un número o d'una pàgina, i l'estil que pren un :ref que no n'indica cap. Cada plantilla porta {n} on va el número; una que no el porta rep el número després d'un espai no separable ("§" imprimeix § 3.2). Una plantilla sense definir segueix la llengua del document: capítulo / sección / pág. en castellà, chapter / section / p. en anglès, 第{n}章 / 第{n}节 / 第{n}页 en xinès, i el mateix per al francès, l'alemany, l'italià, el portuguès, el català i el neerlandès.

interface CrossRefsConfig {
  chapter?: string;  // Words around a level-1 heading's number: "chapter {n}".
  section?: string;  // Around any other heading's number: "section {n}".
  page?: string;     // Around a page number: "p. {n}".
  defaultStyle?: 'default' | 'number' | 'title' | 'page'; // A :ref without style=.
}

Les referències prenen el color, el pes i la inclinació de totes les referències (bodyText.referenceColor, referenceBold, referenceItalic).

#Cites

La propietat citations tria l'estil de cita i com es veuen les cites i la bibliografia. El marcatge es descriu a Cites i bibliografia; l'estil l'aplica el paquet postext-citeproc.

interface CitationsConfig {
  style?: string;          // 'apa', 'ieee', 'chicago-notes-bibliography'… or 'custom'
  customStyle?: string;    // a whole CSL style (.csl XML), used with style: 'custom'
  locale?: string;         // CSL locale; the document language when unset
  link?: boolean;          // citations link to their entries
  marker?: 'style' | 'brackets' | 'parentheses' | 'superscript' | 'corner';
  collapseRanges?: boolean;
  notes?: 'footnote' | 'warichu';
  numbering?: 'book' | 'chapter';
  bibliography?: {
    title?: string;        // unset: the document language's word; '' or ' ': none
    scope?: 'book' | 'chapter';
    auto?: boolean;
    fontSize?: Dimension;
    lineHeight?: Dimension;
    hangingIndent?: Dimension;
    entrySpacing?: Dimension;
    labelWidth?: Dimension;
    labelAlign?: 'left' | 'right';
    doi?: 'link' | 'text' | 'hide';
    includeUncited?: boolean;
    groupByLanguage?: boolean;
  };
}

#Índex de continguts

La propietat toc configura el que imprimeix una directiva :::toc (vegeu Format del document). L'índex es munta a partir de l'esquema del document — cada encapçalament amb el seu número i la seva etiqueta de pàgina, cada :::part — de manera que segueix els capítols: canvia el nom d'un, mou-lo a una altra part, canvia'n els autors, i les entrades canvien amb ell. Una entrada és el número de l'encapçalament en una columna pròpia, el títol, una línia de punts i l'etiqueta de pàgina a la vora dreta, i després una línia de subtítol opcional; una part és una fila dissenyada per parts.design.

const config: PostextConfig = {
  toc: {
    levels: [{ level: 1, fontWeight: 700, color: { hex: '#00507b', model: 'hex' }, numberWidth: { value: 7.4, unit: 'mm' } }],
    unnumbered: { color: { hex: '#000000', model: 'hex' } },
    pageNumber: { fontWeight: 400, width: { value: 8, unit: 'mm' } },
    leader: { char: '.', gap: { value: 1, unit: 'mm' } },
    subtitle: { enabled: true, attr: 'author', italic: true, fontSize: { value: 8.5, unit: 'pt' } },
    parts: {
      height: { value: 23, unit: 'pt' },
      marginTop: { value: 11.5, unit: 'pt' },
      design: { elements: [/* una caixa de banda, 'SECCIÓ {number}', '{titleText}', '{pageNumber}' */] },
    },
  },
};

Les etiquetes de pàgina són les que imprimeix el document. buildDocument() torna a compondre un document amb :::toc amb les etiquetes de la passada anterior fins que s'estabilitzen (tres passades addicionals com a màxim); un amfitrió que compon un llibre capítol a capítol subministra en lloc d'això l'esquema del llibre sencer com a PostextContent.outline, muntat amb contentOutline() (encapçalaments i parts a partir del text) i outlineFromDoc() (les mateixes entrades amb les etiquetes de pàgina d'una composició), i torna a compondre el capítol de l'índex cada vegada que canvia l'outlineKey() d'aquest esquema. Cada entrada d'encapçalament porta el number que imprimeix l'índex i, en un encapçalament numerat, el seu counter: el compte acumulat del nivell després de qualsevol startAt, imprimeixi el que imprimeixi la plantilla — el que un amfitrió mostra al costat d'un capítol a les seves pròpies llistes.

#Índex analític

La propietat index configura el que imprimeix una directiva :::index (vegeu Format del document): els termes marcats amb :index[…] i :index{term="…"} al text, ordenats, agrupats per inicial (en xinès, per la inicial del pinyin o per traços, i en japonès per files del gojūon; vegeu groupBy) i cadascun amb les pàgines on cau. Una entrada és el seu terme, un separador i els seus números de pàgina; al darrere van les seves subentrades, amb un pas de sagnat per nivell, i les línies que continuen una entrada pengen turnoverIndent per no alinear-se mai amb una subentrada.

const config: PostextConfig = {
  headingStyles: [
    // L'índex a dues columnes, sota el seu propi encapçalament.
    { id: 'indice', numbered: false, layout: { layoutType: 'double', gutterWidth: { value: 6, unit: 'mm' } } },
  ],
  index: {
    fontSize: { value: 8.5, unit: 'pt' },
    lineHeight: { value: 11, unit: 'pt' },
    rangeFormat: 'chicago',
    groups: { fontFamily: 'Source Sans 3', fontWeight: 700, color: { hex: '#8a1c1c', model: 'hex' } },
  },
};

Els números de pàgina surten de l'esquema del llibre, com els de l'índex de continguts: computeOutline() i contentOutline() enumeren les marques d'un text com a entrades de tipus 'indexMark' (amb indexMark.path, sort, see, seeAlso, main, range i index), i outlineFromDoc() dona a cadascuna la pàgina on va caure, que la composició registra a doc.indexMarks ({ sourceStart, pageIndex } per marca). buildDocument() torna a compondre un document que imprimeix el seu propi índex fins que els números s'estabilitzen; un amfitrió que compon un llibre capítol a capítol passa al capítol que conté :::index l'esquema del llibre sencer com a PostextContent.outline. tocOutline() i indexOutline() separen un esquema en allò que llegeixen l'índex de continguts i l'analític, perquè l'amfitrió associï cada capítol al que imprimeix: el sandbox torna a compondre el capítol de l'índex analític només quan es mou una marca, i el de l'índex de continguts només quan es mou un encapçalament. contentOutline() indica a més si un text imprimeix un índex analític (hasIndex).