# XMLTV2TGD Benutzeranleitung

## Einleitung

Diese Java Applikation konvertiert XML Files in TGD Files. Akzeptiert werden nur XMLTV Files, die TV Programm Informationen enthalten. Informationen zu XMLTV unter http://membled.com/work/apps/xmltv.
Um das Programm zu starten muss man dem Programm mindestens zwei Parameter über die Kommandozeile mitgeben:
Das XML File, das gelesen werden soll, und das TGD File.
Die Parameter werden hinter Starter angegeben. java -cp "xmltv2tgd.jar;dom4j-1.6.1.jar" xmltv2tgd.Starter [-options] *.xml *.tgd ...

## TGD File

Eine Zeile im TGD File wird folgendermassen dargestellt:

- Name des Senders <tab>
- Startdatum im Format yyyy-MM-dd <space>
- Startzeit im Format HH:mm <tab>
- Länge der Sendung in Minuten <tab>
- Titel <tab>
- Kurze Beschreibung / Kategorie <tab>
- Lange Beschreibung <tab>
- Rating-Flag <tab>
- Timer-Flag (Y oder N)

Falls die Applikation eine dieser Informationen im XML File nicht auffinden kann, wird an diesen Stellen einfach nur ein Tab oder Space im TGD File hingeschrieben.

## Konfiguration

Man hat die Möglichkeit Werte mitzuliefern, die das Programm beinflussen.
Entweder kann man diese Werte in einem Configfile abspeichern. Oder sie über die Kommdozeile dem Programm direkt als Parameter mitgeben.
Die Werte, die über die Kommdozeile übergeben werden haben höhere Priorität als diejenigen aus der Config. Die Parameter gelten jedoch nur solange, bis das Programm beendet wird, die aus der Config gelten bei jedem Start, solange sie nicht durch Parameter überschrieben werden.
Die Werte sollten wie folgt in der Config (xmltv2tgd.properties) stehen:
<command=value>
z.B. maxEventLength=600 oder channelExclude=rtl.de,rtl2.de
Kommentarzeilen werden mit einem ! eingeleitet.

## Werte

- maxEventLength
  Dieser Wert definiert die maximale Länge (in Minuten), die ein TV-Programmhaben darf.
- defaultLength
  Falls ein Programm die maxEventLength überschreitet, oder falls keine Ersatz Start- oder Stoppzeit gefunden wird, wird dieser Wert als Programmlänge eingesetzt (in Minuten).
- maxShortDesc
  die maximale Short Description Länge (Anzahl Zeichen)
- maxLongDesc
  die maximale Long Description Länge (Anzahl Zeichen)
- language
  Falls mehrere Titel, Short- oder Long Descriptions, oder Kategorien im XMLTV File vorkommen, haben diese mit der angegeben Sprache Priorität. Die Sprache muss in zwei Buchstaben angegeben sein, falls sie länger ist wird sie einfach abgeschnitten. z.B. de, en, fr
- channelInclude
  Es werden nur diese Sender in das TGD-File aufgenommen (durch Kommas getrennt).
- channelExclude
  Es werden alle Sender ausser diesen in das TGD-File aufgenommen (durch Kommas getrennt).
- startDate
  Es werden nur Sendungen ab diesem Tag übernommen. Entweder als Datum im Format 'yyyy-MM-dd', 'now' für ab heute, oder '*' ab dem frühsten Datum im File. Default: startDate=now
- stopDate
  Es werden nur Sendungen bis zu diesem Tag übernommen. Entweder als Datum im Format 'yyyy-MM-dd', als Zahl für Anzahl Tage, oder '*' für bis auf unbegrenzte Zeit hinaus. Default: stopDate=*
- dailyFiles
  Kann auf yes oder no gesetzt werden.
- useOffset
  Kann auf yes oder no gesetzt werden.
- timeOffset
  Muss das Format +/-HHmm aufweisen.

Wichtig: Die Werte maxEventhLength, defaultLength, maxShortDesc und maxLongDesc müssen immer ganze Zahlen sein.

## Parameter

