some additions to the FAQ and hyphenation usage.

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

src/documentation/content/xdocs/0.20.5/hyphenation.xml

@@ -28,7 +28,7 @@
     <section id="intro">
       <title>Introduction</title>
       <p>FOP uses Liang's hyphenation algorithm, well known from TeX. It needs
-       language specific pattern and other data for operation.</p>
+       language specific patterns and other data for operation.</p>
       <p>Because of <link href="#license-issues">licensing issues</link> (and for 
        convenience), all hyphenation patterns for FOP are made available through 
        the <fork href="http://offo.sourceforge.net/hyphenation/index.html">Objects For 
@@ -39,6 +39,79 @@
        Please inquire on the <link href="../maillist.html#fop-user">FOP User
        mailing list</link>.</note>
     </section>
+    <section id="using">
+      <title>Using Hyphenation</title>
+      <p>
+        In order to get words hyphenated, hyphenation has to be
+        enabled explicitely (set property hyphenation="true") and a
+        language has to be defined (e.g. language="en"). Optionally, a
+        country can be specified (e.g. country="GB").
+      </p>
+      <p>
+        If hyphenation is requested, at first a serialized instance
+        containing precompiled hyphenation patterns is looked up in
+        the classpath. If only a language is specified, a ressource
+        named <code>hyph/&lt;language>.hyp</code> is loaded. If both
+        language and country are specified, the ressource
+        <code>hyph/&lt;language>_&lt;country>.hyp</code> is looked up,
+        and if this fails, the loader looks also for
+        <code>hyph/&lt;language>.hyp</code>. 
+      </p>
+      <p>
+        If no precompiled patterns are found, FOP tries to load raw
+        patterns from the an XML file name
+        <code>/hyph/&lt;language>.xml</code> respective
+        <code>/hyph/&lt;language>_&lt;country>.xml</code> . The /hyph
+        prefix is hardcoded and can't be configured. Note that this
+        usually constitues an absolute file path. FOP can't load raw
+        patterns from other sources than files.
+      </p>
+      <p>
+        If you think hyphenation is enabled but words aren't
+        hyphenated, check whether FOP finds the relevant hyphenation
+        patterns:
+      </p>
+      <ol>
+        <li>Did you download and install the hyphenation patterns
+        properly? In case you downloaded the files from OFFO, check
+        whether you have downloaded the patterns for the correct FOP
+        version (0.20.5 or the development version), and check whether
+        you followed the installation instructions.</li>
+        <li>Check whether you have spelled the language code and
+        optionally the country code correctly. Note that the country
+        codes are in uppercase, by convention. This matters.</li>
+      </ol>
+      <p>
+        If hyphenation works in general, but specific words aren't
+        hyphenated, or aren't hyphenated as expected, you may have one
+        of the following problems:
+      </p>
+      <ol>
+        <li>The patters contain a bug, or simply wont do as you
+        expect. In order to reduce the amount of patters, they are
+        usually cut some slack.</li>
+        <li>The patterns may be for an unexpected, unofficial or
+        outdated dialect of the language. For example, the turkish
+        patterns were (and maybe still are) made for 17c Osman rather
+        than modern turkish.</li>
+        <li>The word may contain invisible characters which prevent it
+        from being parsed properly from the content stream, or from
+        being properly matched. Examples of such characters are the
+        soft hyphen (U+00AD) and the zero width joiner (U+200D). You
+        have to remove them in order to get the words hyphenated
+        properly. OTOH, you can use them in order to prevent certain
+        (unwanted, spurious or incorrect) hyphenations</li>
+        <li>If the word contains characters which can be composed from
+        other Unicode characters, or vice versa (e.g. U+00E4 "latin
+        small a with diaresis" and U+0061 U+0308 "latin small a"
+        "combining diaresis"), the patterns may just contain the
+        opposite form. FOP doesn't run <link
+        href="http://www.unicode.org/reports/tr15/">Unicode
+        normalization</link> on either the content nor on the
+        patterns. You have no choice but to check which form the
+        patterns use and adapt your FO source.</li>
+      </ol>
+    </section>
     <section id="license-issues">
       <title>License Issues</title>
       <p>Many of the hyphenation files distributed with TeX and its offspring are

