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

Recommandé

Recommandé

Contenu connexe

En vedette

En vedette (20)

Similaire à Custom PDFs from the DITA OT

Similaire à Custom PDFs from the DITA OT (20)

Plus de Leigh White

Plus de Leigh White (8)

Dernier

Dernier (20)

Custom PDFs from the DITA OT