Buy this book before attempting to customize your DITA OT PDF output!
The Problem (My Story)
Several months ago, I spent a substantial amount of time struggling through the process of customizing DITA Open Toolkit (DITA OT) PDF output. I drastically underestimated the complexity of this, and my experience could have easily qualified as a ‘Tech Writer Horror Story’.
As someone with a solid working knowledge of HTML, XML, and CSS, and a basic understanding of XSL, I assumed that I’d be able to figure this out easily enough – how hard could be right? I soon realized that just understanding the logic of the PDF2 folder and file structure was enough to make my head spin.
I decided I needed help. Since I couldn’t find any books or formal documentation relating to the DITA OT PDF customization process, I resorted to what I hate the most – searching online through groups and forums. I managed to find enough information to get me started in the LinkedIn DITA awareness group, and the Yahoo! DITA users group. Eventually, by reverse engineering the plug-in that I got out of this DITA OT PDF plug-in generator, I was able to create the customization that I wanted.
Although my PDF output looked pretty, I knew I hadn’t followed best practices and had no doubt created something that was difficult to alter or maintain.
The Solution (This Book)
I picked up my signed copy of DITA for Print: A DITA Open Toolkit Workbook at LavaCon 2013. After flipping through a few chapters, I quickly realized that I would have saved an enormous amount of time and frustration if I had had Leigh White’s book before I struggled through figuring this process out on my own, as such, I decided to start over again from scratch and do things right.
The book is structured as a workbook (as the title indicates), and it’s comprised of nineteen chapters. With the exception of chapter 1, which introduces and explains the basic concepts of the DITA Open Toolkit and PDF customization, each chapter walks you through customizing a different piece of your PDF output. Take a look at the table of contents to see the full list.
My particular PDF customization requirements involved modifying the DITA Open Toolkit default PDF to create a ‘quick reference’ type document that adhered to corporate branding.
Starting from scratch, in about 7 hours (70% less time than I spent customizing these pieces without this book, not including my initial research), this is what I was able accomplish:
- Created my own PDF plug-in
- Customized fonts
- Customized pages, page layouts, page orientation
- Customized header and footers to add images and text
- Customized formatting on a variety of content
- Customized localization variables
The customizations that I’ve made represent just a portion of what’s covered in this book. Regardless of whether I customize further or not, I have the peace of mind to know that the information is there if I need it.
Also, what I found particularly valuable Leigh’s approach is that the exercises don’t just explain ‘how’ to do something, but they also explain ‘why’ it’s important (or a maybe just a good idea) to do something one way versus another, including best practices (e.g., why you should create your own custom XSL attribute sets rather than making modifications to the default sets). In fact, the tasks are so well explained that I’ve actually gained enough XLS/XSL-FO knowledge to troubleshoot errors and create customizations on my own.
The one piece of advice that I would offer to anyone considering purchasing this book is that it you should definitely have a strong understanding of markup and style sheet languages. If you don’t, you’ll get there, but be prepared to take it slow.
In summary, if you have a DITA Open Toolkit PDF customization in your future and you value your time and you don’t enjoy stress, frustration or anxiety, this book is for you!
