Tutorenanleitung
Anmerkung
Die Tutorenanleitung für Markdown befindet sich momentan noch in der Entstehung. Bitte haben Sie etwas Geduld.
Zielsetzung dieser Anleitung
Die vorliegende Anleitung soll studentischen Hilfskräften der Arbeitsgruppe Studium für Blinde und Sehbehinderte (AG SBS) als Richtlinie bei der Übertragung von Studienmaterialien in sehgeschädigtengerechte Form dienen. Studienmaterialien werden für blinde und sehbehinderte Studenten an der TU Dresden in ein barrierefreies HTML-Format übertragen. Die Übertragung erfolgt in der Regel durch studentische Hilfskräfte der jeweiligen Studienfächer. Die Kenntnisse der Studenten bezüglich HTML und der Arbeitsweise sehgeschädigter Leser sind daher sehr verschieden. Motivation dieser Anleitung ist die Entstehung einheitlicher, fehlerfreier Dokumente trotz unterschiedlicher Vorkenntnisse. Es empfiehlt sich, diese Anleitung vor Beginn der Übertragungsarbeiten gründlich durchzuarbeiten. Während der Arbeit kann sie als Nachschlagewerk benutzt werden.
Wichtigster Bestandteil dieser Anleitung sind die Regeln für die Gestaltung von elektronischen Dokumenten im HTML-Format. Dazu gehört die Aufbereitung von Texten, Bildern und ganzen Fachbüchern. Es werden außerdem Hinweise zum organisatorischen Ablauf der Tutorentätigkeit gegeben. Die in dieser Anleitung enthaltenen Regeln sind eine verbindliche Arbeitsgrundlage für die Gestaltung von sehgeschädigtengerechten Dokumenten bei der AG SBS. Sie müssen unbedingt eingehalten werden!
Bereitstellung von Studienmaterial an der TU Dresden
Die AG SBS unterstützt sehgeschädigte Studierende im integrativen Studium an der Technischen Universität Dresden. Eine wichtige Aktivität ist die Übertragung von Studienmaterialien wie Vorlesungsskripten, Lehrbriefen, Foliensammlungen, Aufgabensammlungen und Fachbüchern in eine sehgeschädigtengerechte Form. Diese Arbeit wird in der Regel von studentischen Hilfskräften (Tutoren) ausgeführt. Die von der AG SBS koordinierten Übertragungsarbeiten sind mit anderen Einrichtungen innerhalb des Bundesgebietes, die Texte sehgeschädigtengerecht auflesen, abgestimmt. Für einen breiteren Nutzerkreis interessante Texte, wie z.B. Fachbücher und Broschüren, werden SehKOn (Sehgeschädigtengerechter Katalog Online) an der Universität Dortmund registriert. Sie können von den sehgeschädigten Lesern per Fernleihe über die AG SBS bezogen werden. Bei den an der TU Dresden sehgeschädigtengerecht aufbereiteten Studienmaterialien handelt es sich ausschließlich um elektronische Dokumente. Tonkassetten werden nicht produziert.
Die umgesetzten Studienmaterialien werden in das Elektronische Literaturverzeichnis und Informationssystem für blinde und sehbehinderte Studierende (ELVIS) der AG SBS eingestellt. Als Datenformat wird das HTML-Format verwendet, damit können die Dokumente mit allen gängigen elektronischen Hilfsmitteln, wie z.B. Braillezeilen, Sprachausgabe- und Großschriftsystemen gelesen werden. Von den Arbeitsplätzen der AG SBS kann per Rechnernetz auf den Datenbestand zugegriffen werden. Die Übertragung urheberrechtlich geschützter Veröffentlichungen ist durch eine Vereinbarung mit dem Urheber bzw. mit dem Inhaber der Verwertungsrechte abgesichert. Aus dieser Vereinbarung ergeben sich einschränkende Nutzungsbedingungen für die übertragenen Dokumente. Studenten und Tutoren werden über den Inhalt der Vereinbarung belehrt.
Wie lesen Blinde und Sehbehinderte?
Viele blinde Menschen nutzen heutzutage einen Screenreader, um sich elektronische Dokumente zugänglich zu machen. Screenreader dienen als Schnittstelle zwischen visueller Bildschirminformation und dem Leser. Anstelle der visuellen Informationen werden Daten akustisch (Sprachausgabegeräte) oder taktil (Brailleausgabe) dargeboten. Dabei können nicht nur Texte wiedergegeben werden, sondern auch Bild- und Layout-Informationen, wie zum Beispiel Menüs, Hyperlinks und andere Bedienelemente. Eine weitere Möglichkeit, visuelle Inhalte für blinde Menschen zugänglich zu gestalten, sind taktile Grafiken. Durch Ertasten der Struktur können blinde Menschen Abbildungen erfassen. Die Herstellung solcher Grafiken ist recht aufwändig. Besteht der wesentliche Informationsgehalt der Grafik jedoch in Formen und Strukturen, ist eine solche Aufbereitung von Vorteil für den Betrachter.
Sehbehinderte Leser nutzen abhängig von Grad und Art ihrer Behinderung unterschiedliche Hilfsmittel, um sich elektronische Dokumente zugänglich zu machen. Dazu zählen Bildschirmlupen oder die Veränderung des Layouts per CSS. So können individuelle Probleme (z.B. eine zu kleine Schrift oder eine kontrastarme Darstellung) ausgeglichen werden. Menschen mit starker Sehbehinderung verwenden teilweise auch akustische und taktile Hilfsmittel, wie sie im oberen Abschnitt beschrieben sind. Es ist wichtig, dass Textauszeichnungen und Dokumentstrukturen dafür in einer für die Geräte lesbaren Form vorliegen. Um die Kompatibilität des HTML-Dokumentes mit diesen Hilfsmitteln zu gewährleisten, ist eine barrierefreie Gestaltung notwendig.
Anforderungen
Barrierefreiheit
"Barrierefrei sind bauliche und sonstige Anlagen, Verkehrsmittel, technische Gebrauchsgegenstände, Systeme der Informationsverarbeitung, akustische und visuelle Informationsquellen und Kommunikationseinrichtungen sowie andere gestaltete Lebensbereiche, wenn sie für behinderte Menschen in der allgemein üblichen Weise, ohne besondere Erschwernis und grundsätzlich ohne fremde Hilfe zugänglich und nutzbar sind." (Gesetz zur Gleichstellung behinderter Menschen, § 4 Barrierefreiheit)
Der Begriff der Barrierefreiheit zieht sich durch viele Gebiete des öffentlichen Lebens. Im Rahmen der Arbeit der AG SBS bezieht sich der Begriff auf die HTML-Dokumente, welche auf Grundlage der Tutorenanleitung erstellt werden. Diese Dokumente müssen blinden und sehbehinderten Studenten in ihrem kompletten Umfang zugänglich sein. Barrierefreiheit kann hierbei durch die spezielle Aufbereitung der HTML-Dateien erreicht werden. Wichtig ist es dabei, dass Textauszeichnungen, wie z.B. Überschriften, auch nicht-visuell wahrgenommen werden können. Es muss also neben Schriftgröße und -stil andere Faktoren geben, an denen man eine Überschrift erkennt.
Zitierfähigkeit
Zitierfähig sind grundsätzlich alle Quellen, die beschaffbar bzw. zugänglich sind, d.h. von interessierten Dritten nachgeprüft werden können. Um Zitierfähigkeit auch in barrierefreien HTML-Reproduktionen von Fachliteratur zu gewährleisten, ist es wichtig, dass blinden und sehbehinderten Studenten dieselben Informationen zur Verfügung stehen, wie ihren sehenden Kommilitonen. Dies beinhaltet neben textuellen Inhalten auch die Beschreibung von Grafiken, Tabellen oder besonderen Formatierungen (Zitate, Info-Kästen, ...) ebenso wie beispielsweise die Integrität der Seitennummerierung.
Einführung in MarkDown
Empfohlene Software
Für die Bearbeitung werden folgende Programme benötigt:
Folgende Programme werden empfohlen:
- PowerPoint AddIn für die schnelle Konvertierung von PowerPoint-Folien nach Markdown
- Editoren für die manuelle Bearbeitung/Erstellung von Markdown-Dateien
- Sublime Text 3
- die Installation das Package AGSBS Markdown Helper ist erforderlich
- Atom
- Sublime Text 3
- Browser zum Testen der generierten HTML-Dateien
Aufbau der Dokumente
Datei- und Verzeichnisstruktur
Unterteilung in Dateien und Dateigröße
Für das schnelle Auffinden von Informationen ist es günstig, wenn umfangreiche Studienmaterialien in mehrere Dateien untergliedert werden. Dabei dient die im Originaltext verwendete Gliederung als Orientierung. Relevante Textabschnitte können dann in Zusammenhang mit dem Inhaltsverzeichnis schnell gefunden werden. Eine Unterteilung in mehrere Dateien ist auch dann vorzunehmen, wenn es sich um einen umfangreicheren Fließtext ohne hervorgehobene Gliederungspunkte handelt. Generell sind aber sehr kleine Dateien, die nur wenige Zeilen Text enthalten, zu vermeiden.
Vergabe der Dateinamen
Die Vergabe der Dateinamen erfolgt nach einem einheitlichen Schema. Umlaute und Sonderzeichen dürfen für Dateinamen nicht verwendet werden. Alle Datei- und Verzeichnisnamen innerhalb eines Buches bzw. von Lehrmaterial müssen klein geschrieben werden. Das gilt natürlich auch für die Datei-Endungen.
Namenskonvention
Nachfolgend werden die einzelnen Dateien und deren Namen benannt und erklärt.
Dateiname | Erklärung |
anhxx.md | Der Dateiname enthält die Nummerierung des Anhangs, wobei xx durch eine
zweistellige Ziffer ersetzt werden muss. Ob der Anhang mit einer Ziffer oder einem Buchstabenpräfix nummeriert wird, hängt lediglich von einer Konfigurationsoption ab. Beispiel.: anh01.md, anh0302.md |
blattxx.md | Dieses Verzeichnis ist zu verwenden, wenn die bearbeiteten Materialien keine
Kapitel, sondern z.B. Übungsblätter oder wissenschaftliche Veröffentlichungen sind. |
glossar.md | Wörterverzeichnis einschließlich vorhandener Erklärungen |
index.md | Index (Schlagwortverzeichnis) des Dokumentes |
info.md oder readme.md | Diese Datei beinhaltet wichtige und allgemeine Informationen zur Bearbeiteten
Version, wie Beispielsweise Umsetzung Tabellen in Listenform oder ähnliche Anpassung zur Erleichterung der Lesbarkeit. |
inhalt.md | Diese Datei wird automatisch generiert und enthält sowohl das traditionelle
Inhaltsverzeichnis, als auch Verweise zu allen hier aufgeführten Dateien wie z.B. der Liste der taktilen Grafiken. |
kxx.md | Text, gegliedert nach nummerierten Kapiteln. Der Text sollte nach Möglichkeit so aufgeteilt werden, dass Gliederungspunkte immer vollständig in einer Datei enthalten sind. Der Dateiname wird vom ersten Gliederungspunkt in der Datei abgeleitet. Für jede Gliederungsebene sind unbedingt zwei Ziffern zu verwenden. x ist Platzhalter für eine Ziffer. Die Unterteilung in Unterkapitel ist optional und hängt von der Länge des Kapitels ab.
Beispiel: Kapitel 1: k01.md, Kapitel 5.6: k0506.md |
kurz.md | Diese Datei beinhaltet das Abkürzungsverzeichnis; diese Datei wird automatisch ins Inhaltsverzeichnis übernommen. |
titel.md | Haupttitelseite und deren Rückseite mit allen darauf befindlichen Informationen. |
taktil.md | Diese Datei enthält eine Liste der verfügbaren taktilen Grafiken zu einem
Lehrmaterial bzw. Buch. Zusätzlich zur Übersicht über die verfügbaren taktilen Grafiken, sollten auch Legenden an dieser Stelle vermerkt werden. Falls es für ein Lehrmaterial viele taktile Grafiken gibt, so sollten jeweils im zugehörigen Verzeichnis des betreffenden Kapitels Dateien mit dem namen "taktil.md" angelegt werden. Die Bilder müssen aus dem Material verlinkt werden. |
vxx.md | Diese Datei(en) beinhalten das Vorwort. In den meisten Fällen existiert nur ein Vorwort, es kann aber auch vorkommen, dass mehrere Kapitel unter dem Punkt Vorwort aufgeführt sind.
Beispiel: Einfaches Vorwort: v01.md, Gegliedertes Vorwort: v01.md, v02.md |
copyright.md | Diese Datei enthält den Hinweis zum Urheber, dem Inhaber der Verwertungsrechte (z.B. Verlag) und die genehmigten Nutzungsrechte. |
Alle Dateien, welche eine Nummerierung beinhalten, müssen in ein separates Unterverzeichnis, welches nach der gleichen Bezeichnung und Hauptkapitelnummer benannt ist. Das gilt für Blätter, Kapitel, Anhänge und Vorwortkapitel. Zu beachten ist, dass mehrfach untergliederte Dateien trotzdem nur in ein Hauptverzeichnis gehören.
Beispiele:
- k01
- k01.md
- k02
- k0201.md
- k0202.md
- anh01
- anh01.md
ToDo: Was ist mit:
- beilagen.html steht, dass nicht in der readme.de
- loe.html
Umsetzung
In diesem Kapitel werden alle Fragen zur Umsetzung des Ausgangsmaterials nach Markdown behandelt. Einige der nachfolgenden Code-Beispiele wurden von Markdown-Referenz entnommen.
Allgemeines
Grundsätzlich soll der übertragene Text die Gestaltung der Vorlage so gut wie möglich wiedergeben. In einigen Punkten muss aber von diesem Grundsatz, zum Zwecke der besseren Lesbarkeit, aber auch aus den in Kapitel 3(Referenz überarbeiten) genannten Überlegungen heraus, abgewichen werden.
In der Auszeichnungssprache Markdown können auch HTML-Tags genutzt werden. Jedoch wird dies nicht empfohlen, wenn ein HTML-Tag erlaubt und genutzt werden soll, wird es in dieser Anleitung benannt.
Absätze und Zeilenumbrüche
Absätze sind das zentrale Element in Markdown. Sie werden durch eine Leerzeile vor- und nach dem Absatz begrenzt. Ausnahmen sind hierbei Anfang / Ende des Dokumentes und verschachtelte Blöcke. Die meisten Elemente in Markdown müssen in einem Absatz stehen.
Beispiel:
Das ist der 1. Absatz und wenn ein neuer Absatz eingefügt werden soll. Wird einfach eine Zeile davor frei gelassen.
Zeilenumbrüche
Zeilenumbrüche werden entweder mit einem \
am Zeilenende oder durch
zwei Leerzeichen gekennzeichnet. Sie sollten sparsam verwendet werden,
stattdessen sollten Absätze, wenn immer möglich verwendet werden.
Beispiel:
In dieser Zeile wird ein Zeilenumbruch \ mit einem Backslash erzwungen. Es ist nicht erlaubt mit<br /> die Zeile umzubrechen.
Falls mehrere Zeilen nacheinader umgebrochen werden müssen, wie beispielsweise auf einer Titelseite, so kann am Anfang der Zeile ein senkrechter Strich verwendet werden.
Beispiel:
| **Analyse eines Forschungsthemas** | TU Dresden | 6.7.8999
Textformatierung und Hervorhebung
Erklärung | Auszeichnung | Bemerkung |
Kursiv |
Dieser Text ist _kursiv mit Unterstrichen_ und *dieser Text ist kursiv mit einem Sternchen* formatiert. |
Dieser Text ist kursiv mit Unterstrichen
und dieser Text ist kursiv mit einem Sternchen formatiert. |
Fett |
Dieser Text ist __fett mit zwei Unterstrichen__ und **dieser Text ist fett mit zwei Sternchen** formatiert. |
Dieser Text ist fett mit zwei Unterstrichen
und dieser Text ist fett mit zwei Sternchen formatiert. |
Fett und Kursiv |
Ist ein Text mit ***drei Sternchen (\*\*\*)*** oder ___ drei Unterstriche (\_\_\_)___ umschlossen, wird der Text fett und kursiv dargestellt. |
Ist ein Text mit drei Sternchen (***) oder
drei Unterstrichen (___) umschlossen, wird der Text fett und kursiv dargestellt. |
durchgestrichen (ToDo) |
Ist ein Test mit zwei Tilden (~~), wird dieser ~~Text durchgestrichen~~. |
Ist ein Test mit zwei Tilden (~~), wird dieser |
Wichtig! Für die Formatierung ist es erforderlich, dass zwischen dem ersten und letzten Buchstaben des zu formatierenden Textes keine Leerzeichen sind.
Beispiel für falsch formatierten Text:
Diese Formatierung ist ** falsch **, da Leerzeichen vor dem f und hinter dem h sind.
Korrektes Beispiel:
Es darf kein Leerzeichen zwischen dem Formatierungszeichen und Buchstaben sein, wie bei **diesem Text**!
Überschriften
Für die Gliederung des Textes können Überschriften der Ebene 1 bis Ebene 6 verwendet werden. Jedes Verzeichnis wie z.B. kXX wird vom Konverter als Kapitel angesehen, daher darf es im gesamten Verzeichnis nur eine Überschrift der Ebene 1 geben. Ausnahme hierbei ist die Datei mit den Bildbeschreibungen (z.B. bilder.md oder images.md), da diese nur ausgelagerte Bildbeschreibungen enthält und nicht zum Kapitel gehört.
Überschriften der Ebene 1 und Ebene 2 können auf 2 Weisen ausgezeichnet werden.
Ansonsten gibt die Anzahl des Raute-Zeichen die Überschriftenebene an.
Wichtig - Vor und hinter der Überschriftenauszeichnung muss immer eine leere Zeile sein.
Erklärung | Auszeichung | Bemerkung |
Überschriften Ebene 1 | Das ist eine Überschrift Ebene 1 ======================= # Das ist eine Überschrift Ebene 1 |
Darf nur einmal in jedem Kapitel vorkommen |
Überschrift Ebene 2 | ## Überschrift Ebene 2 |
|
Überschrift Ebene 3 | ### Überschrift Ebene 3 |
|
Überschrift Ebene 4 | #### Überschrift Ebene 4 |
|
Überschrift Ebene 5 | ##### Überschrift Ebene 5 |
|
Überschrift Ebene 6 | ###### Überschrift Ebene 6 |
Überschriften werden vom Konverter automatisch nummeriert, deshalb ist es wichtig diese nicht mit in die Überschrift zu übernehmen und die Namenskonvention der Dateinamen einzuhalten.
Seitenzahlen
Seitenzahlen werden mit "||" eingeleitet und müssen das Format
<Bezeichner> <Zahl>
haben, wobei "Bezeichner"
entweder "Seite, Folie, slide, page" ist. Jede Seitenzahl MUSS ein eigener Absatz sein. Beispiel:
Beispiel für eine Seite
|| - Seite 80 -
Beispiel für eine Folie
|| - Folie 80 -
Seitenzahlen werden u.a. genutzt, um die Navigationsleiste zu generieren.
Listen
Bei den Listen wird zwischen geordneten (nummerierten) und unsortierte (mittels Anstrichen) Listen unterschieden. Listen sind ein Blockelement und müssen daher von Leerzeilen umgeben sein.
Nummerierte Listen
Bei nummerierten Listen können arabische und römische Zahlen, sowie Buchstaben zur Numerrierung verwendet werden. Dabei muss auf das Aufzählungszeichen entweder ein Punkt folgen, eine runde Klammer oder das Aufzählungszeichen muss vollständig in runde Klammern eingeschlossen sein (siehe unten).
Unterbrochene Aufzählungen können forgesetzt werden, z.B. nach einem Seitenumbruch. Dafür beginnt man einfach mit der jeweiligen Nummer.
Beispiele
1. Eier 2. Mehl 3. Kartoffel I. Cäsar II. Konstantin (1) Beispiel (2) Mehr Beispiel a) Brot b) Käse (c) auch legitim Die Aufzählungsliste wird auf der Seite 2 fortgesetzt. 1. Windel Größe 1 2. Feuchttücher 3. Nuckel || - Seite 2 - 4. Fläschchen 5. Fieberthermometer
Unsortierte Listen
Unsortierte Listen können mit den Zeichen `+, *` oder `-` umgesetzt werden. Welches Zeichen verwendet wird, ist dabei dem Bearbeiter feigestellt.
Beispiele
- Pizza - Döner Weitere Aufzählung +-Zeichen: + Schokolade + Kekse ...
Verschachtelte Listen
Wie alle Blockelemente, so können auch Listen verschachtelt werden. Hierbei ist zu beachten, dass eine Verschachtelte Liste um 4 Zeichen eingerückt werden muss. Ferner muss jede Liste wieder ein Absatz sein, wie im folgendne Beispiel illustriert. Nummerierte und geschachtelte Listen können frei ineinander verschachtelt werden, aber nur bis einer Tiefe von vier Ebenen.
Beispiel
Im folgenden Beispiel gehört der einführende Text noch zum Anstrich der Aufgabenstellung, die verschachtelte Aufzählung hingegen steht in ihrem eigenen Absatz.
1. Aufgabe: Beschreiben Sie den Wissenserwerb im Internet. a) Welche Vorteile bietet die unkomplizierte Verfügbarkeit der Informationen? b) Welche Risiken bietet die Partizipation vieler Menschen, erörtern Sie: - Objektivität der Informationen - Validität der Information 2. Aufgabe ...
Tabellen
Der nachfolgende Text sowie die Beispiele wurden von Pandoc Dokumentation übersetzt bzw. übernommen.
In Pandocs Markdown können Tabellen auf vier verschiedene Arten ausgezeichnet werden.
Außerdem kann optional eine Tabellenbeschriftung (auch Tabellenunterschrift) vorgenommen werden. Dazu beginnt man entweder über oder unter der Tabelle einen Absatz mit dem englischen, großgeschriebenen Wort "Table:" und schreibt die Tabellenbeschriftung dahinter. Beispielsweise Table: Übersicht aller Messwerte
.
Einfache Tabellen
Einfache Tabellen sehen folgendermaßen aus:
Rechtsbündig Linksbündig Zentriert Standard -------------- ------------- ------------- -------- 12 12 12 12 123 123 123 123 1 1 1 1 Table: Demonstration of simple table syntax.
Bei einfachen Tabellen müssen alle Werte der Spalten in einer Zeile stehen, können also nicht umgebrochen werden. Dies gilt auch für die Tabellenüberschriften.
Die Spalten werden abhängig von der Spaltenüberschrift ausgerichtet. Die Ausrichtung orientiert sich dabei an der gestrichelten Linie unterhalb des Texts (wie im obigen Beispiel ersichtlich):
- ist der Inhalt bündig mit der gestrichelten Linie auf der rechten Seite, wird die Spalte rechtsbündig formatiert
- ist der Inhalt bündig mit der gestrichelten Linie auf der linken Seite, wird die Spalte linksbündig formatiert
- ist der Abstand des Inhaltes gleich zu der gestrichelten Linie, wird die Spalte zentriert formatiert
- ist der Inhalt nicht eindeutig zur gestrichelten Linie formatiert, wird die Spalte standardmäßig links formatiert
Spaltenüberschriften können auch weggelassen werden: Dabei wird die Ausrichtung der Spalten am ersten Element ausgerichtet.
Beispiel für eine einfache Tabelle ohne Tabellenüberschriften:
------- ------ ------------ ------- 12 12 12 12 123 123 123 123 1 1 1 1 ------- ------ ------------ -------
Mehrzeilige Tabellen
Bei Tabellen mit mehrzeiligen Inhalten können die einzelnen Tabellenzellen mehr als nur eine Zeile beinhalten.
Beispiel für eine mehrzeilige Tabelle mit Tabellenüberschriften:
------------------------------------------------------------- Centered Default Right Left Header Aligned Aligned Aligned ----------- ------- --------------- ------------------------- First row 12.0 Example of a row that spans multiple lines. Second row 5.0 Here's another one. Note the blank line between rows. -------------------------------------------------------------
Die Formatierung ist ähnlich der Formatierung von einfachen Tabellen. Es gibt aber folgende Unterschiede:
- Sie müssen mit einer gestrichelten Linie beginnen, vor dem Tabellenkopf, es sei denn der Tabellenkopf fehlt (siehe nachfolgendes Codebeispiel)
- Sie müssen mit einer gestrichelten Linie und einer Leerzeile beendet werden.
- Die einzelnen Reihen werden durch eine Leerzeile getrennt.
- Wenn der Text umgebrochen werden soll, muss der Zeilenumbruch mit einem Backslash (\) gekennzeichnet werden
Beispiel für eine mehrzeilige Tabelle ohne Tabellenüberschriften:
----------- ------- --------------- ------------------------- First row 12.0 Example of a row that spans multiple lines. Second row 5.0 Here's another one. Note the blank line between rows. ----------- ------- --------------- -------------------------
Netztabellen
Bei Netztabellen wird die Tabelle sehr visuell dargestellt. Gleichheitzeichen (=) trennen den Tabellenkopf vom restlichen Tabellenkörper.
Die Besonderheit bei Netztabellen ist das die Zellen andere Auszeichnungselemente, wie Aufzählungslisten, mehrere Absätze, Codebeispiele etc., beinhalten können. Formatierungen wie bei den einfachen Tabellen werden nicht unterstützt.
Beispiel für eine Netztabelle:
+---------------+---------------+--------------------+ | Fruit | Price | Advantages | +===============+===============+====================+ | Bananas | $1.34 | - built-in wrapper | | | | - bright color | +---------------+---------------+--------------------+ | Oranges | $2.10 | - cures scurvy | | | | - tasty | +---------------+---------------+--------------------+
Ähnlich wie bei den vorherigen Tabellen können die Tabellenüberschriften auch weggelassen werden.
Beispiel für eine Netztabelle ohne Tabellenüberschriften:
+---------------+---------------+--------------------+ | Bananas | $1.34 | - built-in wrapper | | | | - bright color | +---------------+---------------+--------------------+ | Oranges | $2.10 | - cures scurvy | | | | - tasty | +---------------+---------------+--------------------+
Strichtabellen
Bei Strichtabellen werden die Tabellen ähnlich bei Netztabellen visuell dargestellt. Dieser Tabellentyp kann keine Blockelemente wie Aufzählungslisten, mehrere Absätze, Codebeispiele etc., enthalten. Des Weiteren muss diese Tabelle immer einen Tabellenkopf besitzen.
Die Formatierung der Spalten erfolgt über einen Doppelpunkt (:). In Abhängigkeit der Position der Doppelpunkte wird die Spalte formatiert.
- Ist der Doppelpunkt auf der rechten Seite, wie die Spalte rechtsbündig formatiert
- Ist der Doppelpunkt auf der linke Seite, wird die Spalte linksbündig formatiert
- Ist kein Doppelpunkt vorhanden wird die Spalte standardmäßig linksbündig formatiert
- Ist jeweils ein Doppelpunkt auf der linken und rechten Seite, wird die Spalte zentriert formatiert
Beispiel für eine Strichtabelle:
| Right | Left | Default | Center | |------:|:-----|---------|:------:| | 12 | 12 | 12 | 12 | | 123 | 123 | 123 | 123 | | 1 | 1 | 1 | 1 |
Quellcode
In der Informatik müssen neben Standardtextformatierung auch Quellcode-Ausschnitt formatiert. In Markdown gibt es 2 Möglichkeiten für die Formatierung von Quellcode
Formatierung mittels Einrückungen
Quellcode-Beispiele müssen mit einem Tab oder 4 Leerzeichen eingerückt werden.
# Mein erstes Python-Programm print("Hello World")
Umschließende Formatierung
Die Verwendung der Formatierung mit Einrückungen ist nicht immer gut geeignet. Es können auch Quellcode-Beispiele mit mindesten 3 oder mehr Tilden (~) ausgezeichnet werden. Es ist wichtig, dass der geöffnete Codeblock auch wieder geschlossen wird.
~~~~~~ # Mein erstes Python-Programm print("Hello World") ~~~~~~
Wenn in dem Quellcode jedoch Tilden vorkommen, müssen die umschließenden Tildenreihen länger sein als die im Code enthaltenden Tilden.
~~~~~~~~~~~~~~~~ ~~~~~~~~~~ Dieser Code enthält Tilden ~~~~~~~~~~ ~~~~~~~~~~~~~~~~
Mathematische Ausdrücke
Die Auszeichnung von mathematischen Ausdrücken wie Formeln kann in Markdown über mehrere Möglichkeiten erfolgen. An der TU Dresden werden Ausdrücke grundsätzlich in LaTeX gesetzt, da dies mit einem Bildschirmleser am leichtesten zu lesen ist.
Es gibt zwei Sorten von Formeln:
- Formeln im Fließtext:**
Formeln im Fließtext müssen mit einfachen Dollar-Zeichen umgeben werden. Der Konverter wird die Formel auf die Höhe der Zeile anpassen.
Beispiel:
Jedem ist bekannt, dass $a^2 + b^2 = c^2$, aber nicht jeder weiß auch, was es bedeutet.
Alleinstehende Formeln:
Formeln, die nicht in einen Text eingebunden sind, werden mit zwei Dollar-Zeichen umgeben. Damit hat der Konverter mehr Platz, um muss die Formel nicht auf Zeilenbreite stauchen.
Beispiel:
$$\vec{A} = \Big\{...\{i\mid i\in\mathbb{N}\}, ...\Big\}$$
Eine große Auswahl verfügbarer mathematischer Symbole kann in dieser Liste nachgelesen werden. Für vertiefende Informationen und weitere Symbole kann man auch die (La)TeX-Einführung von Wikipedia lesen.
Links
Links sind querverweise auf andere Dokumente oder Teile innerhalb eines Elements. Sie bestehen aus dem zu verlinkenden Text gefolgt vom Pfad des Ziels. Der Linktext wird dabei in eckige Klammern und der Pfad/die URL in runde Klammern eingefasst.
Beispiel:
Verweis auf ein Kapitel: [siehe Bildbeschreibung](bilder.html) Verweis mit URL: [Elvis Wiki](https://elvis.inf.tu-dresden.de)
Bilder
Die Markdown-Syntax für Bilder und Links ist sehr ähnlich. Der einzige Unterschied ist das Ausrufezeichen vor der öffnenden eckigen Klammer, wenn ein Bild eingebunden werden soll. In den eckigen Klammer steht die Bildbeschreibung. In den runden Klammer steht der Speicherort und Name des Bildes mit der Dateiendung.
![Alternativtext](Referenz zum Bild) ![Elvis-Logo](logo.png)
Wichtig! Die entwickelten Plugins entscheiden selbständig in Abhängigkeit der Länge, ob die Bildbeschreibung ausgelagert werden muss oder nicht. Alle ausgelagerte Bildbeschreibungen sind in Unterordner des jeweiligen Kapitels in der Datei, bilder.md, gespeichert.
Die ausgelagerten Bildbeschreibungen werden dann in der jeweiligen Kapiteldatei als verlinktes Bild eingebunden.
[![Bildbeschreibung ist ausgelagert](bilder/logo.png)](bilder.md#Bildbeschreibung_zu_Bild_1)
Zitate
Zitate müssen gesondert ausgezeichnet werden. Die Auszeichnung von Zitaten erfolgt mit dem ">"-Zeichen am Anfang der Zeile. Vor und hinter dem Zitat muss eine Leerzeile sein, da es ein Blockelement ist.
Ein weltberühmtes Zitat von Gaius Julius Caesar ist > Veni Vidi Vici Es können auch mehrere Zeilen als Zitat gekennzeichnet werden. Die 1. Strophe des Gedichtes "Erlkönig" von Johann Wolfgang von Goethe beginnt > Wer reitet so spät durch Nacht und Wind? > Es ist der Vater mit seinem Kind; > Er hat den Knaben wohl in dem Arm, > Er fasst ihn sicher, er hält ihn warm.
Fußnoten
Es existieren in Markdown zwei Arten von Fußnoten. Sie sind äquivalent und können beliebig gemischt werden.
Eingebetttete Fußnoten
Es ist möglich Fußnoten direkt in den Text einzubetten. Dabei wird der Fußnotentext direkt im Fließtext niedergeschrieben und in der Ausgabe erscheint die Fußnote dann korrekt außerhalb des Textes (darunter / am Ende des Dokumentes). Um eine solche Fußnote zu erzeugen, nutzt man das Dach-Zeichen, gefolgt von dem Text in eckigen Klammern.
Beispiel:
Das ist eine eingebettete Fußnote.^[Der Fußnotentext steht gleich mit im Text.]
Fußnote über Referenzen
Es ist möglich Fußnoten im Text zu markieren und im Anschluss an den Text diese manuell aufzulisten.
Im Fließtext markiert man die Fußnote mit in ekigen Klammern, in denen ein Dach-Zeichen gefolgt von einem Bezeichner steht. Ein Bezeichner ist dabei eine frei wählbare Zeichenkette, die im Dokument nur einmal vorkommen darf und die
mit einem Buchstaben beginnen muss, beispielsweise
Wie schon Schiller sagte,[^fn1]
Unterhalb des Absatzes, in einem eigenen Absatz, fügt mann dann die Fußnote ein. Dabei verwendet man dieselbe Syntax, also ein Dach-Zeichen mit dem gleichen Bezeichner umrahmt mit eckigen Klammern. An dieser stelle muss dann aber ein Doppelpunkt folgen und im Anschluss der Fußnotentext.
Beispiel:
Das ist ein Text mit einer Fußnote[^fn1]. Es sind auch mehrere Fußnoten erlaubt[^fn2] [^fn1]: Das ist die erste Fußnote [^fn2]: Das ist eine längere Fußnote. Wichtig ist nur, dass es eine Leerzeile zwischen den Fußnoten gibt und dass der Fußnotentext eingerückt ist.
Anmerkungen des Bearbeiters
Anmerkungen des Bearbeiters werden in einem eigenen Absatz kenntlich gemacht. Dabei sollte die Anmerkung vorzugsweise vor dem Element stehen, welches einer Anmerkung bedarf. Eine Anmerkung ist immer dann sinnvoll, wenn Originalinhalte leicht verändert werden, damit sie für den Nutzer leichter erfassbar sind. Das umfasst zum Beispiel das Transponieren von Tabellen. Dies gilt nicht für die Beschreibung von Bildern, o.ä.
Der Absatz mit der Anmerkung wird von einem speziellen Element, dem div
-Element, umgeben. Als Klasse wird dem div
-Element der Wert annotation
übergeben. Die Syntax lautet wie folgt:
<div class="annotation">Die unten stehende Tabelle enthält eigentlich vier Spalten, doch die vierte ist leer. </div> ...
Der Erklärung wird kein Text wie "Anmerkung des Bearbeiters" vorangestellt, dies geschieht bei der Konvertierung automatisch
Falls es nötig sein sollte eine Anmerkung innerhalb eines Blockelementes wie z.B. einer Tabelle oder eines Absatzes zu machen, dann muss statt eines Div-Elementes ein Span-Element verwendet werden. Die Verwendung ist analog:
Beispiel mit einer Tabelle:
------- ---------------------------------------------- Farbe Verwendung rot Färbung des Königsmantels blau Markierung... <span class="annotation">auf Markierung zeigt ein Pfeil</span> ------- ----------------------------------------------
Umrahmter Text
In seltenen Fällen kann es nötig sein, dass Text umrahmt wird. Dies sollte in aller Regel nicht genutzt werden, da Bildschirmleser nicht in der Lage sind, umrahmten Text darzustellen. Eine Anmerkung (siehe vorheriger Abschnitt) kann sinnvoller sein.
Umrahmungen werden in einem div
-Element mit der Klasse frame
erstellt. Die Syntax sieht aus wie folgt:
<div class="frame">Dieser Text ist umrahmt.</div>
Das div
-Element muss in einem eigenen Absatz stehen.
Backslash-Maskierung
In Markdown sind einige Zeichen reserviert, um z.B. den Text zu formatieren, Listen zu kennzeichnen usw. Daher müssen diese Zeichen mit einem Backslash maskiert werden.
Um ein Zeichen zu maskieren, muss ein Backslash vor dem Zeichen eingefügt werden
*Das ist ein kursiver Text.* \* Dieser Text steht in Sternchen.\*
Die folgenden Zeichen müssen maskiert werden
$ Dollarzeichen \ Backslash ` Backtick * Sternchen _ Unterstrich {} Geschweifte Klammern [] Eckige Klammern () Runde Klammern # Raute + Plus-Zeichen - Minus-Zeichen (Bindestrich) . Punkt ! Ausrufezeichen