# Datenformate für Memoranden Eine technische Dokumentation oder ein **Memorandum** ist im wissenschaftlichen Umfeld oft erforderlich, **um Ergebnisse zu dokumentieren**. Dabei handelt es sich jedoch nicht um einen streng wissenschaftlichen Aufsatz, sondern um ein internes Dokument, welches Entscheidnungen dokumentiert. Zur Übersichtlichkeit sollten Textauszeichnungen (fett, kursiv und unterstrichen) vorhanden sein und das Dokument selbst eine Struktur (Überschriften und Abschnitte) aufweisen. Für die Darstellung von Ergebnissen eignen sich zudem oft Listen und Tabellen. Ideen und Herleitungen drücken sich durch Literaturangaben und Formeln aus. Da das Dokumentieren im wissenschaftlichen Bereich (etwa einer Forschungs- & Entwicklungsabteilung) einen **Langzeitcharakter** aufweist, sollte auch dessen Daten- und Dateiformat für lange Zeit lesbar sein. Im Idealfall sind die **Daten unabhängig von Programmen** und besonders einfach für den Menschen bearbeitbar. Dies hat wiederum zurfolge, dass Textauszeichnungen möglichst simpel aufgebaut sein sollten, um sie schnell lesen und tippen zu können. Für diesen Zweck suchen wir ein geeignetes Daten- und Dateiformat sowie ein Werkzeug zur Bearbeitung. In den folgenden Abschnitten werden zwei gegensätzliche, jedoch sehr oft verwendete Werkzeuge analysiert und miteinander verglichen. Aufgrund der Einschränkung beider Systeme, wird ein neuer Ansatz erarbeitet, welcher eine Schnittmenge beider Datenformate darstellt. Folgend sind die Anforderungen nochmals zusammengefasst: * Textauszeichnungen (fett, kursiv, Listen, Tabellen, Quelltext). * Multimedial (Hyperlinks, Bilder, Videos, Audio, Interaktion). * Wissenschaftlich (Formeln, Literaturangaben, Verweise). * Intuitives Markup (wenig Tipparbeit, simples Datenformat). * Schreiben ohne Unterbrechungen durch Kompiliervorgänge. * Beliebige (nachträgliche) Gestaltungsmöglichkeit (etwa durch CSS). * Veröffentlichungsfähig (druckbar und Upload ins Web). ## Das Lamport TeX System Das bekannteste Textsatz-Programm aus dem Bereich von Wissenschaft und Forschung dürfte [LaTeX](https://latex-project.org) sein. Es wurde in den 80'er Jahren von __Leslie Lamport__ entwickelt und basiert auf dem von __Donald Knuth__ programmierten TeX System aus dem Jahr 1977. Mittlerweile ist es zu einem **quasi Standard** geworden, sobald es um wissenschaftliche Abhandlungen mit Formeln und Bibliographie geht. Dieses System hat einige markante Vor-, aber auch Nachteile. Sie werden in folgender Liste angerissen: * Riesige Distribution mit mehreren GB. * Ein umständliches Markup (Listen, Tabellen, Formeln). * Gute Verwaltung der Bibliographie. * Extrem robustes Datenformat, dadurch aber auch kaum neue Funktionen. * Inhaltsverzeichnis wird automatisch erzeugt. * Schlecht konfigurierbar im Sinne von Farbe, Form, Schrift und Abständen. * Ein veralteter Kompilierungsvorgang, der das Schreiben unterbricht. * Keine interaktiven Medien (etwa Videos oder Beispiele mit Schaltern). Besonders das **umständliche Markup** führt bei Formeln und Tabellen schnell zu unleserlichen Passagen und ein Dokument muss immer wieder kompiliert werden, um Eingaben zu prüfen. Wegen dem Kompilierungsvorgang muss die eigentliche **Schreibarbeit immer wieder unterbrochen** werden. Für ein technisches Memorandum ist diese Arbeitsweise wenig geeignet, da zuerst ein LaTeX-konformes Dokument (mit Präabel) erstellt werden muss. Dieser Vorgang und das Lernen der Markup-Sprache kostet Anfänger erhebliche Einarbeitungszeit. ## Markdown Markdown ist eine vereinfachte Auszeichnungssprache, die von __John Gruber__ entworfen und im Dezember 2004 spezifiziert wurde. Ein Ziel von [Markdown](https://daringfireball.net/projects/markdown/) ist, dass schon die **Ausgangsform ohne weitere Konvertierung leicht lesbar** ist. Als Auszeichnungselemente wurden daher vor allem Formen verwendet, die in __plain text__ und E-Mails üblich sind. Da jedoch **nicht alle erforderlichen Textauszeichnungen enthalten** sind (etwa Tabellen), haben andere Implementierungen die Spezifikation erweitert, jedoch nicht einheitlich umgesetzt. Aus diesem Grund ist Markdown heute in unterschiedlichen __Slangs__ verfügbar. Diese ähneln sich teilweise stark, unterscheiden sich jedoch in Details. Allen gemein ist, dass sie keine einfache Umsetzung für Formeln aufweisen. Falls überhaupt vorhanden, werden Formeln meist durch die umständliche Synatx für LaTeX umgesetzt. Auch hier eine Zusammenfassung: * Einfaches Markup für Text und Listen. * Literaturangaben sind möglich, jedoch keine verwaltete Bibliographie. * Keine Tabellen und Formeln. * Einfaches, nicht standardisiertes Datenformat. * Interaktive Medien in HTML und JavaScript. ## Ein neuer Markdown Slang: **Tech**Memo Um ein möglichst einfaches Datenformat für ein technisches Memorandum zu erhalten, kombinieren wir die für uns wichtigen Eigenschaften von LaTeX und Markdown zu einer neuen Textauszeichnung. Diese verstehen wir dabei als einen weiteren Slang von Markdown. Dabei motivieren wir diese Arbeit mit dem Zitat: > Ob es besser wird, wenn es anders wird, weiß ich nicht. Dass es anders werden muss, wenn es besser werden soll, ist gewiss. > ..Georg Christoph Lichtenberg.. (1742 – 1799) Der hier verwendete Slang **basiert auf Auszeichnungen**, die besonders einfach durch **reguläre Ausrücke** in andere Formate wie etwa HTML konvertiert werden können. Grundsätzlich wird der Kerngedanke von Markdown verwendet und um Tabellen und Formeln erweitert. Letztere verwenden das [ASCIIMath](https://asciimath.org) Markup, welches sich wiederum an den Umgangsformen von E-Mails orientiert. Es ist deutlich schneller und übersichtlicher bearbeitbar, als Formeln im LaTeX-Format. Um den Slang schnell zu lernen, gibt es einen interaktiven HTML-Editor, welcher den eingegebenen Text sofort in HTML übersetzt und in einer Vorschau darstellt. Folgend ist ein tabellarischer Vergleich aufgeführt, welcher die Syntax von LaTeX mit dem neuen Markdown Slang vergleicht. Man sollte sich besonders vor Augen halten, dass beide Formate dasselbe Ziel haben: Den Text für den Leser besser kenntlich zu machen. Meiner Meinung nach ist es jedoch genauso wichtig, den Text für den Autor leserlich zu halten. ; **LaTeX** ; **TechMemo** ; \emph{Kursiv} ; __Kursiv__ ; \textbf{Fett} ; **Fett** ; \underline{Unterstrichen} ; ..Unterstrichen.. ; ; ~~Durchgestrichen~~ ; \texttt{Source Code} ; ''Source Code'' ; \section{Abschnitt 1} ; # Abschnitt 1 ; \subsection{Abschnitt 2} ; ## Abschnitt 2 ; \subsubsection{Abschnitt 3} ; ### Abschnitt 3 ; \paragraph{Abschnitt 4} ; #### Abschnitt 4 ; \[ \left[ \frac{1}{x} \right]^n \approx 0 \] ; $$ [1/x]^n approx 0 $$ ; \label{Ref1} ; [Ref1]: ; \ref{Ref1} ; [Ref1] ; \includegraphics{Datei.png} ; i[Bild](Datei.png) ; \begin{blockquote}Zitat\end{blockquote} ; > Zitat ; \begin{itemize}\item Punkt\end{itemize} ; * Punkt ; \begin{enumerate}\item Punkt\end{enumerate} ; 1. Punkt ; \begin{enumerate}\item[ A] Punkt\end{enumerate} ; A. Punkt Mit Tabellen oder Matrizen wollen wir in LaTeX erst gar nicht anfangen. Trotzdem ist hier für Kenner noch ein Beispiel für eine Matrix im Markdown Slang: $$ bb M = ((1),(2),(3)) * ((4,5,6)) = ((4,5,6),(8,10,12),(12,15,18)) $$ CODE "String" replace split substr // Strings global private public // Storage Array List Map Queue Record Set Stack // Collections Interface func implements in // Structure abs ceil floor max min mod clamp factor gcd lcm lerp prime // Arithmetic exp ln log pow sqrt // Exponential functions acos asin atan cos deg2rad rad2deg sin tan // Trigonometry cross det dot inv len norm orth refl rot trace transp // Linear algebra curl div grad // Vector analysis Avg Prod Quantile RSE Sum Var shuffle sort rand // Statistics bool nat int real vec mat str // Data types and false inf nan not null or pi true xor // Constants & logic async await produce consume // Async & parallel control // Parallel data management map stencil scan recur reduce decompose gather scatter if else for skip while exit return // Control flow assert test try catch ensure expect // Quality CODE ### Markdown nach HTML übersetzen Um einen Text in eine andere Sprache zu übersetzen, werden in der Referenzimplementierung reguläre Ausdrücke verwendent. Der gesamte Text wird dabei nach den Auszeichnungen durchsucht, welche dann durch Befehle bzw. ein Markup in der Zielsprache ersetzt werden. Als Beispiel konvertieren wir einen Codeabschnitt in die dementsprechende Auszeichnung für HTML. Folgender Quelltext zeigt den Vorgang in JavaScript: CODE str tm = "Hier ``code`` im Text."; str html = tm.replace(/``([^`\n]+)``/g, "<code>$1</code>"); CODE ### Darstellung der Seiten Angelehnt an Erkenntnisse aus der Typographie verwendet die HTML bzw. CSS Darstellung der Seite die folgenden Grundregeln: * Die Schriftgrößen sind 10 – 12pt für den Druck bzw. 16 – 20px für das Web. * Die Zeilenlänge entspricht dreimal dem kleinen Alphabet mit Leerzeichen. * Der Zeilenabstand ist 120 – 145% der Buchstabengröße. * Der Kontrast von Text zu Hintergrund ist maximiert (Schwarz auf Weiß). * Überschriften enthalten Serifen, der Fließtext ist serifenlos. * Die verwendeten Schriftarten haben 9 verschiedene Gewichtungen. * Blocksatz wird mit automatischer Silbentrennung verwendet. * Bei der Darstellung von Schriften sollte Kerning immer eingeschaltet sein. * Es gibt einen Nachtmodus, der auch die Blaulichtfilter berücksichtigt. ## Bekannte Probleme und weitere Entwicklung * Auszeichnungen können sich überschneiden. * Unterpunkte können nur für denselben Listentyp erstellt werden. Save TechMemo Export HTML