Updated FAQ with leader expansion faq.

Squished a few bugs in the documentation.


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

4 files changed, 182 insertions, 73 deletions

diff --git a/src/documentation/content/xdocs/faq.xml b/src/documentation/content/xdocs/faq.xml
index 7664a763d..bc10c39af 100644
--- a/src/documentation/content/xdocs/faq.xml
+++ b/src/documentation/content/xdocs/faq.xml
@@ -138,22 +138,21 @@
           definitions.
         </p>
         <p>
-          See also <link href="relnotes.html">release notes</link>.
+          Update your FO documents and style sheets.
         </p>
       </answer>
     </faq>
     <faq id="NoClassDefFound">
       <question>I get a NoClassDefFound exception.</question>
       <answer>
-        <p>
-          This is typically a problem with your <!--link
-            href="classpath.html"-->classpath<!--/link-->.</p>
+        <p>This is typically a problem with your classpath.</p>
         <p>If you are running FOP from the command line:</p>
         <ul>
           <li>
-            Use the fop.bat or fop.sh command file from the FOP distribution.
-            Ensure the directory where FOP and these files have been installed
-            is the current working directory.
+            Use the fop.bat or fop.sh 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.
           </li>
           <li>
             If this doesn't help, check whether still all the jar files
@@ -162,8 +161,11 @@
           </li>
         </ul>
         <p>
-          If you run FOP embedded in your servlet, web application or other
-          Java application, check the classpath of the application.
+          If you run FOP embedded in your servlet, web application or
+          other Java application, check the classpath of the
+          application. Check the also the information pertaining <link
+          href="servlets.xml#servlet-engine">servlet engines</link>
+          for further hints.
         </p>
       </answer>
     </faq>
@@ -248,7 +250,7 @@
         </p>
         <p>
           If you use XSLT, problems in your style sheet and in your source XML
-          also often produce a NullPointerException. Run the transformation
+          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.
         </p>
@@ -330,7 +332,7 @@
       <answer>
         <p>
           Did you get: &#171;Failed to read font metrics file C:\foo\arial.xml
-          : File "C:\foo\arial.xml" not found&#178;? The value for the
+          : File "C:\foo\arial.xml" not found&#187;? The value for the
           metrics-file attribute in the user config file is actually an URL, not
           a file name. Use "file:///C:/foo/arial.xml" instead.
         </p>
@@ -339,11 +341,51 @@
           directory you expect. Currently FOP does not use the baseDir for
           resolving relative URLs pointing to font metric files.
         </p>
+        <p>
+          Try also setting the fontBaseDir configuration. (FIXME: add
+          link to congfiguration page)
+        </p>
       </answer>
     </faq>
   </part>
   <part id="part-output">
     <title>Problems with FOP output</title>
+    <faq id="leader-expansion">
+      <question>Leaders don't work anymore in 0.20.5. Instead of
+      filling the line, only three dots or a short ruler is
+      output.</question>
+      <answer>
+        <p>
+          Leaders still work, in fact they work better than ever
+          before. You'll just have to add text-align="justify" and/or
+          text-align-last="justify" to the block with the leader. Be
+          sure you haven't accidentally overridden the
+          leader-length.maximum="100%" default value.
+        </p>
+        <p>
+          Earlier versions of FOP used to expand a leader to fill the
+          rest of the line unconditionally, anything following it,
+          like page numbers in a TOC, was actually shifted beyong the
+          right margin.
+        </p>
+        <p>
+          The new implementation uses leader-length.optimum to
+          determine where to break the line, and expands the leader
+          only further if the line should be filled, as indicated by
+          the text-aling and text-align-last properties.
+        </p>
+        <p>
+          Actually due to the fuzzyness of the specification both the
+          old and the new method are conformant (although adding text
+          after the expanded leader in the old variant never was).
+        </p>
+        <p>
+          If you want to have a longer ruler or space in a
+          non-justified line, you have to increase the
+          leader-length.optimum property.
+        </p>
+      </answer>
+    </faq>
     <faq id="blank-page-between-page-sequences">
       <question>Why does FOP insert a blank page between my page sequences?</question>
       <answer>
@@ -488,16 +530,16 @@ Any easy way to check this is to cut&amp;paste the source URL from the fo:extern
       <question>Page numbers are not properly right aligned.</question>
       <answer>
         <p>
