Konfiguration: Kästen

#Kastenstile

Die Eigenschaft calloutStyles deklariert die benannten Kastenstile, die ein Dokument mit einem Container :::callout{type="…"} anwendet – Anmerkungen, Tipps, Warnungen, Lernziele, jeder Inhalt, der in einem getönten oder umrandeten Kasten vom Fließtext abgesetzt wird. Ein neutraler Stil, note, ist standardmäßig dabei (hellgrauer Hintergrund, kein Rahmen, kein Streifen, kein Symbol, kein Titel), sodass :::callout ohne jede Konfiguration funktioniert; wer calloutStyles deklariert, ersetzt diese Standardliste.

const config: PostextConfig = {
  calloutStyles: [
    { id: 'note', name: 'Note' },
    {
      id: 'objectives',
      name: 'Learning objectives',
      title: 'Objectives',
      stripe: { enabled: true, side: 'left' },
      icon: { kind: 'glyph', glyph: '✓' },
      titleStyle: { textTransform: 'uppercase' },
      lists: { bulletChar: '–' },
    },
    {
      id: 'warning',
      title: 'Warning',
      backgroundEnabled: false,
      border: { enabled: true, color: { hex: '#AA0000', model: 'hex' }, width: { value: 1, unit: 'pt' } },
      borderRadius: { value: 1, unit: 'mm' },
      titleStyle: { color: { hex: '#AA0000', model: 'hex' } },
    },
  ],
};

:::callout{type="objectives"}
- Describe the parts of the lantern.
- Trim the wick at dusk.
:::
 
:::callout{type="warning" title="Do not touch the lens"}
The glass stays hot for an hour after the flame is out.
:::

#Der Container :::callout

Eine Zeile :::callout{type="<id>"} öffnet den Kasten, eine bloße Zeile ::: schließt ihn. Die Einfassung nimmt fünf Attribute an – type (die ID des Stils), title (überschreibt den Titel des Stils), span, placement und columns (überschreiben die Werte des Stils) –, und der Inhalt dazwischen wird im Kasten gesetzt: ein optionaler Titel, dann die Absätze, Listen, Zitatblöcke, Formeln oder Ressourceneinbettungen, jeweils mit der Typografie body / lists des Stils (Überschriften behalten ihre üblichen Stile). Außenabstände zwischen Kindblöcken fallen wie im Fließtext zusammen; das Innere verlässt das Grundlinienraster, und der Fluss rastet nach dem Kasten mit mindestens marginBottom darunter wieder darauf ein (das Raster hat Vorrang; der Außenabstand ist ein Mindestwert – dieselbe Konvention, der Ressourcen folgen). Ein Stil mit snapToGrid: false behält stattdessen das genaue marginBottom, und der Text nach dem Kasten bleibt bis zur nächsten Überschrift oder zum nächsten Listenende außerhalb des Rasters. Eine Überschrift unmittelbar vor einem Kasten bleibt bei ihm.

Grenzen in dieser Version:

