see 3.3
[prev in list] [next in list] [prev in thread] [next in thread] List: fop-dev Subject: Re: FAQ Answers please From: Joerg Pietschmann <[EMAIL PROTECTED]> Date: 2002-03-07 17:21:09 [Download message RAW] (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">∅</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 ​) 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 --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, email: [EMAIL PROTECTED] [prev in list] [next in list] [prev in thread] [next in thread] Log in / Log out | Configure Your Environment | About MARC | We're Hiring! | Want to add a list? Tell us about it. | 10East > -----Message d'origine----- > De : Harald Meyer [mailto:[EMAIL PROTECTED] > Envoyé : mercredi 17 avril 2002 15:02 > À : [EMAIL PROTECTED] > Objet : non-editable PDF > > I want FOP to generate a non-editable PDF document. How is it done? > > Thanks > Harald
