Funktionen ▶
Auf dieser Seite
Dieses Untermenü stellt Nachbearbeitungen in der Export-Datei bereit, die über das Ersetzen oder Entfernen der Editor-Variablen und Yaml-Variablen hinaus gehen.
Funktionen werden auf die erzeugte Ausgabe angewandt, nachdem Module und Yaml-(Editor-)Variablen ersetzt wurden. Innerhalb einer Funktion kann deshalb eine Variable als Parameter verwendet werden.
Anwendungsregeln
- Allgemeine Schreibweise
-
$$$ Funktionsname [Zuordnung] [:] [Wertzuweisung] $$$
- Falsch geschriebene, unbekannte oder ungenutzt gebliebene Funktionen werden vollständig (
$$$…$$$) entfernt. - Funktionsname = FUNKTIONSNAME = Funktionsname, Zuordnung = ZUORDNUNG = zuordnung
- Funktionsname und Zuordung müssen aus Buchstaben, Zahlen und ausgewählten Zeichen ≠ „:“ oder Leerzeichen bestehen.
- Der Funktionsname ist unveränderlich von
OSE vorgegeben - Die Zuordnung kann – abhängig vom Funktion – entfallen oder eine eingeschränkte Schreibweise haben (s. Inhaltsverzeichnis).
- Die Wertzuweisung darf beliebig lang sein und beliebige Zeichen enthalten. Hier können einige Zeichen eine besondere Eigenschaft für die Funktion haben (s. Wahl)
- Funktionsname, Zuordnung und Wertzuweisung werden von den Funktionsbegrenzungen oder mindestens einem Leerzeichen oder dem Doppelpunkt voneinander getrennt. Zur besseren Leesbarkeit dürfen weitere Leerzeichen verwendet werden.
- Ineinander verschachtelte Funktionen verstümmeln die Ausgabe-Datei.
Einige Funktionen können über mehrere Absätze hinweg eingesetzt werden. Es hängt vom Einzelfall ab, ob das erforderlich oder sinnvoll ist.
Innerhalb der Funktionsbegrenzungen $$$ werden Funktionen vom Markdown-Parster als Markdown angesehen, Auszeichnungen entsprechend ersetzt. Das ermöglicht Strukturen, die mit einfachem Markdown unmöglich sind oder die Integration von HTML-Code erfordern würden.
ern würden.
Die Behandlung „als Markdown“ erzeugt aus einer allein stehenden Funktion ohne Inhalt einen leerer Absatz.
Funktionen, die konzeptionell allein in einem Absatz stehen sollten, entfernen entstehende Leerabsätze.
Kombinationen
Variablen, Module und Funktionen können miteinander kombiniert werden. Maßgeblich für ein erfolgreiches Resultat ist die Reihenfolge der Verarbeitung:
- Ersetzung der Editor-Variablen
- Ersetzung der Module
- Verbinden mit dem Layout
- Ersetzung der Yaml-Variablen
- Ersetzung der Funktionen
Ob valider Code ausgegeben wird, hängt von der Sorgfalt bei der Verwendung der Module, Variablen und Funktionen ab.
Anker: id
Ermöglicht die Erzeugung beliebiger Sprungmarken im Text. Wahlweise wird ein markierter Block oder ein anzugebender Text übergeben. Dieser Text wird als sowohl als unsichtbarer Anker als auch im Text ausgegeben:
»$$$ id: Dieser Anker $$$ wird zu«
»<a id="dieser-anker"></a>Dieser Anker wird zu«
Es gelten den Regeln für die ID-Erzeugung. Die Position kann innerhalb der Datei und von anderen Dateien mit einem Hyperlink angesprungen werden:
- Beispiel
-
[Zum ersten Absatz]⟨#$$$ mkid : Dieses Untermenü $$$ ""⟩→ Zum ersten Absatz
Ein Anker kann nahezu überall plaziert und umschließend formatiert werden.
- Hinweis
-
Browser springen mit der aktiven Marke zu Hyperlinks auf der gleichen Seite. Das kann ein Rollen auslösen, mit dem die Marke am Seitenanfang oder -ende sichtbar wird. Befindet sich die Marke bereits im sichtbaren Bereich, wird der Sprung nur wahrnehmbar, wenn eine entsprechend Stilvorlage die aktive Marke hervorhebt. Bei Ankern ist diese Marke bestensfalls einen Strich breit.
Es findet keine Dubletten-Prüfung statt.
- Querverweise
-
- Mit Modulen, genauer mit markierten Parametern von Modulen, können ebenfalls Anker erzeugt werden.
- Mit der Wahl-Funktion wird automatisch der zur Wahl passende Anker erzeugt.
ID erzeugen: mkid
Diese Funktion ist primär für Module gedacht, in denen aus übergebenen Parametern ein ID erzeugt werden soll. Das Ergebnis entspricht dem Menübefehl.
- Beispiel
-
$$$ mkid : Hier steht Text $$$→ hier-steht-text
Anwendungsbeispiel: „Glossar-Links erzeugen“
Platzhalter: insert
Markiert die Einfügeposition für den Inhalt eines Platzhalters. Der Platzhalter kann an beliebiger Stelle im [Editor]ose]-Quelltext stehen. Abhängig von der Position und dem deshalb erzeugten Export-Code kann das Einfluss auf die Code-Struktur haben.
Ist beim Aufruf des Befehls ein Text markiert, wird er als Bezeichner des Platzhalters übernomen, ohne Prüfung, ob die Markierung die dafür geltenden Regeln erfüllt. Andernfalls wird der Cursor an der Position plaziert, an der eine Zuordnung vorgenommen werden muss.
Ein Platzhalter ohne korrespondierender Definition wird aus dem Ergebnis entfernt.
Platzhalter werden ohne Rücksicht auf Strukturen, d.h. innerhalb von PHP-Code, als Code formatierte Abschnitte, … — überall — ersetzt. Es findet keine Kontrolle statt, ob das darstellbaren Code ergibt.
Platzhalter: define
Einem mit »insert name« erzeugten Platzhalter-Namen wird mit »define name: …« ein Inhalt zugewiesen.
Der Umfang ist nahezu beliebig. Von einem einzelnen Wort bis zu unzähligen Absätzen inklusive Modulen, etc. ist möglich. Die Art der Einfügung lässt sich durch die Art der Definition beeinflussen:
- Folgt der Definition direkt im Absatz ein Inhalt (
$$$ define name : Inhalt… $$$), wird dieser ohne umschließende Strukturmerkmale (Absatz, Abschnitt) übernommen. - Steht
$$$ define name :in einer einzelnen Zeile, gefolgt von Absätzen, die mit einer allein stehenden Schlussmarke$$$in einem Absatz beendet wird, wird der Abschnit als Block mit<DIV>…</DIV>umschlossen.
define Szenarien
Nachfolgend einige Beispiele, welchen Einfluss die Position des $$$insert … $$$ und der Struktur des damit verwiesenen $$$ define … : auf die Ausgabe hat. Der mit dem jeweiligen Beispiel erzeugte Code kann mit der Quelltext-Funktion des Browsers untersucht werden.
Variante 1 ✔
Funktionsmarken im Text eines Absatzes : Der umschlossene Inhalt wird rückstandslos entnommen und ohne umschließenden Absatz-Tag in einem Platzhalter eingefügt.
$$$ insert variante1 $$$
Aus dem darunter liegenden Absatz wird Text entnommen $$$define variante1: Das ist der Inhalt von Variante 1. $$$ und darüber eingesetzt.
Ausgabe
Aus dem darunter liegenden Absatz wird Text entnommen und darüber eingesetzt.
Variante 2 ✔
Funktionsmarken umschließen den Inhalt eines Absatzes : Der umschlossene Inhalt wird ohne Absatz-Tags in einem Platzhalter eingefügt, der dann leere Absatz wird entfernt.
- $$$insert variante2 $$$
$$$ define variante2:Aus diesem Absatz wird Variante 2 entnommen.$$$
Ausgabe
Variante 3 ✔
Funktionsmarken alleinstehend jeweils in einem Absatz: Die dazwischenliegenden Zeilen werden vollständig übernommen, die Funktionsmarken hinterlasssen keine leeren Absätze
Das ist die favorisierte Variante, die der eingefügte Block vorschlägt.
$$$insert Variante3 $$$
$$$define variante3:
::: info
Dieser Abschnitt wird in der verwendeten Form hervorragend funktionieren und in Variante 3 eingefügt.
Bei der Verarbeitung wird dieser Bereich zusätzlich mit einem HTML-Block [nw "`<div>Variante 3</div>`"] als strukturierendes Element umschlossen. Innerhalb dieses Bereichs können daher weitere Struktur-Elemente, wie z.B. Zitate, weitere Blöcke, Aufzählungen, …, verwendet werden.
:::
$$$
„nw“ ist ein Modul, „info“ ein CSS-Stil dieses Projekts.
Ausgabe
Dieser Abschnitt wird in der verwendeten Form hervorragend funktionieren und in Variante 3 eingefügt.
Bei der Verarbeitung wird dieser Bereich zusätzlich mit einem HTML-Block <div>Variante 3</div> als strukturierendes Element umschlossen. Innerhalb dieses Bereichs können daher weitere Struktur-Elemente, wie z.B. Zitate, weitere Blöcke, Aufzählungen, …, verwendet werden.
Damit dieser Ansatz wie gezeigt funktioniert, dürfen hinter den Einfügemarken bzw. dem Doppelpunkt der define-Funktion keine Leerzeichen stehen.
Variante 4 ✗
Funktionsmarken beginnen/enden in einem Absatz mit Inhalt, überspannen mehrere Zeilen: Das wird verstümmelten Code erzeugen, es sei denn, im Inhalt ist am Anfang/Ende ein HTML-Absatzbegrenzer von Hand angegeben und der Platzhalter kann damit etwas anfangen.
- $$$insert Variante4 $$$
Aus diesen Absätzen wird $$$ define variante3: Das wird kein gutes Ende nehmen.
Denn es entsteht kein valider HTML-Code. Neben dem Abschnitt, in dem der Platzhalter steht, beschädigt es womöglich die „Teilabsätze“. Hier fügen sie sich „zu einem Absatz“ zusammen.$$$ Variante 3 entnommen.
Ausgabe
Denn es entsteht kein valider HTML-Code. Neben dem Abschnitt, in dem der Platzhalter steht, beschädigt es womöglich die „Teilabsätze“. Hier fügen sie sich „zu einem Absatz“ zusammen.
Aus diesen Absätzen wird Variante 4 entnommen.
In diesem Fall ist der Fehler moderat und wird von den meisten Browsern kompensiert: Es fehlt der Absatzanfang (<p>) des ersten, und das Absatzende des letzten Absatzes (</p>).
Inhalt: toc
Alternativ zumm manuellen Inhaltsverzeichnis durch eine Querverweis-Liste kann ein Überschriften-Verzeichnis der Seite mit der Funktions toc erzeugt werden.
Alle Überschriften im erzeugten Dokument, inklusive der womöglich im Layout erzeugten, können gegenüber der Querverweise in der Arbeitsdatei einfließen. Dieses Verzeichnis entspricht immer dem Status der Datei beim Export, es „pflegt sich selbst“.
$$$ toc 1-6 : Inhaltsverzeichnis $$$
Regeln
- Das Verzeichnis wird mit
<DIV class="toc">umschlossen. - Ein Inhaltsverzeichnis muss der einzige Eintrag in einem Absatz sein.
- Mit der Zuordnung kann der berücksichtigte Hierarchie-Bereich festgelegt werden.
- Ohne Zuordnung wird „1-6“ unterstellt
- Statt „-“ kann ein beliebiger Buchstabe verwendet werden, mit dem ggf. mehrere Verzeichnisse auf einer Seite unterschieden werden können.
- Als Wert kann optional eine Überschrift übergeben werden.
- Die Überschrift wird mit
<p class="toctitle">umschlossen. Jeder Verzeichniseintrag erhält eine ID, der „toc-“ vorangestellt ist.
Bei mehreren Verzeichnissen mit gleichen Verweisen kommen diese IDs mehrfach vor!
„Für schick“ muss neben der umschließenden Klasse
.toc, der Überschrift.toctitlenoch eine Formatierung für die Liste.toc ulbzw. ggf. individuell für jede Stufe erfolgen.
$$$ TOC 3A4 : Beispiel 1 $$$
Beispiel 2
$$$ TOC 2B2 : Beispiel 2 $$$
Beispiel 3
$$$ TOC 1C1 : Beispiel 3 $$$
Die Buchstaben A,B,C adressieren das jeweilige Inhaltsverzeichnis.
Wahl: choice
Mit der „Schalterfunktion“ von Variablen mit vorangestelltem ! der Yaml-Variablen lassen sich Absätze steuern. Damit ist „entweder - oder“ innerhalb eines Absatzes unmöglich.
Das bietet die Funktion choice:
$$$ choice [+][name] :[variante 1 | variante 2 | …] $$$
Es können beliebig viele Werte, getrennt durch | (ALT < - Taste) angegeben werden.
Ausgegeben wird der erste von rechts gefundene Wert, der länger als 0 Zeichen ist (umschließende Leerzeichen werden entfernt). Nützlich ist das beispielsweise für Überschriften im Layout, die normalerweise mit dem title erzeugt werden, doch wahlweise mit einem anderen Text gefüllt werden oder leer bleiben sollen.
Hat choice ein + in der Zuordnung, wird ein Anker erzeugt.
- Zeile in der Layout-Datei
-
<H1>$$$ choice layout+header : %%%!kopfzeile%%%$$$ | %%%title%%% | %%%Ersatztitel%%% $$$</H1> $$$
- Besonderheit dieser Lösung:
-
- In den Meta-Daten kann der
titleverwendet werden, für die erste Überschrift optional derersatztitel. - Es wird eine formatierte Überschrift, die von (einem nachfolgenden) TOC erkannt wird. - Mit dem Deaktivieren der „Löschvariable“
!kopfzeilekann die Funktion aus dem Layout entfernt werden, wenn vor dem Standard-Titel beispielsweise ein Bild am Seitenanfang stehen soll.
- In den Meta-Daten kann der
Das ermöglicht dynamische Inhalte innerhalb von Absätzen ohne Script-Einsatz.
Datei: file
$$$ file platzhalter : Dateipfad $$$
Im Ergebnis entspricht diese Funktion einem „include“ (PHP, HTML): Eine Datei aus dem Projektverzeichnis wird wie sie ist in die Ausgabedatei eingefügt. Der »Platzhalter« dient der zweifelsfreien Identifikation der Datei bei einem Fehler (hier provoziert):
Ladefehler: $$$ file platzhalter $$$
Der Datei-Pfad wird aus der Fehlermeldung entfernt. Für die Fehlersuche ist die Zuordnung ausreichend, der Pfad zu einer (fehlenden) Datei sollte aus mehreren Gründen kein Bestandteil einer Webseite sein.
Der wesentliche Unterschied zum „include“: Die geladene Datei ist fester Bestandteil des erzeugten Dokuments, während bei einem include die Enfügung jeweils im Augenblick des Seitenaufrufs erfolgt, also immer die aktuelle Version der eingefügten Datei verwendet wird.
Diese Funktion ist ein Behelf für Bedingungen, in denen „include“ keine Option ist (z.B. lokale Anwendung ohne aktive Umgebung, Webseiten mit maximalen Sicherheitseinschränkungen). In diesen Fällen müssen bei Änderungen der eingebetteten Datei(en) die davon betroffenen Seiten neu generiert werden (s. Projekt neu generieren).
Grundsätzlich kann eine beliebige, lokale Datei mit dieser Funktion in die Ausgabe integriert werden. Für den Verweis mit korrektem relativen Pfad gibt es den Datei-Befehl „Dateiverweis (lokal)“.
Eingefügte Dateien müssen validen Code enthalten, der sich strukturell korrekt in die erzeugte Ausgabe einfügt.
Es findet keine Kontrolle statt, ob die ausgewählte Datei eine funktionsfähige Export-Datei erzeugt.
Verzeichnis: dir
„dir“ ermöglicht das Einbetten aller Dateien eines Verzeichnisses in die Ausgabe.
Es findet keine Prüfung statt, ob die vorgefundenen Dateien dafür geeignet sind und das Ergebnis eine darstellbare Datei erzeugt.
Sinnvoll verwendbar ist dieser Befehl nur für Verzeichnisse, in denen HTML-Fragmente oder PHP-Skripte (soweit auf dem Server unterstützt) vorliegen.
- Das Einlesen erfolgt in alphabetischer Reihenfolge der Dateien im Verzeichnis.
- Jede Datei wird mit einer Blockmarke
<div>…</div>umschlossen. - Die Funktion sollte alleinstehend in einer Zeile positioniert sein.
Wird ein Projekt vollständig neu erzeugt, müssen Seiten mit dieser Funktion explizit kontrolliert werden:
Das Verzeichnis, aus dem die Dateien eingelesen werden sollen, ist zum Zeitpunkt der Erstellung womöglich noch leer!
Ein Anwendungsbeispiel ist das hier in der Hilfe damit erzeugt Glossar.