We’re back…

Hello again.

I’ll have a new post for you later this week. In the meantime, how about having a dig into some of the pdf generation ideas we are discussing.

Best Pratice: Flare 4 – High Definition PDF Part 2

Having introduced the concept of high definition PDF’s output straight from Flare’s source files with minimal post-production, we can now start to dig into the technologies that are used to produce it.

The XSL style sheet produces the following sections of XML-FO :

• Page Layout Definitions
  • Page Sizes and Layout
  • Branded Headers and Footers
  • Odd Even Pages
• Branded Title Pages
• It firstly calls the Flare TOC file, using the @Title element, to create the bookmarks for the pdf.
• It secondly calls the Flare TOC file, using the @Title element to create a structure for the document.
  • Table of Contents
  • Chapters
  • Main Headings
• It thirdly calls the Flare TOC file, using the @Link element to locate each topic in turn.
  • Each topic is then added to the above structure.
• Branded Back Pages 

This is all wrapped up as one big XML-FO file.

The XML-FO file is then passed into the Apache FOP engine which outputs the PDF document.

In the next part we’ll look at some of the key issues to solve with this process and the code you can use to overcome them.

Best Pratice: Flare 4 – High Definition PDF Part 1

In this article we take things up a notch. This enters the realm of the real tech tip. If you want your authoring tool to do everything for you and don’t want to delve into CSS, XML and XSL then maybe you should move onto the next post.

Those still reading, lets roll our sleves up and have a look under the hood. The aim of todays article to to produce a high quality pdf document that has at least the following features:

• Front Matter
  • Graphical Front and Back page
  • Table of Contents for the book
• Separate Chapters
  • Mini Table of Contents for each Chapter
  • Chapter name in the header
  • Clickable links from Table of Contents to relevant section
  • Marginalia (notes, references, notifiers)
• Full Bookmark tree.
• Odd/Even Pages
• Odd/Even Headers and Footers

Bit of a tall order, maybe. But with the following technology you can achieve this from your Flare source files. Once setup you can then generate it at the click of a button.

The technology we will be using are XML, XSL, XPATH and XML-FO. In part 2 we will detail the steps in this process.

Flare 3: Custom Layout – How do you use yours?

This is the third in a series of post about how to get the most out of Madcap Flare. We’ve look at Reporting and  Topic Titles, now a little post about the flexible user configurable layout.

Pictured on the right, using a screen portrait of course, is my current setup for producing help with Flare. After experimenting with a few different models, this seem to be the most productive for me. It is achieved as follows:

1. Open Flare.
2. Open a project.
3. Click the Primary tab title to select it.
4. Select Window | Floating, to float the Primary toc.
5. Drag the Primary Toc over the left pane, likely to be the content explorer.
6. Drop it on the the right arrow which appears to tile it on the right.
7. Ensure Document Dock is on via the Window menu.
8. Open a topic, which will open in the document dock.
9. Drag the document dock to the right and drop it onto the left arrow that appears over the start page so the at tiles to the left.

You can now view the Content Explorer (for direct access to the files), the Primary TOC to manage the help and edit in the Document Dock.

Additionally you can sent topics to the far right pane by pressing shift control-D.

Let me know if you agree, but for me this is a very productive workspace which minimises both navigation and page sawpping.

Create Table from Tabbed Text

So you have copied a table out of Word or some other package and paste it into your Topic or html. This comes in as tab separated rows, one row on each line. Now you want to recreate the table, but this will invovle laborious cutting and pasting right?

Not necessarily, the following procedure enables you to create the table using a simple series of search and replace commands:

1. You can use a program such as textpad (or any text editor) to performa the search and replace.
2. Replace the tab character with </td><td>.
3. Replace the line break character “/n” with “</td></tr>/n<tr><td>”
4. Then all you need to do is wrap the table with <table> tags and a little cleaning up.

This has saved me countless hours of content adjustment. Let me know how you get on, in the comments.

Best Practice: Flare 2 – Automated Themed Topic Types

As we suggested in our previous topic types post, to ensure you are ready for future help formats it is advisable that your topics provide information in clearly defeind types. This post considers how you can present these topics in an HTMLHelp in such a way that it is clear what sort of information is being communication.

Topic Titles
The first step in this task is to ensure that you have consistently named your topics, as we discussed in our delicious topic title post. You need to define a set of rules that specifies how you name your topics and then stick to it.

One rule could be to always title concept topics ‘Concepts:…’. Another might be to always include the control type in your software screen focused topics, for example ‘Select Window’, ‘Open Frame’ or ‘Close Tool’.

Dynamic Header
The next step is to include a .js file in your Flare project to output content at the top of your topic. It is advisable for this to be directly after the <Body> tag, and referenced as follows:

<script language=”JavaScript1.2″ type=”text/javascript” src=”Head.js” mce_src=”Head.js”></script>

Detect Topic Type
This head.js javascript then need to interrogate the title of the html file, (document.title) then check it:

1. If it contains concepts, then output a concept header.
2. If it contains Window, Frame etc, then output a software control header.
3. Otherwise output a procedural header.

The content of the header will need to be output with the following javascript:

document.write(‘<H1 class=”topic_type1″>’+document.title + ‘</H1>’)

In this example we are using the heading one class to apply the format, which is controlled in our .css file in flare. This can make use of colours and icons to make it clear what sort of information is being provided.

The beauty of this approach is that should you need to change the criteria or the look and feel of each topic, you simply update your one .js file.

Best Pratice: Flare 1 – Reporting

The first of our mini-series of tips for Flare, here we consider how to leverage that old RoboHelp licence to squeeze some extra information out on your Flare HTMLHelps. 

It is advisable to ensure the following checks towards the end of a help project:

1. Technical correctness check by Designer
2. Help integrity checks by Technical Author
3. Grammatical check by Proof Reader
4. Accessibility check by the Tester
    

The second stage here requires a high degree of reporting information. To aid us with this we need to leverage functionality in RoboHelp until the reporting in Flare is updated. The following process enables you to gain a whole host of additional information about your Flare HTMLHelp project. Perhaps you CAN have your cake and eat it:

1. Towards the end of your help project in flare.
2. Generate output and save a log of the issue as a report.
3. Run through this report, correcting the errors.
4. Generate output again.
5. Take a copy of the temporary output from:
   1. PROJECT\Output\USER\Temporary\Microsoft HTML Help\Content.
6. Open the _Temp.hhp in your legacy copy of RoboHelp.
7. Work through the topics in the RoboHelp Broken links section to fix links back in flare.
8. Select the TOC in Robohelp, check through the list for topics not included in the TOC. Add these items into the TOC back in Flare as appropriate.
9. Select Tools | Report in RoboHelp and use any additional reports to check content.

Screen Portrait Mini’s

Further to our discussions about screen portraits (our cell shaded alternative to screen shots) Another case for the importance of screen portraits is the fact that Vista Super Tooltips enable you to include images in the popup pane.

These images can provide graphical clues about the use of a function, or provide a preview of the dialog that will appear when an operation is selected.

These inevitably nudge us back towards providing more screen shots, and therefore greatly increase the maintenance load on the online help (or should we now say User Assistance). If a screen portion or layout is adjusted you suddely have a stack of updating to do in the help files.

Screen portraits enable you to include these graphical enhancements to toolstips and topics, but minimise the maintenance cost. You should not need to update the images unless a screen or function has been completely revised. If this is the case you would likely want to revisit the help in any case.