Steve Salter

 Flare masterpages have another trick up their sleeve – running headers and footers.

Flare allows you to nominate a style in a special type of variable. The first occurrence of text formatted with the nominated style on each page can be substituted for the variable. If the style doesn’t occur on the page, Flare will use the previous value. Normally you would use a heading style, but you can use whatever you like. You can even create a style specially for the running header and footer.

The screen grab shows a running header in Microsoft Word. It’s the standard Flare printed masterpage, except I’ve added the special variable.

So, you’ve seen it and now you want to add running headers to your project.

The first step is adding the special variable set. Click Project -> Add Variable Set… The Add Variable Set dialog opens. Make sure you have Factory Templates selected in the left window and select Running HF in the right. Give the variable set a name, something like “Running HFs” and click Add.

The standard running header and footer variable set is added to the project – you can see it in the Project Organizer Variables folder. The basic running HF set is for heading styles 1 to 6 (h1 to h6).

You might want to use something other than a heading style for the header. You might want to identify a catchy phrase from the content and use that instead. Make sure the styles tab is showing – if it isn’t press [F12]. Select the text you want to use in your running header and footer and apply one of the styles from the style window. I’m going to use anything styled as cite for my running headers. (If you are using a heading style for your running header, just apply the heading style.)

If you are using something other than h1 to h6 you’ll have to add the special variable. Double click the runningHF variable set in the Project Organizer Variables folder. You can either modify one of the existing variables or create a new one. Creating a new one seems better to me. Click the New Item button, add a name and specify the style you want to use in the format <$paratext[style]>, substitute the style name in the square brackets. You can look at how Madcap have specified the others for help.

Once you’ve set up the variables (and applied the styles throughout the project) you can modify the masterpage to add the variable.

Open the masterpage and place the cursor where you want the running header (or footer) to appear. Click Insert -> Variable... The Insert Variable dialog opens. Select the running header and footer variable set you added earlier in the left window then select the variable for the style you’re using to choose the running header. Click OK.

Now when you create the printed output version of your project you’ll see running headers (or footers, if that’s where you inserted the variable).

The “Other” Pages
There are several pages in the printed document that can cause even more confusion. I’m talking about the Table of Contents, the Glossary, and the Index.

Much of the confusion revolves around naming conventions, and the Table of Contents is slightly more confusing than the others, so I’ll concentrate on it. If you’re creating online help, Flare uses the TOC nominated in the target properties to generate the table of contents that (normally) appears in the left hand pane of your help. You can see this in compiled HTML or .chm, web help, and dot net help. Printed targets don’t get off so easily.

The first thing to consider is Flare builds the output using the TOC specified in the project as its plan. If you want to include a topic in the output it must be in the TOC. A lot of time you will be using the “default” TOC, created when you started the project. Its name is Master and you can see it using Windows Explorer under Project -> TOCs as Master.fltoc (for Flare TOC).

When Flare builds the project, using the TOC, it applies TOC levels to the resulting Word document. Word uses the TOC levels to build the table of contents in much the same way as it does when working natively in Word. If you look in a stylesheet, each of your headings has a property mc-heading-level. You can see it under PrintSupport. Normally this value corresponds with the heading level, but if you wanted to elevate all your headings to the same level in the table of contents produced by Word you can set mc-heading-level for all headings to “1″. If you don’t want a heading to appear in the table of contents, set the value to “0″.

You can see why its confusing – Flare has a TOC for building and Word produces a table of contents. But wait, there’s more.

As stated above, Word produces the table of contents from the heading levels. But we need to tell Word, through Flare that we want a table of contents and where we would like to place it. To do this we need to create a topic for the table of contents. Most people would name the topic toc.htm, table_of_contents.htm, or something similar. That’s alright, but it introduces another toc type of name into the mix.

So, we have a topic for our table of contents. You’ve named it something clever, like topic_toc.htm, to avoid confusion. Now we have to add a proxy so Flare knows to build the table of contents. And, you’ve guessed it, the proxy is the TOC proxy. To add the proxy Insert -> Proxy -> TOC Proxy… You end up with a proxy in your topic with the description output toc proxy.

If you look at the example, which is confusingly named toc.htm, you’ll notice the text “Table of Contents”. You may be forgiven for thinking its a heading style, but although it is a large blue font and uses small caps (which is the h2 style in this project), its actually a paragraph formatted to look that way. Why? I don’t like “Table of Contents” to appear in my table of contents, and if the table of contents gets built from heading levels I need to make sure the text isn’t a heading.

You can also see a tab marked “Master”. That’s the master toc used to build my printed target.

So now we have a toc proxy in a toc topic (with the text “table of contents”) used by the master toc to create a table of contents. Can it get more confusing? You bet.

We use Chicago Manual of Style. What does Chicago say about table of contents? It starts on page 5 (depending on what else constitutes you front matter), uses roman numerals, and is a recto (odd page number or right hand side) page. You may have other considerations because of your company style guide, such as the header says “Table of Contents” or similar. Knowing what we do about masterpages, we know we are going to need a masterpage just for our table of contents.

We can create our masterpage easy enough. We can see the confusing pattern of naming occurring, so we call our masterpage masterpage_toc.flmsp. And we set Page Type -> Type to odd , Page Numbers -> Start Number to “5″, and Number Format to “i (lowercase roman). We make sure we’ve included page numbers on the masterpage.

The final step is to assign the masterpage to the topic in the toc Flare uses to build the output. Open the toc (if its the default toc you can open it by clicking the Open the Master TOC button. It looks like a hand pointing at a book ) and add the TOC topic to the master TOC (you can drag and drop from the Content Explorer). Make sure the topic is selected and press [F4] to open the properties dialog. Select the Printed Output tab and then the Start a new section check box. Choose the TOC masterpage from the drop-down list. Make sure you set the next topic’s masterpage so it doesn’t use the toc masterpage.

And that’s it. Just do something similar with your glossary and index, and you are well on the way to producing professional printed documents from Flare.

The Body Proxy
Last time out we looked at the masterpage. We used the analogy of a picture frame, where the masterpage was the frame and the body proxy the “hole” where the picture (our topic) goes.

To make the masterpage usable we need to add a body proxy. If you used one of the provided masterpages or modified one of the provided masterpages, the body proxy is already added for you. If you are feeling adventurous and creating a masterpage from scratch, you have to add it.

Insert -> Proxy -> Insert Body Proxy… Yep, that’s all you have to do. If you try to open the menu command in a page that isn’t a masterpage (it has a .flmsp extension) the command isn’t enabled.

It’s more than likely you’ll have at least 2 masterpages – 1 for online and 1 for print. The online may have breadcrumbs at the top and a mini-toc at the bottom. Below the mini-toc you may have a copyright message.

If you look at the “You are here: How to section” you will see the content created by the breadcrumb proxy. It’s a navigation aid.

Next is the actual topic. There’s a heading, “How to”, and some content.

Then we have the mini table of contents. It shows the topics in the same “book” as the current topic in the table of contents used by Flare when building the project output.

At the bottom is a copyright message, which is just text entered on the masterpage. In this case the text is a snippet, but that’s another story. A snippet is a block of formatted text you can insert anywhere. If you update the snippet it automatically updates the content of the snippet wherever it’s used.

Our printed masterpage has another trick up its sleeve – we can set the properties for the printed page. If we think about a word document we can set paper (page) size, margins, and so on. We don’t worry about that sort of thing in online help – online help normally fills the available window and wraps the text as the window resizes. If we click on the body proxy itself, a context menu opens with the option Edit Body Proxy… Select this option.

This is where you select your paper size! In the Page Size drop-down there are all the metric paper sizes. Being an Australian, I select A4.

You can format the page numbering, both page number format and start number, in the Page Numbers section. So, in the previously quoted example of restarting the page numbering when the front matter ends, you would set the Start Number to 1, leaving it at default would mean it would continue from the previous document section.

You can use the Page Type to control page breaks so the topic using the master page starts on the correct side of a duplex document. If you want it to be verso (right side) or recto (left) you can select odd from the Type drop-down list for verso pages or even for recto.

Using Masterpages for Printed Output
There is one confusing issue when using Flare (or Blaze) to create printed output, and that is the use of masterpages. Okay, there may be more than one, but I’m only talking about one confusing issue this time.

We start using Flare and get stuck into creating our content. It’s straight forward enough. You create a topic and start adding content to the topic. Add words, pictures, tables, links, lists, and so on. Format the topic – using a stylesheet is best. And, because the topic is saved as HTML, you can open it in a browser to view it. In fact, you can send the topic to anyone who can open it and view it.

So, we are happy with our topic. It makes complete sense, there are no spelling or grammar errors and it looks sensational! Let’s create some output!

All targets have a default masterpage. You set it by opening the target, selecting the advanced tab, and selecting your masterpage from the drop down list. Of course, this implies you’ve created a masterpage, but if you haven’t you can add one easily. Just use the Project -> Add Masterpage… menu commands, which opens a dialog where you can select the “factory” masterpages or one you’ve created and saved in the “My Templates” directory. And, for online help, default masterpages seem to work fine.

If you look at any printed documentation, particularly the header and footer on each page, you will notice something. Most documents that have more than a couple of pages and several sections, also have different header and footer styles throughout the document. It may be something simple, like the section name appears in the header, or it may be the page numbering suddenly appears on the 7th page but the numbering starts at 1, after the front matter. It may be the front matter uses roman numerals and the main body uses arabic. Whatever.

Flare allows you use different headers and footers by adding the header and footer to a masterpage. You need a different header and footer layout? Add it to a new masterpage and apply it to the topic. Flare will keep using that masterpage until you specify another.

Of course, you’re not restricted to header and footer with your masterpage. You can add body content as well.

A good example of body content on a masterpage is “breadcrumbs”. What are breadcrumbs? Well, at the top (or bottom, but normally top) of online help you might see “You are here: Introduction – About XYZ”. You know what I mean – you’ve seen it before. These are breadcrumbs, they show the navigation path to get where you are in the help system. Remember the story of Hansel and Gretel? They left a trail of breadcrumbs they were going to follow back. (Of course, that didn’t work, but that’s another story entirely.)

Setting up your masterpage is easy. The supplied masterpages are a good place to start. Sure, they use tables for layout, which might not be best practice for web pages, but it is a proven formula for printed (i.e. Microsoft Word) output.

Lets look at the printed doc masterpage that comes with Flare. Click the Project menu, then select Add Masterpage… Use the resulting dialog box to select the Printed Doc Masterpage from the factory templates. Add a filename, something like printed, and click the OK button. A new masterpage, named printed.flmsp (for Flare Masterpage) will open.

If you look at the top line you will see the header for an odd page. Change the text “Odd Page Heading” to something else – your printed output would look strange with the header saying “Odd Page Heading” after all. You can replace “Chapter Title” as well.

PageNumber is a system variable, obviously it will substitute a page number when your output is compiled.

If you hold your mouse over the block at left that says Madcap… the tooltip says <Madcap:pageheader> class:oddpage. If you were starting with a blank page you could insert a page heading of the odd page class by Insert -> Proxy -> Page Header… and selecting odd page from the stylesheet class.

The even page header is similar. Notice the page number and chapter number (instead of chapter title) are on the opposite side.

The final header is the first page header. This one doesn’t use a table for format, but just has a centre justified title header.

The footer(s) follow a similar concept – an odd, even, and first page footer are part of the template. Notice the first page has a system variable to insert the system date, formatted in long date format.

If your first page is the same as the rest, you don’t need a first page header, just odd and even. If your pages are the same (for example, just a centre justified page number) you don’t need any footer or header proxies – add the page number to the masterpage.

The last thing to notice is the topic body proxy. If you remember the picture frame analogy used earlier, the body proxy is the hole in the picture frame. When Flare compiles the output, your topic is displayed in the “hole”.

To finish, this is a masterpage I used in a project:

Notice the formatted “Draft” and “Not for Release” text? The page numbers have been moved to the bottom, in the middle on the first page and outside on subsequent pages. There is a variable called “App”, which is defined as “Records Maintenance”. At compile time all instances of App are changed to Records Maintenance.

Finally, a caveat. You can apply a stylesheet to a masterpage. The thing to remember is in the cascade, Flare adds the topic to the masterpage, so any property set in your masterpage stylesheet overwrites the styles from your topic stylesheet.

Hopefully this explains a little bit about the Madcap Flare (and Blaze) masterpage(s).