Getting Started with PDF Publishing from the DITA Open Toolkit

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


• 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!


• 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


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


• 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-OT\demo\fo:


The cfg folder

• DITA-OT\demo\fo\cfg:

Attribute sets to

control Images associated

with the


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

Attribute sets

• Grouped by element “type” (lists, links, tables, etc.) or

domain (ui, pr, etc.)

• Everything else is in commons-attr.xsl


• Everything else is in commons-attr.xsl

Attribute sets

• Expect to see the attributes in the default sets

• If you customize &

remove attributes,


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-OT\demo\fo\xsl

• Use the attribute set name to find the xsl template OR


• 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




– 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


• 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


• 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


Create your own customization

• Copy and rename Customization folder

– Don’t make changes to the default files!

• Rename and edit catalog.xml.orig


• 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


• 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


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


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


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


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


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


• 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


• 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


– 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:


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


– 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


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


• 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


• 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!


• 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


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


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


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


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:


• 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


Leigh White


[email protected]

678.467.7706

Getting Started with PDF Publishing from the DITA Open Toolkit

Technology

Transcript of Getting Started with PDF Publishing from the DITA Open Toolkit