Annotationen (links) & Apparate (footnotes)

Die möglichen Annotationen und Anmerkungsapparate werden über Typen konfiguriert. Annotationen (links) zeichnen eine Textstelle mit einem Tag aus. Dabei kann es sich unter anderem um die Kennzeichnung kursiver Texte, die Kennzeichnung von Worttrennern oder verlorener Textteile, um Verweise auf Literatur oder andere Kategorien handeln. Jedes Tag kann weitere Attribute enthalten und auf Kategorien (properties) verweisen. Apparate (footnotes) in der Form von Fußnoten enthalten weiteren Text zu einer Textstelle.

Konfiguration

Annotationen und Apparate werden in der Datenbank über XML-Tags erfasst und zur Darstellung auf der Seite in HTML-Tags umgewandelt. Die Konfiguration enthält Angaben dazu, wie diese Annotationen dargestellt und wie die Buttons in der Werkzeugleiste gestaltet werden.

Schlüssel	Beschreibung
group	Optional. Name der Gruppe, zu der diese Annotation gehört, zum Beispiel "transcription". Damit werden mehrere Annotationen zusammengefasst und können gemeinsam angesprochen werden. Das ist vor allem bei der Konfiguration von XML-Feldern nützlich, um nicht alle möglichen Annotationen einzeln aufführen zu müssen. Stattdessen kann der Gruppenname angegeben werden.
shortcut	Shortcut zum Einfügen der Annotation. Beispiele: Alt+N Ctrl+Shift+A F9 Die Möglichkeiten sind durch den CKEditor vorgegeben.
toolbutton	Ein Objekt mit der Konfiguration des Toolbuttons. Beispiel für Verweis auf Literatur: `"toolbutton": { "icon": "literature", "group": "links" }` Die Konfiguration kann in einfachen Fällen abgekürzt werden: 1. Boolean-Wert (`false\|true`): Standardmäßig erhält jede Annotation einen eigenen Button in der Toolbar (`true`). Um keinen Button zu erzeugen, wird der Schlüssel auf `false` gesetzt. Das ist beispielsweise der Fall bei Sonderzeichen, die keinen eigenen Button bekommen, sondern im Sonderzeichen-Dropdown landen sollen (siehe unten). Entspricht dem Schlüssel `enable` in der Vollkonfiguration. 2. String: Beschriftung des Toolbuttons, zum Beispiel `[abc]` oder ein Unicode-Symbol. Entspricht dem Schlüssel `symbol` in der Vollkonfiguration.
tag_type	Wie wird das Tag bei der Ausgabe dargestellt? Soll ausschließlich ein Dropdown-Toolbutton erzeugt werden, wird der Schlüssel weggelassen. text: Ein alleinstehendes Tag. Die Werte der Schlüssel html_prefix, html_content und html_postfix werden zusammengefügt und ausgegeben, zum Beispiel ein festgelegtes Symbol für Worttrenner. Alternativ kann der Wert eines Attributs ausgelesen werden, zum Beispiel um URLs auszugeben, siehe unten die attributes-Konfiguration. format: Der Text wird formatiert, zum Beispiel kursiviert. bracket: Der Text wird geklammert. Vor dem Text wird dazu Der in html_prefix angegebene Wert ausgegeben, nach dem Text der Wert aus html_postfix. break: Es handelt sich um einen Zeilenumbruch, der in ein br-Tag umgewandelt werden soll.
attributes	Optional ein Objekt mit der Konfiguration von Attributen. Jeder Schlüssel ist ein Attributname, der Wert enthält wiederum die folgenden Schlüssel: caption: Eine Beschriftung des Attributs in Eingabefeldern, mit denen das Attribut bearbeitet wird. default (optional): In Eingabefeldern der Standardwert. render (optional): Attributwerte können als Klammern und alleinstehende Elemente ausgegeben werden. Mit der Angabe `text` wird für alleinstehende Elemente (tag_type text) der Attributwert statt html_content ausgegeben. Für Klammern kann der Attributwert über die Angabe `prefix` bzw. `postfix` in die öffnende bzw. schließende Klammer übertragen werden. Mit der Angabe `attribute` wird das Attribut als Attribut ausgegeben. Ohne Angabe wird das Attribut nicht gerendert. default (optional): Standardwert, wenn Attribute in Klammern und Elementen ausgegeben werden und das Attribut leer ist. repeat (optional): der Wert wird so oft ausgegeben, wie im Attribut angegeben. Das Attribut muss dazu eine Zahl enthalten. Ist das Attribut leer oder enthält die Zahl 0, dann wird der Wert in `default` ausgegeben. values (optional): Entweder ein regulärer Ausdruck oder eine Liste oder ein Objekt. Mit einem regulären Ausdruck werden die erlaubten Werte eingeschränkt. Beispielsweise wird mit `[0-9]+` auf Zahlen eingeschränkt. Eine Liste enthält Werten, die zur Auswahl bereitgestellt werden, zum Beispiel `["lost", "omitted", "ellipsis"]`. Sollen in der Auswahlliste andere Beschriftungen verwendet werden, kann ein Objekt angegeben werden, wobei die im Element gespeicherten Werte in den Schlüsseln und die Beschriftungen als Werte angegeben werden, zum Beispiel: `{"lost": "Verloren","ellipsis": "Auslassung"}`. Soll eine Checkbox ausgegeben werden, müssen im Objekt die Werte für eine aktivierte und deaktivierte Checkbox angegeben werden. input (optional): In der Standardeinstellung `text` wird eine Texteingabefeld ausgegeben. Mit der Angabe `select` wird eine Auswahlliste mit allen Werten aus values erzeugt. Mit `checkbox` wird eine Checkbox erzeugt. In values sollte dazu ein Objekt angegeben werden. Der erste Schlüssel des Objekts wird verwendet, wenn die Checkbox nicht aktiviert ist, der zweite Schlüssel wenn sie aktiviert ist. Die Beschriftung wird aus dem ersten Wert des Objekts entnommen. title (optional): Ein kurzer Hilfetext. Die Attribute `id`, `value`, `class` und Attribute mit einem `data-`Präfix sind reserviert und dürfen nicht verwendet werden.
fields	Konfiguration der Felder einer Annotation bzw. Fußnote mit den entsprechenden Einstellungen für das Rendering. Die Feldnamen werden als Schlüssel und die Einstellungen als Objekt angegeben. Mögliche Felder in Fußnoten: name: Konfiguration der Nummerierung. Der Unterschlüssel `format` muss auf "counter" gesetzt werden. Die Ausgabe der Nummer wird im Schlüssel `render` mit den Werten "prefix", "text" oder "postfix" angegeben. Die Art der Nummerierung wird im Unterschlüssel `counter` mit folgenden möglichen Werten angegeben: numeric: Es wird eine Zahl ausgegeben. alphabetic: Es wird ein lateinischer Buchstabe ausgegeben (Varianten: alphabetic-lower, alphabetic-upper) roman: Es wird eine römische Zahl ausgegeben (Varianten: roman-lower, roman-upper) greek: Es wird eine griechische Zahl ausgegeben (Varianten: greek-lower, greek-upper) segment und content: Konfiguration für den Anmerkungstext und einen Referenztext. Der Unterschlüssel `format` muss auf "xml" gesetzt werden. Im Unterschlüssel `types` wird wie bei Feldkonfigurationen für Items angegeben, welche Annotationen darin wiederum erlaubt sind. Mit dem Unterschlüssel `caption` kann eine Überschrift gesetzt werden. Mögliche Felder in links-Annotationen: to: Konfiguration von Verweisen. Der Unterschlüssel `format` muss auf "record" gesetzt werden. Soll eine Ausgabe in alleinstehenden Tags oder in Klammern erfolgen, wird dies im Schlüssel `render` mit den Werten "prefix", "text" oder "postfix" angegeben. Im `targets`-Schlüssel wird angegeben, worauf verwiesen werden kann: articles: Erlaubte Werte sind "intern" für interne Verweise und "extern" für Verweise auf andere Artikel. sections: Die erlaubten Abschnittstypen werden in einer Liste angegeben. items: Die erlaubten Inhaltstypen werden in einer Liste angegeben. properties: Die erlaubten Kategorientypen werden in einer Liste angegeben. footnotes: Die erlaubten Apparattypen werden in einer Liste angegeben.
html_tag	Die XML-Tags werden für die Anzeige auf der Webseite in HTML-konforme Tags konvertiert. Das Feld gibt an, welches HTML-Tag verwendet werden soll. In der Regel sollten alle XML-Tags in span-Tags konvertiert werden, eine Differenzierung der span-Tags kann über Klassen erfolgen. Jedes konvertierte Tag erhält die Klasse xml_tag. Zusätzlich wird jedes Tag mit einer Klasse nach dem Schema "xml_tag_<name>" versehen. Wenn das XML-Tag zum Beispiel "wtr" heißt, wird nach der Transformation die Klasse "xml_tag_wtr" vergeben. Format-Tags erhalten zusätzlich die Klasse xml_format. Bracket-Tags werden in drei Tags konvertiert. Die öffnende Klammer erhält die Klasse xml_bracket_open, die schließende Klammer die Klasse xml_bracket_close und der enthaltende Text die Klasse xml_bracket_content.
html_prefix	Bei Bracket-Tags der für die öffnende Klammer verwendete Wert. Bei Text-Tags wird dieser Wert dem in html_content festgelegten Wert vorangestellt. Bei Format-Tags wird dieser Wert als Text zu Beginn des markierten Bereichs eingefügt.
html_content	Bei Text-Tags wird dieser Werte bei der Konvertierung zu HTML innerhalb des Tags ausgegeben. So können zum Beispiel Worttrenner durch einen Mittelpunkt dargestellt werden.
html_postfix	Bei Bracket-Tags der für die schließende Klammer verwendete Wert. Bei Text-Tags wird dieser Wert an den in html_content festgelegten Wert angehängt. Bei Format-Tags wird dieser Wert als Text an das Ende des markierten Bereichs eingefügt.
css_style	CSS-Angaben, die in die Webseite eingebettet werden, um das Tag zu gestalten. Die CSS-Angaben können sich auf die Klassen der konvertierten Tags beziehen (siehe die Konfiguration von html_tag). Beispiel, um einen Umbruch nach einem Tag zu erzeugen: `.xml_tag_vz:after {content: \"\\A\" ; white-space: pre;}`

