Funktionen

Zurück zum Anker-Beispiel

Dieses Untermenü stellt Nachbearbeitungen in der Export-Datei bereit, die über das Ersetzen oder Entfernen der Editor-Variablen und Yaml-Variablen hinaus gehen.

Allgemeine Regeln

$$$ Funktionsname [Zuordnung] [:] [Wertzuweisung] $$$

Schreibweise

• 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.

Präprozessor

Regeln

• Der Yaml-Header importierter Markdown-Dateien wird ignoriert.
• Markdown-Funktionen sollten vorzugsweise freistehend in einem Absatz verwendet werden.
• Eingefügte Dateien werden grundsätzlich in einen Abschnitt (<div>) gesetzt, weshalb eine Einfügung innerhalb eines Absatzes dessen Struktur zerstört.
• Es findet keine Prüfung statt, ob die eingefügten Dateien tatsächlich Markdown enthalten.
• Es findet keinerlei Interpretation beim Einfügen des Dateiinhaltes statt.
• Das eingefügte Markdown wird bearbeitet, als stünde es in der Quelldatei, von der aus das eingefügte Markdown referenziert wurde.
• Präprozessor-Module können ausschließlich in der Markdown-Quelle verwendet werden.

Bitte beachten:

• Yaml-Variablen werden mit den Werten der aktuellen Quelldatei ersetzt.
• Relative Referenzen gelten relativ zur aktuellen Quelldatei.

MD-Datei: mdfile

Fügt eine referenzierte Markdown-Datei aus dem Projekt-Markdown-Verzeichnis ein.

• Dem übergebenen Dateipfad wird der Markdown-Basispfad des Projekts vorangestellt.
• Die eingefügte Datei wird mit einem Abschnitt <div class="…">…</div> umschlossen.
• Wird eine Klasse übergeben, wird diese verwendet, andernfalls erhält der Abschnitt eine Klasse mit der Kennung der Funktion.
• Innerhalb der aktuellen Markdown-Datei muss die Kennung eindeutig sein.

MD-Verzeichnis: mddir

Fügt alle Dateien aus dem gewählten Verzeichnis in die aktuelle Datei ein.

• Dem übergebenen Dateipfad wird der Markdown-Basispfad des Projekts vorangestellt.
• Sowohl die gesamte Einfügung, als auch jede einzelne Datei wird mit einem Abschnitt <div class="…">…</div> umschlossen.
• Werden keine Klassen übergeben, wird für alle Abschnitte die Kennung als Klasse vergeben.
• Wird eine Klasse übergeben (k1), gilt diese für die Datei-Abschnitte.
• Werden zwei Klassen übergeben, gilt die erste (k1) für den umschließenden, die zweite (k2) für die Datei-Abschnitte.

MD-Pfad: mdtoc

Fügt eine verlinkte Liste aller Dateien aus dem gewählten Verzeichnis in die Aktuelle Datei ein.

Für eine komfortable Verwendung der Funktion werden bedarfsweise doch Yaml-Variablen aus den referenzierten Dateien verwendet. Diese können über die Zuordnung individuell gewählt werden.

• Verfügt die Funktion über keine weiteren Angaben außer der Kennung und dem Pfad, wird der Yaml-Eintrag title als Text für den Hyperlink unterstellt.
• Statt dessen kann ein beliebiger Yaml-Eintrag verwendet werden. Dieser wird als erster Eintrag in der Zuordnungsliste erwartet. Fehlt diese Yaml-Definition wird ein Ersatztext verwendet.
• Ist ein zweiter Yaml-Eintrag zugeordnet, wird dieser zum Sortieren verwendet. Fehlt er, wird auf den Titel zugegriffen.
• Ist ein dritter Yaml-Eintrag zugeorndet, wird dessen Inhalt unter den Link als Beschreibungstext eingefügt.
• Wird im Yaml-Header einer zu verlinkenden Datei der Projekt-Parameter delete gefunden, wird diese Datei aus der Liste ausgeschlossen: Der Parameter verhindert den Export auf den Server, also wird diese Datei (wahrscheinlich) dort fehlen und wäre deshalb ein „toter“ Link.

Die Formatierung

Ohne Beschreibungstext wird jeder Link als Absatz in die Markdown-Datei eingefügt:

[Titel]⟨Link zur Datei⟩

Mit Beschreibungstext wird ein Definitionslisten-Eintrag erzeugt:

[Titel]⟨Link zur Datei⟩
: Beschreibung

Die Formatierung kann mit umschließenden Klassen und nachgeordneten Definitionen für die Definitionsliste darin frei gestaltet werden.

<div class="small">
$$$ mdtoc einfuegen title rang description : /editor/einfuegen/  $$$
</div>

Postprozessor

Regeln

• 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.
• Postprozessor-Funktionen können in allen Teilen, also neben der HTML-Quelle auch in der Layout-Datei, verwendet werden.

Wahl: choice

Der Wahlschalter kann variablen Text abhängigg Yaml-Variablen in einen Absatz oder als Überschrift einfügen.

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). Die Funktion wird durch den gefundenen Text ersetzt.

Hat choice ein + an einer beliebigen Stelle in der Zuordnung, wird hinter dem Text ein gleichnamiger Anker erzeugt.

Beginnt die Zuordnung mit einer Zahl, wird ein „Überschrift-Rumpf“ erzeugt. Deshalb muss die Funktion für einen validen Code mit <…> umschlossen sein. Ein womöglich enthaltenes „+“ wird in diesem Fall ignoriert: Die Überschrift bekommt einen ID, damit sie z.B. aus einem generierten Inhaltsverzeichns angesprungen werden kann.

<$­$$ choice 4heading : Seitentitel | %­%%Ersatztitel%­%% $­$$>

<h4 id="auswahl-der-ueberschrift">Auswahl der Überschrift</h4>

Die Wahlfunktion kann darüber hinaus mit der „Löschfunktion“ (vorangestelltes „!“) von Yaml-Variablen kombiniert werden. Die Yaml-Variablen werden vor den Funktionen abgearbeitet.

„choice“ wird vor „toc“ abgearbeitet, weshalb die Position der Funktionen innerhalb der Seite keine Rolle spielt.

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:

Es gelten den Regeln für die ID-Erzeugung. Die Position kann innerhalb der Datei und von anderen Dateien mit einem Hyperlink angesprungen werden:

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.

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.

Anwendungsbeispiel: „Glossar-Links erzeugen“

Platzhalter: insert

Markiert die Einfügeposition für den Inhalt eines Platzhalters. Der Platzhalter kann an beliebiger Stelle im  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.

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.

Ausgabe

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.

Ausgabe

Variante 3 ✔

Funktionsmarken alleinstehend jeweils in einem Absatz: Die dazwischenliegenden Zeilen werden vollständig übernommen, die Funktionsmarken hinterlasssen keine leeren Absätze

„nw“ ist ein Modul, „info“ ein CSS-Stil dieses Projekts.

Ausgabe

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.

Ausgabe

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“.

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 .toctitle noch eine Formatierung für die Liste .toc ul bzw. ggf. individuell für jede Stufe erfolgen.

Datei: file

​

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.

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)“.

Verzeichnis: dir

„dir“ ermöglicht das Einbetten aller Dateien eines Verzeichnisses in die Ausgabe.

• 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.