From: Joerg Pietschmann Date: Sun, 5 Jan 2003 19:43:57 +0000 (+0000) Subject: Added Ant target for validating xdocs. X-Git-Tag: Alt-Design-integration-base~201 X-Git-Url: https://source.dussan.org/?a=commitdiff_plain;h=02bcdf9e5e4bd1cb011ee5169cb82f77eead68ac;p=xmlgraphics-fop.git Added Ant target for validating xdocs. Some FAQ enhancments. Minor edits to output.xml. git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk@195816 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/build.xml b/build.xml index 9a10f14af..02546bf2b 100644 --- a/build.xml +++ b/build.xml @@ -148,6 +148,7 @@ list of possible build targets. + @@ -707,4 +708,65 @@ list of possible build targets. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/documentation/content/xdocs/faq.xml b/src/documentation/content/xdocs/faq.xml index ef25c3646..9afb13754 100644 --- a/src/documentation/content/xdocs/faq.xml +++ b/src/documentation/content/xdocs/faq.xml @@ -78,9 +78,10 @@

XSLFO is an XML vocabulary that is used to specify a pagination and - other styling for page layout output. The acronym “FO” stands for + other styling for page layout output. The acronym “FO” + stands for Formatting Objects. XSLFO can be - used in conjunction with XSLT to convert + used in conjunction with XSLT to convert from any XML format into a paginated layout ready for printing or displaying.

@@ -100,9 +101,9 @@

XSLT describes the transformation of arbitrary XML input into other - XML (like XSLFO), HTML or plain text. The “T” comes from + XML (like XSLFO), HTML or plain text. The “T” comes from Transformation. For historical reasons, a - transformation is often also called a “style sheet”. + transformation is often also called a “style sheet”.

Synonyms: XSL transformation, XSL:T, XSL style sheet. @@ -147,9 +148,10 @@ My PNG images don't work.

- The Jimi image library, which is used for processing images in PNG and - other formats, was removed from the distribution for licensing - reasons. You have to download + The Jimi image library, which is by default used for processing + images in PNG and other formats, was removed from the distribution + for licensing reasons. You have to download and install it by yourself.

