Configuración: notas y referencias

#Notas al pie

La propiedad footnotes fija dónde van las notas citadas con [^id], cómo se numeran y qué aspecto tienen. El marcado se describe en Formato del documento.

interface FootnotesConfig {
  placement?: 'column' | 'chapterEnd' | 'spread'; // Pie de la columna que cita, tras el capítulo, o junto al texto de un pliego.
  numbering?: 'chapter' | 'document' | 'page' | 'column' | 'spread'; // Reiniciar en cada capítulo, seguir, o reiniciar en cada página / columna / pliego.
  numberFormat?: string;      // decimal, lower-roman, circled-decimal (①)…
  symbols?: string[];         // Los símbolos de llamada de numberFormat: 'symbols'.
  markerPosition?: 'auto' | 'superscript' | 'inline' | 'side' | 'right'; // Volada, sobre la línea de base, junto a la palabra, o a la derecha de una línea vertical.
  markerSize?: Dimension;     // Tamaño de la llamada en línea, lateral o a la derecha; em es el texto que la rodea.
  numberGap?: 'en' | 'em';    // Espacio tras el número de la propia nota.
  chapterEndAlign?: 'foot' | 'text';   // chapterEnd: notas al pie de la columna, o bajo el texto.
  fontSize?: Dimension;       // Cuerpo de la nota; em es el cuerpo del texto.
  lineHeight?: Dimension;     // Interlineado de la nota; em es el cuerpo de la nota.
  color?: ColorValue;         // Color de la nota; sin valor, el del cuerpo.
  textAlign?: TextAlign;      // Sin valor, la alineación del cuerpo.
  hangingIndent?: Dimension;  // Sangría de las líneas siguientes de una nota.
  spaceBetween?: Dimension;   // Espacio entre dos notas.
  spaceAbove?: Dimension;     // Espacio entre el texto y el filete; em es el cuerpo del texto.
  spaceBelowRule?: Dimension; // Espacio entre el filete y la primera nota.
  separator?: {
    enabled?: boolean;        // Dibujar el filete.
    width?: number;           // Longitud del filete, fracción del ancho de columna.
    lineWidth?: Dimension;    // Grosor del filete.
    color?: ColorValue;       // Sin valor, el color de las notas.
  };
}

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' } },
}

Libros japoneses. Un documento japonés (locale: 'ja', desde postext 1.16) da a los campos que deja sin fijar los valores de JLReq §4.2. Un libro vertical compone sus notas tras el capítulo (placement: 'chapterEnd', 後注), numeradas por capítulo, con llamadas （{n}） a la derecha de la línea (markerPosition: 'right', con las cifras de pie según cjk.uprightDigits); uno horizontal las compone al pie de la página, numeradas en cada página, con llamadas voladas. Los dos trazan el filete con un tercio de la medida (separator.width: 1/3), y las notas tras el capítulo llevan numberGap: 'em' y una sangría francesa de dos cuadratines. Un valor explícito manda y se conserva al guardar (stripFootnotesDefaults compara con los valores por defecto del propio documento); los documentos chinos, árabes y latinos se resuelven como antes. footnoteDocumentDefaults(locale, writingMode, placement?) devuelve estos valores. La llamada se escribe delante de un 。 que cierra la oración (先生[^1]。): se queda con el carácter anterior, y 。 nunca abre una línea. Ver Composición japonesa › Notas.

Cómo se componen las notas al pie de columna:

• La nota y su llamada comparten columna. Antes de colocar una línea, la maquetación suma la altura de las notas que esa línea cita por primera vez (y la del filete, en la primera nota de la columna). Una línea cuyas notas no caben debajo pasa a la columna siguiente con el resto de su párrafo, según las reglas de viudas y huérfanas. El área de texto de la columna se acorta en la altura de las notas, así que el equilibrado de columnas y la banda de cierre de un capítulo solo cuentan el texto.
• Varias notas en una columna se apilan en el orden de cita bajo un único filete. Una nota citada de nuevo más adelante conserva su número y no se vuelve a componer.
• Flotantes al pie. Una figura que ocupa el pie de una columna después de que sus notas se hayan compuesto queda encima de ellas; las notas compuestas después de la figura quedan encima de ella.
• Recuadros. Una nota citada dentro de un recuadro (en línea, flotante o fijo) va al pie de la columna donde sigue el texto tras el recuadro, normalmente la misma. Un recuadro que cierra el documento deja sus notas al pie de la columna donde terminó el texto.
• Límites. Una nota nunca se parte: una más alta que la columna la desborda. Las llamadas en pies de figura, celdas de tabla y títulos no se leen (se imprimen tal cual).
• Salida. El canvas, el HTML y el PDF pintan las notas, las llamadas (un número volado) y el filete. En el PDF cada llamada enlaza con su nota, y un PDF etiquetado marca cada nota como elemento Note con un /ID único listado en el /IDTree del árbol de estructura (PDF/UA-1). Las notas son VDTBlock con footnoteNote, en page.floats; los filetes están en page.footnoteAreas.
• Avisos. undefinedFootnote (una llamada sin definición: el número se imprime sobre una nota vacía) y unusedFootnote (una definición que ninguna llamada cita: no se compone).