Toolbuttons

Für jede Annotation wird ein Button erzeugt. Die Gestaltung wird im toolbutton-Key festgelegt. Prinzipiell gibt es drei Möglichkeiten, Icons und Beschriftungen der Buttons festzulegen:

Eine eigene SVG-Vektorgrafik, die im icon-Schlüssel festgelegt wird.
Eine kurze Beschriftung oder ein Unicode-Symbol aus der Standardschriftart, das im symbol-Schlüssel festgelegt wird.
Ein Unicode-Symbol aus der Schriftart Font Awesome, das im symbol-Schlüssel festgelegt wird. Zusätzlich wird im font-Schlüssel die Schriftart "awesome" festgelegt.

Schlüssel	Beschreibung
icon	Der Wert verweist auf eine vordefinierte SVG-Grafik (momentan ist noch kein Upload benutzerdefinierter Grafiken möglich). Wird der Schlüssel weggelassen, wird standardmäßig eine SVG-Grafik mit dem Namen des IRI-Fragments eingebunden (z. B. `"letterspaced"` für die Gesperrt-Annotation).
symbol	Ideal, wenn man schnell ein Icon erzeugen will, ohne erst eine SVG-Datei erstellen zu müssen. Es kann eine Beschriftung wie `[abc]` oder ein Unicode-Symbol wie ✅ für ein Haken-Symbol angegeben werden. Nach dem Speichern wird das Zeichen automatisch in sein Unicode-Kürzel (im Beispiel `"\u2705"`) übersetzt und beim Bearbeiten der Konfiguration auch immer so angezeigt.
font	Es können Unicode-Symbole von Font Awesome verwenden, werden. Dazu sucht man auf der Font-Awesome-Seite aus den Free Icons (wichtig!) ein Symbol heraus, z. B. das Font Awesome-eigene Buch-Symbol. Von der Seite entweder die Glyphe oder das Unicode-Kürzel kopieren und in den `symbol`-Schlüssel einfügen (wenn der Codepoint kopiert wird, dann bitte ein `\u` davorsetzen). Zusätzlich muss der `font`-Schlüssel auf "awesome" gesetzt werden.
style	Mit CSS-Angaben können Schriftfarbe und Schriftschnitt (fett, kursiv) verändert werden, zum Beispiel: `color:#ff0000;font-weight:bold;` für einen roten gefetteten Button.
group	Um mehrere Toolbuttons zu einem Dropdown zu kombinieren, kann hier eine Kategorie angegeben werden. Alle Toolbuttons innerhalb einer Kategorie werden zu einem Dropdown kombiniert. Beispiel: Wird für Verweise-Annotationen (beispielsweise Verweis auf Hausmarke, Verweis auf Literatur) immer der Wert `reference` angegeben, entsteht ein Dropdown mit den entsprechenden Toolbuttons. Der Wert `default` sorgt dagegen dafür, dass der Toolbutton einzeln bleibt und nicht einer Gruppe zugeordnet wird.
dropdown	Um Dropdown-Buttons gestalten zu können, wird für den Button eine eigene Annotation angelegt. Der `group`-Schlüssel wird auf die Gruppe der unterzuordnenden Buttons und der `dropdown`-Schlüssel wird auf `true` gesetzt. Mit weiteren Schlüsseln wie `icon`, `symbol` oder `style` kann der Button gestaltet werden. Beispiel: `"toolbutton": { "group": "links", "icon": "reference", "dropdown": true }`

