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.
+
projects / xmlgraphics-fop.git / commitdiff