From 35f3f195bd246e1a600145a0468b183e5a5ccbe4 Mon Sep 17 00:00:00 2001 From: Joerg Pietschmann Date: Tue, 27 May 2003 00:02:42 +0000 Subject: [PATCH] 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 --- src/documentation/content/xdocs/faq.xml | 111 +++++++++++++----- .../content/xdocs/pdfencryption.xml | 42 ++++--- src/documentation/content/xdocs/servlets.xml | 52 ++++---- src/hyph/pt.xml | 50 +++++++- 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.

- See also release notes. + Update your FO documents and style sheets.

I get a NoClassDefFound exception. -

- This is typically a problem with your classpath.

+

This is typically a problem with your classpath.

If you are running FOP from the command line:

  • - 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.
  • If this doesn't help, check whether still all the jar files @@ -162,8 +161,11 @@

- 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 servlet engines + for further hints.

@@ -248,7 +250,7 @@

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.

@@ -330,7 +332,7 @@

Did you get: «Failed to read font metrics file C:\foo\arial.xml - : File "C:\foo\arial.xml" not found²? The value for the + : File "C:\foo\arial.xml" not found»? 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.

@@ -339,11 +341,51 @@ directory you expect. Currently FOP does not use the baseDir for resolving relative URLs pointing to font metric files.

+

+ Try also setting the fontBaseDir configuration. (FIXME: add + link to congfiguration page) +

Problems with FOP output + + Leaders don't work anymore in 0.20.5. Instead of + filling the line, only three dots or a short ruler is + output. + +

+ 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. +

+

+ 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. +

+

+ 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. +

+

+ 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). +

+

+ If you want to have a longer ruler or space in a + non-justified line, you have to increase the + leader-length.optimum property. +

+ + Why does FOP insert a blank page between my page sequences? @@ -488,16 +530,16 @@ Any easy way to check this is to cut&paste the source URL from the fo:extern Page numbers are not properly right aligned.

- 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.

- 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.

@@ -678,17 +720,28 @@ Can I control this? displayed as “#”.

- 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 - embedding fonts. + This usually means the selected font doesn't have a glyph + for the character. +

+

+ 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 overview for the default + PDF fonts. +

+

+ 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 embedding fonts.

- Furthermore, if you select a certain font family, the font must - contain glyphs for the desired character. There is an overview 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:

∅]]> @@ -915,7 +968,7 @@ Can I control this? in the input.

- See XML Entity Characters. + See Using HTML Character Names.

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 @@ 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.

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.

For further information about features and restrictions regarding PDF @@ -36,13 +36,15 @@ options.

- An owner password with the -o 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 -o 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.

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.

A user password, supplied with the -u option, will @@ -60,13 +62,13 @@

Environment

- In order to use PDF encryption, FOP has to be compiled with cryptography - support. Currently, only JCE - 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.

Cryptography support must also be present at run time. In particular, a @@ -76,7 +78,7 @@

"Cannot find any provider supporting RC4"

- then you don't have the needed support. + then you don't have the needed infrastructure.

There are several commercial and a few Open Source packages which @@ -113,6 +115,10 @@ providers. For JDK 1.4 this is detailed on Sun's web site. +

+ If you have any experience with Mozilla JSS or any other + cryptography provider, please post it to the fop-user list. +

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 @@
  • http://localhost:8080/fop/fop?xml=/home/path/to/xmlfile.xml&xsl=/home/path/to/xslfile.xsl

    • -

    The source code for the servlet can be found under xml-fop/examples/servlet/src/FopServlet.java.

    +

    The source code for the servlet can be found under {fop-dir}/examples/servlet/src/FopServlet.java.

    Create your own Servlet @@ -62,9 +62,10 @@
    Adding XSL tranformation (XSLT)

    - 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:

    protected Logger log; @@ -108,15 +109,17 @@ public void init() throws ServletException { response.getOutputStream().flush(); 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.

    - The Source instance used above is simply an example. - If you have to read the XML from a string, supply a - new StreamSource(new StringReader(xmlstring)). 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 Source instance used above is simply an + example. If you have to read the XML from a string, supply + a new StreamSource(new + StringReader(xmlstring)). 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.

    Because you have an explicit Transformer object, you can also use it to @@ -179,20 +182,23 @@ public void init() throws ServletException { effect may depend on IEx version.

  • - 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 + not cache any content retrieved over HTTPS. + Setting the Expires header entry may help in + this case:
    response.setDateHeader("Expires", + System.currentTimeMillis() + cacheExpiringDuration * + 1000);
    Consult your server manual and the + relevant RFCs for further details on HTTP headers and + caching.
  • - Setting the Expires header entry may help: - response.setDateHeader("Expires", System.currentTimeMillis() + cacheExpiringDuration * 1000); -
    • -
  • - 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.
    • 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 . For more information on + * the Apache Software Foundation, please see . Tabela de hifenação FOP para o português. / FOP hyphenation table for Portuguese versão / version 1.0 (2002-07-01) -- 2.39.5