src/documentation/content/xdocs/faq.xml

@@ -194,7 +194,7 @@
         <p>If you are running FOP from the command line:</p>
         <ul>
           <li>
-            Use the <code>fop.bat</code> or <code>fop.sh</code> command file from the FOP
+            Use the <code>fop.bat</code>, <code>fop</code> or <code>fop.sh</code> command file from the FOP
             distribution. If you have a FOP version older than 0.20.5,
             ensure the directory where FOP and these files have been
             installed is the current working directory.
@@ -212,6 +212,11 @@
           href="0.20.5/servlets.html#servlet-engine">servlet engines</link>
           for further hints.
         </p>
+        <p>
+          If you downloaded the source distribution, or a snapshop
+          from the repository, remember you have to build the FOP jars
+          first.
+        </p>
       </answer>
     </faq>
     <faq id="NoSuchMethodException">
@@ -293,10 +298,11 @@
           relied upon to catch all.
         </p>
         <p>
-          If you use XSLT, problems in your style sheet and in your source XML
-          also can produce a NullPointerException. Run the transformation
-          separately to check for this, usually you'll get a detailed error
-          message from the XSLT processor.
+          If you use XSLT, problems in your style sheet and in your
+          source XML also can produce a NullPointerException. <link
+          href="0.20.5/running.html#check-input">Run the transformation
+          separately</link> to check for this, usually you'll get a
+          detailed error message from the XSLT processor.
         </p>
         <p>
           If you turn on debugging with the "<code>-d</code>" option you may be able to
@@ -371,8 +377,9 @@
           resolving relative URLs pointing to font metric files.
         </p>
         <p>
-          Try also setting the fontBaseDir configuration. (FIXME: add
-          link to congfiguration page)
+          Try also setting the <link
+          href="0.20.5/configuration.html#summary-key-value">fontBaseDir
+          configuration</link>.
         </p>
       </answer>
     </faq>
@@ -448,14 +455,15 @@ Check the following:</p>
         <ul>
           <li>Empty or wrong baseDir setting.</li>
           <li>Spelling errors in the file name (including using the wrong case).</li>
-          <li>Security Problems (i.e. image was not delivered because FOP is not
-          allowed to read the file). This is especially a problem if the external
-          file is retrieved over HTTP. Possible issues include security settings
-          on the server, server configuration, and missing cookies or other
+          <li>Security Problems (i.e. the image could not be accessed
+          because FOP is not allowed to read the file). This is
+          especially a problem if the external file is retrieved over
+          HTTP. Possible issues include security settings on the
+          server, server configuration, and missing cookies or other
           authorization information. Any easy way to check this is to
-          cut&amp;paste the source URL from the fo:external-graphic into
-          the Location field of a browser <strong>on the machine where the
-          FOP process will be running</strong>.</li>
+          cut&amp;paste the source URL from the fo:external-graphic
+          into the Location field of a browser <strong>on the machine
+          where the FOP process will be running</strong>.</li>
         </ul>
         <p>Other possibilities:</p>
         <ul>
@@ -493,7 +501,7 @@ Check the following:</p>
         </p>
         <p>
           The concept is called &#8220;blind table&#8221;. The table is used for
-          pure layout reasons and not obvious in the output.
+          pure layout reasons and is not obvious in the output.
         </p>
         <p>
           An example of an image and the image caption to be kept together:
@@ -528,7 +536,7 @@ Check the following:</p>
         <p>
           Also, the <code>fo:table-with-caption</code> element is not implemented, tables
           within such an element are dropped too. FOP generates an error
-          message for this problem. The DocBook style sheets generate
+          message for this problem. Older DocBook style sheets generate
           <code>fo:table-with-caption</code> elements, so watch out.
         </p>
       </answer>