Konfiguration: Listen und Mathematik

#Aufzählungen

Die Eigenschaft unorderedLists steuert, wie Aufzählungen (-, *, +) und GFM-Aufgabenlisten (- [ ], - [x]) dargestellt werden. Bis zu fünf Verschachtelungsebenen werden unterstützt.

#Standardwerte für Aufzählungen

#Erweiterungen für Aufgabenlisten

GFM-Aufgabenpunkte (- [ ] …, - [x] …) werden als Punkte einer Aufzählung mit einem Kontrollkästchen anstelle des Aufzählungszeichens dargestellt. Die Engine zeichnet das Kästchen selbst, einen quadratischen Umriss mit einem Häkchen, wenn der Punkt erledigt ist: Dafür wird keine Schrift angefordert, es sieht also auf jedem Rechner gleich aus, auf dem Canvas, im PDF, im HTML und im EPUB, und assistive Technologien lesen ☐ oder ☑. Seine Seitenlänge beträgt 0,6 em der Größe des Zeichens (bulletFontSize oder fontSize der Ebene), und das ist der Raum, den es vor dem gap einnimmt; in Textgröße steht es auf der Grundlinie der ersten Zeile des Punkts. Seine Strichstärke folgt dem fontWeight des Zeichens und seine Farbe dessen color. Die folgenden Felder gelten nur für Aufgabenpunkte:

#Überschreibungen pro Ebene für Aufzählungen

Jeder Eintrag in levels gilt für eine Tiefe (1–5) und kann jede der folgenden Eigenschaften überschreiben:

Kaskade der Einzüge. Ebene 1 beginnt immer beim allgemeinen Wert indent (standardmäßig 0 em – die Aufzählungszeichen stehen an der Spaltenkante). Lassen Sie indent für die Ebenen 2–5 undefiniert, setzt die Engine das Aufzählungszeichen an den Textanfang der vorigen Ebene (Einzug der übergeordneten Ebene + Breite des Aufzählungszeichens + gap). Setzen Sie auf einer Ebene ein ausdrückliches indent, um die Kaskade zu unterbrechen und diese Tiefe an beliebiger Stelle festzulegen.

unorderedLists: {
  bulletChar: '—',
  gap: { value: 0.4, unit: 'em' },
  hangingIndent: true,
  levels: [
    { level: 2, bulletChar: '·' },
    { level: 3, bulletChar: '◦', color: { hex: '#666666', model: 'hex' } },
  ],
}

#Nummerierte Listen

Die Eigenschaft orderedLists steuert nummerierte Listen (1., 2) usw.). Bis zu fünf Verschachtelungsebenen werden unterstützt, und jede Tiefe kann ein anderes Zahlenformat verwenden.

#Standardwerte für nummerierte Listen

#Überschreibungen pro Ebene für nummerierte Listen

Jeder Eintrag in levels kann numberFormat, prefix, separator, fontFamily, fontSize, color, fontWeight, italic, indent, verticalOffset und den Stil des Trenners (separatorFontFamily, separatorFontWeight, separatorItalic, separatorColor, separatorGap) überschreiben – es gilt dieselbe Kaskade der Einzüge wie bei Aufzählungen. Der Trennerstil einer Ebene erbt den eigenen Nummernstil der Ebene, sofern keine listenweite Einstellung für den Trenner angegeben ist.

Rechtsbündige Ausrichtung. Die Pipeline misst die breiteste formatierte Nummer innerhalb einer Folge und rückt alle Punkte dieser Folge so ein, dass die Nummern an ihrer rechten Kante fluchten. In einer Liste mit zehn Punkten, gesetzt als 1. – 10., werden die einstelligen Nummern rechts aufgefüllt, sodass der Trenner in derselben Spalte bleibt.

orderedLists: {
  numberFormat: 'arabic',
  separator: '.',
  levels: [
    { level: 2, numberFormat: 'lower-alpha' },
    { level: 3, numberFormat: 'lower-roman', separator: ')' },
  ],
}

Das ergibt die klassische verschachtelte Mischung:

1. First item
   a. Sub-item
      i) Deep note
   b. Sub-item
2. Second item

Die Gliederung chinesischer Dokumente (GB/T 15834—2011, Anhang B.3) hat fünf Ebenen, 一、, dann （一）, dann 1., dann （1）, dann ①:

orderedLists: {
  levels: [
    { level: 1, numberFormat: 'simp-chinese-informal', separator: '、' },
    { level: 2, numberFormat: 'simp-chinese-informal', prefix: '（', separator: '）' },
    { level: 3, numberFormat: 'arabic', separator: '.' },
    { level: 4, numberFormat: 'arabic', prefix: '（', separator: '）' },
    { level: 5, numberFormat: 'circled-decimal', separator: '' },
  ],
}

#Mathematik

