Style Guide – MyST-Markdown (Medizinisches Kompendium)

18.6.3. Style Guide – MyST-Markdown (Medizinisches Kompendium)#

Dieses Kapitel enthält die verbindlichen projektspezifischen Regeln für den MyST-Quelltext des Kompendiums. Die allgemeine Einführung und zusätzliche Syntaxbeispiele finden sich in MyST-Markdown Kurzanleitung. Bei Abweichungen zwischen einem allgemeinen Beispiel und einer hier beschriebenen Projektregel gilt die Projektregel. Fachliche und sprachliche Redaktionsregeln stehen in Inhalts- und Textgestaltung; Vorgaben zu Gestaltung, Farben und Abbildungen in Design Guidelines.

  • Die Quelldokumente werden als MyST-Markdown-Quelltext gepflegt.

  • Technische Struktur und Semantik der MyST-Auszeichnungen bleiben erhalten.

  • Die veröffentlichte Darstellung wird aus dem Quelltext über Sphinx/Jupyter Book und für PDF über LuaLaTeX erzeugt.

MyST Markdown: Quelltext und Gliederung#

  • Jeder vollständige Satz beginnt in einer eigenen physischen Quelltextzeile

  • Ein Satz wird nicht aufgrund einer Zeilenlängenbegrenzung auf mehrere Quelltextzeilen verteilt

  • Tab = 4 spaces: Pro Verschachtelungsebene wird um vier Leerzeichen eingerückt

  • Lokale Verweise auf benannte Abschnitte werden bevorzugt mit {ref} gesetzt

  • Semantisches *...* wird beibehalten, auch wenn die für die PDF-Ausgabe verwendete Schrift Lexend keinen eigenständigen kursiven Schnitt nutzt

  • Tabellen, Admonitions, Glossare, Formeln und andere MyST-Elemente werden entsprechend ihrer jeweiligen inhaltlichen Funktion verwendet. Für Tabellen gelten die Regeln im folgenden Abschnitt „Tabellen: MyST list-table“.

Listen#

  • Ungeordnete Listeneinträge beginnen mit -   (Bindestrich und soviele Leerzeichen, dass um 4 Leerzeichen eingerückt wird (hier: 3))

  • Nummerierte Listeneinträge beginnen mit 1.  (Ziffer, Punkt, soviele Leerzeichen, dass um 4 Leerzeichen eingerückt wird (hier: 2))

  • Field-Lists sind ein eigenständiges Strukturelement und werden nicht durch Überschriften oder Tabellen ersetzt

  • Field-List-Werte beginnen mit :   ; zwischen zwei Field-List-Einträgen stehen zwei Leerzeilen

  • Vor und nach einem zusammenhängenden Field-List-Block stehen zwei Leerzeilen

  • Begriffe vor dem Doppelpunkt einer Field-List werden nicht zusätzlich fett oder kursiv ausgezeichnet, da die Darstellung bereits die Hervorhebung übernimmt

  • Bestehende Hervorhebungen in den Werten einer Field-List oder im Fließtext bleiben erhalten, wenn keine inhaltliche oder redaktionelle Änderung dies erfordert

  • Stichwörter, Satzfragmente und infinitivische Handlungsanweisungen in Listen und Field-Lists erhalten keinen Schlusspunkt; vollständige Sätze erhalten einen Schlusspunkt

  • Zusammenhängender Fließtext wird nicht als Pseudo-Liste formatiert

Überschriften#

Eine Überschriftseinheit besteht aus:

  1. Indexeinträgen

  2. Label

  3. Überschrift

  • Vor Überschriften, oder den der Überschrift zugehörigen Label- oder Index-Einträgen, sofern vorhanden, stehen fünf Leerzeilen, sofern der unmittelbar vorausgehende Inhalt nicht selbst eine Überschrift ist

  • Zugehörige MyST-Indexdirektiven und Labels (Label)= stehen direkt im Block der folgenden Überschrift

  • Vorhandene MyST-Direktiven mit Colon-Fences (:::{...}), Rollen, Labels, Indexeinträge und Querverweise entsprechen der Projektsyntax

  • Überschriften erhalten keine zusätzliche dekorative Fett- oder Kursivformatierung

  • Die bestehende Hierarchie von Überschriften, benannten Labels, Indizes, Glossaren und Referenzzielen bleibt konsistent