@@ -157,7 +159,9 @@ 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:

  • @@ -207,16 +211,23 @@

    • - Avoid forward references. Forward references cause all - pages from the page with the reference on to be held in memory until - the page with the referenced element is encountered. Common forward + Increase memory settings of the JVM, see for example the + -Xmx option. Be aware that it is usually unwise to + increase the memory allocated to the JVM beyond the amount of + physical RAM, it will significantly slow down. YMMV. +
      • +
    • + Avoid forward references. Forward references cause all pages from + the page with the reference on to be held in memory until the + page with the referenced element is encountered. Common forward references are table of contents at the beginning of the document - and the "page N of TOTAL" in footers. Forward - references may be required by the task, however, if you are getting - a memory overflow you should at least check whether this is really - as necessary as claimed. A TOC, for example, could often be placed - at the end of the document without dimishing it's value too much, - the paper can be reshuffled after printing, and you can use + and the "page N of TOTAL" in footers. + Forward references may be required by the task, however, if you are + getting a memory overflow you should at least check whether this is + really as necessary as claimed. A TOC, for example, could often be + placed at the end of the document without dimishing it's value too + much, the paper can be reshuffled after printing, and you can use bookmarks in PDF.
    • @@ -232,11 +243,6 @@ page by page, some memory allocated for other purposes could possibly be freed after the page sequence has been rendered.
      • -
    • - Increase memory settings of the JVM. Be aware that it - is usually unwise to increase the memory allocated to the JVM beyond - the amount of physical RAM, it will significantly slow down. YMMV. -

    There are also some bugs which cause FOP to go into an nonterminating @@ -281,10 +287,10 @@ resolving process, which transforms it into an absolute URL.

    -

    + @@ -302,8 +308,10 @@ whether you got them right.

    - You may find it helpful to use the validation tools to validate your -FO document. This will catch most problems, but should not be relied upon to catch all. + You may find it helpful to use the validation tools to validate your + FO document. This will catch most problems, but should not be + relied upon to catch all.

    If you use XSLT, problems in your style sheet and in your source XML @@ -368,22 +376,22 @@ FO document. This will catch most problems, but should not be relied upon to cat Relative URLs are resolved against the baseDir property of FOP. For the command line FOP application, the baseDir is the directory of the input file, either the FO file or the XML source. If FOP is used - embedded in a servlet, baseDir can be set explicitely. If - it's not set, it is usually the current working directory of the - process which runs FOP. + embedded in a servlet, baseDir can be + set explicitely. If it's not set, it is usually the current + working directory of the process which runs FOP.

    -

    + FOP does not find my fonts.

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

    @@ -399,12 +407,12 @@ FO document. This will catch most problems, but should not be relied upon to cat don't work.

    - These properties are not implemented, except for keep-with-next and - keep-with-previous on table rows. In order to take advantage of them, - you have to nest stuff to be kept together in a table. + These properties are not implemented, except on table rows. In + order to take advantage of them, you have to nest stuff to be + kept together in a table.

    - The concept is called “blind table”. The table is used for + The concept is called “blind table”. The table is used for pure layout reasons and not obvious in the output.

    @@ -494,7 +502,19 @@ FO document. This will catch most problems, but should not be relied upon to cat A graphic is not displayed.

    - Several possibilities: + The most common reason is that the file is not found because + of an empty or wrong baseDir setting, spelling errors in the + file name, in particular using the wrong case, or, if the + image is retrieved over HTTP, the image was not delivered because + of security settings in the server, missing cookies or other + authorization information or other server misconfigurations. + One way to check this is to cut&paste the source URL + from the fo:external-graphic into the Location field of + a browser on the machine where the FOP process + will be running. +

    +

    + Several other possibilities:

    • @@ -510,9 +530,9 @@ FO document. This will catch most problems, but should not be relied upon to cat content (very rare, but has happened).
    -

    + @@ -527,7 +547,7 @@ FO document. This will catch most problems, but should not be relied upon to cat - Embedding FOP. Using FOP in a servlet + Embedding FOP. Using FOP in a servlet. How do I use FOP in a servlet? @@ -546,8 +566,8 @@ driver.run(); with IEx and view it later. There are other problems with this code.

    - Please look into Howto embed FOP in a servlet for all - kinds of details. + Please look into Embedding FOP + for all kinds of details.

    @@ -793,8 +813,8 @@ transformer.transform(xmlsource, new SAXResult(driver.getContentHandler())); - Problems with SVG referring to gradients etc. using - "uri(#stuff)" (MalformedURLException or stuff not found) + I have problems with SVG referring to gradients etc. using + "uri(#stuff)". I get a MalformedURLException.

    This is really a "resolving relative URI" problem with some @@ -852,40 +872,109 @@ transformer.transform(xmlsource, new SAXResult(driver.getContentHandler())); - Characters not displayed, or displayed incorrectly, or displayed - as "#" - -

    Answers are that fonts must be available for the output format, and - the selected font must contain glyphs for the desired character. -PDF has a set of defined fonts, other fonts can be embedded following the -instructions. -To find out if the characters you need are in the core fonts then -(todo - find a glyph font table for the fonts). -

    -

    For example, for most symbols, the symbol font has to be selected - explicitely (in future it should be possible to specify a list of fonts -where it will select the font for the specified character): -

    -

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

    + Some characters are not displayed, or displayed incorrectly, or + 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. +

    +

    + 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 + mathematical empty set, write: +

    + ∅]]> +

    + The "#" shows up if the selected font does not define a glyph for the + required character, for example if you try: +

    + ∅]]>     What tools are available for post-processing my PDF document?
      -
    • The most popular one that we are aware of is iText, which has tools for adding security features, document properties, watermarks, and many other features to PDF files. See also Joerg Pietschmann's posting on PDF Encryption for an example of Java application using iText.
      • -
    • You can use Adobe Acrobat (the full version, not the Reader) to process the file manually or with scripting that it supports.
      • +
    • + The most popular one that we are aware of is iText, which has tools + for adding security features, document properties, watermarks, and + many other features to PDF files. FOP and iText can be integrated + into one Java application, see sample code for encryption. + The bad news is that iText swallows PDF bookmarks. +
      • +
    • + You can use Adobe Acrobat (the full version, not the Reader) to + process the file manually or with scripting that it supports. +
    - - How do I add security features (encryption, for example) to my PDF document? - -

    FOP does not currently support this feature. Possible workarounds include those mentioned in the PDF Post-Processing FAQ.

    + + How do I add security features (encryption, disable printing) to my PDF document? + +

    + FOP does not currently support this feature. Possible workarounds + include those mentioned in the PDF + Post-Processing FAQ. +

    +

    + Some sample code for encrypting a FOP generated PDF with iText to + get you started: +

    + +

    + Check the iText tutorial and documentation for setting access flags, + password, encryption strength and other parameters. +

    @@ -899,27 +988,46 @@ where it will select the font for the specified character):

    FOP does not currently support this feature. Possible workarounds:

      -
    • See the PDF Post-Processing FAQ.
      • -
    • (submitted by Trevor_Campbell@kaz.com.au) Place an image in a region that overlaps the flowing text. For example, make region-before large enough to contain your image. Then include a block (if necessary, use an absolutely positioned block-container) containing the watermark image in the static-content for the region-before.
      • +
    • + Use a background image for the body region. +
      • +
    • + See the PDF Post-Processing + FAQ. +
      • +
    • + (submitted by Trevor_Campbell@kaz.com.au) Place an image in a + region that overlaps the flowing text. For example, make + region-before large enough to contain your image. Then include + a block (if necessary, use an absolutely positioned + block-container) containing the watermark image in the + static-content for the region-before. + Note that the image will be drawn on top of the normal content. +
    - PDF prints contorted - -

    Check paper size in Acrobat settings and "fit to page" (or something)

    -     -     - - Controlling Acrobat bookmark display + The PDF is printed contorted! -

    Not possible with FOP. Postprocess the PDF.

    +

    + Check the paper size in Acrobat settings and the "fit to page" print + setting. Contorted printing is often caused by a mismatched paper + format, for example if the setting is "US Letter" but the PDF was made + for A4. + Sometimes also the printer driver interferes, check its settings + too. +

    - PDF (more precise: Acrobat Reader) and IEx + How do I control the Acrobat bookmark display? -

    see #later

    +

    + FOP does not currently support this feature. Possible workarounds + include those mentioned in the PDF + Post-Processing FAQ. +

    @@ -934,7 +1042,7 @@ where it will select the font for the specified character):

    • - Use a URL ending in .pdf, like + Use an URL ending in .pdf, like http://myserver/servlet/stuff.pdf. Yes, the servlet can be configured to handle this. If the URL has to contain parameters, try to have both the base URL as well as the last parameter end in @@ -966,7 +1074,7 @@ where it will select the font for the specified character):

      For the first problem, look at the print servlet in the FOP - examples. You'll have to gather any printer settings in an HTML form + examples. You'll have to gather any printer settings in a HTML form and send it to the server.

      @@ -1196,21 +1304,35 @@ where it will select the font for the specified character): - (FO) How to get Euro sign/checkbox/some other stuff + (FO) How do I print an Euro sign, a checkbox or other some other + special symbols?

      - Try to look it up in the Unicode reference at the Unicode Consortium, in particular search the reference by - name. Use . +

      +

      + Use XML character references to put the character into your source XML, XSLT or FO.

      - Watch out for font traps, see #, change font temporarily using - fo:inline if necessary. + For example, the following will result in an Euro sign: +

      + +

      + The selected font family must have a glyph for the character you want + to show. This is actually a somewhat tricky issue, especially for + symbol characters. +

      +

      + Some environments provide also a character table utility (like Win2K + or WinXP), which can also help you to get an idea what glyphs are + available in a certain font.

      Alternative: Use an embedded graphic: GIF, PNG, SVG, whatever. @@ -1218,8 +1340,8 @@ where it will select the font for the specified character): - (FO) How do I keep linebreaks/hard spaces? How do I get - preformatted text displayed as expected. + (FO) How do I keep linebreaks and hard spaces? How do I get + preformatted text displayed as expected?

      The specification provides some properties for this:

      - (XSL FAQ) + This is an XSL FAQ.

      Put an empty block with an id at the end of the flow:

      - ... + ... - ]]> +]]>

      Get the number of the last page as follows:

      @@ -1310,7 +1432,7 @@ class rendtest { (FO) The header overlaps body content. The body extends into - footer. + the footer.

      Contrary to popular opinion, the regions on a page may overlap. @@ -1355,13 +1477,26 @@ class rendtest { (FO) How do I validate my FO document? -

      RenderX has provided an Unofficial DTD for FO Documents. This document may be helpful in validating general FO issues.

      -

      FOP also maintains an Unofficial FOP Schema in the FOP CVS Repository. This document can be used either to validate against the FO standard, or against the actual FOP implementation. See the notes near the beginning of the document for instructions on how to use it.

      +

      + RenderX has provided an + Unofficial + DTD for FO Documents. This document may be helpful in + validating general FO issues. +

      +

      + FOP also maintains an Unofficial + FOP Schema in the FOP CVS Repository. This document can be + used either to validate against the FO standard, or against the + actual FOP implementation. See the notes near the beginning of the + document for instructions on how to use it. +

      - (XML) Complaints about &nbsp;. How do I get a non-breaking - space in FO? + (XML) There are complaints about &nbsp;. How + do I get a non-breaking space in FO?

      Use &#160; everywhere. In your own XML, you could also use a DTD @@ -1371,8 +1506,8 @@ class rendtest { (XML) There are complaints about undefined entities, for example - complaints about &uuml; which used to work in HTML. How do I enter - special characters like in HTML? + about &uuml; which used to work in HTML. How do I enter + special characters like in HTML?

      Don't use names as in HTML, use numbers (unless you have a DTD which @@ -1397,7 +1532,8 @@ class rendtest { offending characters.

      - Refer to the XML specification or to a good tutorial for + Refer to the XML + specification or to a good tutorial for details of the XML file format.

      @@ -1412,19 +1548,20 @@ class rendtest { packages producing XML, in particular most XSLT processors, produce by default UTF-8 encoded files. If you view them with something not aware of the encoding, like Notepad for Win95/98/ME/NT, funny characters are - displayed. A Å is a giveaway. + displayed. A Å is a giveaway.

      - General suggestions. How to solve problems + General suggestions. How to solve problems. - Where to post bugs + Where to post bugs.

      - See docs. See also "where to post - questions". + See documentation. See also + "where to post + questions".

      @@ -1439,7 +1576,7 @@ class rendtest { You get exceptions. First, check the FAQ whether the exception is mentioned. ClassNotFoundException, NoSuchMethodException and NoSuchFieldException problems are almost always a problem with the - local environment. Check bugzilla. If still not found, post to fop-dev.
      • @@ -1459,17 +1596,21 @@ class rendtest { XSLT specific stuff sould go to the XSL list. This includes problems with the language and XSLT - How-Tos. + HOW-TOs.
    • Problems specific to a certain XSLT processor, like Xalan, Saxon or MSXML, should be handled by processor specific lists. This includes problems with deployment, processor specific extensions, suspected - bugs and processor specific APIs. + bugs and processor specific APIs. Note that JDK 1.4 comes with an + XML parser and an XSLT processor which are older versions of + Xerces and Xalan, respectively, and both have a number of annoying + bugs. See $$$FIXME on how to use more recent versions or other + packages instead.
    • Problems with servlet containers should be asked on the vendor - specific lists for these software packets. + specific lists for these software packages.
    • More general questions regarding Java, including deployment, Java diff --git a/src/documentation/content/xdocs/output.xml b/src/documentation/content/xdocs/output.xml index 4af6ac7c6..69a01863c 100644 --- a/src/documentation/content/xdocs/output.xml +++ b/src/documentation/content/xdocs/output.xml @@ -41,7 +41,7 @@ output format and associated data and flow. Fonts and Layout - some formats (eg. PDF and AWT) rely on different font information. The fonts for these outputs have different sizes for the same point size. This means that the layout can be quite -different for the same fo document. +different for the same FO document.

      DPI - This is an important issue when creating output for printing. @@ -51,13 +51,13 @@ images and the rendering of certain graphics in the output. Currently FOP uses a value of 72dpi.

      -You may want to send your output directly to a printer. The Print -renderer uses the java api to print the document or you might be +You may want to send your output directly to a printer. The print +renderer can use the Java API to print the document. You might also be able to send the output stream directly to a printer. If your printer supports postscript you could send the postscript to the printer. If you have a printer that supports PCL you could stream the PCL document to your printer. -On Windows: +On Windows, you can use:

      @@ -66,8 +66,8 @@ On UNIX:

      -And give the OutputStream (out) to the PCLRenderer and it happily sends the -PCL to the AIX print queue. +Set the OutputStream (out) to the PCLRenderer and it happily sends the +PCL to the UNIX printer queue.