• Save
Understanding and Configuring the FO Plug-in for Generating PDF Files: Part II (beginner level)
Upcoming SlideShare
Loading in...5
×
 

Understanding and Configuring the FO Plug-in for Generating PDF Files: Part II (beginner level)

on

  • 190 views

 

Statistics

Views

Total Views
190
Views on SlideShare
182
Embed Views
8

Actions

Likes
0
Downloads
0
Comments
0

2 Embeds 8

http://suitesol.profiledatacenter.com 5
http://suite-sol.com 3

Accessibility

Categories

Upload Details

Uploaded via as Microsoft PowerPoint

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Processing…
Post Comment
Edit your comment
  • 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
  • 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
  • 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 II (beginner level) Understanding and Configuring the FO Plug-in for Generating PDF Files: Part II (beginner level) Presentation Transcript

  • Understanding and Configuring the FO Plug-in for Generating PDF Files Part II (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.
  • Configuring FO Plug-in Part II Main Topics
    • How to Customize the FO Plug-in
    • Customization Units
    • Customization Case Studies
  • 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 customizationfoxsl and include file names in customizationfoxslcustom.xsl OR
      • Paste whole changed templates directly into customizationfoxslcustom.xsl
  • How to Customize (2)
    • Include changed attribute sets
      • Copy attribute files to customizationfoattr dir and include file names in customizationfoattrcustom.xsl OR
      • Paste whole changed attributes sets directly into customizationfoattrcustom.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 customizationcatalog.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=&quot;customization.dir&quot; value=“<your customization dir>&quot; />
    • 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.
  • Configuring FO Plug-in Part II Main Topics
    • How to Customize the FO Plug-in
    • Customization Units
    • Customization Case Studies
  • Templates (1)
    • Question :
    • How much of the template files should be retained?
    • Best Practice :
    • Save only those templates that are being changed. Your custom template replaces the out of the box template.
      • Makes your custom files smaller
      • Allows for easier upgrading to subsequent plug-in releases. Templates you haven’t touched will be automatically upgraded, and you will only have to maintain changes in templates you have changed.
    • Problem :
    • I customized my template, and the PDF renders, but I still don’t see my change. Where did it go?
    • Solution :
      • Check that you remembered to include the changed file in custom.xsl and that you updated the catalog file accordingly.
      • Check that the file you changed is the one that is being used.
      • Check which file you changed. Make sure it is being saved where you think it is being saved. Beware of duplicate file names and directory names.
    • Best Practice :
      • Develop a system for keeping track of which are the custom files and which are the originals. Make sure that changes are always made in the COPY of the file, and not the original.
    Templates (2)
  • Attribute Sets (1)
    • Question :
    • How much of the original attribute file should be retained?
    • Answer – Unresolved:
      • Only changed attributes sets – same advantages are for templates: smaller files, only need to maintain changes.
      • All attribute sets – formatting is interdependent. Don’t necessarily want your formatting changed when plug-in is upgraded. You end up touching most attributes sets anyway because so many attributes are repeated in different places.
  • Attribute Sets (2)
    • Problem :
    • Where did all of these attributes in my document come from? I don’t remember defining them in my custom attribute set.
    • Answer :
    • The toolkit MERGES the standard attribute sets with the custom attribute sets. This means that any attribute that you did not replace will still appear in the final output, whether or not you want it.
    • Best Practice :
    • When customizing attribute sets, copy the WHOLE standard attribute set to the new file. This way you will be aware of all of the attributes that will be included in the PDF. Then change the desired attributes.
  • Attribute Sets (3)
    • Note :
    • This can in theory become a problem again after the toolkit upgraded, if the attribute sets are updated. Beware of formatting changes creeping into your document after an update.
    • Problem :
    • Some attributes exist in the standard attribute set that I don’t want at all. How do I delete an attribute?
    • Answer :
    • Where relevant, set the value of the attribute to 0 in the new attribute set.
    • If that is not possible, you may have to create a new attribute set with a different name that does not include the problematic attribute. You can then reference the new attribute set from the templates.
  • Configuring FO Plug-in Part II Main Topics
    • How to Customize the FO Plug-in
    • Customization Units
    • Customization Case Studies
  • Configuring FO Plug-in Part II Main Topics
    • Customization Case Studies
      • Document Body
      • Tables
      • Lists
      • Related Links
      • Rendering Engine
  • Customizing the Document Body (1)
    • Goal :
    • Customize the titles in the body of the document.
    • Problem:
    • There is no file called body.xsl.
    • Where is the information stored?
    • Answer:
    • When all else fails, reference commons.xsl. Note the file size. Contains a lot of general (common) formatting and template information.
    • Best Practice:
    • We strongly recommend using a good searching program that can do quick text searching in subdirectories. (i.e. Textpad, grep, google desktop). It is often much quicker to do a direct search than untangle the web of files.
  • Customizing the Document Body (2)
    • Relevant files :
      • commons.xsl, commons-attr.xsl
    • Problem :
    • I see the topic.topic.title attribute set, but when I searched, I can’t find a use-attribute-sets reference anywhere. Where is topic.topic.title being used?
    • Answer :
    • commons.xsl GENERATES the topic.topic… attribute set names in createTopicAttrsName template. The number of topics reflects the number of levels.
    • Solution:
    • Customize the topic.title attribute sets in commons-attr.xsl.
  • Configuring FO Plug-in Part II Main Topics
    • Customization Case Studies
      • Document Body
      • Tables
      • Lists
      • Related Links
      • Rendering Engine
  • Customizing Tables (1)
    • Goal :
    • Display borders around each cell of a table.
    • Relevant files :
    • tables.xsl, tables1.0.xsl, tables-attr.xsl.
    • Suggestion :
    • Insert attributes for borders in relevant attribute sets.
    • Problem :
    • DITA supports special table border definitions within the actual DITA files.
      • colsep - Column separator : 0 - no separators; 1 - separators
      • rowsep - Row separator : 0 - no separators; 1 - separators
      • frame - Specifies which portion of a border should surround the element. Possible values: top | bottom | topbot | all | sides | none
    • Note:
    • Hardcoding the table borders in the attribute sets will work if you ALWAYS want this look. If, however, you want the table borders to vary based on the presence of the CALS table attributes, this solution will not be effective.
    • Solution :
    • Make the change in the tables.xsl or tables1.0.xsl files, and NOT in the attribute set files. In my case, I made a change in the template generateTableEntryBorder.
    Customizing Tables (2)
  • Configuring FO Plug-in Part II Main Topics
    • Customization Case Studies
      • Document Body
      • Tables
      • Lists
      • Related Links
      • Rendering Engine
  • Customizing Lists (1)
      • Goal :
      • Ensure that the first and last list items are not alone on a page
    • Relevant files :
    • lists.xsl, lists-attr.xsl
      • Method:
      • This can be accomplished by using XPATH within the attribute set.
      • Note:
      • XSL can be used within an attribute set. It must be used within the attribute – can not be used to determine which attribute should be there.
      • Sample Code:
    Customizing Lists (2)
  • Configuring FO Plug-in Part II Main Topics
    • Customization Case Studies
      • Document Body
      • Tables
      • Lists
      • Related Links
      • Rendering Engine
  • Customizing Related Links (1)
    • Goal:
    • Display related links after each topic in the PDF
    • Relevant files :
    • links.xsl, links-attr.xsl
    • Question :
    • I can render the document but I don’t see any related links. I thought this was a built-in function?
    • Answer :
    • This is a built-in function, and links are displayed by default – for online documents. To get the links to appear in the PDF, you can send a parameter in your build file – disableRelatedLinks=‘no’ . This should work in all versions of the Toolkit.
  • Customizing Related Links (2)
    • There is a new parameter in the toolkit which controls the display of links called args.fo.include.rellinks
    • Values (from a comment in basic_settings.xsl):
      • none - no links are included. This is the default, to match previous settings.
      • all - all links are included. If the original parameter $ disableRelatedLinks is customized to &quot;no&quot;, this is the default, to match previous settings.
      • nofamily - excludes links with @role = parent, child, next, previous, ancestor, descendant, sibling, cousin.
  • Configuring FO Plug-in Part II Main Topics
    • Customization Case Studies
      • Document Body
      • Tables
      • Lists
      • Related Links
      • Rendering Engine
  • Configuring the FO Plug-in to Use Antenna House and Render X
    • To configure the FO Plug-in to use Antenna House or Render X, set the pdf.formatter parameter in the project build file.
    • Values
      • fop – (default)
      • ah – Antenna House
      • xep – RenderX
    • It is much more complicated to do this using previous versions of the toolkit. We recommend upgrading to the latest version of the toolkit to take advantage of this feature and other improvements.
  • Configuring FO Plug-in Part II Main Topics
    • Customization Case Studies
      • Document Body
      • Tables
      • Lists
      • Related Links
      • Rendering Engine
  • Configuring FO Plug-in Part II Main Topics
    • How to Customize the FO Plug-in
    • Customization Units
    • Customization Case Studies
  • End of Session: Understanding and Configuring the FO Plug-in for Generating PDF Files Part II (Beginner Level)