Beispiel

:::{index} single: Begriff
:::

(label)=

## Überschrift

Tabellen: MyST list-table#

  • Das bevorzugte Tabellenformat ist die MyST-Direktive list-table. Herkömmliche Markdown-Tabellen mit Pipe-Syntax (|) sollen grundsätzlich vermieden werden.

  • Die Direktive verwendet Colon-Fences in der Form :::{list-table}. Der optionale Tabellentitel steht unmittelbar nach dem Direktivenamen, beispielsweise :::{list-table} Vergleich der Verfahren.

  • Tabellen, auf die im Text verwiesen wird, erhalten mit :name: ein eindeutiges Referenzziel. Querverweise erfolgen bevorzugt mit {ref}.

  • Tabellenzeilen beginnen mit *   , Tabellenzellen mit -   . Jede weitere Verschachtelungsebene wird um vier Leerzeichen eingerückt; Tabulatoren werden nicht verwendet.

  • Zwischen Direktivenoptionen und Tabelleninhalt steht eine Leerzeile.

  • Jede Tabellenzeile enthält die gleiche Anzahl von Zellen. list-table unterstützt keine verbundenen Zellen über mehrere Zeilen oder Spalten.

  • Inhaltlich eigenständige Kategorien und Vergleichsmerkmale erhalten eigene Spalten, sofern dies die Lesbarkeit verbessert. Unzusammenhängende Sachverhalte werden nicht ohne inhaltlichen Grund in einer Tabellenzelle zusammengefasst.

  • Kopfzeilen werden nur verwendet, wenn sie für das Verständnis der Tabelle sinnvoll sind. Bei Tabellen mit Kopfzeile wird :header-rows: 1 verwendet; die erste Tabellenzeile enthält die Spaltenüberschriften. Bei Tabellen ohne Kopfzeile wird :header-rows: 0 verwendet oder die Option weggelassen. Eine Kopfzeile wird nicht allein aus formalen Gründen hinzugefügt.

  • :stub-columns: 1 kann verwendet werden, wenn die erste Spalte die Zeilenbezeichnungen enthält.

  • :widths: kann bei Bedarf die relativen Spaltenbreiten festlegen. Die Anzahl der Breitenangaben muss der Anzahl der Spalten entsprechen.

  • Spaltenüberschriften und über :stub-columns: ausgezeichnete Zeilenbezeichnungen erhalten keine zusätzliche Markdown-Fettschrift. Darüber hinausgehende Hervorhebungen werden nur verwendet, wenn sie eine eigenständige semantische Bedeutung besitzen.

  • Tabellenzellen können Fließtext, mehrere Absätze, Listen, Formeln, Literaturreferenzen und weitere geeignete MyST-Elemente enthalten. Der Inhalt bleibt gemäß der erforderlichen Listenverschachtelung eingerückt.

  • Auch innerhalb von Tabellenzellen beginnt jeder vollständige Satz in einer eigenen physischen Quelltextzeile. Sätze werden nicht aufgrund einer Zeilenlängenbegrenzung umgebrochen.

  • Stichwörter und Satzfragmente in Tabellenzellen erhalten keinen Schlusspunkt; vollständige Sätze erhalten einen Schlusspunkt.

  • Bestehende MyST-Rollen, Literaturverweise, Indexeinträge und Querverweise bleiben innerhalb von Tabellenzellen erhalten. Bereits vorhandene Indexeinträge werden nicht unbeabsichtigt dupliziert.

  • Erforderliche Markdown-Escapezeichen bleiben erhalten, beispielsweise bei der wörtlichen Darstellung von Pluszeichen als \+.

  • Tabellen und Field-Lists erfüllen unterschiedliche semantische Funktionen. Bestehende Field-Lists werden nicht allein deshalb durch Tabellen ersetzt, weil ihre Inhalte auch tabellarisch darstellbar wären. Dies gilt insbesondere für die Field-Lists der Arzneimittelmonographien.

  • Bei der Umwandlung bestehender Tabellen bleiben Zeilen- und Spaltenreihenfolge, Zuordnung der Inhalte, Referenzen und semantische Hervorhebungen erhalten, sofern keine inhaltliche Änderung beabsichtigt ist.

  • Für Darstellungen, die verbundene Zellen oder andere von list-table nicht unterstützte Funktionen zwingend benötigen, kann begründet auf ein anderes geeignetes Tabellenformat ausgewichen werden.

  • Die Lesbarkeit und korrekte Darstellung müssen sowohl in der HTML- als auch in der PDF-Ausgabe gewährleistet sein.

