Custom PDFs from the DITA OT

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


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!

Ask yourself…

…which is more important:
– perfect pages
– more time to spend creating quality content


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


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


What happens


Quick tour of the FO plug-in

• DITA-OTdemofo:


The cfg folder

• DITA-OTdemofocfg:

Attribute sets to Images associated
control with the
appearance of customization
elements

Stylesheets to
control Language-specific
processing and variables for
behavior of “boilerplate” text;
elements header/footer
definitions; note
image paths


Attribute sets

• Grouped by element “type” (lists, links, tables, etc.) or
domain (ui, pr, etc.)
• Everything else is in commons-attr.xsl


Attribute sets

• Expect to see the attributes in the default sets
• If you customize &
remove attributes,
OT “fills them back
in” from the default


Attribute sets

• Can call other attribute sets:


Attribute sets

• Called by the stylesheets in
DITA-OTdemofoxsl
• 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
– _fop: Apache FOP


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


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


XSL

• Some files specific to FO processors:
– _axf: Antenna House
– _xep: XEP
– _fop: Apache FOP


_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


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.


Bored? Confused?


Okay, let’s make a PDF!

• Multiple ditamaps
• Bookmap
• ANT build file
– DITA-OTsamplesant_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


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


Create your own customization

• In IntellContfoattrs, rename custom.xsl.orig
– Rename the one in IntellContfoxsl, 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


basic-settings.xsl

• Copy to your customization


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


Rearrange info in headers, footers

• Copy en.xml to your customization
• Copy static-content.xsl to your customization


static-content.xsl

• insertBodyOddHeader
• insertBodyEvenHeader
– 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"/>
– <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()"/>


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”


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>


Change inside, outside margins

• basic-settings.xsl
– page-margin-inside
– page-margin-outside


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)


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


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)


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


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


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


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


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


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


Remove the mini-TOC

• ANT build file:
– <property name="args.chapter.layout" value="BASIC"/>


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)


Omit top-level index page #s

• In index.xsl:
<xsl:when test="opentopic-index:index.entry">

</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
– “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!
– 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
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
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
14. font-variant


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, widows
5. span
6. fo:float*
7. relative-align

Frame-FO crosswalk

1. hyphenation-ladder-
count
2. hyphenation-remain-
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:
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 White
XML Press, 2012

Contact me

Leigh White

elementalsource@gmail.com
678.467.7706


Custom PDFs from the DITA OT

Empfohlen

Empfohlen

Weitere ähnliche Inhalte

Andere mochten auch

Andere mochten auch (20)

Ähnlich wie Custom PDFs from the DITA OT

Ähnlich wie Custom PDFs from the DITA OT (20)

Mehr von Leigh White

Mehr von Leigh White (8)

Kürzlich hochgeladen

Kürzlich hochgeladen (20)

Custom PDFs from the DITA OT