El resolutor y el depurador siguen el patrón de las demás secciones:

import { DEFAULT_FOOTNOTES_CONFIG, resolveFootnotesConfig, stripFootnotesDefaults, footnoteDocumentDefaults } from 'postext';
 
resolveFootnotesConfig(config.footnotes, 'ja', 'vertical-rl'); // los campos sin fijar toman los valores japoneses verticales

#Numeración de líneas

La propiedad lineNumbers imprime en el margen el número de cada quinta línea (o de cada enésima), a su lado, como hacen las ediciones críticas, las antologías de poesía, los textos legales y las ediciones escolares. Cuenta los versos de los poemas :::verse, o todas las líneas del texto. Está desactivada por defecto. Cada número se pinta sobre la línea base de su línea, con un cuerpo propio, y nunca mueve una línea: la página se compone exactamente igual que sin números. Desde postext 1.23.

interface LineNumbersConfig {
  enabled?: boolean;        // Desactivada por defecto.
  count?: 'verse' | 'all';  // Los versos de los poemas, o todas las líneas del texto.
  interval?: number;        // Imprimir los múltiplos de N.
  numberFirst?: boolean;    // Imprimir también la primera línea tras cada reinicio.
  restart?: 'document' | 'chapter' | 'section' | 'page' | 'poem'; // Dónde vuelve a empezar la cuenta.
  startAt?: number;         // El número de la primera línea tras un reinicio.
  position?: 'outer' | 'inner' | 'left' | 'right' | 'start' | 'end' | 'side';
  multiColumn?: 'each' | 'gutter' | 'outer-edges'; // Páginas de dos o más columnas.
  gap?: Dimension;          // Del texto al número; em es el cuerpo del número.
  align?: 'auto' | 'left' | 'right';
  fontFamily?: string;      // La familia del cuerpo si no se fija.
  fontSize?: Dimension;     // em es el cuerpo del texto.
  fontWeight?: number;      // El peso del cuerpo si no se fija.
  italic?: boolean;
  color?: ColorValue;       // El color del cuerpo si no se fija.
  format?: string;          // decimal, lower-roman, arabic-indic, 一…
}

lineNumbers: {
  enabled: true,
  count: 'verse',
  interval: 5,
  restart: 'document',          // una sola cuenta para todo el libro
  position: 'outer',
  fontSize: { value: 0.75, unit: 'em' },
  italic: true,
}

Qué se cuenta y qué no:

• Nunca se cuentan los títulos, los pies, las tablas y las imágenes, las fórmulas en bloque, el texto de diseño (aperturas, titulillos), las notas al pie y las notas de final de capítulo, el índice general, las entradas del índice alfabético y de la bibliografía, ni las páginas en blanco.
• Recuadros y prosa. El texto de un recuadro no se cuenta, y con count: 'verse' tampoco la prosa, salvo que el estilo de párrafo en que se compone diga lineNumbers: true; un estilo con lineNumbers: false no se cuenta nunca (véase Estilos de párrafo).
• Un poema. La apertura de un poema admite numbered=false (sus versos no se cuentan), lineStart=N (su primer verso es el N, y la cuenta vuelve a empezar ahí) e interval=N. :::numbering{lines=N} da el número N a la siguiente línea contada, esté donde esté. Véase Formato del documento › :::verse y :::numbering.

En un libro maquetado capítulo a capítulo, restart: 'document' lleva la cuenta de un capítulo al siguiente en continuation.lineNumber. continuationAfter cuenta los versos a partir del texto; con count: 'all' la cuenta depende de la maquetación, así que la aplicación pasa el lastLineNumber del documento del capítulo anterior, como hace el Sandbox.

Con position: 'side' los números comparten la columna lateral con los recuadros, los pies y las figuras laterales. Un número que se solapa con uno de ellos se pinta igualmente, ninguno de los dos se mueve, y la maquetación da un aviso de contenido lineNumberOverlap que señala la línea numerada.

Salida. El canvas, el PDF, el visor HTML y el EPUB de maquetación fija pintan los números. En un PDF etiquetado son artefactos de paginación y cada uno lleva un /ActualText vacío, así que el texto copiado o extraído pasa de una línea a otra sin ellos. La salida HTML los oculta a las tecnologías de apoyo (aria-hidden), a la selección y al texto copiado. El EPUB de maquetación fluida, cuyas líneas compone el sistema de lectura, conserva solo los números de los versos: un span pt-line-number (también aria-hidden) en el margen inicial de la estrofa, junto a cada verso que lleva número en la versión impresa. En el VDT los números son una ranura de diseño de cada página (page.lineNumbers, con sus bloques de texto marcados artifact) y una lista de marcas (page.lineNumberMarks: number, label, columnIndex, blockId, lineIndex); el documento guarda lastLineNumber.

