Configuration: notes and references

#Footnotes

The footnotes property sets where the notes cited with [^id] go, how they are numbered and how they look. The markup is described in Document format.

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

Japanese books. A Japanese document (locale: 'ja', since postext 1.16) gives the fields it leaves unset the values of JLReq §4.2. A vertical book sets its notes after the chapter (placement: 'chapterEnd', 後注), numbered by chapter, with markers （{n}） right of the line (markerPosition: 'right', digits upright by cjk.uprightDigits); a horizontal one sets them at the foot of the page, numbered per page, with superscript markers. Both draw the rule a third of the measure long (separator.width: 1/3), and notes after the chapter take numberGap: 'em' and a two-em hanging indent. An explicit value wins and is kept on save (stripFootnotesDefaults compares with the document's own defaults); Chinese, Arabic and Latin documents resolve as before. footnoteDocumentDefaults(locale, writingMode, placement?) returns these values. Write a marker before a sentence-final 。 (先生[^1]。): it stays with the character before it, and 。 never opens a line. See Japanese layout › Notes.

How the notes are laid out at the column foot:

• Note and citation share a column. Before it places a line, the layout adds the height of the notes that line cites for the first time (and the rule, for the first note of the column). A line whose notes do not fit under it goes to the next column with the rest of its paragraph, under the orphan and widow rules. The column's text area shrinks by the notes' height, so the column balancing and the closing band of a chapter count only the text.
• Several notes in one column stack in citation order under one rule. A note cited again later keeps its number and is not set again.
• Bottom floats. A figure that takes the foot of a column after its notes were set goes above them; notes set after the figure go above it.
• Boxes. A note cited inside a callout (inline, floated or fixed) goes to the foot of the column where the text after the box goes on, usually the same column. A box that closes the document leaves its notes at the foot of the column the text ended in.
• Limits. A note is never split: one taller than a column overflows it. Markers in captions, table cells and headings are not read (they print as written).
• Output. Canvas, HTML and PDF paint the notes, the markers (a superscript number) and the rule. In the PDF each marker links to its note, and a tagged PDF sets each note as a Note element with a unique /ID listed in the structure tree's /IDTree (PDF/UA-1). The notes are VDTBlocks with footnoteNote set, in page.floats; the rules are in page.footnoteAreas.
• Warnings. undefinedFootnote (a marker with no definition: the number prints over an empty note) and unusedFootnote (a definition no marker cites: it is not set).

Resolver and stripper match the other sections:

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

#Line numbers

The lineNumbers property prints the number of every fifth line (or every Nth) in the margin beside it, as critical editions, anthologies of poetry, legal texts and school editions do. It counts the lines of :::verse poems, or every line of the text. It is off by default. Each number is painted on the baseline of its line, in a size of its own, and never moves a line: the page is laid out exactly as it would be without numbers. Since 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,
}

What is counted, and what is not:

• Never counted: headings, captions, tables and pictures, display formulas, design text (openers, running heads), footnotes and chapter-end notes, the contents, the entries of the index and of the bibliography, and blank pages.
• Boxes and prose. The text of a callout is not counted, and under count: 'verse' neither is prose, unless the paragraph style it is set in says lineNumbers: true; a style with lineNumbers: false is never counted (see Paragraph styles).
• One poem. A poem's fence takes numbered=false (its lines are not counted), lineStart=N (its first line is N, and the count starts again there) and interval=N. :::numbering{lines=N} numbers the next counted line N, wherever it stands. See Document format › :::verse and :::numbering.

In a book laid out chapter by chapter, restart: 'document' carries the count from one chapter to the next through continuation.lineNumber. continuationAfter counts the lines of verse from the text; with count: 'all' the count depends on the layout, so the host passes on the lastLineNumber of the previous chapter's document, as the Sandbox does.

With position: 'side' the numbers share the side column with side boxes, side captions and side figures. A number that overlaps one of them is painted anyway, neither of them moves, and the build reports a lineNumberOverlap content warning that points at the numbered line.