Beispiel: Tabelle mit Kopfzeile#

:::{list-table} Vergleich der Verfahren
:header-rows: 1
:name: Tab-Verfahrensvergleich
:widths: 30 35 35

*   -   Verfahren
    -   Merkmal
    -   Besonderheit
*   -   Verfahren A
    -   Merkmal A
    -   Besonderheit A
*   -   Verfahren B
    -   Merkmal B
    -   Besonderheit B
:::

Beispiel: Tabelle ohne Kopfzeile#

:::{list-table}
:header-rows: 0
:stub-columns: 1
:widths: 30 70

*   -   Bezeichnung
    -   Kurze Beschreibung
*   -   Besonderheiten
    -   Erster vollständiger Satz.
        Zweiter vollständiger Satz.
*   -   Unterpunkte
    -   -   Erster Unterpunkt
        -   Zweiter Unterpunkt
:::

Ordner- und Dateistruktur#

  • Die Dokumente befinden sich im Verzeichnis Text.

  • Jeder Teil hat einen separaten Unterordner. Die Ordner der Teile haben eine zweistellige fortlaufende Nummer gemäß ihrer Reihenfolge als Präfix, getrennt mit einem Unterstrich nach dem Muster Teilnummer_Kurztitel, z. B. 07_Skills.

  • Die Kapitel haben ebenfalls eigene Unterordner nach dem Muster Kapitelnummer_Kurztitel, z. B. 02_CRM.

  • Die Hauptdatei eines Teils oder Kapitels ist jeweils index.md im entsprechenden Verzeichnis.

  • Kapitel können in einzelne Abschnitte unterteilt werden, die normalerweise als separate Dateien im Kapitelordner abgelegt werden. Die Abschnittsdateien werden gemäß ihrer Reihenfolge im Kapitel fortlaufend nummeriert, z. B. 02_Mechanische-Therapie.md (Text/08_Reanimation/01_Einleitung-Saeulen/02_Mechanische-Therapie.md).

  • Ob die Abschnitte eines Kapitels in separaten Dateien oder gemeinsam in der index.md abgebildet werden, hängt vom Umfang und der Struktur der Inhalte ab.

  • Bei besonderen Anforderungen kann von dieser Struktur abgewichen werden. Zusätzliche Unterordner können angelegt werden, wenn dies aufgrund der Inhalte notwendig ist.

  • In der Pharmakopeia entfällt das numerische Präfix der Abschnittsdateien, da sich deren Reihenfolge aus dem Alphabet ergibt.

YAML-Frontmatter und Dokumentstatus#

