(Crossposted to both fop-dev and fop-user. fop-user subscribers, please
post follow-ups to fop-dev)

alex <[EMAIL PROTECTED]> 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">&#x2205;</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: [EMAIL PROTECTED]
   > 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 &#x200B;) 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 &nbsp; How to get non-breaking space in FO.
  Use &#160; 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 &amp; and "<" is written as &lt;
  and ">" as &gt;
  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

---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, email: [EMAIL PROTECTED]

Reply via email to