Die Eigenschaft math steuert, wie LaTeX-Formeln zwischen den Begrenzern $...$ (inline) und $$...$$ (abgesetzt) geparst und dargestellt werden. Die zugrunde liegende Engine ist MathJax (das Paket mathjax-full) im SVG-Ausgabemodus, auf dem Canvas gerastert und im PDF als skalierbare Glyphen eingebettet.

interface MathConfig {
  enabled?: boolean;        // Render LaTeX. When false, spans pass through as literal TeX.
  fontSizeScale?: number;   // × the surrounding text's size (the body size for display maths).
  color?: ColorValue;       // Formula colour; inherits body colour if omitted.
  marginTop?: Dimension;    // Space above display math blocks.
  marginBottom?: Dimension; // Minimum space below; baseline grid snap may enlarge it.
  indentAfterDisplay?: boolean; // Indent a paragraph that follows a display formula.
  keepWithLeadIn?: boolean; // Keep a display formula with the line that leads into it.
  equationNumbering?: {      // Number the display formulas that carry a \label.
    enabled?: boolean;           // default true
    numberingTemplate?: string;  // '{n}'; '{h1}.{n}' numbers by chapter
    resetOn?: ResourceCounterReset; // 'never' | 'h1' … 'h6'
    counterFormat?: ResourceCounterFormat; // 'decimal'
    format?: string;             // '({n})': what the formula and \eqref print
  };
}

math: {
  enabled: true,
  fontSizeScale: 1.0,
  color: { hex: '#295AA3', model: 'hex' },
  marginTop: { value: 1, unit: 'em' },
  marginBottom: { value: 1, unit: 'em' },
}

Formelgröße, geändert in postext 1.5. MathJax gibt den Rahmen einer Formel in ex an, und ein ex seiner TeX-Schrift misst 0,442 em. Bis postext 1.4 nahm die Engine ein halbes Geviert dafür an, sodass jede Formel etwa 13 % größer als bodyText.fontSize × fontSizeScale gesetzt wurde. Formeln erscheinen jetzt in der dokumentierten Größe, und Zeilen und Seiten mit Mathematik werden neu umbrochen. Eine für 1.4 im Code geschriebene Konfiguration behält die Formelgröße von 1.4, indem sie einmal, wie geschrieben, durch pinLegacyMathSize aus postext/bundle geschickt wird:

import { pinLegacyMathSize } from 'postext/bundle';
 
config = pinLegacyMathSize(config); // formulas, and the space around display formulas, as 1.4 set them

Auch andere Regeländerungen in 1.5 können ihre Seiten verschieben: die Umbrüche vor Überschriften, der Abstand um eine Inline-Abbildung (im laufenden Text und in Kästen), die Inline-Auszeichnungen ihrer Überschriften, die Größe ihrer Initialen, der Raum unter einer Doppelpunktzeile für die Liste, die sie einleitet, die Zeilen, die ein Kastenschnitt von einem Absatz oder Listenpunkt übrig lässt, die Zeilenumbrüche nach einem Strich, der Umbruch von Flattersatz, die Teilung eines Absatzes unter einer Überschrift, die Zeilenumbrüche nach dem Bindestrich eines Kompositums und der Abstand unter einem Container :::paragraphs. migrateConfig, einmal mit dem Markdown ausgeführt, das die Konfiguration setzt, fixiert diejenigen, die dieser Text braucht, die Formelgröße eingeschlossen (siehe Pakete, die postext 1.4 oder früher geschrieben hat):

import { migrateConfig } from 'postext/bundle';
 
config = migrateConfig(config, undefined, { content: markdown }); // heading breaks, formulas, inline gaps, heading marks, drop caps, colon lines, box cuts, dash breaks, compound breaks, ragged breaking, splits under a heading and container space as 1.4 set them