• Ein Kasten wird zusammengehalten, sofern sein Stil nicht keepTogether: false setzt. Passt er nicht in den verbleibenden Spaltenraum, wandert er ganz in die nächste Spalte oder auf die nächste Seite – auch aus einer leeren Spalte, die Gleitobjekt-Bänder oder eine Bandgrenze verkürzt haben, solange eine volle Spalte ihn fassen würde. Ein Kasten, der höher als eine volle Spalte ist, wird stattdessen geteilt, wie ein teilbarer; nur einer, den kein Schnitt teilen kann (eine Abbildung oder Tabelle, die höher als die Spalte ist, oder ein splitMinLines, das kein Schnitt erfüllt), wird trotzdem platziert und läuft über; das Layout vermerkt dann eine Warnung calloutOverflow (VDTDocument.warnings), die die Sandbox auflistet. Eine Gruppe :::columns wird wie der Kasten um sie herum geschnitten, zwischen ihren Unterspalten (seit postext 1.25); sie bleibt nur mit layout.flowColumns: false oder in einem verschachtelten Kasten ganz und kann dann ebenso überlaufen. Ein teilbarer Kasten lässt den passenden Teil zurück – ganze Kindblöcke oder die Zeilen eines Absatzes bis hinab zu splitMinLines auf jeder Seite (eine Abbildung, Tabelle oder abgesetzte Formel allein genügt für eine Seite) – und geht in einem Kasten ohne Symbol in der nächsten Spalte oder auf der nächsten Seite weiter, ohne Titel, sofern der Stil ihn nicht wiederholt, und optional mit einem Hinweis unter dem verlassenen Teil (siehe Hinweise an einem geteilten Kasten).
• Gleitobjekte weichen einem unteilbaren Kasten. Ist der Block direkt nach dem Verweis auf eine Abbildung ein Kasten mit keepTogether, wird ein Platz, der dem Kasten keine Spalte des aktuellen Bands zum Landen ließe (die verweisende Spalte oder eine leere danach, die ihn vor dem Gleitobjekt aufgenommen hat), nicht genommen: Die Abbildung geht zu ihrem nächsten Platz weiter, meist auf der nächsten Seite, und der Kasten bleibt im Fluss – so, wie ein Setzer ihn setzen würde, statt den Kasten von der Seite zu drängen und die Spalte mit der Abbildung allein zu lassen.
• span: 'page' in einem mehrspaltigen Layout macht den Kasten zu einem Spannblock: Er wird auf die volle Inhaltsbreite gesetzt und teilt die Seite in Spaltenbänder – die Textspalten darüber werden an der Schnittlinie geschlossen, der Kasten nimmt eine eigene Spalte über die volle Breite ein, und darunter öffnet sich ein neues Band von Textspalten, sodass der Fluss in jeder Spalte unter dem Kasten weitergeht. Wo die Spalten ausgeglichen sind – am Kopf einer Seite, direkt unter einer Auftaktüberschrift mit span: 'page', direkt unter einem anderen Spannblock oder direkt unter einem Gleitobjekt-Band am Kopf –, schneidet der Kasten einfach dort. Kommt er mitten auf der Seite an, bei ungleichen Spalten, wird er so gesetzt, wie es ein Setzer täte: Der Text darüber wird über alle Spalten ausgeglichen geschnitten (die Engine wiederholt die Platzierung mit Spalten des Bands, die auf dieselbe Zahl von Rasterzeilen gekürzt sind, sodass der Text natürlich von Spalte zu Spalte überläuft und jede Regel zu Waisen, Witwen und Zusammenhalt mit dem Folgenden weiterhin gilt), der Kasten überspannt die Seite, und die Spalten gehen darunter weiter. Der Schnitt kostet einige zusätzliche Platzierungsdurchgänge; ließe die Schnittlinie keinen Raum für den Kasten plus das Witwenminimum an Fließtextzeilen darunter, oder passt nach einigen Versuchen keine Anordnung, wandert der Kasten an den Kopf der nächsten Seite. Der Text darüber hält sich an den Schnitt: Ein Absatz, der in den wenigen Zeilen, die eine Spalte unter einer Abbildung darüber freihält, nicht beginnen kann, geht in die nächste Spalte (die Abbildung steht dann allein in ihrer Spalte), und würde ein Block dennoch über den Schnitt hinauslaufen, wird der Schnitt eine Zeile tiefer gesetzt, statt dort, wo dieser Block endet. Ein geteilter Kasten, der das Band eröffnet, wird ebenfalls dort geschnitten, sodass sein Rest nie über den Schnitt hinausläuft. Mit headings.balancing.beforeSpan (dem Standard) wird das verlassene Band hinter ihm ausgeglichen geschnitten – wie das abschließende Band eines Kapitels –, und wenn der Stil das Teilen erlaubt (keepTogether: false), schließt der Teil des Kastens, der unter die ausgeglichenen Spalten passt, die Seite ab, und der Rest eröffnet die nächste; mit beforeSpan: false wird die verlassene Seite einfach wie üblich ausgeglichen, ohne einen Seitenumbruch zu erzwingen. Eine Überschrift direkt vor einem Spannblock wandert nicht mit ihm. In einspaltigen Layouts ist span: 'page' einfach ein Kasten im Fluss.
• placement: 'fixed' nimmt den Kasten aus dem Fluss: Er wird gesetzt (width: 'auto' passt sich eng an den Titel an; 'fill' nimmt die Breite der Textspalte unter dem Ankerpunkt) und auf der Seite, auf der er im Fluss vorkommt, an der Position fixiert, die fixed.anchor / fixed.offset beschreiben – standardmäßig die linke untere Ecke des Inhaltsbereichs. Die Textspalten, die er überdeckt, geben diese Zone frei (von unten abgeschnitten oder von oben, wenn die Spalte noch leer ist), genau wie bei einem Gleitobjekt-Band; enthält die Zone bereits Text, ein Gleitobjekt oder einen Spannblock, wandert der Kasten auf die nächste Seite. Ein fixierter Kasten, der das Kapitel abschließt (der nächste Block ist ein Kapitelauftakt, ein :::part, ein Schrankenkasten oder das Ende des Dokuments), gleicht zuerst die Spalten darüber aus (headings.balancing.trailing), sodass eine kurze Schlussseite ausgeglichen über dem Abzeichen darunter endet. Rahmen und Kindblöcke stehen in page.floats und werden in jeder Ausgabe außerhalb des Spaltenbeschnitts gezeichnet.
• placement: 'top' | 'bottom' lässt den Kasten wie eine Ressource gleiten: Er verlässt den Fluss an seiner Stelle und nimmt das erste freie Band nach diesem Punkt – den Fuß der aktuellen Seite ('bottom') oder Kopf / Fuß der nächsten Seite, die der Fluss eröffnet – in Spaltenbreite (span: 'column') oder in voller Inhaltsbreite (span: 'page'); der Text danach füllt die verlassene Seite. Rahmen und Kindblöcke kommen in page.floats, wie bei einem fixierten Kasten. Ein gleitender Kasten, der eine neue Seite anführt, wird vor den Abbildungen gesetzt, die auf diese Seite warten, und eine Abbildung, auf die auf einer früheren Seite verwiesen wurde und die dann darunter passt, nimmt den Rest dieser Seite, auch wenn weniger als drei Textzeilen übrig blieben (eine Galerieseite: Kasten plus Abbildung, kein Text dazwischen). Ein Kasten mit span: 'side' gleitet nie: Er stapelt sich neben dem Text, gleich welche Platzierung er hat. Mit columns über 1 (im Stil oder als Attribut der Einfassung, seit postext 1.18) nimmt ein Kasten mit span: 'column' so viele benachbarte Spalten ein: den Kopf einer Folge leerer Spalten, die auf gleicher Höhe beginnen, oder den Fuß der aktuellen Spalte und der leeren danach, wie in :::callout{placement="top" columns="2"}.
• width: 'auto' passt sich nur eng an den Titel an; Kindblöcke werden ignoriert.
• Ein in einem anderen Kasten verschachteltes :::callout ist ein eigener Kasten: Es wird mit seinem eigenen Stil (Hintergrund, Rahmen, Radius, Innenabstand, Streifen, Titel, Symbol, Marker, Reiter, Typografie) auf die volle Innenbreite seines Elternkastens gesetzt und stapelt sich als ein Kindblock darin, wobei sein marginTop / marginBottom mit den Nachbarn zusammenfällt. Sein span und placement (aus Einfassung oder Stil) werden ignoriert – ein verschachtelter Kasten fließt immer in seinem Elternkasten –, ebenso floatBarrier und snapToGrid. Kästen lassen sich beliebig tief verschachteln und können in einer Gruppe :::columns stehen (jeder ganz, in einer Spalte). Wird der Elternkasten geteilt, fällt der Schnitt vor oder nach einem verschachtelten Kasten oder in ihn, wenn der verschachtelte Stil das Teilen erlaubt; jedes Fragment zeichnet die Rahmen neu, die es durchschneidet, und ein verschachtelter Kasten, der aus dem vorigen Fragment fortgesetzt wird, verliert Titel und Symbol, wie eine Fortsetzung auf oberster Ebene.
• Eine Gruppe :::columns{count=N} … ::: unter den Kindblöcken setzt diese Kindblöcke im Kasten in N gleich breiten Spalten im Abstand columnGap: Die Folge wird an den Block- oder Zeilengrenzen geschnitten, die die Spalten am besten ausgleichen (ein mittendrin geschnittener Absatz oder Listeneintrag geht am Kopf der nächsten Spalte ohne sein Aufzählungszeichen weiter), jede Spalte beginnt am Kopf der Gruppe, und die Gruppe ist so hoch wie ihre höchste Spalte; die Kindblöcke danach kehren zur vollen Breite zurück. Ein Kasten, der sich teilt (keepTogether: false oder höher als eine Spalte), schneidet auch innerhalb einer Gruppe, zwischen ihren Spalten: Eine fortlaufende Gruppe füllt ihre Spalten der Reihe nach und geht im nächsten Fragment weiter, eine parallele (breaks) geht Strang für Strang weiter (seit postext 1.25; siehe Dokumentformat › :::columns). Ein gap an der Einfassung ersetzt columnGap für diese Gruppe, und rule zieht eine Linie durch jeden Spaltenabstand. Verwenden Sie es für eine zweispaltige Zusammenfassung von Kernpunkten oder für nebeneinandergesetzte Tabellen eines breiten Kastens.
• Das sechste Attribut der Einfassung, label, erscheint auf dem Reiter des Stils (siehe label oben) – :::callout{type="box" label="BOX 1-1" title="The octet rule"}; ohne einen Stil label wird das Attribut ignoriert.

