Custom PDFs from the DITA OT
-
Upload
leigh-white -
Category
Technology
-
view
625 -
download
3
Transcript of Custom PDFs from the DITA OT
![Page 1: Custom PDFs from the DITA OT](https://reader036.fdocuments.net/reader036/viewer/2022062303/558519b5d8b42ada748b460a/html5/thumbnails/1.jpg)
Customizing PDF output from the DITA Open Toolkit
Leigh WhiteElementalSource, LLC
![Page 2: Custom PDFs from the DITA OT](https://reader036.fdocuments.net/reader036/viewer/2022062303/558519b5d8b42ada748b460a/html5/thumbnails/2.jpg)
ElementalSource, LLC
Me, me, me
• Background: English, Theoretical Linguistics• NOT a programmer or stylesheet developer• 20+ years as a content creator
![Page 3: Custom PDFs from the DITA OT](https://reader036.fdocuments.net/reader036/viewer/2022062303/558519b5d8b42ada748b460a/html5/thumbnails/3.jpg)
ElementalSource, LLC
Lower your standards?
• That depends…– Are your standards based on…non-standards?
• A tweak here, a tweak there, whatever “looks right”
• That is not a standard!• A standard is “an approved model”
– Predictable and prescriptive• PDF processing via the OT is absolutely based on
standards– If you can’t capture your “tweak” with a context-based rule,
it’s not predictable or prescriptive—drop it!
![Page 4: Custom PDFs from the DITA OT](https://reader036.fdocuments.net/reader036/viewer/2022062303/558519b5d8b42ada748b460a/html5/thumbnails/4.jpg)
ElementalSource, LLC
Ask yourself…
…which is more important:– perfect pages– more time to spend creating quality content
![Page 5: Custom PDFs from the DITA OT](https://reader036.fdocuments.net/reader036/viewer/2022062303/558519b5d8b42ada748b460a/html5/thumbnails/5.jpg)
ElementalSource, LLC
How does the OT make PDFs?
• Uses the FO plug-in• A collection of stylesheets, variables files, build files,
etc. that transform DITA into XSL:FO and then send it to an FO processor
• You never see an actual page until the PDF is done– This is a COMPLETE mind freak for some people– And a godsent miracle for others
![Page 6: Custom PDFs from the DITA OT](https://reader036.fdocuments.net/reader036/viewer/2022062303/558519b5d8b42ada748b460a/html5/thumbnails/6.jpg)
ElementalSource, LLC
FO plug-in
• Originally developed to fill in the “hardcopy” gap• Currently maintained by Suite Solutions• Several folks working on improvements or complete
re-writes• It ain’t pretty but it works
![Page 7: Custom PDFs from the DITA OT](https://reader036.fdocuments.net/reader036/viewer/2022062303/558519b5d8b42ada748b460a/html5/thumbnails/7.jpg)
ElementalSource, LLC
What happens
![Page 8: Custom PDFs from the DITA OT](https://reader036.fdocuments.net/reader036/viewer/2022062303/558519b5d8b42ada748b460a/html5/thumbnails/8.jpg)
ElementalSource, LLC
Quick tour of the FO plug-in
• DITA-OT\demo\fo:
![Page 9: Custom PDFs from the DITA OT](https://reader036.fdocuments.net/reader036/viewer/2022062303/558519b5d8b42ada748b460a/html5/thumbnails/9.jpg)
ElementalSource, LLC
The cfg folder
• DITA-OT\demo\fo\cfg:
Language-specific variables for
“boilerplate” text; header/footer
definitions; note image paths
Attribute sets to control
appearance of elements
Stylesheets to control
processing and behavior of elements
Images associated with the
customization
![Page 10: Custom PDFs from the DITA OT](https://reader036.fdocuments.net/reader036/viewer/2022062303/558519b5d8b42ada748b460a/html5/thumbnails/10.jpg)
ElementalSource, LLC
![Page 11: Custom PDFs from the DITA OT](https://reader036.fdocuments.net/reader036/viewer/2022062303/558519b5d8b42ada748b460a/html5/thumbnails/11.jpg)
ElementalSource, LLC
Attribute sets
• Grouped by element “type” (lists, links, tables, etc.) or domain (ui, pr, etc.)
• Everything else is in commons-attr.xsl
![Page 12: Custom PDFs from the DITA OT](https://reader036.fdocuments.net/reader036/viewer/2022062303/558519b5d8b42ada748b460a/html5/thumbnails/12.jpg)
ElementalSource, LLC
Attribute sets
• Expect to see the attributes in the default sets• If you customize &
remove attributes, OT “fills them back in” from the default
![Page 13: Custom PDFs from the DITA OT](https://reader036.fdocuments.net/reader036/viewer/2022062303/558519b5d8b42ada748b460a/html5/thumbnails/13.jpg)
ElementalSource, LLC
Attribute sets
• Can call other attribute sets:
![Page 14: Custom PDFs from the DITA OT](https://reader036.fdocuments.net/reader036/viewer/2022062303/558519b5d8b42ada748b460a/html5/thumbnails/14.jpg)
ElementalSource, LLC
Attribute sets
• Called by the stylesheets inDITA-OT\demo\fo\xsl
• Use the attribute set name to find the xsl template OR use the xsl template to find the attribute set
![Page 15: Custom PDFs from the DITA OT](https://reader036.fdocuments.net/reader036/viewer/2022062303/558519b5d8b42ada748b460a/html5/thumbnails/15.jpg)
ElementalSource, LLC
Attribute sets
• Some files are specific to FO processors:– _axf: Antenna House– _xep: XEP– _fop: Apache FOP
![Page 16: Custom PDFs from the DITA OT](https://reader036.fdocuments.net/reader036/viewer/2022062303/558519b5d8b42ada748b460a/html5/thumbnails/16.jpg)
ElementalSource, LLC
basic-settings.xsl
• Variables that define:– page dimensions– margins– default font size– default line height
• Use these variables instead of fixed values in attribute sets and layout-masters
• Add more as needed for greater uniformity
![Page 17: Custom PDFs from the DITA OT](https://reader036.fdocuments.net/reader036/viewer/2022062303/558519b5d8b42ada748b460a/html5/thumbnails/17.jpg)
ElementalSource, LLC
XSL
• Lots of these but many you probably won’t touch• Grouped by element “type” (lists, links, tables, etc.) or
domain (ui, pr, etc.)– Names match the attribute set files
• Everything else is in commons.xsl– Kitchen sink
![Page 18: Custom PDFs from the DITA OT](https://reader036.fdocuments.net/reader036/viewer/2022062303/558519b5d8b42ada748b460a/html5/thumbnails/18.jpg)
ElementalSource, LLC
XSL
• Some files specific to FO processors:– _axf: Antenna House– _xep: XEP– _fop: Apache FOP
![Page 19: Custom PDFs from the DITA OT](https://reader036.fdocuments.net/reader036/viewer/2022062303/558519b5d8b42ada748b460a/html5/thumbnails/19.jpg)
ElementalSource, LLC
_1.0 files
• Sometimes replace original file:– bookmarks_1.0.xsl– front-matter_1.0.xsl
• Sometimes supplement original file:– commons_1.0.xsl– index_1.0.xsl– table_1.0.xsl– toc_1.0.xsl
![Page 20: Custom PDFs from the DITA OT](https://reader036.fdocuments.net/reader036/viewer/2022062303/558519b5d8b42ada748b460a/html5/thumbnails/20.jpg)
ElementalSource, LLC
root-processing.xsl
• Creates the “shell” for your FO file• Calls other templates for frontmatter, TOC, index, etc.• Creates variables from map metadata that are available
throughout the build in headers, footers, cover pages, etc.
![Page 21: Custom PDFs from the DITA OT](https://reader036.fdocuments.net/reader036/viewer/2022062303/558519b5d8b42ada748b460a/html5/thumbnails/21.jpg)
ElementalSource, LLC
Bored? Confused?
![Page 22: Custom PDFs from the DITA OT](https://reader036.fdocuments.net/reader036/viewer/2022062303/558519b5d8b42ada748b460a/html5/thumbnails/22.jpg)
ElementalSource, LLC
Okay, let’s make a PDF!
• Multiple ditamaps• Bookmap• ANT build file
– DITA-OT\samples\ant_sample• Batch file
– Copy startcmd.bat from DITA-OT
![Page 23: Custom PDFs from the DITA OT](https://reader036.fdocuments.net/reader036/viewer/2022062303/558519b5d8b42ada748b460a/html5/thumbnails/23.jpg)
ElementalSource, LLC
A couple of quick changes
• ANT build file:– Change FO processor– Retain the topic.fo file
![Page 24: Custom PDFs from the DITA OT](https://reader036.fdocuments.net/reader036/viewer/2022062303/558519b5d8b42ada748b460a/html5/thumbnails/24.jpg)
ElementalSource, LLC
Create your own customization
• Copy and rename Customization folder– Don’t make changes to the default files!
• Rename and edit catalog.xml.orig• Call your customization from your ANT build file• Copy a file into your customization
– commons-attr.xsl
![Page 25: Custom PDFs from the DITA OT](https://reader036.fdocuments.net/reader036/viewer/2022062303/558519b5d8b42ada748b460a/html5/thumbnails/25.jpg)
ElementalSource, LLC
Create your own customization
• In IntellCont\fo\attrs, rename custom.xsl.orig– Rename the one in IntellCont\fo\xsl, too
• Call your commons-attr.xsl from custom.xsl– <xsl:import href="commons-attr.xsl"/>
• Make small, obvious change to commons-attr.xsl and run build to test
![Page 26: Custom PDFs from the DITA OT](https://reader036.fdocuments.net/reader036/viewer/2022062303/558519b5d8b42ada748b460a/html5/thumbnails/26.jpg)
ElementalSource, LLC
basic-settings.xsl
• Copy to your customization
![Page 27: Custom PDFs from the DITA OT](https://reader036.fdocuments.net/reader036/viewer/2022062303/558519b5d8b42ada748b460a/html5/thumbnails/27.jpg)
ElementalSource, LLC
Add bookmap metadata to cover
• Copy root-processing.xsl to your customization• Create variables
– productRev– bookNo
• Copy front-matter_1.0.xsl to your customization• Add fo:block elements that contain variables
![Page 28: Custom PDFs from the DITA OT](https://reader036.fdocuments.net/reader036/viewer/2022062303/558519b5d8b42ada748b460a/html5/thumbnails/28.jpg)
ElementalSource, LLC
Rearrange info in headers, footers
• Copy en.xml to your customization• Copy static-content.xsl to your customization
![Page 29: Custom PDFs from the DITA OT](https://reader036.fdocuments.net/reader036/viewer/2022062303/558519b5d8b42ada748b460a/html5/thumbnails/29.jpg)
ElementalSource, LLC
static-content.xsl
• insertBodyOddHeader• insertBodyEvenHeader
– Comment out <prodname>, <pagenum>• insertBodyOddFooter• insertBodyEvenFooter
– Comment out <heading>– Add <prodname>, <version>
![Page 30: Custom PDFs from the DITA OT](https://reader036.fdocuments.net/reader036/viewer/2022062303/558519b5d8b42ada748b460a/html5/thumbnails/30.jpg)
ElementalSource, LLC
en.xml
• <variable id="Body odd footer"/>– <param ref-name="prodname"/> <param ref-
name="version"/><param ref-name="pagenum"/>• <variable id="Body even footer"/>
– <param ref-name="pagenum"/><param ref-name="prodname"/> <param ref-name="version"/>
![Page 31: Custom PDFs from the DITA OT](https://reader036.fdocuments.net/reader036/viewer/2022062303/558519b5d8b42ada748b460a/html5/thumbnails/31.jpg)
ElementalSource, LLC
Wait!
• Page numbers are not on the outside in even footers• basic-settings.xsl:
– <xsl:variable name="mirror-page-margins" select="true()"/>
![Page 32: Custom PDFs from the DITA OT](https://reader036.fdocuments.net/reader036/viewer/2022062303/558519b5d8b42ada748b460a/html5/thumbnails/32.jpg)
ElementalSource, LLC
Justify footers
• static-content.xsl:– <fo:leader leader-pattern="space"/>– Be sure to put in right place!
• Copy static-content-attr.xsl to your customization• Attribute sets odd__footer, even__footer
– text-align=“justify”– text-align-last=“justify”
![Page 33: Custom PDFs from the DITA OT](https://reader036.fdocuments.net/reader036/viewer/2022062303/558519b5d8b42ada748b460a/html5/thumbnails/33.jpg)
ElementalSource, LLC
Set up even, odd body pages
• Copy layout-masters.xsl to your customization– Different path in custom.xsl
• Copy layout-masters-attr.xsl to your customization• region-body.odd, region-body.even:
– <xsl:attribute name="background-color">#ffffc0</xsl:attribute>
• region.before, region.after:– <xsl:attribute
name="background-color">#ffc0ff</xsl:attribute>
![Page 34: Custom PDFs from the DITA OT](https://reader036.fdocuments.net/reader036/viewer/2022062303/558519b5d8b42ada748b460a/html5/thumbnails/34.jpg)
ElementalSource, LLC
Change inside, outside margins
• basic-settings.xsl– page-margin-inside– page-margin-outside
![Page 35: Custom PDFs from the DITA OT](https://reader036.fdocuments.net/reader036/viewer/2022062303/558519b5d8b42ada748b460a/html5/thumbnails/35.jpg)
ElementalSource, LLC
Align footers with margins
• static-content-attr.xsl– odd__footer
• start-indent ($page-margin-inside)• end-indent ($page-margin-outside)
– even__footer• start-indent ($page-margin-outside)• end-indent ($page-margin-inside)
![Page 36: Custom PDFs from the DITA OT](https://reader036.fdocuments.net/reader036/viewer/2022062303/558519b5d8b42ada748b460a/html5/thumbnails/36.jpg)
ElementalSource, LLC
Why are *all* the pages…
…yellow and pink, not just body pages?
• By default, all page types call region-body.odd and region-body.even
• You can change this– Add new attribute sets for each page type
![Page 37: Custom PDFs from the DITA OT](https://reader036.fdocuments.net/reader036/viewer/2022062303/558519b5d8b42ada748b460a/html5/thumbnails/37.jpg)
ElementalSource, LLC
Restart page numbering
• Copy commons.xsl to your customization• startPageNumbering template:
– Comment out xsl:if• processTopicAppendix template:
– Add <xsl:call-template name="startPageNumbering"/>– (It’s missing for appendix)
![Page 38: Custom PDFs from the DITA OT](https://reader036.fdocuments.net/reader036/viewer/2022062303/558519b5d8b42ada748b460a/html5/thumbnails/38.jpg)
ElementalSource, LLC
Add an image to the title page
• Background image– Can also add within flow
• layout-masters.xsl:– Change front-matter-first to use region-
body__frontmatter.first• layout-masters-attr.xsl:
– Create region-body__frontmatter.first
![Page 39: Custom PDFs from the DITA OT](https://reader036.fdocuments.net/reader036/viewer/2022062303/558519b5d8b42ada748b460a/html5/thumbnails/39.jpg)
ElementalSource, LLC
Change fonts
• Copy font-mappings.xml to your customization• Uncomment entry in catalog• Add Verdana to “Sans”• Add Palatino to “Serif”• Processor-dependent:
– XEP: edit xep.xml– FOP: edit fop.xconf– AH: edit font-config.xml
![Page 40: Custom PDFs from the DITA OT](https://reader036.fdocuments.net/reader036/viewer/2022062303/558519b5d8b42ada748b460a/html5/thumbnails/40.jpg)
ElementalSource, LLC
Format TOC levels
• Copy toc.xsl and toc-attr.xsl to your customization• Copy font-weight attribute
– Add different colors for levels– Useful model for any level-based attribute
![Page 41: Custom PDFs from the DITA OT](https://reader036.fdocuments.net/reader036/viewer/2022062303/558519b5d8b42ada748b460a/html5/thumbnails/41.jpg)
ElementalSource, LLC
TOC attribute set interaction
• __toc__topic__content is overwritten by – __toc__chapter__content– __toc__appendix__content– __toc__part__content
when processing bookmap• Many more examples
![Page 42: Custom PDFs from the DITA OT](https://reader036.fdocuments.net/reader036/viewer/2022062303/558519b5d8b42ada748b460a/html5/thumbnails/42.jpg)
ElementalSource, LLC
Understanding indent formula
• concat($side-col-width, ' + (', string($level - 1), ' * ', $toc.toc-indent, ') + ', $toc.text-indent)– 25pt + (0 * 14pt) + 30pt = 55pt– 25pt + (1 * 14pt) + 30pt = 69pt– 25pt + (2 * 14pt) + 30pt = 83pt
• To play with the formula, adjust values for– toc.toc-indent– toc.text-indent
![Page 43: Custom PDFs from the DITA OT](https://reader036.fdocuments.net/reader036/viewer/2022062303/558519b5d8b42ada748b460a/html5/thumbnails/43.jpg)
ElementalSource, LLC
Include +/- levels in TOC
• Default is 4• Controlled by tocMaximumLevel
– Defined in topic2fo.xsl, topic2fo_1.0.xsl– You can hardcode in your customization
• toc.xsl:– <xsl:if test="$topicLevel < $tocMaximumLevel">– <xsl:if test="$topicLevel < 3">
![Page 44: Custom PDFs from the DITA OT](https://reader036.fdocuments.net/reader036/viewer/2022062303/558519b5d8b42ada748b460a/html5/thumbnails/44.jpg)
ElementalSource, LLC
Remove the mini-TOC
• ANT build file:– <property name="args.chapter.layout" value="BASIC"/>
![Page 45: Custom PDFs from the DITA OT](https://reader036.fdocuments.net/reader036/viewer/2022062303/558519b5d8b42ada748b460a/html5/thumbnails/45.jpg)
ElementalSource, LLC
Format index page numbers
• Copy index-attr.xsl, index.xsl to your customization• Find index-page-citation-list (in index.xsl)• Put whole xsl:if inside <fo:inline>• Call attribute set __index__page__link• Add attributes to __index__page__link (index-attr.xsl)
![Page 46: Custom PDFs from the DITA OT](https://reader036.fdocuments.net/reader036/viewer/2022062303/558519b5d8b42ada748b460a/html5/thumbnails/46.jpg)
ElementalSource, LLC
Omit top-level index page #s
• In index.xsl:
<xsl:when test="opentopic-index:index.entry">
<!--<xsl:for-each select="child::opentopic-index:refID[last()]">
<fo:inline index-key="{@value}"/>
</xsl:for-each>-->
</xsl:when>
<xsl:otherwise>
...
• This is a complete kludge but the list is silent…any better ideas?
![Page 47: Custom PDFs from the DITA OT](https://reader036.fdocuments.net/reader036/viewer/2022062303/558519b5d8b42ada748b460a/html5/thumbnails/47.jpg)
ElementalSource, LLC
Dynamically scale images
• “Create a chart note”– Image is way too big
• commons-attr.xsl– “image” attribute set:<xsl:attribute
name="content-width">scale-to-fit</xsl:attribute>
<xsl:attribute name="content-height">100%</xsl:attribute>
<xsl:attribute name="width">100%</xsl:attribute>
<xsl:attribute name="scaling">uniform</xsl:attribute>
• Watch out for width-height ratios!
![Page 48: Custom PDFs from the DITA OT](https://reader036.fdocuments.net/reader036/viewer/2022062303/558519b5d8b42ada748b460a/html5/thumbnails/48.jpg)
ElementalSource, LLC
Why didn’t I…
…Talk more about how to format specific elements?
• Because that’s the easiest thing to do!– Once you find the correct attribute set, it’s a matter of adding
a new attribute or changing the value of an existing one.
![Page 49: Custom PDFs from the DITA OT](https://reader036.fdocuments.net/reader036/viewer/2022062303/558519b5d8b42ada748b460a/html5/thumbnails/49.jpg)
ElementalSource, LLC
Frame-FO crosswalk
1. (attribute set name)2. text-indent3. margin-left4. margin-right5. text-align6. margin-top/
space-above7. margin-bottom/
space-below8. line-height9. line-height-shift-
adjustment
![Page 50: Custom PDFs from the DITA OT](https://reader036.fdocuments.net/reader036/viewer/2022062303/558519b5d8b42ada748b460a/html5/thumbnails/50.jpg)
ElementalSource, LLC
Frame-FO crosswalk
1. font-family2. font-size3. font-style4. font-weight5. text-transform6. color7. letter-spacing8. font-stretch9. xml:lang
![Page 51: Custom PDFs from the DITA OT](https://reader036.fdocuments.net/reader036/viewer/2022062303/558519b5d8b42ada748b460a/html5/thumbnails/51.jpg)
ElementalSource, LLC
Frame-FO crosswalk
10. text-decoration11. text-decoration12. text-decoration13. baseline-shift14. font-variant
![Page 52: Custom PDFs from the DITA OT](https://reader036.fdocuments.net/reader036/viewer/2022062303/558519b5d8b42ada748b460a/html5/thumbnails/52.jpg)
ElementalSource, LLC
Frame-FO crosswalk
1. break-before;page-break-before
2. keep-with-next.within-page/keep-together
3. keep-with-previous.within-page/ keep-together
4. orphans, widows5. span6. fo:float*7. relative-align
![Page 53: Custom PDFs from the DITA OT](https://reader036.fdocuments.net/reader036/viewer/2022062303/558519b5d8b42ada748b460a/html5/thumbnails/53.jpg)
ElementalSource, LLC
Frame-FO crosswalk
1. hyphenation-ladder-count
2. hyphenation-remain-character-count
3. hyphenation-push-character-count
4. hyphenate;hyphenation-keep
5. word-spacing6. border-top*7. border-bottom*
![Page 54: Custom PDFs from the DITA OT](https://reader036.fdocuments.net/reader036/viewer/2022062303/558519b5d8b42ada748b460a/html5/thumbnails/54.jpg)
ElementalSource, LLC
Other resources
• Jarno Elovirta's web-based PDF plug-in generator: http://dita-generator.appspot.com/pdf-plugin/
• Patrick Quinlan's (Ditanauts.org) mypdf plug-in:http://sourceforge.net/p/mypdf/home/Home/
• Suite Solutions’ DITA-OT webinars:http://www.suite-sol.com
• Custom PDFs from the DITA Open Toolkit, Leigh WhiteXML Press, 2012