Das hält zurück, was diese Regeländerungen verschieben würden, bewahrt aber nicht jede Seite von 1.4. Version 1.5 behebt auch Layoutfehler, und eine Korrektur hat keine Fixierung: Eine alte Konfiguration erhält sie wie eine neue, sodass sich eine davon betroffene Seite dennoch verschieben kann. Darunter: Eine Überschrift über die ganze Seitenbreite ohne eigene Gestaltung wird über die Seite gemessen und im Zeilenabstand ihrer Ebene gesetzt; unter der Grundlinie einer Initiale in einer Überschriftengestaltung wird nichts reserviert; eine Initiale nimmt die Palettenfarbe des Abschnitts an und wird auch in einem Gestaltungstext gesetzt, dessen overflow nicht 'wrap' ist, der dann umbricht; ein Absatz in einem Kasten malt die Laufweite, mit der er gemessen wurde; ein geteilter Kasten behält seine Symbolspalte auf jedem Fragment; eine Kastenzeile, die ihre Leerzeichen über das 3-Fache dehnen würde, wird wie im laufenden Text im Flattersatz gesetzt; der Hebel für lockere Absätze setzt nie eine Blocksatzzeile breiter, als maxWordSpacing zulässt; ein gleitender Kasten behält ein marginBottom (in einem oberen Band) oder marginTop (in einem unteren Band), das breiter als der Gleitobjektabstand ist; ein zentrierter oder rechtsbündiger Gestaltungstext mit Laufweite (ein lebender Kolumnentitel, ein Auftakttitel) wird nach seinen Buchstaben platziert, ohne die Laufweite nach dem letzten; unter einem Auftakt über die ganze Seitenbreite beginnt der Text, der die zweite Spalte eröffnet, dort, wo Text direkt unter dem Auftakt beginnen würde, auch wenn eine Überschrift auf den Auftakt folgt; die Punkte des Inhaltsverzeichnisses enden vor der Seitenzahl in einer Schrift, die eine Folge von Punkten auseinanderkernt; ein lebender Kolumnentitel liest eine Überschrift wie geschrieben, ohne Leerzeichen, wo eine ihrer Zeilen nach einem Bindestrich oder einem Strich oder innerhalb eines aus Breitengründen geschnittenen Worts endet (MEDIOAMBIENTALES, nicht MEDIOAMBIENTALE S), und das {titleText} einer Überschriftengestaltung liest sie ebenso (thousand-colour, nicht thousand- colour); ein am Fuß oder an der Mitte des Bands einer Überschriftengestaltung verankerter Text hält das Band hoch genug, um ihn zu fassen, sodass er nicht mehr über den Text über der Überschrift steigt; ein Wort, das breiter als seine Zeile ist und neben einem eigenen Bindestrich geschnitten wird, wird nach diesem Bindestrich geschnitten und erhält keinen zweiten; der Punkt nach einer in einer anderen verschachtelten Liste nimmt das itemSpacing seiner eigenen Liste an, nicht das der verschachtelten; und der Rest eines Worts, das wegen Überbreite geschnitten wurde, behält seine eigenen Umbruchstellen, sodass eine Webadresse weiter an ihren Fugen umbricht und ein Kompositum an seinen Bindestrichen statt an den Silben des Wörterbuchs.

pinLegacyMathSize multipliziert den Faktor mit 1,1312 (0,5 ÷ 0,442) und teilt die Abstände abgesetzter Formeln in em durch denselben Faktor. Der Faktor allein reicht für ein Buch mit abgesetzten Formeln nicht: Ihre Abstände sind Längen in der eigenen Größe der Formel, sie würden also um dieselben 13 % wachsen und den Text darunter nach unten schieben. Für die Standardabstände ausgeschrieben, lauten die drei Werte:

math: {
  fontSizeScale: 1.131,
  marginTop: { value: 0.7072, unit: 'em' },
  marginBottom: { value: 0.7072, unit: 'em' },
} // formulas as large as 1.4 set them, with the space 1.4 left around them

Wo die Konfiguration gespeichert wurde, erkennt die Engine das und erledigt es für Sie: openBundle / readBundle für ein .postext-Paket, das vor 1.5 geschrieben wurde (siehe Pakete, die postext 1.4 oder früher geschrieben hat), und die Sandbox für die Bücher, die Arbeitskopie und die Dateien postext-config.json, die damals gespeichert wurden (siehe Sandbox → Persistenz). Sie werden durch migrateConfig gelesen, das die Größe fixiert (pinLegacyMathSize): fontSizeScale wird zum gespeicherten Faktor (1, wenn nicht gesetzt) × 1,1312, und ein Abstand abgesetzter Formeln in em oder rem – eine Länge in der eigenen Größe der Formel – wird durch denselben Faktor geteilt, sodass der Abstand um eine abgesetzte Formel bleibt, wie 1.4 ihn ließ (aus dem Standard 0,8 em werden 0,7072 em). Ein Abstand in einer Seiteneinheit (pt, mm …) bleibt, wie er ist, ebenso eine Konfiguration mit enabled: false oder eine, deren Buch kein $ enthält. Das alte Buch wird dann so gesetzt, wie 1.4 es setzte, und sein Abschnitt math zeigt die Größe, in der es gesetzt wird. Um ein solches Buch stattdessen in der heutigen Größe zu setzen, setzen Sie diese Werte zurück – Formeln → Größenfaktor, Abstand oben (abgesetzt) und Abstand unten (abgesetzt) in der Sandbox, oder im Code:

math: { ...config.math, fontSizeScale: 1, marginTop: undefined, marginBottom: undefined } // today's size and margins

