Steve Salter

An important part of technical writing is numbering. You don’t have to look far in the Tech Com world to find frustration with an application’s ability to handle numbering - and if you’re using Word you know what I mean. (I’m using Word in my paid job…)

Flare is quite adept at numbering - when you know how. In this first of maybe many blogs I want to examine numbering using complex selectors and the style sheet.

It is quite simple to create an ordered list - one that numbers the items. (An unordered list is one that most of us refer to as “dot points”.)

Just type your list item and apply the numbering from Flare’s format toolbar.

But, what if you want 2 levels to your list?

That’s easy - the Flare Stylesheet Editor is set up to allow you to format the complex selector ol ol - the one that sets the style for the second level of numbering.

Here I’ve set my lower level to lower case alphabetical characters. And the result:

So far, so good. The Flare interface has allowed me to create 2 depths to my list. But wait, I want more!

You’d be right in guessing I need a complex selector ol ol ol. Trouble is, the Flare stylesheet editor doesn’t have it! We can overcome this limitation using our favourite text editor. Open the stylesheet and enter the following at the bottom (I’m using Notepad++):

You can either add the formatting for the third level in the text editor, or you can save the stylesheet and open it with Flare’s stylesheet editor to format the level you just created. I’m using lower case roman for my third level:

Once you have set up your stylesheet, you can control your numbered list using the indent button on a list item.

Flare uses cascading style sheets to apply formatting.

Unfortunately, the similarity between a word processes and the Flare interface is setting the new user up for a shock. At the top left of screen you have a dropdown list of styles, similar to Microsoft Word. There is a styles pane, where the styles applicable to the tag you’re in are listed (and there’s the first trap). You can select some text and apply a style, just like your favourite word processing application.

What’s different is Flare’s using a web compliant standard known as cascading style sheets. Sure, those of us with enough grey in our hair can remember the earliest versions of word where you selected a block and applied markups to control formatting, but Word has hidden all that from the user.

We all know the reason for using a style, rather than applying inline formatting. If we use a style, and want to update that style, we can go to the style sheet and change it once. Everywhere the style is used is updated on the next refresh. If we used inline styles we would have to proof read the entire project, changing instances of the old style to the new.

And, to be fair, Word does let you do that.

The trouble is Word creates printed documents, and isn’t designed to create online help. Okay, you can save it as rich text, use certain hidden styles and feed it through the Microsoft Help Workshops to create HTML help, but it’s not a very intuitive process.

So, because Flare makes HTML help (and other online help) as well as printed documentation we have to get used to using web standards - HTML is a web standard as well.

Remember I said “there’s the first trap”? A common question on the Flare forum is “Where did my style go?”. If you create a custom style in Flare it will create a class for the parent tag selected at the time. Confused? Try this:

1. Select a paragraph
2. Make sure the styles pane is open ([F12] if it isn’t) and click Create Style

A create style dialog box opens

1. Name the style
2. Select the style sheet where you want the new style
3. Make sure Create style and update the source element is selected
4. Click Okay

I named my style Look, I want it to grab people’s attention.

You can now create the style format (this is one way, there are others):

1. Place the cursor in a paragraph you’re going to format as Look
2. Select p.Look in the styles pane
3. Click Edit Style

The style sheet editor will open.

1. Select Look (it’s under the p element, click the + to expand)
2. Expand the font properties
3. Set color to red
4. Set font-weight to bold
5. Save the stylesheet

When you go back to your topic, the selected paragraph id bold and red.

And that should be the end of it….

…Untill you want to apply the style to a list item.

You select a list item, look in the styles pane and see nothing. Your look style isn’t there.

What you need is a generic class.

The easiest way is to modify the style sheet using a text editor:

1. Backup your stylesheet
2. Right click the style sheet in the content explorer
3. Select open with
4. Click Internal Text Editor
5. Scroll down to p.Look

1. Delete the p
2. Save the style sheet

Now when you select a list item you can see the Look class.

In fact, .Look is available all the time - it’s now a generic class. Of course, you could straight out add it to your style sheet in your favourite text editor. Which. now you know about generic classes, is probably what you’re going to do.

I must ‘fess up. Despite the <tongue in cheek> air of culture and sophistication</tongue in cheek> I try to exude, I’m a petrol head.

This afternoon friends are coming around to watch the V8 supercars (Oz’s premier sedan racing class). We’ll have a meal (Chris’s putting the final touches on it now), a few drinks, cheer the Holdens, and boo the Fords. We’ll have a good afternoon as always.

But yesterday a mate and I went to the tractor pulls. It’s a great day, and it’s what motor sport should be. You get to stand a few metres from all the action. Just a light courtesy fence that a five year could cross without difficulty between you and the action. The noise, the smell of high octane fuel, the excitment of big block Chev’s running at the limit while travelling at a snail’s pace right in front of you….