Im VDT ist der Kasten ein Rahmenblock mit type: 'callout', dessen Schmuck (Hintergrund, Streifen, Symbol, Titel) in designOverlay liegt, gefolgt von seinen Kindblöcken in derselben Spalte; der Rahmen und jeder Kindblock tragen die containerId der Einfassung. Ein verschachtelter Kasten ist ein eigener Rahmen mit type: 'callout' unter den Kindblöcken, gefolgt von seinen Blöcken; sie behalten die containerId der Einfassung auf oberster Ebene (Platzierung und Ausgleich sehen weiterhin eine Einheit) und fügen calloutPath hinzu, die Container-IDs der umgebenden verschachtelten Einfassungen, die äußerste zuerst (die eigene ID eines verschachtelten Rahmens ist der letzte Eintrag). Das getaggte PDF gibt jedem verschachtelten Kasten ein Div innerhalb dessen seines Elternkastens. Symbolbilder werden wie Ressourcenbilder aufgelöst: über das Bildregister des Canvas, die HTML-Option resourceImageUrl und den PDF-Provider resourceBytes.

const resolved = resolveCalloutStylesConfig(config.calloutStyles, resolvedBodyText, resolvedHeadings, resolvedUnorderedLists, config.locale);
// => every inherited field filled from the resolved sections; the optional
//    locale picks the language of the continuation strings
 
