Answer to Mimic Question from DocTrain East Workshop on Nov. 1

Let's say that you create a text caption box in a Mimic movie frame, add some text that includes a variable, and size the text caption box so that its borders fit tightly around the text. Furthermore, let's say that the value of the variable is "ABC".

If you then change the value of the variable to a longer entry, such as "MadCap Software, Inc.", might some text be pushed outside the borders of the text caption box? Yes.

If so, how do I fix this to be sure that all the text fits inside the borders of the box? You have to adjust the size of each text caption box by hand. A better solution is to size each text caption box whose text contains that variable so that all the text will appear inside the box when the variable's value is set to the longest possible entry - e.g. "MadCap Software, Inc." This way, you know that all the text will appear in the box when you use shorter variable values. There will be some excess white space in the box, but you won't run the risk of having to modify the size of the box every time you change the value of the variable.

Chrome - the Google vs. Microsoft War Heats Up...

After a three-month hiatus, the blog is back...

In February, I wrote a column called "The $44.6 Billion Paradigm Shift" for STC's Intercom magazine. The column looked at Microsoft's aborted attempt to buy Yahoo and what that meant strategically. The gist of the column was that Microsoft saw a long-term threat from Google as the latter works to shift applications from the desktop to the web. Such a shift would make Microsoft's domination of the desktop irrelevant and cause a disastrous cut in Microsoft's revenue stream. (If you don't need the desktop, you don't need Windows...)

The latest sally in this war comes from Google with its release of Chrome in early September. On the surface, Chrome is just a browser. But it also offer an environment in which to run applications like Google Docs, without going through Windows. It has a ways to go today; we're looking at v.1 or, more accurately, a beta v.1 that really uses the Chrome interface to launch the application, which then opens in your regular browser. But the idea is likely to be refined in later releases, just as Microsoft went through several early releases of Windows before getting it (largely) right. If you remember the infamous Microsoft Bob, you get the idea.

I'll discuss Chrome in more detail in my Bleeding Edge column for STC's Intercom. If you're not an STC member but would like a copy of the column, email me at the beginning of November.

One side note about Chrome - how does it work with the output from popular help authoring tools. In a totally unscientific test, I tried viewing two different WebHelp projects through Chrome, one created in RoboHelp 7, the other in Flare 3.1 and then imported into Flare 4. The results?

Everything seemed to work in the Flare project - graphics, links, formatting, and navigation tabs (TOC, Index, etc.)

Almost everything seemed to work in the RoboHelp project. The graphics, links, and formatting all worked, which makes sense since they're basically standard HTML. But I ran into two problems. First, when I opened a topic containing a Captivate movie, the movie display box appeared but a message indicated that I needed to download the Flash player. I did and the movie ran fine, but I'm not sure why I had to download the player since it was already on the machine. More serious was the fact that the navigation tabs displayed but the TOC and Index tabs were empty. More research on the horizon...

Remaining Questions From Remote Flare Course

Sorry about the delay, folks. Here are the answers to the remaining questions…

How to control the indent of a table – To set a global indent, open the Stylesheet Editor, select the tr style, open the Box properties group, and set the indent by using the margin-left property. To set an indent for one table, or one group of tables, create a new style class under the tr style, such as “table indent style 1” or the like, then select the new style, open the Box properties group, and set the indent by using the margin-left property.

Find Results window not displaying – If you recall, the Find Results window didn’t open when I ran a search in the advanced course. This was due to some undetermined layout setting. To fix this, reset your layout to the default (Window > Layouts > Reset Window Layout…) and try the search again. The Find Results window should display perfectly at the bottom of the screen.

Is there a “Keep With Next” or “Keep With Previous” setting for print out- put to prevent two page elements from splitting across a page break, such as keeping a paragraph and a numbered list together? – Yes, but it’s not labelled as such. In the Stylesheet editor, open the PrintSupport properties group for the style that you’re formatting and select either the always or avoid value, as needed, for either the page-break-before or page-break-after property, as needed.

First Issue From the 7/21-7/22 Advanced Flare Course

Re the exercise on page 103 about finding and removing unused style classes from a CSS - I looked in the original dept_styles.css file, in the Files folder, and it does contain the p.temporary class. This means that I probably accidentally deleted p.temporary from the css in the project when I was moving other style classes out from under the Print Medium. So you should have found p.temporary in the dept_styles.css file that you imported into the project and should have been able to delete it per the exercise.

More to come over the next few days.

A Word and Framemaker File Import Peculiarity in MadCap Flare

If you've ever imported Word or Frame files into Flare, you may have tripped over a peculiarity in Flare's Word Import Editor and Frame Import Editor. It has to do with how two features in these editors can conflict and produce often totally unpredictable results.

The first feature is the New Topic Styles tab. This feature scans the file to import and lists all head styles in that file. You can then tell Flare to split the file by splitting on specific head styles. For example, if Flare finds head 1, 2, and 3 in the incoming file and you specify head 1 and 2 on which to split, Flare creates a new topic every time it finds text in head 1 or 2 style. Text in head 3 style remains a part of the head 2-level-based topic that contains it. So far, so good.

The second feature is the Options tab. This feature scans the file to import, counts the number of characters in it, then lets you split the file at character X. The default length is 10,000 characters, with a default of 1,000 in the split document. For example, if a file contains 10,001 characters, Flare will not split this document because it exceeds the minimum length to be split (10,000 characters) but does not meet the minimum length required for the file to be split out (1,000 characters). If the a file contains 11,001 characters, then it meets both minimums (10,000 characters overall plus 1,000 characters for the split). The result is two topics, one of 10,000 characters and one of 1,001 characters.

The result is actually a bit more complex since there's a risk of the split occurring in the middle of a paragraph. So Flare actually splits the file at the whole paragraph nearest the split point. As you might imagine, it's hard to predict where the file will be split. Ignoring this issue, however, the split-on-number-of-characters feature is pretty straightforward. So what's the problem that I mentioned at the beginning?

The problem is that this split-on-number-of-characters feature is turned on by default. If you look at the Options tab on the Word or Frame Import Editor, you'll see that the two "Add..." options, the "Split..." option, and the "Avoid Creating..." option are all selected. The result is that if you also use the Heading style options on the New Topic Styles tab to split incoming files, you have absolutely no idea how Flare will create the new topics.

So, if you want to use the Heading style options on the New Topic Styles tab to split incoming files, go to the Options tab first and deselect the two "Add..." options, the "Split..." option, and the "Avoid Creating..." option. Then you should be fine.

Why Migrating From Word To An XML-Based Document Authoring Tool Won’t Be Easy …

Every once in a while, you run into a situation that supports a position of yours to a tee. Here’s one…

XML-based authoring tool vendors claim their products are getting easier to use with each release. They’re right. Comparing today’s xMetal to the original is like comparing night and day. However, my position is that there are four unfortunate corollaries to this trend that are going to make life tough for many doc groups in the next few years.

1 - As the tools get better, the need for authors to understand the underlying technologies is apparently declining. For example, if a tool lets you define styles by using a dialog box, do you need to know CSS coding, or even what CSS is? Which brings us to…

2 - As the tools get easier to use, there’s a sense in many companies that there's less need for training.

3 - XML-based authoring tool vendors talk about authors using their tools to create content much the way authors do now with Word. The implication is that migration from Word to an XML-based authoring tool is conceptually similar and thus shouldn’t be too difficult.

4 - The XML-based authoring world is very different from the Word world, and those differences are going to create some unfortunate assumptions.

The result of these corollaries is a lot of confusion, which brings up that situation I mentioned. (Before I proceed, let me make clear that what follows is not a slap at xMetal. It’s just that a very basic feature of xMetal illustrates the four corollaries perfectly.)

To create a new document in xMetal, you select File > New.

The first decision point, and problem, is whether to create a document from a template or a blank document. It’s confusing since any new document is “blank.” What this is really asking is whether to create a new document based on a DITA template or a non-DITA template, specifically XML or SGML. If authors understand the difference between DITA, XML, and SGML, it’s an easy decision. But if authors don’t understand the difference, haven’t been trained, and are thinking in Word terms, the very first step in a new project is confusing.

The second decision point, and problem, is when you decide that the General tab options make sense since you want to create an XML document rather than a DITA document. The help even says to choose the DTD, schema, or rules file for the document you want to create. But if you select the Blank Well-Formed XML Document option, there’s no place to choose the DTD, schema, or rules file. You’re just thrown into a new document. But if you select the Blank XML Document option, xMetal asks you to select the DTD, schema, or rules file. So there’s something different between the Blank Well-Formed XML Document and Blank XML Document options, but what? And isn’t a document that’s well-formed, whatever that is, better than a document that’s apparently not well-formed? And why would any tool let you create one? It all makes sense once you understand that the Blank XML Document option is really the Blank ‘Valid’ XML Document option, if you can find someone to explain this. If not, authors coming over from Word will again be lost on their first step.

The solution, of course, is to understand XML’s underlying technologies, ideally through directed training as opposed to floundering through a new technology. This may seem like a lot to read into one menu selection, but there are many assumptions behind that one menu selection that, if unaddressed, will leave new authors lost and frustrated.

Follow-Up to Yesterday's Post About AIR

If you read yesterday's post when it went up, be sure to go back and look at the comments section. Two very useful comments from consultant Peter Grainge and AIR Product Manager Rob Christensen.