It helps a rural community, struggling with the drought. We come, we see, we eat, we drink. We pay our admission fee. But it’s not a rip-off. A full day’s entertainment, some Jim Beam, steak sandwiches (with real steak) and I didn’t spend over fifty buck! THAT’s value.

The commentator walks up and down between the tractors, wisecracking in a way that everyone wants to but can’t, becasue they want to be politically correct. I mean, the whole concept of a pulling competition is open to the lowest form of puns, but this guy knows where the line is. He crossed it 5 minutes after he started so he has you in stitches for the rest of the day. And, he knows his stuff. Like why the 327 sounds different to the 350 Chev. Why Chrysler (Mopar) gave up motor sport dominance overnight. All the things petrol heads love and everyone else says “So what?”.

And then there’s the Merlins. And sisters to the Merlin, the Allison and the Meteor. These are motors from the 1930s and 40s. They put them in the front of Spitfires and other legendary fighters and bombers. The meteor was the same thing driving tanks, or side by side in patrol boats (remember McHale’s Navy?). Over 1700 cubic inches of v12. We sometimes go to the aviation museum’s engine runs, just to haer a Merlin idling…

There are tractors with these beats as well. That’s what I go for. They sound magnificent. But its not only the sound, its the vibration. You can feel these beasts as they try to drag the sled for the fullll pullll….

…When’s the next one?

 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).

A recent post to the Flare user’s forum raised the issue of paragraph content added automatically.

 The original post was asking about the content selector and if it was possible to use it to add text to the beginning of a paragraph. In this case the paragrah should start with “Note: “.

CSS 2 does allow you to do this. You need to use the :before (and maybe :after) pseudo elements:

p.note:before {
content: "Note: ";
}

p.note:after {
content: " [end note];
}

CSS will let you number the notes as well.

You can use an explicit counter, in this case called note:

p.note:before{
content: "Note " counter(note) " : ";
}

You have to set the increment property for the counter, else it will show the same value every time:

p.note{
counter-increment: note;
}

And, if you want to reset the counter every chapter (and you use H1 for your chapter headings):

H1{
counter-rest: note;
}

This approach is technically correct and has the benefit of being a stylesheet solution - you could change “Note: ” to “notes: ” in your stylesheet to have all occurences changed. Unfortunately the content and counter properties aren’t supported by Internet Explorer (at least IE up to version 7).

Flare allows you to create paragraphs with preinserted text and numbers. And, it works when displayed in IE. Flare adds the text and the number as formatted text during the build, rather than relying on the browser to do it at viewing.

This stylesheet setting in Flare creates a comment - dark green text on a light green background, surrounded by a dashed red border:

What about the stylesheet? This is what Flare adds:

p.comment
{
 font-weight: bold;
 color: #008000;
 border: dashed 2px;
 border-color: #ff0000;
 background-color: #90ee90;
 mc-auto-number-format: ‘R:COMMENT {Gn+}: ‘;
 mc-language: none;
}

The smoke and mirrors come from the property mc-auto-number-format. R:COMMENT {Gn+}:

The R is the series (or specific counter). I could have used something else, but in this case R for remark (the original text added to the paragraph).

Comment is the text added to the paragraph. As I said, originally I added Rem x:, but decided Comment x: read better.

Lastly we have a global counter increment command {Gn+}. If I wanted a chapter based counter, I could have used {n+}. The plus sign means the counter is incremented, to display the value without incrementing use {n}.

If I used a chapter based numbering system I’d want something like R:COMMENT {chapnum}.{n+}: . That would give me COMMENT X.Y: , where X is the chapter number and Y the comment number, resetting with each chapter.

You could use a numbered list as well, but if you want to add some default text and if the elements aren’t close in the topic, you might find it harder than getting your head around auto numbering.

Adelaide, where I live, has just rewritten the record for a heat wave experienced by an Australian capital city.

We sweltered through 15 days with the temperature above 35 degrees Celsius. That’s 95 degrees for our US friends. The last 13 days were all over 38 (100). And, 3 days were over 40 (105). Hot, damn hot.

As a volunteer firefighter it was enough to cause some anxiety. Okay, a lot of anxiety. Fortunately there were only 3 fires of note, all far enough from home that we weren’t threatened. I went to one of them, Williamstown, in a command car. We spent the night shift, blacking out and making sure the fire didn’t jump containment lines. It was a quiet night, but a couple of hours before sunrise the wind sprang up and it was enough to get our pulses racing.

It’s funny. Until I joined the CFS I never stayed up all night. Not even new years eve. But the last few years I’ve gone to work, attended a fire over night, and gone back to work next day on more occasions than I care to remember. When the community thanks volunteers for their efforts at a large fire they should also thank the understanding employers who support us.

They say the heat wave is a one in 3000 year event. So, if it happens next year does that mean this one is for the past 3000 years and the next one is for the next 3000 years?

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).