Umbrüche

Eine besondere Behandlung erfahren Umbrüche. Umbrüche werden im Editor mit Shift+Enter erzeugt. Sie werden in XML als leere nl-Tags gespeichert und im HTML als alleinstehende br-Tags ausgegeben. In den Types muss dafür ein nl-Link angelegt und wie folgt konfiguriert sein:

{
   "tag_type": "break",
   "toolbutton": false
}

Sollen Umbrüche in einem Feld möglich sein, dann muss das nl-Tag in der Feldkonfiguration im types-Schlüssel aufgeführt werden.

Sonderzeichen

Der Editor enthält ein Standardset an Sonderzeichen (Satzzeichen, Währungssymbole, Einheiten etc.), die über den Special Characters-Button in der Toolbar eingefügt werden. Die Sonderzeichen sind kategorisiert und können beispielsweise nach Mathematical oder Text gefiltert werden.

Darüber hinaus können in den Types auch zusätzliche Sonderzeichen konfiguriert werden. Dazu wird eine Konfiguration vom Typ "link" mit folgenden Feldern angelegt:

Schlüssel	Beschreibung
Name	Englische Bezeichnung des Sonderzeichens, das sich im Idealfall an der Unicode-Norm richtet. Das Zeichen "■" heißt beispielsweise in der Norm "Black square". Im Name Feld sollte eine davon abgeleitete Bezeichnung in Kleinschreibung und ohne Leer- oder Sonderzeichen abgeleitet werden. Im Beispiel würde dafür "black_square" verwendet werden.
Scope	Besitzt den gleichen Scope wie alle anderen Links, da Sonderzeichen auch in der Toolbar des Editors eingeblendet werden: "links".
Kategorie	Dient der leichteren Auffindbarkeit in der Typkonfiguration und kann frei vergeben werden, zum Beispiel "Characters".
Caption	Bezeichnung des Sonderzeichens, die in der Toolbar angezeigt wird, zum Beispiel "Schwarzes Quadrat" (in deutscher Sprache).
IRI-Fragment	Wird aus dem Namen mit dem Präfix "char-" gebildet, also zum Beispiel "char-black_square".
Config	Enthält die weite Konfiguration des Sonderzeichens, siehe die nächste Tabelle.

