-
Notifications
You must be signed in to change notification settings - Fork 0
wortsammler syntax
Please read also
Markdown ist eine vereinfachte Auszeichnungssprache. Ein Ziel von
Markdown ist, dass schon die Ausgangsform ohne weitere Konvertierung
leicht lesbar ist. Als Auszeichnungselemente wurden daher vor allem
Auszeichnungsarten verwendet, die bei der Schreibmaschine und und
E-Mails üblich sind.
Wortsammler verarbeitet markdown mit Hilfe von Pandoc bzw. LaTeX. Für spezifesche Anforderungen gibt es weiterführende Konventionen, die von Wortsammler verarbeitet werden:
- Tracing
- Einbindung von PDF-Seiten
- Textschnipsel
- Dokumentinterne Verweise
- Zielgruppespezifische Ausgaben
Überschriften entstehen durch voranstellen von "#"
# Header 1
## Header 2
### Header 3
- Ein Paragraph entsteht durch eine oder mehrere aufeinander folgende Textzeilen, getrennt durch eine leerzeile.
- Eine Zeile, die mit einem Backslash (
\) erzeugt einen manuellen Zeilenumbruch.
-
kursiv entsteht durch
*kursiv* -
fettdruck entsteht durch
**fettdruck** -
durchstreichenentsteht durch~~durchstreichen~~ -
Hoch^stellung^ entsteht durch
Hoch^stellung^ -
Tief
stellungentsteht durchTief~stellung~ -
Schreibmaschinenschriftentsteht durch einfache 'backticks'`Schreibmaschinenschrift`Wenn der verbatim text ein back tick enthält, sollte man es in doppelte backticks einhüllen.
`Schreibmaschinenschrift` entsteht durch einfache 'backticks' `` `Schreibmaschinenschrift` `` -
Leerzeichen innerhalb von Texthervorhebung müssen durch
\geschützt werden, zum Beispiel e.g., Hthis is a long subscriptH~this\ is\ a\ long\ subscript~.
Note
: Please note that wortsammler uses striketrhough also for specific syntax.
Numerierte Aufzählungen (auch geordnete Listen genannt) entstehen durch manuelles voranstellen einer Aufzählungsnummer. Es kann bei allen Einträgen die gleiche Nummer verwendet werden. Wortsammler baut aber die richtige Nummer ein.
Aus
1. erster Eintrag
1. zweiter Eintrag
entsteht
- erster Eintrag
- zweiter Eintrag
ED detail
aus
A) erster Eintrag
A) zweiter Eintrag
entsteht
A) erster Eintrag B) zweiter Eintrag
aus
a) erster Eintrag
a) zweiter Eintrag
entsteht
a) erster Eintrag b) zweiter Eintrag
ED all
Einfache Aufzählungen (ungeordnete Listen) entstehen durch markieren der
Einträge mit '*', '+', oder '-' markiert werden. SN Wortsammler
ersetzt diese aber immer durch "-" in den Eingabedateien.
aus
+ example
- example
* example
entsteht
- example
- example
- example
Listen können durch Einrücken um vier Zeichen verschachtelt werden:
Aus
- example
- Das ist die innere liste. Sie kann auch aus mehreren
Paragraphen bestehen.
Das ist der zweite Paragraph der inneren Liste
- Das ist der zweite Eintrag der inneren Liste
- example
entsteht
-
example
-
Das ist die innere liste. Sie kann auch aus mehreren Paragraphen bestehen.
Das ist der zweite Paragraph der inneren Liste
-
Das ist der zweite Eintrag der inneren Liste
-
-
example
Definitionslisten beschreiben einen Begriff und dessen Definition.
Aus
Term 1
: Definition 1
Term 2
: Definition 2
Zweiter parargraph von Definition 2.
entsteht
Term 1 : Definition 1
Term 2 : Definition 2
Zweiter parargraph von Definition 2.
Zitate - meist eingerückt dargestellt - entstehen durch ein
vorangestelltes > (eben wie bei emails)
aus
> das ist ein Zitat
> das auch aus mehreren Zeilen bestehen kann
>
> und noch ein Absatz im Zitat
>
>> verschachteltes Zitat
>> nested blockquote
entsteht
das ist ein Zitat das auch aus mehreren Zeilen bestehen kann
und noch ein Absatz im Zitat
verschachteltes Zitat nested blockquote
Für die Handhabung von dokument internen verweise braucht man die folgenden beiden markierungen:
-
Verweisziel
Das Verweisziel entsteht durch die spezifische Eingabe (eingebettete HTML - Syntax):
<a id="name des Verweisziels">(Wortsammler)Wird Requirements tracing verwendet, werden aus den Trace-ids ebenfalls Verweisziele erzeugt.
-
Verweis
Der Verweis selbst wird ebenfalls als HTML erfasst:
<a href="id">text für den Verweis</a>.Verweise auf Trace-Items werden als
->[id]markiert.
aus
<http://example.com>
<foo@bar.com>
entsteht
http://example.com
foo@bar.com
Bei expliziten verweisen steht der Text für das Dokument in eckigen Klammern, gefolgt vom Verweisziel in runden Klammern.
[inline link](http://example.com "Title")
Bei indirekten Verweisen wird das Verweisziel an andrer Stelle im Dokument einmalig definiert und ggf. mehrfach verwendet. Folgende Eingabe ist ein indirekter Verweis.
-
[reference link][id]- id ist er name des Verweisziels -
[implicit reference link][]oder[implicit reference link]Der Name des Verweisziels fällt mit dem darzustellenden Text zusammen.
Die Verweisziele können an einer Stelle im Dokument detailliert werden.
[id]: http://example.com "Title"
[implicit reference link]: http://example.com
[id2]: /path/to/image "alt text"
Ein vorangestelltes Ausrufezeichen zeigt an, dass das Verweisziel eine einzubettende Grafik markiert.
![reference image][id2]
Hinweis: Wenn eine Grafik alleine in einem Paragraphen steht, dann
wird sie nummeriert und ggf. auch innerhalb des Textes um die Seiten
optimal zu füllen. Es wird empfohlen, das zu vermeiden, z.b. durch
hintenanstellen eines \
Wortsammler kann Grafiken einbauen, die vom Text umflossen werden. Die Anweisung muss in einer Zeile stehen, die mit Leerzeichen beginnt
~~EMBED "{filename}" {ausrichtung} {breite} {hoehe}~~
~~EMBED "foo.pdf" l 1cm 2cm~~
ausrichtung: r oder l : rechts oder links
breite: Breite in TeX notation
hoehe: Höhe in TeX notation
PDF-Seiten können direkt eingebunden werden. Dazu wird folgende Markierung verwendet[^1]:
~~PDF "filename" "eintrag für Inhaltsverzeichnis" level seitenbereich seitenvorschub~~
Diese Eingabe muss allein in einer Zeile stehen und vier Leerzeichen davor haben. Damit wird verhindert dass Wortsammler die Zeile umbricht, und sie nicht mehr richtig verarbeitet werden kann.
Die letzten Parameter level (default=9) und seitenbereich (default=alle) seitenvorschub (default="cleardoublepage") sind optional.
Folgendes Beispiel bindet die Seite 3-4 aus der Datei
"../Beispiel.pdf" ein. Dabei wird ein PDF-Bookmark auf Ebene 2
erzeugt.
~~PDF "../Beispiel.pdf" "das ist ein Beispielpdf" 2 3-4 clearpage~~
Markdown-Fragmente können direkt eingebunden werden. Dazu wird folgende Markierung verwendet[^1]:
~~MD "filename"~~
- Das Markdown-File wird so eingebunden als der Inhalt per cut&Paste eingefügt worden wäre.
- Falls das eingefügte Fragment weitere Einfügungen enthält, werden diese ebenfalls aufgelöst.
- Die Einrückung der Zeile wird allen Zeilen im eingefügten Markdown-file vorangestellt. Damit kann man
- Markdown beispiele als Verbatim einfügen
- Partielle Listen behandeln
Textschnipsel werden in eigenen Schnipselbibliotheken spezifiziert, die in der Wortsammler Manifest referenziert werden.
Textschnipsel werden aufgerufen durch die Markierung
~~~~
~~SN <name>~~
~~~~
Dabei referenziert name den namen des Textschnipsels in der Bausteindatei.
Seitenumbrüche können durch das eingebettete LaTeX Kommando
\clearpage erreicht werden. Das funktioniert nur bei PDF-Ausgabe
Man kann auch einen bedingten Seitenumbruch bekommen durch das LaTeX Kommando
\needspace{10cm}
Right Left Center Default
------- ------ ---------- -------
12 12 12 12
123 123 123 123
1 1 1 1
Table: Demonstration of simple table syntax.
For more complex tables, see the pandoc documentation in http://johnmacfarlane.net/pandoc/README.html#pandocs-markdown
ED detail
Drei oder mehr Bindestriche, Sterne oder oder Unterstriche erzeugen eine horizontale Linie
---
* * *
- - - -
ED all
Wortsammler erlaubt zielgruppenspezifische Ausgaben. Dabei wird im Textfluss die Verarbeitung ein- bz. ausgeschaltet, je nachdem welche Zielgruppe adressiert wird.
Die Zielgruppen müssen im Wortsammler Manifest vordefiniert werden. Dann kann durch folgende Markierung die Verarbeitung auf eine oder mehrere bestimmte Zielgruppen geschaltet werden:
~~ED <zielgruppe> [<zielgruppe>]*~~
~~ED internextern~~ab hier gilt: Text erscheint in Ausgabeinternals auch inextern.
-
Die Umschaltung wirkt ab einschliesslich der Zeile, die die Umschaltung enthält, bis zum Aufruf einer neuen Umschaltung.
-
Die möglichen Zielgruppen werden im Manifest festgelegt (Eintrag
:editions:) -
Eine durch Wortsammler implizit vorgegebene Zielgruppe
allerzeugt keine spezifische Ausgabe. Sie kennzeichnet vielmehr Inhalte, die in allen Ausgaben gleichermassen enthalten sind. -
Bei einer Aufteilung auf mehrere Dateien wird empfohlen am Ende einer jeden Datei auf
allzu schalten. Dadurch wird das System einfache wartbar. -
Im Manifest kann auch eine Ausgabe mit der Eigenschaft "debug" spezifiziert werden. In dieser Ausgabe kommen alle Inhalte, die Zielgruppenumschaltung ist am Rand markiert.
In einer Debug-Ausgabe des Dokumentes werden Zeilen, die ein todo:
enthalten am Rand markiert, so dass man vorläufige Teile eines
Dokumentes gut erkennen kann.
ED all
In einer Testspezifikation muss ein Verdict definiert werden. Bei der Durchführung eines Tests soll das Verdict im generierten PDF eingetragen werden können. Das wird durch Wortsammler
Aus
~~~~ {.expectedResult TC_DES_003}
- logo on every page
- color scheme shall be seen
- clear visual structure can be recognized
- main information can be seen without scrolling
~~~~
entsteht ein PDF-Formular welches die Listenpunkte aus ausführbare checkliste darstellt.
Plantuml <plantuml.sourceforge.net> ist eine einfache Möglichkeit, UML-Diagramme zu erstellen. Wortsammler unstetützt das durch einen speziellen Textblock:
~~~~ {.plantuml}
@startuml authentification.png
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response
@enduml
~~~~
Der Dateiname der Grafik wird in der Zeile mit @startuml angegeben. Die Grafik muss explizit eingebunden werden. Damit wird der Anwendungsfall unterstützt, dass dasselbe Diagramm mehrfach im Dokument eingebunden wird.
Die Dateien, die UML-Grafiken enthalten müssen in einer separaten rake task konvertiert werden:
desc "convert the embedded plantuml diagrams"
task :plantuml do
sh "java -jar lib/plantuml.jar myfile.md"
end
[^1]: Die verwendung der Tilde führt bei normaler Verarbeitung zu einem durchgestrichenen Text