Understanding and Configuring the FO Plug-in for Generating PDF Files: Part I (Beginner Level)

Understanding and Configuring the FO Plug-in for Generating PDF Files Part I (Beginner Level) Adena Frazer Suite Solutions

Who am I? Background in Computer Science and Education Experience in several computer companies over the past decade+ Web applications Telecommunications Early member of the Suite Solutions team Various webinars and on-site training seminars in Boston and Santa Clara PDF and HTML style sheet projects FO plug-in support for PDF output Project Management

What is Suite Solutions? Our Mission To increase our customers’ profitability by significantly improving the efficiency of their information development and delivery processes. Qualitative Advantage Content Lifecycle Implementation (CLI) is Suite Solutions’ comprehensive approach – from concept to publication – to maximizing the value of your information assets. Our professionals are with you at every phase, determining, recommending and implementing the most cost-effective, flexible and long term solution for your business.

Overview of FO Plug-in Main Topics Overview of PDF Generation Introduction to the FO Plug-in Customizing the FO Plug-in

DITA-OT Components DOST.jar XSL Transforms XSL style sheets Pre-process General processing Transform to output format (xhtml, fo) XSLT Engines SAXON XALAN Apache ANT Batik.jar (FOP) Resolver.jar (resolves DTD) Icu4j.jar (internationalization) Fop.jar XML Parser XERCES

PDF Generation XSL style sheets dita2pdf XSLT Engine SAXON XALAN Merged XML file generated from all referenced topics FO file XSL-FO Rendering Engine Antenna House RenderX Apache FOP Final PDF Output

Intermediate Files (1) DITA files _MERGED.xml stage1.xml stage2.fo The Plug-in creates intermediate files in the process of rendering a PDF Ditamaps are resolved and DITA files are pulled into one XML file Index preprocessing Style sheets are applied

Intermediate Files (2) stage2.fo stage3.fo topic.fo .pdf Internationalization preprocessing Internationalization postprocessing FO document is converted to a PDF File using an XSL-FO rendering engine

Using the Intermediate Files The style sheets are applied to stage1.xml during PDF rendering. All XPATH and related code should be written with this in mind. Debug style sheet issues by opening up stage1.xml to see to what XML the style sheets are being applied. Location of Intermediate Files Topic.fo is created in the output directory The other intermediate files ( _MERGED.xml, stage1.xml, stage2.fo, stage3.fo ) are created in the temp directory. By default, the intermediate files are deleted by the Toolkit They can be retained by telling the plug-in not to delete these files

Retaining the Intermediate Files In older versions of the toolkit, comment out the deletion code from demo/fo/build.xml. In newer versions of the toolkit, use parameters to prevent the deletion of these files Retain.topic.fo – Set to “yes” to retain the topic.fo file Clean.temp – set to “no” to retain the other intermediate files

Why use the FO Plug-in? Legacy PDF code is deprecated Plug-in provides for increased functionality Index and TOC generation Characters can be remapped to different fonts Extensive customization of publishing output by setting variables and attribute-sets A catalog-based customization framework where you can customize variables, attribute-sets and XSL files without modifying toolkit code: your custom settings live in files in a separate customization hierarchy Bookmap support See c:ditaot\demo\fo\readme.txt for more details

PDF Transtypes In older versions of the toolkit, PDF processing is included in the toolkit without a plug-in. There is also an option to install the FO Plug-in for greater functionality. PDF transtype references the old pdf code PDF2 transtype references the FO Plug-in code. In recent versions of the toolkit, the FO Plug-in code has become the default code for PDF processing. PDF transtype references the FO Plug-in code. ( PDF2 has been retained for backwards compatibility). The legacypdf transtype references the old PDF code.

FO Plug-in Directory Structure

Document Components (1) Front Matter (Title Page) front-matter.xsl, front-matter-attr.xsl Table of Contents (TOC) toc.xsl, toc-attr.xsl Static Content (includes footers and headers) static-content.xsl, static-content-attr.xsl Links (includes reltables) links.xsl, links-attr.xsl Index index.xsl, index_1.0.xsl, index-attr.xsl Bookmarks bookmarks.xsl, bookmarks_1.0.xsl, bookmarks-attr.xsl Layout Information layout-masters.xsl (new in v1.4.3!), layout-masters.xml