-          This happens for fo:page-number-citation elements if the citation
-          occurs before FOP formatted the requested page, usually in TOC or
-          index pages.
+          This happens for fo:page-number-citation elements if the
+          citation occurs before FOP formatted the requested page,
+          usually in TOC or index pages. It is caused by the problem
+          that FOP has to guess how much space the yet unknown page
+          number will occupy, and usually the guesses are somewhat
+          off.
         </p>
         <p>
-          It is caused by the problem that FOP has to guess how much space the
-          yet unknown page number will occupy, and usually the guesses are
-          somewhat off. You can try to use a non-proportional font like Courier
-          to remedy this. However, this is likely to look ugly, and wont fix the
-          problem completely.
+          The most recent FOP releases should have this problem
+          fixed. Check whether you can upgrade.
         </p>
       </answer>
     </faq>
@@ -678,17 +720,28 @@ Can I control this?</question>
       displayed as &#8220;#&#8221;.</question>
       <answer>
         <p>
-          There are a few fonts supplied with Acrobat Reader. If you use other
-          fonts, the font must be available on the machine where the PDF is
-          viewed or it must have been embedded in the PDF file. See
-          <link href="fonts.html">embedding fonts</link>.
+          This usually means the selected font doesn't have a glyph
+          for the character.
+        </p>
+        <p>
+          The standard text fonts supplied with Acrobat Reader have
+          mostly glyphs for characters from the ISO Latin 1 character
+          set. For a variety of reasons, even those are not completely
+          guaranteed to work, for example you can't use the fi
+          ligature from the standard serif font. Check the <link
+          href="output.html#pdf-fonts">overview</link> for the default
+          PDF fonts.
+        </p>
+        <p>
+          If you use your own fonts, the font must have a glyph for
+          the desired character. Furthermore the font must be
+          available on the machine where the PDF is viewed or it must
+          have been embedded in the PDF file. See <link
+          href="fonts.html">embedding fonts</link>.
         </p>
         <p>
