You are viewing a plain text version of this content. The canonical link for it is here.
Posted to fop-users@xmlgraphics.apache.org by Joerg Pietschmann <jo...@zkb.ch> on 2002/03/07 18:21:09 UTC
Re: FAQ Answers please
(Crossposted to both fop-dev and fop-user. fop-user subscribers, please
post follow-ups to fop-dev)
alex <al...@yahoo.com> wrote:
> Can anyone capture any important questions and answers which I should put
> into the FAQ?
Well questions are easy, answers somewhat less:
Here is my impression
1. FOP specific technical questions
1.1 Using FOP in a servlet. Apparently, the servlet example in the
distribution is not sufficient, but still a frist answer.
1.2 Using FOP in a servlet with an XSLT transformation
Many suboptimal answers are regulrly posted here and to the
fop-user list.
The canonical answers are, use XSLTInputHandler or TraxInputHandler
if both XML and XSL are files, or a SAX event stream if some XML
is generated on the fly or read from an network stream or such.
Code can be copied from
http://marc.theaimsgroup.com/?l=fop-dev&w=2&r=1&s=xsltinputhandler&q=b
namely
http://marc.theaimsgroup.com/?l=fop-dev&m=101232320408992&w=2
and
http://marc.theaimsgroup.com/?l=fop-dev&w=2&r=1&s=getContentHandler&q=b
unfortunately, there are various neat snippets which would have to
be combined in order to show all the possibilites.
http://marc.theaimsgroup.com/?l=fop-dev&m=100583267306925&w=2
http://marc.theaimsgroup.com/?l=fop-dev&m=100703832007931&w=2
1.3 User supplied fonts
While this is answered in the Docs, some expressive hints about what
data are file names and what are file _URLs_ could be noted again.
1.4 Embedding fonts when run from a servlet
The usual code how to get the settings from userconfig.xml, as for
example seen at
http://marc.theaimsgroup.com/?l=fop-dev&m=101421597727050&w=2
This question needs to be indexed twice, obviously.
1.5 Complaints about:
1.5.1 files not found referenced in fo:external-graphics, user fonts etc.
1.5.2 MalformedURLException, especially URIs starting with "(null)"
It should be explained
o The "file names" are URIs.
o Users should be encouraged to get familar with URI syntax (quote
web ressources, at least the RFCs).
o The correct syntax for file URIs is file:///some/path/file.ext
(on localhost, the usual case). Emphasize the triple slash.
o The resolution mechanism for relative URIs should be explained,
especially the role of baseDir.
o Note that XSL transformations and JAXP transformers have their
own mechanism for resolving relative URIs, could be redirected
to the XSLT FAQ http://www.dpawson.co.uk/xsl/xslfaq.html
1.6 Setting baseDir in userconfig.xml
1.7 Setting baseDir in a servlet environment
Either via userconfig.xml or the Configuration, code at
http://marc.theaimsgroup.com/?l=fop-dev&m=101354604124258&w=2
1.8 New VFAQ: PNG images and other formats dont (no longer) work,
Jimi library is missing
Jimi is no longer in the distribution. Explain where to get it.
1.9 NoClassDefFound (Command line)
Explain again how to set the CLASSPATH. Explain the usage of the
batch files and that they have to be started in the correct directory.
1.10 NoClassDefFound (Servlet environment), getting FOP working
for various servlet engines.
Explain classpath issues, how jar files are gathered by various
products, and possible conflicts with existing XML/XSLT libraries
Subquestions
o Tomcat 4
o Tomcat 3
o IBM Websphere
Oh, i have this at hand:
> Put a copy of a working parser in some directory where WebSphere can access
> it,
> for example, if /usr/webapps/yourapp/servlets is the classpath for your
> servlets, copy the Xerces jar into it (any other direcotry would also be
> fine)
> Do not add the jar to the servlet classpath, but add it to the classpath
> of the application server which contains your web application. In the
> WebSphere
> administration console, click on the "environment" button in the "general"
> tab
> (i have a german version so you may see different names). Fill CLASSPATH
> in the "varianble name" box and /usr/webapps/yourapp/servlets/Xerces.jar
> (or whatever your complete path is) in the value box, press "OK", then
> apply the change and restart the application server.
o Others? The mail archive is not very responsive about this today.
1.11 Method not found
Explain possible incompatibilites (XML parsers, XSLT engines, Batik).
Refer to previous question.
1.12 FOP and multithreading
FOP is not thread safe. Explain consequences.
1.13 FOP memory consumption (should be higher in the list). OutOfMemoryException.
Mention redesign effords
Suggest using multiple page sequences if possible
2. Batik/SVG specific questions
2.1 SVG text rendered in bad quality, how to put SVG text as text into PDF
That's here
http://marc.theaimsgroup.com/?l=fop-dev&m=100525846132084&w=2
Refer also to "how to use userconfig in servlets"
2.2. Batik on headless servers
Refer to Xvfb and PJA
http://marc.theaimsgroup.com/?l=fop-dev&m=101481782018662&w=2
2.3. FOP does not exit if a SVG is included
Applies to older FOP versions and JDK 1.3 and older. That's because there
is an AWT thread hanging around. The solution is to put a System.exit(0)
somewhere.
2.4. Problems with SVG referring to gradients etc. using "uri(#stuff)"
(MalformedURLException or stuff not found)
That's really a "resolving relative URI" problem (1.5) with some twists
I made some suggestions in
http://marc.theaimsgroup.com/?l=fop-dev&m=101247088010389&w=2
but didn't try anything by myself.
3. PDF specific (includes Acrobat peculiarities)
3.1. Embedding fonts.
Refer to 1.3
3.2. Characters not displayed, or displayed incorrectly, or displayed
as "#"
Answers are that fonts must be available on the target platform, and
the selected font must contain glyphs for the desired character.
For example, for most symbols, the symbol font has to be selected
explicitely (actually: is this a feature or a bug?):
<fo:inline font-family="Symbol">∅</fo:inline>
gives EMPTY SET while the same characters in the default font results
in AE LIGATURE (which happens to occupy the same place in the default
font as the EMPTY SET in the Symbol font). The "#" shows up if the
selected font does not define a glyph for the translated index.
3.3. PDF encryption, PDF protection (read-only)
Answer: use some other tool to postprocess the PDF (itext, or something?)
3.4. Watermarks
Answer: see 3.3, or use a a region overlapping the flowing text and put
an image there:
> From: Trevor_Campbell@kaz.com.au
> Use the region-before. Make it large enough to contain your image and then
> include a block (and if required an absolutely positioned block-container)
> with your image in the static-content for the region-before.
Could use some code here...
3.5. PDF (more preciese: Acrobat Reader) and IEx
See later
3.6. PDF print disturbed
Check paper size in Acrobat settings and "fit to page" (or something)
3.7. Controlling Acrobat bookmark display
Not possible with FOP. Postprocess the PDF.
4. IEx specific stuff
4.1. Servlet called multiple times.
Some suggestions
o Use a proper URL, effect may depend on IEx version.
I made some guesswork at
http://marc.theaimsgroup.com/?l=fop-dev&m=101540736828809&w=2
o Give IEx the possibility to cache
o Cache in the server
4.2. Print PDF directly from Browser
A suggestion:
http://marc.theaimsgroup.com/?l=fop-dev&m=101065988325115&w=2
There was a more complete thread earlier on this list...
5. FOP deficiencies and confusing/odd results
5.1. Keep-with-next/previous/together
Not implemented except for table rows. Nest stuff to be kept toghether
in a table.
5.2. Table content missing
Check for fo:table-body around the rows. FOP doesn't raise an error.
5.3. Error 'master-reference' for 'fo:page-sequence' matches no
'simple-page-master'
Mention change in standard. Suggest to replace "master-name" by
"master-reference".
5.4. Text overflowing table cells and the like not clipped. Long
text flows into adjacent cells/block, obscuring stuff there.
Clipping is not implemented (AFAIK)
Use wrapping and/or hyphenation. May require special processing at
XSLT level, like
o clip long text in XSLT
o explicit wrapping+clipping in XSLT (hard)
o insert zero width spaces (U+200B or ​) at XSLT level to
allow FOP to wrap
5.5. fo:page-number-citation screws right or left margin or is not
aligned as expected
This happens if the citation occurs before FOP formatted the
requested page, usually in index pages. Ought to be fixed, later.
5.6. FOP runs out of memory
See 1.13
5.7. Some graphic is not displayed
Several possibilities:
o The graphic is too large to fit.
o Some subclasses can't be handled, try to convert the graphic
in a format subclass known to work (could use list here...)
o something else obscures the graphic (very rare)
5.8. Hyphenation does not work
Set the language attribute somewhere. Check whether you use
a language for which hyphenation is supported (could use
list here...)
5.9. FOP runs forever, spitting lots of ">".
There is something too large to fit into the intended place,
usually a large image or a table whose rows are kept together
(there are more possibilities, does someone already have a complete
list?)
See also 7.3.
5.10. FOP does not terminate. FOP does not exit.
See 5.9 and 2.3
6. More general XSL questions, both XSLT and FO, and basic XML
(should be better sorted)
6.1. (FO) How to center an image or a table (or whatever)
Several different answers in the archive. I don't want to pick one.
6.2. (FO) How to get page numbers printed on the "outer side" of the page
(for books, obviously)
That's about different static content on odd/even pages, see 6.4
6.3. (FO) How to get a special header on the first page
Either insert it into the flow instead of the static part, or use
different static content on the first page, see 6.4
6.4. (FO) Different static content
The key is to define several page masters and give regions which
get static gontent individual names. There are examples in the FO
distribution and in the XSL FAQ FO section
http://www.dpawson.co.uk/xsl/sect3/index.html
6.5. (XML) Complaints about How to get non-breaking space in FO.
Use   everywhere. In you own XML, you could also use a DTD
which declares the entity.
6.6. (XML) Complaints about &<somestuff>; which used to work in HTML
Don't use names as in HTML, use numbers (unless you have a DTD
which declares the entities). For predefined HTML entities and
their Unicode codepoints see
http://www.w3.org/TR/html4/sgml/entities.html
6.7. (FO) How to get Euro sign/checkbox/some other stuff
Try to look it up in the Unicode reference at
http://www.unicode.org
namely search the reference by name
http://www.unicode.org/charts/charindex.html
Use XML character references to put it into the XML osr XSLT or FO
http://www.w3.org/TR/2000/REC-xml-20001006#sec-references
Watch out for font traps, see 3.2, change font teporarily using
fo:inline if necessary.
Alternative: Use embedded graphic: GIF, PNG, SVG, whatever.
6.8. (FO) How to keep linebreaks/hard spaces. How to get preformatted
text displayed as expected.
Use white-space="pre" or something similar on an enclosing fo:block
Details at
http://www.w3.org/TR/xsl/slice7.html#white-space
http://www.w3.org/TR/xsl/slice7.html#linefeed-treatment
http://www.w3.org/TR/xsl/slice7.html#white-space-treatment
and elsewhere.
6.9. (FO) How to get page total. How to print "page 1 of 12"
Refer to the XSL FAQ.
Canonical answer: put an empty block with an id at the end of
the flow:
<fo:block id="last-page"/>
Get the number of the last page as
<fo:page-nuber-citation ref-id="last-page"/>
6.10. (FO) Header overlaps body content. Body extends into footer.
Contrary to popular opinion, the regions on a page may overlap.
Defining a certain body region does not automatically constrain
other regions, this has to be done explicitely.
The overlap effect can be used for watermarking and similar stuff,
see 3.4
Could use example here...
6.11. (FO) How to get lines in the result?
Several possibility
o Use fo:leader (details in the spec,or use a book)
o Use some solid border on a suitable fo:block
o Insert a graphic. GIF, PNG SVG, whatever.
6.12. (XML) Complaints about illegal characters in input
Make sure ampersands are written as & and "<" is written as <
and ">" as >
The XML parser should give the proper line and possibly column for
offending characters.
See also 6.13
6.13. (XML) Complaints about illegal bytes or odd character in the
result.
Usually, this is a character encoding problem. See XSL FAQ.
7. General suggestions.
7.1. Where to post bugs
See docs. See also 7.2
7.2. Where to post questions.
Decide where to post:
o You get exceptions. First, check the FAQ whether the exception
is mentioned. Check bugzilla. If still not found, post to fop-dev
o Something doesn't work with FOP but works with another formatter
(AntennaHouse, PassiveTex), post a bug or to fop-dev
o otherwise, post to fop-user
See also 7.5
7.3 What to do if something does not work as expected. General error
searching techniques
o Is there an error message? Read it. Try to understand it. Search the
FAQ for words. It may give a clue where to start searching. Try the
next steps in any case.
o If FOP runs embedded, try the command line application with the
FO resp. XML/XSL combo. This may fail for other reasons, though.
o If the XML is generated on the fly, dump it. You can use an identity
transformer to achive this. Usually it is important to have the real
XML, not "something that hopefully looks like it".
o If the command line application produces what you expect, the
problem is in the embedding or embedding specific deployment. See
Section 1 and/or 7.4
Otherwise it's a general FOP installation problem, a problem with the
FO, the XSLT or the original XML, a FOP bug or a problem with getting
additional files. For the first, try 7.4, otherwise try the next steps.
o If you a run XSL transformation, run it separately.
(insert how to run xalan here)
If this works, feed the resulting FO file to the FOP command line
application. If this works to, check whether FOP uses the same
XSLT processor as the separate transforamtion run.
For XSLT problems, refer to the XSL FAQ
http://www.dpawson.co.uk/xsl/xslfaq.html
o If the FO (either written by yourself or produced by the last step)
contains SVG stuff, delete it (or change your XSL not to produce it).
If the problem disappears, check the SVG with another tool, like
some the SVG viewer from Batik.
o If the FO refers to external graphics, delete the references (or
change your XSL not to produce them). If the problem disappears,
check your graphics files. In order to get a clue which of your
graphics causes problems, you can produce a FO which contains only
the graphics (use a special XSL if necessary). Check whether the
problem is still there. Delete all graphics except one (the first)
and check whether the problem persists. If it disappears, reestablish
the file with all graphics and narrow it down by binary search
(delete the last half until the problem disappears, und the last
deletion and delete the first half, check whether the problem reappears,
then continue as before until you have a file with a graphic which
causes the problem.
After you have narrowed the problem, check the error. If it's an
I/O error, check read permissions, ACLs, whether FOP correctly resolves
the URL (see 1.5), and in especially case of http URIs whether the
server actually serves the image. For other problems, check it with
another appropriate tool.
o Narrow down the problem by deleting stuff from the FO file generated
earlier, or by not generating stuff until the problem disappears. Use
a XML aware editor to kill whole elements/attributes only. Undo the
last deletion and continue with deleting other stuff unless you can't
delete anything without the problem disappearing. Don't forget to
simplify your page masters. Delete as much regions as possible.
o If you still can't spot the problem cause, go to 7.2
7.4. Get a local guru for your environment. If you have to run FOP in a
servlet environment, get local or corporate support for this. Ask
specifically for integrating FOP. This may be expensive, but you
can sue them if their solution doesn't work out.
If you have trouble running the FOP command line application with
any FO file, especially the examples distributed with FOP, get the
help of a local Java guru.
If *you* are supposed to be the guru in either case, ask your boss
for a training course (Java and/or your specific environment), and/or
check amazon.com for books about Java, XML, XSL, XSLT, FO and/or your
specific environment and ask your boss for time to read them. (could
use a list here...). If your boss is uncooperative, ask yourself
whether you really want to keep the assignment... :-)
Check the list archives at
http://marc.theaimsgroup.com/?l=fop-dev&r=1&w=2
http://marc.theaimsgroup.com/?l=fop-user&r=1&w=2
http://www.biglist.com/lists/xsl-list/archives/
If you figure your english is not good enough to understand the messages
or to formulate your question properly, at least try to get local help
with this issue.
If this still doesn't give an answer, goto 7.2. Be prepared to be flamed
if your problem is already solved here :-) See also 7.5
7.5 Adhere netiquette when posting to the lists.
- Choose meaningful subjects. Do not use "Urgent" or "Help" or "Problem
with FOP"
- Do not shout (means: uppercase characters only), especially in subject
lines. This does not help you getting an answer faster.
- Expressing urgency in any way does not help you getting an answer faster.
- Do not repost a question after a short time, like half an hour. It may
take up to a few days until an answer arrives. Experts are busy. Also,
the expert you need could be reading the digest.
- State your problem clearly. See 7.6 for some standard information
you should supply.
- Use conservative spelling, punctuation, grammar and formatting. If you
figure your english is bad, at least try to get local help for
formulating the message. Gibberish and slang may decrease your chance
of getting an answer significantly.
- Use a fixed width font when composing your message. Formatting looking
ok for a message composed with a proportional font is usually screwed up
if viewed in a mail client using a fixed font, especially indentations.
There are a lot of mail clients and users out there who can't or don't
want take advantage of proportional fonts or other non-plain formattings.
A screwed formatting may decrease your chance of getting an answer
significantly.
- Don't use tabs unless really necessary. If cut&paste XML or other source
from elsewhere, try to get tabs converted to spaces. Other mail clients
and users may have different ideas of in what formatting the tabs result.
A screwed formatting may decrease your chance of getting an answer
significantly.
- There is no need to put elaborate excuses about your (lack of)
FOP/servlet/Java-related knowledge, bad spelling and formatting or bad
english at the beginning of the message. You wont gain any advantage
if your post is still badly formulated and formatted, lacks important
information, is off-topic or otherwise offensive. Get right to the point.
- Don't include or attach large files unless really necessary. Try to
narrow the problem location as described somewhere in 7.2. Especially,
don't attach any binaries. This includes images. If you have absolutely
to post an image, for example to prove a misformatting, use an image
manipulation program to cut only the relevant portion. If you don't know
how to do this, at least try to get local help. Most screen shot program
allow to select the portion of the screen to save, don't be to generous
during selection, especially don't select the complete window unless
necessary. Also, don't post complete PDF files unless necessary.
- Send XML and other source inline if possible, not as attachment. Some
mail bridges and firewalls block mails with attachments or strip them.
This is especially bad for people reading the digest.
- If replying to a post, make sure you have trimmed unnecessary text
quoted from the original message. Such text really messes up the digest,
especially if your mail client does not mark quoted text properly.
Also, remember there are people paying for traffic by volume. Yes,
your contribution matters, think about it.
7.6. Data to supply for posting problems or specific questions.
- State the version of FOP you are running, unless you know for sure this
is not relevant.
- State vendor and version of the Java environment and/or servlet engine
you are running, unless you know for sure this is not relevant.
- If you are running XSL or using SVG, state whether you are using
Xalan/Xerces/Batik from the FOP distribution (make sure this statement
is correct), or state what you use instead.
- Supply a narrowed down version of your FO/XML/XSL/java files which
produces your problem.
Regards
J.Pietschmann
Re: FAQ Answers please
Posted by Keiron Liddle <ke...@aftexsw.com>.
A big Thanks for putting this together. Hopefully this will help everyone.
Some of these questions are also answered on the website.
http://xml.apache.org/fop/
On 2002.03.07 18:21 Joerg Pietschmann wrote:
> 2. Batik/SVG specific questions
> 2.1 SVG text rendered in bad quality, how to put SVG text as text into
> PDF
This isn't quite true: the svg text is rendered as shapes the Acrobat
viewer displays it with bad quality unless you turn on smooth line art in
the Acrobat preferences.
---------------------------------------------------------------------
To unsubscribe, e-mail: fop-dev-unsubscribe@xml.apache.org
For additional commands, email: fop-dev-help@xml.apache.org