Generating Quality Print Output from MadCap Flare or Blaze

By Matthew Ellison

Bookmark and Share


Contents

Click a link below to jump to a particular section; click any "CONTENTS" image following a section heading to jump back here.

Introduction    Link to the article contents

Although MadCap FlareExternal link is known primarily as a Help Authoring Tool (HAT), one of its outstanding qualities is its ability to generate high-quality print documentation from the same source files as for the Help. In fact, its print capabilities has been engineered to the extent that MadCap Software has been able to market another product called Blaze, which is basically the same authoring tool as Flare but with the capability to generate only the print-based outputs including PDF, Word, and FrameMaker—effectively Flare without the Help outputs.

The quality of a tool's print-based output is determined by a number of factors including:

  • Ability to filter and re-sequence the content
  • Ability to include professionally-formatted table of contents, index, and glossary at appropriate locations within the document
  • Ability to change the formatting properties of text and tables to make it them more suited to the print medium
  • Control of the presentation of images including size, positioning, resolution and color depth
  • Handling of hyperlinks, with ideally the option to convert these to cross-references including page or section numbers
  • Control of page layout including margins, headers, footers, pagination, and the ability to define special layouts for title pages and chapter starts

Flare and Blaze score highly on all these criteria—they enable users to customize the printed output with high precision without (in the case of Flare) effecting the onscreen Help outputs such as HTML Help and WebHelp. But in order to provide this level of control for the print output, their features and accompanying user interface in this area are necessarily rich and quite complex. In fact, my experience is that the print-oriented aspects of Flare are more challenging for new users than any other aspect of the tool.

With this in mind, I have put together the following guidelines that cover some of the key steps in the process of setting up and refining the printed output of either a Flare or Blaze project. These guidelines are intended to help Flare or Blaze users get the most from these tools, but they may also be of interest to users of other tools who would like to find out more about Flare's approach to single-sourcing. The guidelines do not tell you everything you need to know about creating print-based output, but they cover the issues that I get asked most questions about by Flare users.

For a comprehensive set of instructions on how to prepare your Flare or Blaze project for printed output, you should refer to the excellent Help system provided by MadCap. This topic is a good place to start:

Creating Print-based OutputExternal link

Overview of the Guidelines    Link to the article contents

Each of the sections below contains guidelines on a specific aspect of setting up the print-based output for your Flare or Blaze project. The sections are arranged roughly in the order in which I believe it makes sense to address the tasks. However, there is a lot of flexibility here—there may be some steps (for example, Setting up auto-numbering for headings) that you may wish to skip initially and then return to at a later date in order to refine your print-based output further.



From both Flare and Blaze there are actually four print-based outputs, which are Adobe PDF, Microsoft XML Paper Specification (XPS), Adobe FrameMaker, and Microsoft Word. In this article I focus specifically on Adobe PDF since this is currently the most popular format for providing print-based documentation to customers. However, most of the techniques described below are also applicable to the other print-based formats.

For detailed instructions relating to each of the sections, I have provided references to the official Web-based Help for Flare v5.

Adding TOC, index, and glossary topics    Link to the article contents

If you have already set up TOC (.fltoc) and glossary (.flglo) files within your project, and inserted index markers within your topics, then it is tempting to assume that these navigation devices have been taken care of. However, the TOC, index and glossary can only appear in your print-based output if you create topics to contain each of them. This is a simply matter of creating three empty topics and then inserting the appropriate "Proxy" into each. In Flare, a Proxy is a special kind of placeholder that will be replaced by the appropriate content at generation time. You can control the presentation of the table of contents and the index by using the Stylesheet Editor to set the properties of p.TOC1, p.TOC2, etc. and p.Index1, p.Index2, etc. as required.

For detailed instructions, see Creating a Topic for a Print TOCExternal link, Creating a Topic for a Print IndexExternal link, and Creating a Topic for a Print GlossaryExternal link

Creating a custom TOC for print    Link to the article contents

