Configurazione: note e riferimenti

#Note a piè di pagina

La proprietà footnotes stabilisce dove vanno le note citate con [^id], come sono numerate e che aspetto hanno. Il markup è descritto in Formato del documento.

interface FootnotesConfig {
  placement?: 'column' | 'chapterEnd' | 'spread'; // Foot of the citing column, after the chapter, or beside the text of a spread.
  numbering?: 'chapter' | 'document' | 'page' | 'column' | 'spread'; // Start again at each chapter, run on, or start again on each page / column / spread.
  numberFormat?: string;      // decimal, lower-roman, circled-decimal (①)…
  symbols?: string[];         // The note symbols of numberFormat: 'symbols'.
  markerPosition?: 'auto' | 'superscript' | 'inline' | 'side' | 'right'; // Raised, on the baseline, beside the word, or right of a vertical line.
  markerSize?: Dimension;     // Inline, side or right marker size; em is the text around it.
  numberGap?: 'en' | 'em';    // Space after the note's own number.
  chapterEndAlign?: 'foot' | 'text';   // chapterEnd: notes at the column foot, or under the text.
  fontSize?: Dimension;       // Note size; em is the body size.
  lineHeight?: Dimension;     // Note leading; em is the note size.
  color?: ColorValue;         // Note colour; the body colour when unset.
  textAlign?: TextAlign;      // The body alignment when unset.
  wordBreak?: 'normal' | 'keep-all'; // The document's cjk.wordBreak when unset.
  hangingIndent?: Dimension;  // Indent of a note's turnover lines.
  spaceBetween?: Dimension;   // Space between two notes.
  spaceAbove?: Dimension;     // Space between the text and the rule; em is the body size.
  spaceBelowRule?: Dimension; // Space between the rule and the first note.
  separator?: {
    enabled?: boolean;        // Draw the rule.
    width?: number;           // Rule length, a fraction of the column width.
    lineWidth?: Dimension;    // Rule thickness.
    color?: ColorValue;       // The note colour when unset.
  };
}

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

Libri giapponesi. Un documento giapponese (locale: 'ja', da postext 1.16) assegna ai campi che lascia non impostati i valori di JLReq §4.2. Un libro verticale colloca le note dopo il capitolo (placement: 'chapterEnd', 後注), numerate per capitolo, con richiami （{n}） a destra della riga (markerPosition: 'right', cifre dritte grazie a cjk.uprightDigits); uno orizzontale le colloca al piede della pagina, numerate per pagina, con richiami in apice. Entrambi disegnano il filetto lungo un terzo della giustezza (separator.width: 1/3), e le note dopo il capitolo prendono numberGap: 'em' e un rientro sporgente di due em. Un valore esplicito ha la precedenza e si conserva al salvataggio (stripFootnotesDefaults confronta con i valori predefiniti propri del documento); i documenti cinesi, arabi e latini si risolvono come prima. footnoteDocumentDefaults(locale, writingMode, placement?) restituisce questi valori. Scrivi un richiamo prima di un 。 di fine frase (先生[^1]。): resta con il carattere che lo precede, e 。 non apre mai una riga. Vedi Impaginazione giapponese › Note.

Come si dispongono le note al piede della colonna:

• Nota e citazione condividono una colonna. Prima di collocare una riga, l’impaginazione aggiunge l’altezza delle note che quella riga cita per la prima volta (e il filetto, per la prima nota della colonna). Una riga le cui note non stanno sotto di essa passa alla colonna successiva con il resto del suo paragrafo, nel rispetto delle regole su orfane e vedove. L’area del testo della colonna si riduce dell’altezza delle note, quindi il bilanciamento delle colonne e la fascia di chiusura di un capitolo contano solo il testo.
• Più note in una colonna si impilano in ordine di citazione sotto un unico filetto. Una nota citata di nuovo più avanti conserva il suo numero e non viene composta di nuovo.
• Elementi flottanti in basso. Una figura che occupa il piede di una colonna dopo che le sue note sono state collocate va sopra di esse; le note collocate dopo la figura vanno sopra di essa.
• Riquadri. Una nota citata dentro un riquadro (in linea, flottante o fisso) va al piede della colonna in cui prosegue il testo dopo il riquadro, di solito la stessa colonna. Un riquadro che chiude il documento lascia le sue note al piede della colonna in cui è terminato il testo.
• Limiti. Una nota non si divide mai: una più alta di una colonna la eccede. I richiami nelle didascalie, nelle celle di tabella e nei titoli non vengono letti (si stampano così come sono scritti).
• Output. Canvas, HTML e PDF disegnano le note, i richiami (un numero in apice) e il filetto. Nel PDF ogni richiamo è un link alla sua nota, e un PDF con tag imposta ogni nota come elemento Note con un /ID univoco elencato nel /IDTree dell’albero di struttura (PDF/UA-1). Le note sono VDTBlock con footnoteNote impostato, in page.floats; i filetti sono in page.footnoteAreas.
• Avvisi. undefinedFootnote (un richiamo senza definizione: il numero si stampa sopra una nota vuota) e unusedFootnote (una definizione che nessun richiamo cita: non viene composta).

