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 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, aber auch im Text vorhandener Mängel.
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 generierten 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 von 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 und 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 im Grunde auch HTML-Tags genutzt werden, davon wird aber grundsätzlich wegen der anschließenden Konvertierung vom Markdown ins HTML abgeraten. HTML-Tags, die erlaubt sind oder auch genutzt werden sollen, werden in dieser Anleitung genannt.
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 mit einem \ am Zeilenende gekennzeichnet. Sie sollten allerdings sparsam verwendet werden, stattdessen ist lieber ein komplett neuer Absatz mit Leerzeile in Betracht zu ziehen.
Beispiel:
In dieser Zeile wird ein Zeilenumbruch \ mit einem Backslash erzwungen. Es ist nicht erlaubt mit<br /> die Zeile umzubrechen.
Falls mehrere Zeilen nacheinander 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 der Überschriftenauszeichnung muss immer eine leere Zeile sein.
Beispiel:
Das ist der letzte Satz von vorherigen Absatz ## Eine Überschrift Ebene 2 Dies ist der neue Abend.
| 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 freigestellt.
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 ausgerichtet
- ist der Inhalt bündig mit der gestrichelten Linie auf der linken Seite, wird die Spalte linksbündig ausgerichtet
- ist der Abstand des Inhaltes gleich zu der gestrichelten Linie, wird die Spalte zentriert ausgerichtet
- ist der Inhalt nicht eindeutig zur gestrichelten Linie ausgerichtet, wird die Spalte standardmäßig links ausgerichtet
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. Zellen, welche sich über mehrere Zellen erstrecken, werden nicht unterstützt.
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.
-------------------------------------------------------------
Table: Hier ist die Tabellenunterschrift, und diese kann gern auch über
mehrere Zeilen gehen.
Die Ausrichtung ist ähnlich der Ausrichtung von einfachen Tabellen. Es gibt aber folgende Unterschiede:
- Sie müssen mit einer gestrichelten Linie vor dem Tabellenkopf beginnen, es sei denn der Tabellenkopf wird ausgelassen (siehe nachfolgendes Beispiel)
- Sie müssen mit einer gestrichelten Linie und einer Leerzeile beendet werden.
- Die einzelnen Zeilen 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 Tabellenkopf:
----------- ------- --------------- -------------------------
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.
----------- ------- --------------- -------------------------
In mehrzeiligen Tabellen achtet Pandoc auf die Breite der Spalten und im Ausgabeformat wird versucht, die relative Breite der Spalte ungefähr abzubilden. Wenn eine Spalte in der Ausgabe zu klein ist, sollte sie im Markdown-dokument verbreitert werden.
Gitternetztabellen
Bei Netztabellen wird die Tabelle sehr visuell dargestellt. Gleichheitzeichen (=) trennen den Tabellenkopf vom restlichen Tabellenkörper und können für eine Tabelle ohne Kopf weggelassen werden.
Die Besonderheit bei Netztabellen ist das die Zellen andere Auszeichnungselemente, wie Aufzählungslisten, mehrere Absätze, Codebeispiele etc., beinhalten können. Sowohl die Ausrichtung von Spalten, als auch das Zusammenfassen von Zeilen oder Spalten, wird nicht unterstützt.
Beispiel für eine Netztabelle mit Tabellenkopf:
+---------------+---------------+--------------------+ | Frucht | Preis | Vorteil | +===============+===============+====================+ | Bananen | 1.34€ | - in Schale | | | | - gelbe Farbe | +---------------+---------------+--------------------+ | Orangen | 2.10€ | - kuriert Skorbut | | | | - schmecken gut | +---------------+---------------+--------------------+
Ähnlich wie bei den vorherigen Tabellen können die Tabellenüberschriften auch weggelassen werden.
Beispiel für eine Netztabelle ohne Tabellenkopf:
+---------------+---------------+--------------------+ | Bananen | 1.34€ | - in Schale | | | | - gelbe Farbe | +---------------+---------------+--------------------+ | Orangen | 2.10€ | - kuriert Skorbut | | | | - schmecken gut | +---------------+---------------+--------------------+
Rahmentabellen
Bei diesem Tabellentyp wird jede Spalte durch einen senkrechten Strich (|)
abgetrennt, die Trennstriche zwischen den den Spalten dürfen nicht weggelassen werden. Dieser Tabellentyp kann nur Ausrichtungen, wie links-, rechtsbündig und zentriert. Aber keine Blockelemente wie Absätze, Aufzählungen, o.ä. dürfen hier nicht enthalten sein. Der Tabellenkopf muss bei diesem Tabellentyp angegeben werden, er darf aber auch leer sein.
Die Ausrichtung der Spalten erfolgt über einen Doppelpunkt (:). In Abhängigkeit der Position der Doppelpunkte wird die Spalte ausgerichtet.
- Ist der Doppelpunkt auf der rechten Seite, wie die Spalte rechtsbündig ausgerichtet
- Ist der Doppelpunkt auf der linken Seite, wird die Spalte linksbündig ausgerichtet
- Ist kein Doppelpunkt vorhanden wird die Spalte standardmäßig linksbündig ausgerichtet
- Ist jeweils ein Doppelpunkt auf der linken und rechten Seite, wird die Spalte zentriert ausgerichtet
Beispiel für eine Strichtabelle:
| Right | Left | Default | Center | |------:|:-----|---------|:------:| | 12 | 12 | 12 | 12 | | 123 | 123 | 123 | 123 | | 1 | 1 | 1 | 1 |
Da Spalten in gerahmten Tabellen durch senkrechte Striche begrenzt werden, müssen die Spalten nicht untereinander ausgerichtet sein. Im Folgenden eine hässlich aussehende, dennoch gültige Tabelle:
Frucht |Preis
----------|-----:
Annanas|2,05
Birne|1,37
Pampelmuse|1,13
Hinweis: wie Eingangs beschrieben, sind nur die senkrechten Striche zwischen den Spalten verpflichtend, die umrahmenden Striche können weggelassen werden.
Quelltext
In einigen Fällen muss Text unverändert in das Ausgabedokument übernommen werden. Dies ist zum Beispiel der Fall für Quelltexte von Programmen. In Markdown gibt es zwei Möglichkeiten für die Formatierung:
Formatierung mittels Einrückungen
Wird Text mit einem Tab (Tab-Taste) oder vier Leerzeichen eingerückt, so wird er vollständig unverändert in die Ausgabe übernommen. Das heißt auch, das kein Auszeichnungen wie z.B. fett oder kursiv, nicht übernommen werden.
Beispiel:
# Mein erstes Python-Programm
print("Hello World")
Hinweis: Wird ein Quelltext innerhalb einer Liste eingefügt, so muss die Einrückung der Liste auch noch berücksichtigt werden:
- So könnte es aussehen:
# fügen Sie hier
# Ihren Quelltext ein
- Weiter geht's
Umschlossene Quelltexte
Anstatt der Einrückung eines Quelltextes, kann dieser auch mit drei oder mehr
Tilden (~) umschlossen werden. Dabei ist zu beachten, dass der
Qulltext mit exakt so vielen Tilden beendet werden muss, wie er angefangen
wurde:
~~~~~~
# 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\}$$
Wichtig! Zwischen den $-Zeichen und dem ersten sowie letzten Formelelement dürfen keine Leerzeichen sein
Beispiele für zwei Formeln, die nicht interpretiert werden:
$ a^2 + b^2 = c^2 $
$$ \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.
 
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.
[](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 |
\
|
Umgekehrter Schrägstrich |
| ``` | Gravis |
*
|
Sternchen |
_
|
Unterstrich |
{}
|
Geschweifte Klammern |
[]
|
Eckige Klammern |
#
|
Raute |
+
|
Plus-Zeichen |
-
|
Minus-Zeichen (Bindestrich) |
Bildbeschreibungen
Allgemeines
Serienbilder beschreiben
Serienbilder sind Bilder, die im Verlauf eines Dokuments in veränderter oder ergänzter Form wiederkehren. Um dem Leser, unabhängig davon an welcher Stelle des Dokumentes er zu lesen beginnt, keine Informationen vorzuenthalten, müssen Bilder immer vollständig beschrieben werden. Damit beim Betrachten der gesamten Serie nicht große Teile der Bildbeschreibung immer wieder gelesen werden müssen, soll der Leser die Möglichkeit haben, den wiederkehrenden Teil der Beschreibung zu überspringen. Hierfür sollen Überschriften verwendet werden, die sich bei Nutzung eines Screenreaders direkt anspringen lassen. Da der Titel der Bildbeschreibung nach dem Generieren in HTML immer als Überschrift der Ebene 3 dargestellt werden, sollten die beiden Teile der Bildbeschreibungen Überschriften der Ebene 4 bekommen.
Abhängig davon, was sich im Verlauf der Serien am Bild ändert, soll dies wie folgt umgesetzt werden (die Bildbeschreibungen werden hier verkürzt dargestellt):
Grafik wird ergänzt
Der bereits beschriebene Text umfasst jeweils den gesamten Text der Bildbeschreibung des Bildes, was in der Serie unmittelbar vorausging. Hinzugekommener Bildinhalt wird im zweiten Teil ergänzt.
Bildbeschreibung in Markdown:
### Bildbeschreibung Bild 1 Dreidimensionale Darstellung eines Würfels.
Bildbeschreibung in Markdown:
### Bildbeschreibung Bild 2 #### Bereits bei Bild 1 beschrieben Dreidimensionale Darstellung eines Würfels. #### Neuer Bildinhalt Dreidimensionale Darstellung eines Zylinders.
Bildbeschreibung in Markdown:
### Bildbeschreibung Bild 3 #### Bereits bei Bild 2 beschrieben Dreidimensionale Darstellung eines Würfels und eines Zylinders. #### Neuer Bildinhalt Darstellung eines gleichmäßigen fünfzackigen Sterns.
Bildbeschreibung in Markdown:
### Bildbeschreibung Bild 4 #### Bereits bei Bild 3 beschrieben Dreidimensionale Darstellung eines Würfels und eines Zylinders und Darstellung eines gleichmäßigen fünfzackigen Sterns. #### Neuer Bildinhalt Darstellung eines Gleichseitigen Dreiecks (Spitze oben).
Grafik wird verändert
Der bereits beschriebene Text umfasst jeweils den Text der Bildbeschreibung des ersten Bildes der Serie (Basisgrafik). Neuer Bildinhalt wird im zweiten Teil ergänzt.
Bildbeschreibung in Markdown:
### Bildbeschreibung Bild 1 Dreidimensionale Darstellung eines Würfels.
Bildbeschreibung in Markdown:
### Bildbeschreibung Bild 2 #### Bereits bei Bild 1 beschrieben Dreidimensionale Darstellung eines Würfels. #### Neuer Bildinhalt Dreidimensionale Darstellung eines Zylinders.
Bildbeschreibung in Markdown:
### Bildbeschreibung Bild 3 #### Bereits bei Bild 1 beschrieben Dreidimensionale Darstellung eines Würfels. #### Neuer Bildinhalt Darstellung eines gleichmäßigen fünfzackigen Sterns.
Bildbeschreibung in Markdown:
### Bildbeschreibung Bild 4 #### Bereits bei Bild 1 beschrieben Dreidimensionale Darstellung eines Würfels. #### Neuer Bildinhalt Darstellung eines gleichseitigen Dreiecks (Spitze oben).
Bildelemente werden entfernt
Der bereits beschriebene Text umfasst jeweils den Text der Bildbeschreibung des ersten Bildes der Serie (Basisgrafik). Im zweiten Teil wird entweder alles beschrieben, was aus der Basisgrafik entfernt wurde oder alles, was nach Entfernung übrig geblieben ist. Dabei soll die Variante ausgewählt werden, die den kürzeren bzw. übersichtlicheren Text ergibt. Jedoch soll innerhalb der Serie nur eine Variante verwendet werden.
Bildbeschreibung in Markdown:
### Bildbeschreibung Bild 1 Dreidimensionale Darstellung eines Würfels und eines Zylinders und Darstellungen eines gleichmäßigen fünfzackigen Sterns und eines Dreiecks (Spitze oben).
Bildbeschreibung in Markdown:
### Bildbeschreibung Bild 2 #### Bereits bei Bild 1 beschrieben Dreidimensionale Darstellung eines Würfels und eines Zylinders und Darstellungen eines gleichmäßigen fünfzackigen Sterns und eines Dreiecks (Spitze oben). #### Entfernte Elemente ggü. Bild 1 Darstellung eines Gleichseitigen Dreiecks (Spitze oben).
oder
#### Verbliebene Elemente ggü. Bild 1 Dreidimensionale Darstellung eines Würfels und eines Zylinders und Darstellung eines gleichmäßigen fünfzackigen Sterns.
Bildbeschreibung in Markdown:
### Bildbeschreibung Bild 3 #### Bereits bei Bild 1 beschrieben Dreidimensionale Darstellung eines Würfels und eines Zylinders und Darstellungen eines gleichmäßigen fünfzackigen Sterns und eines Dreiecks (Spitze oben). #### Entfernte Elemente ggü. Bild 1 Darstellungen eines gleichmäßigen fünfzackigen Sterns und eines Dreiecks (Spitze oben).
oder
#### Verbliebene Elemente ggü. Bild 1 Dreidimensionale Darstellung eines Würfels und eines Zylinders.
Bildbeschreibung in Markdown:
### Bildbeschreibung Bild 4 #### Bereits bei Bild 1 beschrieben Dreidimensionale Darstellung eines Würfels und eines Zylinders und Darstellungen eines gleichmäßigen fünfzackigen Sterns und eines Dreiecks (Spitze oben). #### Entfernte Elemente ggü. Bild 1 Dreidimensionale Darstellung eines Zylinders und Darstellungen eines gleichmäßigen fünfzackigen Sterns und eines Dreiecks (Spitze oben).
oder
#### Verbliebene Elemente ggü. Bild 1 Dreidimensionale Darstellung eines Würfels.
