Configuração: notas e referências

#Notas de rodapé

A propriedade footnotes define onde ficam as notas citadas com [^id], como são numeradas e qual é a sua aparência. A marcação é descrita em Formato do documento.

interface FootnotesConfig {
  placement?: 'column' | 'chapterEnd' | 'spread'; // No pé da coluna que cita, depois do capítulo, ou ao lado do texto de uma página dupla.
  numbering?: 'chapter' | 'document' | 'page' | 'column' | 'spread'; // Recomeça a cada capítulo, segue corrida, ou recomeça a cada página / coluna / página dupla.
  numberFormat?: string;      // decimal, lower-roman, circled-decimal (①)…
  symbols?: string[];         // Os símbolos de nota de numberFormat: 'symbols'.
  markerPosition?: 'auto' | 'superscript' | 'inline' | 'side' | 'right'; // Elevado, na linha de base, ao lado da palavra, ou à direita de uma linha vertical.
  markerSize?: Dimension;     // Tamanho do marcador em linha, lateral ou à direita; em é o texto ao redor.
  numberGap?: 'en' | 'em';    // Espaço depois do número da própria nota.
  chapterEndAlign?: 'foot' | 'text';   // chapterEnd: notas no pé da coluna ou logo abaixo do texto.
  fontSize?: Dimension;       // Tamanho das notas; em é o tamanho do corpo.
  lineHeight?: Dimension;     // Entrelinha das notas; em é o tamanho da nota.
  color?: ColorValue;         // Cor das notas; a cor do corpo quando não definida.
  textAlign?: TextAlign;      // O alinhamento do corpo quando não definido.
  hangingIndent?: Dimension;  // Recuo das linhas seguintes de uma nota.
  spaceBetween?: Dimension;   // Espaço entre duas notas.
  spaceAbove?: Dimension;     // Espaço entre o texto e o fio; em é o tamanho do corpo.
  spaceBelowRule?: Dimension; // Espaço entre o fio e a primeira nota.
  separator?: {
    enabled?: boolean;        // Desenha o fio.
    width?: number;           // Comprimento do fio, uma fração da largura da coluna.
    lineWidth?: Dimension;    // Espessura do fio.
    color?: ColorValue;       // A cor das notas quando não definida.
  };
}

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

Livros japoneses. Um documento japonês (locale: 'ja', desde o postext 1.16) dá aos campos que deixa sem definir os valores do JLReq §4.2. Um livro vertical compõe as notas depois do capítulo (placement: 'chapterEnd', 後注), numeradas por capítulo, com marcadores （{n}） à direita da linha (markerPosition: 'right', algarismos em pé por cjk.uprightDigits); um horizontal as compõe no pé da página, numeradas por página, com marcadores sobrescritos. Os dois desenham o fio com um terço da medida (separator.width: 1/3), e as notas depois do capítulo recebem numberGap: 'em' e um recuo deslocado de dois emes. Um valor explícito prevalece e é mantido ao salvar (stripFootnotesDefaults compara com os padrões do próprio documento); documentos em chinês, árabe e línguas latinas se resolvem como antes. footnoteDocumentDefaults(locale, writingMode, placement?) devolve esses valores. Escreva o marcador antes de um 。 de fim de frase (先生[^1]。): ele fica junto do caractere anterior, e 。 nunca abre uma linha. Veja Composição em japonês › Notas.

Como as notas são compostas no pé da coluna:

