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: 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


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 | -helpZeigt die Hilfe an.
-versionZeigt die Version von xmltv2tgd an.
-infoZeigt 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: Version 1.2 vom 28. Juni 2005: Version 1.3 vom 30. Juni 2005: Version 1.4 vom 4. Juli 2005: Version 1.5 vom 22. Juli 2005: