Tech Write Tips

July 31, 2006

We’re back…

Filed under: Tip — AndyR @ 6:26 am

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.


July 20, 2006

Best Pratice: Flare 4 – High Definition PDF Part 2

Filed under: Best Practice,Madcap Flare,Technology — AndyR @ 7:00 am

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.

July 19, 2006

Best Pratice: Flare 4 – High Definition PDF Part 1

Filed under: Best Practice,Madcap Flare,Technology — AndyR @ 6:59 am

prime.jpgIn 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.

July 12, 2006

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

Filed under: Madcap Flare,Tip,Tool — AndyR @ 12:35 pm

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.

flare_layout.gifPictured 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

Filed under: Tip,Tool — AndyR @ 6:55 am

replace.gifSo 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.

July 11, 2006

Best Practice: Flare 2 – Automated Themed Topic Types

Filed under: Best Practice,Future-proofing,Information Types,Madcap Flare — AndyR @ 12:38 pm

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.

July 6, 2006

Best Pratice: Flare 1 – Reporting

Filed under: Best Practice,Madcap Flare,Tool — AndyR @ 12:32 pm

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.

July 3, 2006

Screen Portrait Mini’s

Filed under: Best Practice,Technology — AndyR @ 5:00 pm

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.

June 28, 2006

HTMLHelp Multiple Page Printing

Filed under: HTMLHelp,Technology — AndyR @ 6:55 am

HTMLPrint.gifIt wasn’t until I was reading of another authors struggle to get multiple topics printing correctly out of HTMLHelp that I realised that I had hit the problem myself. If you haven’t tried it you should try multiple page printing for your HTMLHelp and see if it still has your style applied.

The issue is that when you print multiple topics from a .chm it doesn’t just print each topic in turn. What happens is an intermediate html file is created from the selected topic. 

You can view this file as follows:

  1. Right clicking a book in the TOC of your .chm.
  2. Selecting print all topics. Leave the Print dialog open and browse to “C:\Documents and Settings\USERNAME\Local Settings\Temp”.
  3. Sort this folder by date, and you should see an .htm file thats name starts with “~hh…”.
  4. Open this file in a text editor to view how it has been compiled.
  5. Note the single <Head> section, and updated SRC sttributes for <IMG> tags.
  6. Also note the location of the .css which will reference your .chm absolutely but include the relative path from the topic and therefore not work.

Head Problem
This intermediate file only has one head section. This can cause a few headaches such as the IE header states the first topic on all printed pages. But worse than this is that if you have included any script calls or any automation in your header, or if you have a script that references header information will not work. In my case I was generating the topic title from the page title tag in the header. Therefore when I printed mulitple pages they all had the same header. Doh!

This is something that you may need to work around for your printed output. In my case I ended up including a hidden topic title that was then turned on just for printing via a “@media print {H1.print {display:block}}” in my style sheet.

CSS and JS Location Problem
This intermediate file is generated in a temp folder. To ensure that the images are displayed correctly the print routine automatically adjusts the src elements to reference from its new location. However, if you have referenced a .css or .js it doesn’t update the location.

To get around this you need to implement an absolute location to these files in your topics. You are essentially replacing the relative location (“../../Style.css”) with an absolute location (“ms-its:HELP.chm::Style.css”). These absolute references are dealt with properly in the intermediate file for printing.

May 3, 2006

What is: Vista Office Help

Filed under: Information Types,Technology,Vista,What is — AndyR @ 12:45 pm

If you haven’t this across it yet, it is well worth a look. Jenson Harrison is the Lead Program Manager on Microsoft Office. It gives the inside line on how the new UI will work in Vista.

For help authors this enables us to get a headstart with our thinking on how we will deliver help.

Posts of note for help are:

« Previous PageNext Page »

Create a free website or blog at