# Dokumentformat > Die Markdown-Teilmenge, die Postext einliest, und die Regeln für das Verfassen von Quelldokumenten - HTML-Fassung: https://postext.dev/de/docs/document-format - Zuletzt aktualisiert: 2026-10-07 - Lesezeit: 10 min - Andere Sprachen: [en](https://postext.dev/en/docs/document-format.md), [es](https://postext.dev/es/docs/document-format.md), [ca](https://postext.dev/ca/docs/document-format.md), [fr](https://postext.dev/fr/docs/document-format.md), [it](https://postext.dev/it/docs/document-format.md), [pt](https://postext.dev/pt/docs/document-format.md), [zh](https://postext.dev/zh/docs/document-format.md), [ja](https://postext.dev/ja/docs/document-format.md), [ar](https://postext.dev/ar/docs/document-format.md) ## Kurz gesagt Diese Seite erklärt, wie Sie einen Text schreiben, den Postext setzen kann. Sie schreiben in Markdown, einer einfachen Schreibweise, in der ein paar Zeichen Überschriften, Listen, fette Wörter und Links kennzeichnen. Postext versteht außerdem einige zusätzliche Zeichen für Kästen, Fußnoten, Bilder, Tabellen und Formeln. Die Seite führt jedes Zeichen auf, das Postext annimmt, und jedes, das es übergeht. Am Ende stehen Ratschläge für Texte, die sich leicht lesen lassen. **Postext liest einen bewusst kleinen Markdown-Dialekt.** Der Parser ist ein von Hand geschriebener Tokenizer – keine vollständige CommonMark-Implementierung –, daher ist das Quellformat eng gefasst und vorhersehbar. Das Ziel ist ein doppeltes: Die Engine soll klein und schnell bleiben, und Dokumente sollen sich ohne Aufwand zwischen Postext und jedem anderen CommonMark-Leser (Obsidian, Pandoc, VS Code …) austauschen lassen. Alles, was auf dieser Seite nicht aufgeführt ist, wird entweder als einfacher Text behandelt oder aus dem Inline-Strom entfernt. Wenn Sie ein Dokument programmatisch aufbauen, liefert Ihnen die Funktion `parseMarkdown` (siehe [Konfiguration › Parsen](https://postext.dev/de/docs/configuration-programmatic-usage.md#parsen)) genau die Blockstruktur, die die Layout-Engine verarbeitet. ## Frontmatter Ein Dokument kann mit einem optionalen YAML-Frontmatter-Block beginnen, der von `---`-Markierungen eingefasst ist: ```md --- title: Chapter One author: Jane Doe publishDate: 2026-04-15 --- # Chapter One The story begins here… ``` Rufen Sie `extractFrontmatter(source)` auf, um das Frontmatter vom Hauptteil zu trennen. Das eingelesene Metadatenobjekt wird zusammen mit dem restlichen Markdown und dem Zeichenoffset zurückgegeben, an dem der Hauptteil beginnt – nützlich, wenn Sie Fehler oder Cursorpositionen auf die ursprüngliche Quelle zurückführen müssen. Das Frontmatter wird mit [`gray-matter`](https://github.com/jonschlinkert/gray-matter) eingelesen, daher wird YAML jeder Form angenommen. Postext selbst beachtet nur `title`, `subtitle`, `author` und `publishDate`; weitere Schlüssel bleiben in `PostextContent.metadata` erhalten und stehen Ihnen zur freien Verwendung. Ein Block, der kein gültiges YAML ist – ein nicht geschlossenes Anführungszeichen, Text nach einem Wert in Anführungszeichen –, hält den Satz nicht an: `extractFrontmatter` gibt keine Metadaten zurück, den Text nach dem schließenden `---` als Hauptteil und die Begründung des Parsers in `error`. Das Dokument wird ohne seine Metadaten gesetzt, und der Build führt einen Eintrag `invalidFrontmatter` in `contentWarnings` (die Sandbox zeigt ihn als **Ungültiges Frontmatter** an). YAML gibt seinen Werten Typen: `1984` ist eine Zahl, `2026-04-15` ein Datum, `[Ana Gil, Luis Paz]` eine Liste. Postext druckt jedes dieser vier Felder als Text, gleich welchen Typs es ist: - eine Zahl in ihrer einfachen Dezimalform und einen Wahrheitswert als `true` oder `false` (`title: 1984` druckt *1984*). YAML liest eine Zahl als Wert, nicht Ziffer für Ziffer: `1.50` druckt *1.5*, `017` (oktal) *15*, `1:30` (Basis 60) *90*; - ein Datum als seinen Kalendertag, ausgeschrieben in der Sprache des Dokuments – der Einstellung `locale`, andernfalls dem Gebietsschema der Silbentrennung: `publishDate: 2026-04-15` druckt auf Englisch *April 15, 2026*, auf Spanisch *15 de abril de 2026*, auf Deutsch *15. April 2026*. Arabische Daten verwenden den gregorianischen Kalender, sofern das Tag keinen anderen nennt (`ar-u-ca-islamic` druckt das Hidschra-Datum), mit den Ziffern, die das Tag vorgibt (`ar-EG`: ١٥ أبريل ٢٠٢٦; `ar-u-nu-latn`: 15 أبريل 2026). Ein Datum mit Uhrzeit druckt den Tag seiner UTC-Zeit und lässt die Uhrzeit weg: `2026-09-24T23:30:00-05:00` ist 04:30 UTC am 25. und druckt *September 25, 2026*; - eine Liste als ihre durch Kommas verbundenen Einträge (`author: [Ana Gil, Luis Paz]` druckt *Ana Gil, Luis Paz*). Setzen Sie einen Wert in Anführungszeichen, damit er genau so gedruckt wird, wie er geschrieben ist – eine Zahl, die ihre Ziffern behalten muss, ein Datum, das seinen Tag behalten muss: `publishDate: "15/04/2026"`, `title: "1984"`. Der Text gelangt in `doc.metadata`, in die Platzhalter (`{title}`, `{publishDate}` …) und in Titel und Autor des PDFs. Eines der vier Felder ohne Textform – eine verschachtelte Map, ein leeres `title:` – fehlt in `doc.metadata`. `extractFrontmatter` gibt die Werte weiterhin so zurück, wie YAML sie typisiert hat; `metadataText(value, locale)` liefert den Text, den Postext für einen davon druckt. ## Blockelemente Postext erkennt sieben Arten von Textblöcken und Code-Listings, dazu die Direktiven und eingebetteten Ressourcen, die weiter unten auf dieser Seite behandelt werden. Blöcke enden immer an einer Leerzeile oder am Beginn eines anderen Blocks. > **Abbildung: Textblöcke auf einen Blick** > Die sieben Arten von Textblöcken, die Postext erkennt: Überschrift, Absatz, Zitat, ungeordnete Liste, geordnete Liste, Aufgabenliste und abgesetzte Formel, jeweils mit ihrer Markdown-Syntax. Direktiven und eingebettete Ressourcen werden gesondert behandelt. > > *Jede Art von Textblock und ihre Markdown-Schreibweise.* | Element | Syntax | Hinweise | | --- | --- | --- | | Überschrift | `# Title` … `###### H6` | Ein bis sechs `#`-Zeichen, gefolgt von einem Leerzeichen und dem Text der Überschrift. Die Ebenen 1–6 entsprechen direkt der Konfiguration `headings.levels`. | | Absatz | Einfacher Text über eine oder mehrere Zeilen | Aufeinanderfolgende nicht leere Zeilen ohne besondere Bedeutung werden mit einem einzelnen Leerzeichen verbunden und als ein Absatz ausgegeben. Zwischen zwei chinesischen oder japanischen Zeichen (Ideogramme, Kana, Satzzeichen voller Breite sowie typografische Anführungszeichen, Striche oder Auslassungspunkte daneben) entfällt das Zeilenende stattdessen, wie in CSS, sodass ein chinesischer Absatz in der Quelle an beliebiger Stelle umbrochen werden darf. Zwischen zwei solchen Zeichen (`“你好”⏎“再见”`, `他说……⏎“好”`) entscheiden die Zeichen dahinter: Das Zeilenende entfällt, wenn eines davon chinesisch oder japanisch ist, und `“hello”⏎“bye”` behält sein Leerzeichen. Koreanisch behält sein Leerzeichen. Ein in der Quelle getippter Zeilenumbruch bleibt nicht erhalten, es sei denn, die Zeile endet mit einem Backslash (ein erzwungener Zeilenumbruch, siehe [Zeilenumbrüche](https://postext.dev/de/docs/document-format.md#zeilenumbrüche)); eine Leerzeile beginnt einen neuen Absatz. Ein im Text getippter Tabulator ist ebenfalls ein Wortzwischenraum, sofern das Format des Absatzes keine Tabstopps setzt; `:tab` ist immer ein Tabulator (siehe [Tabulatoren und Tabstopps](https://postext.dev/de/docs/document-format.md#tabulatoren-und-tabstopps)). Ein Gedicht, dessen Zeilen so bleiben müssen, wie sie geschrieben sind, gehört in einen Block [`:::verse`](https://postext.dev/de/docs/document-format.md#verse). | | Zitat | `> quoted text` | Jede Zeile des Zitats muss mit `>` beginnen (danach ein optionales Leerzeichen). Aufeinanderfolgende Zitatzeilen verschmelzen zu einem einzigen Zitatblock und werden wie Absatzzeilen verbunden. Gesetzt wird er so, wie es `bodyText.blockquote` vorgibt: grau und kursiv mit dem Erstzeileneinzug des Fließtexts, sofern Sie nichts daran ändern (siehe [Konfiguration › Zitate](https://postext.dev/de/docs/configuration-text.md#zitate)). | | Ungeordnete Liste | `- item`, `* item`, `+ item` | Jede der drei Aufzählungsmarken wird angenommen. Ein Eintrag wird unter dem Eintrag darüber verschachtelt, wenn seine Marke mindestens zwei Spalten weiter eingerückt ist als die Marke jenes Eintrags: zwei Leerzeichen unter `-`, zwei oder drei unter `1.` (die Spalte seines Texts, wie in CommonMark), bis zu einer maximalen Tiefe von 5. | | Geordnete Liste | `1. item`, `2) item` | Ziffern, gefolgt von `.` oder `)`. Die Startnummer bleibt erhalten (eine Liste kann also bei 5 oder bei 0 beginnen). Das in der Ausgabe gesetzte Trennzeichen stammt aus `orderedLists.separator`, nicht aus der Quelle. | | Aufgabenliste (GFM) | `- [ ] todo`, `- [x] done` | Ein ungeordneter Eintrag mit einem Kontrollkästchen in eckigen Klammern. Angenommen werden ein kleines `x` und ein großes `X`. Die Engine zeichnet das Kästchen, mit einem Häkchen, wenn die Aufgabe erledigt ist; ein in `taskCheckboxChar` / `taskCheckedChar` angegebenes Zeichen wird an seiner Stelle als Text gesetzt. | | Abgesetzte Formel | `$$ … $$` | Eine LaTeX-Formel, als eigener Block gesetzt. Sie wird auf der Spalte zentriert, wie eine Überschrift am Grundlinienraster ausgerichtet und in der PDF-Ausgabe als Vektorgrafik beibehalten. Die einzeilige Form und die eingezäunte mehrzeilige Form sind unter [Mathematische Formeln](https://postext.dev/de/docs/document-format.md#mathematische-formeln) beschrieben. | | Codeblock | `0`, `~~~` … `~~~` | Ein Listing, so belassen, wie es geschrieben ist: jedes Leerzeichen, jeder Tabulator und jeder Zeilenumbruch, nichts wird als Markdown gelesen. Zeile für Zeile in der Code-Schrift in einem Kasten gesetzt. Siehe [Codeblöcke](https://postext.dev/de/docs/document-format.md#codeblöcke). | Eine einzelne Leerzeile zwischen zwei Listeneinträgen wird toleriert – die Liste bleibt zusammen. Zwei oder mehr Leerzeilen beenden die Liste. Listen verschiedener Art auf derselben Tiefe werden angenommen (Sie können mitten in einer Folge von ungeordnet zu geordnet wechseln), doch die Engine behandelt die Folgen für die Nummerierung als getrennt. In der Praxis bleiben Sie besser bei einer Art je Tiefe, sofern Sie keinen Grund zum Mischen haben. > **Abbildung: Verschachtelungstiefe von Listen** > Ein Listeneintrag wird unter dem Eintrag darüber verschachtelt, wenn er über dessen Marke hinaus eingerückt ist: zwei Leerzeichen unter einem Aufzählungszeichen, bis zu einer maximalen Tiefe von fünf. Jede Ebene ist weiter eingerückt und kann ein anderes Aufzählungszeichen verwenden. > > *Zwei Leerzeichen je Ebene unter einem Aufzählungszeichen. Maximale Tiefe: fünf.* ### Attribute von Überschriften Eine Überschriftenzeile kann mit einem Attributblock in geschweiften Klammern enden – mit derselben Syntax `key="value"`, die Direktiven verwenden: ```markdown # The Long Road {author="I. Zango Martín" year=1998} ``` Die Klammern und ihr Inhalt werden aus dem Text der Überschrift entfernt (der Titel oben erscheint als *The Long Road*) und an der Überschrift als `attrs` gespeichert. Gestaltungsfelder erhalten sie als Platzhalter `{attr.}`: im erweiterten Gestaltungsfeld der Überschrift selbst sowie in Kopf- und Fußzeilen, wo sie aus der H1 des aktuellen Kapitels aufgelöst werden. Erkannt wird nur ein ausgewogener Block ohne innere Klammern ganz am Zeilenende, nach einem Leerzeichen oder, da chinesische Titel ohne Leerzeichen geschrieben werden, direkt nach einem chinesischen oder japanischen Zeichen (`# 回目{style="x"}`). Der Block wird nur übernommen, wenn die unten beschriebene Attributsyntax ihn vollständig liest: `{x, y}`, `{紅樓|hóng lóu}` und ein einzelnes `{}` bleiben im Titel, ebenso einzelne Schalter, die direkt am Titel kleben (`# 第一回{draft}`). Attribute werden durch Leerzeichen getrennt, daher bleiben auch ein Block mit Kommas (`{a="1", b="2"}`) und Pandocs `{.class}` im Titel. Pandocs Bezeichner `{#id}` wird gelesen: Er entspricht `id="…"` und benennt die Überschrift für [Querverweise](https://postext.dev/de/docs/document-format.md#querverweise-und-anker). Ein in einer anderen Schrift geschriebener Schlüssel wird gelesen und mit einer Warnung verworfen (siehe unten), sodass `# 回目{style="x" 作者=曹雪芹}` dennoch `style` übernimmt. Siehe **Konfiguration → Kopf- und Fußzeilen**. Ein Wert, den ein Gestaltungstext druckt, kann sich über mehrere Zeilen erstrecken: Die beiden Zeichen `\n` beginnen dort eine neue Zeile, unabhängig vom `overflow` des Elements (`to="Firma X\nStrasse 1\n10115 Berlin"` druckt eine dreizeilige Anschrift). Mit `inlineMarks` am Element gelten auch Inline-Auszeichnungen im Wert: `authors="Ana Ruiz^1^, Luis Gil^2^"` setzt die Nummern der Affiliationen hochgestellt. Diese Escape-Sequenz gehört zu Attributwerten (und zu den eigenen Vorlagen der Gestaltung): Die Zeichen `\n` im Text einer Überschrift, etwa in einem Code-Span, werden so gedruckt, wie sie geschrieben sind. Zwei Attribute haben eine eigene Bedeutung. `style=""` wendet ein benanntes [Überschriftenstil](https://postext.dev/de/docs/configuration-styles.md#überschriftenstile) auf die Überschrift an – ein Vorwort oder eine Autorenliste mit eigener Auftaktgestaltung, eigenen Kolumnentiteln, eigener Seitengeometrie und eigener Typografie des Fließtexts und ohne Kapitelnummer, wenn das Format `numbered: false` angibt. `toc="false"` (oder `"true"`) legt abweichend fest, ob `:::toc` die Überschrift aufführt: ```markdown # Preface {style="front-matter"} # Contents {style="front-matter" toc="false"} ``` Zwei weitere ändern, was eine Überschrift druckt und wie sie zählt. `hidden="true"` (oder `"false"`) überschreibt das `hidden` der Ebene oder des Formats der Überschrift: Eine verborgene Überschrift druckt nichts und nimmt keinen Platz ein – im Fluss wie in einem Kasten `:::callout` –, öffnet aber weiterhin ihre Seite, zählt mit und erscheint im Inhaltsverzeichnis, in den Kolumnentiteln `{chapterTitle}` und in den PDF-Lesezeichen. `jidori=N` verteilt eine einzeilige Überschrift gleichmäßig auf `N` ihrer eigenen Zeichen (字取り: `# 序章 {jidori=3}` druckt 序　章), und `jidori=0` schaltet die gleichmäßige Verteilung ab, die ihre Ebene oder ihr Format setzt (siehe [Konfiguration › Überschreibungen pro Ebene](https://postext.dev/de/docs/configuration-text.md#überschreibungen-pro-ebene)). `indent=N` rückt eine einzelne Überschrift um `N` Zeichen des Fließtexts vom Zeilenanfang ein (字下げ: `## 一 {indent=5}`), vorrangig vor dem `indent` ihrer Ebene oder ihres Formats; eine bloße Zahl zählt Gevierte des Fließtexts, `0` setzt die Überschrift an den Zeilenanfang, und es wirkt in senkrechtem und waagerechtem Text gleich. `firstLineIndent=N` rückt nur die erste Zeile einer einzelnen Überschrift ein, vorrangig vor dem `firstLineIndent` ihrer Ebene oder ihres Formats, während ihre übrigen Zeilen dort beginnen, wo `indent` sie hinsetzt (die Überschriften nach GB/T 9704: `## 关于加强管理的通知 {firstLineIndent=2}`); es liest Längen wie `indent`, und `0` hebt den Einzug der Ebene auf. `startAt=N`, eine positive ganze Zahl, setzt den Ebenenzähler der Überschrift auf `N`, statt ihn weiterzuzählen; die folgenden Überschriften zählen von dort aus weiter, auch in späteren Kapiteln, und die Ebenen darunter beginnen wie üblich unter ihr neu. Mit einem Überschriftenformat, das Anhänge mit Buchstaben zählt (`numberingTemplate: 'Appendix {1:A}'`), beginnt der erste Anhang die Zählung neu, sodass er *Appendix A* lautet, statt an die Kapitel anzuschließen: ```markdown # To my mother {hidden="true" toc="false"} # Survey instrument {style="appendix" startAt=1} # Raw data {style="appendix"} ``` ### Initialen Ein Absatz beginnt mit einer Initiale, wenn die Ebene oder das Format seiner Überschrift oder das Absatzformat seiner Gruppe `:::paragraphs` eine vorsieht (siehe [Konfiguration › Initialen](https://postext.dev/de/docs/configuration-text.md#initialen)): Der erste Buchstabe wird groß neben die ersten Zeilen gesetzt, die um ihn herum verkürzt werden. Im Absatz selbst steht keine Auszeichnung; der Text wird wie gewohnt geschrieben, und der Buchstabe bleibt beim Kopieren, bei der Suche und in der Source-Map Teil seines Worts. Ein Attribut `dropcap` schaltet sie für ein Kapitel oder eine Gruppe um: ```markdown # Lost {dropcap=false} # The mines {dropcap=2} :::paragraphs{style="entry" dropcap} The lamp of the first entry opens with an initial. ::: ``` In einer Überschriftenzeile lässt `dropcap=false` den Absatz nach dieser Überschrift ohne die Initiale, die ihre Ebene oder ihr Format vorsieht, `dropcap=N` setzt sie über `N` Zeilen, und ein bloßes `dropcap` gibt diesem Absatz eine Initiale (drei Zeilen, in der Schrift des Absatzes), wo die Ebene keine setzt. An einem Direktivenblock `:::paragraphs` bewirkt das Attribut dasselbe für den ersten Absatz der Gruppe oder für jeden Absatz, wenn das Format `each: true` angibt. Der Absatz nach einer Überschrift wird über Direktiven- und Codeblöcke, Direktiven, aus dem Fluss gelöste Kästen und gleitende Abbildungen hinweg gefunden; ein Absatz in einem Kasten, einem Listeneintrag, einem Zitat oder einem Gedicht erhält nie eine Initiale. Seit postext 1.23. ### Codeblöcke Ein Listing steht in einem Codeblock zwischen zwei Zeilen aus drei oder mehr Backticks (oder drei oder mehr Tilden), jede für sich allein, um höchstens drei Leerzeichen eingerückt. Alles dazwischen bleibt so, wie es geschrieben ist: führende Leerzeichen und Folgen von Leerzeichen, Tabulatoren, Leerzeilen und Zeilen, die mit `#`, `-`, `1.`, `>`, `$` oder `:::` beginnen. Nichts darin wird als Markdown gelesen: keine Hervorhebung, kein `:ref`, keine Formeln, keine Chips, keine Direktiven, keine Überschriften. Die schließende Zeile verwendet das Zeichen der öffnenden und ist mindestens ebenso lang; ein Listing, das einen Codeblock zeigt, steht daher in einem längeren oder in Tilden: ~~~markdown ```bash {title="backup.sh" lineNumbers start=12 highlight="3,5-7"} #!/usr/bin/env bash # Copy the photos to the backup disk rsync -a --delete ~/Photos/ /Volumes/Backup/Photos/ echo "done: $(date)" ``` ~~~ Die Info-Zeichenkette nach der öffnenden Zeile des Codeblocks nennt die Sprache (ihr erstes Wort: `js`, `ts`, `python`, `bash`, `console`, `json` …), und der Rest wird in der [Attributsyntax](https://postext.dev/de/docs/document-format.md#attributwerte) als Attribute gelesen, in geschweiften Klammern oder ohne (`title="app.js" lineNumbers`). Alles andere nach der Sprache ist der Titel: ```` ```console Terminal ```` und ```` ```python normalize.py ```` drucken *Terminal* und *normalize.py* über dem Listing. | Attribut | Wirkung | | --- | --- | | `title="…"` | Ein Titel über dem Listing, in einer Titelzeile (oder in einem Etikett am Rand des Kastens, wenn `codeStyle.label` gesetzt ist). | | `label="…"` | Der Text des Etiketts am Kasten, wie bei einem `:::callout` (mit `codeStyle.label`). | | `lineNumbers`, `lineNumbers=false` | Nummeriert die Zeilen dieses Listings (oder nicht), unabhängig von `codeStyle.lineNumbers`. Die Nummern stehen in einer Randspalte vor dem Code und werden nicht mitkopiert. | | `start=N` | Die Nummer der ersten Zeile (nummeriert das Listing, wenn nichts anderes es tut). | | `highlight="3,5-7"` | Tönt die genannten Zeilen (gezählt ab der ersten Zeile des Listings, beginnend bei 1): einzelne Zeilen und Bereiche, durch Kommas getrennt. | | `span=page` | Auf einer mehrspaltigen Seite erstreckt sich das Listing über alle Spalten. | Ein Codeblock beendet den Absatz darüber, ob mit oder ohne Leerzeile, und der Text nach seiner schließenden Zeile beginnt einen neuen Absatz. Ein offen gelassener Codeblock reicht bis zum Ende des Texts und wird gemeldet (`unclosedCodeBlock`). Ein Codeblock in einem `:::callout` ist ein darin verschachtelter Kasten; in `:::paragraphs` behält das Listing das Code-Format, nicht das Absatzformat. Postext kennt keine Fortsetzung von Listeneinträgen, daher schließt ein Codeblock nach einem Listeneintrag die Liste. Registermarken und Anker, die in einem Listing stehen, bleiben so, wie sie geschrieben sind. Eingerückter Code (vier Leerzeichen oder ein Tabulator nach einer Leerzeile) wird nur dann als Listing gelesen, wenn `codeStyle.indentedCode` eingeschaltet ist: Postext-Texte rücken oft mit Leerzeichen ein, und verschachtelte Listeneinträge lesen führende Leerzeichen. Wie ein Listing aussieht (seine Schrift, sein Kasten, die Tabulatorbreite, was mit einer Zeile geschieht, die breiter ist als der Kasten, Zeilennummern, die Farben seiner Token), legt `codeStyle` fest; siehe [Konfiguration › Code-Listings](https://postext.dev/de/docs/configuration-styles.md#code-listings). Inline-Code (`` `x` ``) bleibt in der Schrift des Texts, sofern `codeStyle.inline` ihm keine eigene gibt. Ein vor postext 1.23 gespeichertes Buch mit Codeblöcken im Text liest diese wie damals als Markdown (`codeStyle.blocks: false`). Seit postext 1.23. ## Direktiven Direktiven sind einzeilige Steuerbefehle, die als `:::name` oder `:::name{attrs}` auf einer eigenen Zeile stehen. Sie erzeugen keine sichtbare Ausgabe – sie steuern die Platzierung und die Nummerierung. | Syntax | Wirkung | | --- | --- | | `:::pagebreak` | Der nächste Block beginnt auf einer neuen Seite. | | `:::pagebreak{parity="odd"}` | Ebenso, und die neue Seite ist zudem ungerade (rechte Seite). Fügt bei Bedarf eine leere Füllseite ein. | | `:::pagebreak{parity="even"}` | Ebenso, aber mit einer geraden (linken) Seite als Ziel. | | `:::pagebreak{parity="always-odd"}` | Garantiert mindestens eine verpflichtende leere Trennseite, bevor eine ungerade Seite erreicht wird. Die leere Trennseite gehört zum vorangehenden Inhalt, jede weitere Füllseite für die Parität zum folgenden. Nützlich, wenn jedes Kapitel auf einer neuen Doppelseite beginnen muss. | | `:::pagebreak{parity="always-even"}` | Ebenso, aber mit einer geraden Seite als Ziel. | | `:::numbering{format="decimal" startAt=1}` | Wechselt an der nächsten Seitengrenze die Folge der Seitenzahlen. Beide Attribute sind optional – ohne `format` bleibt das Format erhalten, ohne `startAt` zählt der Zähler weiter. | | `:::columnbreak` | Beendet die aktuelle Spalte an dieser Stelle: Der nächste Block beginnt in der nächsten Spalte derselben Seite (oder auf einer neuen Seite, wenn die Direktive in der letzten Spalte steht). In einer leeren Spalte wirkungslos, sodass nie eine leere Spalte oder Seite entsteht. Die beendete Spalte behält ihren Leerraum am Fuß – der Spaltenausgleich dehnt sie nicht. | | `:::space` | Lässt an dieser Stelle eine leere Zeile des Grundtexts frei – der ausdrückliche Weg, zwischen zwei Blöcken etwas Luft zu schaffen. `:::space{lines=2}` lässt zwei frei (auch Bruchteile wie `0.5` sind möglich). Der Raum kommt zum Abstand zwischen den Blöcken hinzu und entfällt am Kopf einer Spalte oder Seite. Siehe [unten](https://postext.dev/de/docs/document-format.md#space). | | `:::toc` | Setzt hier das Inhaltsverzeichnis: ein Eintrag je Überschrift der aufgeführten Ebenen (Titel, Nummer, Seitenzahl, wahlweise die Autoren des Kapitels) und eine Zeile je Teiltitel, gesetzt nach der Konfiguration `toc`. Die Einträge folgen dem Dokument – wird ein Kapitel umbenannt, verschoben oder neu nummeriert, folgt das Verzeichnis. | | `:::index` | Setzt hier das Register: jeden im Buch mit `:index` ausgezeichneten Begriff, sortiert und nach Buchstaben gruppiert, mit den Seiten, auf denen er vorkommt, gesetzt nach der Konfiguration `index`. `:::index{index="names"}` setzt ein benanntes Register. Siehe [Register](https://postext.dev/de/docs/document-format.md#register). | | `:::page{…}` … `:::` | Eine Comicseite: ihre Zeilen `::panel` und deren Skriptzeilen, gesetzt als Panels und geletterte Sprechblasen auf einer eigenen Seite. Siehe [Comics](https://postext.dev/de/docs/document-format.md#comics). | | `:::strip{…}` … `:::` | Ein Comicstrip im Textfluss, so breit wie eine Spalte oder eine Seite. Siehe [`:::strip`](https://postext.dev/de/docs/document-format.md#strip). | | `:::verse` … `:::` | Ein Gedicht, Zeile für Zeile so gesetzt, wie es geschrieben ist (jede Zeile ein Vers, Leerzeilen zwischen den Strophen, führende Leerzeichen als Einzug), oder im klassischen arabischen Layout, wenn seine Zeilen die Halbverse mit `\|\|` trennen. Siehe [unten](https://postext.dev/de/docs/document-format.md#verse). | Attributwerte können in doppelten (`"…"`) oder einfachen Anführungszeichen (`'…'`) stehen oder ohne (`startAt=17`). Ein Schlüssel ohne `=` gilt als gesetztes, aber leeres Flag. Derzeit werden nur `pagebreak`, `numbering`, `columnbreak`, `space`, `toc` und `index` als einzeilige Direktiven erkannt (und `references`, `verse`, `page` und `strip` als Direktivenblöcke) – jede andere Zeile `:::name`, die kein Container ist (siehe unten), wird als Absatz gelesen und löst in der Sandbox die Warnung **Unbekannte Direktive** aus. Auch die Engine vermerkt sie, als Eintrag `unknownDirective` in den `contentWarnings` des Dokuments (siehe [Konfiguration › Warnungen im Dokument](https://postext.dev/de/docs/configuration-programmatic-usage.md#warnungen-im-dokument)). ### Attributwerte Dieselbe Syntax `key="value"` lesen Attribute von Überschriften, Direktivenblöcke von Direktiven und Containern (`:::name{…}`), Querverweise im Text (`:ref{…}`), Chips (`:chip[…]{…}`), Farbfelder (`:swatch{…}`) und Registermarken (`:index[…]{…}`). Es gelten folgende Regeln: - **Schlüssel** beginnen mit einem ASCII-Buchstaben oder `_` und setzen sich mit ASCII-Buchstaben, Ziffern, `_` oder `-` fort. Leerzeichen um `=` sind erlaubt, das vollbreite `＝`, das eine chinesische Eingabemethode tippt, wirkt wie `=`, ein wiederholter Schlüssel behält seinen letzten Wert, und ein Schlüssel ohne `=` ist ein Flag mit leerem Wert. Ein Schlüssel in einer anderen Schrift (`作者=曹雪芹`) wird nicht gelesen und löst die Warnung `attributeKeyInvalid` aus; die übrigen Schlüssel des Blocks gelten weiterhin. Werte dürfen in jeder Schrift stehen. - **Werte in Anführungszeichen.** Ein Wert in doppelten Anführungszeichen darf alles außer `"` enthalten, einfache Anführungszeichen eingeschlossen; ein Wert in einfachen alles außer `'`. Ein Wert mit doppelten Anführungszeichen steht also in einfachen: `lead='He said "hi"'`. Escape-Sequenzen gibt es nicht – ein Backslash ist ein gewöhnliches Zeichen –, daher nimmt ein Wert, der beide ASCII-Anführungszeichen braucht, typografische (`“…”`, `’`). Ein Wert darf auch mit dem typografischen `“` oder der Eckklammer `「` beginnen, die eine chinesische Eingabemethode tippt, und reicht dann, Leerzeichen eingeschlossen, bis zum passenden `”` bzw. `」`: `title=“甲戌本 眉批”`, `title=「脂批」`. - **Werte ohne Anführungszeichen** (`startAt=17`, `year=1998`) reichen bis zum nächsten Leerzeichen: `title=Hello world` ergibt `title="Hello"` und dazu ein Flag `world`. - **Keine geschweiften Klammern.** `{` und `}` stehen nie in einem Wert. Die erste `}` beendet den Block: Ein Direktivenblock, dessen Wert eine enthält, ist keine Direktive mehr, sondern ein Absatz, und im Fließtext läuft der Rest des Werts in den Text über. In einer Überschrift bleibt bei einer Klammer in einem Wert der ganze Block im Titel: `# Title {note="a {b"}` wird so gesetzt, wie es geschrieben ist. (Bis postext 1.8 begann ein `{` nach einem Leerzeichen den Block neu, und `b` wurde als Flag gelesen.) - **Dollarzeichen sind gewöhnlicher Text.** Attribute werden vor den Formeln im Text gelesen, daher ist `lead="from $5 to $6"` einfach Text. - **Eine Zeile.** Ein Attributblock erstreckt sich nie über mehrere Zeilen. ```markdown # The Long Road {lead='A "road novel", they said' price="$18"} :::callout{type="note" title='The "fast" path'} … ::: ``` `::resource{id="…"}` ist strenger: die ID in doppelten Anführungszeichen und kein weiteres Attribut (siehe [Ressourcen](https://postext.dev/de/docs/document-format.md#ressourcen)). ### Container Ein Container fasst eine Folge von Blöcken in einem Direktivenblock zusammen: eine öffnende Zeile `:::name` oder `:::name{attrs}`, danach beliebiger gewöhnlicher Inhalt – Absätze, Überschriften, Listen, Zitate, Formeln, sogar weitere Direktiven – und eine schließende Zeile, die nur `:::` enthält. Container lassen sich verschachteln; jedes schließende `:::` schließt den innersten offenen. ``` :::callout{type="note"} Keep the lantern lit **every** night. - Check the wick. - Trim it at dusk. ::: ``` Im Textfluss werden fünf Containernamen erkannt. Was jeder davon darstellt, legt ein eigener Abschnitt der Konfiguration fest: | Syntax | Wirkung | | --- | --- | | `:::callout{…}` … `:::` | Inhalt im Kasten – ein Hinweis, Tipp oder eine Warnung, vom Grundtext abgesetzt in einem umrandeten oder getönten Kasten. | | `:::paragraphs{…}` … `:::` | Eine Folge von Absätzen, die statt im Format des Grundtexts in einem benannten Absatzformat gesetzt werden (ein Vorspann, ein Motto, eine Reihe kleingedruckter Anmerkungen). `align`, `indent` und `endIndent` legen Ausrichtung und Einzüge fest, mit oder ohne Format: `:::paragraphs{align=end endIndent=1}` setzt ein Datum ein Zeichen vor dem Zeilenende (地から1字上げ). `dropcap` schaltet eine [Initiale](https://postext.dev/de/docs/document-format.md#initialen) für den ersten Absatz ein. | | `:::part{…}` … `:::` | Der Auftakt eines Teils oder Abschnitts: Die eingeschlossene Überschrift und der Text bilden die Auftaktseite eines Hauptteils. | | `:::paper{…}` … `:::` | Eine Folge von Seiten, die auf einem anderen Papier gedruckt werden, etwa ein Bildteil auf Glanzpapier in einem Buch auf mattem Papier. Nur der Betrachter Folio zeigt das an. | | `:::columns{…}` … `:::` | Blöcke in eigenen Spalten: in einem Kasten, in der Textspalte oder über eine Seite mit mehreren Spalten hinweg. Siehe [`:::columns`](https://postext.dev/de/docs/document-format.md#columns) unten. | Welche Attribute jeder Container annimmt und wie er gestaltet wird, beschreibt die [Konfiguration](https://postext.dev/de/docs/configuration.md). Attributwerte folgen derselben Grammatik wie bei Direktiven. Ein Direktivenblock `:::callout` nimmt `type` (die ID eines konfigurierten Kastenformats – unbekannte oder fehlende Typen fallen auf das erste Format zurück), `title` (ersetzt den Standardtitel des Formats) sowie `span` / `placement` (`column`, `page` oder `side`; `here`, `top`, `bottom` oder `fixed`), um Ausdehnung und Position des Formats für diesen Kasten zu überschreiben: ``` :::callout{type="objectives" title="What you will learn" span="page" placement="top"} - Name the parts of the lantern. - Trim the wick without touching the glass. ::: ``` Ein gleitender Kasten (`placement` `auto`, `top` oder `bottom`) nimmt außerdem `columns` an, die Zahl der benachbarten Spalten, über die er sich auf einer mehrspaltigen Seite erstreckt, wie in `:::callout{placement="top" columns="2"}` (seit postext 1.18). Ein Kasten kann den Text nach ihm auch neben sich laufen lassen: `wrap` (`left`, `right`, `start` oder `end`), `width` (sein Anteil an der Spalte, 0 bis 1; ohne Angabe `layout.wrap.defaultWidth`) und `wrapGap` (eine Länge wie `6pt`), wie in `:::callout{wrap="right" width=0.4}` (siehe [Textumfluss](https://postext.dev/de/docs/document-format.md#textumfluss); seit postext 1.24). Ein Kasten wird als Box gesetzt – ein optionaler Titel, danach der Inhalt in der Grundtext- und Listentypografie des Formats. Standardmäßig bleibt er zusammen und wandert als Ganzes in die nächste Spalte oder auf die nächste Seite, wenn er nicht passt (ein Kasten, der höher ist als eine ganze Spalte, wird trotzdem geteilt, statt überzulaufen); ein Format mit `keepTogether: false` erlaubt die Teilung zwischen seinen Blöcken oder zwischen Zeilen, wobei auf jeder Seite des Schnitts mindestens `splitMinLines` Textzeilen bleiben – oder eine Abbildung, eine Tabelle, eine abgesetzte Formel bzw. ein verschachtelter Kasten (ein Schnitt innerhalb eines Absatzes oder Listenpunkts lässt zudem auf jeder Seite mindestens `layout.boxChildSplitMinLines` seiner Zeilen stehen: standardmäßig zwei, `splitMinLines`, wenn dieser Wert kleiner ist; vor 1.5 gespeicherte Bücher, deren Kapitel einen Kasten enthalten, werden mit 1 gelesen, dem Schnitt von 1.4). Jeder Teil nach dem ersten beginnt ohne das Symbol, wobei sein Text die Spalte des Symbols beibehält, und ohne den Titel, sofern das Format ihn nicht wiederholt (`repeatTitle`: „Key points (cont.)“); ein Format kann außerdem unter jeden Teil, der weitergeht, einen Vermerk „Fortsetzung“ setzen (`continuesMarkerEnabled`) – siehe [Hinweise an einem geteilten Kasten](https://postext.dev/de/docs/configuration-styles.md#hinweise-an-einem-geteilten-kasten). Kästen über die ganze Seitenbreite (`span="page"`) teilen die Seite in Spaltenbänder; Kästen mit `span="side"` verlassen den Fluss und wandern in die Randspalte eines anderthalbspaltigen Layouts, die nur Gleitobjekte aufnimmt (`layout.sideColumnRole: 'floats'`), gestapelt neben dem Text, den sie unterbrechen, und werden als Spaltenkästen gesetzt, wo es keine solche Spalte gibt; Kästen mit `placement="fixed"` verlassen den Fluss und werden an Seitenkoordinaten fixiert (etwa ein Selbsttest-Abzeichen in der unteren linken Ecke der letzten Seite eines Kapitels), wobei die überdeckten Spalten diesen Bereich freigeben; gleitende Kästen (`placement="top"` / `"bottom"`) verlassen den Fluss an ihrer Stelle und belegen das erste freie Band nach dieser Position – den Fuß der Seite oder Kopf bzw. Fuß der nächsten –, während der Text nach ihnen die verlassene Seite füllt. Ein Format mit `floatBarrier: true` (typischerweise der abschließende Kasten „Key points“ eines Kapitels) macht den Kasten zu einer **Gleitobjekt-Sperre**: Jede vor ihm referenzierte Abbildung oder Tabelle wird vor ihm platziert – in den freien Plätzen der Seite oder auf Seiten, die vor dem Kasten geöffnet werden –, sodass kein Gleitobjekt über das Ende seines Kapitels hinausrutscht. Ein unbekannter Direktivenblock `:::name` ist kein Container – die Zeile wird als Text behandelt, genau wie eine unbekannte Direktive. Ein Direktivenblock `:::part` nimmt `number` (so, wie die Nummer gedruckt werden soll – `"I"`, `"IV"`, `"3"`; sie wird zudem ausgewertet, damit die Gestaltung sie umformatieren kann) und `title`; beide sind optional. Ein drittes Attribut, `palette="band=#hex"` (mehrere Paare `id=#hex`, durch Kommas getrennt), färbt jede Gestaltungsfarbe um, die mit diesen Paletten-IDs verknüpft ist – Kolumnentitel, Auftaktband, Gestaltungen der Teile –, und die Farben des Textflusses mit demselben Grundwert (Überschriften, Fettes, Querverweise, Aufzählungszeichen, Legenden, Tabellen, Kästen, Chips), und zwar für den Teil und die folgenden Kapitel bis zum nächsten Teil; siehe [Konfiguration › Teile](https://postext.dev/de/docs/configuration-styles.md#teile). Der Container öffnet stets eine eigene Seite: davor ein Seitenumbruch mit der konfigurierten Parität, eine einzige Textspalte mit den Rändern `parts.margins`, die Auftaktgestaltung über die ganze Seite und nach der schließenden Zeile des Direktivenblocks ein weiterer Seitenumbruch. Der Inhalt – meist die Liste der Kapitel, die der Teil zusammenfasst, oder gar nichts – wird mit `parts.bodyStyle` gesetzt: ``` :::part{number="I" title="Foundations"} 1. The lantern and its parts 2. Trimming the wick ::: # The lantern and its parts ``` Mit den Standardeinstellungen für Überschriften ergibt das die klassische Folge: Teiltitelseite rechts, leere linke Seite, Kapitel auf der nächsten rechten Seite. Die Seite wird als `role: 'part'` gemeldet, damit Kopf- und Fußzeilen sie auslassen können, und `{partTitle}` / `{partNumber}` lösen sich auf jeder folgenden Seite in den aktuellen Teil auf. Siehe [Teile](https://postext.dev/de/docs/configuration-styles.md#teile) in der Konfigurationsreferenz. Vor einem Direktivenblock braucht es keine Leerzeile: Eine öffnende oder schließende Zeile eines Direktivenblocks direkt unter einem Absatz, einer Liste oder einem Zitat beendet diesen Block. Ein Container, der am Ende des Dokuments noch offen ist, wird dort automatisch geschlossen, und die Sandbox meldet die Warnung **Nicht geschlossener Container** mit Verweis auf die öffnende Zeile. Ein einzelnes `:::` ohne offenen Container bleibt als sichtbarer Absatz im Text, statt stillschweigend zu verschwinden. ### `:::columns` Eine Gruppe `:::columns{count=2}` … `:::` setzt die Blöcke innerhalb ihres Direktivenblocks in `count` gleich breiten Spalten (2 bis 6); der Text danach nimmt wieder die volle Breite ein. In einem `:::callout` teilen sich die Spalten die Innenbreite des Kastens, im Abstand `columnGap` des Formats, in der Grundtext- und Listentypografie des Kastens, und der Kasten wächst bis zur höchsten Spalte. Im laufenden Text (seit postext 1.25) teilen sie sich die Textspalte, eine Zeile des Grundtexts voneinander entfernt, und die Blöcke behalten die Typografie des Texts; mit `span="page"` auf einer mehrspaltigen Seite teilt die Gruppe die Seite in ein Band, wie es ein Kasten über die ganze Seitenbreite tut: Die Spalten darüber schließen auf gleicher Höhe, die Gruppe wird über die ganze Inhaltsbreite gesetzt (im Abstand des Spaltenabstands), und der Text läuft darunter in allen Spalten weiter. Auf einer einspaltigen Seite setzt `span="page"` sie in die Spalte. Überschriften in einer Gruppe behalten ihr Format, ihre Nummer und ihren Eintrag im Inhaltsverzeichnis, eine darin zitierte Fußnote kommt an den Fuß der Textspalte, und Abbildungen, auf die sie verweist, gleiten wie gewohnt. | Attribut | Wirkung | | --- | --- | | `count` | Zahl der Spalten, 2 bis 6. Standard: 2. | | `gap` | Der Abstand zwischen den Spalten, eine Länge (`12pt`, `1em`, `4mm`). Standard: `columnGap` des Kastenformats in einem Kasten, eine Zeile des Grundtexts in der Textspalte, `layout.gutterWidth` über die Seite. | | `rule` | Zieht in jedem Zwischenraum eine Linie in Farbe und Stärke von `layout.columnRule`: `:::columns{count=3 rule}`. | | `breaks` | Die Blöcke, mit denen jede Spalte nach der ersten beginnt, statt auszugleichen: `breaks="4"` beginnt die zweite Spalte mit dem vierten Block der Gruppe (eine Liste mit Kommas für weitere Spalten). Wie gezählt wird, steht weiter unten. | | `flow` | Wie eine Gruppe weiterläuft, die nicht passt: `snake` (Standard ohne `breaks`) oder `parallel` (Standard mit `breaks`). Siehe [Eine Gruppe teilen](https://postext.dev/de/docs/document-format.md#eine-gruppe-teilen). | | `span` | Nur im laufenden Text: `column` (Standard) oder `page`. | | `marginTop` | Der Abstand über der Gruppe, eine Länge wie bei `gap`. Er verschmilzt mit dem Abstand, der über der Gruppe ansteht; am Kopf einer Spalte oder wenn die Gruppe ihren Kasten eröffnet, entfällt er. Seit postext 1.28. | | `marginBottom` | Der Abstand unter der Gruppe, eine Länge; `0` verlangt keinen. Im laufenden Text tritt er an die Stelle des Absatzabstands des Grundtexts, in einem Kasten ist er der Abstand vor dem nächsten Block. Seit postext 1.28. | Eine Gruppe, die als Ganzes gesetzt wird, wird dort geschnitten, wo ihre Spalten am besten auf gleicher Höhe enden – zwischen Blöcken oder zwischen den Zeilen eines Absatzes oder Listenpunkts, dessen Rest am Kopf der nächsten Spalte ohne Aufzählungszeichen weiterläuft –, es sei denn, `breaks` legt die Spaltenanfänge fest, ohne Schnitt innerhalb eines Absatzes: eine Textspalte neben einer Abbildungsspalte. **Der Raum um eine Gruppe.** Im laufenden Text folgt auf eine Gruppe der Absatzabstand des Grundtexts (eine Zeile bei `bodyText.paragraphSpacing`, ohne ihn keiner), in einem Kasten kein eigener Abstand. `marginTop` und `marginBottom` am Direktivenblock legen ihn fest: `:::columns{count=3 span="page" marginBottom="0.75em"}`. Jeder ist ein Mindestwert, der mit dem Abstand verschmilzt, den der benachbarte Block für sich beansprucht, wie es die Ränder eines Kastens tun. Im laufenden Text kehrt der Fluss unter der Gruppe zum Grundlinienraster zurück, sodass der Abstand in ganzen Zeilen ausfällt, und eine auf Spalten oder Seiten verteilte Gruppe behält den oberen Abstand für ihren ersten und den unteren für ihren letzten Teil. Ein `em` ist die Größe des Texts, in dem die Gruppe steht; ein Wert, der keine Länge ist, oder ein negativer Wert wird ignoriert. ```md :::callout{type="summary"} :::columns{count=2} - Every element is one kind of atom. - Electrons live in orbitals. - A bond shares or transfers electrons. ::: ::: ``` **Wie `breaks` zählt.** `breaks` nummeriert die Blöcke der Gruppe der Reihe nach – Absätze, Listenpunkte (jeder ein Block), abgesetzte Formeln, Abbildungen und Tabellen –, und ein verschachteltes `:::callout` zählt als ein Block, gleich wie viele es enthält. Direktiven sind keine Blöcke: Ein `:::space` zwischen zwei Strophen verschiebt die Zählung nicht. Eine Zahl unter 2, eine jenseits des letzten Blocks der Gruppe oder eine, die nicht nach dem vorigen Umbruch liegt, wird ignoriert. In einer Gruppe trennt `:::space` zwei Blöcke wie überall in einem Kasten und entfällt am Kopf der Gruppe und am Kopf jeder ihrer Spalten (an einer Position aus `breaks` oder einem Ausgleichsschnitt) – um die Gruppe tiefer beginnen zu lassen, setzen Sie den Raum vor den Direktivenblock `:::columns`. Zwei Spalten mit denselben Abständen stehen daher Strophe für Strophe auf gleicher Höhe: ```md :::callout{type="verse"} :::columns{count=2 breaks="4"} The lamp is lit at dusk, and trimmed before the dawn. :::space The keeper sleeps by day. La lámpara se enciende al anochecer, y se despabila antes del alba. :::space El farero duerme de día. ::: ::: ``` Hier beginnt der vierte Block, „La lámpara…“, die zweite Spalte; die beiden Zeilen `:::space` werden nicht gezählt und lassen in beiden Spalten denselben Zwischenraum. #### Eine Gruppe teilen Seit postext 1.25 wird eine Gruppe, die nicht in den verfügbaren Raum passt – den Rest ihrer Spalte im laufenden Text oder den Teil eines Kastens, der geteilt wird (`keepTogether: false` oder ein Kasten, der höher ist als eine Spalte) –, zwischen ihren Spalten geschnitten und läuft in der nächsten Spalte oder auf der nächsten Seite weiter, bei einer Gruppe in einem Kasten in einem eigenen Kasten: - **`flow="snake"`**, der Standard ohne `breaks`: Die Blöcke der Gruppe laufen als eine Fahne durch, wie der Text eines Zeitungsartikels. Ein fortgesetzter Teil füllt seine Spalten nacheinander, so gleich hoch, wie es die Schnitte erlauben, und schneidet zwischen Blöcken oder zwischen den Zeilen eines Absatzes oder Listenpunkts (mindestens `layout.boxChildSplitMinLines` seiner Zeilen auf jeder Seite, standardmäßig zwei); der letzte Teil wird ausgeglichen wie eine ganze Gruppe. - **`flow="parallel"`**, der Standard mit `breaks`: Jeder Lauf, den die Umbrüche beginnen, ist ein Strom, der seine eigene Spalte behält. Ein Teil füllt jeden Strom bis zum verfügbaren Raum, und jeder läuft in derselben Spalte des nächsten Teils weiter, sodass ein Gedicht und seine nebeneinander gesetzte Übersetzung Strophe für Strophe auf gleicher Höhe bleiben. Eine parallele Gruppe ohne `breaks` läuft wie eine Snake-Gruppe als Fahne weiter. Ein verschachtelter Kasten in einer Gruppe bleibt ganz und wandert in den nächsten Teil, und eine Gruppe in einem verschachtelten Kasten wird nie geschnitten. Eine Gruppe, die passt, wird genau wie bisher gesetzt. `layout.flowColumns: false` behält die Regeln von postext 1.24 bei: Ein Direktivenblock außerhalb eines Kastens wird ignoriert, und eine Gruppe wird nie geschnitten; vor 1.25 gespeicherte Bücher mit einer Gruppe `:::columns` werden so gelesen. Die Sandbox meldet einen unbekannten Wert für `flow` (**Unbekannter Spaltenfluss**) und Spalten, die schmaler sind als sechs Geviert ihres Texts (**Spalten zu schmal**). ```md ## Briefs :::columns{count=3 span="page" rule} **Harbour.** The new pier opens on Monday… **Market.** Stall rents stay as they are… **Weather.** Rain from the west by the evening… ::: ``` Ein Direktivenblock `:::callout` nimmt außerdem `label="…"` an: den Text, den ein Format mit einem Reiter `label` an der oberen Ecke des Kastens druckt (`:::callout{type="box" label="BOX 1-1" title="The octet rule"}`). Ein `:::callout` in einem anderen ist ein eigener Kasten – etwa eine Arbeitsblattkarte mit Antwortkästen. Er nimmt sein eigenes Format an (Hintergrund, Rahmen, Radius, Innenabstand, Titel, Symbol) in der vollen Innenbreite des äußeren Kastens und reiht sich zwischen dessen übrige Blöcke ein; seine Angaben `span` und `placement` werden ignoriert, da ein verschachtelter Kasten stets innerhalb seines Elternkastens fließt. Jede schließende Zeile eines Direktivenblocks schließt den innersten noch offenen Kasten: ```md :::callout{type="card"} The statement of the exercise. :::callout{type="answer"} A white answer box with its own border and padding. ::: :::callout{type="answer"} A second answer box. ::: ::: ``` Wird der äußere Kasten auf Spalten oder Seiten verteilt (`keepTogether: false` oder höher als eine Spalte), wandert ein verschachtelter Kasten als Ganzes in das nächste Fragment, sofern sein eigenes Format nicht ebenfalls eine Teilung erlaubt; jedes Fragment zeichnet die Rahmen neu, die es enthält, und ein fortgesetzter verschachtelter Kasten verliert sein Symbol und seinen Titel, sofern sein Format ihn nicht wiederholt (`repeatTitle`). ### `:::paper` Ein Buch kann für eine Folge von Seiten das Papier wechseln: ein Bildteil auf gestrichenem Glanzpapier in einem Buch auf ungestrichenem Werkdruckpapier, eine Karteneinlage, einige Blätter getöntes Papier. Fassen Sie diesen Inhalt in einen Container `:::paper`: ```md :::paper{type=coatedGloss grammage=130} ## Plates ::resource{id="plate-1"} ::resource{id="plate-2"} ::: ``` Ein Papier umfasst ganze Bogen, daher beginnt der Inhalt des Direktivenblocks auf einer neuen Seite, und was auf das schließende `:::` folgt, ebenfalls. Ein Lauf am Ende des Dokuments hinterlässt danach keine leere Seite. Abbildungen und Tabellen, auf die innerhalb des Laufs verwiesen wird, werden platziert, bevor er endet. Jede Seite, die mit Inhalt aus dem Container gesetzt ist, trägt das Papier im Layout (`VDTPage.paper`, die Attribute so, wie der Direktivenblock sie schreibt); Seiten außerhalb tragen nichts. Der Betrachter Folio liest es und zeichnet diese Blätter mit Farbe, Oberfläche, Dicke und Steifigkeit des Papiers. Canvas-, PDF- und HTML-Ausgabe ignorieren es: Die Seiten werden wie alle anderen gesetzt und gedruckt. Die Attribute sind die der Einstellungen `folio.paper`, und alle sind optional. Was der Direktivenblock auslässt, folgt dem Papier des Dokuments und darüber hinaus den Standardwerten des Papiers: | Attribut | Wert | | --- | --- | | `type` | Die Papiersorte: `uncoated`, `bookWove`, `coatedMatte`, `coatedSilk`, `coatedGloss`, `bible`, `newsprint`, `cardStock`, `board`. Sie legt die Standardwerte der folgenden Attribute fest. | | `grammage` | Flächengewicht in g/m², eine Zahl über 0. Schwereres Papier ist dicker, steifer und undurchsichtiger. | | `bulk` | Dicke je Gewicht in cm³/g, eine Zahl über 0 (Dicke in µm = Grammatur × Volumen). | | `finish` | Die Oberfläche: `auto`, `uncoated`, `matte`, `silk`, `gloss`. | | `texture` | Das Relief der Oberfläche: `auto`, `smooth`, `vellum`, `wove`, `laid`, `linen`, `felt`. | | `textureStrength` | Wie stark die Struktur sichtbar ist, von 0 bis 2. | | `shade` | Die Farbe des Papiers: `#rgb`, `#rrggbb` oder die ID eines Eintrags in `colorPalette`. | | `showThrough` | `true` oder `false`: ob die Rückseite schwach durchscheint. Ein bloßes `showThrough` bedeutet `true`. | Ein `:::paper` in einem anderen überschreibt nur die Attribute, die es setzt, und beginnt und endet ebenfalls mit einem Seitenumbruch. In einem `:::callout` werden die Direktivenblöcke ignoriert. Ein Wert, den die Engine nicht lesen kann, wird verworfen, und die Sandbox führt ihn als Warnung **Ungültiges Papierattribut** auf (`paperAttributeInvalid` in den `contentWarnings` des Dokuments). ### `:::pagebreak` Die Direktive selbst erzwingt keine Parität – nur das Layout des nächsten Blocks. Verwenden Sie sie, um ein Vorwort zu beenden, eine Widmung auf eine eigene Seite zu setzen oder das Ende eines Abschnitts zu markieren. Sollen an derselben Stelle ein Seitenumbruch und ein Neubeginn der Nummerierung stehen, schreiben Sie `:::pagebreak` gefolgt von `:::numbering` – der Wechsel der Nummerierung gilt dann auf der neuen Seite, die `:::pagebreak` gerade erzeugt hat. Ein Seitenumbruch auf einer noch leeren Seite bewirkt nichts und fügt daher nie eine leere Seite hinzu. Er ersetzt auch nicht das `breakBefore` einer unmittelbar folgenden Überschrift (Ebene 1 hat standardmäßig eines): Die Überschrift wendet ihre Parität trotzdem an, was nach der von der Direktive geöffneten Seite eine leere Seite hinzufügen kann. Soll eine Überschrift genau dort beginnen, schalten Sie ihren Umbruch aus (siehe **Konfiguration → Überschriftenstile**). Nach einer Titelüberschrift, die ihre Seite füllt, ist der Umbruch optional: Der Titel beansprucht den Rest seiner Seite bereits, in ein- wie mehrspaltigen Layouts, und ein `:::pagebreak` direkt danach schadet nicht. Nötig ist er nur nach einem Titel, dessen Gestaltung vor dem Seitenfuß endet, wenn der Text trotzdem auf der nächsten Seite beginnen soll (siehe **Konfiguration → Reservierte Höhe**). ```md The old chapter ends here. :::pagebreak{parity="odd"} # A new chapter ``` Das Flag `center` (`:::pagebreak{center}`, aus mit `center=false`) zentriert den Text der Seite, die der Umbruch öffnet, zwischen Kopf und Fuß des Satzspiegels, in vertikalem Text quer über die Seite: das ページの左右中央 eines japanischen Teiltitels oder einer Widmung. Gleitobjekte, Anmerkungen und Kolumnentitel bleiben, wo sie sind, und eine bereits volle Seite bleibt unberührt. Das Flag beendet die Seite nicht: Schließen Sie sie mit einem weiteren `:::pagebreak`. ```md :::pagebreak{center} # 上　先生と私 :::pagebreak ``` #### Das Attribut parity Das Attribut `parity` nimmt dieselben fünf Werte an wie `headings.levels[*].breakBefore.parity`: - `'any'` – der Standard: keine Paritätsvorgabe; der Umbruch öffnet einfach eine neue Seite. - `'odd'` / `'even'` – die neue Seite beginnt auf der verlangten Seite der Doppelseite; eine einzelne leere Seite wird nur eingefügt, wenn die natürliche nächste Seite auf der falschen Seite liegt. - `'always-odd'` / `'always-even'` – garantiert mindestens eine verpflichtende leere Trennseite zwischen dem vorigen Inhalt und der neuen Seite und erzwingt dann die Parität. Die leere Trennseite gehört zum **vorigen** Kapitel; jede weitere Füllseite für die Parität gehört zu dem, was folgt. #### Zugehörigkeit leerer Seiten Die beiden Arten leerer Seiten, die `:::pagebreak` (und `breakBefore`) einfügen können, werden im Modell `VDTPage` unterschieden: - `blankForParity: true` – eingefügt, um eine Paritätsvorgabe zu erfüllen. In Kopfzeilen mit `{chapterTitle}` trägt diese Seite den Titel des **kommenden** Kapitels, denn die leere Seite existiert nur, um dieses Kapitel auf die richtige Seite zu schieben. - `blankForForce: true` – die verpflichtende vorangestellte Trennseite eines Modus `'always-*'`. Sie gehört zum **vorigen** Kapitel – eine bewusste Atempause am Kapitelende, keine Füllseite für die Parität des nächsten Kapitels. Dieselben beiden Regeln geben einer leeren Seite die Kolumnentitel und die Palette eines gestalteten Abschnitts – siehe [Konfiguration › Überschriftenstile](https://postext.dev/de/docs/configuration-styles.md#überschriftenstile). #### Ausnahme am Dokumentanfang Ist `:::pagebreak` das allererste Element eines Dokuments (oder würde eine Überschrift mit `breakBefore` einen solchen Umbruch auslösen), wird die Parität nicht erzwungen, solange die erste Seite noch leer ist. Der nächste Block landet wie geschrieben auf Seite 1, unabhängig von der verlangten Parität – keine überflüssige leere Seite am Anfang. ### `:::numbering` Mit `:::numbering` beginnen Sie den Seitenzähler mitten im Dokument neu. Das klassische Buchbeispiel: ```md --- title: "A Book With Front Matter" --- # Preface … :::pagebreak{parity="odd"} :::numbering{format="decimal" startAt=1} # Chapter 1 ``` Die Seiten des Vorworts tragen `i`, `ii`, `iii`, …; das erste Kapitel beginnt auf einer rechten Seite mit der Zahl `1`. Änderungen nur des Formats (ohne `startAt`) lassen den Zähler weiterlaufen – nützlich etwa, um von `lower-alpha` zu `upper-alpha` zu wechseln, ohne neu zu zählen. `format` nimmt jede Schreibweise eines Nummerierungsformats an – `roman-lower` und `i` funktionieren ebenso wie `lower-roman`, `arabic` ebenso wie `decimal`, `一` und `あ` ebenso wie `japanese-informal` und `hiragana` (siehe [Konfiguration › Schreibweisen der Nummernformate](https://postext.dev/de/docs/configuration-page-layout.md#schreibweisen-der-nummernformate)). Ein Wert, der keiner davon ist, lässt das Format unverändert, und die Sandbox markiert ihn. `lines` beginnt die Zählung der [Zeilennummern](https://postext.dev/de/docs/configuration-notes-references.md#zeilennummern) neu, nicht den Seitenzähler: Die nächste gezählte Zeile erhält die angegebene Nummer, gleich was `lineNumbers.restart` vorgibt. Ein Wert, der keine ganze Zahl ab 0 ist, wird ignoriert. ```md ## Act II :::numbering{lines=1} ``` ### `:::space` `:::space` lässt vertikalen Raum zwischen zwei Blöcken: um eine Schlusszeile vom Text darüber abzusetzen, ein Motto oder eine Unterschrift etwas tiefer zu rücken oder einen *Leerraum* (Szenenwechsel) zwischen zwei Textpassagen zu öffnen. Zusätzliche Leerzeilen im Markdown leisten das nicht – wie in jedem Markdown ist eine Folge von Leerzeilen nur ein einziger Absatztrenner, damit sich das Layout eines Dokuments nicht ändert, wenn ein Editor oder Formatierer Leerraum hinzufügt oder entfernt. ```md The last paragraph of the scene. :::space A new scene begins one line lower. :::space{lines=2} Two lines lower still. ``` - **`lines`** – wie viel Raum, in Zeilen des Grundtexts (dem Grundlinienraster). Standard: `1`. Ganze Zahlen halten jede Textzeile auf dem Raster, sodass die Spalten weiterhin über die Seite hinweg registerhaltig stehen; ein Bruchteil (`lines=0.5`) wird exakt eingehalten, auf Kosten dieser Ausrichtung bis zum nächsten Block, der am Raster einrastet. Ein Wert, der keine Zahl größer als 0 und höchstens 20 ist, fällt auf eine Zeile zurück, und die Sandbox markiert ihn (**Ungültige Abstandsgröße**). - **Er addiert sich.** Der Raum kommt zum Abstand hinzu, der die beiden Blöcke bereits trennt – dem oberen Abstand einer Überschrift, dem unteren einer Liste –, statt darin aufzugehen. Zwei Zeilen `:::space` hintereinander ergeben zwei Zeilen. - **An einem Umbruch entfällt er**, wie `\vspace` in LaTeX: Am Kopf einer Spalte oder Seite verschwindet er, sodass eine Seite nie mit einem Loch beginnt; und passt er am Fuß einer Spalte nicht mehr, beendet er einfach diese Spalte, ohne den Rest mitzunehmen. - **Der Absatz danach beginnt stumpf.** Ist `bodyText.indentAfterHeading` ausgeschaltet, verliert ein Absatz direkt nach `:::space` seinen Erstzeileneinzug, wie nach einer Überschrift – die übliche Konvention für Text, der nach einer Leerzeile wieder einsetzt. - **In einem Kasten** (oder einer Gruppe `:::columns`) trennt er die Kinder des Kastens auf dieselbe Weise, gemessen in den Grundtextzeilen des Kastens. Vor dem ersten Block des Kastens entfällt er, wie am Kopf einer Spalte – der Innenabstand setzt den Inhalt bereits vom Rahmen ab –, außer in zwei Fällen, in denen er entsprechend Raum öffnet: direkt unter dem Titel des Kastens und in einem Kasten, der sonst nichts enthält (ein Antwortkasten, ein Schreibfeld, bemessen in Zeilen). Am Kopf einer Gruppe `:::columns`, am Kopf jeder ihrer Spalten und am Anfang des Teils eines geteilten Kastens, der in der nächsten Spalte oder auf der nächsten Seite weitergeht, verschwindet er immer. In einem Container `:::paragraphs` wirkt er wie zwischen Absätzen des Grundtexts. - **Das Zusammenhalten mit dem Folgenden** zählt ihn mit: Eine Überschrift, auf die `:::space` folgt, wandert weiter, wenn der Raum und die ersten Zeilen ihres Texts nicht darunter passen. Der Antwortkasten eines Arbeitsblatts ist ein Kasten, dessen einziger Inhalt Raum ist: die Frage im Titel, darunter Platz für vier Zeilen. ```md :::callout{type="answer" title="1. Name the three parts of the lantern."} :::space{lines=4} ::: ``` Für einen festen Umbruch statt Raum verwenden Sie `:::columnbreak` oder `:::pagebreak`. ### `:::verse` Ein Gedicht. `:::verse` setzt es in einem von zwei Layouts: **Zeile für Zeile**, wie die meisten Gedichte gedruckt werden, oder im **klassischen arabischen Layout** einer Qaṣīda, jeder Bayt in zwei nebeneinanderstehenden Halbversen. Ein Gedicht, dessen Zeilen ein Trennzeichen für Halbverse tragen (`||` oder ein von Leerzeichen umgebenes `\\`), erhält das arabische Layout, jedes andere das Zeilenlayout; `layout=lines` oder `layout=bayt` am Direktivenblock legt eines fest. #### Zeile für Zeile Schreiben Sie das Gedicht so, wie es gedruckt wird: ein Vers je Markdown-Zeile, eine Leerzeile zwischen den Strophen und Leerzeichen vor einer Zeile, um sie einzuziehen. ```md :::verse Whose woods these are I think I know. His house is in the village though; He will not see me stopping here To watch his woods fill up with snow. My little horse must think it queer To stop without a farmhouse near ::: ``` - **Zeilen.** Jede nicht leere Zeile ist ein Vers und wird für sich als Inline-Markdown gelesen: Kursive, Kapitälchen, Anmerkungen und Querverweise funktionieren. Eine Folge von Leerzeilen ist ein einziger Strophenwechsel. - **Einzüge.** Jedes führende Leerzeichen ist `indentStep` breit, standardmäßig 0,5 em, sodass zwei Leerzeichen eine Zeile um ein Geviert einziehen; ein Tabulator zählt als vier Leerzeichen, ein ideografisches Leerzeichen (U+3000) als zwei. - **Überläufe.** Eine Zeile, die etwas breiter ist als die Satzbreite, verringert zuerst ihre Wortabstände, bis auf `bodyText.minWordSpacing` ihrer natürlichen Breite (die Grenze, bis zu der Blocksatz staucht), und bleibt auf einer Zeile; `tighten=false` am Direktivenblock oder `bodyText.verse.tighten: false` bricht sie stattdessen um. Eine noch breitere Zeile wird an einem Wortzwischenraum umbrochen. Mit `turnover=hang` (Standard) hängt der Rest in der nächsten Zeile, um `hang` vom Anfang der eigenen Zeile eingerückt: den `hangingIndent` des Absatzformats des Gedichts, sonst 2 em (`bodyText.verse.hang`). Mit `turnover=right` wird er bündig mit dem Ende der Satzbreite gesetzt, hinter einer öffnenden eckigen Klammer (`turnoverMark`, standardmäßig `[`), wie in englischen und spanischen Ausgaben üblich. Verse werden nicht getrennt, es sei denn, ihr Absatzformat setzt selbst `hyphenation: true`. Eine Zeile und ihr Überlauf werden an einem Spalten- oder Seitenumbruch nie getrennt. - **Strophen.** Der Abstand zwischen zwei Strophen beträgt eine Zeile des Zeilenabstands des Gedichts; `stanzaSpace=0.5` macht daraus eine halbe Zeile, und eine Länge (`stanzaSpace=6pt`) legt ihn genau fest. Auf dem Grundlinienraster ergibt er ganze Rasterzeilen. Spalten und Seiten brechen bevorzugt zwischen Strophen um; innerhalb einer Strophe gelten die Regeln für Waisen und Witwen, die dann die Zeilen der Strophe zählen. `keepStanzas=N` hält jede Strophe mit N oder weniger Zeilen zusammen: ein Haiku nimmt `keepStanzas=3`, ein Tanka `keepStanzas=5`. - **Platzierung.** Das Gedicht wird anhand seiner längsten Zeile in der Satzbreite zentriert, jede Zeile bündig mit dem Anfang des Gedichts (`align=center`, die übliche Einstellung für ein in Prosa zitiertes Gedicht); `align=start` setzt es bündig mit dem Anfang der Satzbreite, der Standard in vertikalem Text. Der Absatz, der das Gedicht einleitet, hält seine letzte Zeile mit den ersten Versen zusammen. - **Gestaffelte Zeilen.** Eine als `+ …` geschriebene Zeile beginnt dort, wo die Zeile darüber endete, einen Wortzwischenraum weiter, wie ein Vers im Drama, den sich zwei Sprecher teilen. Schreiben Sie `\+` für eine Zeile, die mit einem Pluszeichen beginnt. - **Zäsuren.** Mit `keepSpaces` am Direktivenblock behält eine Folge von zwei oder mehr Leerzeichen innerhalb einer Zeile ihre Breite; ohne das fallen Leerzeichen wie in jedem Absatz zusammen. - **Schrift und Richtung.** `style` nennt ein Absatzformat, das Schriftart, Größe, Zeilenabstand, `indent` sowie den Abstand über und unter dem Gedicht bestimmt. `dir` und `lang` legen Richtung und Sprache fest: Ein lateinisches Gedicht in einem arabischen Buch (`dir=ltr`) wird von seiner eigenen Anfangsseite aus eingezogen. In vertikalem Text ist jeder Vers eine Spalte, eingezogen vom Kopf aus. | Attribut | Standard | Beschreibung | | --- | --- | --- | | `layout` | `auto` | `lines`, `bayt` oder `auto`: das Bayt-Layout, wenn eine Zeile ein Trennzeichen trägt. | | `indentStep` | `0.5em` | Breite eines führenden Leerzeichens. | | `turnover` | `hang` | `hang` oder `right`. | | `hang` | `hangingIndent` des Formats, sonst `2em` | Einzug eines hängenden Überlaufs vom Anfang seiner Zeile aus. | | `turnoverMark` | `[` | Das Zeichen vor einem rechtsbündig gesetzten Überlauf. | | `stanzaSpace` | `1` | Abstand zwischen Strophen: Eine bloße Zahl zählt Zeilen im Zeilenabstand des Gedichts, eine Länge ist genau diese Länge. | | `keepStanzas` | `0` | Strophen mit höchstens so vielen Zeilen zusammenhalten; 0 schaltet es aus. | | `tighten` | `true` | Die Wortabstände einer etwas zu breiten Zeile bis auf `bodyText.minWordSpacing` verringern, bevor sie umbrochen wird. | | `keepSpaces` | aus | Folgen von zwei oder mehr Leerzeichen innerhalb einer Zeile beibehalten. | | `align` | `center` (`start` in vertikalem Text) | Das Gedicht anhand seiner längsten Zeile zentrieren oder bündig mit dem Anfang setzen. | | `style`, `dir`, `lang` | — | Absatzformat, Richtung und Sprache des Gedichts. | | `numbered` | `true` | `false` nimmt das Gedicht von den Zeilennummern aus: Seine Zeilen werden nicht gezählt. | | `lineStart` | — | Die Zeilennummer der ersten Zeile des Gedichts. Dort beginnt die Zählung neu, gleich was `lineNumbers.restart` vorgibt. | | `interval` | `lineNumbers.interval` | Das eigene Intervall des Gedichts: die Nummer jeder N-ten Zeile drucken. | `bodyText.verse` legt die Standardwerte für jedes Gedicht fest (siehe [Konfiguration › Verse](https://postext.dev/de/docs/configuration-text.md#vers)). Der reine Text bewahrt das Gedicht so, wie es geschrieben ist, mit einem Zeilenvorschub zwischen den Zeilen und einer Leerzeile zwischen den Strophen, sodass eine kopierte Passage und eine Suche es Zeile für Zeile lesen; das umfließende EPUB setzt eine Strophe als Element, dessen Zeilen ihre Überläufe hängen lassen, und das getaggte PDF taggt eine Strophe als Absatz. **Zeilennummern.** Ist `lineNumbers` eingeschaltet, werden die Zeilen eines Gedichts gezählt (siehe [Konfiguration › Zeilennummern](https://postext.dev/de/docs/configuration-notes-references.md#zeilennummern)). Jeder Vers zählt einmal: Ein Überlauf erhält keine Nummer, und der Abstand zwischen Strophen wird nicht gezählt. Standardmäßig druckt jede fünfte Zeile ihre Nummer im Außensteg, und die Zählung beginnt bei jedem Gedicht neu. Ein Gedicht im klassischen arabischen Layout zählt eine Zeile je Bayt. Der Direktivenblock passt ein einzelnes Gedicht an: `lineStart=N` gibt seiner ersten Zeile eine Nummer, `interval=N` ein eigenes Intervall, und `numbered=false` nimmt es aus. ```md :::verse{lineStart=37} … ::: ``` Mit dem Standardintervall von 5 druckt dieses Gedicht 40, 45 und so weiter neben seine Zeilen. #### Klassisches arabisches Layout Ein Gedicht im klassischen arabischen Layout (eine Qaṣīda, eine Qiṭʿa): jeder Vers, der *Bayt*, auf einer Zeile in zwei Hälften, der *Ṣadr* auf der Anfangsseite (rechts im Arabischen) und der *ʿAǧuz* auf der Endseite, mit einem Zwischenraum dazwischen. Schreiben Sie einen Bayt je Zeile, die Halbverse getrennt durch `||` (ein `\\` mit je einem Leerzeichen davor und danach, wie in Texten aus Wikisource, funktioniert auch). Eine Zeile ohne Trennzeichen ist ein einzelner Halbvers, auf das Gedicht zentriert. ```md فأنشد يقول: :::verse يَا حُرْقَةَ الدَّهْرِ كُفِّي || إِنْ لَمْ تَكُفِّي فَعِفِّي فَلَا بِحَظِّيَ أُعْطِي || وَلَا بِصَنْعَةِ كَفِّي ::: ``` - **Eine Breite.** Jeder Halbvers des Gedichts wird auf eine einheitliche Breite gesetzt, sodass jeder Ṣadr auf derselben Senkrechten beginnt und jeder ʿAǧuz auf einer anderen endet und die Reimbuchstaben untereinander stehen. Die Breite ist die des breitesten Halbverses, höchstens die halbe Satzbreite abzüglich des Zwischenraums; `width` legt sie fest (`width=55mm`). Jeder Halbvers wird zuerst mit Kaschidas auf diese Breite gebracht (Verse dehnen stärker als Prosa: doppelt `bodyText.kashidaMaxLength`), dann mit seinen Wortabständen; ein Halbvers aus einem einzigen Wort, der sie nicht füllen kann, lässt den Rest im Zwischenraum. - **Der Zwischenraum** beträgt standardmäßig 2 em; `gap` legt ihn fest (`gap=3em`, eine bloße Zahl gilt in Geviert). `ornament` druckt in seiner Mitte ein Zeichen (`ornament="٭"`), das nicht zum Text gehört. - **Zu breit.** Ein Halbvers, der breiter ist als die gemeinsame Breite, verringert zuerst seine Wortabstände bis auf `bodyText.minWordSpacing`. Passt er dann noch nicht, wird sein Bayt gestaffelt gesetzt: der Ṣadr bündig mit der Anfangsseite auf einer eigenen Zeile, der ʿAǧuz bündig mit der Endseite auf der nächsten. - **Platzierung.** Das Gedicht wird in der Spalte zentriert; `align=start` setzt es bündig mit der Anfangsseite. Ein Bayt wird nie auf Spalten oder Seiten verteilt, und das Gedicht folgt den Regeln für Waisen und Witwen von Absätzen (ein Gedicht mit drei Bayts oder weniger bleibt ganz). Der Absatz vor dem Gedicht, der es einleitet («فأنشد يقول:»), hält seine letzte Zeile mit den ersten Bayts zusammen. - **Schrift.** Das Gedicht übernimmt Schriftart, Größe und Zeilenabstand des Grundtexts; `style` nennt ein Absatzformat dafür (`style="verse"`), so erhält ein vokalisiertes Gedicht den zusätzlichen Zeilenabstand, den seine Harakat brauchen. `dir=ltr` oder `dir=rtl` legt seine Richtung fest wie bei jedem Block; bei einem Gedicht in lateinischer Schrift in einem linksläufigen Buch steht der Ṣadr links. Der reine Text des Gedichts hält Halbverse und Bayts auseinander (ein Tabulator und ein Zeilenumbruch), sodass eine Suche oder eine kopierte Passage es so liest, wie es geschrieben ist; Kaschidas und Ornament bleiben weg. ### `:::toc` `:::toc` setzt das Inhaltsverzeichnis an der Stelle, an der es steht. Es entfaltet sich zu gewöhnlichen Blöcken – einem je Überschrift der Ebenen, die `toc.levels` aufführt (standardmäßig Ebene 1), und einem je `:::part` –, sodass das Verzeichnis wie jeder andere Text durch Spalten und Seiten fließt und ein Klick auf einen Eintrag zur Zeile der Direktive führt. Ein Eintrag zeigt die Nummer der Überschrift (die Ausgabe ihres `numberingTemplate`, sonst die Ordnungszahl des Kapitels), ihren Titel, eine Punktlinie und die Bezeichnung der Seite, auf der sie beginnt, und, wenn `toc.subtitle` eingeschaltet ist, eine zweite Zeile mit einem Attribut der Überschrift wie dem `{author="…"}` des Kapitels. Ein Teil erhält eine eigene Zeile, gestaltet von `toc.parts.design` und eingefärbt mit der eigenen `palette` des Teils. Überschriften, deren Format `numbered: false` hat, werden ohne Nummer aufgeführt; `{toc="false"}` an einer Überschrift hält sie heraus (typischerweise die Überschrift des Verzeichnisses selbst). ```md # Contents {style="front-matter" toc="false"} :::toc ``` Die Seitenzahlen sind die, die das Dokument tatsächlich druckt. Ein für sich gesetztes Dokument wird mit den Bezeichnungen des vorigen Durchgangs erneut gesetzt, bis sie sich nicht mehr verschieben – beginnt die Nummerierung nach der Titelei neu (das Rezept `:::numbering` oben), genügt ein zusätzlicher Durchgang. Ein für sich gesetztes Kapitel (die Vorschauen der Sandbox) erhält stattdessen die Gliederung des ganzen Buchs von seinem Host. Siehe [Inhaltsverzeichnis](https://postext.dev/de/docs/configuration-notes-references.md#inhaltsverzeichnis) in der Konfigurationsreferenz. ### `:::index` `:::index` setzt das Register an der Stelle, an der es steht: die im ganzen Buch mit `:index[…]` oder `:index{term="…"}` ausgezeichneten Begriffe mit ihren Seiten, die dem Text folgen, wenn er sich verschiebt. Beschrieben wird es zusammen mit den Marken unter [Register](https://postext.dev/de/docs/document-format.md#register). Eine Spalte endet nie nach dem ersten Eintrag einer Gruppe und nie vor ihrem letzten: Zwei Einträge der Gruppe bleiben und zwei laufen weiter, oder die Gruppe wandert als Ganzes (`index.groups.splitMinEntries`). ```md # Index {style="index"} :::index ``` ### Zeilenumbrüche Die Zeilen eines Absatzes werden mit einem Leerzeichen verbunden. Um innerhalb eines Absatzes eine Zeile zu beenden, ohne einen neuen zu beginnen (eine Anschrift, die Anrede eines Briefs, eine Widmung), beenden Sie die Quellzeile mit einem Backslash, dem harten Umbruch von CommonMark, oder schreiben Sie `\\` gefolgt von einem Leerzeichen: ```md To the keeper of the lighthouse,\ at the end of the northern pier. Ana Ruiz \\ Calle Mayor 4 \\ 28013 Madrid ``` - Die Zeile vor einem Umbruch wird in ihrer natürlichen Breite gesetzt, wie die letzte Zeile eines Absatzes, nie auf die Satzbreite gedehnt. Der Text danach beginnt eine neue Zeile desselben Absatzes, ohne Erstzeileneinzug und ohne Abstand darüber; bei einem hängenden Einzug hängt er wie jede Zeile nach der ersten. - Absätze, Zitate (`> First line\` über `> second line`), Fußnoten und Listenpunkte nehmen ihn an. Ein Listenpunkt ist eine einzige Quellzeile, daher bricht er bei `\\` um. - Ein Backslash am Ende des Absatzes wird gedruckt, wie in CommonMark, und zwei Umbrüche hintereinander ergeben einen: Für eine leere Zeile beginnen Sie einen neuen Absatz oder fügen ein [`:::space`](https://postext.dev/de/docs/document-format.md#space) ein. - Ein `\\`, das direkt am nächsten Zeichen hängt, ist kein Umbruch: `\\*` druckt einen Backslash und ein maskiertes Sternchen, `C:\\Temp` beide Backslashes. In Inline-Code und in einer Formel gehören die Backslashes zum Code bzw. zur Formel. - Zwei Leerzeichen am Zeilenende, der andere harte Umbruch von CommonMark, sind keiner: Sie sind in einem Editor unsichtbar, und viele Editoren lassen sie zurück, sodass sie Zeilen umbrechen würden, die niemand umbrechen wollte. - Aus dem HTML-Betrachter kopierter Text hat am Umbruch einen Zeilenvorschub, das umfließende EPUB ein `
`, der Text des PDF ein Zeilenende und ein Word-Export einen manuellen Zeilenumbruch (Umschalt+Eingabe), den der Word-Import wieder als Umbruch liest. - Ein Gedicht behält seine Zeilen, Einzüge und Strophen in einem Block [`:::verse`](https://postext.dev/de/docs/document-format.md#verse), ohne Backslash an jeder Zeile. Bis postext 1.22 wurde der Backslash gedruckt, und die Zeilen wurden mit einem Leerzeichen verbunden. Ein damals gespeichertes Buch, dessen Text eine Zeile mit einem Backslash beendet oder `\\` vor ein Leerzeichen setzt, behält diese Lesart (`bodyText.hardLineBreaks: false`, siehe [Konfiguration › Pakete, die postext 1.4 oder früher geschrieben hat](https://postext.dev/de/docs/configuration-programmatic-usage.md#pakete-die-postext-14-oder-früher-geschrieben-hat)). ### Zeilenumbrüche in Titeln Schreiben Sie `\\` in eine Überschrift (oder in das Attribut `title` eines Teils), um einen Zeilenumbruch dort zu erzwingen, wo der Titel als Titel angezeigt wird: Die Überschrift in der Spalte fließt weiter und zeigt an dieser Stelle ein Leerzeichen, während `{titleText}` einer Auftaktgestaltung die Zeile dort umbricht (in jedem Modus `overflow` des Textelements). Kolumnentitel, `{chapterTitle}`, `{partTitle}` und die PDF-Gliederung geben den Titel stets einzeilig wieder. Im Chinesischen oder Japanischen gilt der Umbruch als ideografisches Leerzeichen zwischen zwei Zeichen der Schrift (ein Titel aus einem Verspaar); wo eines davon auf eine Ziffer oder lateinischen Text trifft (`关于举办 \\ 2026年…`), setzt die Seite den Abstand zwischen Han- und lateinischer Schrift, und die PDF-Lesezeichen und der Dokumenttitel fügen die beiden Hälften ohne Zwischenraum zusammen, wie chinesischer Fließtext geschrieben wird. ```md # Concepts of health and illness. \\ Community health {author="I. Zango Martín"} ``` ## Inline-Formatierung Inline-Auszeichnungen werden in jedem Textblock erkannt (Überschriften, Absätze, Zitate, Listeneinträge). In einer Überschrift folgen sie `headings.inlineMarks`, standardmäßig eingeschaltet: Kursives, Fettes, Hoch- und Tiefstellungen, Kapitälchen und Links des Titels werden wie in einem Absatz gedruckt, und eine kursive Folge in einer kursiven Überschrift erscheint aufrecht. Ist es ausgeschaltet, entfallen die Markierungen, und der Titel wird im eigenen Format der Überschrift gedruckt; Konfigurationen, die mit postext 1.4 oder früher gespeichert wurden und deren Überschriften Auszeichnungen tragen, werden so gelesen (siehe [Konfiguration › Überschriften](https://postext.dev/de/docs/configuration-text.md#überschriften)). Eine Überschriftengestaltung druckt `{titleText}` in jedem Fall als einfachen Text. > **Abbildung: Inline-Formatierung auf einen Blick** > Gegenüberstellung von Markdown und Ergebnis für fett, kursiv, fett kursiv, Inline-Code und Links. > > *Links das Markdown, rechts das gesetzte Ergebnis.* | Auszeichnung | Syntax | Hinweise | | --- | --- | --- | | Fett | `**bold**` oder `__bold__` | Gesetzt mit `bodyText.boldFontWeight`. Ein optionales `bodyText.boldColor` ersetzt für fette Folgen die Standardfarbe des Fließtexts. | | Kursiv | `*italic*` oder `_italic_` | Gesetzt mit dem kursiven Schnitt der aktuellen Schriftfamilie. Ein optionales `bodyText.italicColor` ersetzt für kursive Folgen die Standardfarbe des Fließtexts. Ein Unterstrich kennzeichnet Hervorhebung nur an einer Wortgrenze, wie in CommonMark: Einer zwischen zwei Buchstaben oder Ziffern – `snake_case_name`, das `SR_AIR_EN.pdf` einer URL – ist Text (auch bei `__bold__`); innerhalb eines Worts verwenden Sie Sternchen (`un*believ*able`). Chinesische, japanische und koreanische Zeichen zählen hier nicht, da diese Schriften keine Leerzeichen kennen: `中文_斜体_中文` und `中文__粗体__中文` sind kursiv bzw. fett. Ein `__`, das keinen Fettdruck ergibt, wird nie zu Kursivschrift: `foo__bar__baz` bleibt Text. | | Fett kursiv | `***both***` oder `___both___` | Beide Kennzeichen werden kombiniert. | | Hochgestellt | `^text^` | Gesetzt in 58 % der Textgröße und um ein Drittel davon angehoben – ein Exponent (`10^-8^`), eine Ionenladung (`Na^+^`). Der markierte Text beginnt und endet mit einem Zeichen, das kein Leerzeichen ist; ein einzelnes Caret im Text bleibt wörtlich stehen, ebenso die Gesichter `^_^` und `^o^` (`n.^o^` und `1^o^` sind dennoch hochgestellt). | | Tiefgestellt | `~text~` | Gleiche Größe, um 0,15 der Textgröße abgesenkt, sodass es innerhalb der Unterlängen bleibt – ein chemischer Index (`H~2~O`, `pK~a~`). Eine Tilde mit einer Ziffer auf jeder Seite ist ein Bereich und bleibt wörtlich stehen: `3~5 days`, `需要3~5天`. Ebenso eine zwischen zwei chinesischen Wörtern, die keine Tiefstellung öffnet: `周一~周五`, `北京~上海`; eine Tiefstellung schließt aber weiterhin vor einem chinesischen Zeichen (`F~合~等于`). Lässt sich mit fett und kursiv kombinieren (`**H~2~O**`). Eine Tiefstellung und eine Hochstellung, die ohne etwas dazwischen zusammen geschrieben sind, werden wie in einer Formel gestapelt: `*T*~0~^2^` setzt die 2 über die 0, gleich welche zuerst kommt, die Tiefstellung um 0,25 der Textgröße abgesenkt, damit sie der Hochstellung ausweicht, und das Paar nimmt die Breite des breiteren Teils ein. Ein Leerzeichen oder ein Buchstabe dazwischen setzt sie nacheinander; ein Wortverbinder (U+2060) ebenso, ohne dass dazwischen etwas sichtbar ist. Ein gestapeltes Paar wird nie an einem Zeilenumbruch getrennt: Ein für die Zeile zu breites Wort bricht vor dem Paar um. | | Kapitälchen | `:smallcaps[text]` | Kleinbuchstaben als Großbuchstaben in 70 % der Textgröße gesetzt – der Name einer Figur in einem Theaterstück, ein Akronym im Fließtext. Nimmt andere Auszeichnungen in sich und um sich herum an; siehe [Kapitälchen](https://postext.dev/de/docs/document-format.md#kapitälchen). | | Ausrichtung in senkrechtem Text | `:tcy[12]`, `:upright[GDP]`, `:sideways[12]` | In senkrechtem Text: eine aufrechte Zelle (Tate-chū-yoko), jedes Zeichen aufrecht in einer eigenen Zelle oder die ganze Folge gedreht. Keine Wirkung in waagerechtem Text; siehe [Ausrichtung in senkrechtem Text](https://postext.dev/de/docs/document-format.md#ausrichtung-in-senkrechtem-text). | | Chinesische Zeichen | `:dots[不可]`, `:name[賈寶玉]`, `:book[石頭記]` | Betonungspunkte (着重号), die Eigennamenlinie (专名号) und das Buchtitelzeichen (书名号: 《》 oder eine Wellenlinie, je nach `cjk.bookTitleMark`). Der Text bleibt so, wie er geschrieben ist; siehe [Chinesische Zeichen, Ruby und Warichu](https://postext.dev/de/docs/document-format.md#chinesische-zeichen-ruby-und-warichu). | | Ruby | `:ruby[紅樓]{rt="hóng lóu"}` oder `{紅樓\|hóng\|lóu}` | Lesungen in Pinyin oder Zhuyin über (oder neben) den Grundzeichen. Die Kurzform braucht eine Basis aus Han-Zeichen, Kana oder Bopomofo, daher bleibt `{x\|x>0}` Text. | | Warichu | `:warichu[note]{open="〔" close="〕"}` | Eine Anmerkung, in zwei Zeilen halber Größe innerhalb der Zeile gesetzt (双行夹注), über Zeilen und Seiten umbrochen. | | Inline-Code | `0` | Die Backticks werden entfernt; die Folge wird als einfacher Text gesetzt, genau so, wie sie geschrieben ist: Ein `:ref{…}`, ein Chip, eine Formel, ein Link oder eine Hervorhebungsmarkierung darin wird wörtlich gedruckt, und so zeigt ein Text die Syntax. Gesetzt wird sie in der Schrift des Texts oder, mit `codeStyle.inline`, als Einheit in der Code-Schrift (siehe [Konfiguration › Code-Listings](https://postext.dev/de/docs/configuration-styles.md#code-listings)). Ein Listing gehört in einen [Codeblock](https://postext.dev/de/docs/document-format.md#codeblöcke). | | Escape | `\*`, `\_`, `\^`, `\~`, ``\```, `\$` | Ein Backslash setzt das Markierungszeichen selbst – das Sternchen einer Tabellenfußnote (`\* pOH = −log [OH^−^]`), ein wörtliches Caret, ein Dollarzeichen, das keine Formel öffnet –, statt eine Folge zu öffnen. Funktioniert im Fließtext, in Chips sowie in Legenden, Zellen und Anmerkungen. (Bis postext 1.4 druckten Legenden, Zellen, Anmerkungen und Chips den Backslash von `\$` mit.) | | Geschütztes Leerzeichen | das Zeichen selbst: U+00A0, U+202F, U+2007 | Verbindet die Wörter zu beiden Seiten, sodass eine Zeile nie zwischen ihnen umbricht: eine Zahl und ihre Einheit (37 °C), eine Seitenangabe (S. 12), eine Tausendergruppe (225 000). Das geschützte Leerzeichen (U+00A0), das schmale geschützte Leerzeichen (U+202F) und der Ziffernabstand (U+2007) verbinden alle – im Fließtext, in Legenden, Zellen, Kästen und Kolumnentiteln –, und jedes behält seine eigene Breite: Der Blocksatz dehnt nur die Wortzwischenräume. Viele Schriften haben kein Glyph für das schmale geschützte Leerzeichen oder den Ziffernabstand; diese werden dann so gesetzt, wie Browser sie setzen, im Canvas, im HTML und im PDF gleichermaßen: als halber Wortzwischenraum bzw. in der Breite einer Ziffer. Praktisch jede Schrift hat U+00A0, daher ist es die sichere Wahl. Eine so verbundene Gruppe, die breiter ist als die ganze Zeile, bricht an ihrem letzten geschützten Leerzeichen um statt innerhalb eines Worts. Der Wortverbinder (U+2060) verbindet, ohne Platz einzunehmen. Tippen Sie das Zeichen selbst: Eine HTML-Entität wie ` ` wird so gedruckt, wie sie geschrieben ist. Siehe [Wo eine Zeile nie umbricht](https://postext.dev/de/docs/justification.md#wo-eine-zeile-nie-umbricht). | | Bedingter Trennstrich | das Zeichen selbst: U+00AD | Eine Stelle, an der das Wort getrennt werden darf, mit einem hinzugefügten Trennstrich, wenn dort eine Zeile endet: nur zwischen zwei Buchstaben oder Ziffern. Ein Wort, das einen enthält, erhält aus dem Wörterbuch keine weitere Trennstelle, sodass der bedingte Trennstrich seine einzige Trennung ist; vor dem ersten Buchstaben eines Worts getippt, trennt er nichts und hält dieses Vorkommen ganz. Neben einer Klammer, einem Anführungszeichen oder einem Satzzeichen bewirkt er nichts. Siehe [Wo eine Zeile nie umbricht](https://postext.dev/de/docs/justification.md#wo-eine-zeile-nie-umbricht). | | Link | `[text](https://…)` | Der sichtbare Text bleibt im Fluss und wird genau so gesetzt wie ohne den Link. Die URL macht die Wörter in der HTML- und PDF-Ausgabe zu einem aktiven Link; siehe [Links](https://postext.dev/de/docs/document-format.md#links). | | Bild | `![alt](src)` | Markdown für Inline-Bilder wird aus dem Text **entfernt**. Bilder müssen in `PostextContent.resources` deklariert werden, damit die Layout-Engine sie nach den Regeln von `resourcePlacement` platzieren kann. | | Chip | `:chip[text]` | Eine eingerahmte Textfolge, die als Einheit umbricht – eine Wortbank, eine Taste, ein Tag. Gestaltet über `chipStyles`; siehe [Inline-Chips](https://postext.dev/de/docs/document-format.md#inline-chips). | | Tabulator | `:tab`, `:tab{at=120mm align=end leader="."}` | Schickt die Wörter danach zum nächsten Tabstopp: einem der Tabstopps des Absatzformats oder dem, den seine Attribute festlegen. Ein im Text getippter Tabulator ist nur dort ein Tabulator, wo das Format Tabstopps setzt. Siehe [Tabulatoren und Tabstopps](https://postext.dev/de/docs/document-format.md#tabulatoren-und-tabstopps). | | Inline-Formel | `$…$` | Eine LaTeX-Formel, die mit dem umgebenden Text fließt, z. B. `$e^{i\pi}+1=0$`. Gesetzt von MathJax und auf jedem Backend als Vektorpfade gerendert. Verwenden Sie `\\$` für ein wörtliches Dollarzeichen. Skalierung, die abgesetzte Form (`$$ … $$`) und die Fehlerbehandlung werden unter [Mathematische Formeln](https://postext.dev/de/docs/document-format.md#mathematische-formeln) behandelt. | ### Links Ein Markdown-Link, `[text](url)`, behält seinen Text im Fluss genau so, wie der Text ohne ihn gesetzt würde: Der Link ändert nie Zeilenumbrüche, Abstände oder Farbe. Er behält seine URL für die Ausgaben, die ihr folgen können: - **HTML** (`renderToHtml`): Die verlinkten Wörter werden in `` eingeschlossen, das die Textfarbe übernimmt und nicht unterstrichen ist. Je Folge verlinkter Wörter auf einer Zeile gibt es einen Anker. - **PDF** (`postext-pdf`): Jede Folge verlinkter Wörter auf einer Zeile wird zu einer anklickbaren URI-Link-Annotation. In einem getaggten PDF ist sie ein Element `Link`, dessen Text die verlinkten Wörter sind. - **Canvas**: als einfacher Text gemalt, da ein Canvas keine Klickfläche hat. ```markdown Read the [configuration guide](https://postext.dev/en/docs/configuration "Configuration") or write to [the team](mailto:team@example.com). ``` - Das Ziel kann einen Titel tragen, der ignoriert wird (`[text](https://example.com "Title")`). Es kann auch in spitze Klammern eingeschlossen sein, wobei Leerzeichen zu `%20` werden (`[text]()`). - Nur sichere Ziele bleiben erhalten: `http:`, `https:`, `mailto:`, `tel:`, `ftp:` und relative URLs (`../guide`, `#top`). Jedes andere Schema (`javascript:`, `data:`, `file:` …) setzt den Text ohne Link. Das PDF verlinkt nur absolute URLs. - Das Ziel darf Klammern enthalten, solange sie ausgeglichen sind, wie in CommonMark: `[photo](https://commons.wikimedia.org/wiki/File:Bike_(Unsplash).jpg)` verlinkt die ganze URL. Ein Backslash maskiert ein Zeichen (`\(`, `\_`). Sind die Klammern nicht ausgeglichen, endet das Ziel an seiner ersten `)`, und der Text wird ohne Link gesetzt; kodieren Sie eine einzelne Klammer als `%28` oder `%29`. Auch ein Leerzeichen beendet das Ziel, sofern es nicht in spitze Klammern eingeschlossen ist. - Ein Wort, das direkt am Linktext klebt, gehört mit zum Link. In `see [the site](https://example.com).` ist der Punkt Teil der anklickbaren Fläche. - Der Linktext kann Hervorhebungen enthalten (`[**bold** words](…)`) und selbst darin stehen (`**[words](…)**`). - Links funktionieren in Absätzen, Listeneinträgen, Zitaten, Kästen, Legenden, Anmerkungen und Tabellenzellen sowie in Überschriften, solange `headings.inlineMarks` eingeschaltet ist (die Voreinstellung). Kolumnentitel, die Gliederung und die aus einer Überschrift erzeugten Zeilen des Inhaltsverzeichnisses behalten nur den Text, ebenso der Text eines `:chip[…]`. - Links im Referenzstil (`[text][id]`) und Autolinks (``) werden nicht erkannt (siehe [Was NICHT unterstützt wird](https://postext.dev/de/docs/document-format.md#was-nicht-unterstützt-wird)). Im VDT steht das Ziel an jedem verlinkten Segment, als `VDTLineSegment.href`. Der Parser hält die Links einer Folge als Bereiche ihres Texts in `InlineSpan.links` fest und teilt eine Folge nie wegen eines Links; deshalb kann ein Link das Layout nicht verändern. ### Inline-Chips `:chip[text]` setzt `text` in einen Kasten – einen abgerundeten, getönten „Chip“ –, der mit der Zeile fließt: die Wörter einer Wortbank oder einer Zuordnungsübung, Tastaturtasten, Tags. `:chip[text]{style="key"}` wählt ein benanntes Format aus `chipStyles` (siehe die Konfigurationsreferenz); ohne `style` oder mit einer ID, die kein Format deklariert, erhält der Chip das erste Format (ein eingebautes Format `chip`, wenn die Konfiguration keines hat; die Sandbox warnt vor einer unbekannten ID). ```markdown Classify: :chip[battery] :chip[cable] :chip[switch] :chip[bulb] Press :chip[Ctrl]{style="key"} + :chip[C]{style="key"} to copy. ``` - **Eine Einheit.** Ein Chip wird innen nie umbrochen oder getrennt; die Zeile bricht zwischen Chips um, an den Wortzwischenräumen um sie herum. Ein Chip, der breiter ist als die ganze Zeile, ragt über sie hinaus, statt geteilt zu werden. - **Breite.** Seine Laufweite ist der Text plus der waagerechte Innenabstand und die Kontur auf beiden Seiten. Der Blocksatz dehnt nur die Wortzwischenräume, nie das Innere eines Chips. Das `gap` des Formats ist der geringste Abstand, der über einen Zwischenraum hinweg zwischen dem Kasten und einem benachbarten Wort oder Chip bleibt – ein schmalerer Zwischenraum wird aufgefüllt (nicht an einem Zeilenrand und nicht vor anhängender Interpunktion wie in `:chip[a],`). - **Höhe.** Der Kasten ist ein Band um die Grundlinie, 0,8 em darüber und 0,25 em darunter in der Größe des Chips, erweitert um den senkrechten Innenabstand und die Kontur. Der senkrechte Innenabstand wird außerhalb des Zeilenkastens gemalt und ändert nie die Zeilenhöhe, sodass das Grundlinienraster hält; ein Kasten, der höher ist als der Zeilenabstand, kann in einen Chip der Zeile darüber oder darunter hineinreichen, und die Sandbox kennzeichnet zwei Chips auf verschiedenen Zeilen, die sich überlappen („Chips berühren die nächste Zeile“), damit Innenabstand, Kontur oder Größe verringert werden können. - **Text.** Der Text des Chips nimmt eigene Inline-Auszeichnungen an (`:chip[**bold** word]`, `:chip[x^2^]`) sowie die Hervorhebung um ihn herum (`**:chip[a]**`); das Format kann Familie, Größe, Farbe, fett und kursiv festlegen. Schreiben Sie `\]` für eine wörtliche Klammer darin. Verweise, Farbfelder und Formeln in einem Chip bleiben wörtlich, und `\$` druckt ein Dollarzeichen (bis postext 1.4 wurde auch der Backslash gedruckt). - **Leer.** Ein Chip nur aus Leerzeichen (`:chip[ ]`, geschützte Leerzeichen eingeschlossen) ist ein leerer Kasten – eine Antwortlücke, ein Schlusszeichen: so breit wie waagerechter Innenabstand und Kontur seines Formats, so hoch wie ein Chip mit Wörtern. Die Breite der Lücke bestimmen Sie über das `paddingX` eines Formats (`:chip[ ]{style="blank"}`). Steht gar nichts zwischen den Klammern, bleibt `:chip[]` wörtlicher Text. - **Wo.** Absätze, Listeneinträge, Zitate, Kästen, Tabellenzellen, Legenden und Anmerkungen. Überschriften behalten `:chip[…]` als wörtlichen Text. - **Ausgabe.** Canvas, HTML und PDF malen den Kasten und setzen die Wörter als echten Text: im HTML auswählbar, im PDF extrahierbar und in Lesereihenfolge (in einem getaggten PDF ist der Kasten ein Layout-Artefakt, und die Wörter gehören zum Absatz). ### Kapitälchen `:smallcaps[text]` setzt `text` in Kapitälchen – die Namen der Figuren in einem Theaterstück, ein Akronym im Fließtext, die ersten Wörter eines Kapitels. Kleinbuchstaben werden als Großbuchstaben in 70 % der Textgröße gesetzt, während Großbuchstaben, Ziffern und Satzzeichen die volle Größe behalten; `:smallcaps[Hamlet]` druckt also ein H in voller Größe, gefolgt von AMLET in Kapitälchen. ```markdown Enter :smallcaps[Hamlet] and :smallcaps[Horatio], reading. The :smallcaps[unesco] report and the :smallcaps[who] guidelines. ``` - **Synthetisch.** Die Kapitälchen werden aus den Großbuchstaben der Schrift selbst gebildet, auf dem Canvas, im HTML und im PDF auf dieselbe Weise, sodass der Text überall gleich gemessen und umbrochen wird. Echte Kapitälchen einer Schrift (das OpenType-Feature `smcp`) werden nicht verwendet; für sie setzen Sie den Text über ein Absatzformat in einer Kapitälchenfamilie (etwa einer Familie, deren Name auf „SC“ endet). - **Auszeichnungen.** Der Text nimmt eigene Inline-Auszeichnungen an (`:smallcaps[**Ophelia**]`) sowie die Hervorhebung um ihn herum (`*:smallcaps[Act I]*`); schreiben Sie `\]` für eine wörtliche Klammer darin. Ein Verweis oder ein Chip darin wird ebenfalls in Kapitälchen gesetzt, und ein Verweis bleibt im HTML und im PDF ein einziger Link; eine Formel nicht. - **Umbruch.** Wörter werden wie üblich umbrochen und getrennt; die Silbentrennung liest jedes Wort in seiner eigenen Schreibung. - **Wo.** Absätze, Listeneinträge, Zitate, Kästen, Tabellenzellen, Legenden und Anmerkungen sowie Überschriften, solange `headings.inlineMarks` eingeschaltet ist (die Voreinstellung); ist es ausgeschaltet, wird die Auszeichnung aus einer Überschrift entfernt und der Text so gedruckt, wie er geschrieben ist. - **Ganze Absätze.** Ein Absatzformat oder der Inhalt eines Kastens mit `smallCaps: true` setzt seinen ganzen Text auf diese Weise (siehe [Absatzformate](https://postext.dev/de/docs/configuration-styles.md#absatzformate)). - **Text.** Canvas, HTML und PDF enthalten die Buchstaben so, wie sie gemalt sind: Wer `:smallcaps[Hamlet]` kopiert, erhält „HAMLET“. ### Tabulatoren und Tabstopps Ein Tabulator schickt die Wörter danach zu einem Stopp auf der Zeile: den Preis eines Gerichts bündig am Ende der Zeilenbreite hinter einer Punktreihe, den Darsteller hinter der Rolle in einer Besetzungsliste, die Punktzahl einer Prüfungsfrage am Rand. Schreiben Sie `:tab` dort, wo der Tabulator hingehört; die Leerzeichen um ihn herum gehen in ihm auf. Die Tabstopps werden in der Konfiguration festgelegt: `bodyText.tabStops` für jeden Absatz, Listeneintrag und jedes Zitat, das `tabStops` eines Absatzformats für die Absätze einer Gruppe `:::paragraphs` und das `body.tabStops` eines Kastenformats innerhalb seiner Kästen (siehe [Konfiguration › Tabulatoren](https://postext.dev/de/docs/configuration-text.md#tabulatoren)). Eine Speisekarte, deren Preise am Ende der Zeilenbreite hinter Punkten enden: ```ts paragraphStyles: [ { id: 'menu', firstLineIndent: { value: 0, unit: 'em' }, tabStops: [{ position: 'end', align: 'end', leader: '. ' }] }, ], ``` ```markdown :::paragraphs{style="menu"} Onion soup :tab 8.50 Grilled sea bream with fennel and lemon :tab 21.00 ::: ``` `:tab{…}` setzt einen Stopp für genau diesen einen Tabulator, ohne Format: die Lücke eines Formulars bis zum Zeilenende, einen Betrag an seinem Dezimaltrennzeichen. ```markdown Name and surname :tab{at=end leader=rule} Total due :tab{at=80% align=decimal} 1,234.50 ``` | Attribut | Bedeutung | | --- | --- | | `at` | Wo der Stopp steht, gemessen vom Anfangsrand der Zeilenbreite des Absatzes: eine Länge (`120mm`, `4cm`, `2em`; eine bloße Zahl gilt in Punkt), `end` für das Ende der Zeilenbreite oder ein Anteil davon (`60%`). Ohne `at` geht `:tab{…}` zu den Stopps des Formats, wie ein bloßes `:tab`. | | `align` | `start` (die Voreinstellung): Der Text nach dem Tabulator beginnt am Stopp. `end`: Er endet dort (der Text bis zum nächsten Tabulator oder zum Ende des Absatzes). `center`: Er wird auf dem Stopp zentriert. `decimal`: Sein Dezimaltrennzeichen steht auf dem Stopp; eine Folge ohne eines endet dort. | | `leader` | Text, der über den Raum vor dem Stopp wiederholt wird: `"."`, `". "`, `"·"`, `"_"`, `"-"` oder ein anderer kurzer Text, in Schrift und Farbe des Absatzes. `rule` zieht eine Linie knapp unter der Grundlinie, die Lücke eines Formulars. Standardmäßig keiner. | | `gap` | Abstand, der zwischen der Füllung und dem Text auf beiden Seiten bleibt. Standardmäßig `0.5em` der Größe des Absatzes; eine bloße Zahl gilt in Punkt. | | `decimal` | Das Trennzeichen, an dem ein Stopp `decimal` ausrichtet. Standardmäßig das der Dokumentsprache: `.` in Englisch, Chinesisch, Japanisch und Arabisch, `,` in Spanisch, Katalanisch, Portugiesisch, Französisch, Deutsch und anderen. | - **Wohin ein Tabulator geht.** Zum ersten Stopp hinter dem Text davor, unter den Stopps nach demjenigen, den der vorige Tabulator der Zeile genommen hat; der zweite Tabulator einer Zeile nimmt daher meist den zweiten Stopp. Hinter dem letzten Stopp setzt `tabInterval` weitere Stopps in jedem Intervall ab dem Anfang der Zeilenbreite; ohne es ist der Tabulator ein Wortzwischenraum. - **Tabulatorzeichen.** Ein im Text getippter Tabulator (U+0009) ist nur in einem Absatz ein Tabulator, dessen Format `tabStops` oder `tabInterval` setzt. Überall sonst ist er der Wortzwischenraum, der er immer war, sodass ein Dokument, das Tabulatoren statt Leerzeichen verwendet, sein Layout behält. Mehrere Tabulatorzeichen hintereinander gehen ebenso viele Stopps weiter. Ein Tabulator am Anfang einer Quellzeile wird mit den übrigen führenden Leerräumen der Zeile entfernt: Schreiben Sie `:tab`, um eine Zeile an einem Stopp zu beginnen. - **Was Text bleibt.** Ein `:tab`, auf das ein Buchstabe folgt (`3:table`), sowie ein `:tab` in Inline-Code, in einer Formel, in der Adresse eines Links oder in den Attributen einer Direktive. - **Wo.** Absätze, Listeneinträge, Zitate, Kästen und Gruppen `:::paragraphs`. Überschriften, Legenden, Tabellenzellen und die Texte von Gestaltungen (Kapitelauftakte, Kolumnentitel) haben keine Tabstopps. - **Text hinter dem Stopp.** Hat der Text vor einem Tabulator bereits jeden auf seiner Zeile verbliebenen Stopp überschritten, nimmt ein Stopp `end`, `center` oder `decimal` das letzte Wort vor dem Tabulator zusammen mit dem Text am Stopp in die nächste Zeile mit, und der Text davor wird schmaler gesetzt, so wie eine Zeile des Inhaltsverzeichnisses ihren Titel umbricht, um die Seitenzahl zu behalten. Ein Stopp `start` bricht die Zeile vor dem Tabulator um, und der Text danach beginnt die nächste Zeile an seinem Stopp. Ein Tabulator, der seine Zeile eröffnet und trotzdem keinen Stopp findet, nimmt keinen Platz ein. - **Füllzeichen.** Eine Füllung füllt den Raum vor ihrem Stopp und endet bündig mit dem Ende dieses Raums, sodass die Punkte mehrerer Zeilen untereinander stehen, gleich welcher Text davor steht. `gap` hält sie vom Text auf beiden Seiten fern; davor gibt es keinen Abstand, wenn der Tabulator die Zeile eröffnet, und danach keinen, wenn nichts folgt. Eine Füllung wird ab drei Wiederholungen gesetzt; ein Raum für eine oder zwei bleibt leer, wie im Inhaltsverzeichnis. - **Zeilenumbruch.** Ein Absatz mit einem Tabulator wird Zeile für Zeile gesetzt, nie mit Knuth-Plass. Im Blocksatz nehmen nur die Wortzwischenräume nach dem letzten Tabulator einer Zeile den Ausgleich auf, und die letzte Zeile des Absatzes wird nicht gedehnt (siehe [Blocksatz › Zeilen mit Tabulatoren](https://postext.dev/de/docs/justification.md#zeilen-mit-tabulatoren)). Ein zentrierter oder rechtsbündiger Absatz setzt seine Zeilen mit Tabulatoren von der Anfangsseite aus, da die Stopps Positionen auf der Zeilenbreite sind. Von rechts nach links werden die Stopps von rechts gemessen, und ein Stopp `end` steht links (siehe [Arabischer Satz](https://postext.dev/de/docs/arabic-layout.md#inhaltsverzeichnis-und-register)). In senkrechtem Text ist ein Tabulator ein Wortzwischenraum, und ein `:tab` löst dort die Inhaltswarnung `tabInVerticalText` aus. - **Text und Ausgaben.** Der reine Text enthält an jedem Tabulator ein Tabulatorzeichen (`\t`); die Füllzeichen sind kein Text, und Kopien, Suchen und die Source-Map lassen sie weg. Canvas, HTML-Betrachter und EPUB mit festem Layout malen sie (im HTML vor Screenreadern verborgen); ein getaggtes PDF kennzeichnet sie als Artefakte, sodass sein Text `Onion soup 8.50` lautet. Das umfließende EPUB kann die Stopps nicht exakt halten: Jede Zeile eines Absatzes mit Tabulatoren wird zu einer Reihe aus den Teilen zwischen ihren Tabulatoren, in der ein Stopp `end`, `center` oder `decimal` oder einer mit Füllung den nächsten Teil an das Ende der Reihe schiebt (seine Füllung als gepunkteter oder durchgezogener Rand), und ein Stopp `start` den Teil davor in seiner gedruckten Breite hält. Ein Word-Export schreibt `:tab` als Word-Tabulator, und der Word-Import liest einen Tabulator im Fließtext als `:tab` mit dem Stopp zurück, den Word dafür gesetzt hat (siehe [Sandbox › Word-Dokumente](https://postext.dev/de/docs/sandbox.md#word-dokumente)). ### Ausrichtung in senkrechtem Text In senkrechtem Text (`layout.writingMode: 'vertical-rl'`) stehen chinesische Zeichen aufrecht, lateinische Wörter und lange Zahlen werden seitlich gedreht, und eine Zahl mit höchstens zwei Ziffern steht aufrecht in einer Zelle, es sei denn, sie steht in einem lateinischen Satz, dessen Wörtern sie folgt (siehe [Konfiguration › Zahlen im vertikalen Text](https://postext.dev/de/docs/configuration-east-asian.md#zahlen-im-vertikalen-text)). Drei Auszeichnungen heben eine Folge von Hand ab: ```markdown 第:tcy[120]回，:upright[GDP]增長:sideways[12]倍。 ``` - `:tcy[…]` (Tate-chū-yoko, 縱中橫) setzt seinen Text nebeneinander in eine aufrechte Zelle von einem Geviert, quer gestaucht, wenn er breiter ist: `:tcy[120]`, `:tcy[3.0]`, `:tcy[A+]`. Bis zu etwa vier Zeichen lesen sich gut. - `:upright[…]` stellt jedes Zeichen aufrecht in eine eigene Zelle, lateinische Buchstaben darin zentriert: ein Akronym, das Buchstabe für Buchstabe die Spalte hinab gelesen wird. Darin bricht nie eine Zeile um. - `:sideways[…]` dreht die ganze Folge mit der Zeile, auch chinesische Zeichen: eine zweistellige Zahl, die der Autor seitlich haben will. - Der Text bleibt im reinen Text erhalten; die Auszeichnungen nehmen andere Inline-Auszeichnungen in sich auf (`:tcy[**12**]`), einen Link (`:sideways[[iPhone](https://…)]`) und einander, wobei die innerste gewinnt (`:tcy[:upright[AB]]` stellt A und B aufrecht), und für eine wörtliche Klammer schreiben Sie `\]`. In waagerechtem Text ändern sie nichts. - Ein Verweis, eine Anmerkungsmarke, eine Formel, ein Chip oder ein Farbfeld innerhalb einer Auszeichnung behält seine eigene Einstellung: `:sideways[iPhone[^1]]` dreht iPhone und lässt die Anmerkungsnummer so, wie jede Anmerkungsnummer gesetzt wird; die Nummer eines Verweises steht nach `cjk.uprightDigits` wie jede kurze Zahl in einer Zelle. - Ein Textelement einer Gestaltung mit `inlineMarks: true` nimmt sie ebenfalls an, wenn es senkrecht gesetzt wird (siehe [Konfiguration › Vertikale Textelemente](https://postext.dev/de/docs/configuration-page-layout.md#vertikale-textelemente)). - Für Umbruch und Blocksatz zählen eine Zelle `:tcy` und jedes Zeichen von `:upright` als chinesische Zeichen, und neben ihnen wird kein Han-Latein-Abstand gesetzt. ### Chinesische Zeichen, Ruby und Warichu Chinesische und japanische Ausgaben kennzeichnen Text zwischen den Zeilen statt mit Kursivschrift oder Unterstreichung, versehen Zeichen mit ihren Lesungen und setzen Kommentare in die Zeile. Sieben Direktiven leisten das. [Chinesischer Satz](https://postext.dev/de/docs/chinese-layout.md) und [Japanischer Satz](https://postext.dev/de/docs/japanese-layout.md) erklären die Konventionen dahinter. Sie behalten ihren Text: Die Zeichen zwischen den Klammern bleiben im Absatz (Suche, Inhaltsverzeichnis, Registeranker und kopierter Text lesen sie so, wie sie geschrieben sind), und die Direktiven nehmen die anderen Inline-Auszeichnungen in sich und um sich herum an, verschachtelte eingeschlossen. Schreiben Sie `\]` für eine wörtliche Klammer. ```markdown 此事:dots[不可]輕忽。:name[賈寶玉]與:name[林黛玉]讀:book[西廂記]。 {滿紙|mǎn|zhǐ}荒唐言，:ruby[一把]{rt="yì bǎ"}辛酸淚！:ruby[都]{rt="ㄉㄡ"}云作者痴。 寶玉:warichu[甲戌側批：此是第一首標題詩。]{open="〔" close="〕"}道：…… {東京|とう|きょう}の:ruby[紫陽花]{rt="あじさい"}は*とんと*:sideline[見事]だ。:book[こころ]を読む。 :kunten[學]{okuri="ビテ"}而:kunten[時]{okuri="ニ"}:kunten[習]{kaeri="二" okuri="フ"}:kunten[之]{kaeri="一" okuri="ヲ"}。 ``` - **`:dots[text]`** setzt einen Betonungspunkt (着重号) unter jedes Zeichen in waagerechtem Text, rechts daneben in senkrechtem Text, und keinen auf Satzzeichen oder Leerzeichen. `style="dot|circle|sesame"` (Standard `dot`), `fill="open"` für eine Kontur, `pos="over|under"` für die andere Seite. Markdown-Hervorhebung `*…*` auf chinesischen oder japanischen Zeichen bewirkt dasselbe unter `cjk.emphasis: 'dots'`, der Voreinstellung in einem chinesischen oder japanischen Dokument; lateinische Buchstaben in derselben Hervorhebung bleiben kursiv. Weggelassene Attribute übernehmen `cjk.emphasisMark`: im Chinesischen ein Punkt unter dem Text, im Japanischen ein Sesam darüber (in senkrechtem Text rechts daneben). - **`:name[text]`** zieht die Eigennamenlinie (专名号) unter den Text (in senkrechtem Text links daneben), und **`:book[text]`** setzt das Buchtitelzeichen (书名号): 《》 um den Titel (〈〉 für einen Titel in einem anderen), die Wellenlinie klassischer und taiwanischer Ausgaben oder nichts, wie `cjk.bookTitleMark` es angibt (standardmäßig Klammern auf dem Festland und in Japan, die Wellenlinie in Taiwan und Hongkong). In einem japanischen Dokument sind die Klammern 『』 und 「」 für einen Titel in einem anderen (`cjk.bookTitleBrackets`). Eine Quelle dient so einer modernen Festlandausgabe wie einer klassischen. Zwei Namen oder Titel nebeneinander halten ihre Linien getrennt. - **`:ruby[base]{rt="…"}`** setzt Lesungen über die Basis (Pinyin) oder rechts neben jedes Zeichen (Zhuyin, die Voreinstellung für Bopomofo-Lesungen). Bei ebenso vielen Lesungen wie Zeichen, getrennt durch Leerzeichen oder `|`, erhält jedes Zeichen seine eigene, und zwischen ihnen darf eine Zeile umbrechen (Mono-Ruby); `group` oder eine Anzahl, die nicht passt, setzt eine Lesung zentriert über die ganze Basis, die nie umbricht. `pos="over|under|right"` wählt die Seite. Die Kurzform `{紅樓|hóng|lóu}` (eine Lesung je `|`) oder `{紅樓|hónglóu}` (eine Lesung für die ganze Basis) liest sich gleich, aber nur, wenn die Basis ein Han-, Kana- oder Bopomofo-Zeichen enthält, und außerhalb von Formeln, Code und Attributen, sodass `{x|x>0}` in lateinischem Text Text bleibt. Ein Backslash vor der Klammer oder dem Strich lässt eine chinesische Kurzform Text bleiben: `{紅|hóng}` und `{紅\|hóng}` drucken `{紅|hóng}`. Eine Basis, die eine Zeile eröffnet oder schließt, richtet sich mitsamt ihrer Lesung an diesem Rand aus. `mode=mono|group|jukugo` wählt, wie die Lesungen über die Basis verteilt werden (`mode=group` entspricht `group`), und `align=center|jis|start`, wie eine Lesung, die kürzer ist als ihre Basis, gesperrt wird. In einem japanischen Dokument ist die Form je Zeichen für ein Wort aus zwei oder mehr Zeichen (`{東京|とう|きょう}`, `rt="とう|きょう"`) Jukugo-Ruby: Jedes Zeichen behält seine Lesung, die auf das nächste Zeichen des Worts übergreifen darf, die Zeile darf zwischen ihnen umbrechen, und die Lesungen werden so gesperrt und greifen so auf Kana über, wie `cjk.ruby.align` und `cjk.ruby.overhang` es angeben; eine Lesung für die ganze Basis (`{紫陽花|あじさい}`, das `《》` von Aozora) ist Gruppen-Ruby; `mode=mono` behält eine Lesung je Zeichen, ohne Übergreifen auf die Nachbarn. - **`:sideline[text]`** zieht eine Seitenlinie (傍線) neben den Text, Satzzeichen und Leerzeichen eingeschlossen: darunter in waagerechtem Text, rechts daneben in senkrechtem Text. `style="solid|double|wavy|dotted"` (Standard `solid`), `pos="over|under"` (in senkrechtem Text ist „over“ rechts und „under“ links; `position=` funktioniert ebenfalls). Es funktioniert in jeder Schrift, auch für eine unterstrichene englische Wendung. - **`:warichu[note]`** setzt eine Anmerkung (双行夹注) in zwei Zeilen in halber Textgröße innerhalb der Zeile, die obere Zeile wird zuerst gelesen (in senkrechtem Text die rechte). Eine lange Anmerkung füllt den Rest der Zeile und setzt sich in der nächsten Zeile, Spalte oder Seite fort, mit mindestens zwei ihrer Zeichen auf jeder Seite des Umbruchs (`cjk.warichu.minChars`). `open` und `close` schließen sie in Klammern in Textgröße ein; `cjk.warichu` legt Größe, Farbe und Standardklammern fest (（） in einem japanischen Dokument). Eine Anmerkung in lateinischer Schrift bricht zwischen ihren Wörtern um. - **`:kunten[字]{kaeri="…" okuri="…" tate}`** setzt die Kanbun-Zeichen des letzten Zeichens zwischen den Klammern: `kaeri` das Rückkehrzeichen (レ, 一 二 三, 上 中 下, 甲 乙 丙, 天 地 人 sowie 一レ 上レ 甲レ 天レ; die Codepunkte ㆑ ㆒ … werden gleich gelesen), `okuri` das Okurigana (die Klammern `（ヲ）` von Aozora entfallen) und der Schalter `tate` den Tatesen, der es mit dem nächsten Zeichen verbindet. Der Text wird nicht umgestellt: Die Zeichen werden in halber Größe daneben gesetzt (`cjk.kunten`), und kopierter Text lautet 學ビテ而時ニ習フ之ヲ, mit dem Okurigana und ohne die Rückkehrzeichen. Ein Ruby darin funktioniert für zweimal gelesene Zeichen: `:kunten[:ruby[未]{rt="ザル" pos=under}]{kaeri="レ" okuri="ダ"}`. Der Zeilenabstand ändert sich nie: Zeichen und Lesungen sitzen im Durchschuss, und der Build warnt, wenn der Zeilenzwischenraum eines Absatzes für sie zu schmal ist (`cjkMarksExceedLeading`, `rubyExceedsLeading`, `kuntenExceedsLeading`) und wenn die Zeichen unter einer Zeile und die Lesungen über der nächsten nicht in den Zwischenraum passen, den sie sich teilen, in einem Absatz oder über zwei hinweg. Geben Sie annotierten Absätzen ein Absatzformat mit mehr Zeilenabstand. Zeichen, Lesungen und Anmerkungen werden in Absätzen, Überschriften, Listeneinträgen, Zitaten und Kästen gezeichnet, ebenso in Legenden, Tabellenzellen und Anmerkungen, deren Zeilenabstand auf dieselbe Weise geprüft wird; in Kolumnentiteln und Gestaltungen wird der Text ohne sie gedruckt. Unter `cjk.bookTitleMark: 'brackets'` sind die 《》 eines Titels Satzzeichen des Texts: Legenden, Zellen, Anmerkungen, Zeilen des Inhaltsverzeichnisses, Lesezeichen und Registereinträge behalten sie. Siehe [Konfiguration › Zeichen, Ruby und Warichu](https://postext.dev/de/docs/configuration-east-asian.md#zeichen-ruby-und-warichu). ### Schreibrichtung in der Auszeichnung Ein Dokument läuft in der Richtung, die sein `locale` vorgibt (`direction` in der Konfiguration: von rechts nach links für Arabisch, Persisch, Urdu oder Hebräisch). Darin legt die Auszeichnung die Richtung eines Blocks oder einer Textfolge fest, für ein englisches Zitat in einem arabischen Buch oder ein arabisches in einem englischen Buch. - **Eine Überschrift oder ein Container**: `{dir=ltr}` oder `{dir=rtl}` in ihren Attributen, `# Introduction {dir=ltr}`, `:::paragraphs{dir=ltr}`, `:::callout{dir=rtl}`. Jeder Block in einem Container übernimmt die Richtung, bis hinab zu einem verschachtelten Container oder einer Überschrift, die eine andere festlegt. Ein einfacher Absatz, eine Liste oder ein Zitat hat keine eigenen Attribute: Schließen Sie ihn in `:::paragraphs{dir=…}` ein. Andere Werte werden ignoriert. Das `lang` eines Containers (`:::paragraphs{dir=ltr lang=en}`) benennt auf dieselbe Weise die Sprache der Blöcke darin: Ihre geordneten Listen zählen in den Ziffern dieser Sprache. - **Eine Textfolge**: `:ltr[…]` und `:rtl[…]` isolieren ihren Text (die LRI…PDI und RLI…PDI des Unicode-Bidi-Algorithmus): Innen wird er geordnet, und der umgebende Absatz sieht ein einziges neutrales Zeichen. `{lang=…}` kennzeichnet die Sprache der Folge im HTML und im PDF. Eine Anmerkungsmarke, ein `:ref` oder eine Formel darin gehört zur Isolierung, und Isolierungen lassen sich verschachteln. ```markdown :::paragraphs{dir=ltr} The opening of the *Nights* in Lane's translation. ::: ترجمها :ltr[Edward William Lane]{lang=en} سنة ١٨٣٩. ``` Ein Block, der gegen die Richtung des Dokuments gesetzt ist, behält seine eigene Anfangsseite: Einzug, Listenmarken und das bündige Ende seiner letzten Zeile wandern auf die Seite, auf der sein Text beginnt. Verwenden Sie eine Isolierung, wenn ein lateinischer Titel auf ein neutrales Zeichen endet (einen Punkt, eine Klammer), das sich sonst dem umgebenden Arabisch anschließen würde. Die Unicode-Steuerzeichen selbst (U+2066–2069, U+202A–202E, U+200E, U+200F, U+061C) werden ebenfalls beachtet. Im Editor der Sandbox läuft jede Zeile in der Richtung ihres ersten Buchstabens. Siehe [Arabischer Satz](https://postext.dev/de/docs/arabic-layout.md#richtung-und-bidirektionaler-algorithmus). ## Fußnoten Eine Fußnote hat zwei Teile: die Marke `[^id]` an der Stelle, an der die Anmerkung zitiert wird, und die Definition, einen eigenen Absatz, der irgendwo im Kapitel mit `[^id]:` beginnt. ```md The keeper climbed the tower every evening.[^steps] The wind put out his candle, so he learned to count the steps in the dark. [^steps]: The cast-iron staircase has 112 steps; the tower was built in 1861. ``` - **Marke.** `[^id]` druckt die Nummer der Anmerkung hochgestellt, angehängt an das Wort davor (schreiben Sie sie wie oben nach dem Satzzeichen). Die ID besteht aus Buchstaben, Ziffern, `-`, `_`, `.` und `:`. Die Marke funktioniert in Absätzen, Listeneinträgen, Zitaten und Kästen; in Überschriften, Legenden und Tabellenzellen wird sie so gedruckt, wie sie geschrieben ist. - **Definition.** Ein Absatz, der mit `[^id]:` beginnt; sein Text reicht bis zur nächsten Leerzeile und nimmt die üblichen Inline-Auszeichnungen an (fett, kursiv, Links, `:ref`, Formeln, Chips). Definitionen verlassen den Fluss, wo immer sie stehen; sie können also unter dem Absatz stehen, der sie zitiert, oder gesammelt am Ende des Kapitels. Die erste Definition einer ID gilt. - **Nummern.** Anmerkungen werden in der Reihenfolge ihrer ersten Zitierung nummeriert, in jedem Kapitel neu beginnend (eine Überschrift der Ebene 1 und jedes Dokument eines Buchs); eine zweimal zitierte Anmerkung behält ihre erste Nummer und wird einmal gesetzt. `footnotes.numbering: 'document'` zählt die Nummern durch das ganze Buch weiter, und `'page'` beginnt sie auf jeder Seite neu, wie es chinesische Bücher tun; `footnotes.numberFormat: 'circled-decimal'` schreibt ① ② ③ auf die Grundlinie. `footnotes.numberFormat: 'symbols'` kennzeichnet sie mit `*`, `†`, `‡`, `§`, `‖`, `¶`, danach verdoppelt, auf jeder Seite neu beginnend, wie in Fachzeitschriften. - **Japanischer Text.** Schreiben Sie die Marke vor ein satzschließendes 。 (`先生[^1]。`): Sie bleibt beim Zeichen davor, und 。 eröffnet nie eine Zeile. Ein senkrecht gesetztes japanisches Buch setzt seine Marken （1） standardmäßig rechts neben die Zeile und seine Anmerkungen hinter das Kapitel; `footnotes.markerPosition: 'side'` setzt eine kleine Marke neben das Wort, ohne Platz in der Zeile einzunehmen, und `footnotes.placement: 'spread'` setzt die Anmerkungen neben den Text jeder Doppelseite (siehe [Konfiguration › Fußnoten](https://postext.dev/de/docs/configuration-notes-references.md#fußnoten)). - **Wohin die Anmerkung kommt.** Standardmäßig an den Fuß der Spalte, die die zitierende Zeile enthält, unter eine kurze Linie: Zeile und Anmerkung teilen sich immer eine Spalte, und eine Zeile, deren Anmerkung nicht passt, wandert mit ihr weiter. In einem einspaltigen Layout ist das der Fuß der Seite. `footnotes.placement: 'chapterEnd'` setzt stattdessen alle Anmerkungen eines Kapitels hinter dessen letzten Block, standardmäßig an den Fuß der Spalte, die sie abschließen. Größen, Linie und Abstände finden Sie unter [Fußnoten](https://postext.dev/de/docs/configuration-notes-references.md#fußnoten) in der Konfigurationsreferenz. - **Prüfungen.** Eine Marke ohne Definition (`undefinedFootnote`) druckt ihre Nummer über einer leeren Anmerkung; eine Definition, die keine Marke zitiert (`unusedFootnote`), wird nicht gesetzt. Die Sandbox führt beide im Bedienfeld Prüfungen auf. ## Querverweise und Anker Ein Querverweis benennt eine Stelle im Buch und druckt ihre Nummer, ihren Titel oder ihre Seite: *siehe Abschnitt 3.2*, *wie Kapitel 4 erläutert*, *auf S. 112*. Wörter und Nummern folgen dem Text; wird ein Abschnitt verschoben, werden die Kapitel neu nummeriert oder das Buch neu umbrochen, aktualisiert sich jeder Verweis. Im PDF, im HTML und in den Vorschauen der Sandbox ist jeder Verweis ein Link: Ein Klick führt den Leser zu seinem Ziel, auch in ein anderes Kapitel. **Anker.** Ein Verweis braucht etwas, worauf er zeigt: - **Eine Überschrift** mit einem Bezeichner: `## Method {#sec-method}` (die Form von Pandoc; `id="sec-method"` funktioniert ebenfalls). - **Ein Kasten oder ein anderer Container**, der mit einem Bezeichner geöffnet wird: `:::callout{#box-safety title="Safety"}`. Auf einen Kasten eines nummerierten Formats (ein Theorem) wird mit seiner Bezeichnung und Nummer verwiesen: *Theorem 2*. - **Eine abgesetzte Formel** mit einem `\label{eq:x}` (siehe [Mathematische Formeln](https://postext.dev/de/docs/document-format.md#mathematische-formeln)): Ein Verweis druckt ihre Nummer so, wie die Formel es tut, *(3)*. - **Eine Stelle im Text**: `:anchor{#key-idea}` setzt einen unsichtbaren Anker; `[the key idea]{#key-idea}` behält seine Wörter und benennt sie. Ein Bezeichner besteht aus Buchstaben, Ziffern, `-`, `_`, `.` und `:`. Er muss im Buch eindeutig sein: Das Bedienfeld Prüfungen führt einen doppelt gesetzten auf (`duplicateAnchor`), und Verweise erreichen sein erstes Vorkommen. **Verweise.** `:ref{id="…"}` benennt einen Anker so, wie es eine Abbildung oder eine Tabelle benennt: ```md ## Method {#sec-method} The results of :ref{id="sec-method"} hold on :ref{id="sec-method" style=page}. ``` | `style` | druckt | | --- | --- | | *(keiner)* | eine nummerierte Überschrift mit ihrem Wort und ihrer Nummer (*Abschnitt 3.2*, *Kapitel 4*), eine nicht nummerierte Überschrift mit ihrem Titel, einen Anker mit seinem Text, eine Gleichung mit ihrer Nummer, wie sie gedruckt ist (*(3)*), einen nummerierten Kasten mit seiner Bezeichnung und Nummer (*Theorem 2*) | | `number` | nur die Nummer (*3.2*, *3*, *2*) | | `title` | den Titel der Überschrift, den Text des Ankers oder den `title` des Kastens | | `page` | die Seite, auf der das Ziel gelandet ist (*S. 112*) | | `pageNumber` | nur die Seitenzahl (*112*) | `\eqref{x}` und `\ref{x}` aus LaTeX funktionieren auch im Text: `\eqref` als Verweis ohne Format, `\ref` als `style=number`, sodass `\ref{thm:main}` *2* druckt und `\ref{fig:map}` die Nummer einer Abbildung. Ein `~` direkt davor ist ein geschütztes Leerzeichen (`Theorem~\ref{thm:main}`). Innerhalb von `$…$` gehören sie zur Formel. `text="…"` druckt Ihre eigenen Wörter und verlinkt trotzdem; `case=capitalize` beginnt die Bezeichnung mit einem Großbuchstaben (*Section 3.2* am Satzanfang). Die Wörter folgen der Dokumentsprache (*sección 3.2*, *第3.2节*, *S. 112*) und lassen sich unter [Querverweise](https://postext.dev/de/docs/configuration-notes-references.md#querverweise) in der Konfiguration ändern; eine Überschriftennummer, die ihre Vorlage bereits ausschreibt (*Chapter 4*, *第四章*), wird so gedruckt, wie sie ist. **Zeilenumbrüche.** Ein Verweis, der Wörter druckt, bricht wie der umgebende Text an seinen Leerzeichen um: der Text eines Ankers (`[close the lever so that it points backwards]{#step}`), ein Titel, Ihr eigenes `text="…"`. Seine Leerzeichen sind Leerzeichen der Zeile, sodass sie sich auf einer Zeile im Blocksatz mit den anderen dehnen, und der Verweis bleibt ein einziger Link, in zwei Stücken, wenn er über zwei Zeilen läuft. Seine Wörter werden nie getrennt. Innerhalb einer solchen Bezeichnung bleibt eine Zahl, eine römische Zahl oder ein einzelner Buchstabe beim Wort davor, sodass `text="Fig. 1a"` oder `text="plate IV"` nie getrennt wird. Eine Bezeichnung, die eine Nummer oder eine Seite enthält (*Abschnitt 3.2*, *S. 112*, *Abb. 1.7*, *Theorem 2*), bricht nie um, gleich welchen Zwischenraum ihre Vorlage enthält, und ein geschütztes Leerzeichen in einer Bezeichnung verbindet wie überall. `crossRefs.breakLabels: false` hält jede Bezeichnung ganz, wie bis postext 1.27, als eine Bezeichnung ein einziges Wort war, das nicht in die Zeile davor hinaufrücken konnte; siehe [Querverweise](https://postext.dev/de/docs/configuration-notes-references.md#querverweise). **Seitenverweise** sind erst bekannt, wenn das Buch gesetzt ist. Die Engine setzt das Dokument mit den Seiten des vorigen Durchgangs erneut, bis sie stabil bleiben, wie beim Inhaltsverzeichnis; bis dahin druckt eine Seite *?*. **pandoc-crossref.** Für pandoc-crossref geschriebener Text liest sich gleich: `@sec:method`, `[@fig:map]` und `[-@tbl:data]` für die bloße Nummer. Das Präfix (`sec`, `fig`, `tbl`, `eq`, `lst`) kann Teil des Bezeichners sein (`{#sec:method}`) oder fehlen (`{#method}`). Ein `@`, das direkt an einem Wort klebt, wie in einer E-Mail-Adresse, bleibt Text. Ein Verweis auf eine ID, die nichts setzt, druckt *?*, und das Bedienfeld Prüfungen führt ihn auf (`unknownResourceId`). Im Editor der Sandbox bietet `@` die Abbildungen, Tabellen, Überschriften mit ID und Anker des Buchs an. ## Zitate und Literaturverzeichnis Schreiben Sie Zitate so, wie Pandoc sie liest, halten Sie die Literaturangaben im Dokument und wählen Sie den Zitierstil in den Einstellungen: Der Wechsel von APA zu IEEE oder zu Chicago-Anmerkungen ändert die Stileinstellung, nicht den Text. Jedes Zitat verlinkt auf seinen Eintrag im Literaturverzeichnis. ### Zitieren ```md As [@garcia2020, p. 33] shows, reading on paper is faster [see @lopez2019, chap. 2; @bringhurst2004]. @garcia2020 [p. 4] says it plainly; the 2020 study [-@garcia2020] agrees. ``` - **`[@key]`** zitiert in Klammern; mehrere Werke stehen in einem Klammerpaar, getrennt durch `;`. - **Fundstelle:** nach einem Komma `p. 33`, `pp. 4–6`, `chap. 2`, `sec. IV`, `fig. 3`, `vol. 2`, `n. 12`, `l. 4`, `§ 4.2`; eine bloße Zahl ist eine Seite. Spanische (`pág.`, `cap.`) und chinesische (`页`, `章`) Wörter funktionieren ebenfalls. Ein Bereich nimmt einen Halbgeviertstrich oder die zwei Bindestriche von TeX: `pp. 4--6` druckt *4–6*. - **Präfix und Suffix:** Text vor dem `@` (`see`) und nach dem Schlüssel oder der Fundstelle (`, emphasis added`). Das Suffix behält das davor geschriebene Komma, mit oder ohne Fundstelle: `[@brown2020, inter alia]` druckt *(Brown et al., 2020, inter alia)*, wie bei Pandoc; ohne Komma geschrieben (`[@brown2020 inter alia]`) hat es keines. Hervorhebung in einem Präfix oder Suffix wird in jedem Stil als Hervorhebung gesetzt: `[*e.g.*, @brown2020, *inter alia*]`. - **`[-@key]`** lässt den Autor weg, für einen Satz, der den Autor bereits nennt. - **`@key`** zitiert im Satz (*García (2020)*); `@key [p. 4]` fügt eine Fundstelle hinzu. - **In Legenden:** Die Legende einer Abbildung oder Tabelle und ihre Anmerkung zitieren wie der Text (`Prior best from [@cobbe2021].`). Ihre Werke gelangen ohne `nocite` ins Literaturverzeichnis, und ein nummerierter Stil nummeriert sie dort, wo die Ressource platziert wird: nach den Zitaten des Absatzes, der zuerst auf sie verweist (ihr Block `::resource` oder ihr erstes `:ref`). Ein Zitat in einer Tabellenzelle bleibt Text. - Ein `@`, das an einem Buchstaben oder einer Ziffer klebt (eine E-Mail-Adresse), ein `@` in Inline-Code und `\@` sind Text. Ein Zitat, für das das Buch keine Literaturangabe hat, wird so gedruckt, wie es geschrieben ist, sodass sich ein Dokument ohne Literaturangaben wie zuvor liest. In einem Zitat mehrerer Werke wird ein Schlüssel, den keine Literaturangabe definiert, fett hinter den anderen gedruckt (`(Glen, 1955) **@nye1953**`), sodass das fehlende Werk auf der Seite ebenso sichtbar ist wie unter den Warnungen. Ein Doppelpunkt nach einem Zitat ist Text: `[@french2018]: the land…`. - In chinesischem, japanischem und koreanischem Text folgt ein Zitat ohne Leerzeichen auf das letzte Zeichen (`周明远@zhou2019认为`), und ein Autor-Jahr-Zitat übernimmt die Satzzeichen voller Breite des umgebenden Texts: `（施雅风等，1988；刘时银等，2015）`. ### Literaturangaben Literaturangaben werden im Dokument geschrieben, in CSL-Form (dem Datenmodell von Zotero und Pandoc): ```md --- references: - id: garcia2020 type: book author: [{family: García, given: Ana}] title: Tipografía y lectura issued: 2020 publisher: Trea nocite: "@lopez2019" --- ``` oder in einem Block `:::references`, in BibTeX (ein Export aus Zotero, JabRef oder Google Scholar), CSL-JSON oder CSL-YAML: ```md :::references{format=bibtex} @article{lopez2019, author = {López, Luis and Ruiz, Eva}, title = {Leer en pantalla}, journal = {Revista de Letras}, year = 2019, volume = 12, pages = {45--67}, doi = {10.1000/xyz}} ::: ``` Der Block druckt nichts. `nocite` führt Werke auf, ohne sie zu zitieren (`@*`: alle). In einem Buch gelten Literaturangaben aus jedem Kapitel für das ganze Buch. In einer BibTeX-Namensliste steht `and others` für die weggelassenen Namen (`author = {Tan, Wei and others}`): Jeder Stil druckt an seiner Stelle *et al.* In YAML schreiben Sie `others` als letzten Namen der Liste. ### Das Literaturverzeichnis `:::bibliography` setzt die Liste der zitierten Werke dort, wo es steht; ohne einen solchen Block folgt die Liste auf das letzte Kapitel, betitelt in der Dokumentsprache (*References*, *Referencias*, *参考文献*). `:::bibliography{title="Works cited"}` ändert den Titel, und `title=""` lässt ihn weg; `scope=chapter` führt die Werke auf, die das Kapitel zitiert (ein Sammelband). Jeder Eintrag ist ein Anker (`ref-`), sodass ein Markdown-Link auf `#ref-garcia2020` ihn erreicht, und das PDF taggt ihn als `BibEntry`. `scope=new` führt die bisher im Dokument zitierten Werke auf, die keine vorherige Liste gedruckt hat, in der Reihenfolge des Stils und mit seinen Nummern: Ein `:::bibliography{scope=new}` nach dem Haupttext und ein weiteres nach den Methoden ergeben die zwei Listen eines Nature-Artikels, die zweite von der ersten an weiternummeriert. Ein nummerierter Stil zählt seine Zitate durch das ganze Buch; mit `citations.numbering: 'chapter'` nummeriert jedes Kapitel (jedes Dokument und jede Überschrift der Ebene 1 nach einem Zitat) seine eigenen ab 1, und seine Kapitelliste übernimmt diese Nummern, wie es die Berichte eines Bulletins oder die Beiträge eines Tagungsbands tun. ### Zitierstile Der Stil entscheidet, was ein Zitat und ein Eintrag aussagen. Die mitgelieferten Stile sind unten aufgeführt; jeder andere CSL-Stil (im Stil-Repository von Zotero gibt es mehr als zehntausend) lässt sich aus seiner `.csl`-Datei unter **Einstellungen → Zitate** laden. | `citations.style` | Name | System | | --- | --- | --- | | `apa` | APA 7 | Autor-Jahr | | `chicago-author-date` | Chicago (Autor-Jahr) | Autor-Jahr | | `harvard-cite-them-right` | Harvard | Autor-Jahr | | `iso690-author-date-en`, `iso690-author-date-es` | ISO 690 | Autor-Jahr | | `china-national-standard-gb-t-7714-2025-author-date` | GB/T 7714—2025 著者-出版年 | Autor-Jahr | | `china-national-standard-gb-t-7714-2015-author-date` | GB/T 7714—2015 著者-出版年 | Autor-Jahr | | `modern-language-association` | MLA 9 | Autor-Seite | | `ieee` | IEEE | nummeriert | | `elsevier-vancouver` | Vancouver | nummeriert | | `american-medical-association` | AMA | nummeriert | | `nature` | Nature | nummeriert | | `iso690-numeric-en` | ISO 690 | nummeriert | | `china-national-standard-gb-t-7714-2025-numeric` | GB/T 7714—2025 顺序编码 | nummeriert | | `china-national-standard-gb-t-7714-2015-numeric` | GB/T 7714—2015 顺序编码 | nummeriert | | `sist02` | SIST 02 参照文献の書き方 | nummeriert | | `chicago-notes-bibliography` | Chicago (Anmerkungen) | Anmerkungen | | `oscola` | OSCOLA | Anmerkungen | | `china-national-standard-gb-t-7714-2025-note` | GB/T 7714—2025 注释 | Anmerkungen | | `china-national-standard-gb-t-7714-2015-note` | GB/T 7714—2015 注释 | Anmerkungen | Bei einem **Anmerkungsstil** wird jedes Zitat zu einer Fußnote, platziert und nummeriert nach den Fußnoteneinstellungen; spätere Zitate desselben Werks nehmen eine Kurzform an. In chinesischem Text setzt `citations.notes: 'warichu'` sie als zweizeilige Anmerkungen in die Zeile (夹注); eine Anmerkung, auf die ein chinesisches Satzzeichen folgt (`，`, `。`), verliert ihren eigenen Schlusspunkt. **Chinesisch.** Die Stile nach GB/T 7714-2015 schreiben die Dokumenttyp-Codes (`[M]`, `[J]`, `[D]`, `[EB/OL]`), lassen chinesische Namen ungeteilt und schreiben `等` nach drei Autoren eines chinesischen Werks und `et al.` nach denen eines westlichen, je nach der `language` jedes Werks. In senkrechtem Text steht eine hochgestellte Nummer rechts neben ihrem Zeichen; `citations.marker: 'corner'` schreibt `〔1〕`, das aufrecht bleibt. **Engine.** Zitate werden vom Paket `postext-citeproc` formatiert (citeproc-js und die CSL-Stile). Die Sandbox lädt es für Dokumente, die zitieren; in Ihrem eigenen Code registrieren Sie es vor dem Setzen: ```ts import 'postext-citeproc/register'; ``` Das Bedienfeld Prüfungen führt einen Schlüssel auf, den keine Literaturangabe definiert (`unknownCitationKey`), sowie einen Literaturblock, der sich nicht lesen lässt (`referencesUnreadable`). ## Register Ein Register führt die Begriffe eines Buchs mit den Seiten auf, auf denen sie vorkommen. Markieren Sie jeden Begriff dort, wo der Text ihn behandelt, und drucken Sie das Register mit `:::index` an der Stelle, an die es gehört, meist in einem eigenen Kapitel am Ende. Die Engine ermittelt die Seite jeder Marke nach dem Setzen, sodass die Zahlen dem Text folgen: Fügen Sie einen Absatz hinzu, verschieben Sie ein Kapitel oder ändern Sie das Endformat, und das Register druckt die neuen Seiten. ```md Iron-deficiency :index[anaemia] is the most common kind. The pulse is taken at the wrist.:index{term="Pulse!radial" main} # Index {style="index"} :::index ``` ### Registermarken - **`:index[text]`** druckt `text` und ordnet ihn unter seinen eigenen Wörtern ein. Inline-Auszeichnungen darin werden gedruckt und aus dem Eintrag entfernt. Attribute nach der Klammer ordnen ihn anderswo ein: `:index[iron deficiency]{term="Anaemia!iron-deficiency"}`. - **`:index{term="…"}`** druckt nichts. Die Marke übernimmt die Seite des Worts, das auf ihrer Zeile direkt vor ihr steht, oder, wenn sie eine Zeile eröffnet, die des Worts danach. Eine Zeile, die nur Marken enthält, wird entfernt, sodass eine Marke auf einer eigenen Zeile nie einen Absatz teilt oder Abstand hinzufügt. - **Wo.** Absätze, Überschriften, Listeneinträge, Zitate, Kästen und Fußnotendefinitionen. In Legenden, Tabellenzellen und Gestaltungselementen wird eine Marke so gedruckt, wie sie geschrieben ist. In Inline-Code und nach einem Backslash (`\:index`) ist sie Text. | Attribut | Wirkung | | --- | --- | | `term` | Der Eintrag, seine Ebenen durch `!` getrennt: `term="Heart!valves!mitral"` ordnet die Seite unter *mitral* ein, einem Untereintrag von *valves* unter *Heart*. Eine Ebene kann Inline-Auszeichnungen tragen (`term="*Escherichia coli*"`); sortiert wird sie ohne sie. Ohne `term` verwendet `:index[text]` seinen Text. | | `sub` | Eine nach `term` hinzugefügte Ebene: `term="Heart" sub="valves"` entspricht `term="Heart!valves"`. | | `sort` | Der Sortierschlüssel der letzten Ebene, wenn sie nach anderen Buchstaben sortiert werden soll: `:index[St Kilda]{sort="Saint Kilda"}`, `term="20th century" sort="twentieth century"`. Ein chinesisches Register sortiert und gruppiert nach der Lesung, die die Kollation einem Zeichen gibt. Für ein Zeichen mit mehreren Lesungen, das anders gelesen wird, schreiben Sie den Schlüssel in Zeichen, die nur die gewünschte Lesung haben: `:index[重阳]{sort="崇阳"}` ordnet 重阳 unter C ein, zwischen 程 und 崔, nicht unter Z. Ein Pinyin-Schlüssel (`sort="chong yang"`) erreicht ebenfalls C, sortiert aber hinter alle chinesischen Einträge von C, weil die Kollation lateinische Buchstaben hinter chinesische Zeichen setzt (siehe [Konfiguration › Register](https://postext.dev/de/docs/configuration-notes-references.md#register), `groupBy`). | | `yomi`, `reading` | Die Lesung der letzten Ebene in Kana, nach der ein japanisches Register sie sortiert und gruppiert: `:index[夏目漱石]{yomi="なつめそうせき"}` wird unter な eingeordnet, in der な-Reihe. Ohne sie wird eine Marke, deren Text Furigana in Kana trägt, über diese gelesen (`:index[{東京\|とう\|きょう}]` sortiert als とうきょう), dann über `sort`, dann über den Text; ein Eintrag, der weiterhin mit einem Kanji beginnt, wird als `indexReadingMissing` gemeldet. In einem Register in einer anderen Sprache wirkt `yomi` wie `sort`. Schreiben Sie Furigana in einer Marke in der Kurzform: Ein `:ruby[…]` bräuchte maskierte Klammern. Seit postext 1.16. | | `main` | Ein Schalter: die Hauptbehandlung des Begriffs. Ihre Seitenzahl wird fett gesetzt (`index.main`). Eine auf beide Arten markierte Seite ist fett. | | `range` | `range="start"` und `range="end"` mit demselben Begriff begrenzen eine Behandlung, die über mehrere Seiten läuft: Der Eintrag druckt `34–37`. Ein Anfang ohne Ende oder ein Ende ohne Anfang druckt seine eine Seite und löst `indexRangeUnclosed` aus. | | `see` | Ein Querverweis statt einer Seitenzahl: `:index{term="Cardiac insufficiency" see="Heart failure"}` druckt *Cardiac insufficiency. See Heart failure*. Ebenen des Ziels werden durch `!` getrennt und mit einem Doppelpunkt gedruckt (*See Heart: valves*). Ein Ziel, das kein Eintrag des Registers ist, löst `indexSeeUnknown` aus. | | `seealso` | Ein Querverweis nach den Seitenzahlen des Eintrags: *Heart, 12, 40. See also Circulation*. Die eigene Seite der Marke zählt wie die jeder anderen Marke, sodass eine Marke eine Passage registrieren und auf einen verwandten Eintrag zeigen kann; eine Marke `see` fügt keine Seite hinzu. | | `index` | Der Name eines eigenen Registers: `index="names"` ordnet die Marke in das Register ein, das `:::index{index="names"}` druckt, nicht in das Hauptregister. | Eine Marke ohne Begriff (`:index{}` oder `:index{see="…"}` allein) registriert nichts und löst `indexMarkInvalid` aus. ### Das Register drucken `:::index` druckt das Hauptregister dort, wo es steht, und `:::index{index="names"}` ein benanntes. Die Direktive entfaltet sich zu gewöhnlichen Blöcken, einem je Eintrag, die wie Text durch Spalten und Seiten fließen: Unter einer Überschrift, deren [Überschriftenstil](https://postext.dev/de/docs/configuration-styles.md#überschriftenstile) ein zweispaltiges `layout` festlegt, ergibt sie das übliche zweispaltige Register. Ein Klick auf einen Eintrag führt zur Zeile der Direktive. ```md # Index of names {style="index"} :::index{index="names"} # Index of subjects {style="index"} :::index ``` - **Reihenfolge.** Einträge werden in der alphabetischen Reihenfolge der Dokumentsprache sortiert (`locale` oder `index.locale`): Ein Buchstabe mit Akzent wird bei seinem Grundbuchstaben eingeordnet (*Árbol* unter A), und im Spanischen folgt *ñ* auf *n*, unter einem eigenen Kopf. Einträge, die mit einem Symbol beginnen, kommen zuerst, dann die mit einer Ziffer, dann die Buchstaben. Untereinträge werden unter ihrem Eintrag ebenso sortiert, um eine Stufe je Ebene eingerückt. Ein japanisches Register sortiert nach der Lesung in der Reihenfolge von JIS X 4061 und gruppiert nach Gojūon-Reihen (あ行, か行 …), seine lateinischen Einträge vor den Kana (siehe [Japanischer Satz › Register in Gojūon-Ordnung](https://postext.dev/de/docs/japanese-layout.md#register-in-gojūon-ordnung)). - **Gruppen.** Jeder neue Anfangsbuchstabe eröffnet eine Gruppe: einen Buchstabenkopf (`index.groups`) und eine Leerzeile darüber (keine über der ersten Gruppe). Der Kopf wird in einem Block mit dem ersten Eintrag der Gruppe gesetzt, sodass er nie allein eine Spalte beschließt; ein Eintrag ohne eigene Seite (einer, der nur seine Untereinträge anführt) wird aus demselben Grund mit seinem ersten Untereintrag gesetzt. - **Seitenzahlen.** Die Bezeichnungen, die die Seiten drucken, römische in der Titelei eingeschlossen. Die Seiten eines Eintrags werden sortiert und jede einmal aufgeführt; aufeinanderfolgende Seiten verbinden sich zu einem Bereich (`12–14`, `index.mergeRanges`), eine Seite innerhalb eines Bereichs desselben Eintrags geht in ihm auf (eine Hauptseite darin macht den Bereich fett), und `index.rangeFormat: 'chicago'` kürzt die zweite Zahl (`234–37`). Fette Seiten (Hauptstellen) bleiben getrennt. Im PDF verlinkt jede Zahl auf ihre Seite. - **Querverweise** schließen den Eintrag ab: *Begriff. See Ziel*, wenn der Eintrag keine Seiten hat, *Begriff, 12. See also Ziel*, wenn er welche hat. Die Bezeichnungen folgen der Dokumentsprache (*See*, *Véase* …) und lassen sich in `index.see` festlegen. - **Bücher.** In einem Buch, das Kapitel für Kapitel gesetzt wird (die Sandbox, `buildBundle`), erhält das Kapitel, das das Register druckt, die Marken jedes Kapitels mit ihren Seiten und wird nur dann neu gesetzt, wenn sich eine davon verschiebt. Ein Dokument, das sowohl seine Marken als auch sein Register enthält, wird so lange neu gesetzt, bis sich die Zahlen eingependelt haben, wie bei `:::toc`. Typografie, Einzüge und Trennzeichen finden Sie unter [Register](https://postext.dev/de/docs/configuration-notes-references.md#register) in der Konfigurationsreferenz. ## Mathematische Formeln Formelsatz ist ein vollwertiger Bestandteil des Dokumentformats. Postext liest `$…$` als Formel im Text und `$$…$$` als abgesetzte Formel (Blockformel) und rendert beide mit [MathJax](https://www.mathjax.org/) im SVG-Modus. Dieselben Vektorpfade speisen alle drei Backends, sodass die Canvas-Vorschau, der HTML-Export und die PDF-Ausgabe pixelgenau übereinstimmen – und das PDF bleibt bei jeder Vergrößerung vollständig vektoriell. - **Im Text:** `$…$`. Wird in jedem Textblock erkannt (Absatz, Überschrift, Zitat, Listenpunkt). Bildet in der Zeile eine einzige unteilbare Box ohne Umbruchstelle; Knuth-Plass behandelt sie wie ein Wort, das nicht getrennt werden darf. Würde die natürliche Höhe der Formel die Zeilenbox sprengen, wird sie gleichmäßig verkleinert, damit das Grundlinienraster erhalten bleibt – sehr hohe Ausdrücke gehören in eine abgesetzte Formel. - **Abgesetzt:** `$$…$$`. Entweder in einer eigenen Zeile (`$$\int_0^1 x^2\,dx$$`) oder über mehrere Zeilen, eingefasst von `$$`-Markierungen in eigenen Zeilen. Wird in der Spalte zentriert und mit einstellbarem Abstand oben und unten (`math.marginTop`, `math.marginBottom`) auf das Grundlinienraster gesetzt – mit genau demselben Korrekturmechanismus wie bei Überschriften, sodass der Absatz nach der Formel wieder auf dem Raster steht. - **Text um eine abgesetzte Formel:** Eine abgesetzte Formel in einer eigenen Zeile unterbricht einen Absatz auch ohne Leerzeile darüber. Der Text davor ist ein Absatz, der zu ihr hinführt; Text, der direkt unter dem schließenden `$$` ohne Leerzeile steht, setzt den unterbrochenen Absatz fort und wird ohne Erstzeileneinzug gesetzt, so wie TeX das „wobei …“ nach einer abgesetzten Formel setzt. Eine Formel, die vom Text darüber durch eine Leerzeile getrennt ist (oder die auf eine Liste, ein Zitat oder eine Überschrift folgt), unterbricht nichts: Der Text danach ist ein neuer Absatz, wie gewohnt eingezogen, ob mit Leerzeile oder ohne (`math.indentAfterDisplay: false` setzt ihn ebenfalls stumpf). Nur eine vollständige abgesetzte Formel unterbricht einen Absatz – eine Formel allein in der Zeile oder ein `$$`-Block, der vor der nächsten Leerzeile geschlossen wird; eine Zeile wie `$$a$$ and $$b$$` bleibt Text. `math.keepWithLeadIn` hält eine Formel in der Spalte der Zeile, die sie einleitet. (Bis postext 1.4 wurde eine `$$…$$`-Zeile ohne Leerzeile darüber als Teil des Absatzes gelesen und so gedruckt, wie sie geschrieben war.) - **Gleichungsnummern:** `\label{eq:x}` in einer abgesetzten Formel nummeriert sie in Lesereihenfolge: (1), (2) … Eine nummerierte Formel nimmt die ganze Spaltenbreite ein (oder die Innenbreite des Kastens), die Gleichung zentriert und ihre Nummer rechtsbündig in ihrer Zeile. In einem `align`, `gather`, `alignat`, `flalign` oder `eqnarray` erhält jede Zeile mit einem `\label` eine eigene Nummer, sofern die Zeile nicht `\nonumber` oder `\notag` enthält. Eine Formel ohne `\label` wird nicht nummeriert, wie `$$…$$` es nie wurde. `\tag{…}` nummeriert eine Formel weiterhin mit dem angegebenen Text (`\tag*{…}` ohne Klammern) und wird nicht mitgezählt; ein `\label` daneben benennt diesen Text. Format, Kapitel- oder Abschnittsnummern (2.3) und Neubeginn der Zählung werden in [`math.equationNumbering`](https://postext.dev/de/docs/configuration-text.md#mathematik) eingestellt. Setzen Sie das `\label` auf die oberste Ebene der Formel oder ihrer Zeile, nicht in `aligned`, `split` oder `cases`. - **Verweise auf Gleichungen:** `\eqref{eq:x}` im Text druckt die Nummer so, wie die Formel sie trägt, (3), und `\ref{eq:x}` die bloße Nummer, 3; beide sind Links, wie jeder [Querverweis](https://postext.dev/de/docs/document-format.md#querverweise-und-anker). `Eq.~\eqref{eq:x}` behandelt `~` wie LaTeX: als geschütztes Leerzeichen. `:ref{id="eq:x"}` und `@eq:x` drucken ebenfalls (3). Innerhalb einer Formel drucken `\eqref` und `\ref` die Nummer (ohne Link). Ein Label, das nirgends gesetzt wird, druckt *?* und erscheint im Bedienfeld Prüfungen. - **Maskieren:** `\$` ist ein wörtliches Dollarzeichen. Nicht geschlossene `$`- oder `$$`-Begrenzer erzeugen im Bedienfeld Prüfungen der Sandbox einen Eintrag `unclosedMath` mit einem Quellanker, der per Klick die Stelle anspringt. - **Legenden, Anmerkungen und Tabellenzellen** setzen ebenfalls Formeln im Text (seit postext 1.19), in der Zeile mit dem Text, mit der Ausrichtung der Zelle und in der Größe des Textstücks. Dort eröffnet ein `$` nur nach der Pandoc-Regel eine Formel: kein Leerzeichen nach dem öffnenden `$`, keines vor dem schließenden und keine Ziffer direkt danach, sodass die Preise in *$5 to $10* Text bleiben; `\$` druckt ein Dollarzeichen, sodass ein maskierter String im Text und in einer Tabelle gleich gelesen wird. Die Beschriftung eines Chips nimmt keine Formeln auf. Bis postext 1.18 wurde ein `$` dort immer so gedruckt, wie es geschrieben war. - **Fehler:** TeX-Quelltext, den MathJax ablehnt (undefinierte Makros, Syntaxfehler), erscheint als Warnung `invalidMath`. Die Formel wird durch einen kleinen roten Platzhalter ersetzt, damit die Geometrie des Layouts gültig bleibt. - **Konfiguration:** Der Abschnitt `math` der Konfiguration bietet `enabled`, `fontSizeScale` (relativ zur Größe des umgebenden Textes: bei 1.0 ist ein Geviert der Formel so groß wie dieser – die Grundschriftgröße bei abgesetzten Formeln und bei Formeln im Grundtext; seit postext 1.5, das Formeln etwa 13 % kleiner setzt als 1.4, während Pakete und Sandbox-Bücher, die mit 1.4 gespeichert wurden, ihre Größe behalten – siehe [Formelgröße](https://postext.dev/de/docs/configuration-text.md#mathematik)), `color` (übernimmt ohne eigene Angabe die Farbe des Grundtextes) und die Abstände abgesetzter Formeln. - **Die Engine:** MathJax wird bei Bedarf geladen. Die Sandbox und der Layout-Worker starten es selbst; in Ihrem eigenen Code rufen Sie `await initMathEngine()` vor `buildDocument` auf, sonst wird jede Formel als grauer Platzhalterkasten gesetzt (siehe [Die Mathematik-Engine starten](https://postext.dev/de/docs/configuration-text.md#die-mathematik-engine-starten)). ```md The Euler identity $e^{i\pi}+1=0$ links the five fundamental constants. $$ \int_0^{\infty} e^{-x^2}\,dx = \frac{\sqrt{\pi}}{2} $$ ``` Eine Formel mitten im Satz, und der Satz geht danach ohne Einzug weiter: ```md For a pendulum of length $L$ the period is $$T_0 = 2\pi\sqrt{L/g}$$ where $g$ is the acceleration of free fall. ``` Nummerierte Gleichungen und Verweise darauf: ```md The energy is conserved, $$ \begin{align} E &= T + V \label{eq:energy} \\ &= \tfrac12 m v^2 + m g h \nonumber \end{align} $$ and Eq.~\eqref{eq:energy} holds at every instant. ``` **Sätze, Lemmata und Beweise.** Ein Kastenformat mit `numbering` zählt seine Kästen, so wie `amsthm` in LaTeX Theorem-Umgebungen zählt: Jeder Kasten beginnt mit seiner Bezeichnung und Nummer in Fett, „**Theorem 2.**“, der `title` des Blocks folgt der Nummer in Klammern, „**Theorem 2** (Bradley–Terry)**.**“, und ein Verweis auf seine `{#id}` druckt „Theorem 2“ (`\ref{thm:x}` oder `style=number` die bloße 2). Formate, die denselben Zähler nennen, teilen ihn, sodass ein Lemma nach einem Theorem Lemma 3 ist. Das `endMark` eines Beweisformats schließt seine Kästen mit ∎ oder □ ab, rechtsbündig in der letzten Zeile. Die Formate finden Sie unter [Nummerierte Aussagen und Beweise](https://postext.dev/de/docs/configuration-styles.md#nummerierte-aussagen-und-beweise). ```md :::callout{type="theorem" #thm:main title="Bradley–Terry"} Every reward class holds one reparameterised reward. ::: :::callout{type="proof"} Apply the projection of \eqref{eq:projection} to any member of the class. ::: By :ref{id="thm:main"}, the objective is unchanged. ``` ## Ressourcen Bilder, SVGs, Tabellen und Videos werden nicht im Text geschrieben. Sie werden einmal als **Ressourcen** angelegt (verwaltet im [Bedienfeld Ressourcen](https://postext.dev/de/docs/sandbox.md#bedienfeld-ressourcen) der Sandbox, das das Hochladen von Bildern und SVGs, einen interaktiven Tabelleneditor, YouTube-, Vimeo- und hochgeladene Videos sowie die Bearbeitung von Legende und Platzierung übernimmt) und dann über ihre ID mit dem Text verbunden. **Ein Verweis auf eine Ressource genügt, um sie einzubinden** – Sie nennen sie einmal mit einem `:ref{id="…"}` im Text, und die Engine lässt die Abbildung oder Tabelle in den ersten freien Platz nach diesem Verweis gleiten – an den Fuß der Spalte, in der Sie sie nennen, an den Kopf der nächsten Spalte, in ein Band der nächsten Seite –, so wie es ein Setzer im Druck täte. Sie platzieren sie kein zweites Mal. Beide Formen unten sind neue Syntax, die nicht mit CommonMark kollidiert, sodass ein Dokument, das sie verwendet, in jedem anderen Markdown-Betrachter weiterhin als reiner Text lesbar bleibt. ### Verweis im Text (die Hauptform) Verweisen Sie im Fließtext mit `:ref{id="…"}` auf eine Ressource. Der erste Verweis **bindet** die Ressource zugleich **ein** (sie wird also auf der Seite platziert) und gibt ihre berechnete Nummer aus, standardmäßig mit der Kurzbezeichnung des Typs davor: ```md As shown in :ref{id="lighthouse-diagram"}, the lantern room sits above the gallery. ``` ergibt: *As shown in Fig. 1.7, the lantern room sits above the gallery.* – und das Diagramm selbst gleitet an den nächsten freien Platz nach dem Satz (den Fuß dieser Spalte, den Kopf der nächsten oder ein Band der nächsten Seite), während dieser Satz und der Text danach ohne Unterbrechung weiterlaufen. Der Fließtext wird an der Verweisstelle nie unterbrochen. Wo die Ressource landet – am ersten freien Platz oder nur an einem Platz oben oder unten, innerhalb einer Spalte oder über die ganze Breite –, bestimmen ihre **Platzierung** (siehe [Platzierung](https://postext.dev/de/docs/document-format.md#platzierung) weiter unten) und die Stelle, an der Sie sie nennen: Die Suche beginnt direkt nach dem Verweis. ### Blockeinbettung (optional, ausdrückliche Platzierung im Text) Gelegentlich soll eine Ressource an einer genauen Stelle im Textfluss stehen, statt zu gleiten. Schalten Sie das Gleiten ab, indem Sie der Ressource `placement.position: "here"` geben und sie mit `::resource{id="…"}` in einer eigenen Zeile einbetten: ```md Here is the floor plan we discussed. ::resource{id="lighthouse-diagram"} The keeper's quarters occupy the eastern wing. ``` Für eine gleitende Ressource ist die Direktive `::resource` unnötig – das `:ref` hat sie bereits platziert, und ein überzähliges `::resource` für dieselbe ID wird einfach als weiterer Verweis behandelt, nicht als zweite Kopie. Ein `::resource` setzt die Ressource nur dann im Text, wenn ihre aufgelöste Platzierung `"here"` ist. Eine Ressource im Text hält über sich eine Zeile Abstand (den Gleitobjektabstand), wie es ein Gleitobjekt täte, sofern der Block davor nicht mehr verlangt. Im Fließtext hält sie darunter denselben Abstand; danach kehrt der Text auf das Grundlinienraster zurück, was bis zu einer weiteren Zeile hinzufügen kann. Eine Überschrift, eine Liste, ein Kasten oder eine weitere Ressource im Text direkt danach teilt diesen Abstand mit ihrem eigenen Abstand oben: Es gilt der größere der beiden, nicht beide. (Bis postext 1.4 war der Abstand darunter nur das, was die Rasterausrichtung übrig ließ, irgendwo zwischen nichts und einer Zeile; `layout.inlineResourceGap: 'above'` behält diese Regel bei, und vor 1.5 gespeicherte Bücher werden damit gelesen.) Innerhalb eines Kastens (`:::callout`) behält die Ressource denselben Abstand, eine Zeile des Kastentextes darüber und, mit `'around'`, darunter; am Kopf oder Fuß des Kastens setzt stattdessen der Innenabstand sie ab. (Bis postext 1.4 stand sie direkt am Text des Kastens; `layout.inlineResourceGapInBoxes: false` behält das bei, und vor 1.5 gespeicherte Bücher, deren Kästen eine Ressource einbetten, werden damit gelesen.) Eine Ressource im Text, deren Platzierung zusätzlich `span: 'page'` angibt (`placement: { position: 'here', span: 'page' }`), läuft in einem mehrspaltigen Layout an der Stelle ihrer Direktive über die ganze Seitenbreite, wie ein seitenbreiter Kasten: Die Spalten darüber enden auf gleicher Höhe (ausgeglichen, oder die Ressource wandert an den Kopf der nächsten Seite, wenn das nicht geht), sie wird über die Breite des Inhaltsbereichs mit demselben Abstand darüber und darunter gesetzt, und der Text läuft in jeder Spalte darunter weiter. Auf einer einspaltigen Seite wird sie wie bisher in voller Satzbreite gesetzt. Eine Ressource mit `span: 'column'` und gesetztem `columns` bleibt in ihrer Spalte, wenn sie im Text eingebettet wird: Die Spaltenzahl gilt nur für Gleitobjekte. Seit postext 1.19. Die `id` muss einer im Bedienfeld Ressourcen angelegten Ressource entsprechen. Die Engine rendert die Ressource (Bitmap, SVG oder Tabelle) mit ihrer Legende darunter als Fuß der Abbildung bzw. Tabelle. Der Legendentext setzt sich aus dem `captionPrefix` des Ressourcentyps, der berechneten Nummer und der eigenen Legende der Ressource zusammen – z. B. **Figure 1.7. The original lighthouse plan.** Ihre Typografie regelt [Konfiguration › Legendenstil](https://postext.dev/de/docs/configuration-resources.md#legendenstil): Bezeichnung und Beschreibung teilen Schriftart und Größe, während die Bezeichnung eigene Einstellungen für fett, kursiv und Farbe behält; der Abstand über der Legende ist standardmäßig `0.75em`, die Ausrichtung linksbündig. Die Legende kann stattdessen über der Ressource stehen (`captionStyle.position: 'above'`, global oder je Ressourcentyp), wahlweise auf einem farbigen Balken. Eine Ressource kann außerdem eine `note` tragen – eine kurze Quellen- oder Nachweiszeile mit derselben Formatierung im Text und denselben `:ref`-Markierungen wie die Legende –, die kleiner unter der Ressource gesetzt wird (unter der Legende, wenn diese unten steht, unter dem Inhalt, wenn sie oben steht) und über `captionStyle.note` gestaltet wird. **Zeilenumbrüche in Legenden und Anmerkungen.** Eine Legende oder Anmerkung ist ein Absatz in der Satzbreite ihres Platzes, und ein darin getippter Zeilenwechsel ist ein Leerzeichen. Um eine neue Zeile zu beginnen, schreiben Sie `\\` – den erzwungenen Umbruch von Titeln – oder beenden die Zeile mit einem Backslash, dem harten Umbruch von Markdown: `¹ Measured at 20 °C. \\ ² Mean of three runs.` setzt jede Fußnote einer breiten Tabelle in eine eigene Zeile. Die Zeile vor einem Umbruch behält ihre natürliche Breite und wird nie auf die Satzbreite gedehnt, und zwei Umbrüche hintereinander ergeben keine Leerzeile (ein geschütztes Leerzeichen dazwischen schon). In einer Tabellenzelle wirkt `\\` wie ein Zeilenwechsel: Es beginnt einen neuen Absatz; der Einzug der folgenden Zeile bleibt erhalten, sodass zwei führende Leerzeichen weiterhin einen Listenpunkt verschachteln. Im Text selbst sind die beiden Backslashes immer ein Umbruch, ohne Maskierung: Um sie zu drucken, setzen Sie sie in Code im Text, wo Backslashes so gedruckt werden, wie sie geschrieben sind. Im Ziel eines Links bleiben sie Teil der URL, in den Attributen einer Direktive (dem `text` eines `:ref`) Teil des Wertes; in einem Chip, der einzeilig gesetzt wird, ist ein Umbruch ein Leerzeichen. (Bis postext 1.4 wurden die Backslashes gedruckt, und eine Legende oder Anmerkung brach nur dort um, wo die Satzbreite endete.) Tabellenressourcen zeichnen ihr eigenes Gitter, gestaltet über [Konfiguration › Tabellenstil](https://postext.dev/de/docs/configuration-resources.md#tabellenstil): Grund- und Kopfzellen haben völlig unabhängige Typografie, der Hintergrund der Kopfzeile ist standardmäßig `#f0f0f0`, Linien sind `0.75pt` stark und `cellPadding` beträgt `0.375em` – jedes nicht gesetzte Feld übernimmt den Wert des Grundtextes. Spaltenbreiten gehören zur Tabelle selbst: `TableModel.columnWidths` enthält je Spalte ein relatives Gewicht (`[2, 1, 1]` gibt der ersten Spalte die halbe Breite); ohne Angabe teilen sich die Spalten die Breite gleichmäßig. Eine Tabelle kann auch in einer benannten Variante gesetzt werden: `table.styleId` wählt einen der `tableStyles` des Dokuments (siehe [Konfiguration › Benannte Tabellenstile](https://postext.dev/de/docs/configuration-resources.md#benannte-tabellenstile)), dessen nicht gesetzte Felder `tableStyle` übernehmen; eine unbekannte oder fehlende ID behält `tableStyle` bei. Eine Zelle richtet ihren Inhalt mit `TableCell.align` (`left`, `center`, `right`; Listenpunkte bleiben linksbündig) und `TableCell.verticalAlign` (`top`, der Standard, `middle` oder `bottom`) aus. Die vertikale Ausrichtung verschiebt den gesamten Zellinhalt – das Bild und den Text darunter als Einheit – innerhalb einer Zelle, die höher ist als er: einer Zeile, die eine längere Nachbarzelle streckt, oder der Zeilen, die ein `rowSpan` überdeckt. Sie gilt in jeder Ausgabe (Canvas, HTML, PDF), in gedrehten Tabellen und in jedem Teilstück einer über mehrere Seiten geteilten Tabelle. Beide werden je Zelle über die Ausrichtungsschaltflächen in der Werkzeugleiste des Tabelleneditors der Sandbox gesetzt. Eine Tabellenzelle kann auch ein Bild enthalten. `TableCell.image` nennt eine Bitmap- oder SVG-Ressource über ihre ID (`{ "resourceId": "fig-arm", "width": 0.7 }`): Das Bild wird in der Zelle gezeichnet – nie nummeriert, gleitend oder beschriftet –, auf die Innenbreite der Zelle eingepasst (oder auf den mit `width` angegebenen Anteil davon, Standard `1`) unter Wahrung des Seitenverhältnisses, ausgerichtet wie der Zelltext, und ein etwaiger Zelltext läuft darunter. Die Zeile wächst, um es aufzunehmen. Im Tabelleneditor der Sandbox wählt die Bildschaltfläche der Werkzeugleiste die Ressource für die aktive Zelle, und ein Breitenfeld setzt den Anteil. Eine ID, die zu keiner Bildressource passt, lässt die Zelle reinen Text enthalten. Eine Zelle kann eine eigene Füllung tragen. `TableCell.background` ist ein Farbwert (`{ "hex": "#c1dfd6", "model": "hex" }`, wahlweise über `paletteId` mit einem Eintrag der Dokumentpalette verknüpft), der statt des Kopf- oder Grundhintergrunds des Stils gemalt wird – eine Kompatibilitätsmatrix färbt ihre Zellen auf diese Weise grün, rot und gelb. Der Tabelleneditor der Sandbox setzt ihn über das Füllsteuerelement der Werkzeugleiste. Um solche Füllungen zu erklären, nehmen Legende, Anmerkung und jeder Textblock ein **Farbfeld** im Text auf: `:swatch{color="#c1dfd6"}` (ein Hexwert oder die ID eines Paletteneintrags – `:swatch{color="table-compatible"}`) setzt ein kleines Quadrat auf die Grundlinie, drei Viertel der Schriftgröße groß, mit der Farbe gefüllt und in der Textfarbe umrandet, sodass eine Anmerkung `:swatch{color="ok"}: compatible; :swatch{color="no"}: incompatible` lauten kann. Eine Farbe, die sich zu nichts auflöst, zeichnet einen leeren Umriss. Der Hexwert kann einen Alphakanal enthalten (`#rrggbbaa`, `#rgba`), und `rgb()`- / `rgba()`-Farben funktionieren ebenfalls, sodass eine durchscheinende Zellfüllung ein passend durchscheinendes Farbfeld hat (siehe [Konfiguration › Transparenz](https://postext.dev/de/docs/configuration-fonts-colors-viewers.md#transparenz)). SVG-Ressourcen lassen sich zusätzlich für den Druck mit einer einzigen Schmuckfarbe umfärben, über `diagramStyle.singleInk` (Standard `false`). Ist es eingeschaltet, wird jede Farbe in einem SVG-Diagramm auf einen helligkeitsabhängigen Tonwert von `diagramStyle.inkColor` abgebildet (standardmäßig die Hauptfarbe der Palette, `#295AA3`) – Weiß wird zu Papier, Schwarz zur vollen Farbe –, sodass Abbildungen getreu wiedergegeben werden, wenn das Dokument mit einer einzigen Schmuckfarbe gedruckt wird. Siehe [Konfiguration › Diagrammstil](https://postext.dev/de/docs/configuration-resources.md#diagrammstil). Eine fehlerhafte Einbettung (fehlende oder leere `id`, eine `id` ohne Anführungszeichen oder in einfachen Anführungszeichen, zusätzliche Attribute) wird nicht zu einem Ressourcenblock; sie fällt auf das normale Lesen als Absatz zurück und bleibt in der Ausgabe sichtbar. Ebenso eine korrekt geschriebene Einbettungszeile, die ohne Leerzeile direkt unter einer Absatzzeile steht: Sie wird als Teil dieses Absatzes gelesen. Beide lösen eine Warnung `malformedEmbed` aus – einen Eintrag **Einbettung als Text gesetzt** im Bedienfeld Prüfungen der Sandbox. Verweise im Text werden in jedem Textblock erkannt – Absätzen, Überschriften, Zitaten und Listenpunkten – und können neben fett, kursiv, Code und Formeln im Text stehen. #### Verweisoptionen Die Direktive `:ref` nimmt drei optionale Attribute in beliebiger Reihenfolge an. `style` wählt, wie die berechnete Bezeichnung ausgegeben wird: `style="number"` druckt die bloße Nummer (`1.7`), `style="full"` den vollen Namen des Typs plus Nummer (`Figure 1.7`), und ohne `style` wird die `shortLabel` des Typs plus Nummer verwendet (`Fig. 1.7`). `case` ändert nur die Groß- und Kleinschreibung des Bezeichnungsteils – `lower`, `upper` oder `capitalize` – und lässt die Nummer unberührt. `text` ist eine wörtliche Ersetzung, die jede berechnete Bezeichnung ersetzt und Vorrang vor `style` und `case` hat. Die Ausgabeoptionen nebeneinander: | Syntax | Ausgabe | Hinweise | | --- | --- | --- | | `:ref{id="…"}` | `Fig. 1.7` | Standardstil: die `shortLabel` des Typs, gefolgt von der Nummer, verbunden durch ein geschütztes Leerzeichen, sodass beide nie getrennt umbrochen werden. | | `:ref{id="…" style="number"}` | `1.7` | Die bloße berechnete Nummer, ohne Bezeichnung. | | `:ref{id="…" style="full"}` | `Figure 1.7` | Der volle `name` des Typs, gefolgt von der Nummer. Für den Satzanfang oder wo die Abkürzung schlecht liest. | | `:ref{id="…" case="lower"}` | `fig. 1.7` | Ändert nur die Schreibung der Bezeichnung: `lower` (`fig. 1.7`), `upper` (`FIG. 1.7`) oder `capitalize` (erster Buchstabe groß). Lässt sich mit `style="full"` kombinieren (`figure 1.7`); die Nummer wird nie verändert, und ein unbekannter Wert wird ignoriert. | | `:ref{id="…" text="see the plan"}` | `see the plan` | Eine ausdrückliche Ersetzung. Der angegebene Text wird wörtlich statt jeder berechneten Bezeichnung verwendet – nützlich für Links im Fließtext wie „wie wir zuvor gesehen haben“. Ist `text` vorhanden, hat es Vorrang vor `style` und `case`. | Nennt ein `:ref` (oder `::resource`) eine ID ohne passende Ressource, fällt die Bezeichnung auf `?` zurück (eine `text=`-Bezeichnung wird stattdessen gedruckt, weiterhin ohne Nummer und Link), und die Sandbox meldet eine Warnung **Unbekannte Ressource**. Die Engine verzeichnet sie als Eintrag `unknownResourceId` in den `contentWarnings` des Dokuments, mit dem Quellbereich und der Seite des Verweises – auch für ein `:ref` in der Legende, der Anmerkung oder einer Tabellenzelle einer Ressource, die der Text verwendet. ### Nummerierung beim ersten Verweis Die Nummer einer Ressource wird vergeben, wenn sie **in Lesereihenfolge zum ersten Mal genannt** wird – ob diese erste Nennung eine Blockeinbettung `::resource` oder ein `:ref` im Text ist. Von da an druckt jeder Verweis auf dieselbe ID dieselbe Nummer. Die Nummern folgen also der Reihenfolge, in der der Leser auf sie trifft, nicht der Reihenfolge, in der die Ressourcen im Bedienfeld angelegt wurden: - Wenn Sie in der Einleitung per `:ref` auf eine Abbildung verweisen und sie erst zwei Seiten später einbetten (`::resource`), erhält sie trotzdem die Nummer der Einleitung – der Verweis kam zuerst. - Ein neuer Verweis *weiter vorn* im Dokument nummeriert alles danach automatisch neu. Es gibt keine manuelle Nummerierung, die abgeglichen werden müsste. Die Nummerierung erfolgt je Ressourcentyp und beachtet dessen Rücksetzbereich und Zählerformat – siehe [Konfiguration › Ressourcentypen](https://postext.dev/de/docs/configuration-resources.md#ressourcentypen) zu den Vorlagen-Tokens (`{h1}`, `{n}`), `resetOn` und `counterFormat`. Gezählt wird nur, worauf der Text verweist: Eine Ressource, die nur eine Gestaltung zeichnet (etwa ein Bildelement eines Kapitelauftakts), erhält keine Nummer und lässt den Zähler unverändert. Und `{h1}` zählt jede Überschrift der Ebene 1, deren Format nicht `numbered: false` ist, auch eine mit leerer `numberingTemplate`, sodass ein Artikel, dessen einzige H1 sein Titel ist, seine Abbildungen standardmäßig 1.1, 1.2 … nummeriert. [Konfiguration › Was nummeriert wird](https://postext.dev/de/docs/configuration-resources.md#was-nummeriert-wird) beschreibt beide Regeln und die Einstellungen für Abbildung 1, 2 …. ### Platzierung Jede Ressource hat eine **Platzierung**, die bestimmt, wo ihr Gleitobjekt landet; aufgelöst wird sie je Ressource (ihr eigenes `placement`), dann über das `defaultPlacement` ihres Typs, dann über den eingebauten Standard `auto` / `column`: | Feld | Werte | Bedeutung | | --- | --- | --- | | `position` | `"auto"` · `"top"` · `"bottom"` · `"here"` | `"auto"` (der Standard) nimmt den ersten freien Platz nach dem Verweis, oben oder unten; `"top"` / `"bottom"` nehmen nur Plätze dieser Art an; `"here"` schaltet das Gleiten ab und bettet die Ressource an der Direktive `::resource` im Text ein (eine dort platzierte Tabelle wird zwischen Zeilen geteilt, wenn sie nicht in den Rest ihrer Spalte passt, siehe [Tabellen, die höher als die Seite sind](https://postext.dev/de/docs/configuration-resources.md#tabellen-die-höher-als-die-seite-sind)). | | `width`, `align` | `0 < width < 1`; `"left"` · `"center"` · `"right"` | Eine Ressource, die schmaler ist als ihr Platz: `width` ist der Anteil der Spalten- (oder Seiten-)breite, den sie einnimmt, `align`, wo sie im Platz steht (eine kleine Tabelle mittig in ihrer Spalte; ein seitenbreites Band, dessen Bild eine Spalte breit ist). Ein Bild, das schmaler ist als sein Platz – eine Bitmap, die kleiner ist als die Spalte, oder eine, die `layout.fitFiguresToPage` verkleinert hat –, steht ebenfalls gemäß `align` dort, unter einer Legende, die die Satzbreite des Platzes behält. Gilt für Gleitobjekte und für Einbettungen mit `::resource` im Text gleichermaßen. | | `captionSide` | `true` · `false` | In einem anderthalbspaltigen Layout, dessen Nebenspalte für Gleitobjekte reserviert ist (`layout.sideColumnRole: 'floats'`), behält ein `"column"`-Gleitobjekt mit `captionSide` seinen Inhalt in der Hauptspalte und setzt seine Legende (und Anmerkung) in die Nebenspalte, auf Höhe der Oberkante der Abbildung – oder ihrer Unterkante bei einem Gleitobjekt unten; die Nebenspalte gibt dieses Band ab. Eine Seite ohne solche Spalte behält die Legende unter der Abbildung. Seit postext 1.28 gilt das auch für eine im Text gesetzte Ressource (`"here"`), eine Spalte breit: Ihre Legende und Anmerkung stehen in der Nebenspalte, auf Höhe der Oberkante ihres Inhalts, der Block im Text ist nur so hoch wie der Inhalt, und die danach gesetzten Abbildungen und Kästen der Nebenspalte halten Abstand zur Legende. Wo die Nebenspalte neben der Einbettung belegt ist, bleibt die Legende unter dem Inhalt; eine Einbettung, die in die nächste Spalte oder auf die nächste Seite wandert, entscheidet dort neu. Nicht in einem Kasten, auf einer Seite mit senkrechtem Satz oder bei einem Bild, das vom Text umflossen wird. `layout.inlineCaptionSide: false` beschränkt seitliche Legenden auf Spalten-Gleitobjekte. | | `span` | `"column"` · `"page"` | Eine einzelne Spalte belegen oder den Spaltenfluss unterbrechen und über die ganze Breite des Inhaltsbereichs, über alle Spalten laufen. In einem einspaltigen Layout sind beide gleich. | | `columns` | eine ganze Zahl, Standard `1` | Auf einer mehrspaltigen Seite ein `"column"`-Gleitobjekt über so viele benachbarte Spalten, Spaltenabstände eingeschlossen: ein Bild über zwei der fünf Spalten einer Zeitung. Es nimmt den Kopf einer Folge leerer Spalten, die auf gleicher Höhe beginnen, oder den Fuß der zitierenden Spalte und der leeren Spalten danach. So viele Spalten, wie die Seite hat, oder mehr machen es zu einem seitenbreiten Gleitobjekt. Wird bei den Spannweiten `"page"` und `"side"`, bei einer gedrehten Ressource und bei einer Einbettung im Text (`"here"`) ignoriert; `captionSide` gilt nur für ein Gleitobjekt von einer Spalte Breite. Seit postext 1.18. | | `rotate` | `"ccw"` · `"cw"` | Die Ressource um eine Vierteldrehung gedreht setzen – eine Tabelle im Querformat in einem Buch im Hochformat. `"ccw"` dreht sie gegen den Uhrzeigersinn, ihre Oberkante zum linken Seitenrand (der Leser dreht das Buch im Uhrzeigersinn), die übliche Konvention; `"cw"` in die andere Richtung. Eine gedrehte Ressource ist immer ein seitenbreites Gleitobjekt auf einer eigenen Seite: Sie wird entlang der Höhe des Inhaltsbereichs gesetzt, abgerundet auf ganze Zeilen des Grundlinienrasters und abzüglich einer Grundtextzeile, des Gleitobjektabstands, den jedes Gleitobjektband hält (ein Satzspiegel von 237 mm auf einem 14-pt-Raster fasst 47 Zeilen, 232,1 mm, die Ressource erhält also 46 davon, 227,2 mm), steht bei gespiegelten Rändern bündig am Bund (sonst linksbündig), und eine Tabelle, die zu breit für eine Seite ist, wird zwischen Zeilen geteilt und läuft gedreht auf den folgenden Seiten weiter, mit wiederholter Kopfzeile, genau wie eine aufrechte Tabelle, die höher ist als eine Seite. Eine gedrehte Abbildung wird auf die Seite eingepasst. Wird bei einer Einbettung im Text (`"here"`) ignoriert. | | `shrink`, `minScale` | `"never"` · `"page"` · `"slot"`; `0 < minScale ≤ 1`, Standard `0.7` | Ein gleitendes Bild (Bitmap, SVG, das Posterbild eines Videos) unter Wahrung seiner Proportionen auf den Raum eines Platzes verkleinern, statt es weiterzuschieben. `"never"` (der Standard) setzt es in seiner Größe. `"page"` verkleinert es nur, wenn es zu hoch für das Band einer frischen Seite ist: den Inhaltsbereich abzüglich dessen, was dort bereits steht (ein Auftakt, andere Gleitobjekte, Fußnoten), und des Gleitobjektabstands, wie bei einer Katalogtafel, die auf ihre Seite zugeschnitten ist. `"slot"` verkleinert es außerdem in einen Platz der zitierenden Seite oder in den neben einem anderen Band verbliebenen Raum, wenn es dort mit `minScale` oder mehr hineinpasst; sonst wandert es wie bisher weiter. Die Plätze werden in ihrer üblichen Reihenfolge geprüft, und das Band endet weiterhin auf dem Grundlinienraster. Ein Bild mit Sicherheitsbereich wird innerhalb dessen beschnitten, bevor es skaliert wird (siehe [Sicherheitsbereich](https://postext.dev/de/docs/document-format.md#sicherheitsbereich)). Auf einer frischen Seite, wo es sonst nirgends hin kann, wird ein Bild, das selbst bei `minScale` nicht passt, in diesem Maßstab gesetzt und ragt über das Band hinaus. Das Layout meldet jedes verkleinerte Gleitobjekt als Warnung `floatShrunk`. Tabellen (die geteilt werden), gleitende Kästen, Comicstreifen, gedrehte Ressourcen und Einbettungen im Text werden nie skaliert. Der Dokumentstandard ist `layout.floatShrink`. Seit postext 1.24. | | `captionMeasure` | `"slot"` · `"body"` | Die Satzbreite von Legende und Anmerkung eines Bildes, das schmaler ist als sein Platz (verkleinert oder eine Bitmap, die kleiner ist als die Spalte): `"slot"` (der Standard) behält die Satzbreite des Platzes; `"body"` setzt sie so breit wie das Bild, darunter gemäß `align`, sodass eine zentrierte Tafel ihre Legende mittig darunter hat. Gilt für Gleitobjekte und Einbettungen im Text gleichermaßen. Seit postext 1.24. | | `wrap`, `wrapGap` | `"none"` · `"left"` · `"right"` · `"start"` · `"end"`; eine Länge | Den Text neben der Ressource laufen lassen: Sie steht an dieser Seite ihrer Spalte, und die Zeilen daneben werden auf die verbleibende Satzbreite gesetzt, mit `wrapGap` Abstand zu ihrem Kasten (Legende eingeschlossen), und kehren darunter zur vollen Satzbreite zurück. Eine Einbettung im Text (`"here"`) und ein einspaltiges Gleitobjekt am Kopf oder Fuß einer Spalte nehmen das an; seitenbreite, mehrspaltige, Nebenspalten- und gedrehte Gleitobjekte behalten ihr Band. Die Ressource nimmt `width` der Spalte ein, sonst `layout.wrap.defaultWidth` (0.45). `wrapGap` ist standardmäßig `layout.wrap.gap`, sonst eine Grundtextzeile. Siehe [Textumfluss](https://postext.dev/de/docs/document-format.md#textumfluss). Seit postext 1.24. | | `citingPage` | `true` · `false`, Standard `false` | Ein `"top"`- oder `"auto"`-Gleitobjekt den Kopf der Seite (bei einem seitenbreiten Gleitobjekt) oder der Spalte (bei einem Spalten-Gleitobjekt, auch über `columns`) einnehmen lassen, auf der die Zeile landet, die es zuerst zitiert, wie es die Platzierung `t` in LaTeX tut, statt des ersten freien Platzes nach dieser Zeile. Der Text über dem Verweis rückt unter das Gleitobjekt nach unten. Das geschieht nur, wenn das Gleitobjekt dort innerhalb von `layout.maxTopFraction` der Spalte (standardmäßig 0.7) Platz findet, wenn die früheren Gleitobjekte seiner Nummernfolge bereits gesetzt sind, wenn kein ausdrücklicher Umbruch die Seite eröffnet (die erste Seite eines Kapitels, ein Teil, ein `:::pagebreak`) und nichts Seitenbreites über der zitierenden Zeile steht, und wenn die zitierende Zeile bei dieser Anordnung noch auf dieser Seite landet (in einer Spalte, die das Gleitobjekt anführt); andernfalls nimmt das Gleitobjekt seinen üblichen Platz. Gedrehte Gleitobjekte, Nebenspalten-Gleitobjekte und der Rest einer über Seiten geteilten Tabelle werden nie so verschoben. Standard: das `defaultPlacement` des Typs, dann `layout.floatsAtCitingPage`. Seit postext 1.25. | Ein Gleitobjekt kommt an den **ersten freien Platz nach seinem ersten Verweis**, in Lesereihenfolge: den Fuß der Spalte, in der der Verweis steht, dann Kopf und Fuß der nächsten leeren Spalte derselben Seite, dann die Bänder der nächsten Seite, die der Fluss öffnet (ein seitenbreites Gleitobjekt nimmt den Fuß der Seite, wenn jede Spalte noch Platz dafür hat, sonst ein Band der nächsten Seite). Eine Seite, die eine Abbildung oder Tabelle im Text eröffnet, zählt ebenfalls: Ein Gleitobjekt, das auf diese Seite wartet, nimmt ihren Kopf über der Abbildung oder Tabelle ein, wenn beide darauf passen; passen sie nicht, behält die Abbildung oder Tabelle die Seite, und das Gleitobjekt wartet auf die nächste. Bis postext 1.4 wurde eine solche Seite übersprungen, und das Gleitobjekt wartete auf die Seite danach, auch wenn beide gepasst hätten. Es wird in seiner Größe gesetzt, sofern sein `shrink` es nicht auf den Raum eines Platzes skalieren lässt (siehe Tabelle oben), und es landet nie vor seinem Verweis. Gleitobjekte einer Nummernfolge erscheinen in Verweisreihenfolge: Eine Abbildung, die auf einer Seite nirgends passt, hält die Abbildungen hinter ihr auf (eine wartende Tabelle hält keine Abbildung auf und umgekehrt), sodass Abbildung 12 nie vor Abbildung 11 erscheint. Eine Tabelle, die sonst warten müsste, wird stattdessen geteilt: Bietet sich ihr der Kopf einer leeren Spalte, nimmt sie die Zeilen, die passen, und setzt sich im nächsten Platz fort – der Spalte daneben oder der nächsten Seite – mit wiederholten Kopfzeilen (siehe `tableStyle.overflow`). Ein `top`- oder `auto`-Gleitobjekt mit eingeschaltetem `citingPage` kann stattdessen die Seite (oder Spalte) anführen, auf der seine zitierende Zeile landet, wobei der Text über dem Verweis darunter nach unten rückt: Es wird dann auf derselben Seite über seinem Verweis gemalt, nie auf einer früheren, und in einem getaggten PDF und im HTML weiterhin danach gelesen. Die Engine klärt das in einigen zusätzlichen Durchläufen und behält es nur, solange die zitierende Zeile auf dieser Seite bleibt. Gleitobjekte verlassen nie ihr Kapitel: An einem Kapitelauftakt (einer Überschriftenebene mit `breakBefore` oder `span: 'page'`), einem `:::part`, einem Kastenformat mit `floatBarrier: true` (dem abschließenden Kasten „Das Wichtigste“ eines Kapitels) und am Ende des Dokuments wird jedes noch ausstehende Gleitobjekt zuerst platziert – in den freien Plätzen der Seite oder auf Seiten, die vor der Grenze eröffnet werden. Ein Gleitobjekt, das zuerst vom Auftakt selbst zitiert wird (ein Kapiteltitel, der seine Abbildung nennt) oder vom ersten Block nach einem `:::part`, gehört zum neuen Kapitel: Es landet nach dieser Zeile, wie jedes andere. Eine Abbildung oder Tabelle, die den Kopf einer Seite verlangt hat, kann dann den Fuß der Schlussseite des Kapitels unter dessen ausgeglichenen Spalten einnehmen, statt einer eigenen Seite. Ein `:::pagebreak` schickt ausstehende Gleitobjekte einfach auf die Seite danach. Unter einem seitenbreiten Auftakt über zwei oder mehr Textspalten gilt die eigene Spalte des Auftakts an ihrem Kopf als leer, solange ihm darin nichts folgt: Ein gleitender Kasten, der direkt nach dem Auftakt steht, oder eine dort mit `::resource` eingebettete Ressource nimmt den Kopf der ersten Spalte ein, unter dem Auftakt und auf Höhe der Köpfe der anderen Spalten (mit `columns` über mehrere Spalten ab dieser), und der Text der Spalte beginnt darunter. Ein im Fließtext zitiertes Gleitobjekt folgt weiterhin seiner zitierenden Zeile. Bis postext 1.24 bot die erste Spalte dort keinen Platz, und ein solches Gleitobjekt landete erst ab der zweiten Spalte; `layout.floatsUnderOpener: false` behält das bei (siehe [Konfiguration › Layout](https://postext.dev/de/docs/configuration-page-layout.md#layout)). Seitenkästen (`span="side"`) bleiben ebenfalls in ihrem Kapitel. Ein Kasten, den die Nebenspalte seiner Seite nicht fassen kann, nimmt die Nebenspalte der nächsten Seite; wo das Kapitel oder das Dokument vorher endet, wird jeder noch wartende Kasten in der Nebenspalte einer nach dem Text eröffneten Seite gesetzt, in der Reihenfolge ihrer Blöcke, und eine danach zitierte Seitenabbildung steht hinter ihnen. Eine solche Seite enthält keinen Text, daher meldet der Build jeden Kasten und jede Abbildung darauf (`afterText`). Ein Kasten, der höher ist als eine leere Nebenspalte, wird trotzdem gesetzt und gemeldet (`calloutOverflow`), und alles, was weiterhin keine Seite findet, wird ebenfalls gemeldet (`unplaced`) statt verworfen. Bis postext 1.24 wurde nur die erste dieser Seiten eröffnet, und die übrigen Kästen gingen ohne Warnung verloren. Gleitobjektbänder werden am Grundlinienraster ausgerichtet, damit der umgebende Text den seitenweiten vertikalen Rhythmus behält. Ein Band **oben** vergrößert seinen unteren Abstand bis zur nächsten Rasterlinie, sodass der Text unter dem Gleitobjekt mit den Nachbarspalten und der gegenüberliegenden Seite registerhaltig bleibt. Ein Gleitobjekt **unten** wird so verankert, dass die letzte Zeile seiner Legende eine Grundlinie mit der letzten Textzeile der anderen Spalten teilt (Inhalt ohne Legende richtet seine Unterkante an der letzten Rasterzeile aus) – volle Seiten enden daher über alle Spalten und gegenüberliegenden Seiten hinweg auf derselben Höhe. Auf der Schlussseite eines Kapitels – und des Dokuments – folgt den seitenbreiten Abbildungen und Tabellen unter dem letzten Textband nichts mehr; sie rücken daher nach oben und stehen einen Gleitobjektabstand darunter, in ihrer Reihenfolge gestapelt, statt Weißraum zwischen dem Text und einer Abbildung am Seitenfuß zu lassen. Das gilt auch für ein Gleitobjekt mit `position: 'bottom'`. Um sie wie auf jeder anderen Seite am Fuß zu halten, setzen Sie `layout.hugClosingFloats: false` (siehe [Konfiguration › Layout](https://postext.dev/de/docs/configuration-page-layout.md#layout)). Seiten mit Nebenspalte verschieben sie nie. Alle drei Backends – die Canvas-Vorschau, der HTML-Betrachter und die PDF-Ausgabe – rendern Ressourcen. Im HTML-Backend liegen die Bilddaten außerhalb des Dokuments, daher liefert der Host sie über die Resolver-Option `resourceImageUrl(fileId)`; fehlt der Resolver (oder liefert er für eine Datei nichts), wird die Ressource als neutraler Platzhalterkasten gerendert, damit das Layout stabil bleibt. Die eigene Datei eines Videos kommt auf dieselbe Weise über `resourceVideoUrl(fileId)` (siehe [Videos](https://postext.dev/de/docs/document-format.md#videos)). #### Wo ein Gleitobjekt landen kann „Nie vor seinem Verweis“ zählt ab der Zeile, die das Gleitobjekt zitiert: Das Gleitobjekt wartet, bis diese Zeile gesetzt ist, und nimmt den ersten freien Platz danach in Lesereihenfolge – der Kopf der Seite, auf der die Zeile steht, kommt vor ihr. Ein Seitengleitobjekt (`span: 'side'`, in der Nebenspalte nur für Gleitobjekte eines anderthalbspaltigen Layouts) ist die Ausnahme: Es stapelt sich in der Nebenspalte neben dem Text, der es zitiert, und kann höher auf der Seite stehen als die zitierende Zeile. Für eine auf Seite 5 zitierte Abbildung: | Platzierung | Auf Seite 5 | Sonst | | --- | --- | --- | | `top`, `span: 'page'` | Nie: Das Band am Kopf der Seite liegt über der zitierenden Zeile. | Das obere Band von Seite 6. | | `top`, `span: 'column'` | Der Kopf einer späteren Spalte, die noch leer ist – in der ersten von zwei Spalten zitiert, kann sie die zweite eröffnen. | Der Kopf einer Spalte von Seite 6. | | `auto` oder `bottom`, `span: 'page'` | Das Fußband von Seite 5, wenn jede Spalte noch Platz dafür hat. | Ein Band von Seite 6. | | `auto` oder `bottom`, `span: 'column'` | Der Fuß der zitierenden Spalte; dann der Fuß (beide) oder der Kopf (nur `auto`) einer späteren leeren Spalte. | Seite 6. | - Eine Seite mit Kapitelauftakt folgt denselben Regeln: Ein seitenbreites `auto`- oder `bottom`-Gleitobjekt, das im ersten Absatz des Auftakts zitiert wird, kann das Fußband dieser Seite unter ihrem Text einnehmen; ein `top`-Gleitobjekt eröffnet die nächste Seite. Soll das Bild auf der Seite stehen, die es zitiert, verwenden Sie `auto` oder `bottom`, oder zeichnen Sie es als Bildelement in der Gestaltung des Auftakts. - Zwei Spalten-Gleitobjekte, die im selben Absatz zitiert werden, nehmen die nächsten beiden Plätze: typischerweise das erste den Fuß der zitierenden Spalte, das zweite den Kopf der nächsten leeren Spalte – nebeneinander auf der Seite. - In einem einspaltigen Layout ist ein seitenbreites Gleitobjekt ein Spalten-Gleitobjekt, und es gelten dieselben Regeln: Ein `top`-Gleitobjekt, das auf einer Seite zitiert wird, landet am Kopf der nächsten. - Ein Absatz, der von einer Seite auf die nächste läuft, zählt ebenfalls ab seiner zitierenden Zeile. Beginnt der Absatz am Fuß von Seite 5 und fällt der Verweis auf Seite 6 – oder wandert der ganze Absatz auf Seite 6, weil am Fuß von Seite 5 nicht genug seiner Zeilen passen –, steht der Verweis auf Seite 6: Ein `top`-Gleitobjekt eröffnet Seite 7, und ein `auto`-Gleitobjekt nimmt den Fuß von Seite 6, wenn dort Platz ist. Dasselbe gilt zwischen den Spalten einer Seite und für einen über Seiten geteilten Kasten: Eine Abbildung, die sein zweiter Teil zitiert, wartet auf diesen Teil. - **Geändert in postext 1.5.** Bis postext 1.4 wurde ein Gleitobjekt eingereiht, sobald das Layout den zitierenden Absatz erreichte, sodass die Seite, auf die ein solcher Absatz lief (oder wanderte), mit dem Gleitobjekt beginnen konnte, über der Zeile mit dem Verweis. Eine solche Abbildung landet jetzt eine Seite später oder, wenn sie `auto` verlangt, am Fuß der Seite; die Seitenzahl kann sich dadurch ändern. ### Textumfluss Ein Bild, eine Tabelle oder ein Kasten, schmaler als die Spalte, kann an einer Seite davon stehen, während der Text daneben läuft, wie in einer Zeitschrift oder einem Newsletter. Geben Sie seiner Platzierung eine Umflussseite `wrap` und, wenn Sie möchten, eine `width`: ```json { "id": "bed", "typeId": "figure", "kind": "svg", "caption": "The new planting bed.", "placement": { "position": "here", "wrap": "right", "width": 0.4 } } ``` - **Im Text (`"here"`).** Die Ressource steht an ihrer Seite der Spalte, ihre Oberkante auf Höhe der Oberkante der nächsten Zeile an der `::resource`-Zeile, und die folgenden Absätze, Zitate und Listenpunkte laufen in der verbleibenden Satzbreite daneben, dann in voller Satzbreite darunter. Ein Absatz, der daneben beginnt und darunter endet, bleibt ein Absatz: kein Umbruch, kein zusätzlicher Abstand am Fuß des Bildes. Jede Zeile bleibt auf dem Grundlinienraster; der Raum unter dem Bild ist sein Abstand, aufgerundet auf ganze Rasterzeilen. - **Ein Spalten-Gleitobjekt.** Ein `span: "column"`-Gleitobjekt von einer Spalte Breite, am Kopf (`"top"` oder `"auto"` am Kopf einer Spalte) oder am Fuß (`"bottom"`, `"auto"`) einer Spalte, wird wie jedes Gleitobjekt in seinem Band platziert; die ersten oder letzten Zeilen der Spalte laufen dann daneben. Auf einer zweispaltigen Seite gehört das Gleitobjekt zu seiner Spalte, und die andere läuft in voller Breite. - **Ein Kasten.** Ein `:::callout` nimmt dieselben Einstellungen als Attribute an: `:::callout{wrap="right" width=0.4}` setzt ein Zitat in Auszeichnungsgröße oder einen Seitenkasten an die Stelle, an der er steht, mit dem Text danach daneben, und `placement="top"` oder `"bottom"` mit `wrap` lässt ihn an den Kopf oder Fuß einer Spalte gleiten. Ein umflossener Kasten wird als Ganzes gesetzt und nie geteilt. - **Was darunter kommt.** Eine Überschrift, eine abgesetzte Formel, eine Abbildung oder Tabelle, ein Kasten und ein Gedicht laufen nicht neben einem umflossenen Element: Sie kommen darunter, und der Weißraum neben ihm über ihnen bleibt leer. Das Verlassen der Spalte (ihr Fuß, ein `:::columnbreak`, ein Seitenumbruch) beendet den Umfluss dort: Das Element gehört zu seiner Spalte. Kann der Block direkt nach einer Ressource im Text nicht daneben laufen, nimmt die Ressource ihr Band ein, wie ohne `wrap`. - **Abstand und Grenzen.** `wrapGap` (sonst `layout.wrap.gap`, sonst eine Grundtextzeile) trennt das Element, Legende eingeschlossen, vom Text daneben und vom Text darunter. Wo der Text daneben schmaler würde als `layout.wrap.minTextWidth` (12 em Grundtext) oder das Element kürzer ist als `layout.wrap.minLinesBeside` Zeilen (2), nimmt es sein Band ganz ein, und eine Warnung `textWrap` sagt das. Ein Element im Text, das zu hoch für den in seiner Spalte verbliebenen Raum ist, wandert mit seinem Anker in die nächste, mit derselben Warnung. - **Seiten.** `left` und `right` sind Seiten des Textflusses, wie bei `align`: In einem Buch, das von rechts nach links läuft, ist `left` die rechte Seite des Blattes. `start` und `end` bezeichnen dieselben Seiten. - **Ausgaben.** Canvas, HTML-Betrachter, PDF und EPUB mit festem Layout setzen die Zeilen so, wie sie gesetzt wurden; ein getaggtes PDF liest das Bild oder den Kasten vor dem Absatz, der daneben läuft. Ein umfließendes EPUB lässt es per CSS an seine Seite gleiten, mit demselben Anteil an der Textbreite. - **Noch nicht.** Text auf beiden Seiten eines Bildes, Konturenumfluss, Umfluss innerhalb des eigenen Inhalts eines Kastens und Umfluss in senkrechtem Text (das Element behält sein Band, mit einer Warnung). Spalten mit einem umflossenen Element werden vom Spaltenausgleich ausgenommen. ### Bitmap-Größe Eine Bitmap gibt ihre Pixel an: `bitmap.width` und `bitmap.height` sind die Pixelzahlen der Datei, keine Druckgröße. Wie viele davon auf einen Zoll kommen, entscheidet, wie groß das Bild gesetzt wird, bevor sein Platz es begrenzt. Es gibt drei Wege, die Größe festzulegen: - **Ihre Pixel bei der dpi-Zahl der Seite** (der Standard). Ohne Auflösung ist ein Pixel des Bildes ein Pixel des Layouts (`page.dpi`, 300, sofern nicht gesetzt): Ein Foto von 2400 px ist auf einer Seite mit 300 dpi 8 Zoll (203,2 mm) breit und auf einer mit 150 dpi doppelt so breit. - **Eine Auflösung.** `bitmap.resolution` ist die ppi-Zahl des Bildes bei seiner natürlichen Druckgröße, seine natürliche Breite ist also auf einer Seite beliebiger dpi-Zahl `width × page.dpi / resolution`: 2400 px bei `resolution: 300` sind 203,2 mm breit, ob die Seite mit 150 dpi oder mit 300 gesetzt wird. `layout.bitmapResolution` gibt jeder Bitmap ohne eigene Auflösung eine: eine Zahl (`300`) oder `'file'`, die Auflösung, die ihre Datei angibt (`bitmap.fileResolution`: das `pHYs` eines PNG, die JFIF- oder EXIF-Dichte eines JPEG, das EXIF eines WebP; bei einem aus Word importierten Bild die Größe, in der Word es gedruckt hat). Kameras, Bildschirmfotos und Web-Exporte geben oft 72 oder 96 ppi an, wenn sie nichts über eine Druckgröße wissen, daher gelten diese beiden Werte unter `'file'` als nicht gesetzt, und das Bild behält seine Pixel bei der dpi-Zahl der Seite; eine an der Ressource selbst angegebene 72 wird wörtlich genommen. `'document'`, der Standard, ist der erste Weg. - **Ein Anteil an der Spalte.** `placement.width` verengt ein Gleitobjekt oder eine Einbettung im Text auf einen Bruchteil ihrer Spalte (oder Seite), und ein Bild, das größer ist als dieser Anteil, wird unabhängig von seinen Pixeln darauf verkleinert (siehe [Platzierung](https://postext.dev/de/docs/document-format.md#platzierung)). In jedem Fall begrenzt der Platz das Bild unter Wahrung seiner Proportionen, und ein kleineres Bild wird nie vergrößert. Dieselbe natürliche Größe gilt für ein Bild in einer Tabellenzelle und für ein `image`-Element einer Gestaltung mit Größe `'auto'`. Das PDF bettet die Datei unverändert in ihrer platzierten Größe ein. Der [Preflight](https://postext.dev/de/docs/configuration-fonts-colors-viewers.md#preflight) prüft die Auflösung, in der jedes Bild gedruckt wird, und das [Bedienfeld Ressourcen](https://postext.dev/de/docs/sandbox.md#bedienfeld-ressourcen) der Sandbox zeigt sie für jedes Bild an. Seit postext 1.24. ```json { "id": "harbour", "typeId": "figure", "kind": "bitmap", "caption": "The harbour at dawn.", "bitmap": { "fileId": "harbour.jpg", "format": "jpeg", "width": 2400, "height": 1600, "resolution": 300 } } ``` `bitmapInfo(bytes)` (aus `postext` und `postext/bundle`) liest die Pixel einer Datei und die Auflösung, die sie angibt, `{ width, height, resolution?: { x, y, source } }`; ein unter `'file'` geöffnetes Paket füllt damit `fileResolution`, und die Sandbox speichert sie für jedes Bild, das sie hochlädt. ### Sicherheitsbereich Eine Bitmap- oder SVG-Ressource kann einen **Sicherheitsbereich** markieren: das Rechteck des Bildes, das das Wesentliche enthält (eine Person und einen Streifen der Landschaft hinter ihr, den Datenbereich eines Diagramms) und immer gezeigt wird. Es ist das `safeArea` der Ressource, vier Bruchteile (0–1) der Eigengröße des Bildes, gemessen von seiner linken oberen Ecke: `x` und `width` sind Bruchteile seiner Breite, `y` und `height` seiner Höhe. Der Name sagt, was erhalten bleiben muss; ein Beschnittrahmen würde sagen, wo geschnitten wird. ```ts const harbour: Resource = { id: 'harbour', typeId: 'figure', kind: 'bitmap', caption: 'The harbour at dawn.', createdAt: 0, updatedAt: 0, bitmap: { fileId: 'harbour.jpg', format: 'jpeg', width: 2400, height: 1600 }, // the boats and the quay: 18–68 % of the width, 25–85 % of the height safeArea: { x: 0.18, y: 0.25, width: 0.5, height: 0.6 }, }; ``` Nur ein Bild mit Sicherheitsbereich wird jemals beschnitten. Die Engine kann es dann in jedem Seitenverhältnis zwischen dem ganzen Bild und dem Sicherheitsbereich zeigen: höher als das eigene Verhältnis des Bildes, indem sie die Seiten beschneidet, höchstens bis auf die Breite des Sicherheitsbereichs, oder niedriger, indem sie oben und unten beschneidet, höchstens bis auf seine Höhe. Die Breite der Abbildung ändert sich nie, nur ihre Höhe. Was außerhalb des Sicherheitsbereichs liegt, wird auf beiden Seiten im Verhältnis der dortigen Ränder beschnitten, sodass ein Motiv links der Mitte links der Mitte bleibt. Bei 60 mm Breite ist der Hafen oben ganz 40 mm hoch und kann in jeder Höhe zwischen 24 mm (oben und unten auf 60 % der Höhe beschnitten) und 80 mm (die Seiten auf die halbe Breite beschnitten) gezeigt werden. Werte über die Bildränder hinaus werden auf diese begrenzt; ein Bereich mit einem Wert, der keine Zahl ist, oder einer Seite unter 2 % des Bildes, oder einer, der das ganze Bild abdeckt, wird ignoriert, ebenso das Feld bei einer Tabelle. Ohne Sicherheitsbereich wird ein Bild wie bisher immer ganz gezeigt. Die Engine nutzt diesen Spielraum an vier Stellen: - **Der in einer Spalte verbliebene Raum.** Ein Bild im Text (`position: 'here'`), das etwas zu hoch für den in seiner Spalte verbliebenen Raum ist, auch eines, dessen Legende über den Seitenfuß hinauslaufen würde, wird innerhalb seines Sicherheitsbereichs beschnitten, um dort zu bleiben, statt in die nächste Spalte oder auf die nächste Seite zu wandern und diese hier kurz zu lassen. - **Seiten, die niedriger sind als die Abbildung.** Mit `layout.fitFiguresToPage` wird ein Bild, das zu hoch für die Seite ist, zuerst innerhalb seines Sicherheitsbereichs beschnitten, bei gleicher Breite, und nur verkleinert, wenn es dann noch zu hoch ist (siehe [Konfiguration › Layout](https://postext.dev/de/docs/configuration-page-layout.md#layout)). - **Bänder, die niedriger sind als die Abbildung.** Ein Gleitobjekt, dessen `placement.shrink` es auf den Raum seines Platzes skaliert, wird zuerst innerhalb seines Sicherheitsbereichs beschnitten, bei gleicher Breite, und erst dann verkleinert; der Hebel `flexFigure` unten lässt es nie über diesen Raum hinaus wachsen. - **Spaltenausgleich.** Ein Bild mit Sicherheitsbereich, das im Text einer kurzen Spalte steht oder am Kopf oder Fuß dieser Spalte nur über diese Spalte gleitet, wächst um ganze Zeilen des Grundlinienrasters, um die leeren Zeilen der Spalte zu füllen. Ein höheres Bild hinterlässt kein sichtbares Loch, daher wird dieser Hebel, `flexFigure`, direkt nach dem Kasten, der die Spalte abschließt, versucht und vor jedem zusätzlichen Abstand über Überschriften oder nach Listen. Ein Gleitobjekt am Kopf einer Spalte auf der Schlussseite eines Kapitels oder in einem Schlussband wächst nicht, da diese Spaltenköpfe auf gleicher Höhe bleiben (siehe [Konfiguration › Spaltenausgleich](https://postext.dev/de/docs/configuration-text.md#spaltenausgleich)). Der VDT verzeichnet den Beschnitt am Ressourcenblock: `bodySource` ist der in `bodyRect` gezeigte Teil des Bildes, in denselben Bruchteilen (fehlt, wenn das ganze Bild es füllt), und `bodyFlex` gibt die px an, um die der Inhalt noch schrumpfen und wachsen könnte, und die px, um die die Hebel ihn bereits verändert haben (`{ shrink, grow, delta }`). Die Canvas-Vorschau und das PDF beschneiden auf den Inhalt und zeichnen das ganze Bild in unbeschnittener Größe; der HTML-Betrachter und das EPUB mit festem Layout setzen das Bild mit `object-fit: cover` und einer passenden `object-position`; ein umfließendes EPUB, das keine Seite zu füllen hat, zeigt das ganze Bild. Ein Host, der Bilder selbst zeichnet, kann die Hilfsfunktionen nutzen, die `postext` exportiert: `resourceSafeArea` und `normalizeSafeArea` (der Bereich, wie die Engine ihn liest, oder `undefined`), `safeAreaHeightRange` (der niedrigste und der höchste Inhalt bei einer Breite), `safeAreaSource` (der bei einer gegebenen Höhe gezeigte Teil) und `uncroppedPictureBox` (wo das ganze Bild vor dem Beschneiden zu zeichnen ist), mit dem Typ `ResourceSafeArea`. In der Sandbox heißt das Feld bei einem Bild im [Bedienfeld Ressourcen](https://postext.dev/de/docs/sandbox.md#bedienfeld-ressourcen) **Sicherheitsbereich**. Rezept Nº 116 im Rezeptbuch, [Fotos, die eine kurze Spalte füllen](https://postext.dev/de/cookbook/photos-fill-short-columns.md), setzt eine zweispaltige Zeitschriftenreportage zweimal, ohne und mit Sicherheitsbereichen, sodass Sie die Seiten nebeneinander vergleichen können. ### Sprecheranker und Sperrzonen Ein Bild, das die Zeichnung eines Comic-Panels ist, kann für das Lettering außerdem angeben, wo seine Figuren sind (siehe [Comics](https://postext.dev/de/docs/document-format.md#comics)). `anchors` listet einen Punkt je Sprecher und `avoid` die Bereiche, die keine Sprechblase verdeckt, beide in Bruchteilen des Bildes wie der Sicherheitsbereich: ```ts const radio: Resource = { id: 'lh-radio', typeId: 'figure', kind: 'bitmap', createdAt: 0, updatedAt: 0, bitmap: { fileId: 'lh-radio.jpg', format: 'jpeg', width: 1000, height: 1000 }, safeArea: { x: 0, y: 0.36, width: 0.62, height: 0.56 }, anchors: [ // the keeper: mouth, head (for thought balloons) and face { id: 'tomas', x: 0.345, y: 0.52, head: { x: 0.38, y: 0.44 }, face: { x: 0.29, y: 0.4, width: 0.16, height: 0.18 } }, ], avoid: [{ x: 0, y: 0.44, width: 0.22, height: 0.26 }], // the radio }; ``` Die `id` eines Ankers ist der Sprecherschlüssel des Skripts (`tomas: …`) oder `sfx` für den Punkt, an dem sich die Geräuscheffekte des Panels sammeln; `x` und `y` sind der Mund, auf den der Dorn einer Sprechblase zeigt, `head` der Punkt, auf den die Bläschen einer Gedankenblase zeigen (ohne Angabe der Mund), und `face` ein Rechteck, das keine Sprechblase verdeckt. Die Engine bildet jeden Punkt über Beschnitt und Spiegelung des Panels ab, sodass ein Dorn auf seinem Sprecher bleibt, welche Form das Panel auch annimmt; ein Anker außerhalb des Sicherheitsbereichs löst `comicAnchorOutsideSafeArea` aus, weil ein Beschnitt ihn abschneiden kann. Eine dritte Liste, `faces`, enthält die Gesichter von Figuren, die nicht sprechen, als Rechtecke wie die von `avoid`: Keine Sprechblase verdeckt sie, während eine Sperrzone nachgibt, wenn ein Panel keinen anderen Platz hat. Anker gehören zum Bild und dienen jeder Übersetzung des Comics. Nur Comic-Panels lesen sie; eine Abbildung ignoriert sie. In der Sandbox werden sie im Dialog **Sicherheitsbereich und Lettering** des [Bedienfelds Ressourcen](https://postext.dev/de/docs/sandbox.md#bedienfeld-ressourcen) markiert. ### Videos Eine **Video**-Ressource (`kind: 'video'`) ist ein YouTube- oder Vimeo-Video oder ein eigenes Video: eine im Buch gespeicherte Datei (MP4, WebM) oder eine unter einer Webadresse, eine Datei auf einem Server oder ein **HLS-Stream** (eine `.m3u8`-Playlist). Es wird wie ein Bild platziert, beschriftet, gleiten gelassen und zitiert und in einer eigenen Folge nummeriert: Der eingebaute Typ `video` druckt *Video 1.1*, *Video 1.2* … neben *Figure 1.1* und *Table 1.1* (siehe [Konfiguration › Ressourcentypen](https://postext.dev/de/docs/configuration-resources.md#ressourcentypen)). Jede Ausgabe zeigt es, so gut sie kann: | Ausgabe | Was sie zeigt | | --- | --- | | Canvas, PDF | Das **Posterbild**, ein Einzelbild des Videos, mit einem Abspielzeichen und einem QR-Code, der das Video öffnet ([Konfiguration › Videostil](https://postext.dev/de/docs/configuration-resources.md#videostil)). Im PDF ist das Posterbild außerdem ein Link zum Video. | | Folio | Das Posterbild, wie gedruckt. Ein Klick darauf spielt das Video **auf der Seite selbst** ab, und es läuft weiter, während das Blatt umgeblättert wird (siehe [Videos auf den Seiten von Folio](https://postext.dev/de/docs/document-format.md#videos-auf-den-seiten-von-folio) unten). YouTube- und Vimeo-Videos bleiben Posterbilder. | | HTML-Betrachter | Der **Player** des Videos: der von YouTube oder Vimeo oder der HTML5-Player des Browsers für eine Datei oder eine Adresse. Ein HLS-Stream läuft nativ in Safari und im aktuellen Chrome; anderswo bindet der Host einen Player wie hls.js ein, wie es die Sandbox tut. Mit `videoStyle.html: 'poster'` zeigt er stattdessen das gedruckte Posterbild. | | EPUB | Eine Datei läuft im eigenen Player des Lesesystems, im Buch verpackt oder von ihrer Produktionsadresse gelesen. Ein YouTube- oder Vimeo-Video ist sein Posterbild, mit dem Video verlinkt: Ein EPUB darf den Player einer Webseite nicht einbetten. Ein HLS-Stream ist ebenfalls sein verlinktes Posterbild: Eine HLS-Playlist ist kein Medientyp, den ein EPUB abspielen darf. Wo das Lesesystem Skripte ausführt, halten sich die Dateien einer Seite oder eines Kapitels an `player.exclusive`: Das Starten einer Datei pausiert die anderen, mit denen sie nicht gleichzeitig läuft. | ```ts const talk: Resource = { id: 'keeper-talk', typeId: 'video', kind: 'video', caption: 'The keeper explains the lamp.', altText: 'A lighthouse keeper beside the lamp', createdAt: 0, updatedAt: 0, video: { source: 'youtube', // 'youtube' | 'vimeo' | 'file' url: 'https://youtu.be/aqz-KE-bpKQ', poster: { fileId: 'talk.jpg', format: 'jpeg', width: 1280, height: 720 }, start: 30, // plays from 0:30; the printed link starts there too }, }; ``` Der Text zitiert ein Video wie eine Abbildung: `:ref{id="keeper-talk"}` druckt *Video 1.1* und lässt das Posterbild an den ersten freien Platz nach dem Verweis gleiten, und `::resource{id="keeper-talk"}` mit `placement.position: 'here'` setzt es im Text. Die Felder von `Resource.video` (`ResourceVideo`): | Feld | Typ | Bedeutung | | --- | --- | --- | | `source` | `'youtube'` · `'vimeo'` · `'file'` | Woher das Video abgespielt wird: von einer YouTube- oder Vimeo-Seite oder als eigenes Video (`'file'`), hochgeladen oder unter einer Adresse. | | `url` | `string` | YouTube oder Vimeo: die Adresse des Videos in beliebiger Form (eine Watch-Seite, `youtu.be`, Shorts, ein Embed-Link, `youtube-nocookie.com`; eine Vimeo-Seite, Kanalseite oder ein nicht gelisteter Link mit seinem Hash). Eine Datei: ihre **Produktionsadresse**, unter der das veröffentlichte Buch sie findet. Ein eigenes Video ohne eigene Datei wird von dieser Adresse abgespielt: eine MP4- oder WebM-Datei auf einem Server oder ein HLS-Stream (`…/master.m3u8`). | | `fileId`, `format` | `string` | Eine Datei: das hochgeladene Video, wie eine Bitmap außerhalb des Dokuments gespeichert, und sein Format: `'mp4'`, `'webm'`, `'ogv'`, `'mov'` oder `'hls'` für einen HLS-Stream. Ohne Format bestimmt es die Dateiendung der Adresse (`.m3u8` ist `'hls'`), sonst `'mp4'`. | | `poster` | `{ fileId, format, width, height }` | Das Posterbild, eine Bitmap. | | `width`, `height`, `duration` | `number` | Die Bildgröße des Videos in px (sein Seitenverhältnis, wenn es kein Posterbild gibt) und seine Länge in Sekunden. | | `posterTime` | `number` | Die Sekunde des Einzelbildes einer Datei, das als Posterbild dient, gespeichert, damit es erneut gewählt werden kann. | | `start`, `end` | `number` | Von `start` bis `end` Sekunden abspielen. Der QR-Code und der PDF-Link beginnen ebenfalls bei `start`. | | `player` | `VideoPlayerOptions` | Die Player-Optionen dieses Videos, über `videoStyle.player` gelegt. | **Das Posterbild.** Es wird in der Satzbreite seines Platzes gesetzt (oder im Anteil `placement.width` davon), in seinem eigenen Seitenverhältnis, unabhängig von seiner Pixelgröße: Ein bildschirmgroßes Einzelbild wird vergrößert, statt klein gedruckt zu werden. Wie eine Bitmap kann es einen [Sicherheitsbereich](https://postext.dev/de/docs/document-format.md#sicherheitsbereich) tragen und `placement.align` folgen. Ein Video ohne Posterbild druckt einen dunklen Kasten im Seitenverhältnis des Videos (16:9, wenn nichts anderes angegeben ist) mit seinen Überlagerungen und löst die Inhaltswarnung `videoWithoutPoster` aus. In der Sandbox wird das Posterbild eines YouTube- oder Vimeo-Videos von der Plattform geholt, sobald seine Adresse eingegeben wird, und das einer Datei ist ein Einzelbild, das Sie im Video auswählen. **Die Adresse.** Der QR-Code und der PDF-Link öffnen die Seite des Videos, `https://youtu.be/` oder `https://vimeo.com/`, ab `start`. Eine Datei hat keine Seite: Sie öffnen ihre Produktionsadresse, von der auch ein Video ohne eigene Datei abgespielt wird (eine MP4-Datei auf einem Server, ein HLS-Stream). Ohne eine solche Adresse erhält der Druck weder QR-Code noch Link (`videoWithoutUrl`), und eine HTML- oder EPUB-Ausgabe, die die Datei nicht mitführt, zeigt das Posterbild. Eine YouTube- oder Vimeo-Adresse, die kein Video dieser Plattform nennt, löst `videoUrlInvalid` aus; statt eines Players wird das Posterbild gezeigt. **Die Player.** Die Player-Optionen (Bedienelemente, Download-Schaltfläche, Vollbild, Geschwindigkeitsmenü, Bild-in-Bild, Casting, automatisches Abspielen, stummer Start, Schleife, Vorladen, datenschutzfreundliche Einbettung) werden für das ganze Buch in `videoStyle.player` und für ein einzelnes Video in `video.player` gesetzt; jeder Player berücksichtigt, was er kann (siehe [Konfiguration › Videostil](https://postext.dev/de/docs/configuration-resources.md#videostil)). Das HTML-Backend erhält die abspielbare URL einer Datei über die Option `resourceVideoUrl(fileId)`, so wie es Bilder über `resourceImageUrl` erhält, und fällt auf die Produktionsadresse zurück. Seine Option `videos: { files, streams, hls }` wählt je Quelle zwischen Player und Posterbild, über `videoStyle.html` hinweg (`hls`, ein von einer HLS-Adresse abgespieltes Video, folgt ohne eigene Angabe `files`); der EPUB-Writer verwendet sie. Ein `