Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Moving Ahead With Xsl Fo Style Sheet Customizations


Published on

  • Be the first to comment

  • Be the first to like this

Moving Ahead With Xsl Fo Style Sheet Customizations

  1. 1. Moving Ahead with XSL-FO Style Sheet Customizations 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. XSL-FO Customizations Main Topics <ul><ul><li>Page Orientation </li></ul></ul><ul><ul><li>Bookmarks </li></ul></ul><ul><ul><li>Index </li></ul></ul><ul><ul><li>Glossary </li></ul></ul><ul><ul><li>TOC Numbering </li></ul></ul><ul><ul><li>Customization Tips </li></ul></ul>
  5. 5. Customizing Page Orientation <ul><ul><li>Goal : </li></ul></ul><ul><ul><li>Change the page orientation from portrait to landscape </li></ul></ul><ul><li>Relevant Files : </li></ul><ul><li>basic-settings.xsl, layout-masters.xsl </li></ul><ul><ul><li>Simple Method: </li></ul></ul><ul><ul><li>To change the page orientation for the whole document, simply change the values of the page-height and page-width global variables in basic_settings.xsl. </li></ul></ul><ul><ul><li>Complex Method: </li></ul></ul><ul><ul><li>For more complicated page orientation needs, change the simple-page-masters in layout-masters.xsl . </li></ul></ul>
  6. 6. XSL-FO Customizations Main Topics <ul><ul><li>Page Orientation </li></ul></ul><ul><ul><li>Bookmarks </li></ul></ul><ul><ul><li>Index </li></ul></ul><ul><ul><li>Glossary </li></ul></ul><ul><ul><li>TOC Numbering </li></ul></ul><ul><ul><li>Customization Tips </li></ul></ul>
  7. 7. Customizing Bookmarks (1) <ul><ul><li>Goal : </li></ul></ul><ul><ul><li>Determine whether the bookmarks display is collapsed or expanded. </li></ul></ul><ul><li>Relevant Files : </li></ul><ul><li>basic-settings.xsl, bookmarks.xsl </li></ul><ul><ul><li>To Change for Each Build: </li></ul></ul><ul><ul><li>Use the new parameter in the project build file. </li></ul></ul><ul><ul><li>Pass in the value of EXPANDED (must be in caps) to expand the bookmarks. </li></ul></ul>
  8. 8. Customizing Bookmarks (2) <ul><ul><li>To Change Permanently: </li></ul></ul><ul><ul><li>Change the default in basic-settings.xsl to EXPANDED, and do not pass in the parameter from the project build file. </li></ul></ul>
  9. 9. XSL-FO Customizations Main Topics <ul><ul><li>Page Orientation </li></ul></ul><ul><ul><li>Bookmarks </li></ul></ul><ul><ul><li>Index </li></ul></ul><ul><ul><li>Glossary </li></ul></ul><ul><ul><li>TOC Numbering </li></ul></ul><ul><ul><li>Customization Tips </li></ul></ul>
  10. 10. Customizing the Index (1) <ul><ul><li>Goal : </li></ul></ul><ul><ul><li>To customize the formatting of the Index title and group labels. </li></ul></ul><ul><li>Relevant Files : </li></ul><ul><li>index.xsl, index-attr.xsl </li></ul><ul><li>Note: </li></ul><ul><li>FOP does not generate indices. This is one of the major disadvantages of FOP. To generate an index, use Antenna House or RenderX rendering Engines. </li></ul>
  11. 11. Customizing the Index (2) <ul><ul><li>Relevant Attribute Sets: </li></ul></ul><ul><ul><ul><li>__index__label - controls the formatting for the index title </li></ul></ul></ul><ul><ul><ul><li>__index__letter-group – controls the formatting for the group names </li></ul></ul></ul><ul><ul><li>Note: </li></ul></ul><ul><ul><li>Relatively minor changes in the attribute sets can have a big impact on the appearance of the index. </li></ul></ul><ul><ul><li>Attribute Set Customizations: </li></ul></ul><ul><ul><li>We changed the color, spacing (margin-bottom, space-before, space-after, and padding-top), and borders of the above attribute sets to give a new look and feel to the index display. </li></ul></ul>
  12. 12. XSL-FO Customizations Main Topics <ul><ul><li>Page Orientation </li></ul></ul><ul><ul><li>Bookmarks </li></ul></ul><ul><ul><li>Index </li></ul></ul><ul><ul><li>Glossary </li></ul></ul><ul><ul><li>TOC Numbering </li></ul></ul><ul><ul><li>Customization Tips </li></ul></ul>
  13. 13. Displaying a Glossary (1) <ul><ul><li>Goal : </li></ul></ul><ul><ul><li>To display a glossary using a ditamap. </li></ul></ul><ul><li>Relevant Files : </li></ul><ul><li>root-processing.xsl (existing file) </li></ul><ul><li>glossary.xsl, glossary-attr.xsl (new files) </li></ul><ul><ul><li>DITA Elements: </li></ul></ul><ul><ul><ul><li>DITA provides initial support for glossary entries using the glossentry, glossdef, and glossterm elements. </li></ul></ul></ul><ul><ul><li>Steps for the DITA </li></ul></ul><ul><ul><ul><li>Create glossentry elements in your DITA source. </li></ul></ul></ul><ul><ul><ul><li>Reference these elements using topicrefs from the ditamap. </li></ul></ul></ul>
  14. 14. Displaying a Glossary (2) <ul><ul><li>Steps for the XSL : </li></ul></ul><ul><ul><ul><li>Create a glossary-attrs.xsl file which contains formatting for glossdef s and glossterm s. </li></ul></ul></ul><ul><ul><ul><li>Create a glossary.xsl file with a createGlossary template that: </li></ul></ul></ul><ul><ul><ul><ul><li>Outputs a Glossary title for the page if the document contains glossentry elements </li></ul></ul></ul></ul><ul><ul><ul><ul><li>Displays the glossary terms and definitions based on the attribute set formatting </li></ul></ul></ul></ul>
  15. 15. Displaying a Glossary (3) <ul><ul><ul><li>Call the createGlossary template from root-processing.xsl </li></ul></ul></ul><ul><ul><ul><li>Filter out the glossary entries from the main body of the document by overriding templates in commons.xsl </li></ul></ul></ul><ul><ul><ul><li>Filter out the glossary entries from the TOC and the bookmarks by overriding templates in toc.xsl and bookmarks.xsl </li></ul></ul></ul>
  16. 16. XSL-FO Customizations Main Topics <ul><ul><li>Page Orientation </li></ul></ul><ul><ul><li>Bookmarks </li></ul></ul><ul><ul><li>Index </li></ul></ul><ul><ul><li>Glossary </li></ul></ul><ul><ul><li>TOC Numbering </li></ul></ul><ul><ul><li>Customization Tips </li></ul></ul>
  17. 17. Customizing the TOC (1) <ul><ul><li>Goal : </li></ul></ul><ul><ul><li>To display topic numbering for all levels of the TOC in a ditamap. </li></ul></ul><ul><li>Relevant Files : </li></ul><ul><li>toc.xsl, toc-attr.xsl </li></ul><ul><ul><li>Note: </li></ul></ul><ul><ul><ul><li>This is a complicated customization task which requires an in-depth knowledge of XSLT and XPATH to do efficiently. </li></ul></ul></ul><ul><ul><ul><li>Reuven Weiser from Suite Solutions wrote a short custom template which provides TOC numbering for ditamaps. </li></ul></ul></ul><ul><ul><ul><li>This code can be expanded to work with bookmaps and more complicated DITA source. </li></ul></ul></ul>
  18. 18. Customizing the TOC (2) <ul><ul><li>TOC Numbering Algorithm (by Reuven Weiser) : </li></ul></ul><ul><ul><li>Write a template that returns the TOC number for a given topic. </li></ul></ul><ul><ul><ul><li>For top level topics: </li></ul></ul></ul><ul><ul><ul><ul><li>Return the number of the topic in the current level by counting the preceding-siblings and adding 1. </li></ul></ul></ul></ul><ul><ul><ul><li>For subtopics: </li></ul></ul></ul><ul><ul><ul><ul><li>Call this template on the immediate parent of the current node. This will work recursively until the top level topic is reached. </li></ul></ul></ul></ul><ul><ul><ul><ul><li>Concatenate the number of the parent with the number of the topic in the current level, with a period in between the two numbers. </li></ul></ul></ul></ul><ul><ul><ul><ul><li>Return this number </li></ul></ul></ul></ul><ul><ul><li>Call this template from the template that creates the TOC. </li></ul></ul>
  19. 19. XSL-FO Customizations Main Topics <ul><ul><li>Page Orientation </li></ul></ul><ul><ul><li>Bookmarks </li></ul></ul><ul><ul><li>Index </li></ul></ul><ul><ul><li>Glossary </li></ul></ul><ul><ul><li>TOC Numbering </li></ul></ul><ul><ul><li>Customization Tips </li></ul></ul>
  20. 20. Customization Tips (1) <ul><ul><li>Isolate the section on which you are working </li></ul></ul><ul><ul><li>Root_processing.xsl controls the calls to the different elements of the documents. You can comment out calls that are not relevant in order to focus on the section on which you are working. </li></ul></ul><ul><ul><li>Save the intermediate files generated by the plug-in </li></ul></ul><ul><ul><li>By default, the plug-in’s, build.xml deletes all of the intermediate files (stage1.xml,,, after the PDF has been rendered. </li></ul></ul><ul><ul><li>Use the following parameters to preserve the intermediate files: </li></ul></ul>
  21. 21. Customization Tips (2) <ul><li>Locations of intermediate files </li></ul><ul><ul><li>_MERGED.xml, stage1.xml,, can be found in dita.temp.dir . </li></ul></ul><ul><ul><li>, .pdf file can be found in output.dir </li></ul></ul><ul><li>Format the XML </li></ul><ul><ul><li>Get an XML formatter such as Microsoft’s Visual Web Developer to display the FO and XSL files in a readable format. This will save time spent trying to match up tags. </li></ul></ul><ul><li>Reference stage1.xml </li></ul><ul><ul><li>The style sheets are applied to stage1.xml during PDF rendering. During development, make sure that all XPATH and related code is written with this in mind. Debug problems with the style sheets by opening up stage1.xml to see to which XML the style sheets are being applied. </li></ul></ul>
  22. 22. Customization Tips (3) <ul><li>Test XPATH code separately </li></ul><ul><ul><li>This tip is especially important for developers who are beginning to use XPATH. Work on the XPATH query using software that applies XSL style sheets to XML such as Cooktop. Copy the relevant XML from stage1.xml and develop and test the XPATH query in isolation. Only transfer the query back to the plug-in once you are sure it is working correctly. </li></ul></ul><ul><li>Adjust styles using the FO file </li></ul><ul><ul><li>Play with the FO file using software that formats FO documents such as Antenna House’s graphical user interface to get the formatting correct there. Once you know how the FO file is supposed to look, you can work backwards and get the style sheets to generate the correct FO. </li></ul></ul>
  23. 23. Customization Tips (4) <ul><li>Double check which file is being used by the Plug-in </li></ul><ul><ul><li>Make a simple, noticeable change to the code on which you are working. Re-render the document and verify that the change appears where it should. If not, the bug may be due to the fact that you are working on a file that is not being referenced. </li></ul></ul><ul><ul><ul><li>Make sure you are working in the right directory. Beware of duplicate file and directory names </li></ul></ul></ul><ul><ul><ul><li>Verify that you included the changed file in custom.xsl and that you updated the catalog file accordingly. </li></ul></ul></ul><ul><ul><ul><li>Remove unnecessary includes, and change necessary hardcoded links to point to your custom attribute and template files. </li></ul></ul></ul><ul><ul><ul><li>Check other relevant files. There can be up to three copies of a given file, all of which may be used at some point. </li></ul></ul></ul>
  24. 24. Customization Tips (5) <ul><li>Reference the built-in attribute sets </li></ul><ul><ul><li>If unwanted formatting is appearing in the document, make sure that attributes from the default attribute sets are not appearing. </li></ul></ul><ul><ul><li>Since the plug-in merges custom attribute sets with default attribute sets, best practice is to copy the whole default attribute set to the custom file, and not to delete unwanted attributes. </li></ul></ul><ul><li>Use Source Forge and Dita-users </li></ul><ul><ul><li>Look on for bugs and patches regarding a persistent problem. The problem may be with the Toolkit, not with your code. </li></ul></ul><ul><ul><ul><li> </li></ul></ul></ul><ul><ul><li>Post problems on dita-users with a clear explanation. Someone else may have had the same issue, and may share the solution with you. </li></ul></ul>
  25. 25. XSL-FO Customizations Main Topics <ul><ul><li>Page Orientation </li></ul></ul><ul><ul><li>Bookmarks </li></ul></ul><ul><ul><li>Index </li></ul></ul><ul><ul><li>Glossary </li></ul></ul><ul><ul><li>TOC Numbering </li></ul></ul><ul><ul><li>Customization Tips </li></ul></ul>
  26. 26. End of Session: Moving Ahead with XSL-FO Style Sheet Customizations