# Eigene KTouch-Lektionen schreiben

!!! info "Information"
    Dieses Tutorial ist für KTouch Version 1.7.1 (unter KDE 4.2.3) geschrieben.

## Lektion schreiben
### Eingebauter Editor
KTouch bringt einen eingebauten Editor mit um eigene Lektionen zu erstellen, oder bestehende zu verändern. Dazu über das Hauptmenü *Datei* → *Lektion bearbeiten ...* anklicken und dann „Eine neue Lektion erstellen“ oder „Aktuelle Lektion bearbeiten“ auswählen. Es öffnet sich der Lektionseditor:

![Image](builtinEditor.png)

Der Editor ist selbsterklärend. Bei dem Titel sollten die [Konventionen](#titel) beachtet werden. Das Kommentar kann frei vergeben werden.

Bei den Stufen sollte jedoch beachtet werden, dass das Feld "Neue Zeichen in dieser Stufe" genau nur die Zeichen enthalten sollte, die in dieser Stufe neu hinzukommen. Das sind dann auch die Zeichen, die beim Lernfortschritt auf der Tastatur aufleuchten. Eine genauere Beschreibung der Stufe erfolgt ein Feld tiefer. Unglücklicherweise wird als Bezeichner der Stufe das Feld "Neue Zeichen in dieser Stufe" gewählt, anstatt die Beschreibung (siehe Stufenauswahl links im Bild). Vielleicht ändert sich das in zukünftigen KTouch Versionen.

Zum Schluss lässt sich die Lektion über das Diskettensymbol (unten rechts im Bild) speichern. Als Ziel sollte das [KTouch-Benutzerverzeichnis](KTouchFuerNeoEinrichten.md#benutzerverzeichnis) gewählt werden. Dann taucht auch die neue Lektion automatisch unter den Standardlektionen auf. Bei der Wahl des Dateinamen sind weitere [Konventionen](#dateinamen) zu beachten.

### Texteditor
Die Funktionen des eingebauten Editors sind sehr eingeschränkt. Soll z.B. die Reihenfolge von mehreren Stufen (engl. Levels) gleichzeitig verändert werden, oder größere Teile von einer bereits bestehenden Lektion in die neue übernommen werden, so geht dies schneller, wenn man die Lektion mit einem normalen Texteditor bearbeitet.

Da die Lektionen in Form einer XML-Datei gespeichert werden, lassen sie sich mit jedem beliebigen Texteditor öffnen. Dennoch sollte man unter Windows lieber [Notepad++](http://notepad-plus.sourceforge.net/de/site.htm) anstatt des einfachen Notepad verwenden, da die Lektionen den Zeilenumbruch in der UNIX-Konvention (LF) darstellen und Notepad nur die Windows-Konvention (CR+LF) kennt.


### Tools
Neben der Möglichkeit Lektionen von Hand einzutippen, gibt es noch Tools, die teilweise ganze Lektionen nach einem bestimmten Muster generieren:

 * [SortWords](SortWords.md)
 * [TrainingGenerator](TrainingGenerator.md)

## Konventionen
Damit die neuen KTouch-Lekionen auch auf der Neo-Webseite in [ktouch/lectures](https://git.neo-layout.org/neo/neo-layout/src/branch/master/ktouch/lectures) veröffentlicht werden können, sollten folgende Konventionen eingehalten werden.

### Titel
Der Titel einer Lektion hat folgendem Muster zu entsprechen:
```
Deutsch (Neo<VERSION> <NAME>)
```
Dabei bedeutet:

 * `<VERSION>` = Die Neo-Version, für die diese Lektion geschrieben wurde. Eine Unterscheidung ist dahingehend sinnvoll, als dass die Belegung auf der Hauptebene sich zwischen den Versionen unterscheiden kann und die Reihenfolge der zu erlernenden Buchstaben eine andere ist. Falls die Lektion keine Einführung von neuen Buchstaben vorsieht, kann die Versionsnummer entfallen.
 * `<NAME>` = Eine beliebiger Text.

Korrekte Titel sind z.B.:
```
Deutsch (Neo1 Tastaturbelegung)
Deutsch (Neo2 Meine Lektion)
Deutsch (Neo Gedichte)
```
Die letzte Lektion stellt eine Ansammlung von Gedichten dar, bei der keine Buchstaben eingeführt, sondern direkt Gedichte getippt werden. Daher entfällt hier die Angabe der Neo-Version.

**Keine** korrekten Titel sind:

 * „Deutsch (NEO1 Tastaturbelegung)“ – `NEO` wurde komplett groß geschrieben.
 * „Deutsch (Neo 1 Tastaturbelegung)“ – Zwischen `Neo` und `1` ist ein Leerzeichen.
 * „German (Neo1 keyboard layout)“ – KTouch ist lokalisiert auf deutsch, daher sollen alle für den Benutzer sichtbaren Namen auch auf deutsch lesbar sein.


### Dateinamen
Der Dateiname einer Lektion hat folgendem Muster zu entsprechen:
```
german.neo<VERSION>.<NAME>.ktouch.xml
```
Im Gegensatz zum Titel, muss der Dateiname auf __englisch__ geschrieben werden. Das ist bei den mitgelieferten Lektionen von KTouch auch der Fall, lediglich die Titel werden in die lokalisierte Sprache (also bei uns deutsch) übersetzt.

Für die `<VERSION>` gilt das gleiche, wie beim [Titel](#titel).

Der `<NAME>` darf jedoch nur aus englischen Buchstaben (keine Umlaute), Zahlen, und den für Dateinamen zulässigen Sonderzeichen `-_.` bestehen. Leer- und weitere Sonderzeichen sollten gemieden werden, da sie beim kopieren über verschiedenen Betriebssysteme hinweg nur zu Problemen führen. Des weiteren ist es bei KTouch üblich, die Namen komplett klein zu schreiben.

Um an die oberen Titel-Beispiele anzuknüpfen, wären korrekte Dateinamen:
```
german.neo1.layout.ktouch.xml
german.neo2.my_lecture.ktouch.xml
german.neo.poems.ktouch.xml
```

**Falsch** hingegen wäre:
 * `german.neo2.my lecture.ktouch.xml` - Leerzeichen zwischen `my` und `lecture`.
 * `german.neo2.my_lecture.xml` - Das `.ktouch` fehlt. Diese Datei wird übrigens von KTouch nicht mal als Lektion erkannt, weil diese stets mit `ktouch.xml` enden müssen.


## Veröffentlichung
Ist die Lektion überprüft und ausgiebig getestet worden, so kann sie im Repository unter [ktouch/lectures](https://git.neo-layout.org/neo/neo-layout/src/branch/master/ktouch/lectures) veröffentlicht werden.

### Upload
!!! warning "Fehlerhafte Links"
    Einige Links zu anderen Dokuseiten funktionieren (noch) nicht und sind auch nicht umgestellt auf die Endung `.md`. Bitte passt die Links an, sobald die entsprechenden Seiten bereitstehen.
    
Falls man keinen Account für dieses Trac besitzt und es sich nur um den gelegentlichen Upload einer neuen Lektion handelt, so kann man seine Lektion an die [Mailingliste](Mailingliste) schicken.

Alternativ kann man auch jemanden im [IRC](IRC) bitten die Lektion hochzuladen.

### Dokumentation
Zum Schluss hat man noch die Möglichkeit seine neue Lektion im Bereich [KTouch für Neo einrichten – Lektionen](KTouchFuerNeoEinrichten.md#lektionen) in kurzen Sätzen vorzustellen.
