Post on 14-Dec-2014
description
Customizing PDF output
from the DITA Open Toolkit
Leigh White
ElementalSource, LLC
Me, me, me
• Background: English, Theoretical Linguistics
• NOT a programmer or stylesheet developer
• 20+ years as a content creator
ElementalSource, LLC
• 20+ years as a content creator
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!
ElementalSource, LLC
• 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!
Ask yourself…
…which is more important:
– perfect pages
– more time to spend creating quality content
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
ElementalSource, LLC
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
FO plug-in
• Originally developed to fill in the “hardcopy” gap
• Currently maintained by Suite Solutions
• Several folks working on improvements or complete
ElementalSource, LLC
• Several folks working on improvements or complete
re-writes
• It ain’t pretty but it works
What happens
ElementalSource, LLC
Quick tour of the FO plug-in
• DITA-OT\demo\fo:
ElementalSource, LLC
The cfg folder
• DITA-OT\demo\fo\cfg:
Attribute sets to
control Images associated
with the
ElementalSource, LLC
Language-specific
variables for
“boilerplate” text;
header/footer
definitions; note
image paths
control
appearance of
elements
Stylesheets to
control
processing and
behavior of
elements
with the
customization
ElementalSource, LLC
Attribute sets
• Grouped by element “type” (lists, links, tables, etc.) or
domain (ui, pr, etc.)
• Everything else is in commons-attr.xsl
ElementalSource, LLC
• Everything else is in commons-attr.xsl
Attribute sets
• Expect to see the attributes in the default sets
• If you customize &
remove attributes,
ElementalSource, LLC
remove attributes,
OT “fills them back
in” from the default
Attribute sets
• Can call other attribute sets:
ElementalSource, LLC
Attribute sets
• Called by the stylesheets in
DITA-OT\demo\fo\xsl
• Use the attribute set name to find the xsl template OR
ElementalSource, LLC
• Use the attribute set name to find the xsl template OR
use the xsl template to find the attribute set
Attribute sets
• Some files are specific to FO processors:
– _axf: Antenna House
– _xep: XEP
ElementalSource, LLC
– _fop: Apache FOP
basic-settings.xsl
• Variables that define:
– page dimensions
– margins
ElementalSource, LLC
– 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
XSL
• Lots of these but many you probably won’t touch
• Grouped by element “type” (lists, links, tables, etc.) or
domain (ui, pr, etc.)
ElementalSource, LLC
domain (ui, pr, etc.)
– Names match the attribute set files
• Everything else is in commons.xsl
– Kitchen sink
XSL
• Some files specific to FO processors:
– _axf: Antenna House
– _xep: XEP
ElementalSource, LLC
– _fop: Apache FOP
_1.0 files
• Sometimes replace original file:
– bookmarks_1.0.xsl
– front-matter_1.0.xsl
ElementalSource, LLC
• Sometimes supplement original file:
– commons_1.0.xsl
– index_1.0.xsl
– table_1.0.xsl
– toc_1.0.xsl
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
ElementalSource, LLC
• Creates variables from map metadata that are available
throughout the build in headers, footers, cover pages,
etc.
ElementalSource, LLC
Bored? Confused?
Okay, let’s make a PDF!
• Multiple ditamaps
• Bookmap
• ANT build file
ElementalSource, LLC
• ANT build file
– DITA-OT\samples\ant_sample
• Batch file
– Copy startcmd.bat from DITA-OT
A couple of quick changes
• ANT build file:
– Change FO processor
– Retain the topic.fo file
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
ElementalSource, LLC
• Rename and edit catalog.xml.orig
• Call your customization from your ANT build file
• Copy a file into your customization
– commons-attr.xsl
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
ElementalSource, LLC
• 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
basic-settings.xsl
• Copy to your customization
ElementalSource, LLC
Add bookmap metadata to cover
• Copy root-processing.xsl to your customization
• Create variables
– productRev
ElementalSource, LLC
– productRev
– bookNo
• Copy front-matter_1.0.xsl to your customization
• Add fo:block elements that contain variables
Rearrange info in headers, footers
• Copy en.xml to your customization
• Copy static-content.xsl to your customization
ElementalSource, LLC
static-content.xsl
• insertBodyOddHeader
• insertBodyEvenHeader
– Comment out <prodname>, <pagenum>
ElementalSource, LLC
– Comment out <prodname>, <pagenum>
• insertBodyOddFooter
• insertBodyEvenFooter
– Comment out <heading>
– Add <prodname>, <version>
en.xml
• <variable id="Body odd footer"/>
– <param ref-name="prodname"/> <param ref-
name="version"/><param ref-name="pagenum"/>
• <variable id="Body even footer"/>
ElementalSource, LLC
• <variable id="Body even footer"/>
– <param ref-name="pagenum"/><param ref-
name="prodname"/> <param ref-name="version"/>
Wait!
• Page numbers are not on the outside in even footers
• basic-settings.xsl:
– <xsl:variable name="mirror-page-margins" select="true()"/>
ElementalSource, LLC
– <xsl:variable name="mirror-page-margins" select="true()"/>
Justify footers
• static-content.xsl:
– <fo:leader leader-pattern="space"/>
– Be sure to put in right place!
ElementalSource, LLC
• Copy static-content-attr.xsl to your customization
• Attribute sets odd__footer, even__footer
– text-align=“justify”
– text-align-last=“justify”
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
ElementalSource, LLC
• 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>
Change inside, outside margins
• basic-settings.xsl
– page-margin-inside
– page-margin-outside
ElementalSource, LLC
Align footers with margins
• static-content-attr.xsl
– odd__footer
• start-indent ($page-margin-inside)
• end-indent ($page-margin-outside)
ElementalSource, LLC
• end-indent ($page-margin-outside)
– even__footer
• start-indent ($page-margin-outside)
• end-indent ($page-margin-inside)
Why are *all* the pages…
…yellow and pink, not just body pages?
• By default, all page types call region-body.odd and
ElementalSource, LLC
• 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
Restart page numbering
• Copy commons.xsl to your customization
• startPageNumbering template:
– Comment out xsl:if
ElementalSource, LLC
– Comment out xsl:if
• processTopicAppendix template:
– Add <xsl:call-template name="startPageNumbering"/>
– (It’s missing for appendix)
Add an image to the title page
• Background image
– Can also add within flow
• layout-masters.xsl:
ElementalSource, LLC
• layout-masters.xsl:
– Change front-matter-first to use region-
body__frontmatter.first
• layout-masters-attr.xsl:
– Create region-body__frontmatter.first
Change fonts
• Copy font-mappings.xml to your customization
• Uncomment entry in catalog
• Add Verdana to “Sans”
ElementalSource, LLC
• Add Verdana to “Sans”
• Add Palatino to “Serif”
• Processor-dependent:
– XEP: edit xep.xml
– FOP: edit fop.xconf
– AH: edit font-config.xml
Format TOC levels
• Copy toc.xsl and toc-attr.xsl to your customization
• Copy font-weight attribute
– Add different colors for levels
ElementalSource, LLC
– Add different colors for levels
– Useful model for any level-based attribute
TOC attribute set interaction
• __toc__topic__content is overwritten by
– __toc__chapter__content
– __toc__appendix__content
ElementalSource, LLC
– __toc__part__content
when processing bookmap
• Many more examples
Understanding indent formula
• concat($side-col-width, ' + (', string($level - 1), ' * ',
$toc.toc-indent, ') + ', $toc.text-indent)
– 25pt + (0 * 14pt) + 30pt = 55pt
ElementalSource, LLC
– 25pt + (1 * 14pt) + 30pt = 69pt
– 25pt + (2 * 14pt) + 30pt = 83pt
• To play with the formula, adjust values for
– toc.toc-indent
– toc.text-indent
Include +/- levels in TOC
• Default is 4
• Controlled by tocMaximumLevel
– Defined in topic2fo.xsl, topic2fo_1.0.xsl
ElementalSource, LLC
– 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">
Remove the mini-TOC
• ANT build file:
– <property name="args.chapter.layout" value="BASIC"/>
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>
ElementalSource, LLC
• Put whole xsl:if inside <fo:inline>
• Call attribute set __index__page__link
• Add attributes to __index__page__link (index-attr.xsl)
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}"/>
ElementalSource, LLC
<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?
Dynamically scale images
• “Create a chart note”
– Image is way too big
• commons-attr.xsl
ElementalSource, LLC
• 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!
Why didn’t I…
…Talk more about how to format specific elements?
• Because that’s the easiest thing to do!
ElementalSource, LLC
• 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.
Frame-FO crosswalk
1. (attribute set name)
2. text-indent
3. margin-left
4. margin-right
5. text-align
ElementalSource, LLC
5. text-align
6. margin-top/space-above
7. margin-bottom/space-below
8. line-height
9. line-height-shift-adjustment
Frame-FO crosswalk
1. font-family
2. font-size
3. font-style
4. font-weight
ElementalSource, LLC
4. font-weight
5. text-transform
6. color
7. letter-spacing
8. font-stretch
9. xml:lang
Frame-FO crosswalk
10. text-decoration
11. text-decoration
12. text-decoration
13. baseline-shift
ElementalSource, LLC
13. baseline-shift
14. font-variant
Frame-FO crosswalk
1. break-before;
page-break-before
2. keep-with-next.within-
page/keep-together
ElementalSource, LLC
3. keep-with-
previous.within-page/
keep-together
4. orphans, widows
5. span
6. fo:float*
7. relative-align
Frame-FO crosswalk
1. hyphenation-ladder-
count
2. hyphenation-remain-
character-count
ElementalSource, LLC
character-count
3. hyphenation-push-
character-count
4. hyphenate;
hyphenation-keep
5. word-spacing
6. border-top*
7. border-bottom*
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:
ElementalSource, LLC
• 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
Contact me
Leigh White
ElementalSource, LLC
Leigh White
ElementalSource, LLC
elementalsource@gmail.com
678.467.7706