If you want to customize the sequence of topics within your print-based output, and perhaps omit certain topics altogether, then you can do this by creating a new TOC that reflects the content and hierarchy that you require for print. The easiest way to do this is to duplicate the master TOC by copying it, pasting it, and then renaming the duplicate copy. Having done that, you can use the TOC Editor to reorganize the new TOC and remove any topics that you do not wish to appear in the print-based output. After that, it is simply a matter of specifying this TOC (instead of the default TOC) when you set up your print-based target—this is covered in the final section.

For detailed instructions, see Creating a Table of ContentsExternal link

Creating and applying conditions    Link to the article contents

This step is important if you want to customize the content of your print-based output at a more granular level than complete topics. For example, you may wish to include screenshots that you don't want to appear in the Help, or there may be certain instructions or navigation devices (such as hyperlinks) that are appropriate for Help but that you'd rather not include in the manual. If your project doesn't already have them, I recommend you create two condition tags: PrintOnly and ScreenOnly. As their names imply, these tags should be applied to content that is specific to either the print or onscreen Help output. Note that they can be applied to image files in the Context Explorer, and they don't then need to be applied to every reference to the images within topic files. So even if an image is used 50 times within your project, you only need to apply a condition tag once to prevent it being displayed anywhere in the Help.

Flare's condition tags normally work on the basis of exclusion. Thus, in your print-based Target you will choose to exclude the ScreenOnly condition tags, and in your Help Targets you will choose to exclude the PrintOnly condition tags. It is only in specific rare circumstances that you ever need to select the Include option, and more often than not this can lead to unwanted results. Send me an email if you'd like to ask me more about this, as it's a potentially confusing area!

For detailed instructions, see About Condition TagsExternal link

Customizing styles for print output    Link to the article contents

It is usual to want the fonts, sizes, margins and spacing of text for print-based output to be different from Help. Flare enables you to achieve this by supporting medium-specific formatting in your style sheet. Best practice is to set up the formatting for all your styles without specifying a medium, and then to specify any formatting overrides that you require for the print medium. For example, you may wish to use a serif font and to express your font sizes in points instead of percentages. To set up these overrides, you simply need to select Medium: Print from the drop-down control in the Stylesheet Editor before selecting your required settings. Don't forget to re-select Medium: Default again when you are finished, otherwise any subsequent amendments you make to your style sheet will only be applied to your print-based output.

For detailed instructions, see About Style Sheet MediumsExternal link

Setting up auto-numbering for headings    Link to the article contents

Although numbered headings are rare in onscreen Help, they are useful in print-based output for being able to refer to specific sections with an indication of their location within the document. In Flare, numbering is simply a property of a style that you can set up in the style sheet. To ensure that the numbering is used only for print-based output, you simply select Medium: Print in the Stylesheet Editor (as described in the previous section) before setting up your numbering.

The numbering format property is called mc-auto-number-format, and you'll find it within the AutoNumber group of properties. The way you set up the numbering format is similar to the system used in Adobe FrameMaker, and it is based on a set of special commands. Flare provides a dialog (shown below) that enables you to construct an auto-number format by selecting from the range of available commands.

Screenshot of Auto-Number Format dialog showing available commands

Auto-Number Format dialog

Setting up these auto-numbering formats can be a bit of a black art when you are starting out with them, so here are some example formats that I often use if I want legal-style heading numbering of the form 1, 1.1, 1.1.1, etc and numbered figures:

ElementAuto-number formatExample result
h1{chapnum}1
h2CH:{chapnum}.{n+}.{ =0} 1.1
h3CH:{chapnum}.{n}.{n+}1.1.1
p.figurecaptionCF:Figure {chapnum}-{n+}: Figure 1-1:

For detailed instructions, see Creating Auto-Number Formats for StylesExternal link

Setting up cross-reference formats    Link to the article contents

Cross-references in Flare are special types of links that can be presented as straightforward hyperlinks in your Help output and as full-featured cross-references (including page or section numbers) in your print-based output. If the quality of your print-based outputs is important to you, then I recommend that you always consider inserting cross-references instead of regular hyperlinks. Once you have set up your required cross-reference format both for Help and for print, then inserting cross-references is almost as quick and easy as inserting regular hyperlinks anyway.