Nummerierte Gleichungen. Eine abgesetzte Formel mit Nummer überspannt ihre Satzbreite (die Spalte oder die Innenbreite des Kastens, in dem sie steht): Die Gleichung wird zentriert und ihre Nummer rechtsbündig auf die Zeile der Gleichung gesetzt, auf jede nummerierte Zeile eines align. Eine Nummer kommt von einem \label{eq:x} (seit postext 1.19): Die beschrifteten Formeln und die beschrifteten Zeilen eines align, gather, alignat, flalign oder eqnarray werden in Lesereihenfolge mit equationNumbering nummeriert, sofern eine Zeile nicht \nonumber oder \notag sagt. Umgebungen wie equation werden nicht von selbst nummeriert: Eine Formel ohne Label hat keine Nummer. \tag{…} druckt die angegebene Bezeichnung in Klammern und \tag*{…} wie geschrieben; keine von beiden wird gezählt, und ein \label daneben benennt sie. Eine nummerierte Gleichung, die breiter als ihre Satzbreite ist, läuft wie jede abgesetzte Formel nach rechts über. (Bis postext 1.4 wurde eine Formel mit \tag gar nicht gezeichnet; bis 1.18 nummerierte nur \tag eine.)

\eqref{eq:x} im Text druckt die Nummer in ihrem format, (3), und \ref{eq:x} die bloße Nummer; ebenso :ref{id="eq:x"} und @eq:x (siehe Querverweise), und innerhalb einer Formel druckt \eqref sie als Text. In einem Kapitel für Kapitel gesetzten Buch läuft der Zähler ab dem vorigen Kapitel weiter: continuationAfter trägt ihn in LayoutContinuation.statementCounters (equation), und die Gliederung des Buchs gibt jedem Label seine Nummer (OutlineEntry.numberLabel), sodass ein Verweis auf eine Gleichung eines anderen Kapitels sie druckt.

math: {
  equationNumbering: { numberingTemplate: '{h1}.{n}', resetOn: 'h1' }, // (1.1), (1.2)… (2.1)
}

Resolver und Stripper entsprechen denen der anderen Abschnitte:

import {
  DEFAULT_MATH_CONFIG,
  resolveMathConfig,
  stripMathDefaults,
} from 'postext';
 
const resolved = resolveMathConfig(config.math);
const minimal  = stripMathDefaults(config.math);

#Die Mathematik-Engine starten

MathJax wird bei Bedarf geladen, nicht mit dem Rest der Engine. Setzen Sie im Hauptthread, starten Sie es, bevor Sie ein Dokument mit Formeln bauen:

import { buildDocument, initMathEngine, renderPage } from 'postext';
 
await initMathEngine(); // loads MathJax once; later calls resolve at once
const doc = buildDocument({ markdown: 'Euler: $e^{i\\pi}+1=0$.' }, config);
document.body.append(renderPage(doc.pages[0], doc));

• Bis die Engine läuft, sind Formeln Platzhalter. Jede wird als grauer Kasten in geschätzter Größe gesetzt. Wird ein Dokument mit Mathematik gesetzt, bevor initMathEngine() je aufgerufen wurde, zeigt die Konsole eine Warnung dazu.
• Der Layout-Worker startet sie für Sie. Ein Build in postext/worker ruft initMathEngine() selbst auf, wenn das Markdown ein $ enthält.
• Jetzt setzen, erneut, wenn sie bereit ist. isMathReady() sagt, ob die Engine läuft. onMathReady(fn) ruft fn auf, sobald sie es tut (sofort, wenn sie es schon tut), und gibt eine Funktion zurück, die den Aufruf abbricht. Ein Editor kann sofort Platzhalter zeigen und erneut setzen, wenn MathJax eintrifft; solange initMathEngine() läuft, wird keine Warnung ausgegeben.
• Fehlschlag. initMathEngine() wird abgelehnt, wenn MathJax nicht geladen werden kann, und ein späterer Aufruf versucht es erneut.
• Jeder Bundler, Node oder ein CDN. MathJax liegt dem Paket als ein vorgebündeltes Modul bei (etwa 1,8 MB vor der Kompression, nur von initMathEngine abgerufen). Das einfache import { initMathEngine } from 'https://esm.sh/postext' funktioniert; kein ?bundle nötig. Das Paket mathjax-full wird nur zum Bauen von postext gebraucht, die Installation von postext installiert es also nicht. MathJax und der mitgebündelte mhchem-Parser stehen unter der Apache-2.0-Lizenz: Ihre Hinweise und der Lizenztext liegen neben dem Modul, als dist/math/THIRD_PARTY_LICENSES.txt.
• Eine Engine pro Seite. Die Engine und ihr Cache gesetzter Formeln werden von allem geteilt, was postext im selben JavaScript-Realm importiert (siehe Globaler Zustand innerhalb einer Seite).

Die Grammatik auf der Dokumentseite ($...$, $$...$$, ein wörtliches Dollarzeichen maskieren) finden Sie unter Dokumentformat.