• Nota e citação dividem uma coluna. Antes de posicionar uma linha, o layout soma a altura das notas que essa linha cita pela primeira vez (e o fio, na primeira nota da coluna). Uma linha cujas notas não cabem abaixo dela vai para a coluna seguinte com o resto do seu parágrafo, conforme as regras de órfãs e viúvas. A área de texto da coluna diminui na altura das notas, então o balanceamento de colunas e a faixa final de um capítulo contam só o texto.
• Várias notas numa coluna se empilham em ordem de citação sob um único fio. Uma nota citada de novo mais adiante mantém o seu número e não é composta outra vez.
• Flutuantes inferiores. Uma figura que ocupa o pé de uma coluna depois que as notas dela foram compostas fica acima delas; as notas compostas depois da figura ficam acima dela.
• Boxes. Uma nota citada dentro de um boxe (em linha, flutuante ou fixo) vai para o pé da coluna em que o texto depois do boxe continua, em geral a mesma coluna. Um boxe que fecha o documento deixa as suas notas no pé da coluna em que o texto terminou.
• Limites. Uma nota nunca é dividida: uma nota mais alta que uma coluna transborda dela. Os marcadores em legendas, células de tabela e títulos não são lidos (saem impressos como foram escritos).
• Saída. Canvas, HTML e PDF pintam as notas, os marcadores (um número sobrescrito) e o fio. No PDF cada marcador tem um link para a sua nota, e um PDF etiquetado compõe cada nota como um elemento Note com um /ID único listado na /IDTree da árvore de estrutura (PDF/UA-1). As notas são VDTBlocks com footnoteNote definido, em page.floats; os fios ficam em page.footnoteAreas.
• Avisos. undefinedFootnote (um marcador sem definição: o número é impresso sobre uma nota vazia) e unusedFootnote (uma definição que nenhum marcador cita: não é composta).

O resolvedor e o redutor seguem o padrão das outras seções:

import { DEFAULT_FOOTNOTES_CONFIG, resolveFootnotesConfig, stripFootnotesDefaults, footnoteDocumentDefaults } from 'postext';
 
resolveFootnotesConfig(config.footnotes, 'ja', 'vertical-rl'); // os campos não definidos recebem os padrões japoneses verticais

#Numeração de linhas

A propriedade lineNumbers imprime na margem o número de cada quinta linha (ou de cada enésima), ao lado dela, como fazem as edições críticas, as antologias de poesia, os textos legais e as edições escolares. Ela conta os versos dos poemas :::verse, ou todas as linhas do texto. Vem desligada por padrão. Cada número é pintado na linha de base da sua linha, num corpo próprio, e nunca move uma linha: a página é diagramada exatamente como seria sem números. Desde postext 1.23.

interface LineNumbersConfig {
  enabled?: boolean;        // Desligada por padrão.
  count?: 'verse' | 'all';  // Os versos dos poemas, ou todas as linhas do texto.
  interval?: number;        // Imprimir os múltiplos de N.
  numberFirst?: boolean;    // Imprimir também a primeira linha depois de cada reinício.
  restart?: 'document' | 'chapter' | 'section' | 'page' | 'poem'; // Onde a contagem recomeça.
  startAt?: number;         // O número da primeira linha depois de um reinício.
  position?: 'outer' | 'inner' | 'left' | 'right' | 'start' | 'end' | 'side';
  multiColumn?: 'each' | 'gutter' | 'outer-edges'; // Páginas com duas colunas ou mais.
  gap?: Dimension;          // Do texto ao número; em é o corpo do número.
  align?: 'auto' | 'left' | 'right';
  fontFamily?: string;      // A família do texto corrido quando não definida.
  fontSize?: Dimension;     // em é o corpo do texto.
  fontWeight?: number;      // O peso do texto corrido quando não definido.
  italic?: boolean;
  color?: ColorValue;       // A cor do texto corrido quando não definida.
  format?: string;          // decimal, lower-roman, arabic-indic, 一…
}

lineNumbers: {
  enabled: true,
  count: 'verse',
  interval: 5,
  restart: 'document',          // uma só contagem para o livro inteiro
  position: 'outer',
  fontSize: { value: 0.75, unit: 'em' },
  italic: true,
}

O que é contado e o que não é:

