Creating Print-based documentation from MadCap Flare

MadCap Flare's XML Editor is based on standard Web technologies including XHTML and CSS. This makes it a natural choice for HTML-based documentation that will be displayed in a browser. However, Flare also does a good job of producing well-formatted and professional-looking print-based documentation. I use the term "print-based" to mean any documentation that is rendered on fix-length pages (for example in A4 or Letter format), even if it is read on screen rather than printed to paper.

I have picked out seven key challenges that you will typically face if you are adding support for print-based documentation within a Flare project. For each of these, I provide tips that I have found useful in real-life projects.

1. Adapting the styles and formatting

Your company may have different style guides for on-screen and print-based documentation. For example, you may need to use a sans-serif font (such as Roboto or Open Sans) for your online Help, and a serif font (such as Garamond or Times New Roman) for your user guides in PDF format. You may also want your headings to be numbered for your print-based output.

You can cater for these differences within a single stylesheet by adding styles for a specific medium. I typically write the styles I want for HTML (on-screen) output within the main body of my stylesheet, and then include a section containing print-specific overrides at the end of the stylesheet. Here is an example of a print-specific section that changes the default font to Georgia 11pt, and adds chapter numbers to top-level headings:

@media print
{
   body
   {
      font-family: 'Georgia';
      font-size: 11pt;
   }

   h1
   {
      mc-auto-number-format: 'Chapter {chapnum}: ';
   }
}
			

2. Providing page numbers within links

When Flare outputs to PDF, all links (including both hyperlinks and cross-references) remain active, which means that readers can click to follow a link when reading the PDF on screen using the free Adobe Acrobat Reader. However, if you expect your PDFs to be printed, then links are obviously no longer clickable (on paper), and a page reference that enables the reader to find the referenced topic is very helpful.

If you use cross-references rather than hyperlinks for your links, then page numbers are added automatically by default to the resulting links in the PDF output. By configuring the special MadCap|xref style or adding your own classes to this style, you can specify the precise format of these page references, or even replace the page reference with a heading number. Cross-references have other significant advantages over hyperlinks, and I always use them when I am linking to another topic within the current project.

3. Controlling page size and layout

One of the defining features of print-based output is that it has a fixed page size and layout (including margins, header, and footer). In Flare, you use a Page Layout (.flpgl) file to set up your required page size and layout. If you are creating one of these Page Layouts from scratch, I recommend you base your new file on one of the provided Factory Templates that includes the word "resizable". The simplest of these is NormalResizable (shown in the screenshot below), which provides a good basic starting point for any Page Layout.

Within a single Page Layout file, you can create different layouts (or Page Types) for your title page, the first page of each chapter, and even for left and right pages. If you need to switch page layouts mid-document (for example to switch to landscape format for a specific section) then you will need two different Page Layout files (one in portrait and the other in landscape format), and you can switch between them by inserting a Page Layout Break within your TOC, as shown here:

4. Controlling pagination

One of the most common issues that authors experience with print-based documentation is page breaks occurring at inappropriate locations - for example, between an image and its accompanying caption. The solution to this is not to insert page breaks manually, but instead to use a combination of styles and divs to specify where page breaks should not occur.

Taking the example of an image and its accompanying caption, one way to prevent them being split by a page break is to define a new div class (perhaps called div.NoBreak) with its page-break-inside property set to avoid. You can then group the image and the caption within this div, as shown in this code:

<div class="NoBreak">
   <p class="ImageCaption">Caption Text</p>
   <img src="../Resources/Images/sample.png" alt="Sample Image" />
</div>
			

5. Imposing a properly structured heading hierarchy

A golden rule I always follow when authoring in Flare is to start every topic with a top-level heading (h1). This makes sense for HTML output where each topic is a separate self-contained page. However, it could result in an unwanted flat heading structure in my PDF output, with the document consisting entirely of chapter-level sections. The way to avoid this is to use a simple (but somewhat hidden) option on the Advanced tab of the PDF Target Editor, as shown here:

Selecting this option results in the topic headings being changed based on each topic's level within the TOC hierarchy. For example, topics at the second level of the TOC will have their h1 heading changed to h2, third-level topics will be changed to h3, and so on. This enables you to use the TOC Editor as an outliner for controlling the heading structure of your PDF output, without needing to worry about applying different heading styles within the topics themselves.

6. Adding front- and back-matter

Print-based documentation typically requires additional pages, such as a cover page, a back page and a copyright page, that are not appropriate for HTML output. I usually create a special folder within the Content Explorer to contain the topics for these pages, and I apply a PrintOnly condition to the folder. This enables me easily to exclude these pages from the HTML output.

To add the topics to the document, you simply drag them into the appropriate locations within the TOC. Don't forget that you may need to insert Page Layout Breaks for these items in order to apply the required associated Page Layout or Page Type.

7. Adding print navigation

For users to be able to navigate a printed manual, you will want to include a Table of Contents. For longer manuals, especially if you expect them to be printed, you should also consider including an alphabetical index at the end of the manual — but this is only worthwhile if you have taken the time to insert a comprehensive set of Index Keywords within your topics.

One way to include a Table of Contents in your PDF output is simply to select the Generate TOC Proxy option in the Target Editor, as shown here:

However, this always adds the Table of Contents at the very start of the document, and does not allow you to precede it with a cover and/or copyright page. I recommend instead creating a topic for your Table of Contents (it will need to contain a TOC Proxy) and then adding that topic to the required location within your TOC. This enables to you select the precise location of the Table of Contents within your document. If required, you can do the same for your index and glossary.

Conclusion

MadCap Flare includes a powerful set of features for controlling the content, layout, and format of your print-based output, while still using the same source as for HTML-based output. Some of these features require a significant investment in time to configure correctly, but once set up are easy to use from then on, and are relatively maintenance-free.