-          Furthermore, if you select a certain font family, the font must
-          contain glyphs for the desired character. There is an <link
-            href="output.html#pdf-fonts">overview</link> available for the
-          default PDF fonts. For most symbols, it is better to select the symbol
-          font explicitely, for example in order to get the symbol for the
+          For most symbols, it is better to select the symbol font
+          explicitely, for example in order to get the symbol for the
           mathematical empty set, write:
         </p>
         <source><![CDATA[<fo:inline font-family="Symbol">&#x2205;</fo:inline>]]></source>
@@ -915,7 +968,7 @@ Can I control this?</question>
       in the input.</question>
       <answer>
         <p>
-          See <link href="fo.html#xml-entity-chars">XML Entity Characters</link>.
+          See <link href="fo.html#xml-entity-chars">Using HTML Character Names</link>.
         </p>
       </answer>
     </faq>
diff --git a/src/documentation/content/xdocs/pdfencryption.xml b/src/documentation/content/xdocs/pdfencryption.xml
index 48873e85f..8db0446a8 100755
--- a/src/documentation/content/xdocs/pdfencryption.xml
+++ b/src/documentation/content/xdocs/pdfencryption.xml
@@ -15,13 +15,13 @@
       <warning>PDF Encryption is available in Release 0.20.5 and later. The comments on this page do not apply to releases earlier than 0.20.5.</warning>
       <p>
         FOP supports encryption of PDF output, thanks to Patrick
-        C. Lankswert. This feature is commonly used to prevent unauthorized
-        viewing, printing, editing and copying text from the document
-        annotations. It is also possible to ask the user for a password in order
-        to view the contents. Note that there already exist third party
-        applications which can decrypt an encrypted PDF without effort and allow
-        the aforementioned operations, therefore the degree of protection is
-        limited.
+        C. Lankswert. This feature is commonly used to prevent
+        unauthorized viewing, printing, editing, copying text from the
+        document and doing annotations. It is also possible to ask the
+        user for a password in order to view the contents. Note that
+        there already exist third party applications which can decrypt
+        an encrypted PDF without effort and allow the aforementioned
+        operations, therefore the degree of protection is limited.
       </p>
       <p>
         For further information about features and restrictions regarding PDF
@@ -36,13 +36,15 @@
         options.
       </p>
       <p>
-        An owner password with the <code>-o</code> option. This password is
-        actually used as encryption key. Usually it is also used by most tools
-        to disregard any restriction imposed on the PDF document.
+        An owner password is set with the <code>-o</code> option. This
+        password is actually used as encryption key. Many tools for
+        PDF processing ask for this password to disregard any
+        restriction imposed on the PDF document.
       </p>
       <p>
         If no owner password has been supplied but FOP was asked to apply some
-        restrictions, a random password is used.
+        restrictions, a random password is used. In this case it is obviously
+        impossiible to disregard restrictions in PDF processing tools.
       </p>
       <p>
         A user password, supplied with the <code>-u</code> option, will
@@ -60,13 +62,13 @@
     <section>
       <title>Environment</title>
       <p>
-        In order to use PDF encryption, FOP has to be compiled with cryptography
-        support. Currently, only <link
+        In order to use PDF encryption, FOP has to be compiled with
+        cryptography support. Currently, only <link
         href="http://java.sun.com/j2se/1.4/docs/guide/security/jce/JCERefGuide.html">JCE</link>
-        is supported. JCE is part of JDK 1.4. For earlier JDKs, it can be
-        installed separately. The build process automatically senses JCE
-        presence and installs PDF support if possible, otherwise, a stub is
-        compiled in.
+        is supported. JCE is part of JDK 1.4. For earlier JDKs, it can
+        be installed separately. The build process automatically
+        detects JCE presence and installs PDF encryption support if
+        possible, otherwise a stub is compiled in.
       </p>
       <p>
         Cryptography support must also be present at run time. In particular, a
@@ -76,7 +78,7 @@
       </p>
       <source>"Cannot find any provider supporting RC4"</source>
       <p>
-        then you don't have the needed support.
+        then you don't have the needed infrastructure.
       </p>
       <p>
         There are several commercial and a few Open Source packages which
@@ -113,6 +115,10 @@
           providers. For JDK 1.4 this is detailed on <link href="http://java.sun.com/j2se/1.4/docs/guide/security/jce/JCERefGuide.html#InstallProvider">Sun's web site</link>.
         </li>
       </ol>
+      <p>
+        If you have any experience with Mozilla JSS or any other
+        cryptography provider, please post it to the fop-user list.
+      </p>
     </section>
   </body>
 </document>
diff --git a/src/documentation/content/xdocs/servlets.xml b/src/documentation/content/xdocs/servlets.xml
index c3bbdf9d5..b3120f531 100644
--- a/src/documentation/content/xdocs/servlets.xml
+++ b/src/documentation/content/xdocs/servlets.xml
@@ -29,7 +29,7 @@
         <li>http://localhost:8080/fop/fop?xml=/home/path/to/xmlfile.xml&amp;xsl=/home/path/to/xslfile.xsl</li>
       </ul>
       <p/>
-      <p>The source code for the servlet can be found under xml-fop/examples/servlet/src/FopServlet.java.</p>
+      <p>The source code for the servlet can be found under {fop-dir}/examples/servlet/src/FopServlet.java.</p>
     </section>
     <section id="servlet">
       <title>Create your own Servlet</title>
@@ -62,9 +62,10 @@
       <section id="xslt">
         <title>Adding XSL tranformation (XSLT)</title>
         <p>
-          A common requirement is the ability to do an XSL transformation to transform some 
-          XML source to XSL-FO. It is recommended that JAXP be used for this task. The following
-          snippet shows the basic code for doing this:
+          A common requirement is the to transform an XML source to
+          XSLFO using an XSL transformation. It is recommended to use
+          JAXP for this task. The following snippet shows the basic
+          code:
         </p>
         <source>
 protected Logger log;
@@ -108,15 +109,17 @@ public void init() throws ServletException {
     response.getOutputStream().flush();</source>
         <note>
           Buffering the generated PDF in a ByteArrayOutputStream is done to avoid potential 
-          problems with the Acrobat Reader Plug-in.
+          problems with the Acrobat Reader Plug-in in IEx.
         </note>
         <p>
-          The <code>Source</code> instance used above is simply an example.
-          If you have to read the XML from a string, supply a 
-          <code>new StreamSource(new StringReader(xmlstring))</code>. Constructing and reparsing 
-          an XML string is generally less desirable than using a SAXSource if you generate your XML.
-          You can alternatively supply a DOMSource as well. 
-          You may also use dynamically generated XSL if you like.
+          The <code>Source</code> instance used above is simply an
+          example.  If you have to read the XML from a string, supply
+          a <code>new StreamSource(new
+          StringReader(xmlstring))</code>. Constructing and reparsing
+          an XML string is generally less desirable than using a
+          SAXSource if you generate your XML.  You can alternatively
+          supply a DOMSource as well.  You may also use dynamically
+          generated XSL if you like.
         </p>
         <p>
           Because you have an explicit <code>Transformer</code> object, you can also use it to 
@@ -179,20 +182,23 @@ public void init() throws ServletException {
           effect may depend on IEx version.
         </li>
         <li>
-          Give IEx the opportunity to cache. In particular, ensure the server
-          does not set any headers causing IEx not to cache the content. This
-          may be a real problem if the document is sent over HTTPS. Consult
-          your server manual.
+          Give IEx the opportunity to cache. In particular, ensure the
+          server does not set any headers causing IEx not to cache the
+          content. This may be a real problem if the document is sent
+          over HTTPS, because most IEx installations will by default
+          <em>not</em> cache any content retrieved over HTTPS.
+          Setting the <code>Expires</code> header entry may help in
+          this case:<br/> <code>response.setDateHeader("Expires",
+          System.currentTimeMillis() + cacheExpiringDuration *
+          1000);</code><br/> Consult your server manual and the
+          relevant RFCs for further details on HTTP headers and
+          caching.
         </li>
         <li>
-          Setting the <code>Expires</code> header entry may help:
-          <code>response.setDateHeader("Expires", System.currentTimeMillis() + cacheExpiringDuration * 1000);</code>
-        </li>
-        <li>
-          Cache in the server. Including a parameter in the URL which has a
-          timestamp as the value may help you to decide whether a request is
-          repeated. IEx is reported to retrieve a document up to three times,
-          but never more often.
+          Cache in the server. It may help to include a parameter in
+          the URL which has a timestamp as the value min order to
+          decide whether a request is repeated. IEx is reported to
+          retrieve a document up to three times, but never more often.
         </li>
       </ul>
     </section>
diff --git a/src/hyph/pt.xml b/src/hyph/pt.xml
index 5eaf76e3c..877932ba9 100644
--- a/src/hyph/pt.xml
+++ b/src/hyph/pt.xml
@@ -5,9 +5,53 @@
  direitos reservados. Para detalhes sobre o uso e redistribuição
  refira-se ao arquivo LICENSE que acompanha estes fontes.
 
- Copyright (C) 2001-2003 The Apache Software Foundation. All rights
- reserved. For details on use and redistribution please refer to the
- LICENSE file included with these sources.
+ * ============================================================================
+ *                    The Apache Software License, Version 1.1
+ * ============================================================================
+ * 
+ * Copyright (C) 1999-2003 The Apache Software Foundation. All rights reserved.
+ * 
+ * Redistribution and use in source and binary forms, with or without modifica-
+ * tion, are permitted provided that the following conditions are met:
+ * 
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ * 
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ * 
+ * 3. The end-user documentation included with the redistribution, if any, must
+ *    include the following acknowledgment: "This product includes software
+ *    developed by the Apache Software Foundation (http://www.apache.org/)."
+ *    Alternately, this acknowledgment may appear in the software itself, if
+ *    and wherever such third-party acknowledgments normally appear.
+ * 
+ * 4. The names "FOP" and "Apache Software Foundation" must not be used to
+ *    endorse or promote products derived from this software without prior
+ *    written permission. For written permission, please contact
+ *    apache@apache.org.
+ * 
+ * 5. Products derived from this software may not be called "Apache", nor may
+ *    "Apache" appear in their name, without prior written permission of the
+ *    Apache Software Foundation.
+ * 
+ * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES,
+ * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+ * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+ * APACHE SOFTWARE FOUNDATION OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
+ * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLU-
+ * DING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
+ * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+ * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ * ============================================================================
+ * 
+ * This software consists of voluntary contributions made by many individuals
+ * on behalf of the Apache Software Foundation and was originally created by
+ * Marcelo Jaccoud Amaral <jaccoud@petrobras.com.br>. For more information on
+ * the Apache Software Foundation, please see <http://www.apache.org/>.
 
    Tabela de hifenação FOP para o português. / FOP hyphenation table for Portuguese
    versão / version 1.0    (2002-07-01)