Die Werte können auch in der Kommandozeile als Parameter übergeben werden. Die Regeln bleiben wie im xmltv2tgd.properties die gleichen, es muss jedoch immer ein '-' vor den Wert gesetzt werden. Es ist zu empfehlen alle Parameter in Anführungszeichen zu setzen ("-command=value").
Die Werte, die über die Kommandozeile gesetzt wurden, haben höchste Priorität.
Falls weder in der Config, noch über die Kommandozeile Werte mitgegeben wurden, werden Default Werte gesetzt. Es ist auch möglich mehrere XML und TGD Files als Parameter anzugeben. Dann wird das Programm dementsprechend mehrmals durchlaufen. Die Parameter werden von links nach rechts gelesen und sobald je ein XML- und TGD-File gefunden wurde (welches zuerst steht spielt keine Rolle), startet das Programm mit den bis jetzt vorhandenen Werten. Alle Werte bleiben die Programmlaufzeit gespeichert, solange sie nicht durch neue überschrieben werden.
Zusätzlich gibt es weitere Befehle für die Kommadozeile, die jedoch keinen Zuweisungswert verlangen sondern nur als -befehl geschrieben werden:

-h | -help | Zeigt die Hilfe an.
-version | Zeigt die Version von xmltv2tgd an.
-info | Zeigt bei der nächsten xmltv2tgd Umwandlung alle Werte an, mit denen das Programm durchlaufen wird.

java -cp <ClassPath> xmltv2tgd.Starter -maxLongDesc=0 -info -language=en test1.xml test1.tgd -maxLongDesc=1000 test2.tgd test2.xml
Hier wird zuerst test1.xml mit einer maxLongDesc von 0 und Sprache Englisch nach test1.tgd gewandelt. Anschliessend test2.xml nach test2.tgd mit einer maxLongDesc von 1000 Zeichen und immer noch Englisch. Beim ersten Durchlauf werden noch alle Werte ausgegeben.

## Zeiten

Manchmal treten in den XML Files Fehler auf, so dass zum Beispiel an manchen Stellen die Zeiten nicht korrekt angegeben sind. Im Falle dass keine Startzeit im XML File angegeben ist, wird nach dem vorhergehenden Programm dieses Senders gesucht, und seine Stoppzeit als Startzeit genommen. Und wenn bei einem Programm die Stoppzeit fehlt, wird die Startzeit des nachfolgenden Programms genommen. Falls jedoch in diesen beiden Fällen auch die zweite Zeit fehlt, wird ein Default Wert (defaultLength) eingesetzt. Dies bedeutet, dass die Länge des Programms durch einen vorher festgelegten Standardwert ersetzt wird. Das gleiche geschieht auch wenn die Start- und Stoppzeit offensichtlich fehlerhaft sind. Z.B. eine Sendung dauert Länger als maxEventLength.

## Beschreibungen

Im TGD File gibt es zwei Arten von Beschreibungen. Eine Short Description und eine Long Description. Für beide Beschreibungen gibt es Werte, die ihre maximale Länge definieren. (maxShortDesc und maxLongDesc) Und für beide Beschreibungen gilt immer:
Wenn sie diese Werte überschreiten werden die Texte abgeschnitten und zwei Punkte am Schluss angefügt. Falls im XMLTV File keine Short Description (sub-title in XMLTV) steht, wird einfach die Long Description genommen, falls vorhanden. Wenn in diesem Fall die Long Description kürzer ist als der Maximalwert der Short Description, wird sie im TGD File nur als Short Description übernommen, sonst wird die Long Description gekürzt. Wenn eine Programmkategorie vorhanden ist, wird diese am Schluss von der Short Description mit einem Slash angehängt.

## Sender Filter

Seit der Version 1.2 besteht die Möglichkeit einzelne Sender herauszufiltern. Dies geschieht mit den Werten channelInclude und channelExclude. Von den beiden Werten gilt jedoch immer nur einer. Derjenige, der zuletzt steht. Ein Wert, der hinter dem = leer ist, gilt nicht.
channelInclude schliesst Sender ein - es werden nur diese übernommen.
channelExclude schliesst Sender aus - es werden alle, ausser diesen übernommen.
Mit Kommas getrennt, kann man auch mehrere Sender ein-, ausschliessen: z.B. channelInclude=Sender1,Sender2,Sender3
Leerzeichen zwischen den Kommas werden schon als Sendernamen erkannt. Wenn man gleich alle Sender ein- oder ausschliessen will, kann man channelExclude=* bzw. channelInclude=* schreiben.

## Datum Filter