• Nunca são contados os títulos, as legendas, as tabelas e as imagens, as fórmulas em destaque, o texto de design (aberturas, cabeços), as notas de rodapé e as notas de fim de capítulo, o sumário, as entradas do índice remissivo e da bibliografia, nem as páginas em branco.
• Boxes e prosa. O texto de um boxe não é contado, e com count: 'verse' a prosa também não, a menos que o estilo de parágrafo em que é composta diga lineNumbers: true; um estilo com lineNumbers: false nunca é contado (veja Estilos de parágrafo).
• Um poema. A abertura de um poema aceita numbered=false (os seus versos não são contados), lineStart=N (o seu primeiro verso é o N, e a contagem recomeça ali) e interval=N. :::numbering{lines=N} dá o número N à próxima linha contada, onde quer que esteja. Veja Formato do documento › :::verse e :::numbering.

Num livro diagramado capítulo por capítulo, restart: 'document' leva a contagem de um capítulo para o seguinte em continuation.lineNumber. continuationAfter conta os versos a partir do texto; com count: 'all' a contagem depende da diagramação, então a aplicação repassa o lastLineNumber do documento do capítulo anterior, como faz o Sandbox.

Com position: 'side' os números dividem a coluna lateral com os boxes, as legendas e as figuras laterais. Um número que se sobrepõe a um deles é pintado mesmo assim, nenhum dos dois se move, e a diagramação dá um aviso de conteúdo lineNumberOverlap que aponta para a linha numerada.

Saída. Canvas, PDF, o visualizador HTML e o EPUB de layout fixo pintam os números. Num PDF etiquetado eles são artefatos de paginação e cada um leva um /ActualText vazio, de modo que o texto copiado ou extraído passa de uma linha para a outra sem eles. A saída HTML os esconde das tecnologias assistivas (aria-hidden), da seleção e do texto copiado. O EPUB refluível, cujas linhas são compostas pelo sistema de leitura, guarda só os números dos versos: um span pt-line-number (também aria-hidden) na margem inicial da estrofe, ao lado de cada verso que leva número na versão impressa. No VDT os números são um bloco de design de cada página (page.lineNumbers, com os blocos de texto marcados artifact) e uma lista de marcas (page.lineNumberMarks: number, label, columnIndex, blockId, lineIndex); o documento registra lastLineNumber.

Não há suporte para números de linha em texto vertical, uma referência cruzada que imprima o número de uma linha, notas ligadas a números de linha, nem números para as linhas de células de tabela, legendas ou listagens de código.

No Sandbox essas configurações são a seção Numeração de linhas do painel Design. O resolvedor e o removedor de padrões seguem as outras seções; a fonte, o peso e a cor vêm do texto corrido:

import { DEFAULT_LINE_NUMBERS_CONFIG, resolveLineNumbersConfig, stripLineNumbersDefaults } from 'postext';
 
resolveLineNumbersConfig(config.lineNumbers, resolvedBodyText); // fonte, peso e cor não definidos seguem o texto corrido

#Referências cruzadas

A propriedade crossRefs define as palavras que uma referência cruzada imprime em volta de um número ou de uma página, e o estilo que um :ref assume quando não define nenhum. Cada modelo contém {n} onde vai o número; um modelo sem ele recebe o número depois de um espaço inseparável ("§" imprime § 3.2). Um modelo não definido segue o idioma do documento: chapter / section / p. em inglês, capítulo / sección / pág. em espanhol, 第{n}章 / 第{n}节 / 第{n}页 em chinês, e assim por diante em francês, alemão, italiano, português, catalão e neerlandês.

interface CrossRefsConfig {
  chapter?: string;  // Palavras em volta do número de um título de nível 1: "chapter {n}".
  section?: string;  // Em volta do número de qualquer outro título: "section {n}".
  page?: string;     // Em volta de um número de página: "p. {n}".
  defaultStyle?: 'default' | 'number' | 'title' | 'page'; // Um :ref sem style=.
}

As referências recebem a cor, o peso e a inclinação de todas as referências (bodyText.referenceColor, referenceBold, referenceItalic).

#Citações

