DITA for Print

DITA for Print

-

English
476 Pages

Description

As DITA has become more and more popular, demand has increased for tools that can produce high quality PDFs from DITA content. The DITA Open Toolkit provides a basic PDF capability, but nearly any real-world application will require customization. Leigh White's new book, DITA for Print, takes you through the process of building a print customization plugin for the DITA Open Toolkit that will give you control over your PDF output.


DITA for Print is for anybody who wants to learn how to create PDFs using the DITA Open Toolkit without learning everything there is to know about XSL-FO, XSLT, or XPath, or even about the DITA Open Toolkit itself. DITA for Print is written for non-programmers, by a non-programmer, and although it is written for people who have a good understanding of the DITA standard, you don't need a technical background to get custom PDFs up and running quickly.


Subjects

Informations

Published by
Published 15 October 2013
Reads 31
EAN13 9781492001881
Language English
Document size 1 MB

Legal information: rental price per page €. This information is given for information only in accordance with current legislation.

Report a problem

3

22




DITA for Print: A DITA
Open Toolkit Workbook
DITA Open Toolkit 1.8
Leigh W. White
http://xmlpress.netDITA for Print: A DITA Open Toolkit Workbook
©Copyright 2013 Leigh W. White
All rights reserved. No part of this book may be reproduced or transmitted in any form or
by any means without the prior written permission of the copyright holder, except for the
inclusion of brief quotations in a review.
Credits
DITA and the DITA logo are used by permission from the OASIS open standards consortium.
Disclaimer
The information in this book is provided on an "as is" basis, without warranty. While every
effort has been taken by the author and XML Press in the preparation of this book, the
author and XML Press shall have neither liability nor responsibility to any person or entity
with respect to loss or damages arising from the information contained in this book.
This book contains links to third-party web sites that are not under the control of the author
or XML Press. The author and XML Press are not responsible for the content of any linked
site. Inclusion of a link in this book does not imply that the author or XML Press endorses
or accepts any responsibility for the content of that third-party site.
The author and XML Press are not responsible for any damage to equipment or loss of data
that might occur as a result of downloading and/or installing any software mentioned herein.
Nor are the author and XML Press responsible for any penalties that might be incurred due
to illegal download, installation or usage of any software mentioned herein.
Trademarks
XML Press and the XML Press logo are trademarks of XML Press.
All terms mentioned in this book that are known to be trademarks or service marks have
been capitalized as appropriate. Use of a term in this book should not be regarded as affecting
the validity of any trademark or service mark.
XML Press
Laguna Hills, CA
http://xmlpress.net
First Edition
ISBN: 978-1-937434-05-2 (print)
ISBN: 978-1-937434-27-4 (ebook)Table of Contents
List of Figures ............................................................................................................................... 15
Preface ...........................................................................................................................................19
Why this book? .................................................................................................................... 19
Who is this book for? ......................................................................................................... 20
What’s not covered in this book ..................................................................................... 21
Keepin’ it real ........................................................................................................................ 21
About me ............................................................................................................................... 22
Contact me ............................................................................................................................ 22
Acknowledgements .............................................................................................................23
Chapter 1: Introduction ........................................................................... 25
What you’ll need .................................................................................................................. 25
Useful resources 27
Some conventions ................................................................................................................ 29
Comment, comment, comment…test, test, test ......................................................... 30
Chapter 2: Custom PDF plugin creation ............................................... 33
What is a PDF plugin and why do you need one? ........................................................ 33
Organization of the org.dita.pdf2 plugin ......................................................................... 35
DITA Open Toolkit 1.5 and earlier ................................................................................. 39
Exercise: Download and install the DITA Open Toolkit ............................................ 39 Create your own PDF plugin ........................................................................... 41
Exercise: Integrate your plugin into the DITA-OT ...................................................... 45 Add an attribute set file to your plugin ......................................................... 46
Exercise: Add an XSLT stylesheet to your plugin ........................................................ 47Why not use a single custom file for my changes? ....................................................... 47
Exercise: Add a localization variable file to your plugin .............................................. 49
Wrap-up .................................................................................................................................49
Chapter 3: DITA Open Toolkit builds ................................................... 51
What is an ANT build file? .................................................................................................51
Exercise: Create an ANT build file .................................................................................. 52 Run an ANT build file (Windows) .................................................................. 55
Exercise: Run an ANT build file (Mac, Linux) ................................................................57 Create a batch file to launch an ANT build (Windows) ........................... 58
Exercise: Create a shell file to launch an ANT build (Mac, Linux) ...........................60 Test your plugin .................................................................................................. 62
Exercise: Use a specific PDF renderer ............................................................................ 63
Other things you can do .................................................................................................... 64
The topic.fo file .............................................................................................................. 64
Exercise: Retain the topic.fo file for troubleshooting ........................................... 67
Chapter 4: Fonts ........................................................................................ 69
About fonts in the PDF plugin .......................................................................................... 69
Font specifications ................................................................................................................ 70
Files you need ....................................................................................................................... 71
Exercise: Select basic fonts for your plugin .................................................................... 71
Other things you can do .................................................................................................... 74
Exercise: Use a custom font family ........................................................................... 74
Chapter 5: Attribute sets ......................................................................... 75
What are attribute set files? .............................................................................................. 75
How attribute set defaults work ...................................................................................... 76
Special attributes for XEP, Antenna House, and FOP ................................................. 78Which attribute set do you customize? .......................................................................... 79
The closest attribute set wins ........................................................................................... 81
Attribute sets that call other attribute sets ................................................................... 82
Basic-settings variables in attribute sets ......................................................................... 83
Exercise: Create a new set ............................................................................... 85 Call a new attribute set .................................................................................... 86
Exercise: Conditionalize an attribute set ........................................................................ 87
Chapter 6: Localization variables ........................................................... 89
What are localization variables? ....................................................................................... 89
Literal characters and numeric character references .................................................. 91
Exercises ................................................................................................................................92
Other things you can do .................................................................................................... 92
Exercise: Create a localization variables file ...........................................................92
Chapter 7: Page masters .......................................................................... 93
Page masters and regions in the PDF plugin .................................................................. 93
Default page masters, regions and attribute sets ......................................................... 95
Page specifications ................................................................................................................ 97
Files you need ....................................................................................................................... 99
Completing these exercises ............................................................................................... 99
Exercise: Set up double-sided pagination ..................................................................... 100 Set page dimensions ........................................................................................ 100
Exercise: Set page margins 101 Set up body regions ......................................................................................... 103
Exercise: Set up header and footer regions ................................................................ 106 Set margins for the front cover page .......................................................... 107
Other things you can do .................................................................................................. 110Exercise: Eliminate blank last pages ........................................................................ 110 Design a separate layout for first pages ............................................... 111
Exercise: Use the bookmap page sequence for maps ........................................ 113 Add a background image to a page ....................................................... 115
Exercise: Change the number of columns on a master page ............................ 117
Specifying landscape pages for a topic .................................................................... 119
Exercise: Set up a landscape page ........................................................................... 120 Assign a page to a topic ........................................................ 124
Chapter 8: Page headers and footers .................................................. 129
About headers and footers ............................................................................................. 129
PDF plugin defaults for headers and footers ............................................................... 130
Where does header and footer information come from? ....................................... 131
Metadata variables for headers and footers ................................................................ 132
Models to use for map metadata ................................................................................... 133
DITA element classes ....................................................................................................... 136
Header and footer specifications 139
Files you need ..................................................................................................................... 141
Completing these exercises ............................................................................................ 141
Header setup ...................................................................................................................... 142
Exercise: Set up headers that include external files ............................................ 142 Set up that include boilerplate text .......................................144
Exercise: Set up headers that include generated text ........................................148
Adding information from the map to headers ..................................................... 151
Exercise: Create metadata variables for headers and footers ................... 151 Add fallback header and footer variables to the localization
variables file ........................................................................................................... 153
Exercise: Set up headers that include map metadata .................................. 154Footer setup ....................................................................................................................... 156
Exercise: Set up footers ............................................................................................ 156 Create new header and footer definitions ......................................... 159
Exercise: Add chapter, appendix, or part numbers to page numbers ............ 161 Restart page numbering in each chapter, appendix or part ............ 164
Header and footer formatting ........................................................................................ 165
Exercise: Set top and bottom margins for headers and footers ...................... 165 Set left and right margins for headers and footers ............................ 167
Exercise: Format the appearance of headers and footers ................................. 168 Justify elements of a header or footer ................................................. 171
Exercise: Add space around a header or footer image ...................................... 173
Other things you can do .................................................................................................. 174
Exercise: Put header or footer content on multiple lines ................................. 174 Add the current date to headers and footers .................................... 176
Exercise: Add a prefix to non-body page numbers ............................................. 178 Use a specific title level in the running header ................................... 179
Chapter 9: Cover pages .......................................................................... 181
Front cover customization .............................................................................................. 181
Cover specifications ................................................................................................... 181
Files you need .............................................................................................................. 183
Exercise: Add bookmap information to the front cover ................................... 184 Format information on the cover page ................................................ 187
Exercise: Place cover page information in a specific location ........................... 188
Back cover creation and customization ........................................................................ 189
Back cover workflow steps ...................................................................................... 189
Exercise: Create and call a back cover template ................................................. 190 Create back cover page sequence ........................................................ 191Exercise: Add back cover page master attribute sets ........................................ 192 Add content to the back cover ............................................................. 193
Exercise: Format content on the back cover ....................................................... 195
Other things you can do .................................................................................................. 197
Exercise: Insert text based on language ................................................................. 197 Eliminate the front cover page ............................................................... 199
Exercise: index page masters when including a back cover
page ................................................................................................................................200
Chapter 10: Titles, body text, and notes ............................................ 201
General text formatting specifications .......................................................................... 201
Files you need ..................................................................................................................... 202
Title formatting .................................................................................................................. 203
How topic title attribute sets work ....................................................................... 203
Exercise: Format topic titles .................................................................................... 205 Format section titles ................................................................................. 206
Exercise: Format chapter, appendix, or part titles .............................................. 207 Format the chapter, appendix, or part autonumber ......................... 208
Exercise: Change the chapter number label and format ................................... 209 Put the chapter, appendix or part label, number, and title on the
same line ....................................................................................................................... 210
Text formatting .................................................................................................................. 213
Formatting body text ................................................................................................. 213
Exercise: Set body font sizes .................................................................................... 215 Format code samples and messages ..................................................... 216
Exercise: Set the default line height ........................................................................ 217 Format trademark, registered trademark, service mark, and
copyright symbols ....................................................................................................... 217Notes formatting ............................................................................................................... 220
Exercise: Format note labels .................................................................................... 220 Change the label for a note type ........................................................... 221
Exercise: Delete the label for a note type ............................................................ 222 Change or delete note icons .................................................................. 223
Exercise: Format note text ....................................................................................... 224 Add left and right borders to notes ...................................................... 225
Exercise: Use a custom label for other-type notes ............................................. 225
Other things you can do .................................................................................................. 227
Exercise: Mark non-standard items for resolution 227 Eliminate the chapter, appendix, or part label and number ............ 228
Exercise: Format note labels as sideheads ............................................................ 229 Rotate text 234
Exercise: Include a topic’s ID in the PDF .............................................................. 237 Add a prefix to a topic title ....................................................................238
Chapter 11: Lists ...................................................................................... 241
Hints on working with list-related attribute sets ....................................................... 241
List specifications ............................................................................................................... 243
Files you need ..................................................................................................................... 243
Exercise: Create multiple bullet formats for unordered lists .................................. 244 Create numbering formats for ordered lists ............................. 246
Exercise: Create a checklist ............................................................................................ 248
Other things you can do .................................................................................................. 249
Exercise: Change the amount of space between a number/bullet and
text .................................................................................................................................249
Exercise: Use an image as a bullet .......................................................................... 250 Format definition lists as a list instead of a table ............................... 251Chapter 12: Task topics ......................................................................... 255
Task topic specifications .................................................................................................. 255
Files you need ..................................................................................................................... 256
Task step formatting tips ................................................................................................. 257
Exercise: Change the label for optional steps ............................................................. 257 labels for task sections ..................................................................... 258
Exercise: Format task section labels and text 259 Format step and substep numbers ............................................................... 261
Other things you can do .................................................................................................. 263
Exercise: Count the number of steps in a task .................................................... 263 Create links to steps within the same task ......................................... 264
Chapter 13: Tables .................................................................................. 269
Table specifications ............................................................................................................ 269
Files you need ..................................................................................................................... 270
Fun with table rules ........................................................................................................... 270
Table border overrides .................................................................................................... 272
Exercise: Force table column widths to be respected .............................................. 273 Change or delete the label for a table title ................................................275
Exercise: Format the table heading row ....................................................................... 275 Format table cell text ...................................................................................... 276
Exercise: Format table rules ............................................................................................ 276 Format the table title 279
Exercise: Place titles below tables ................................................................................. 279 Add chapter, appendix or part numbers to table titles .......................... 281
Other things you can do .................................................................................................. 283
Exercise: Add a bottom table rule when a table breaks across a page .......... 283Exercise: Number table cells .................................................................................... 284 Omit the table heading on subsequent pages ..................................... 287
Exercise: Fix table row ruling ................................................................................... 288
Chapter 14: Images ................................................................................. 291
Files you need ..................................................................................................................... 291
Exercise: Change or delete the label for a figure title ..............................................292 Format figure titles .......................................................................................... 292
Exercise: Add chapter, appendix or part numbers to figure titles ......................... 293 Place titles above images ................................................................................ 294
Exercise: Dynamically scale images to the page width .............................................. 295 Change the default alignment for all images 297
Chapter 15: Related links, cross-references, and footnotes ........... 301
General link formatting specifications ........................................................................... 302
Files you need ..................................................................................................................... 302
General links and cross-references ............................................................................... 303
Exercise: Change the format of cross-references ............................................... 303 the on-page text for related links .......................................... 304
Related links ........................................................................................................................305
Exercise: Include related links in a PDF ................................................................. 305 Change or delete the “Related Links” label ........................................ 305
Exercise: Add a divider above the “Related Links” section .............................. 306 Change the format of related links ....................................................... 307
Footnotes ............................................................................................................................308
Exercise: Change the appearance of footnote text and callouts ..................... 308 the footnote separator line .....................................................309
Exercise: Add brackets around footnote callouts ............................................... 309Other things you can do .................................................................................................. 311
Exercise: Hide short descriptions in related links ............................................... 311
Chapter 16: Table of Contents .............................................................. 313
How TOC attribute sets interact .................................................................................. 313
Title levels in bookmaps and ditamaps ......................................................................... 315
TOC specifications ............................................................................................................ 316
Files you need ..................................................................................................................... 317
Exercise: Add a TOC to a PDF ...................................................................................... 318 Change the title of the TOC 318
Exercise: Format the TOC title ..................................................................................... 319 Add or remove entry levels from the TOC ..............................................319
Exercise: Apply different formatting to different TOC entry levels ...................... 320 Format page numbers in the TOC .............................................................. 323
Exercise: Add chapter, appendix or part number to TOC page numbers .......... 323 Change the leader in TOC entries 325
Exercise: Remove leaders from TOC entries ............................................................. 325 Adjust indents for TOC entries ................................................................... 326
Mini-TOC ............................................................................................................................329
Exercise: Change or delete the title for the mini-TOC ..................................... 331 Format mini-TOC links ............................................................................ 331
Exercise: Add page numbers to mini-TOC entries ............................................ 332 Remove the mini-TOC from a table .................................................... 333
Exercise: Insert a page break after the mini-TOC .............................................. 334 Eliminate the mini-TOC .......................................................................... 335
Other things you can do .................................................................................................. 335
Exercise: Change or delete chapter/appendix/part prefixes in TOC
entries ............................................................................................................................335Exercise: Omit page numbers for TOC entry levels .......................................... 336 Change TOC numbering formats .......................................................... 338
Exercise: Allow line breaks in TOC entries ......................................................... 338 Use Roman numerals for TOC page numbers .................................. 339
Exercise: Eliminate the TOC from a PDF ............................................................. 340 Omit the TOC bookmark from a map-based PDF ........................... 341
Chapter 17: Index .................................................................................... 343
This chapter is different… ............................................................................................... 343
Index entry levels ............................................................................................................... 343
The curious case of page numbers on main index entries ....................................... 344
Index specifications ........................................................................................................... 345
Files you need ..................................................................................................................... 345
Exercise: Add an index to your PDF ............................................................................. 346 Change the title of the index ........................................................................ 347
Exercise: Format the index title ..................................................................................... 348 Format index letter headings 348
Exercise: Format index entries ....................................................................................... 349 Format index page numbers .......................................................................... 350
Exercise: Adjust indents for index entries ................................................................... 351
Other things you can do .................................................................................................. 352
Exercise: Change the column count on index pages (XEP) .............................. 353 the column count on index pages (Antenna House) ......... 353
Exercise: Add chapter numbers to index entries ................................................ 354 Delete the index from a map-based PDF ............................................ 355
Exercise: Delete the Index bookmark from a map-based PDF ........................ 357Chapter 18: List of Tables and List of Figures ................................... 359
List of Tables and List of Figures specifications .......................................................... 359
Files you need ..................................................................................................................... 360
Exercise: Add a List of Tables or List of Figures ........................................................ 360 Format the List of Tables and List of Figures titles .................................. 361
Exercise: Change the title of the List of Tables and List of Figures ....................... 362 Format page numbers in the List of Tables and Figures ......................... 362
Exercise: Format entries in the List of Tables and List of Figures .......................... 364 Add chapter or appendix numbers to table or figure numbers in the
List of Tables or List of Figures ...................................................................................... 365
Chapter 19: Bookmarks ......................................................................... 367
Files you need ..................................................................................................................... 367
Exercise: Add the chapter, appendix or part number to bookmarks ................... 368 Delete the Table of Contents bookmark ................................................. 369
Exercise: Delete the Index bookmark 370
Appendix A: Specifications used in these exercises ......................... 371 B: Attribute set lists and descriptions .............................. 381
Attribute set file list .......................................................................................................... 381
Common attribute sets .................................................................................................... 384
Domain sets ....................................................................................................... 397
Frontmatter attribute sets ............................................................................................... 401
Glossary attribute sets ..................................................................................................... 402
Index attribute sets ........................................................................................................... 402
Layout masters attribute sets ......................................................................................... 403
Link attribute sets .............................................................................................................. 405List attribute sets ............................................................................................................... 408
Lot-Lof attribute sets ........................................................................................................ 410
Map attribute sets .............................................................................................................. 411
Reference attribute sets ................................................................................................... 412
Static content attribute sets ............................................................................................ 413
Task element sets ............................................................................................. 418
Table attribute sets ........................................................................................................... 425
Table of Contents attribute sets .................................................................................... 429
Basic settings variables ...................................................................................................... 432
Appendix C: Localization variables list ............................................... 435 D: GetChapterPrefix template ........................................... 445
Appendix E: GetChapterPrefixForIndex template ........................... 447 F: Back cover template ........................................................ 449
Appendix G: Specialized element template creation ....................... 451 H: Paragraph and character formatting: word processing
applications to XSL-FO match-up ....................................................... 453List of Figures
Figure 1: Default OT organization .......................................................................................... 35
Figure 2: Plugins folder ....................................................................................... 36
Figure 3: org.dita.pdf2 organization ........................................................................................ 37
Figure 4: Plugin folder structure .............................................................................................. 42
Figure 5: Plugin folder structure - expanded ........................................................................ 44
Figure 6: Attribute merge in attribute sets ........................................................................... 77
Figure 7: Use of step-related attribute sets .......................................................................... 80
Figure 8: Interaction between attribute sets ........................................................................ 83
Figure 9: XSL-FO page regions ................................................................................................ 94
Figure 10: Body page diagram based on specifications ....................................................... 98
Figure 11: Page margin diagram ............................................................................................. 102
Figure 12: Body region without space above and below ................................................. 103
Figure 13: Body region with space above and below ....................................................... 104
Figure 14: Body region setup complete ............................................................................... 106
Figure 15: Front cover page margins diagram .................................................................... 109
Figure 16: Example of first body page .................................................................................. 113Figure 17: Example DRAFT stamp background image ..................................................... 116
Figure 18: Front cover page with background image ....................................................... 117
Figure 19: Two-column body page ....................................................................................... 118
Figure 20: Landscape page example ..................................................................................... 124
Figure 21: Map metadata precedence .................................................................................. 133
Figure 22: Example of a map with topicmeta ..................................................................... 134
Figure 23: Example of a bookmap with bookmeta ........................................................... 135
Figure 24: Attribute set priority processing ....................................................................... 138
Figure 25: Header and footer vertical alignment ............................................................... 166
Figure 26: Page footer with multiple lines .......................................................................... 174
Figure 27: Front cover example ............................................................................................ 182
Figure 28: Attribute sets for back cover ............................................................................. 192
Figure 29: Text blocks for back cover ................................................................................. 193
Figure 30: map topic levels and corresponding title attribute sets ............................... 204
Figure 31: Table with rotated header cells ......................................................................... 234
Figure 32: Degrees of text rotation ..................................................................................... 235
Figure 33: List-related attribute sets hierarchy ................................................................. 242
Figure 34: Nested unordered list structure ....................................................................... 245Figure 35: Example of numbered table cells for diagram caption ................................. 284
Figure 36: Left-aligned images ................................................................................................ 297
Figure 37: TOC entry attribute sets .................................................................................... 314
Figure 38: Attribute sets for pieces of TOC entry ........................................................... 314
Figure 39: Topics as chapters ................................................................................................ 316
Figure 40: TOC with text-indent=0 ..................................................................................... 327
Figure 41: TOC with text-indent=toc.text-indent ............................................................ 327
Figure 42: Mini-TOC example ............................................................................................... 330
Figure 43: Structure of index table ....................................................................................... 344Preface
Why this book?
Several years ago I sat down with the DITA Open Toolkit for the first time. I wasn’t new to XML or XSLT,
but I wasn’t an expert, either. Many cups of coffee and even more temper tantrums later, I had my first
PDF customization up and running. Along the way, I had help from individuals and organizations. I
attended webinars and conference sessions. Little by little, it all came together.
Back up to those last three sentences. It took a lot of different resources to enable me to put together that
first PDF customization, and that’s why I wrote this book. There was no single place where I, or anyone,
could find all the information needed. Frustrating? Oh, a little. It’s not that the information isn’t out there.
It’s just that it’s all over the place. Somewhere along the way it occurred to me that I ought to pull together
everything I’d learned and write it down.
This book began as a general reference to all of the most common changes you’d need to make to the
PDF plugin of the DITA Open Toolkit. I started down that road and realized it’d be like trying to describe
every star in the universe. Trying to cover even a reasonable subset of general XSL/XSL-FO customizations
would be almost impossible.
Then I considered that most future readers—like you—would already have been publishing PDFs using
something like FrameMaker or Microsoft Word. You already have a template that you need to reproduce
in XSL-FO. So I decided to create this book as a tutorial, to walk you through migrating a template to FO.
After a brief explanation of the structure of the DITA Open Toolkit’s PDF plugin, you’ll start with a
specification for the PDF you’re going to work towards in this book: master pages, header and footer
information, cover pages, heading formats, body text formats, image, list and table formats, table of
contents and index creation and formatting, and more.
By working through specific tasks, you will create an actual PDF plugin that you can apply to your own
template migration. So even though this book might not cover a specific kind of change, it probably covers
something similar enough that you can apply the logic to whatever you need to do.
One important thing: I’m not a theorist. I’m a busy writer and information architect who’s primarily
concerned with the how, not the why. This book is mostly about the how, but I try to give enough
background for you to understand what’s happening and apply it to other situations. If you want to20 DITA for Print: A DITA Open Toolkit Workbook
completely understand the why, there are good books and resources explain XML, XSL, and XSL-FO
thoroughly. I list a few of them in Why this book? (on page 19) and Useful resources (on page 27).
Who is this book for?
This book is for anybody who wants to learn how to create PDFs using the DITA Open Toolkit without
learning everything there is to know about XSL-FO, XSLT, XPath, or even the DITA Open Toolkit itself.
You’ll get the most out of this book if you
• already have a firm grasp of authoring in DITA, understand the elements and attributes your
organization uses, and can put together maps and bookmaps that represent the output you want;
• enjoy getting under the hood and are not afraid to try things, even if they don’t work at first;
• want to know only as much detail as necessary to accomplish a task and don’t need to know how the
watch works to tell the time.
In other words, this book is for people who are already fluent in DITA and want to get custom PDFs up
and running fast without a lot of technical background.
So, as you might expect, there’s not a full explanation of the architecture of the DITA Open Toolkit in
this book. There’s not even a full explanation of how the PDF plugin works. Everything here is designed
to tell you just as much as you need to know to do what you want to do. You don’t need to understand
the entire PDF transformation pipeline to understand how to change the header on even body pages.
There’s also not much discussion about DITA itself and how it works. This book isn’t a guide to DITA.
In fact, it assumes you already have a firm understanding of authoring in DITA—including how to use
the standard DITA formatting attributes and how to create maps and relationship tables that reflect
appropriate relationships between topics. If you are new to DITA, you’ll want to come up to speed on
authoring before you try to follow these tutorials.
This book focuses on the “out of the box” elements in DITA 1.2. Specialization is one of the most important
aspects of DITA: it lets you create a new element based on an existing element, where the new element
inherits some or all of the characteristics of the original one. Processing specialized elements is a whole
different ball of wax that isn’t covered in this edition of the book.
The PDF plugin in the Open Toolkit is not pretty. It’s had a lot of hands on it over the years, and it’s been
constantly updated to accommodate new features in DITA and the Open Toolkit while maintaining
backward compatibility as much as possible. Which is to say, the XSL is less than pristine—but it works.
A lot of really smart people are working on alternatives, and many of them advise complete rewrites to
sections of the PDF plugin. There’s nothing wrong with that, but this book is focused on working with
the plugin as-is, warts and all, and presenting the simplest, easiest-to-follow solutions for non-programmers.Preface 21
Undoubtedly, there are technically better and more efficient ways to accomplish many of the tasks in this
book. Especially with respect to the paths that select elements—many of them are inefficient and
over-inclusive. However, they’re based on the original code to keep your changes as simple and close to
original examples as possible. If you come up with any better mousetraps, please post them to the SuiteShare
Social Knowledgebase or the Yahoo DITA Users list so we can all benefit from your ideas.
One last thing. I’m based in the United States, so this book is necessarily weighted towards U.S. standards
such as inches, 8.5in x 11in paper, left-to-right word order, and so forth. In most cases, it should be pretty
easy to substitute your own standards for the ones in the examples. Where that’s not the case, let me
know, and I’ll consider it seed material for the next edition.
What’s not covered in this book
There are three significant areas in DITA 1.2 that I do not cover in this book:
• Glossaries
• Learning and Training elements
• Hazard Statement domain
These were introduced in DITA 1.2 and represent a huge gain in functionality. However, the current
release of the DITA Open Toolkit (version 1.8), has only limited support for them. Explaining how to
implement full support for these new elements is beyond the scope of a workbook, so I chose to leave
them out.
Keepin’ it real
This book was written entirely in DITA using <oXygen/> XML Author and was formatted using the
DITA Open Toolkit 1.8 using some of the same techniques you’ll learn about here.
Even after you’ve written DITA content and developed a PDF plugin to format attractive PDF output,
you still have to actually generate that output. The DITA Open Toolkit comes with a built-in tool to
generate PDFs from DITA: the Apache FOP renderer. You can also use a commercial renderer like
RenderX’s XEP or Antenna House (this book was rendered using XEP).
There’s absolutely nothing here that can’t be done with DITA and the Open Toolkit out of the box—plus
the custom PDF plugin this book will help you create. So let the book you hold in your hands (or look at
on your screen) be the proof that all this stuff really does work!22 DITA for Print: A DITA Open Toolkit Workbook
About me
Here’s the first thing I want you to know about me: I have degrees in English and Theoretical Linguistics.
I’ve been a bookstore clerk, a bank teller, a graphic designer, a graduate teaching assistant, a technical
writer, and an information architect. You’ll notice that neither “programmer” nor “developer” is on that
list. Aside from a few one-day classes in various software applications, I’ve never had any training in
computer languages or programming.
I say that first because I want to stress: if I can do this, you can. You don’t need to be a developer to get
serious mileage out of the DITA Open Toolkit. I’ve been professionally creating and publishing content
for over 20 years. During that time, I’ve worked with just about every desktop publishing application out
there. No doubt, wrestling beautiful PDFs out of the DITA Open Toolkit is not as straightforward as
designing a lovely FrameMaker template, but it’s not rocket science either.
While I enjoy writing (though I may take a break now that this book is done), I also enjoy teaching other
writers. And, while I don’t have any formal background in programming, I do like to tinker under the
hood, which is a big advantage. I realize many writers just want to write, and when I teach, I keep that in
mind. There has to be a woman (or a man) behind the curtain, but we don’t have to see her (or him).
Aside from writing and teaching, I do love to talk. About nearly anything, really, but speaking at conferences
and meeting others who do what we do is one of my favorite parts of this profession. Over the years, I’ve
been fortunate enough to speak at the STC Summit, NLDITA, WritersUA, LavaCon, Intelligent Content,
SPECTRUM, DITA/Tech Comm, Real World DITA, and the FrameMaker Chautauquas. The energy and
motivation, not to mention the knowledge, I’ve taken away from those conferences has been incredible.
Do everything you can to get to at least one conference a year. It’ll be amazing.
So enough about me. Well, not quite. I do have a life outside of the DITA Open Toolkit. When I can
wrench myself away from the computer, I enjoy hiking and photography (often together), running, biking,
team trivia, choral singing, reading, and building stuff. I also enjoy inventing languages, though my success
at convincing anyone else to speak them has been spotty.
Contact me
Unfortunately, I’m not able to provide technical help with any of the exercises in this book, but I do want
to hear from you! Hopefully there will be another edition of this book for a future DITA Open Toolkit
release. If there are other topics you’d like to see covered, if you have tips and tricks you’d like to share,
or if you think I could have done a better job explaining something, let me know:
ditaforprint@gmail.com
I may not be able to respond to you personally, but please know I appreciate every comment and suggestion.Preface 23
Acknowledgements
Since I started working with the DITA Open Toolkit, more people have generously helped me than I
could possibly name here. But I’m going to name a few people, without whom this book wouldn’t even
exist. First, deepest gratitude to my publisher and editor, Richard Hamilton, who patiently waited for me
to finish, offered invaluable advice on every aspect of this book and tested the Mac/Linux examples. Many
thanks also to Kristin Eberlein, who put me in touch with Richard in the first place, worked through an
early draft, and gave me excellent feedback on what worked and what didn’t. The wonderful folks at Suite
Solutions have shared their considerable knowledge and expertise with me over the past few years and
it’s been a true pleasure to work with them.
The DITA Users list has been my number one “go to”place for answers and advice. I can’t count all the
people who’ve responded to my posts, but I have to call out three of them: Kyle Schwamkrug for his
contribution of the GetChapterNumber template to the DITA Users group and to this book; Severin
Foreman for answering a gazillion questions and explaining even more carefully when I don’t understand;
and Eliot Kimber for spending hundreds of hours answering questions on the list, including mine—even
though some of his posts are completely over my head, there’s always a kernel of wisdom that gets through
to me. They are my DITA gurus and I’d like to be any one of them when I grow up. Eliot also gave this
book a good once-over to make sure some of the finer points are accurate. Any errors are my own.
My eternal gratitude to my former colleagues on the Documentation Center of Excellence team at Allscripts
Healthcare, LLC. When I first drove up in the DITA bus, they took a leap of faith and climbed on board.
In the years since, they challenged me in every way, throwing me use cases and requirements that I would
never have imagined. I know most of what I know because they asked me to figure it out. Thanks, y’all!
The folks at Ixiasoft have, by answering my countless questions about configuring their DITA CMS
(Content Management System), taught me a great deal about the underlying structure of the DITA DTDs
as well as ANT and XPath. I’ve now joined their team, and it’s a real privilege to work with them. I continue
to learn from them every day.
This list would not be complete without a bow to Jarno Elovirta, the developer responsible for most of
the work on the DITA Open Toolkit over the last few years. Most of the work he does is on his own time,
purely for love of the code and a desire to provide DITA users with the functionality we need to do our
own work and publish our own documents. We are in your debt, Jarno!
This book is for Nana, Daddy, and Sue. All my love.1
Introduction
What you’ll need
To work with the PDF plugin of the DITA Open Toolkit, you will need a few tools.
DITA Open Toolkit
You need to have the DITA Open Toolkit installed, of course. This book is written for the DITA Open
Toolkit 1.8, which is the current stable release as of the publication of this book. There are three versions
available for download: minimal, standard, and full. The full version installs not only the XSLT stylesheets
and ANT build files, but also ANT, FOP, and some other tools you need. It’s really your best bet to be
sure that you have a clean, fully-integrated installation that works out of the box.
There are lots of possible setups you could be working with. XML editors such as XMetaL
or <oXygen/> come with their own installation of the DITA Open Toolkit. Because there’s
really no way to cover all the possibilities without creating a hopeless tangle, this book assumes
a separate, standalone installation of the DITA Open Toolkit 1.8. If you’re using the DITA
Open Toolkit in some other configuration, you’ll need to make corresponding adjustments
to the instructions in these exercises.
PDF renderer
This version of the DITA Open Toolkit comes with Apache FOP 1.1, a free program that generates PDF
from an intermediate format (called “fo,” for “formatting objects,” and that’s all you need to know about
it). In many cases, FOP is adequate, but it may not be robust enough for a full production environment,
especially if you are producing an index. Commercial alternatives are RenderX’s XEP and Antenna House.
Both have free trial versions. This book was created using XEP, but all of the exercises (except those in
the Index (on page 343) chapter) assume you are using FOP.26 DITA for Print: A DITA Open Toolkit Workbook
XML editor
You also need an XML editor that can validate your XSLT stylesheets while you’re editing them. This will
help you spot typos, missing elements, and other errors more quickly. If you’ve been authoring in DITA,
you likely already have an XML editor such as XMetaL, <oXygen/>, Syntext Serna, or XMLMind.
Alternatively, you can use a robust text editor such as the free Notepad++. With a free plug-in, Notepad++
can do basic syntax checking of XML files to help you spot some errors, and it color-codes elements,
attributes, values, and plain text to make reading XML markup easier. Notepad++ also has some useful
features such as file compare. If you’re confident editing XML and XSL files without full validation,
Notepad++ is a quick, lightweight alternative to a full-featured XML editor.
Search and replace utility
You’ll need a good utility to search across multiple files and folders. Until you learn where things are in
the PDF plugin, you’ll do a lot of searching for specific attribute sets and templates. The free TextCrawler
is a very good option for Windows. For Macintosh or Linux systems, take a look at Find & Replace It! or
the grep command.
XSL-FO reference
An absolute must is a good XSL-FO reference that lists and explains the different attributes available for
formatting. When you get comfortable with the basics, you might want to explore other things you can
do to add functionality to your PDFs and make your publishing process more powerful and flexible. Two
books I can recommend are XSL Formatting Objects Developer’s Handbook, by Doug Lovell and XSL-FO,
by Dave Pawson. Both are excellent. Of the two, XSL-FO has a more instructional tone. Both of these
books are complete references to XSL-FO, explaining how to create an FO file from the ground up (or
rather, from the root up). Because the DITA OT creates the FO file for you, you probably won’t use the
entire book, but you will absolutely use the lists of FO elements and attributes that both books provide.
Alternatively, you can use an online FO reference. W3Schools has a pretty good one.
Some content
Finally, you need content you can use for testing. If you don’t already have DITA topics and maps, you
can use the garage samples in the samples subfolder of the DITA Open Toolkit.
If you find that you need some more robust content for testing, you can download the DITA Test Suite
from Sourceforge. The DITA Test Suite is a collection of topics and maps that contain all (or almost all)
of the elements and structures available within DITA.
Websites
DITA Open Toolkit: http://sourceforge.net/projects/dita-ot/
FOP: http://xmlgraphics.apache.org/fop/Introduction 27
XEP: http://www.renderx.com/tools/xep.html
Antenna House: http://www.antennahouse.com
XMetaL: http://na.justsystems.com/index.php
<oXygen/>: http://www.oxygenxml.com/download.html
XMLMind: http://www.xmlmind.com
Notepad++: http://notepad-plus-plus.org
TextCrawler: http://www.digitalvolcano.co.uk/content/textcrawler
Find & Replace It!: the Mac App Store
Useful resources
It takes a village…
Because DITA is an open standard, thousands of people use it, and most of those people are happy to
help you. If you haven’t already done so, consider joining the Yahoo! DITA Users list. The list is extremely
active and well-monitored. The Search feature isn’t the best, but you should still try to search the archives
as thoroughly as you can to make sure you don’t ask a question that’s already been asked and answered
many times.
The SuiteShare Social Knowledgebase, sponsored by Suite Solutions, is also up and running now and
growing every day. It contains articles that address many of the issues discussed on the DITA Users list,
but the articles tend to be a little tighter than some of the DITA Users discussions.
The OASIS DITA Users list is an alternative to the Yahoo! DITA Users list. It’s currently not as active as
the Yahoo list, but there is a large, searchable archive.
If you need a brush-up on DITA itself, there are several very good books available that can get you going.
There’s a list at the end of this section.
These lists are by no means exhaustive. Just enter “DITA” into a search engine and you’ll see that you
could easily spend a lifetime exploring all the information available. Don’t be distracted by Ms. Von Teese.28 DITA for Print: A DITA Open Toolkit Workbook
Websites
DITA 1.2 specification: http://docs.oasis-open.org/dita/v1.2/spec/DITA1.2-spec.html
Yahoo! DITA Users: tech.groups.yahoo.com/group/dita-users
OASIS DITA Users list: https://lists.oasis-open.org/archives/dita-users/
DITA Social knowledgeBase: ditadocs.content-lifecycle.com
Jarno Elovirta’s web-based PDF plugin generator: http://dita-generator.appspot.com/pdf-plugin/
Patrick Quinlan’s (Ditanauts.org) mypdf plugin: http://sourceforge.net/p/mypdf/home/Home/
Eliot Kimber’s specialization tutorials: http://xiruss.org/tutorials/dita-specialization/
Guide to ANT build properties:dita-ot.sourceforge.net/1.8/readme/dita-ot_ant_properties.html
List of entity codes: http://www.entitycode.com
Apache ANT: http://ant.apache.org/
Apache ANT manual: http://ant.apache.org/manual/index.html
Books
Introduction to DITA: A User Guide to the Darwin Information Typing Architecture (Jennifer Linton,
Kylene Bruski)
DITA 101: Fundamentals of DITA for Authors and Managers (Ann Rockley, Steve Manning and
Charles Cooper)
Practical DITA (Julio Vazquez)
DITA Best Practices: A Roadmap for Writing, Editing, and Architecting in DITA (Laura Bellamy,
Michelle Carey, Jenifer Schlotfeldt)
DITA for Practitioners, Volume I: Architecture and Technology (Eliot Kimber)
DITA Style Guide (ePub) (Tony Self)
XSL Formatting Objects Developer’s Handbook (Doug Lovell)
XSL-FO (Dave Pawson)
The DITA Open Toolkit itself
After you work your way through this book, if you’re eager to learn more about customizing the PDF
plugin (or any other kind of plugin), you can turn to the Developer Reference documentation within the
DITA Open Toolkit folder itself.
This documentation is found in DITA-OT/doc/dev_ref and it provides a wealth of information about
the different processing stages of a DITA Open Toolkit build, as well as details on extending and further
customizing plugins.Introduction 29
This information is delivered as a map and source topics, so you’ll probably want to build a PDF to browse
it easily, which you will be able to do after you finish the first few chapters of this book!
Some conventions
Book organization
Each chapter addresses one particular aspect of a print publication. Every chapter has sections with names
prefixed by the word Exercise. These sections contain the exercises you need to complete to set up a PDF
plugin that meets the specifications outlined in the Specifications used in these exercises (on page 371)
appendix. Some chapters have other exercises you can complete to do other cool things with your PDF
plugin. These exercises can be found in the Other things you can do section in those chapters.
Folder names
For the sake of simplicity, in all the examples and paths throughout this book the DITA Open Toolkit
folder is called DITA-OT. If you download the DITA Open Toolkit 1.8, you’ll see that by default, the folder
is named DITA-OT1.8. You can leave that folder name as-is or change it as you like. Just keep in mind
that DITA-OT in file paths in this book refers to whatever you have actually named your folder, so edit
the paths you use accordingly.
Paths
Most of the code samples and paths in the book use the URL syntax convention of forward slashes because
DITA and XSL-FO are Web applications. Windows systems should accept the forward slashes as well in
almost all cases, though you will see backslashed in some Windows-only command lines
Type styles
The following type styles are used to make certain items more obvious.
• Bold: file names, emphasized sections in code samples, attribute values and variable values.
• Italic: attribute set names, attribute names, variable names, template names, parameter names, terms
defined in the glossary
• Monospaced: file paths, folder names, code samples, element names (DITA, XSL, and FO)
• Double quotes: marker names
• ¶: indicates a line return has been inserted in a code example for clarity (usually because without the
line break, the code would not fit on the printed page); the actual code does not include a line return
at that location.30 DITA for Print: A DITA Open Toolkit Workbook
Order of exercises
You can do most of the exercises in any order. You might not always get exactly the results you expect,
especially with respect to formatting, but your build will work. There are a few sets of exercises that must
be done in a specific order because each exercise depends on variables, attribute sets, or page layouts
created in a previous exercise. These exercises are grouped together with a note recommending that you
complete them in order.
Comment, comment, comment…test, test, test
Anytime you change your code, there are two things you should do that will make life a lot easier.
Comment your code
First, comment all your changes, even minor ones like changing an attribute value or a localization variable
value. Even for these simple changes, it’s good to have a record of what you touched and what the original
value was.
For more complicated changes, it almost goes without saying that you need to explain what you did and
why so anyone who comes across the code can understand why the change was made. A year from now,
even you might not remember.
Ideally, start all your comments with something unique, to make it easy to find them later. A good example
of a comment is:
<!--LWW (20130531): Switched the output order of the figure and its title-->
This comment includes the initials of the person making the change, the date the change was made, and
an explanation of the change.
Comments can go almost anywhere in your XSLT stylesheets, attribute set files, or localization variables
files. The only place you can’t put a comment is within another comment.
All comments must start with <!-- and end with -->.
Test your changes frequently
Second, test your changes as you go. Test each change as you make it. Don’t delay testing until you’ve
made several changes. If something goes wrong, it’s going to be more trouble to find exactly where the
mistake happened. Even if the changes seem simple and straightforward, test them. Then, when you
encounter a problem, you will know it occurred within the last few changes you made.Introduction 31
From painful experience, I can tell you that even a small error, like forgetting to close an element tag or
leaving out a quote character, can set off a cascade of error messages that make it look like there are dozens
of mistakes, when in fact there is only one error that messed up everything after it.
Most of the exercises in this book end with, “Save your changes, run a build, and test your work.” Seriously,
do that.2
Custom PDF plugin creation
The whole point of this book is to show you how to create and use your own PDF plugin with the DITA
Open Toolkit. This chapter gets you started.
First, I explain what a PDF plugin is and how the one that comes with the DITA Open Toolkit is organized.
Next, I explain how to download and install the DITA Open Toolkit (if you haven’t already done that).
Finally, I explain how to create your own PDF plugin and tell the DITA Open Toolkit to use it instead of
the default plugin.
Important: You should perform the exercises in this section in the order they’re given. Each
exercise builds on the previous one, so skipping around is not a good idea.
What is a PDF plugin and why do you need one?
Out of the box, the DITA Open toolkit provides ANT build files, XSLT stylesheets, and Java executables
that let you convert a collection of DITA topics into a variety of output formats, including PDF. The
processing for each of these output formats comes bundled in set of plugins that you can extend and
customize. In this book, we’ll explore how to create a plugin that customizes PDF processing.
“Do I need my own PDF plugin,” you ask. Unless you think the out-of-the-box PDFs produced by the
DITA Open Toolkit are just dandy, then yes—you need a PDF plugin. No question about it.
Now that we’ve gotten that out of the way, here’s the story with PDF plugins.
To customize PDF output, you could just edit the files in the default plugin (org.dita.pdf2). That
would be fine, until your boss comes to you and says, “We also need to produce a Quick Reference Guide.
It should be 5.5 inches by 8.5 inches. And all the fonts need to be smaller. And the margins need to be
different. And the headers and footers need to be different.…” What do you do? If you’re using the default
files, you have to keep editing them over and over. Pretty soon, you won’t be able to keep up. And
maintaining more than one type of PDF output at the same time will be nearly impossible.34 DITA for Print: A DITA Open Toolkit Workbook
Instead, the right strategy is to create your own separate PDF plugin. That way, you bundle up all of your
changes into one nice, neat package that you can easily maintain.
Going back to the example above, it makes a lot more sense to create one PDF plugin for User Guides
and another for Quick Reference Guides. That way, you simply call the plugin you need when you create
a PDF. It’s like having different templates in Adobe FrameMaker or Microsoft Word for different kinds
of documents.
When you have a nicely bundled-up PDF plugin, you can easily move it from one installation of the DITA
Open Toolkit to another. (Or you can keep it in another location entirely; it doesn’t have to be within the
DITA OT folder.) You can also send the plugin to other writers on your team, to contractors, to Marketing,
or to whomever. It’s self-contained and portable.
So now that you’re convinced you need a PDF plugin, exactly what is one?
To create PDFs from a map or bookmap, the DITA Open Toolkit uses many different files. These files
are in various places in the Open Toolkit, but most of them, and almost all of the ones you’ll need to work
with, are found in DITA-OT/plugins/org.dita.pdf2. A PDF plugin contains only the files you
needed to change for your customization. (In this path, and throughout the book, DITA-OT refers to
whatever you’ve named your DITA Open Toolkit folder.)
These files fall mainly into three categories: attribute set files, XSLT stylesheets, and variables files.
• Attribute set files control the way each element looks in the PDF—things like indentation, font
characteristics, line spacing, hyphenation, alignment, and so forth. Think (very generally): “attribute
set file equals appearance.”
• Stylesheets control the way each element is processed. For example, if you want to number a paragraph
or assign a custom attribute set to an element based on an @outputclass value, you would use the
appropriate stylesheet. Think (again, very generally): “stylesheet equals behavior.”
• Variables files do several things, but one of the most important is to dynamically insert language-specific
boilerplate text during processing. For example, if you want to add a label in front of a particular
element and that label differs depending on the language, you would set that up in a variables file.
Variables files also play an important role in setting up headers and footers. Think: “variables file
mostly equals translation and headers and footers.”
In addition to these files, a plugin can also include its own ANT build file. If you want a plugin that simply
overrides attribute sets, XSLT stylesheets, and localization variables, you can create the plugin without
an ANT build file. However, if you need additional functionality, you need to include an ANT build file.
It is easy to create a plugin with an ANT build file, and doing so will make it easier to add functionality
in the future, so we will take that approach.Custom PDF plugin creation 35
Organization of the org.dita.pdf2 plugin
Before you get started creating your own plugin, it’ll be helpful for you to understand a little about the
org.dita.pdf2 plugin, because your plugin will have almost the same organization.
IBM originally developed DITA and the Open Toolkit to create online output. IBM has its own print
solution, but it did not include it with the Open Toolkit components it contributed to open source. After
DITA became a public standard, everybody recognized the need to publish PDFs as well.
The org.dita.pdf2 plugin was originally developed by Idiom and is still sometimes referred to as the
“Idiom PDF plugin.” However, the plugin is now maintained by a number of different folks. Like the rest
of the DITA Open Toolkit, the PDF plugin is open source, meaning that no one really owns it. In this
case, “maintains” just means that certain groups make the code changes that are included in the official
plugin as it ships with the DITA Open Toolkit.
Important: There are three versions of the DITA Open Toolkit: full, standard, and minimal.
All of the references to folder structure in this book assume you’ve installed the full version,
which I strongly recommend.
Out-of-the-box, the DITA Open Toolkit is organized like this.
DIT A-OT
css
demo
doc
dtd
lib
plugins
resource
samples
schema
tools
xsl
Figure 1: Default OT organization
The org.dita.pdf2 plugin, not so shockingly, is found in the plugins subfolder.
Actually, that location is shocking because it wasn’t always that way. In DITA Open Toolkit
versions before 1.6, the plugin lived in the demo subfolder because the capability was presented
more or less as a demonstration of future possibilities. So the plugin was placed in the demo
subfolder. Finally, it in its logical location.36 DITA for Print: A DITA Open Toolkit Workbook
Plugins folder organization
Here’s what the plugins folder looks like out of the box.
plugins
com.sophos.tocjs
h2d
legacypdf
org.dita.base
org.dita.docbook
org.dita.eclipsecontent
org.dita.eclipsehelp
org.dita.htmlhelp
org.dita.javahelp
org.dita.odt
org.dita.pdf
org.dita.pdf2
org.dita.specialization.dita1 1
org.dita.specialization.dita132
org.dita.specialization.eclipsemap
org.dita.trof f
org.dita.wordrtf
org.dita.xhtml
Figure 2: Plugins folder organization
It’s kind of scary at first. Block out everything but the org.dita.pdf2 subfolder, because that’s where
the PDF plugin lives. Here’s what that subfolder looks like inside.
Why is there also a folder named org.dita.pdf? Well, because the PDF plugin has been
through a lot of changes in its life. At one point, the developers replaced the original one with
a snazzier new one. But because everything in the DITA Open Toolkit is designed to be
backwards-compatible, the old one is still hanging around. The two folders are legacies of
that history. There’s nothing much in the org.dita.pdf folder, though, and these days,
when you create a PDF, you’re using the org.dita.pdf2 plugin.
org.dita.pdf2 folder organization
Here’s what the org.dita.pdf2 folder contains out of the box.Custom PDF plugin creation 37
org.dita.pdf2
cfg
Customization
fop
lib
resource
xsl
build.xml
build_axf.xml
build_fop.xml
build_template.xml
build_xep.xml
buildPackage.xml
integrator .xml
plugin.xml
README.txt
Figure 3: org.dita.pdf2 organization
You won’t need to work with any of those .xml files for a typical PDF plugin, so forget about them. You’ll
invoke some of them behind the scenes, but you won’t directly edit them.
There are these sub folders within the org.dita.pdf2 folder:
cfg Contains the sub folders common and fo. More on these below.
Customization This folder used to be a “starter set” for your own PDF customization. It became
obsolete in version 1.6 of the DITA Open Toolkit
fop Contains the Apache FOP PDF renderer.
lib Contains fo.jar, a Java executable needed for PDF processing.
xsl Contains the XSLT stylesheets that process DITA content into PDFs. You’ll learn
how to copy these XSLT stylesheets to your own PDF plugin and modify them.
The cfg subfolder is where the magic happens, as far as customization is concerned. Well, most of the
magic, anyway. The cfg subfolder has this structure.38 DITA for Print: A DITA Open Toolkit Workbook
cfg
common
artwork
index
properties
vars
fo
attrs
i18n
xsl
Here’s a description of each of the sub folders of cfg.
artwork Contains standard images and icons used by the default PDF plugin. If you have images
that are specific to your plugin, such as custom icons or logos, you should store them in
the artwork subfolder of your plugin folder.
index Contains the index sorting files for various languages. These files determine the order in
which the DITA Open Toolkit sorts the index for different languages.
properties Contains the properties files for various languages. By default these properties files specify
only the native character encoding for the language, but you can include additional
properties in them, including ANT properties—an alternative to including those properties
in each individual ANT build file.
vars The files in this folder contain boilerplate text that can be dynamically inserted in your
PDF, avoiding the need for redundant translation. This boilerplate text includes things
like the labels for figure and table titles, notes, warnings, cautions, and lots more.
attrs Contains the attribute set files that determine the appearance of DITA elements in a PDF.
i18n Contains the character sets for various languages. These character sets specify which
subset of the Unicode character set the language uses.
xsl Empty by default (except for the custom.xsl file). You don’t really do anything with this
folder. But, within your plugin folder, you’ll have an xsl subfolder just like this one. You
copy any XSLT stylesheets you want to modify for your plugin into this folder.
The fo subfolder also contains font-mappings.xsl and layout-masters.xsl. Font-mappings.xsl determines
the fonts that appear in your PDF. Layout-masters.xsl determines the master pages available in your
PDF—body master pages, index master pages, cover pages, and so forth.
If this doesn’t make a lot of sense right now, don’t worry. As you work through the exercises in this book,
you’ll understand these folders better.