Structured FrameMaker 11: Printing DITA to PDF and Defining Banner Text in Strawman Topics

In this guest blog by Matt Sullivan, several easy-to-do, yet advanced features of structured FrameMaker are covered.

Recorded webinar and demos

The following blog post has an accompanying recorded one-hour webinar and has two additional recorded demonstrations.

Background on FrameMaker and DITA

FrameMaker 11 supports the DITA 1.1 and 1.2 spec. In this article, we will use the DITA 1.2 specification for our examples.

You can speed creation of new DITA 1.2 content using 2 built-in menu items:

FrameMaker 11 lets you choose the exact DITA workflow you prefer. You can work directly with the standard DITA .xml and .ditamap files, or the standard FrameMaker .fm and .book files, or a combination of the two.

The FrameMaker DITA advantage

Without FrameMaker, creating sophisticated output of DITA to print or PDF can be an expensive proposition. Using the DITA Open Toolkit and XSL-FO, you create an output conduit for your content, but the creation of that conduit can be costly, and changes to the format are not easy. The bottom line is that the cost of defining your output can easily run into the thousands of dollars. In sharp contrast, FrameMaker ships with solid templates for output of all DITA content, and allows changes to those templates that will be familiar to any experienced structured FrameMaker user.

Customizing DITA templates

Because FrameMaker is both a full-featured XML authoring solution and a full-featured PDF creation tool, initial output to PDF via supplied templates, and customization/branding of your authoring templates and PDF output is easy.

Customizing page layout

See the 0:06:00 minute mark of the video for a discussion of StructApp files and master page changes.

Customizing your DITA page layout is as easy as opening the template files, and editing your master pages. As with any modifications to default files, it’s a good idea to save a backup of these files before editing.

Here is an example of the default directory containing the DITA templates in a Windows 7 FrameMaker 11 installation:
C:\Program Files (x86)\Adobe\AdobeFrameMaker11\Structure\xml\DITA_1.2\app\technicalContent\template

After backing up the original template files, you can open these files and edit them as you would any other structured FrameMaker documents. In the recorded webinar noted above, I show the results of modifying the master pages of a topic template to allow company branding and customizations to the body page text frames and header frames and graphics.

You can also modify the location of the template files. To do so, modify the Global Application Definitions file available by selecting StructureTools > Edit Global Application Definitions

Here is an example of what that file looks like:

By modifying the location of the template directory, you can ensure that the original template files are not overwritten.

Customizing DITA content options

As with all XML models, and all XML editors, FrameMaker uses a series of files used to control options and formatting of content in a document.

Controlling the strawman structure

See 0:09:00 in the recording for strawman and banner text options

When you create a new DITA file, you will get an initial structure in the file, commonly referred to as strawman text. If you wish to customize options, open up the appropriate template (see screen capture above) and select StructureTools > Export Element Catalog as EDD.

(Alternately, you can edit the template EDD in the \DITA_1.2\app\technicalContent\edd directory)

Within the EDD, some elements will contain AutoInsertions elements.

The combination of the autoinsertions is what creates your strawman structure. Edit the EDD as needed, and then select File > Import > Element Definitions to reimport the element definitions back into the template file.

Congratulations… you just altered the behavior of new files of that doctype!

Controlling the Banner Text string

See 0:13:30 in webinar for a walkthrough.

The EDD also lets you specify a prompt for content entry, known as banner text.

To customize the text displayed for a specific element, modify the BannerText element within the EDD.

Controlling banner text display

Once you’ve defined the text to be displayed when creating new structure, you can also define whether the banner text should be redisplayed when the document is reopened. To do this, open the maker.ini file, found at

C:\Program Files (x86)\Adobe\AdobeFrameMaker11

If you use a text editor like Notepad++ (free, and available at http://notepad-plus-plus.org) that displays line numbers, you’ll find the Banner Text Preferences at or about line 496. You can also use FrameMaker as a text editor (with or without line numbers, but for simplicity, I’ve chosen a separate text editor for editing non-Fm and non-xml files here.

Specifically, among the options you will find the RedisplayBannerTextForEmptyElements flag. Setting this value to Off will prevent the banner text from displaying when a file is reopened.

Producing print and PDF output

Once you’ve created and edited your DITA topics, you can organize them into structures for output and navigation. The DITA structure provided for this function is a ditamap.
Ditamaps resemble FrameMaker books in many ways, but mainly they are simply a way to provide context to your topics, and they also provide easy navigation to a potentially large number of small topic files.
Ditamaps provide an excellent way to organize non-PDF electronic output, but for PDF output, it’s better to process the content into traditional FrameMaker structures that are easily output to PDF.

The windows look similar, but the FrameMaker book file (shown below) references .fm files, and includes generated files for TOC and other common book structures.

Saving a ditamap as a FrameMaker book

To save a ditamap file as a FrameMaker book, make a ditamap your active document on FrameMaker and use the File > Save ditamap as > Book 11 with fm components option.

FrameMaker will convert the active ditamap to a book, convert referenced DITA structures to FrameMaker components (.xml files are converted to .fm files) and specific generated documents are created, based upon settings in the ditafm-output.ini file. You will find the ditafm-output.ini file in the C:\Program Files (x86)\Adobe\AdobeFrameMaker11\fminit\ditafm directory.

The defaults for this file are pretty solid, but if you find you would like to change conversion behavior, open the .ini file in a text editor (I used Notepad++, for reasons stated earlier) and browse the settings available. There are comments to help explain the settings, and you can change behavior by using 0 for false, and 1 for true.

As you can see, there are 364 lines in my copy of this initialization file, so you might find it helpful to browse the sections (sections are wrapped in [ and ] )

Saving the book file as PDF

Almost across the finish line now…

Take your new .book file, make sure you can open all files, and update the book as you would any other FrameMaker project. Confirm that the Adobe PDF print driver is selected, and select File > Save book as… > Adobe PDF.

NOTE: I use the free plugin from sundorne.com to set FrameMaker to the Adobe PDF print driver

Wrapping up

I find working with DITA in FrameMaker to be quite intuitive, especially after tweaking some of the setting mentioned in this post. FrameMaker is without question one of the easiest ways to produce PDF from DITA content, and users comfortable with configuring structured FrameMaker will appreciate the automation of conversion settings, and the reliance upon long-standing FrameMaker conventions like master pages and EDD controls.

About our Guest Blogger:

Matt Sullivan is an Adobe Certified Instructor and Adobe Certified Expert in ten different Adobe publishing and e-learning applications, including everything in the Technical Communication Suite 4. He teaches online and in-person classes as well as helping companies improve their publishing workflow. Matt spent years setting up electronic prepress departments for commercial printers prior to the start of his training career. After that, Matt ran his own Adobe Authorized Training Centers (GRAFIX Training, in southern California), managed the training arm of roundpeg, Inc., and co-wrote the definitive FrameMaker 11 reference book, Publishing Fundamentals: Unstructured FrameMaker 11. He has represented Adobe in countless conferences, trained FrameMaker support personnel, presented webinars, and assisted in Adobe pre- and post-sale engagements. To learn more about Matt, and what he does, you can perform a web search on his social media id, mattrsullivan.