Output. The canvas, the PDF, the HTML viewer and the fixed-layout EPUB paint the numbers. In a tagged PDF they are layout artifacts and each one carries an empty /ActualText, so copied or extracted text runs from line to line without them. The HTML output hides them from assistive technology (aria-hidden), from selection and from copied text. The reflowable EPUB, whose lines are set by the reading system, keeps the numbers of verse only: a pt-line-number span (also aria-hidden) in the start margin of the stanza, beside each line that carries a number in print. In the VDT the numbers are a design slot of each page (page.lineNumbers, its text blocks flagged artifact) and a list of marks (page.lineNumberMarks: number, label, columnIndex, blockId, lineIndex); the document records lastLineNumber.

Not supported: line numbers in vertical text, a cross-reference that prints the number of a line, notes keyed to line numbers, and numbers for the lines of table cells, captions or code listings.

In the Sandbox these settings are the Line numbers section of the Design panel. Resolver and stripper match the other sections; the font, the weight and the colour come from the body text:

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

#Cross-references

The crossRefs property sets the words a cross-reference prints around a number or a page, and the style a :ref takes when it sets none. Each template holds {n} where the number goes; one without it gets the number after a no-break space ("§" prints § 3.2). An unset template follows the document language: chapter / section / p. in English, capítulo / sección / pág. in Spanish, 第{n}章 / 第{n}节 / 第{n}页 in Chinese, and so on for French, German, Italian, Portuguese, Catalan and Dutch.

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=.
}

References take the colour, weight and slant of every reference (bodyText.referenceColor, referenceBold, referenceItalic).

#Citations

The citations property chooses the citation style and how citations and the bibliography look. The markup is described in Citations and bibliography; the style is applied by the postext-citeproc package.

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;
  };
}

#Table of contents

The toc property configures what a :::toc directive prints (see Document format). The contents are assembled from the document's outline — every heading with its number and page label, every :::part — so they follow the chapters: rename one, move it to another part, change its authors, and the entries change with it. An entry is the heading's number in a column of its own, the title, a leader and the page label at the right edge, then an optional subtitle line; a part is a row designed by 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}' */] },
    },
  },
};

The page labels are the ones the document prints. buildDocument() lays a document with a :::toc out again with the labels of the previous pass until they settle (at most three extra passes); a host laying a book out chapter by chapter supplies the whole book's outline as PostextContent.outline instead, assembled from contentOutline() (headings and parts from the text alone) and outlineFromDoc() (the same entries with the page labels of a layout), and lays the contents chapter out again whenever outlineKey() of that outline changes. Each heading entry carries the number the contents print and, for a numbered heading, its counter: the level's running count after any startAt, whatever the template prints — what a host shows beside a chapter in its own lists.

#Back-of-book index

The index property configures what a :::index directive prints (see Document format): the terms marked with :index[…] and :index{term="…"} in the text, sorted, grouped by first letter (by pinyin initial or stroke count in Chinese, by gojūon row in Japanese, see groupBy), each with the pages it falls on. An entry is its term, a separator and its page numbers; its sub-entries follow, one indent step per level, and wrapped lines hang by turnoverIndent so they never line up with a sub-entry.

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

The page numbers come from the book's outline, as the contents' do: computeOutline() and contentOutline() list the index marks of a text as entries of kind 'indexMark' (with indexMark.path, sort, see, seeAlso, main, range and index), and outlineFromDoc() gives each the page it landed on, which the build records in doc.indexMarks ({ sourceStart, pageIndex } per mark). buildDocument() lays a document that prints its own index out again until the numbers settle; a host laying out a book chapter by chapter hands the chapter holding :::index the whole book's outline as PostextContent.outline. tocOutline() and indexOutline() split an outline into what the contents and the index read, so a host can key each chapter to the part it prints: the Sandbox lays the index chapter out again only when a mark moves, and the contents chapter only when a heading does. contentOutline() also says whether a text prints an index (hasIndex).