= wordaxe Silbentrennung =

Henning von Bargen, Mrz 2009, Release 0.3.2

== bersicht ==

Der frhere Name der wordaxe-Bibliothek war "deco-cow" und stand
fr "decomposition of compound words".

Die Bibliothek besteht aber genau genommen aus drei verschiedenen Programmteilen:

1. eine allgemeine (erweiterbare) Klassenbibliothek zur Untersttzung 
   von Silbentrennung in Python-Programmen

2. ein spezieller Silbentrennungsalgorithmus, basierend auf der Zerlegung von zusammengesetzten Wrtern

3. eine Silbentrennungserweiterung zur <a href="http://www.reportlab.org">ReportLab</a> PDF Bibliothek

== <a name="bezug" />Bezugsquelle ==

Die wordaxe Bibliothek wird auf SourceForge verwaltet (<a href="http://deco-cow.sourceforge.net">http://deco-cow.sourceforge.net</a>).

Das jeweils aktuelle Release der Software kann aber ber die entsprechende
SourceForge <a href="http://sourceforge.net/project/showfiles.php?group_id=105867">Download-Seite</a>
heruntergeladen werden. Die allerneueste in Entwicklung befindliche Version
wird im Sourceforge Subversion-Repository verwaltet.

== Lizenz ==

Die wordaxe Silbentrennungsbibliothek kann wahlweise unter einer der beiden
Open-Sourcen Lizenzen "Apache 2.0 License" oder "2-Clauses BSD-License"
verwendet werden.

Der genaue Text liegt der Bibliothek bei (Datei license.txt).

Zu den Lizenzen fr die pyHnj Bibliothek von Danny Yoo zur HNJ-Silbentrennung,
und fr die ReportLab PDF Bibliothek siehe die entsprechenden Webseiten.

Die "dictionary files" mit der Endung <tt>.dic</tt> sind von der OpenOffice
Distribution bernommen, sie stehen unter der GNU LGPL Lizenz.

== Installation ==

=== ReportLab 2.3 ===

wordaxe Release 0.3.2 wurde mit Python 2.5 und ReportLab 2.3 getestet,
sollte jedoch problemlos auch mit Python 2.4 funktionieren, da keine neuen 
Features von Python 2.5 verwendet werden.

ReportLab 2.3 kann von <a href="http://www.reportlab.org">www.reportlab.org</a>
heruntergeladen und installiert werden (hier wird nicht beschrieben, wie das geht).

Die Version wordaxe 0.3.0 funktioniert auch mit dem etwas lteren ReportLab 2.2 oder 2.1.

Hinweise zu noch lteren ReportLab-Versionen:

Mglicherweise funktioniert wordaxe Release 0.3.0 auch mit ReportLab 2.0.
Ansonsten kann in diesem Fall auch Release 0.2.2 verwendet werden,
was aber bei der Installation etwas schwieriger ist (man musste da noch
einige Dateien in der ReportLab-Installation berschreiben und die
Installationsanleitung war nicht korrekt).

Fr ReportLab 1.19 sei auf Release 0.1.1 verwiesen (nicht empfohlen).
Bei einer Umstellung von ReportLab 1.x auf 2.x ist (unabhngig von wordaxe)
zu beachten, dass bestehender Code evtl. angepasst werden muss, da als
"paragraph encoding" immer UTF8 benutzt werden muss.

=== Installation wordaxe Schritt fr Schritt ===
1. Das ZIP-Archiv wordaxe-0.3.2.zip von der SourceForge Seite
   (siehe <a href="#bezug">Bezug</a>) herunterladen.

2. Das ZIP-Archiv wordaxe-0.3.2.zip im Wurzelverzeichnis C:\ entpacken
   (innerhalb des Archivs liegen alle Dateien in einem Verzeichnis "wordaxe-0.3.2").
   Dadurch wird die folgende Verzeichnisstruktur angelegt:

{{{
C:
    wordaxe-0.3.2
        docs
        htdocs
            css
            examples
            icons
            images
        tests
        wordaxe
            dict
            plugins
            rl
}}}

   
3a. Auf der Kommandozeile ausfhren:

{{{
cd /d c:\wordaxe-0.3.2
setup.py install
}}}
   
3b. Alternativ:
   Fr ReportLab 2.2 oder lter: eine Sicherheitskopie der Datei reportlab\pdfbase\rl_codecs.py von der
   ReportLab Installation anlegen; anschlieend die Datei ersetzen
   durch die mitgelieferte angepasste Version in c:\wordaxe-0.3.2\wordaxe\rl\rl_codecs.py.
   
   <em>Beachte:</em> Dadurch werden nur zwei Zeilen in der Datei gendert, 
   die das "scheue Minuszeichen" SHY betreffen. 
   
   Die neue Bibliothek zum Python-Path hinzufgen, zum Beispiel durch Anlegen
   einer entsprechenden Datei wordaxe.pth im Verzeichnis c:\python25\lib\site-packages,
   die nur die folgende Textzeile enthlt:

{{{
c:\wordaxe-0.3.2
}}}

4. Anschlieend sicherstellen, dass "import wordaxe" keine Fehlermeldung erzeugt.
   
5. ReportLab funktioniert genau so wie vorher; Unterschiede knnen hchstens auftreten,
   wenn innerhalb der <em>eigenen</em> Programme oder Texte das SHY-Zeichen verwendet wird.
   
== Verwendung ==

Um die Silbentrennung mit dem DCW-Algorithmus (Zerlegung von zusammengesetzten Wrtern)
fr deutschsprachige Texte in Aktion zu sehen,
kann man zum Beispiel das Skript "test_hyphenation.py" im Unterverzeichnis rl aufrufen.
Es erzeugt dann zwei PDF-Dateien, test_hyphenation-plain.pdf und test_hyphenation_styled.pdf.

Auch dieses Dokument selbst wurde mit automatischer Silbentrennung erzeugt
(siehe Skript buildDoku.py).

Um die Silbentrennung in eigenen Programmen zu verwenden (am Beispiel
des DCW-Algorithmus fr Deutsch), gengt es, wenige sehr einfache nderungen 
am vorhandenen Programm vorzunehmen:
  
Die folgenden Zeilen hinzufgen:

{{{
from wordaxe import hyphRegistry
from wordaxe.DCWHyphenator import DCWHyphenator
hyphRegistry['DE'] = DCWHyphenator('de',5)
}}}

Die folgenden Strings suchen und ersetzen:
{{{
Suchen                            Ersetzen durch
reportlab.platypus.paragraph      wordaxe.rl.paragraph
reportlab.platypus.xpreformatted  wordaxe.rl.xpreformatted
reportlab.lib.styles              wordaxe.rl.styles
}}}

Die Silbentrennung einschalten. Dazu im verwendeten ParagraphStyle zwei
Attribute setzen:

{{{
stylesheet = getSampleStyleSheet()
myStyle = stylesheet["BodyText"]
myStyle.language = 'DE'
myStyle.hyphenation = True
}}}

=== Verwendung eines Hyphenators ===

Selbstverstndlich kann die Silbentrennung auch unabhngig von ReportLab
verwendet werden.

Beim Konstruktor muss neben einem Sprachcode vor allem eine 
minimale Wortlnge angegeben werden. Krzere Wrter werden gar nicht betrachtet.

{{{
from wordaxe.DCWHyphenator import DCWHyphenator
hyphenator = DCWHyphenator('de',5)
}}}

Nun knnen Wrter (Unicode) getrennt werden.
Zurckgeliefert wird entwender None (unbekanntes Wort)
oder ein HyphenatedWord, d.h. ein Wort mit Angabe der
mglichen Trennstellen und ihrer Qualitt.

{{{
hword = hyphenator.hyphenate(u"Donaudampfschiffahrt")
print "Mgliche Trennstellen", hword.hyphenations
# Trenne an der 2. mglichen Trennstelle:
left,right = hword.split(hword.hyphenations[1])
# liefert: (u'Donau\xad', HyphenatedWord(u'dampfschiffahrt'))
# Der linke Teil ist wieder ein Unicode-Objekt (hier: Donau-),
# der rechte Teil ist das briggebliebene HyphenatedWord, das
# in die nchste Zeile kommen soll.
print left
print right.hyphenations
}}}

== Klassen fr die Silbentrennung ==

Zur Verwendung der Klassen siehe auch die jeweiligen Quelltexte, die
jeweils Testcode mit Aufruf des Konstruktors enthalten. Der Testcode
kann aufgerufen werden, um zu sehen, wie die jeweilige Klasse mit
Worten umgeht. Die Worte knnen auf der Kommandozeile eingegeben werden.
Es bietet sich an, dabei auerdem die Option -v anzugeben.

Beispiel:
{{{
c:\python25\python wordaxe\DCWHyphenator.py -v Silbentrennung
}}}

=== DCWHyphenator ===

Diese Klasse basiert auf der Zerlegung von zusammengesetzten Wrtern,
inspiriert durch die Publikationen der TU Wien zur "sicheren sinnentsprechenden 
Silbentrennung fr die deutsche Sprache", siehe 
<a href="http://www.ads.tuwien.ac.at/research/SiSiSi/">http://www.ads.tuwien.ac.at/research/SiSiSi/</a>.

Die Implementierung hat jedoch nichts zu tun mit dem Closed Source Produkt "SiSiSi".

Der Algorithmus funktioniert wie folgt:
Ein gegegebenes zusammengesetztes Wort wird zunchst in die Einzelwrter zerlegt.

Dazu wird die Datei DE_hyph.ini verwendet.
Sie enthlt Wortstmme, teilweise versehen mit zustzlichen Annotationen wie
NEED_SUFFIX, NO_SUFFIX etc.
Auerdem sind dort mgliche Vorsilben und Suffixe hinterlegt.

Aufgrund der Komplexitt des Zerlegungsverfahrens ist es vergleichsweise langsam:

Das Wort wird von links nach rechts betrachtet.
Es wird zerlegt in ein Tupel (L,R), wobei natrlich verschiedene
Aufteilungen mglich sind, z.B. bei "Trennung" ("T", "rennung"),
("Tr", "ennung"), ("Tre", "nnung"),  usw.
Immer wird geprft, ob der linke Teil zu einer der bekannten Vorsilben, Wortstmme 
bzw. Endungen aus der Datei DE_hyph.ini passt. Falls ja, wird mit dem Restwort
analog weitergemacht. Andernfalls, oder wenn die Kombination keinen Sinn ergibt
(z.B. Vorsilbe + Suffix ohne Wortstamm dazwischen) wird abgebrochen.

Im Prinzip handelt es sich dabei um ein rekursives Verfahren, was aber im
Programm nicht rekursiv, sondern mit Hilfe von Listen umgesetzt wurde.

Die besonderen Eigenschaften dieses Verfahrens sind:

Es werden nur dem Programm bekannte Wortstmme erkannt. 

Dadurch werden mgliche Trennstellen evtl. bersehen, denn unbekannte Wrter werden 
grundstzlich nicht getrennt. 

Andererseits kann es so auch nicht zu falschen Trennungen kommen.

Wenn ein zusammengesetztes Wort auf mehr als eine Art interpretiert werden kann,
werden nur die Trennstellen bercksichtigt, die bei allen Zerlegungen gleich sind.
Dadurch kann es nicht zu sinnentstellenden Trennungen kommen.

Trennstellen werden mit einer Prioritt versehen, die dann vom aufrufenden Programm
bercksichtigt werden kann, um gute Trennstellen (an Wortgrenzen) zu bevorzugen.

Diese Klasse untersttzt auch alle Features von ExplicitHyphenator.

=== ExplicitHyphenator ===

Diese Klasse untersttzt alle Features von BaseHyphenator, plus:

Bei dieser Klasse kann man fr jedes Wort einzeln vorgeben, wie es getrennt werden
soll. Damit eignet sich diese Klasse allenfalls fr bestimmte Anwendungsbereiche,
bei denen der Wortschatz so klein ist, dass die Trennung fr alle anfallenden Worte
(zumindest die langen) vorab festgelegt werden kann (z.B. wenn praktisch nur feste
Textbausteine verwendet werden).

Mit den Methoden add_entry, add_entries sowie add_entries_from_file knnen solche
Trennungen genau vorgegeben werden (siehe Testskript special_words.py).

=== PyHnjHyphenator ===

Diese Klasse funktioniert so wie die Silbentrennung in TeX, basierend auf Mustern
(vergleiche libhnj, pyhnj). Die Implementierung kann die pyhnj C-Bibliothek
verwenden (das ist die Voreinstellung) oder aber Pure Python, wenn das
Argument purePython=True beim Konstruktor angegeben wird.

=== wordaxe.plugins.PyHyphenHyphenator ===

Diese Klasse funktioniert ebenfalls so hnlich wie in TeX, verwendet jedoch
eine andere Implementierung und <em>funktioniert wesentlich besser</em>!
Um diese Klasse verwenden zu knnen, muss die pyhyphen-Bibliothek
installiert sein (siehe <a href="http://pypi.python.org/pypi/PyHyphen/">http://pypi.python.org/pypi/PyHyphen/</a>).

Diese Klasse untersttzt auch alle Features von ExplicitHyphenator.

=== BaseHyphenator ===

Diese Klasse funktioniert mit jeder Sprache.
Getrennt wird nur nach den folgenden Zeichen:

{{{
    '-'   Minuszeichen (45, '\x2D')
    '.'   Punkt (46, '\x2E') (aber z.B. nicht bei Punkten zwischen Ziffern)
    '_'   Unterstrich (95, '\x5F')
    ''   SHY hyphenation character (173, '\xAD')
}}}

Wenn beim Konstruktor das Argument CamelCase=True angegeben wird,
dann werden auch CamelCase-Wrter getrennt.

== Anmerkungen ==

=== Performance ===

Der DCWHyphenator bentigt aufgrund des verwendeten
(im Prinzip rekursiven) Algorithmus relativ lange fr die
Trennung eines Wortes.

Da die Wortlnge in der Praxis begrenzt ist, ergibt sich beim
Einsatz mit ReportLab eine Laufzeit proportional zur Anzahl
der (Zeilen minus Abstze), denn es wird jeweils das letzte Wort
einer Zeile geprft (auer bei der letzten Zeile im Absatz).

Speziell fr den DCWHyphenator bietet es sich an, diesen nicht direkt
zu verwenden, sondern die Ergebnisse wie folgt zu cachen:
{{{
import wordaxe
from wordaxe.DCWHyphenator import DCWHyphenator
hyph = DCWHyphenator("DE")
wordaxe.hyphRegistry ["DE"] = wordaxe.Cached(hyph, 1000)
}}}

=== Erweiterungsmglichkeiten ===

Andere Silbentrennungsbibliotheken, z.B. von Duden,
knnen mit Hilfe von ctypes oder mit SWIG leicht eingebaut werden.

Dazu muss die Member-Funktion "hyphenate" berschrieben werden,
die ein Unicode-Wort als Eingabe erhlt und eine HyphenatedWord-Instanz
zurckliefern muss.

=== Hinweise zu ReportLab ===

ReportLab macht uns das Leben nicht leicht, da platypus.paragraph.py
nicht gerade mit Rcksicht auf sptere Erweiterungen geschrieben wurde.

Alles wre <em>viel</em> einfacher, wenn anstelle der vielen internen
Routinen (z.B. "_leftDrawParaLine" etc.) Methoden in der Paragraph-Klasse
verwendet wrden. Eine Erweiterung der Funktionalitt knnte dann
im Grunde durch einfaches Schreiben einer abgeleiteten Klasse erfolgen,
bei der im Wesentlichen nur "breakLines" berschrieben werden msste.

Das zweite Problem bei ReportLab 2.x ist die nicht durchgngige Verwendung
von Unicode. Stattdessen wird mal mit Unicode, mal mit UTF8 und mal mit
noch anderen Byte-Codierungen gearbeitet.

Aus diesem Grunde wird nun eine eigene Paragraph Implementierung genutzt,
bei der gegenber ReportLab groe Teile des Codes von Grund auf neu
geschrieben wurden.