Das standardisierte YAML-Frontmatter enthält die folgenden Schlüssel in dieser Reihenfolge:

  1. status

  2. changes

  3. maintainer

  4. authors

  5. copyright

  6. license

  • Das Frontmatter muss gültiges YAML sein

  • Für changes wird die projektübliche eingerückte Liste mit datierten Änderungen verwendet; bestehende Einträge werden erhalten

  • Einträge unter changes beschreiben konkrete, tatsächlich erfolgte Änderungen und keine pauschalen Überarbeitungsbehauptungen

  • Metadaten zu Autoren, Urheberrecht und Lizenz geben die tatsächlichen Verhältnisse wieder und werden nicht erfunden

  • Soweit für die betreffende Datei zutreffend, lautet die Maintainer-Angabe maintainer:     GABRIEL Sebastian (interim)

  • Jede durch einen KI-Assistenten überarbeitete Arzneimittelmonographie erhält in der überarbeiteten Fassung status: sprint, unabhängig vom Status ihrer Ausgangsfassung (auch bei status: final)

  • Die genehmigte Ausgangsfassung einer Monographie bleibt unverändert erhalten; eine neue Bearbeitungsfassung wird davon unterscheidbar geführt

  • Bei Dokumenten außerhalb der Pharmakopeia bleibt der vorhandene Dokumentstatus grundsätzlich unverändert, sofern keine Statusänderung beschlossen wurde

Index-Einträge#

  • Index-Einträge, welche sich auf den gesamten Abschnitt beziehen, werden als Index-Direktive vor der Überschrift gesetzt.

  • Index-Einträge, deren Relevanz sich auf eine TExt-Stelle beschränkt, werden als Index-Rolle vor dem jeweiligen Satz gesetzt, z. B.:

    {index}` <Albtraum>`
Typische Merkmale sind das *wiederholte Erleben des Traumas* in sich aufdrängenden Erinnerungen (Nachhallerinnerungen, Flashbacks), Träumen oder *Albträumen*, die vor dem Hintergrund eines andauernden Gefühls von *Betäubtsein* und *emotionaler Stumpfheit* auftreten.


-   {index}` <Angioödem; ACE-Hemmer>`
    {index}` <ACE-Hemmer; Angioödem>`
    {index}` <Ödem; Angio->`
    Bei ACE-Hemmer-Therapie kann es zu einem angioneurotischen Ödem mit Ausbildung von Weichteilschwellungen kommen.
    Sollte es zu einer Atemwegsverlegung durch Zungen-, Glottis- bzw. Kehlkopfbeteiligung kommen, müssen unverzüglich Notfallmaßnahmen (Sicherung der Atmung,  Notarzt!) eingeleitet werden!

  • Hierarchische Indexeinträge verwenden ein Semikolon (Oberbegriff; Unterbegriff) statt einer Klammerkonstruktion

Weitere projektspezifische Direktiven und Referenzen#

Admonitions#

Synopsis-Boxen verwenden die Klasse synopsis. Die Direktiven tip, warning oder info ersetzen keine Synopsis-Box.

:::{admonition} Synopsis
:class: synopsis

-   Klinisch wesentliche Aussage
:::

Referenzen und Abkürzungen#

  • Für vorhandene eigenständige Kapitel und benannte Abschnitte werden passende MyST-Querverweise gesetzt.

  • Die Rollen {ref}, {term}, {numref} und {eq} werden entsprechend dem jeweiligen Referenzziel verwendet.

  • Begriff und Abkürzung können jeweils einen eigenen Querverweis besitzen, sofern die Ziele existieren.

  • Referenznamen, Labels, Indizes und vorhandene Ziele werden nicht ohne sachlichen Grund umbenannt.

{ref}`Elektrokardiogramm <EKG>` ({ref}`EKG <EKG>`)

Gestaltung und Inhalt#

  • Semantische Hervorhebungen werden im Quelltext erhalten; bei Field-List-Begriffen erfolgt keine zusätzliche Hervorhebung.

  • Fachliche Aussagen und die sprachliche Verwendung von Hervorhebungen sind in Inhalts- und Textgestaltung geregelt.

  • Die Gestaltung von Abbildungen einschließlich der Farbpalette ist in Design Guidelines geregelt.

  • Bei Fragen zur allgemeinen MyST-Syntax dient MyST-Markdown Kurzanleitung als Einführung, ohne diese Projektvorgaben zu ersetzen.