Während die vorangegangen Felder die Bezeichnung festlegen, wird im Config-Feld das Verhalten im XML-Editor konfiguriert. Wichtig sind die folgenden Schlüssel:

Schlüssel	Beschreibung
toolbutton	Immer "false".
tag_type	Hat bei Sonderzeichen immer den Wert "character". Legt fest, dass das Zeichen als Text eingefügt wird (siehe auch die Dokumentation von tag_type im Abschnitt Annotationen & Apparate).
html_content	Das Zeichen, das eingefügt werden soll. Achtung: Nach dem Speichern wird das Zeichen automatisch in sein Unicode-Kürzel übersetzt und beim Bearbeiten auch immer so angezeigt ("■" wird beispielsweise zu "\u25A0"). Das liegt allerdings nur an der Anzeige in der Types-Konfiguration, im Editor wird das korrekte Zeichen eingefügt.
shortcut	Die Tastenkombination, mit der das Sonderzeichen eingefügt werden kann, ohne es über die Toolbar auszuwählen (z. B. "Ctrl+Q"). Dabei sollte immer das englische Kürzel verwendet werden (z. B. "Ctrl" statt "Strg") und es sollten keine Leerzeichen im Shortcut enthalten sein.
group	Mehrere Sonderzeichen können zu einer Gruppe zusammengefasst werden, indem diese Sonderzeichen einer gemeinsamen Gruppe zugeordnet werden, zum Beispiel "Edition". Ohne Angabe einer Gruppe werden die Sonderzeichen im Bereich "Custom" angezeigt. TODO: Konflikt mit der Gruppenangabe anderer Annotationen auflösen.