Configuration : notes et références

#Notes de bas de page

La propriété footnotes définit où vont les notes appelées avec [^id], comment elles sont numérotées et à quoi elles ressemblent. Le balisage est décrit dans Format du document.

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

Livres japonais. Un document japonais (locale: 'ja', depuis postext 1.16) donne aux champs qu’il laisse vides les valeurs de JLReq §4.2. Un livre vertical place ses notes après le chapitre (placement: 'chapterEnd', 後注), numérotées par chapitre, avec des appels （{n}） à droite de la ligne (markerPosition: 'right', chiffres droits grâce à cjk.uprightDigits) ; un livre horizontal les place au pied de la page, numérotées par page, avec des appels en exposant. Les deux tracent un filet long d’un tiers de la justification (separator.width: 1/3), et les notes après le chapitre prennent numberGap: 'em' et un retrait suspendu de deux cadratins. Une valeur explicite l’emporte et est conservée à l’enregistrement (stripFootnotesDefaults compare avec les valeurs par défaut propres au document) ; les documents chinois, arabes et latins se résolvent comme avant. footnoteDocumentDefaults(locale, writingMode, placement?) renvoie ces valeurs. Écrivez un appel avant un 。 final (先生[^1]。) : il reste avec le caractère qui le précède, et 。 n’ouvre jamais une ligne. Voir Mise en page japonaise › Notes.

Comment les notes se placent au pied de la colonne :

• La note et son appel partagent une colonne. Avant de placer une ligne, la mise en page ajoute la hauteur des notes que cette ligne appelle pour la première fois (et celle du filet, pour la première note de la colonne). Une ligne dont les notes ne tiennent pas sous elle passe à la colonne suivante avec le reste de son paragraphe, selon les règles des orphelines et des veuves. La zone de texte de la colonne diminue de la hauteur des notes, si bien que l’équilibrage des colonnes et la bande de clôture d’un chapitre ne comptent que le texte.
• Plusieurs notes dans une même colonne s’empilent dans l’ordre des appels sous un seul filet. Une note appelée de nouveau plus loin garde son numéro et n’est pas composée une deuxième fois.
• Flottants en bas de page. Une figure qui occupe le pied d’une colonne après que ses notes ont été placées se met au-dessus d’elles ; les notes placées après la figure se mettent au-dessus d’elle.
• Encadrés. Une note appelée dans un encadré (en ligne, flottant ou fixe) va au pied de la colonne où le texte reprend après l’encadré, généralement la même colonne. Un encadré qui termine le document laisse ses notes au pied de la colonne où le texte s’est terminé.
• Limites. Une note n’est jamais coupée : une note plus haute qu’une colonne déborde de celle-ci. Les appels dans les légendes, les cellules de tableau et les titres ne sont pas lus (ils s’impriment tels qu’écrits).
• Sortie. Le canvas, le HTML et le PDF peignent les notes, les appels (un numéro en exposant) et le filet. Dans le PDF, chaque appel renvoie par un lien à sa note, et un PDF balisé fait de chaque note un élément Note doté d’un /ID unique, répertorié dans l’/IDTree de l’arbre de structure (PDF/UA-1). Les notes sont des VDTBlock dont footnoteNote est défini, dans page.floats ; les filets sont dans page.footnoteAreas.
• Avertissements. undefinedFootnote (un appel sans définition : le numéro s’imprime au-dessus d’une note vide) et unusedFootnote (une définition qu’aucun appel ne cite : elle n’est pas composée).

Le résolveur et la fonction de nettoyage suivent le modèle des autres sections :

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

#Numéros de ligne

La propriété lineNumbers imprime le numéro d’une ligne sur cinq (ou sur N) dans la marge, à côté de la ligne, comme le font les éditions critiques, les anthologies de poésie, les textes juridiques et les éditions scolaires. Elle compte les lignes des poèmes :::verse, ou toutes les lignes du texte. Elle est désactivée par défaut. Chaque numéro est peint sur la ligne de base de sa ligne, dans un corps qui lui est propre, et ne déplace jamais une ligne : la page est mise en page exactement comme elle le serait sans numéros. Depuis 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,
}

Ce qui est compté, et ce qui ne l’est pas :

• Jamais comptés : les titres, les légendes, les tableaux et les images, les formules hors texte, le texte de maquette (ouvertures, titres courants), les notes de bas de page et de fin de chapitre, la table des matières, les entrées de l’index et de la bibliographie, et les pages blanches.
• Encadrés et prose. Le texte d’un encadré n’est pas compté, et avec count: 'verse' la prose non plus, sauf si le style de paragraphe dans lequel elle est composée indique lineNumbers: true ; un style avec lineNumbers: false n’est jamais compté (voir Styles de paragraphe).
• Un poème. La directive d’un poème accepte numbered=false (ses lignes ne sont pas comptées), lineStart=N (sa première ligne porte le numéro N, et le compte repart là) et interval=N. :::numbering{lines=N} donne le numéro N à la ligne comptée suivante, où qu’elle se trouve. Voir Format du document › :::verse et :::numbering.

Dans un livre mis en page chapitre par chapitre, restart: 'document' reporte le compte d’un chapitre au suivant par continuation.lineNumber. continuationAfter compte les vers à partir du texte ; avec count: 'all', le compte dépend de la mise en page, si bien que l’hôte transmet le lastLineNumber du document du chapitre précédent, comme le fait le Sandbox.

Avec position: 'side', les numéros partagent la colonne latérale avec les encadrés latéraux, les légendes latérales et les figures latérales. Un numéro qui chevauche l’un de ces éléments est peint malgré tout, aucun des deux ne bouge, et la construction signale un avertissement de contenu lineNumberOverlap qui désigne la ligne numérotée.

