Updated the readme file for hyphenation; a few small corrections to

the hyphenation web page


git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk@292141 13f79535-47bb-0310-9956-ffa450edef68

hyph/readme

@@ -1,43 +1,93 @@
 Hyphenation
 
-Fop comes with some hyphenation pattern. If you need a hyphenation
-pattern which isn't included in the distribution, do the following:
-
-1. get the TeX hyphenation pattern file and turn it into an xml file
-   which conforms to the hyphenation.dtd in the sub directory /hyph
-
-2. name this new file following this schema: languageCode_countryCode.xml.
-   If you don't need a country code, leave it away, p.e. the file name
-   for an American english hyphenation pattern would look like this:
-   en_US.xml.
-   For an Italian file: it.xml.
-   Language and country codes must be the same as in xsl:fo, that is follow
-   ISO 639 <http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt> and
-   ISO 3166 <http://www.ics.uci.edu/pub/ietf/http/related/iso3166.txt>
-   respectively.
+FOP uses Liang's hyphenation algorithm, well known from TeX. It needs
+language specific patterns and other data for operation.
+
+Because of licensing issues (and for convenience), all hyphenation
+patterns for FOP are made available through the Objects For Formatting
+Objects project <http://offo.sourceforge.net/hyphenation/index.html>.
+
+To install a custom hyphenation pattern for use with FOP:
+
+1. Convert the TeX hyphenation pattern file to the FOP format. The FOP
+   format is an xml file conforming to the DTD found at
+   {fop-dir}/hyph/hyphenation.dtd.
+
+   The most important source of TeX hyphenation pattern files is the
+   CTAN TeX Archive
+   <http://www.ctan.org/tex-archive/language/hyphenation/>.
+
+2. Name this new file following this scheme:
+   languageCode_countryCode.xml. The country code is optional, and
+   should be used only if needed. For example:
+-  en_US.xml would be the file name for American English hyphenation
+   patterns,
+-  it.xml would be the file name for Italian hyphenation patterns.
+
+   The language and country codes must match the XSL-FO input, which
+   follows ISO 639
+   <http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt>
+   (languages) and ISO 3166
+   <http://www.ics.uci.edu/pub/ietf/http/related/iso3166.txt>
+   (countries).
+
    NOTE: The ISO 639/ISO 3166 convention is that language names are
-   written in lower case, while country codes are written in upper case.
-
-3. If you have build your new hyphenation pattern file successfully there are
-   two ways to make it accessible to Fop.
-   a) Put this new file into the directory /hyph and rebuild Fop. The file will
-      be picked up and added to the fop.jar.
-   b) Put the file into a directory of your choice and specify this directory
-      in the userconfig.xml in the entry <hyphenation-dir>
-
-4. If the license of your hyphenation pattern file does allow it, please send
-   it to the list fop-dev, so it can be made part of the Fop distribution.
-
-the following hyphenation patterns are part of the Fop distribution
-
-da      Danish
-de      German (traditional)
-de_DR   German (new spelling)
-en      American English
-en_GB   British English
-en_US   American English
-es      Spanish
-fi      Finnish
-fr      French
-it      Italian
-nl      Dutch (new official Dutch spelling)
+   written in lower case, while country codes are written in upper
+   case.
+
+   FOP does not check whether the language and country specified in
+   the FO source are actually from the current standard, but it relies
+   on it being two letter strings in a few places. So you can make up
+   your own codes for custom hyphenation patterns, but they should be
+   two letter strings too (patches for proper handling extensions are
+   welcome)
+
+3. There are basically three ways to make the FOP-compatible
+   hyphenation pattern file(s) accessible to FOP:
+
+a. Download the precompiled JAR from OFFO
+   <http://offo.sourceforge.net/hyphenation/index.html> and place it
+   either in the {fop-dir}/lib directory, or in a directory of your
+   choice (and append the full path to the JAR to the environment
+   variable FOP_HYPHENATION_PATH).
+
+b. Download the desired FOP-compatible hyphenation pattern file(s) from 
+   OFFO <http://offo.sourceforge.net/hyphenation/index.html>, and/or
+   take your self created hyphenation pattern file(s),
+   - place them in the directory {fop-dir}/hyph,
+   - or place them in a directory of your choice and set the Ant
+	 variable user.hyph.dir to point to that directory (in
+     build-local.properties),
+   and run Ant with build target jar-hyphenation. This will create a
+   JAR containing the compiled patterns in {fop-dir}/build that will
+   be added to the classpath on the next run.
+
+   When FOP is built from scratch, and there are pattern source
+   file(s) present in the directory pointed to by the user.hyph.dir
+   variable, this JAR will automatically be created from the supplied
+   pattern(s).
+
+c. Put the pattern source file(s) into a directory of your choice and
+   configure FOP to look for custom patterns in this directory, by
+   setting the hyphenation-dir configuration option.
+
+   Either of these three options will ensure hyphenation is working
+   when using FOP from the command-line. If FOP is being embedded,
+   remember to add the location(s) of the hyphenation JAR(s) to the
+   CLASSPATH (option 1 and 2) or to set the hyphenation-dir
+   configuration option programmatically (option 3).
+
+If you would like to build your own hyphenation pattern files, or
+modify existing ones, the section entitled 'Hyphenation Patterns' of
+the 'FOP: Hyphenation' page at the FOP web site
+<http://xmlgraphics.apache.org/fop/hyphenation.html#patterns> will
+help you understand how to do so. Even when creating a pattern file
+from scratch, it may be beneficial to start with an existing file and
+modify it. See OFFO's Hyphenation page
+<http://offo.sourceforge.net/hyphenation/index.html> for examples.
+
+If you have made improvements to an existing FOP hyphenation pattern,
+or if you have created one from scratch, please consider contributing
+these to OFFO so that they can benefit other FOP users as well.
+Please inquire on the FOP User mailing list.
+

src/documentation/content/xdocs/hyphenation.xml

@@ -64,7 +64,7 @@
     </section>
     <section id="install">
       <title>Installing Custom Hyphenation Patterns</title>
-      <p>To install custom a custom hyphenation pattern for use with FOP:</p>
+      <p>To install a custom hyphenation pattern for use with FOP:</p>
       <ol>
         <li>Convert the TeX hyphenation pattern file to the FOP format. The FOP
          format is an xml file conforming to the DTD found at
@@ -96,7 +96,8 @@
              in a directory of your choice (and append the full path to the JAR to 
              the environment variable <code>FOP_HYPHENATION_PATH</code>).</li>
             <li>Download the desired FOP-compatible hyphenation pattern file(s) from 
-             <fork href="http://offo.sourceforge.net/hyphenation/index.html">OFFO</fork>, 
+             <fork href="http://offo.sourceforge.net/hyphenation/index.html">OFFO</fork>,
+             and/or take your self created hyphenation pattern file(s), 
              <ul>
                 <li>place them in the directory <code>{fop-dir}/hyph</code>, </li>
                 <li>or place them in a directory of your choice and set the Ant variable