<?xml version="1.0" encoding="UTF-8"?>
<chapter id="hyphenator.examples">
    <title>Usage-Examples</title>
    <sect1>
        <title>Prerequisites</title>
        <para>Before the <package>Hyphenator</package> can be used you have to 
        add the provided autoloader either using your own autoloader or by 
        invoking the <package>Hyphenators</package> own autoloader</para>
        <para>
            <programlisting language="php" id="hyphenator.example.prerequisites">require_once 'path/to/Org/Heigl/Hyphenator/Hyphenator.php';
\Org\Heigl\Hyphenator\Hyphenator::registerAutoload()</programlisting>
        </para>
    </sect1>
    <sect1>
        <title>Simple Example</title>
        <para>
            <programlisting language="php" id="example.simple"><![CDATA[use \Org\Heigl\Hyphenator as h;
$hyphenator = h\Hyphenator::factory();
$result = $hyphenator->hyphenate('This is your text to be hyphenated');]]></programlisting>
        </para>
        <para>
            Plainly create a <classname>Hyphenator</classname>-Object via the
            factory-method and invoke its <methodname>hyphenate</methodname>-method. 
        </para>
        <para>
            It will be hard to make it more simple.
        </para>
    </sect1>
    <sect1>
        <title>Simple example with non-standard Hyphenator-Home-folder</title>
        <para>
	        <programlisting language="php"><![CDATA[use \Org\Heigl\Hyphenator as h;
$hyphenator = h\Hyphenator::factory('/path/to/home/directory');
$result = $hyphenator->hyphenate('This is your text to be hyphenated');]]></programlisting>
        </para>
        <para>
            Of course the Hyphenators home-folder has to be available in the 
            given location and has to be writeable to hte user executing the
            hyphenator (normaly the webserver-user).
        </para>
    </sect1>
    <sect1>
        <title>Invoke the <package>Hyphenator</package> manually</title>
        <para>
            <programlisting language="php"><![CDATA[use \Org\Heigl\Hyphenator as h;
$o = new h\Options();
$o->setHyphen('-')
  ->setDefaultLocale('de_DE')
  ->setRightMin(2)
  ->setLeftMin(2)
  ->setWordMin(5)
  ->setFilters('Simple')
  ->setTokenizers('Whitespace','Punctuation');
$h = new h\Hyphenator();
$h->setOptions($o);

echo $h->hyphenate('We have some really long words in german like sauerstofffeldflasche.');
// prints We have some re-al-ly long words in ger-man like sau-er-stoff-feld-fla-sche.
// Thanks to lsmith for the idea!]]></programlisting>
        </para>
    </sect1>
    <sect1>
        <title>Hyphenate HTML-content</title>
        <para>
            <programlisting language="php"><![CDATA[use \Org\Heigl\Hyphenator as h;
$o = new h\Options();
$o->setHyphen('-')
  ->setDefaultLocale('de_DE')
  ->setRightMin(2)
  ->setLeftMin(2)
  ->setWordMin(5)
  ->setFilters('Simple')
  ->setTokenizers('Xml', 'Whitespace', 'Punctuation');
$h = new h\Hyphenator();
$h->setOptions($o);

echo $h->hyphenate('<h1>Long Words</h1><p>We have some really long words in german<br />like sauerstofffeldflasche.</p>');
// prints <h1>Long Words</h1><p>We have some re-al-ly long words in ger-man<br />like sau-er-stoff-feld-fla-sche.</p>
// Thanks to mablae for the idea!]]></programlisting>
        </para>
    </sect1>
    <caution>
        <title>Performance-Hint</title>
        <para>
            Due to the sometimes rather large hyphenation-pattern-files it 
            might be a good idea to cache the hyphenator after instantiation to
            reuse the once created instance.
        </para>
        <para>
            Reading the largest hyphenation-pattern-file takes up to one 
            second on a 2.5GHz Intel Core2 Duo using 4GB RAM.
        </para>
    </caution>
</chapter>
