| 1 | Welcome to Idiom FO output for the DITA Open Toolkit
|
|---|
| 2 | ======================================================
|
|---|
| 3 |
|
|---|
| 4 | Apache FOP (Formatting Objects Processor) is a print formatter driven
|
|---|
| 5 | by XSL formatting objects (XSL-FO) and an output independent formatter.
|
|---|
| 6 | It is a Java application that reads a formatting object (FO) tree and
|
|---|
| 7 | renders the resulting pages to a specified output. Output formats
|
|---|
| 8 | currently supported include PDF, PS, PCL, AFP, XML (area tree representation),
|
|---|
| 9 | Print, AWT and PNG, and to a lesser extent, RTF and TXT. The primary
|
|---|
| 10 | output target is PDF.
|
|---|
| 11 |
|
|---|
| 12 | Installing Idiom FO output
|
|---|
| 13 | =========================================
|
|---|
| 14 |
|
|---|
| 15 | * If you are using a full-easy-install package, you don't need to do additional
|
|---|
| 16 | work to run pdf conversion. Just use the pdf transtype to build your pdf output.
|
|---|
| 17 |
|
|---|
| 18 | * If you are NOT using a full-easy-install package, some additional efforts are
|
|---|
| 19 | needed to get pdf conversion run. You will need the following software:
|
|---|
| 20 |
|
|---|
| 21 | - Apache FOP: Apache FOP can be obtained from http://xmlgraphics.apache.org/fop/
|
|---|
| 22 | This plugin also requires Saxon 6.5.3. But if you are using JDK 1.5 or
|
|---|
| 23 | newer, you will need Saxon 6.5.5 or newer which has fixes for JDK 1.5
|
|---|
| 24 | compatibility. Download Saxon 6.5.5 from http://saxon.sourceforge.net.
|
|---|
| 25 |
|
|---|
| 26 | - ICU4J: You can find this library by clicking on the "Download ICU" link
|
|---|
| 27 | at http://icu.sourceforge.net. Look for the ICU4J downloads. ICU4J is
|
|---|
| 28 | an optional jar that will give you better collation of index entries.
|
|---|
| 29 |
|
|---|
| 30 | To install and use with the Open Toolkit's distribution,
|
|---|
| 31 |
|
|---|
| 32 | 1. Install the DITA Open Toolkit.
|
|---|
| 33 | 2. Unzip this plugin into an Open Toolkit installation's
|
|---|
| 34 | demo directory.
|
|---|
| 35 | 3. Install Apache FOP into demo/fo/fop. The minimum requirements are to place
|
|---|
| 36 | fop.jar into demo/fo/fop/build/ and all library jar files provided in Apache
|
|---|
| 37 | FOP package into demo/fo/fop/lib/.
|
|---|
| 38 | 4. Copy "fop.xconf", which is shipped together within the Apache FOP package
|
|---|
| 39 | in the conf directory, to demo/fo/fop/conf/.
|
|---|
| 40 | 5. Edit the copied fop.xconf, add this line:
|
|---|
| 41 | <strict-validation>false</strict-validation>
|
|---|
| 42 | below the line "<base>.</base>". Save and close fop.xconf.
|
|---|
| 43 | 6. If you are using JDK 1.5, install saxon.jar in FO plug-in's library directory demo/fo/lib/.
|
|---|
| 44 | 7. Install the ICU4j jar (optional) into OT's library directory lib/icu4j.jar
|
|---|
| 45 | 8. From the Open Toolkit directory, run "ant -f integrator.xml"
|
|---|
| 46 |
|
|---|
| 47 | At this point, the FO output is fully integrated into the Open
|
|---|
| 48 | Toolkit's pipeline. The plugin infrastructure will detect the FO
|
|---|
| 49 | plugin and provide a "pdf" output: this will invoke this FO
|
|---|
| 50 | output instead of the previous FOP-based output. Invoke with a command
|
|---|
| 51 | line like:
|
|---|
| 52 |
|
|---|
| 53 | java -jar lib/dost.jar /i:doc/DITA-readme.ditamap /transtype:pdf
|
|---|
| 54 |
|
|---|
| 55 | If you are using the startcmd.bat/sh script, make sure the classpath in that
|
|---|
| 56 | script lists saxon.jar before xalan.jar.
|
|---|
| 57 |
|
|---|
| 58 | About the index extensions
|
|---|
| 59 | ==========================
|
|---|
| 60 |
|
|---|
| 61 | The index generation feature adds extensions to DITA's indexterm that can be
|
|---|
| 62 | expressed as content of that element. These extensions are expressed in a
|
|---|
| 63 | FrameMaker-like syntax in the element's textual content, and provide
|
|---|
| 64 | functionality not yet available in the standard indexterm element. They also
|
|---|
| 65 | help migration from legacy FrameMaker content. For example, the following
|
|---|
| 66 | generates a "see also" entry:
|
|---|
| 67 |
|
|---|
| 68 | <indexterm>Carp:<$nopage>see also Goldfish</indexterm>
|
|---|
| 69 |
|
|---|
| 70 | As:
|
|---|
| 71 |
|
|---|
| 72 | Carp, 34
|
|---|
| 73 | see also Goldfish
|
|---|
| 74 |
|
|---|
| 75 | The extended syntax consists of:
|
|---|
| 76 |
|
|---|
| 77 | : (colon) Separates levels in an entry
|
|---|
| 78 | ; (semicolon) Separates entries in a marker
|
|---|
| 79 | [] (brackets) Specifies a special sort order for the entry
|
|---|
| 80 | <$startrange> Indicates the beginning of a page range
|
|---|
| 81 | <$endrange> Indicates the end of a page range
|
|---|
| 82 | <$nopage> Suppresses the page number in the entry (for example, in
|
|---|
| 83 | a See entry)
|
|---|
| 84 | <$singlepage> In a marker that contains several entries, restores the
|
|---|
| 85 | page number for an entry that follows a <$nopage>
|
|---|
| 86 | building block
|
|---|
| 87 |
|
|---|
| 88 | DITA 1.1 indexing elements have been implemented in this plugin that
|
|---|
| 89 | should make these extensions unnecessary. You can now express see/see
|
|---|
| 90 | also, sort order and page ranges using standard DITA 1.1 elements.
|
|---|
| 91 |
|
|---|
| 92 | About /Customization
|
|---|
| 93 | ====================
|
|---|
| 94 |
|
|---|
| 95 | This directory is where the custom files live that make up customized
|
|---|
| 96 | versions of the FO publishing outputs. Idiom's FO publishing output will
|
|---|
| 97 | look for certain files here to override the standard ones. Things you can
|
|---|
| 98 | currently override include:
|
|---|
| 99 |
|
|---|
| 100 | - Custom XSL via fo/xsl/custom.xsl and fo/attrs/custom.xsl
|
|---|
| 101 | - Layout overrides via fo/layout-masters.xml
|
|---|
| 102 | - Font overrides via fo/font-mappings.xml
|
|---|
| 103 | - Per-locale variable overrides via common/vars/[locale].xml
|
|---|
| 104 | - I18N configuration via fo/i18n/[locale].xml
|
|---|
| 105 | - Index configuration via fo/index/[locale].xml
|
|---|
| 106 |
|
|---|
| 107 | When customizing any of these areas, modify the relevant file(s) in
|
|---|
| 108 | /Customization. Then, to enable the changes in the publishing process,
|
|---|
| 109 | you find the corresponding entry for each file you modified in
|
|---|
| 110 | /Customization/catalog.xml. It should look like this:
|
|---|
| 111 |
|
|---|
| 112 | <!--uri name="cfg:fo/attrs/custom.xsl" uri="fo/attrs/custom.xsl"/-->
|
|---|
| 113 |
|
|---|
| 114 | Remove the comment markers "!--" and "--" to enable the change:
|
|---|
| 115 |
|
|---|
| 116 | <uri name="cfg:fo/attrs/custom.xsl" uri="fo/attrs/custom.xsl"/>
|
|---|
| 117 |
|
|---|
| 118 | Your customization should now be enabled as part of the publishing process.
|
|---|
| 119 |
|
|---|
| 120 | Idiom has provided template files that you can start with throughout
|
|---|
| 121 | this directory structure. These files end in the suffix ".orig" (for
|
|---|
| 122 | example, "catalog.xml.orig"). To enable these files, make a copy of
|
|---|
| 123 | them and remove the ".orig" suffix. For example, copy
|
|---|
| 124 | "catalog.xml.orig" to "catalog.xml". You can then make modifications
|
|---|
| 125 | to the copy.
|
|---|
| 126 |
|
|---|
| 127 | Idiom's FO output also provides a general configuration file called
|
|---|
| 128 | "build.properties" that allows you to control the publishing process.
|
|---|
| 129 | To modify these settings, copy "build.properties.orig" to
|
|---|
| 130 | "build.properties" and then modify the relevant options.
|
|---|
| 131 |
|
|---|
| 132 | History
|
|---|
| 133 | =======
|
|---|
| 134 |
|
|---|
| 135 | FO Plugin Release 1.4.3
|
|---|
| 136 | Available since
|
|---|
| 137 |
|
|---|
| 138 | Sourceforge bug fixes:
|
|---|
| 139 | - 1803111: Idiom plug fails when processing bookmap with DITA composite
|
|---|
| 140 | - 1930201: FO 1.4.2 doesn't fail correctly when called from Ant
|
|---|
| 141 | - 1829816: Value of otherprops is written as a text element
|
|---|
| 142 | - 1942252: <notices> should come before TOC in PDF output
|
|---|
| 143 |
|
|---|
| 144 | ----------------------------------------------------------------------------
|
|---|
| 145 |
|
|---|
| 146 | FO Plugin Release 1.4.2
|
|---|
| 147 | Available since Feb 26, 2008
|
|---|
| 148 |
|
|---|
| 149 | - Misc internal fixes.
|
|---|
| 150 |
|
|---|
| 151 | Sourceforge bug fixes:
|
|---|
| 152 | - 1710233: summary element in bookmeta not handled properly (15251)
|
|---|
| 153 | - 1744350: Navtitle not supported in PDF2
|
|---|
| 154 | - 1807277: FO topicmerge needs to discard reltables
|
|---|
| 155 |
|
|---|
| 156 | ----------------------------------------------------------------------------
|
|---|
| 157 |
|
|---|
| 158 | FO Plugin Release 1.4.1
|
|---|
| 159 | Available since Oct 5, 2007
|
|---|
| 160 |
|
|---|
| 161 | - more flexible index configuration (see common/index/zh_CN.xml for example)
|
|---|
| 162 |
|
|---|
| 163 | Sourceforge bug fixes:
|
|---|
| 164 | - 1793307: issue with topicref in bookmap's <notices> (16587)
|
|---|
| 165 | - 1791403: invalid column-width attribute value (16586)
|
|---|
| 166 | - 1805389: XSLT errors in FO plugin
|
|---|
| 167 | - 1694607: Use-by-reference footnotes not rendered correctly (15249), (not quite right).
|
|---|
| 168 |
|
|---|
| 169 | ----------------------------------------------------------------------------
|
|---|
| 170 |
|
|---|
| 171 | FO Plugin Release 1.4
|
|---|
| 172 |
|
|---|
| 173 | - Rebased with Idiom's internal code as of August 28, 2007.
|
|---|
| 174 | - Updated DITA 1.1 support: new bookmap and indexing elements.
|
|---|
| 175 | - Minor fixes
|
|---|
| 176 |
|
|---|
| 177 | Sourceforge bug fixes:
|
|---|
| 178 | - 1686323: Idiom FO plug-in fails during pdf2 build (15348)
|
|---|
| 179 | - 1729594: Topichead not supported in pdf2 output (15247)
|
|---|
| 180 | - 1647267: Single-step tasks numbers the step (15248)
|
|---|
| 181 |
|
|---|
| 182 | ----------------------------------------------------------------------------
|
|---|
| 183 |
|
|---|
| 184 | FO Plugin Release 1.2.1
|
|---|
| 185 |
|
|---|
| 186 | - rebased with Idiom's internal code as of Nov 6, 2006.
|
|---|
| 187 | - updated copyright/licensing notices in files.
|
|---|
| 188 | - fixed image copying task for customization.
|
|---|
| 189 |
|
|---|
| 190 | Sourceforge bug fixes:
|
|---|
| 191 | - 1574115: Using 1.3 and Idiom FO 1.2 plugin fail
|
|---|
| 192 | - 1523653: pdf2 transform assumes basedir = ditadir (for real, this time!)
|
|---|
| 193 |
|
|---|
| 194 | ----------------------------------------------------------------------------
|
|---|
| 195 |
|
|---|
| 196 | FO Plugin Release 1.2
|
|---|
| 197 | Available since Sept 29, 2006
|
|---|
| 198 |
|
|---|
| 199 | - rebased with Idiom's internal code as of Sept 28, 2006
|
|---|
| 200 | - removed icu4j requirement: it will be used if found, otherwise the built-in
|
|---|
| 201 | Java Collator will be used.
|
|---|
| 202 | - some preliminary DITA 1.1 support. No point going into details since the
|
|---|
| 203 | standard is still in flux.
|
|---|
| 204 |
|
|---|
| 205 | Bug fixes (IDs are Idiom's internal tracking numbers):
|
|---|
| 206 | - 11492: image sometimes indented too far right
|
|---|
| 207 | - 11625: footnote text's formatting not rendered
|
|---|
| 208 | - 10955: tables with titles should be numbered sequentially
|
|---|
| 209 | - 11273: table col span @namest/@nameend not respected
|
|---|
| 210 | - 11432: <p> tag should be formatted according to enclosing tag
|
|---|
| 211 | - 10849: nested codeblocks misrendered
|
|---|
| 212 | - 10755: NullPointerException processing <dita> elements
|
|---|
| 213 |
|
|---|
| 214 | Sourceforge bug fix:
|
|---|
| 215 | - 1523653: pdf2 transform assumes basedir = ditadir
|
|---|
| 216 |
|
|---|
| 217 | ----------------------------------------------------------------------------
|
|---|
| 218 |
|
|---|
| 219 | FO Plugin Release 1.1
|
|---|
| 220 | Available since June 15, 2006
|
|---|
| 221 |
|
|---|
| 222 | - rebased with Idiom's internal build 8.0.1.1.7
|
|---|
| 223 | - improved performance for documents with many xrefs/links, such as the
|
|---|
| 224 | DITA Language Reference
|
|---|
| 225 | - fixed indexterm in topicmeta bug
|
|---|
| 226 | - fixed topicmerge issues that affected (among other things) chapter
|
|---|
| 227 | division rendering for bookmaps
|
|---|
| 228 | - misc bug fixes
|
|---|
| 229 |
|
|---|
| 230 | ----------------------------------------------------------------------------
|
|---|
| 231 |
|
|---|
| 232 | FO Plugin release 1.0
|
|---|
| 233 | Available since Feb. 23, 2006
|
|---|
| 234 |
|
|---|
| 235 | - first release of Idiom's open source donation.
|
|---|
| 236 |
|
|---|
| 237 | ============================================================================
|
|---|
| 238 |
|
|---|
| 239 | Copyright ?2005 by Idiom Technologies, Inc. All rights reserved.
|
|---|
| 240 | IDIOM is a registered trademark of Idiom Technologies, Inc. and WORLDSERVER
|
|---|
| 241 | and WORLDSTART are trademarks of Idiom Technologies, Inc. All other
|
|---|
| 242 | trademarks are the property of their respective owners.
|
|---|
| 243 |
|
|---|
| 244 | IDIOM TECHNOLOGIES, INC. IS DELIVERING THE SOFTWARE "AS IS," WITH
|
|---|
| 245 | ABSOLUTELY NO WARRANTIES WHATSOEVER, WHETHER EXPRESS OR IMPLIED, AND IDIOM
|
|---|
| 246 | TECHNOLOGIES, INC. DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
|
|---|
| 247 | BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
|
|---|
| 248 | PURPOSE AND WARRANTY OF NON-INFRINGEMENT. IDIOM TECHNOLOGIES, INC. SHALL NOT
|
|---|
| 249 | BE LIABLE FOR INDIRECT, INCIDENTAL, SPECIAL, COVER, PUNITIVE, EXEMPLARY,
|
|---|
| 250 | RELIANCE, OR CONSEQUENTIAL DAMAGES (INCLUDING BUT NOT LIMITED TO LOSS OF
|
|---|
| 251 | ANTICIPATED PROFIT), ARISING FROM ANY CAUSE UNDER OR RELATED TO OR ARISING
|
|---|
| 252 | OUT OF THE USE OF OR INABILITY TO USE THE SOFTWARE, EVEN IF IDIOM
|
|---|
| 253 | TECHNOLOGIES, INC. HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
|
|---|
| 254 |
|
|---|
| 255 | Idiom Technologies, Inc. and its licensors shall not be liable for any
|
|---|
| 256 | damages suffered by any person as a result of using and/or modifying the
|
|---|
| 257 | Software or its derivatives. In no event shall Idiom Technologies, Inc.'s
|
|---|
| 258 | liability for any damages hereunder exceed the amounts received by Idiom
|
|---|
| 259 | Technologies, Inc. as a result of this transaction.
|
|---|
| 260 |
|
|---|
| 261 | These terms and conditions supersede the terms and conditions in any
|
|---|
| 262 | licensing agreement to the extent that such terms and conditions conflict
|
|---|
| 263 | with those set forth herein.
|
|---|