A propriedade citations escolhe o estilo de citação e a aparência das citações e da bibliografia. A marcação é descrita em Citações e bibliografia; o estilo é aplicado pelo pacote postext-citeproc.

interface CitationsConfig {
  style?: string;          // 'apa', 'ieee', 'chicago-notes-bibliography'… ou 'custom'
  customStyle?: string;    // um estilo CSL completo (XML .csl), usado com style: 'custom'
  locale?: string;         // locale CSL; o idioma do documento quando não definido
  link?: boolean;          // as citações têm link para as suas entradas
  marker?: 'style' | 'brackets' | 'parentheses' | 'superscript' | 'corner';
  collapseRanges?: boolean;
  notes?: 'footnote' | 'warichu';
  numbering?: 'book' | 'chapter';
  bibliography?: {
    title?: string;        // não definido: a palavra do idioma do documento; '' ou ' ': nenhum
    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;
  };
}

#Sumário

A propriedade toc configura o que uma diretiva :::toc imprime (veja Formato do documento). O sumário é montado a partir da estrutura do documento (cada título com o seu número e o rótulo da sua página, cada :::part), então acompanha os capítulos: renomeie um, mova-o para outra parte, mude os seus autores, e as entradas mudam junto. Uma entrada é o número do título numa coluna própria, o título, uma linha de pontos e o rótulo da página na margem direita, e depois uma linha de subtítulo opcional; uma parte é uma linha desenhada 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: [/* a band box, 'SECTION {number}', '{titleText}', '{pageNumber}' */] },
    },
  },
};

Os rótulos de página são os que o documento imprime. buildDocument() diagrama de novo um documento com :::toc usando os rótulos da passada anterior até que eles se estabilizem (no máximo três passadas extras); um host que diagrama um livro capítulo a capítulo fornece em vez disso a estrutura do livro inteiro como PostextContent.outline, montada a partir de contentOutline() (títulos e partes só a partir do texto) e de outlineFromDoc() (as mesmas entradas com os rótulos de página de uma diagramação), e diagrama de novo o capítulo do sumário sempre que o outlineKey() dessa estrutura muda. Cada entrada de título traz o number que o sumário imprime e, para um título numerado, o seu counter: a contagem corrente do nível depois de qualquer startAt, seja o que for que o modelo imprima; é o que um host mostra ao lado de um capítulo nas suas próprias listas.

#Índice remissivo

A propriedade index configura o que uma diretiva :::index imprime (veja Formato do documento): os termos marcados com :index[…] e :index{term="…"} no texto, ordenados, agrupados pela letra inicial (pela inicial do pinyin ou pelo número de traços em chinês, pela linha do gojūon em japonês, veja groupBy), cada um com as páginas em que aparece. Uma entrada é o seu termo, um separador e os seus números de página; as subentradas vêm em seguida, com um passo de recuo por nível, e as linhas quebradas recuam por turnoverIndent para nunca se alinharem com uma subentrada.

const config: PostextConfig = {
  headingStyles: [
    // O índice em duas colunas, sob o seu próprio título.
    { id: 'index', 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' } },
  },
};

Os números de página vêm da estrutura do livro, como os do sumário: computeOutline() e contentOutline() listam as marcações de índice de um texto como entradas do tipo 'indexMark' (com indexMark.path, sort, see, seeAlso, main, range e index), e outlineFromDoc() dá a cada uma a página em que caiu, que a construção registra em doc.indexMarks ({ sourceStart, pageIndex } por marcação). buildDocument() diagrama de novo um documento que imprime o seu próprio índice até os números se estabilizarem; um host que diagrama um livro capítulo a capítulo entrega ao capítulo que contém :::index a estrutura do livro inteiro como PostextContent.outline. tocOutline() e indexOutline() dividem uma estrutura no que o sumário e o índice leem, para que um host possa associar cada capítulo ao que ele imprime: o Sandbox diagrama de novo o capítulo do índice só quando uma marcação se move, e o do sumário só quando um título se move. contentOutline() também diz se um texto imprime um índice (hasIndex).