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

474
-1

Published on

Published in: Education, Technology
0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total Views
474
On Slideshare
0
From Embeds
0
Number of Embeds
2
Actions
Shares
0
Downloads
0
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide
  • Suite Solutions: DITA Quick Start Training for Authors iDTP, March 16-18, 2009
  • Suite Solutions: DITA Quick Start Training for Authors iDTP, March 16-18, 2009
  • Suite Solutions: DITA Quick Start Training for Authors iDTP, March 16-18, 2009 Apache ANT – Another Neat Tool – it is a JAVA program (a bunch of scripts). Java-based build tool which enables creation of XML-based configuration files Allows you to pass parameters Allows you to extend and customize how the toolkit runs Stylesheets are how exactly all this works is outside the scope of this course – it is covered fully in the wonderful Advanced DITA course
  • DITA Open Toolkit Workshop September 2008
  • DITA Open Toolkit Workshop September 2008
  • DITA Open Toolkit Workshop September 2008
  • DITA Open Toolkit Workshop September 2008
  • DITA Open Toolkit Workshop September 2008
  • Understanding and Configuring the FO Plug-in for Generating PDF Files: Part I (Beginner Level)

    1. 1. Understanding and Configuring the FO Plug-in for Generating PDF Files Part I (Beginner Level) Adena Frazer Suite Solutions
    2. 2. Who am I? <ul><li>Background in Computer Science and Education </li></ul><ul><li>Experience in several computer companies over </li></ul><ul><li>the past decade+ </li></ul><ul><ul><li>Web applications </li></ul></ul><ul><ul><li>Telecommunications </li></ul></ul><ul><li>Early member of the Suite Solutions team </li></ul><ul><ul><li>Various webinars and on-site training seminars </li></ul></ul><ul><ul><li>in Boston and Santa Clara </li></ul></ul><ul><ul><li>PDF and HTML style sheet projects </li></ul></ul><ul><ul><li>FO plug-in support for PDF output </li></ul></ul><ul><ul><li>Project Management </li></ul></ul>
    3. 3. What is Suite Solutions? <ul><li>Our Mission </li></ul><ul><li>To increase our customers’ profitability by significantly improving the efficiency of their information development and delivery processes. </li></ul><ul><li>Qualitative Advantage </li></ul><ul><li>Content Lifecycle Implementation (CLI) is Suite Solutions’ comprehensive approach – from concept to publication – to maximizing the value of your information assets. </li></ul><ul><li>Our professionals are with you at every phase, determining, recommending and implementing the most cost-effective, flexible and long term solution for your business. </li></ul>
    4. 4. Overview of FO Plug-in Main Topics <ul><li>Overview of PDF Generation </li></ul><ul><li>Introduction to the FO Plug-in </li></ul><ul><li>Customizing the FO Plug-in </li></ul>
    5. 5. DITA-OT Components DOST.jar XSL Transforms XSL style sheets <ul><li>Pre-process </li></ul><ul><li>General processing </li></ul><ul><li>Transform to output format (xhtml, fo) </li></ul>XSLT Engines <ul><li>SAXON </li></ul><ul><li>XALAN </li></ul>Apache ANT <ul><li>Batik.jar (FOP) </li></ul><ul><li>Resolver.jar (resolves DTD) </li></ul><ul><li>Icu4j.jar (internationalization) </li></ul><ul><li>Fop.jar </li></ul>XML Parser <ul><li>XERCES </li></ul>
    6. 6. PDF Generation XSL style sheets dita2pdf XSLT Engine <ul><li>SAXON </li></ul><ul><li>XALAN </li></ul>Merged XML file generated from all referenced topics FO file XSL-FO Rendering Engine <ul><li>Antenna House </li></ul><ul><li>RenderX </li></ul><ul><li>Apache FOP </li></ul>Final PDF Output
    7. 7. Intermediate Files (1) <ul><ul><li>DITA files </li></ul></ul><ul><ul><li>_MERGED.xml </li></ul></ul><ul><ul><li>stage1.xml </li></ul></ul><ul><ul><li>stage2.fo </li></ul></ul>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
    8. 8. Intermediate Files (2) <ul><ul><li>stage2.fo </li></ul></ul><ul><ul><li>stage3.fo </li></ul></ul><ul><ul><li>topic.fo </li></ul></ul><ul><ul><li>.pdf </li></ul></ul>Internationalization preprocessing Internationalization postprocessing FO document is converted to a PDF File using an XSL-FO rendering engine
    9. 9. Using the Intermediate Files <ul><ul><li>The style sheets are applied to stage1.xml during PDF rendering. </li></ul></ul><ul><ul><ul><li>All XPATH and related code should be written with this in mind. </li></ul></ul></ul><ul><ul><ul><li>Debug style sheet issues by opening up stage1.xml to see to what XML the style sheets are being applied. </li></ul></ul></ul><ul><ul><li>Location of Intermediate Files </li></ul></ul><ul><ul><ul><li>Topic.fo is created in the output directory </li></ul></ul></ul><ul><ul><ul><li>The other intermediate files ( _MERGED.xml, stage1.xml, stage2.fo, stage3.fo ) are created in the temp directory. </li></ul></ul></ul><ul><ul><li>By default, the intermediate files are deleted by the Toolkit </li></ul></ul><ul><ul><li>They can be retained by telling the plug-in not to delete these files </li></ul></ul>
    10. 10. Retaining the Intermediate Files <ul><ul><li>In older versions of the toolkit, comment out the deletion code from demo/fo/build.xml. </li></ul></ul><ul><ul><li>In newer versions of the toolkit, use parameters to prevent the deletion of these files </li></ul></ul><ul><ul><ul><li>Retain.topic.fo – Set to “yes” to retain the topic.fo file </li></ul></ul></ul><ul><ul><ul><li>Clean.temp – set to “no” to retain the other intermediate files </li></ul></ul></ul>
    11. 11. ANT Build File
    12. 12. Overview of FO Plug-in Main Topics <ul><li>Overview of PDF Generation </li></ul><ul><li>Introduction to the FO Plug-in </li></ul><ul><li>Customizing the FO Plug-in </li></ul>
    13. 13. Why use the FO Plug-in? <ul><li>Legacy PDF code is deprecated </li></ul><ul><li>Plug-in provides for increased functionality </li></ul><ul><ul><li>Index and TOC generation </li></ul></ul><ul><ul><li>Characters can be remapped to different fonts </li></ul></ul><ul><ul><li>Extensive customization of publishing output by setting variables and attribute-sets </li></ul></ul><ul><ul><li>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 </li></ul></ul><ul><ul><li>Bookmap support </li></ul></ul><ul><ul><li>See c:ditaotdemofo eadme.txt for more details </li></ul></ul>
    14. 14. PDF Transtypes <ul><ul><li>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. </li></ul></ul><ul><ul><ul><li>PDF transtype references the old pdf code </li></ul></ul></ul><ul><ul><ul><li>PDF2 transtype references the FO Plug-in code. </li></ul></ul></ul><ul><ul><li>In recent versions of the toolkit, the FO Plug-in code has become the default code for PDF processing. </li></ul></ul><ul><ul><ul><li>PDF transtype references the FO Plug-in code. ( PDF2 has been retained for backwards compatibility). </li></ul></ul></ul><ul><ul><ul><li>The legacypdf transtype references the old PDF code. </li></ul></ul></ul>
    15. 15. FO Plug-in Directory Structure
    16. 16. Document Components (1) <ul><li>Front Matter (Title Page) </li></ul><ul><ul><li>front-matter.xsl, front-matter-attr.xsl </li></ul></ul><ul><li>Table of Contents (TOC) </li></ul><ul><ul><li>toc.xsl, toc-attr.xsl </li></ul></ul><ul><li>Static Content (includes footers and headers) </li></ul><ul><ul><li>static-content.xsl, static-content-attr.xsl </li></ul></ul><ul><li>Links (includes reltables) </li></ul><ul><ul><li>links.xsl, links-attr.xsl </li></ul></ul><ul><li>Index </li></ul><ul><ul><li>index.xsl, index_1.0.xsl, index-attr.xsl </li></ul></ul><ul><li>Bookmarks </li></ul><ul><ul><li>bookmarks.xsl, bookmarks_1.0.xsl, bookmarks-attr.xsl </li></ul></ul><ul><li>Layout Information </li></ul><ul><ul><li>layout-masters.xsl (new in v1.4.3!), layout-masters.xml </li></ul></ul>
    17. 17. Document Components (2) <ul><li>Body Content </li></ul><ul><ul><li>Formatting </li></ul></ul><ul><ul><ul><li>Programming Domain </li></ul></ul></ul><ul><ul><ul><ul><li>pr-domain.xsl, pr-domain-attr.xsl </li></ul></ul></ul></ul><ul><ul><ul><li>Software Domain </li></ul></ul></ul><ul><ul><ul><ul><li>sw-domain.xsl, sw-domain-attr.xsl </li></ul></ul></ul></ul><ul><ul><ul><li>User Interface (includes menu cascade) </li></ul></ul></ul><ul><ul><ul><ul><li>ui-domain.xsl, ui-domain-attr.xsl </li></ul></ul></ul></ul><ul><ul><ul><li>Highlighting Domain (includes bold and italics) </li></ul></ul></ul><ul><ul><ul><ul><li>hi-domain.xsl, hi-domain-attr.xsl </li></ul></ul></ul></ul><ul><ul><li>Titles </li></ul></ul><ul><ul><ul><li>commons.xsl, commons-attr.xsl </li></ul></ul></ul><ul><ul><li>Lists </li></ul></ul><ul><ul><ul><li>lists.xsl, lists-attr.xsl </li></ul></ul></ul><ul><ul><li>Tables (includes Definition Lists) </li></ul></ul><ul><ul><ul><li>tables.xsl, tables_1.0.xsl, tables-attr.xsl </li></ul></ul></ul>
    18. 18. Basic-settings.xsl <ul><ul><li>Located in ditaotdemofocfgfoattrs </li></ul></ul><ul><ul><li>Contains the following global variables: </li></ul></ul><ul><li>page-width </li></ul><ul><li>page-margin-top </li></ul><ul><li>page-height </li></ul><ul><li>page-margin-bottom </li></ul><ul><li>page-margins </li></ul><ul><li>side-col-width </li></ul><ul><li>page-margin-left </li></ul><ul><li>default-font-size </li></ul><ul><li>page-margin-right </li></ul>
    19. 19. Layout-masters.xsl <ul><ul><li>Located in ditaotdemofocfgfo </li></ul></ul><ul><ul><li>References the global variables for page layout </li></ul></ul><ul><ul><li>Centralizes document settings </li></ul></ul><ul><ul><li>Catalog.xml no longer needs to be used to override layout-masters </li></ul></ul><ul><ul><li>Can be located anywhere in the customization directory </li></ul></ul><ul><ul><li>Layout-masters .xml was retained for backwards compatibility </li></ul></ul>
    20. 20. Overview of FO Plug-in Main Topics <ul><li>Overview of PDF Generation </li></ul><ul><li>Introduction to the FO Plug-in </li></ul><ul><li>Customizing the FO Plug-in </li></ul>
    21. 21. How to Customize (1) <ul><li>Pick a directory </li></ul><ul><ul><li>Put your customizations directly in the ‘customization’ directory OR </li></ul></ul><ul><ul><li>Create your own customization directory by copying ‘customization’ and renaming </li></ul></ul><ul><li>Include changed templates </li></ul><ul><ul><li>Copy relevant template files to customizationfoxsl and include file names in customizationfoxslcustom.xsl OR </li></ul></ul><ul><ul><li>Paste whole changed templates directly into customizationfoxslcustom.xsl </li></ul></ul>
    22. 22. How to Customize (2) <ul><li>Include changed attribute sets </li></ul><ul><ul><li>Copy attribute files to customizationfoattr dir and include file names in customizationfoattrcustom.xsl OR </li></ul></ul><ul><ul><li>Paste whole changed attributes sets directly into customizationfoattrcustom.xsl </li></ul></ul><ul><ul><li>NOTE: Pasting code directly into custom.xsl is only prudent for small customizations. We generally recommend including changed files in custom.xsl </li></ul></ul><ul><li>Change the entry in customizationcatalog.xml </li></ul><ul><ul><li>Copy catalog.xml.orig </li></ul></ul><ul><ul><li>Rename to catalog.xml </li></ul></ul><ul><ul><li>Uncomment relevant entries </li></ul></ul>
    23. 23. How to Customize (3) <ul><li>If you created your own customization directory, send the name of your customization directory as a parameter in your ANT build file. </li></ul><ul><ul><li><param name=&quot;customization.dir&quot; value=“<your customization dir>&quot; /> </li></ul></ul><ul><li>NOTE: Customization allows you to easily install your changes on another machine by simply transferring the customization directory to the demofo or pluginfo directory of that machine and sending the appropriate parameter in the ANT build file. </li></ul>
    24. 24. Customizing for Specialization (1) <ul><li>DITA is designed for specialization </li></ul><ul><ul><li>A specialization of topics should, by default, act like topics until told otherwise </li></ul></ul><ul><li>The preprocessing adds a class attribute to each element, which includes text representing the base element and the specialized element </li></ul><ul><ul><li>For example, a concept topic is a specialization of a general topic. Its class is </li></ul></ul><ul><ul><ul><li>“ - topic/topic concept/concept ” </li></ul></ul></ul><ul><li>The class for each element can be found in the DITA language reference in the Inheritance section </li></ul>
    25. 25. Customizing for Specialization (2) <ul><li>XSLT templates in the plug-in match based on the class in order to support specialized elements </li></ul><ul><ul><li>Sample template: </li></ul></ul><ul><li>Best Practice: </li></ul><ul><ul><li>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. </li></ul></ul>
    26. 26. How Customization Works <ul><li>Your code overrides the plug-in using XSLT’s regular rules of precedence </li></ul><ul><li>Your template overrides the template with the same name </li></ul><ul><ul><li>Your template has higher priority, which can have unintended consequences </li></ul></ul><ul><li>If you override a general type, you also override a specialized type. </li></ul><ul><li>Your attribute-sets add to the plug-in’s attribute-sets </li></ul><ul><ul><li>Erasing one attribute from a set won’t help </li></ul></ul>
    27. 27. Customization using Antenna House’s XSL-FO Formatter <ul><li>Using the Graphical User Interface </li></ul><ul><ul><li>Can apply style sheets to XML documents </li></ul></ul><ul><ul><li>Displays document in the pre-PDF stage </li></ul></ul><ul><ul><ul><li>Shows borders of FO elements, which helps the user visualize how the formatting works </li></ul></ul></ul><ul><ul><ul><li>Provides moveable rulers to measure document elements, which can be set to different units of measurements. </li></ul></ul></ul><ul><ul><ul><li>Displays formatting errors </li></ul></ul></ul><ul><ul><ul><li>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. </li></ul></ul></ul>
    28. 28. Overview of FO Plug-in Main Topics <ul><li>Overview of PDF Generation </li></ul><ul><li>Introduction to the FO Plug-in </li></ul><ul><li>Customizing the FO Plug-in </li></ul>
    29. 29. End of Session: Understanding and Configuring the FO Plug-in for Generating PDF Files Part I (Beginner Level)

    ×