Table Of ContentR
e
vi
s
U e
DITA SERIES pd d
a a
t n
e d
d
for
Print
Second edition: updated for the
DITA Open Toolkit Version 2
A DITA Open Toolkit
Workbook
Leigh W. White
DITA for Print: A DITA
Open Toolkit Workbook
DITA Open Toolkit 2
Leigh W. White
http://xmlpress.net
DITA for Print: A DITA Open Toolkit Workbook
Copyright © 2013–2017 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
Second Edition
ISBN: 978-1-937434-54-0
Table of Contents
List of Figures...............................................................................................................................xv
Preface: Preface...........................................................................................1
Why this book?.......................................................................................................................1
Who is this book for?...........................................................................................................2
Keepin’ it real..........................................................................................................................3
About me.................................................................................................................................3
Contact me..............................................................................................................................4
Acknowledgements................................................................................................................5
Chapter 1: Introduction..............................................................................7
What’s different in this edition?..........................................................................................7
PDF changes in DITA OT 2.5..............................................................................................8
What you’ll need....................................................................................................................8
Useful resources..................................................................................................................11
Some conventions................................................................................................................13
Comment, comment, comment…test, test, test.........................................................14
Chapter 2: Custom PDF plugin creation...............................................17
What is a PDF plugin and why do you need one?........................................................17
Upgrading existing plugins..................................................................................................19
Organization of the org.dita.pdf2 plugin.........................................................................20
DITA Open Toolkit 1.5 and earlier.................................................................................23
DITA Open Toolkit post-2.0............................................................................................24
Exercise: Download and install the DITA Open Toolkit............................................24
Exercise: Create your own PDF plugin...........................................................................25
Exercise: Integrate your plugin into the DITA-OT......................................................29
Exercise: Create an attribute set file in your plugin....................................................31
Exercise: Add an attribute set to your plugin...............................................................32
Exercise: Create an XSLT stylesheet in your plugin....................................................32
Exercise: Add a template to your plugin........................................................................34
Why not use a single custom file for all your changes?..............................................34
Exercise: Add a localization variables file to your plugin............................................35
Exercise: Add a localization strings file to your plugin................................................36
Exercise: Add a strings.xml file to your custom plugin...............................................36
Mapping strings files to xml:lang values in the strings.xml file...................................37
Wrap-up.................................................................................................................................38
Chapter 3: DITA Open Toolkit builds...................................................39
What is an ANT build file?.................................................................................................39
Exercise: Create an ANT build file..................................................................................40
Exercise: Create a batch file to launch an ANT build (Windows)...........................43
Exercise: Create a shell file to launch an ANT build (Mac, Linux)...........................45
Exercise: Test your plugin..................................................................................................47
Exercise: Use a specific PDF renderer............................................................................49
Other things you can do....................................................................................................49
The topic.fo file..............................................................................................................49
Exercise: Retain the topic.fo file for troubleshooting...........................................52
Chapter 4: Attribute sets.........................................................................55
What are attribute set files?..............................................................................................55
How attribute set defaults work......................................................................................56
Special attributes for XEP, Antenna House, and FOP.................................................58
Which attribute set do you customize?..........................................................................59
The closest attribute set wins...........................................................................................61
Attribute sets that call other attribute sets...................................................................62
Basic-settings variables in attribute sets.........................................................................64
Other things you can do....................................................................................................65
Exercise: Create a new attribute set........................................................................65
Exercise: Call a new attribute set..............................................................................66
Exercise: Conditionalize an attribute set.................................................................67
Exercise: Conditionalize an attribute set based on a build parameter.............69
Exercise: Select specific elements by context........................................................70
Chapter 5: Localization variables...........................................................75
What are localization variables?.......................................................................................75
Literal characters and numeric character references..................................................77
Exercises................................................................................................................................78
Other things you can do....................................................................................................78
Exercise: Create a localization variables file...........................................................78
Exercise: Create a localization strings file...............................................................79
Chapter 6: Fonts........................................................................................81
About fonts in the PDF plugin..........................................................................................81
Font specifications................................................................................................................82
Files you need.......................................................................................................................83
Exercise: Specify fonts to use............................................................................................83
Other things you can do....................................................................................................86
Exercise: Use a different font in special cases........................................................86
Exercise: Use font mapping in your plugin..............................................................87
Exercise: Use a custom font family with font mapping.........................................89
Chapter 7: Page masters..........................................................................91
Page masters and regions in the PDF plugin..................................................................91
Default page masters, regions, and attribute sets........................................................93
Page specifications................................................................................................................95
Files you need.......................................................................................................................97
Do these exercises in order!............................................................................................97
Exercise: Set up double-sided pagination.......................................................................98
Exercise: Set page dimensions...........................................................................................98
Exercise: Set page margins.................................................................................................99
Exercise: Set up body regions.........................................................................................101
Setting up header and footer regions...........................................................................104
Exercise: Set margins for the front cover page..........................................................105
Other things you can do..................................................................................................107
Exercise: Eliminate blank last pages........................................................................108
Exercise: Design a separate layout for first pages...............................................109
Exercise: Use the bookmap page sequence for maps........................................111
Exercise: Add a background image to a page.......................................................113
Exercise: Change the number of columns on a master page............................115
Chapter 8: Page headers and footers..................................................119
About headers and footers.............................................................................................119
PDF plugin defaults for headers and footers...............................................................120
Where does header and footer information come from?.......................................121
Metadata variables for headers and footers................................................................122
Models to use for map metadata...................................................................................123
DITA element classes.......................................................................................................126
Header and footer specifications...................................................................................129
Files you need.....................................................................................................................131
Complete these exercises in order!..............................................................................132
Header setup......................................................................................................................132
Exercise: Set up headers that include external files............................................132
Exercise: Set up headers that include boilerplate text.......................................135
Exercise: Set up headers that include generated text........................................138
Adding information from the map to headers.....................................................141
Exercise: Create metadata variables for headers and footers...................141
Exercise: Add fallback header and footer variables to the localization
variables file...........................................................................................................144
Exercise: Set up headers that include map metadata..................................144
Footer setup.......................................................................................................................147
Exercise: Set up odd footers....................................................................................147
Exercise: Set up even footers..................................................................................150
Exercise: Create new header and footer definitions .........................................152
Exercise: Add chapter, appendix, or part numbers to page numbers
(Antenna House, XEP)...............................................................................................154
Exercise: Restart page numbering in each chapter, appendix, or part...........157
Header and footer formatting........................................................................................158
Exercise: Set top and bottom margins for headers and footers......................158
Exercise: Set left and right margins for headers and footers............................160
Exercise: Format the appearance of headers and footers.................................161
Exercise: Justify elements of a header or footer.................................................163
Exercise: Add space around a header or footer image......................................165
Other things you can do..................................................................................................166
Exercise: Put header or footer content on multiple lines.................................166
Exercise: Add the current date to headers and footers....................................169
Exercise: Add a prefix to non-body page numbers.............................................171
Exercise: Use a specific title level in the running header...................................172
Chapter 9: Cover pages..........................................................................175
Cover specifications..........................................................................................................175
Files you need.....................................................................................................................177
Front cover customization..............................................................................................178
Exercise: Add bookmap information to the front cover...................................178
Exercise: Format information on the cover page................................................181
Exercise: Place cover page information in a specific location...........................183
Back cover creation and customization........................................................................184
Exercise: Create a back cover.................................................................................184
Exercise: Add content to the back cover.............................................................184
Exercise: Format content on the back cover.......................................................187
Exercise: Adjust pagination of the back cover.....................................................189
Other things you can do..................................................................................................190
Exercise: Insert text based on language.................................................................190
Exercise: Eliminate the front cover page...............................................................191
Chapter 10: Titles, body text, and notes............................................193
General text formatting specifications..........................................................................193
Files you need.....................................................................................................................194
Title formatting..................................................................................................................195
How topic title attribute sets work.......................................................................195
Exercise: Format topic titles....................................................................................197
Exercise: Format section titles.................................................................................198
Exercise: Format chapter, appendix, or part titles..............................................199
Exercise: Format the chapter, appendix, or part autonumber.........................200
Exercise: Change the chapter number label and format...................................201
Exercise: Put the chapter, appendix or part label, number, and title on the
same line.......................................................................................................................202
Text formatting..................................................................................................................206
Formatting body text.................................................................................................206
Exercise: Set body font sizes....................................................................................208
Exercise: Format code samples and messages.....................................................209
Exercise: Set the default line height........................................................................210
Exercise: Format trademark, registered trademark, service mark, and
copyright symbols.......................................................................................................211
Notes formatting...............................................................................................................214
Exercise: Format note labels....................................................................................214
Exercise: Change the label for a note type...........................................................215
Exercise: Delete the label for a note type............................................................215
Exercise: Change or delete note icons..................................................................217
Exercise: Format note text.......................................................................................218
Exercise: Add left and right borders to notes......................................................219
Exercise: Use a custom label for other-type notes.............................................219
Other things you can do..................................................................................................221
Exercise: Mark non-standard items for resolution.............................................221
Exercise: Eliminate the chapter, appendix, or part label and number............222
Exercise: Format note labels as sideheads............................................................224
Exercise: Rotate text..................................................................................................228
Exercise: Include a topic’s ID in the PDF..............................................................231
Exercise: Add a prefix to a topic title....................................................................232
Adding page breaks manually...................................................................................235
Exercise: Generate line numbers in codeblock elements.................................235