const minimal  = stripCalloutStylesDefaults(config.calloutStyles);
// => undefined for the built-in `note` default; static defaults dropped

#Nummerierte Aussagen und Beweise

Ein Stil mit numbering zählt seine Kästen, so wie amsthm in LaTeX Theorem-Umgebungen zählt (seit postext 1.19). Jeder Kasten druckt seine Bezeichnung und Nummer – „Theorem 2.“ zu Beginn seines ersten Absatzes –, und der title der Einfassung folgt der Nummer in Klammern: :::callout{type="theorem" title="Bradley–Terry"} beginnt mit „Theorem 2 (Bradley–Terry).“. Ein Kasten, der mit einem Bezeichner eröffnet wird ({#thm:main}), ist ein Ziel von Querverweisen, die „Theorem 2“ drucken (:ref{id="thm:main"}), und \ref{thm:main} oder style=number druckt 2.

Ein Beweis ist ein Stil mit einer nicht nummerierten Bezeichnung und einem Schlusszeichen:

calloutStyles: [
  { id: 'theorem', numbering: { label: 'Theorem' }, body: { italic: true } },
  { id: 'lemma', numbering: { label: 'Lemma', counter: 'theorem' }, body: { italic: true } },
  { id: 'definition', numbering: { label: 'Definition' } },
  { id: 'proof', backgroundEnabled: false, endMark: '□',
    numbering: { label: 'Proof', counter: false, bold: false, italic: true } },
]

In einem Buch, das Kapitel für Kapitel umbrochen wird, zählen die Zähler vom vorigen Kapitel aus weiter (LayoutContinuation.statementCounters, das continuationAfter füllt), und die Gliederung des Buchs gibt dem Anker jedes nummerierten Kastens seine Bezeichnung (OutlineEntry.numberLabel), sodass ein Verweis aus einem anderen Kapitel sie druckt.

#Typografie im Kasten

Ein Kasten setzt seinen Inhalt mit seiner eigenen Typografie body und lists; alles andere behält die Stile des Dokuments:

• Absätze übernehmen den body des Kastens: Schrift, Größe, Zeilenabstand, Farbe, Auszeichnungsfarben, Schriftstärken, italic, smallCaps, Ausrichtung, Silbentrennung, Einzug und Absatzabstand. Ein nicht gesetztes Feld erbt bodyText. Eine geerbte Auszeichnungsfarbe behält ihre Bindung an die Palette, sodass sich fetter und kursiver Text sowie Bezeichnungen von :ref in einem Kasten mit colorPalette ändern wie außerhalb. (Bis postext 1.4 blieb Fettes in einem Kasten #295AA3, gleich welche Hauptfarbe galt.)
• Aufzählungen übernehmen die lists des Kastens (Aufzählungszeichen, Farbe, Glyphengröße und -stärke, Einzug, Abstand, Eintragsabstand) über unorderedLists, und ihr Text ist der Text des Kastens. Ein lists.bulletChar oder lists.color, das von dem des Dokuments (unorderedLists) abweicht, ersetzt Aufzählungszeichen oder Farbe jeder Ebene; eines, das ihn wiederholt oder nicht gesetzt ist, lässt jeder Ebene ihren eigenen Wert (unorderedLists.levels), sodass verschachtelte Striche im Kasten erhalten bleiben.
• Nummerierte Listen übernehmen lists.indent, gap und itemSpacing sowie lists.color, sobald der Stil es setzt – auch wenn es die Farbe der Aufzählungszeichen des Dokuments ist; ein Stil, der es nicht setzt, behält die Nummern in orderedLists.color. (Bis postext 1.4 erreichte die Farbe die Nummern nur, wenn sie von unorderedLists.color abwich, sodass es nichts bewirkte, sie auf genau diese Farbe zu setzen.) Die Nummer selbst – Schrift, Größe und Trennzeichen – stammt aus dem globalen orderedLists, da lists nur Felder für Aufzählungszeichen hat: Gestalten Sie die Nummern eines Kastens dort.
• :::paragraphs im Kasten verwenden ihr Absatzformat, auch in verschachtelten Kästen. Die Felder, die das Format nicht setzt, erben den bodyText des Dokuments, nicht den body des Kastens (auch nicht dessen Kursive oder Kapitälchen).
• Gruppen :::columns haben keinen eigenen Stil: Jede Spalte teilt die Text- und Listentypografie des Kastens, und columnGap setzt den Abstand zwischen ihnen.
• Zitatblöcke übernehmen Schrift, Größe und Schriftstärken des Kastentexts (kursiv und grau, wie im Fließtext) sowie seine Kapitälchen. Überschriften behalten die Überschriftenstile, abgesetzte Formeln die Mathematik-Einstellungen.
• Abbildungen und Tabellen behalten die Legenden- und Tabellenstile des Dokuments, in der Innenbreite des Kastens; ihre normalen und fetten Schriftstärken folgen denen des body des Kastens.
• Chips behalten ihren Chip-Stil; eine Größe in em wird an der Schriftgröße des Kastentexts gemessen.
• :::space wird in Zeilen des Kastentexts gemessen (siehe :::space dazu, wo es entfällt).
• Ein verschachtelter Kasten übernimmt seinen eigenen Stil vollständig; sein span, placement, floatBarrier und snapToGrid werden ignoriert.

#Hinweise an einem geteilten Kasten

Teilt sich ein Kasten über Spalten oder Seiten (keepTogether: false oder ein Kasten, der höher als eine Spalte ist), beginnt jeder Teil nach dem ersten ohne Titel und Symbol, und standardmäßig sagt nichts dem Leser, dass der Kasten weitergeht. Zwei Optionen fügen die Hinweise hinzu, die ein Buch oder ein Drehbuch verwendet:

• repeatTitle: true wiederholt den Titel am Kopf jeder Fortsetzung, gefolgt von continuedSuffix – standardmäßig „Key points (cont.)“. Die Wiederholung übernimmt den Titelstil, sodass sie mit textTransform: 'uppercase' das „HAMLET (CONT'D)“ eines Drehbuchs ergibt. Symbol und Reiter bleiben am ersten Teil.
• continuesMarkerEnabled: true setzt continuesMarker – „Continued“ oder „Continúa“ in einem spanischen Dokument – unter die letzte Zeile jedes weitergehenden Teils, innerhalb des Kastens, in Schrift und Größe des Kastentexts: kursiv, sofern continuesMarkerItalic nicht false ist, rechtsbündig, sofern continuesMarkerAlign nicht 'left' oder 'center' angibt. Der Hinweis nimmt Raum in dem Teil ein, den er abschließt, und der Schnitt wird so gewählt, dass er passt.

calloutStyles: [{
  id: 'speech',
  keepTogether: false,
  titleStyle: { textTransform: 'uppercase' },
  repeatTitle: true,
  continuedSuffix: "(CONT'D)",
  continuesMarkerEnabled: true,
  continuesMarker: '(MORE)',
  continuesMarkerAlign: 'center',
  continuesMarkerItalic: false,
}],

:::callout{type="speech" title="Hamlet"}
A speech long enough to run over the foot of the page…
:::

Der Teil, der die Seite abschließt, endet mit „(MORE)“, und die nächste Seite beginnt mit „HAMLET (CONT'D)“. Beides gehört zum Paginierungszubehör: In einem barrierefreien PDF sind es Artefakte, und im HTML sind sie vor assistiven Technologien verborgen, sodass der Titel nur einmal vorgelesen wird. Im VDT sind es Textblöcke in designOverlay mit dem Flag artifact: true.