Document Components (2) Body Content Formatting Programming Domain pr-domain.xsl, pr-domain-attr.xsl Software Domain sw-domain.xsl, sw-domain-attr.xsl User Interface (includes menu cascade) ui-domain.xsl, ui-domain-attr.xsl Highlighting Domain (includes bold and italics) hi-domain.xsl, hi-domain-attr.xsl Titles commons.xsl, commons-attr.xsl Lists lists.xsl, lists-attr.xsl Tables (includes Definition Lists) tables.xsl, tables_1.0.xsl, tables-attr.xsl

Basic-settings.xsl Located in ditaot\demo\fo\cfg\fo\attrs Contains the following global variables: page-width page-margin-top page-height page-margin-bottom page-margins side-col-width page-margin-left default-font-size page-margin-right

Layout-masters.xsl Located in ditaot\demo\fo\cfg\fo References the global variables for page layout Centralizes document settings Catalog.xml no longer needs to be used to override layout-masters Can be located anywhere in the customization directory Layout-masters .xml was retained for backwards compatibility

How to Customize (1) Pick a directory Put your customizations directly in the ‘customization’ directory OR Create your own customization directory by copying ‘customization’ and renaming Include changed templates Copy relevant template files to customization\fo\xsl and include file names in customization\fo\xsl\custom.xsl OR Paste whole changed templates directly into customization\fo\xsl\custom.xsl

How to Customize (2) Include changed attribute sets Copy attribute files to customization\fo\attr dir and include file names in customization\fo\attr\custom.xsl OR Paste whole changed attributes sets directly into customization\fo\attr\custom.xsl NOTE: Pasting code directly into custom.xsl is only prudent for small customizations. We generally recommend including changed files in custom.xsl Change the entry in customization\catalog.xml Copy catalog.xml.orig Rename to catalog.xml Uncomment relevant entries

How to Customize (3) If you created your own customization directory, send the name of your customization directory as a parameter in your ANT build file. <param name="customization.dir" value=“<your customization dir>" /> NOTE: Customization allows you to easily install your changes on another machine by simply transferring the customization directory to the demo\fo or plugin\fo directory of that machine and sending the appropriate parameter in the ANT build file.

Customizing for Specialization (1) DITA is designed for specialization A specialization of topics should, by default, act like topics until told otherwise The preprocessing adds a class attribute to each element, which includes text representing the base element and the specialized element For example, a concept topic is a specialization of a general topic. Its class is “ - topic/topic concept/concept ” The class for each element can be found in the DITA language reference in the Inheritance section

Customizing for Specialization (2) XSLT templates in the plug-in match based on the class in order to support specialized elements Sample template: Best Practice: Always develop XPATH using the class attribute, as opposed to the element name. This will ensure that all elements specialized from a given class will inherit the formatting of that class.

How Customization Works Your code overrides the plug-in using XSLT’s regular rules of precedence Your template overrides the template with the same name Your template has higher priority, which can have unintended consequences If you override a general type, you also override a specialized type. Your attribute-sets add to the plug-in’s attribute-sets Erasing one attribute from a set won’t help

Customization using Antenna House’s XSL-FO Formatter Using the Graphical User Interface Can apply style sheets to XML documents Displays document in the pre-PDF stage Shows borders of FO elements, which helps the user visualize how the formatting works Provides moveable rulers to measure document elements, which can be set to different units of measurements. Displays formatting errors Aids development by allowing developer to directly adjust the FO document and see the result without needing to change the style sheets and recompile the PDF each time.

End of Session: Understanding and Configuring the FO Plug-in for Generating PDF Files Part I (Beginner Level)

Understanding and Configuring the FO Plug-in for Generating PDF Files: Part I (Beginner Level)

Recommended

More Related Content

What's hot (18)

Similar to Understanding and Configuring the FO Plug-in for Generating PDF Files: Part I (Beginner Level) (20)

More from Suite Solutions (20)

Recently uploaded (20)

Understanding and Configuring the FO Plug-in for Generating PDF Files: Part I (Beginner Level)

Editor's Notes