Sortie. Le canvas, le PDF, la visionneuse HTML et l’EPUB à mise en page fixe peignent les numéros. Dans un PDF balisé, ce sont des artefacts de mise en page et chacun porte un /ActualText vide, si bien que le texte copié ou extrait passe d’une ligne à l’autre sans eux. La sortie HTML les cache aux technologies d’assistance (aria-hidden), à la sélection et au texte copié. L’EPUB recomposable, dont les lignes sont composées par le système de lecture, ne garde que les numéros des vers : un span pt-line-number (lui aussi aria-hidden) dans la marge de début de la strophe, à côté de chaque ligne qui porte un numéro à l’impression. Dans le VDT, les numéros sont un emplacement de maquette de chaque page (page.lineNumbers, dont les blocs de texte sont marqués artifact) et une liste de repères (page.lineNumberMarks : number, label, columnIndex, blockId, lineIndex) ; le document enregistre lastLineNumber.

Non pris en charge : les numéros de ligne en texte vertical, un renvoi qui imprime le numéro d’une ligne, les notes rattachées à des numéros de ligne, et les numéros des lignes des cellules de tableau, des légendes ou des listings de code.

Dans le Sandbox, ces réglages forment la section Numéros de ligne du panneau Maquette. Le résolveur et la fonction de nettoyage suivent le modèle des autres sections ; la police, la graisse et la couleur viennent du texte courant :

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

#Renvois

La propriété crossRefs définit les mots qu’un renvoi imprime autour d’un numéro ou d’une page, et le style que prend un :ref qui n’en définit aucun. Chaque modèle contient {n} à l’endroit du numéro ; un modèle qui ne le contient pas reçoit le numéro après une espace insécable ("§" imprime § 3.2). Un modèle non défini suit la langue du document : chapter / section / p. en anglais, capítulo / sección / pág. en espagnol, 第{n}章 / 第{n}节 / 第{n}页 en chinois, et ainsi de suite pour le français, l’allemand, l’italien, le portugais, le catalan et le néerlandais.

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

Les renvois prennent la couleur, la graisse et l’inclinaison communes à tous les renvois (bodyText.referenceColor, referenceBold, referenceItalic).

#Citations

La propriété citations choisit le style de citation et l’apparence des citations et de la bibliographie. Le balisage est décrit dans Citations et bibliographie ; le style est appliqué par le package 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;
  };
}

#Table des matières

La propriété toc configure ce qu’imprime une directive :::toc (voir Format du document). La table est assemblée à partir du plan du document (chaque titre avec son numéro et l’étiquette de sa page, chaque :::part), si bien qu’elle suit les chapitres : renommez-en un, déplacez-le dans une autre partie, changez ses auteurs, et les entrées changent avec lui. Une entrée se compose du numéro du titre dans une colonne à part, de l’intitulé, de points de conduite et de l’étiquette de page au bord droit, puis d’une ligne de sous-titre facultative ; une partie est une rangée dessinée par 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}' */] },
    },
  },
};

Les étiquettes de page sont celles que le document imprime. buildDocument() remet en page un document contenant un :::toc avec les étiquettes de la passe précédente jusqu’à ce qu’elles se stabilisent (au plus trois passes supplémentaires) ; un hôte qui met en page un livre chapitre par chapitre fournit à la place le plan du livre entier dans PostextContent.outline, assemblé à partir de contentOutline() (titres et parties tirés du seul texte) et de outlineFromDoc() (les mêmes entrées avec les étiquettes de page d’une mise en page), et remet en page le chapitre de la table des matières chaque fois que l’outlineKey() de ce plan change. Chaque entrée de titre porte le number qu’imprime la table et, pour un titre numéroté, son counter : le compte courant du niveau après un éventuel startAt, quoi qu’imprime le modèle, c’est-à-dire ce qu’un hôte affiche à côté d’un chapitre dans ses propres listes.

#Index

La propriété index configure ce qu’imprime une directive :::index (voir Format du document) : les termes marqués avec :index[…] et :index{term="…"} dans le texte, triés, regroupés par première lettre (par initiale pinyin ou par nombre de traits en chinois, par rangée du gojūon en japonais, voir groupBy), chacun avec les pages où il apparaît. Une entrée se compose de son terme, d’un séparateur et de ses numéros de page ; ses sous-entrées suivent, avec un cran de retrait par niveau, et les lignes suivantes d’une entrée sont décalées de turnoverIndent pour ne jamais s’aligner sur une sous-entrée.

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

Les numéros de page viennent du plan du livre, comme ceux de la table des matières : computeOutline() et contentOutline() listent les marques d’index d’un texte comme des entrées de type 'indexMark' (avec indexMark.path, sort, see, seeAlso, main, range et index), et outlineFromDoc() donne à chacune la page où elle a abouti, que la construction enregistre dans doc.indexMarks ({ sourceStart, pageIndex } par marque). buildDocument() remet en page un document qui imprime son propre index jusqu’à ce que les numéros se stabilisent ; un hôte qui met en page un livre chapitre par chapitre transmet au chapitre contenant :::index le plan du livre entier dans PostextContent.outline. tocOutline() et indexOutline() séparent dans un plan ce que lisent respectivement la table des matières et l’index, pour qu’un hôte puisse associer à chaque chapitre la partie du plan qu’il imprime : le Sandbox ne remet en page le chapitre de l’index que lorsqu’une marque se déplace, et celui de la table des matières que lorsqu’un titre se déplace. contentOutline() indique aussi si un texte imprime un index (hasIndex).