Il resolver e lo stripper funzionano come nelle altre sezioni:

import { DEFAULT_FOOTNOTES_CONFIG, resolveFootnotesConfig, stripFootnotesDefaults, footnoteDocumentDefaults } from 'postext';
 
resolveFootnotesConfig(config.footnotes, 'ja', 'vertical-rl'); // unset fields take the Japanese vertical defaults

#Numeri di riga

La proprietà lineNumbers stampa nel margine accanto a ogni quinta riga (o a ogni N-esima) il suo numero, come fanno le edizioni critiche, le antologie poetiche, i testi giuridici e le edizioni scolastiche. Conta i versi delle poesie :::verse, oppure ogni riga del testo. È disattivata per impostazione predefinita. Ogni numero si disegna sulla linea di base della sua riga, con una dimensione propria, e non sposta mai una riga: la pagina viene impaginata esattamente come lo sarebbe senza numeri. Da postext 1.23.

interface LineNumbersConfig {
  enabled?: boolean;        // Off by default.
  count?: 'verse' | 'all';  // The lines of poems, or every line of the text.
  interval?: number;        // Print the multiples of N.
  numberFirst?: boolean;    // Also print the first line after each restart.
  restart?: 'document' | 'chapter' | 'section' | 'page' | 'poem'; // Where the count starts again.
  startAt?: number;         // The number of the first line after a restart.
  position?: 'outer' | 'inner' | 'left' | 'right' | 'start' | 'end' | 'side';
  multiColumn?: 'each' | 'gutter' | 'outer-edges'; // Pages of two or more columns.
  gap?: Dimension;          // From the text to the number; em is the number's size.
  align?: 'auto' | 'left' | 'right';
  fontFamily?: string;      // The body family when unset.
  fontSize?: Dimension;     // em is the body size.
  fontWeight?: number;      // The body weight when unset.
  italic?: boolean;
  color?: ColorValue;       // The body colour when unset.
  format?: string;          // decimal, lower-roman, arabic-indic, 一…
}

lineNumbers: {
  enabled: true,
  count: 'verse',
  interval: 5,
  restart: 'document',          // one count through the whole book
  position: 'outer',
  fontSize: { value: 0.75, unit: 'em' },
  italic: true,
}

Che cosa si conta e che cosa no:

• Mai contati: titoli, didascalie, tabelle e immagini, formule in evidenza, testi del progetto grafico (aperture, testatine), note a piè di pagina e note di fine capitolo, il sommario, le voci dell’indice analitico e della bibliografia, e le pagine bianche.
• Riquadri e prosa. Il testo di un riquadro non si conta, e con count: 'verse' nemmeno la prosa, a meno che lo stile di paragrafo in cui è composta non indichi lineNumbers: true; uno stile con lineNumbers: false non si conta mai (vedi Stili di paragrafo).
• Una poesia. Il recinto di una poesia accetta numbered=false (i suoi versi non si contano), lineStart=N (il suo primo verso è N, e il conteggio ricomincia lì) e interval=N. :::numbering{lines=N} assegna il numero N alla successiva riga contata, ovunque si trovi. Vedi Formato del documento › :::verse e :::numbering.

In un libro impaginato capitolo per capitolo, restart: 'document' porta il conteggio da un capitolo al successivo tramite continuation.lineNumber. continuationAfter conta i versi a partire dal testo; con count: 'all' il conteggio dipende dall’impaginazione, quindi l’host passa il lastLineNumber del documento del capitolo precedente, come fa la Sandbox.

Con position: 'side' i numeri condividono la colonna laterale con i riquadri laterali, le didascalie laterali e le figure laterali. Un numero che si sovrappone a uno di essi si disegna comunque, nessuno dei due si sposta, e la build segnala un avviso di contenuto lineNumberOverlap che indica la riga numerata.

Output. Il canvas, il PDF, il visualizzatore HTML e l’EPUB a layout fisso disegnano i numeri. In un PDF con tag sono artefatti di impaginazione e ciascuno porta un /ActualText vuoto, quindi il testo copiato o estratto scorre da una riga all’altra senza di essi. L’output HTML li nasconde alle tecnologie assistive (aria-hidden), alla selezione e al testo copiato. L’EPUB a layout fluido, le cui righe sono composte dal sistema di lettura, conserva solo i numeri dei versi: uno span pt-line-number (anch’esso aria-hidden) nel margine iniziale della strofa, accanto a ogni verso che nella stampa porta un numero. Nel VDT i numeri sono uno slot di design di ogni pagina (page.lineNumbers, con i suoi blocchi di testo contrassegnati artifact) e un elenco di marche (page.lineNumberMarks: number, label, columnIndex, blockId, lineIndex); il documento registra lastLineNumber.

