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) 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 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.

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 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.

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)

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)

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 "no", this is the default, to match previous settings. nofamily - excludes links with @role = parent, child, next, previous, ancestor, descendant, sibling, cousin.

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.

End of Session: 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)

More Related Content

What's hot (20)

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

More from Suite Solutions (20)

Recently uploaded (20)

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

Editor's Notes