Mit den Werten startDate und stopDate kann man bestimmte Zeiträume herausfiltern. startDate definiert das Startdatum und stopDate das Stopdatum. startDate kann entweder als Datum 'yyyy-MM-dd' angegeben werden, als 'now' (ab heute), oder als '*' (ab dem frühsten Datum im File). stopDate kann entweder als Datum 'yyyy-MM-dd' angegeben werden, als Zahl (Anzahl Tage), oder als '*' (bis auf unbegrenzte Zeit hinaus). Default sind "startDate=now", "stopDate=*". Es werden immer nur einzelne Tage und keine Stunden berechnet. Wenn die Werte gesetzt wurden, werden alle Sendungen übernommen, die zwischen 0:00 vom startDate Datum bis und mit 23:59 vom stopDate Datum beginnen.
startDate=2005-06-29 stopDate=2005-06-30 würde also zwei Tage bedeuten.
stopDatum=3 würde bedeuten das startDate Datum plus die nächsten zwei Tage.
Das Datum von startDate darf nicht nach dem stopDate sein.

## File pro Tag

Wenn der Wert dailyFiles auf yes gesetzt ist, wird für jeden Tag ein eigenes File erstellt. Der Pfad, in den die Files abgelegt werden sollen bleibt wie normalerweise der Pfad, der beim .tgd File angegeben wird. Die Namen der .tgd Files kann man mit einem Format bestimmen. "yyyy" für das Jahr, "dd" für den Tag und "MM" für den Monat. Die Anordnung kann man selber bestimmen. Man kann auch Zwischenzeichen dazwischen schreiben: ".", "-" oder "_". Ein Datumsformat darf also nur 8 (ohne Zwischenzeichen) , oder 10 (mit Zwischenzeichen) lang sein. Wenn ein Format sonstige Zeichen enthält oder zu lang ist, wird das Defaultformat yyyyMMdd genommen.
Ein Beispiel bei dem tägliche Files im Format dd-MM-yyyy in das Verzeichnis C:/temp gespeichert werden:
java -cp <ClassPath> xmltv2tgd.Starter "-dailyFiles=yes" xmltvfile.xml C:/temp/dd-MM-yyyy.tgd

## Offset

Der Wert useOffset kann entweder auf yes oder no gesetzt werden. Wenn yes gesetzt wurde, wird der Offset der Zeiten aus dem XMLTV File mit berücksichtigt. Das bedeudet, dass die Zeiten nach UTC gerichtet werden. Ein 20050609043000 +0200 im XMLTV File wüde in diesem Fall als 2005-06-09 02:30 in das TGD File geschrieben.
Mit dem Wert timeOffset kann man einen eignen Offset Wert bestimmen, der wenn useOffset auf no ist alle Offsets überschreibt, oder wenn useOffset yes ist, mit den Offsets aus dem XMLTV File addiert wird. timeOffset Werte müssen das Format +HHmm oder -HHmm haben, sonst sind sie ungültig.
Der Offset wird erst bei der Ausgabe in die TGD dazu addiert/subtrahiert. Er wirkt sich also nicht auf startDate, stopDate oder dailyFiles aus.

## Änderungen

Version 1.1 vom 27. Juni 2005:

- Das "Rating" Feld wird korrekt gesetzt.
- Leere Start- und Stopzeiten in der XML Datei führen nicht mehr zu einem Fehler.

Version 1.2 vom 28. Juni 2005:

- Die Werte channelInclude und channelExclude wurden hinzugefügt.
- -h | -help, -version und -info wurden hinzugefügt.

Version 1.3 vom 30. Juni 2005:

- Sendungen die länger dauern als die maxEventLength werden auf die defaultLength gekürzt.
- die Start- Stopzeit Ersetzung der Sendungen wurde korrigiert
- ein Datum Filter ermöglicht es nur Sendungen in einem bestimmten Zeitraum zu übernehmen.
- die Möglichkeit für jeden Tag ein eigenes File zu schreiben wurde eingebaut
- Benutzeranleitung überarbeitet.

Version 1.4 vom 4. Juli 2005:

- Wenn dailyFiles=yes kann das TGD-File nun auch ohne Pfad Angabe im aktuellen Verzeichnis gespeichert werden.
- Die Anzahl Tage bei stopDate wurden um einen Tag gekürzt.
- OutOfMemoryErrors werden abgefangen.
- Bei falschen Parametern wird eine Meldung ausgegeben.
- Stopzeitersetzung korrigiert.

Version 1.5 vom 22. Juli 2005:

- Zwei neue Werte: useOffset und timeOffset
- Kleine Verbesserungen bei den Description Külrzungen.