No se admiten: números de línea en texto vertical, una referencia cruzada que imprima el número de una línea, notas enlazadas a números de línea, ni números para las líneas de celdas de tabla, pies o listados de código.

En el Sandbox estos ajustes son la sección Numeración de líneas del panel de diseño. El resolutor y el depurador siguen el patrón de las demás secciones; la fuente, el peso y el color salen del texto de cuerpo:

import { DEFAULT_LINE_NUMBERS_CONFIG, resolveLineNumbersConfig, stripLineNumbersDefaults } from 'postext';
 
resolveLineNumbersConfig(config.lineNumbers, resolvedBodyText); // fuente, peso y color sin fijar siguen al cuerpo

#Referencias cruzadas

La propiedad crossRefs fija las palabras que una referencia cruzada imprime alrededor de un número o de una página, y el estilo que toma un :ref que no indica ninguno. Cada plantilla lleva {n} donde va el número; una que no lo lleva recibe el número detrás de un espacio de no separación ("§" imprime § 3.2). Una plantilla sin definir sigue al idioma del documento: capítulo / sección / pág. en español, chapter / section / p. en inglés, 第{n}章 / 第{n}节 / 第{n}页 en chino, y lo mismo para francés, alemán, italiano, portugués, catalán y 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=.
}

Las referencias toman el color, el peso y la inclinación de todas las referencias (bodyText.referenceColor, referenceBold, referenceItalic).

#Citas

La propiedad citations elige el estilo de cita y cómo se ven las citas y la bibliografía. El marcado se describe en Citas y bibliografía; el estilo lo aplica el paquete 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;
  };
}

#Índice de contenidos

La propiedad toc configura lo que imprime una directiva :::toc (ver Formato del documento). El índice se ensambla a partir del esquema del documento — cada encabezado con su número y su etiqueta de página, cada :::part — de modo que sigue a los capítulos: renombra uno, muévelo a otra parte, cambia sus autores, y las entradas cambian con él. Una entrada es el número del encabezado en una columna propia, el título, una línea de puntos y la etiqueta de página en el borde derecho, y después una línea de subtítulo opcional; una parte es una fila diseñada por 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 caja de banda, 'SECCIÓN {number}', '{titleText}', '{pageNumber}' */] },
    },
  },
};

Las etiquetas de página son las que el documento imprime. buildDocument() vuelve a componer un documento con :::toc con las etiquetas de la pasada anterior hasta que se estabilizan (tres pasadas adicionales como máximo); un anfitrión que compone un libro capítulo a capítulo suministra en su lugar el esquema del libro entero como PostextContent.outline, ensamblado con contentOutline() (encabezados y partes a partir del texto) y outlineFromDoc() (las mismas entradas con las etiquetas de página de una composición), y vuelve a componer el capítulo del índice cada vez que cambia el outlineKey() de ese esquema. Cada entrada de encabezado lleva el number que imprime el índice y, en un encabezado numerado, su counter: la cuenta acumulada del nivel tras cualquier startAt, imprima lo que imprima la plantilla — lo que un anfitrión muestra junto a un capítulo en sus propias listas.

#Índice analítico

La propiedad index configura lo que imprime una directiva :::index (ver Formato del documento): los términos marcados con :index[…] e :index{term="…"} en el texto, ordenados, agrupados por inicial (en chino, por la inicial del pinyin o por trazos, y en japonés por filas del gojūon; véase groupBy) y cada uno con las páginas en que cae. Una entrada es su término, un separador y sus números de página; detrás van sus subentradas, con un paso de sangría por nivel, y las líneas que continúan una entrada cuelgan turnoverIndent para no alinearse nunca con una subentrada.

const config: PostextConfig = {
  headingStyles: [
    // El índice a dos columnas, bajo su propio encabezado.
    { 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' } },
  },
};

Los números de página salen del esquema del libro, como los del índice de contenidos: computeOutline() y contentOutline() enumeran las marcas de un texto como entradas de tipo 'indexMark' (con indexMark.path, sort, see, seeAlso, main, range e index), y outlineFromDoc() da a cada una la página en que cayó, que la composición registra en doc.indexMarks ({ sourceStart, pageIndex } por marca). buildDocument() vuelve a componer un documento que imprime su propio índice hasta que los números se estabilizan; un anfitrión que compone un libro capítulo a capítulo pasa al capítulo que contiene :::index el esquema del libro entero como PostextContent.outline. tocOutline() e indexOutline() separan un esquema en lo que leen el índice de contenidos y el analítico, para que el anfitrión asocie cada capítulo a lo que imprime: el sandbox vuelve a componer el capítulo del índice analítico solo cuando se mueve una marca, y el del índice de contenidos solo cuando se mueve un encabezado. contentOutline() indica además si un texto imprime un índice analítico (hasIndex).