You set up the format of your cross-references by setting the properties of the special MadCap | xref style in your style sheet, and you need to ensure that Medium: Print is selected when you specify the cross-reference format for your print-based output. The system for specifying the format of cross-references is again similar to that used in Adobe FrameMaker, and Flare provides the following dialog for constructing the format:

Screenshot of Cross-Reference Format dialog showing available commands

Cross-Reference Format dialog

To make a cross-reference appear the same as a regular hyperlink in your Help output, you will set the format simply to {paratext} for the default medium. You might then choose to set the format to {paratext} {pageref} for the print medium, which adds the words "on page x" to the cross-reference.

For detailed instructions, see About Cross-ReferencesExternal link

Setting up page layouts    Link to the article contents

Page layouts were introduced into Flare v4 as a way of providing rich and powerful control over the layout of print-based output on the page. They enable you to specify margins, headers, footers, background images, numbers of columns, and a range of other layout features. A Page Layout is a special xml file in your Flare or Blaze project that shows up in the Content Explorer. It contains the layouts for a number of different page types which can potentially include Normal, Left, Right, First, Title, and Empty.

Flare provides a special Page Layout Editor (shown below) for setting up these layouts. It is a complex tool with many different features and controls, so I will not attempt to explain how to use it here. One tip that I will pass on, however, is to try to ensure that the successful layout of your pages is relatively independent of the page size—so that if, for example, you change the page size from Letter to A5, your text frames do not suddenly spill off the page as a result. You can achieve this by ensuring that your text frames are anchored to the margins of the page instead of having fixed widths and heights. Again, this is a challenging area, and you are welcome to email me if you need guidance on setting up your page layouts in the best way.

Screenshot of Page Layout Editor

Page Layout Editor

For detailed instructions, see About Page LayoutsExternal link

Adding and configuring chapter breaks    Link to the article contents

In order for your heading numbering to work correctly, and for your special page layout for the first page in a chapter to be applied correctly, Flare needs to know where each new chapter starts. You indicate this by setting chapter breaks at the appropriate locations in your TOC—this will normally be at every top-level book. This is a one-off manual task that many newcomers to Flare do not realize is required for each project. However, it is relatively trivial and quick to complete.

You set a chapter break by opening the Properties dialog (shown below) for the appropriate book in the TOC and selecting the Start new chapter document option. You can also select a specific page layout and page type for the first page of the chapter and choose whether page numbering is reset or is continuous.

Screenshot of Properties dialog for TOC book

Properties dialog for TOC book

For detailed instructions, see Specifying Chapter Breaks and Page LayoutsExternal link

Setting up a PDF target    Link to the article contents

In Flare, a "Target" is a collection of settings that is used to generate a particular output from your project. If you currently only have one Target (for generating Help output) then you will need to add a new Target to your project for the print-based output. The most fundamental setting in your new Target is the Output Type, which you will clearly need to set to PDF for Adobe PDF output. Don't forget also to select the custom TOC that you created above, and to exclude your ScreenOnly condition tags. There are two other key settings that I recommend you set on the Printed Output tab in the Target Editor, both of which are easy to miss. They are:

  • Use TOC for heading levels - this option causes all heading levels in the PDF output to be based on the corresponding source topic's location within the TOC hierarchy. If you don't select this, then the PDF will simply use the same heading levels that you used in your topics—and if all you topics start with a Heading 1, this would result in a very flat heading structure in your PDF!
  • Inject headings for unlinked books in TOC - this option ensures that every entry in your TOC (including unlinked books) have a corresponding heading within the PDF output. If you don't select this, you may find that certain key headings are omitted.

For detailed instructions, see Adding TargetsExternal link and Editing Target SettingsExternal link

  


Photo of Matthew Ellison

Matthew is an independent user assistance professional with more than 20 years of experience in the software industry. He is a MadCap Flare Certified InstructorExternal link and also organizes the annual UA Europe conferenceExternal link. Matthew is based in the UK and can be contacted at matthew@ellisonconsulting.com.


up

Copyright © WinWriters, Inc. All Rights Reserved.
shannonm *at* writersua *dot* com
Last modified on