Non supportati: numeri di riga nel testo verticale, un rimando che stampa il numero di una riga, note collegate ai numeri di riga, e numeri per le righe delle celle di tabella, delle didascalie o dei listati di codice.

Nella Sandbox queste impostazioni sono la sezione Numeri di riga del pannello Grafica. Il resolver e lo stripper funzionano come nelle altre sezioni; il font, il peso e il colore vengono dal testo corrente:

import { DEFAULT_LINE_NUMBERS_CONFIG, resolveLineNumbersConfig, stripLineNumbersDefaults } from 'postext';
 
resolveLineNumbersConfig(config.lineNumbers, resolvedBodyText); // unset font, weight and colour follow the body

#Rimandi

La proprietà crossRefs stabilisce le parole che un rimando stampa attorno a un numero o a una pagina, e lo stile che prende un :ref quando non ne imposta uno. Ogni modello contiene {n} dove va il numero; uno senza riceve il numero dopo uno spazio indivisibile ("§" stampa § 3.2). Un modello non impostato segue la lingua del documento: chapter / section / p. in inglese, capítulo / sección / pág. in spagnolo, 第{n}章 / 第{n}节 / 第{n}页 in cinese, e così via per francese, tedesco, italiano, portoghese, catalano e olandese.

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=.
  breakLabels?: boolean; // A label of words breaks at its spaces.
}

I rimandi prendono il colore, il peso e l’inclinazione comuni a tutti i rimandi (bodyText.referenceColor, referenceBold, referenceItalic).

#Citazioni

La proprietà citations sceglie lo stile delle citazioni e l’aspetto delle citazioni e della bibliografia. Il markup è descritto in Citazioni e bibliografia; lo stile viene applicato dal pacchetto 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';
  hyphenateNames?: boolean; // false: the cited authors' names are never divided
  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;
  };
}

#Indice dei contenuti

La proprietà toc configura ciò che stampa una direttiva :::toc (vedi Formato del documento). Il sommario si costruisce a partire dalla struttura del documento (ogni titolo con il suo numero e la sua etichetta di pagina, ogni :::part), quindi segue i capitoli: rinominane uno, spostalo in un’altra parte, cambiane gli autori, e le voci cambiano di conseguenza. Una voce è il numero del titolo in una colonna propria, il titolo, una linea di guida e l’etichetta di pagina al margine destro, poi una riga facoltativa di sottotitolo; una parte è una riga disegnata da 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}' */] },
    },
  },
};

Le etichette di pagina sono quelle che il documento stampa. buildDocument() reimpagina un documento con un :::toc usando le etichette del passaggio precedente finché non si stabilizzano (al massimo tre passaggi in più); un host che impagina un libro capitolo per capitolo fornisce invece la struttura dell’intero libro come PostextContent.outline, costruita con contentOutline() (titoli e parti ricavati dal solo testo) e outlineFromDoc() (le stesse voci con le etichette di pagina di un’impaginazione), e reimpagina il capitolo del sommario ogni volta che cambia outlineKey() di quella struttura. Ogni voce di titolo porta il number che stampa il sommario e, per un titolo numerato, il suo counter: il conteggio progressivo del livello dopo un eventuale startAt, qualunque cosa stampi il modello, cioè ciò che un host mostra accanto a un capitolo nei propri elenchi.

#Indice analitico

La proprietà index configura ciò che stampa una direttiva :::index (vedi Formato del documento): i termini marcati con :index[…] e :index{term="…"} nel testo, ordinati, raggruppati per lettera iniziale (per iniziale pinyin o numero di tratti in cinese, per riga del gojūon in giapponese, vedi groupBy), ciascuno con le pagine in cui compare. Una voce è il suo termine, un separatore e i suoi numeri di pagina; seguono le sue sottovoci, con un gradino di rientro per livello, e le righe che vanno a capo sporgono di turnoverIndent così da non allinearsi mai con una sottovoce.

const config: PostextConfig = {
  headingStyles: [
    // The index in two columns, under its own heading.
    { 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' } },
  },
};

I numeri di pagina vengono dalla struttura del libro, come quelli del sommario: computeOutline() e contentOutline() elencano le marche d’indice di un testo come voci di tipo 'indexMark' (con indexMark.path, sort, see, seeAlso, main, range e index), e outlineFromDoc() assegna a ciascuna la pagina in cui è finita, che la build registra in doc.indexMarks ({ sourceStart, pageIndex } per marca). buildDocument() reimpagina un documento che stampa il proprio indice finché i numeri non si stabilizzano; un host che impagina un libro capitolo per capitolo passa al capitolo che contiene :::index la struttura dell’intero libro come PostextContent.outline. tocOutline() e indexOutline() dividono una struttura in ciò che leggono il sommario e l’indice, così un host può collegare ogni capitolo alla parte che stampa: la Sandbox reimpagina il capitolo dell’indice solo quando si sposta una marca, e il capitolo del sommario solo quando si sposta un titolo. contentOutline() dice anche se un testo stampa un indice (hasIndex).