An Addition to the Previous Post...

I Forgot...

A tip of the hat to Alvaro in MadCap tech support for clearing up a point about the style properties groups. Thanks...

Notes about Flare’s Style Sheet Editor

Flare’s style sheet editor is very powerful but has several attributes that can be confusing.

One such attribute is the variety of styles, including unusual ones like "generic pseudo-class". Another such attribute is the many properties available for those styles. Another is the combining of the properties into functional groups like Font, Background, or Block, which means that a property can appear in several groups.

This last attribute raises two questions – what do the different functional property groups do? And, if a property appears in several groups, is it the same property each time?

I’ve heard these questions often but never got around to writing anything about them until getting a question (thanks, Jennifer) in a CSS course that I recently taught for MadCap. The question was – “I don't understand the difference between padding in the Box, Cell, and Padding groups in Flare’s stylesheet editor.”

As noted above, MadCap combined many style properties into groups depending on their function. This means that some properties, like Padding, will show up in multiple groups because padding applies to different functions, like paragraph and table cell formatting.

Are the repeated properties simply the same property used in several places? To check, you can list all the properties using the Show: Alphabetical List option on the style sheet editor’s toolbar. If a repeated property is actually the same property, it will show up once in the alphabetical list, exactly what happens with the Padding properties.

Regarding the three functional groups in the question above – Box, Cell, and Padding:

- If you want to format a table cell, use the Cell or Box group properties.

- If you want to format a text paragraph, use the Box or Padding group properties.

Each case, table cell or text paragraph, can be handled by the properties in either of two functional groups, so you'd choose between those groups by finding the one that offered the specific properties you needed. For example, if you want to format a table cell and need to set the margin, select from the Box group. If you didn’t need to set the margin, you could select from either group.

Some Thoughts about “User-Generated Content”

These days, the term “user-generated content” is usually interpreted as content generated by users via mechanisms like blogs, wikis, Twitter, etc. But there’s another way to view the term that I’ve run into recently – content generated by SMEs (subject matter experts) via Word (can also be Frame), to be automatically turned into online help using a tool like Flare or RoboHelp. In other words, an online help project in which the SMEs do the work, with little need for an online help developer after the initial project setup. I’ve run into two such cases in the last three months, both involving Flare.

Both clients wanted to take material written in Word by SMEs and convert it to WebHelp help format. The material changed often – daily in one case – and passing it through a Flare developer was a potential bottleneck. So the idea was to buy Flare and set up the project using the auto-reimport feature. When it was time to generate the output, this feature would check the imported Word file to see if there was a later version and, if so, reimport the new version and regenerate the WebHelp. Could this work?

The answer is yes, with one big caveat. Reimporting the Word file overwrites the results of the previous import. This isn’t a bug; it’s just the nature of a reimport. But the result is that, until the vendors change how their reimport feature works, it means that SMEs can only use features that they can add in Word. Flare-specific features won’t work, and Flare simply becomes an output generator. Why?

Let’s say you import a Word file into Flare and, by breaking the file at the level 1 heads, wind up with ten topics. You then add Flare-specific features, such as links or index entries, to those ten topics, and clean up any bad formatting that crept into the Word file. As it often does…

The problem is that the next time you reimport that Word file into Flare and wind up with new versions of those ten topics, the new topics overwrite those from the prior import and all your Flare-specific features and formatting corrections will be gone. You’ll have to recreate them. This usually isn’t hard, but it’s time-consuming and reduces the automated component of the publishing that the client wanted in the first place. According to MadCap tech support, there’s no workaround to this problem. The nature of a reimport is that it over-writes the topics created in the prior import, period.

So this issue has at least two ramifications if you’re looking for a way to automate the process of creating online help.

First, because the reimport overwrites the topics in Flare and any Flare-specific features added to those topics, all the writing, formatting, linking, indexing, etc. must be done in Word since that’s the only way to guarantee that those features won’t be overwritten. In effect, Flare becomes an output generator rather than an authoring tool.

Second, the overwrite of the topics also means that formatting corrections that you made to the Word file prior to importing it into Flare will be lost; you’ll have to make those corrections again on the next reimport pass. For example, if an SME used local formatting on a table and you had to fix that formatting to get the table to display correctly online, you’ll have to fix that formatting again on the next reimport pass. The only solution to this problem, and it’s far from foolproof, is to get the SMEs to use Word correctly, or at least less incorrectly. Provide them with Word templates, sell them on the idea of using the templates, and teach them how to use the templates correctly.

RoboHelp 8 and DITA

If you use RoboHelp 8, you can start getting your feet wet with DITA without necessarily buying a DITA authoring tool. You can’t create DITA maps or topics – that capability won’t be available until, presumably, RoboHelp 9. But you can import DITA maps and topics into RoboHelp 8 to see how well it handles DITA features and how well it turns the DITA material into outputs like WebHelp.

The sticking point is that RoboHelp 8 uses the DITA Open Toolkit (OT) to import DITA material. This means you need the properly configured OT on your PC. If you typically work in RoboHelp’s GUI, installing and configuring the OT will be far more techie than you’re used to. The instructions below should help make the process easier. (Note that some version numbers may have changed since I wrote this. In particular, v. 1.4.3 may have been replaced by v. 1.5.)

Download and unzip the OT from:

http://sourceforge.net/projects/dita-ot/files/#

This will create, among other things, a folder called doc that contains the installation instructions.

Then, if you’re a Windows user, follow the instructions at:

C:\ditaot\DITA-OT 1.4.3\doc\ installguide\windows_installing.html

A crucial step is to be sure your environment variables are correct. You’ll know if they aren’t if you try to import a DITA map into RoboHelp and get this message (shortened somewhat here) in RoboHelp’s Output View pane:

C:\DITA-OT1.5\build_preprocess.xml:269: java.lang.VerifyError: (class: topicpull, method: …
...
Inconsistent stack height 1 != 0

Again, this probably means your environment variables aren’t set correctly. To fix them, follow the instructions in the document at:

C:\ditaot\DITA-OT 1.4.3\doc\installguide\ windows_settingenvvariables.html

However, be aware that some of the settings needed for your PC, particularly the JAVA_HOME setting for the folder where you installed the JDK, may differ from those in the setup instructions.

Note also that some environment variables are optional. For example, if you do not plan to output JavaHelp, you can ignore the JHHOME setting. If you do not plan to use the Apache FOP, you can ignore that setting for the CLASSPATH variable. Ditto for the Xalan setting for the CLASSPATH variable.

Note also that some of these settings are long and complex enough that you do not want to type them if you can avoid it. An easier thing to do is to open the environment variable instructions file (… windows_settingenvvariables.html), copy the value of each variable field that you’re modifying and paste it into Notepad, copy the value to be added for that field from the instructions in the …windows_settingenvvariables.html file, and paste it into the code in Notepad, and finally copy the code out of Notepad and paste it into the appropriate variable field. As messy as this sounds at first, it’s actually straightforward with less risk of typographic errors.

Finally, note that I'm not getting into the specifics of variable settings, especially for the JDK, since it will vary depending on which version you have. But email me if you have specific questions and I'll try to answer them.

You’ll know that you’ve set all the environment variables correctly if you try to import a DITA map and get the “import successful” message in RoboHelp’s Output View pane.

How long will this take? If you’re accustomed to commonly working at this level of technical detail, about an hour. If you’re not, plan on two to three hours. This may be a big chunk of time in a crowded schedule, but it’s a small investment in time that can open up a whole new feature set in RoboHelp.

If you’re interested in more information about how help authoring tools (HATs) are starting to support DITA, I’m giving two presentations at Lavacon in New Orleans in late October, one on how to use HATs to work with DITA and one on how to use HATs to create simulated CMSs. If you’re not going to Lavacon, I’d be happy to send you copies of the PowerPoint slides after October 30.

A Potential Problem Importing RoboHelp HTML 8 Projects Into Flare 5

Flare’s Import Project feature (File > Import Project) can pretty easily import RoboHelp HTML projects except, in some cases, projects from RoboHelp HTML 8 (hereafter RH 8). One such case may be if you moved an old RH for Word project into RH 8 and then decide to move it to Flare. You may find that some topic files in the project contain RH-specific XML processing instructions that look like this:

If you try to import a project whose files contain these codes into Flare using the Import Project feature, Flare will display an error message for each file that contains such codes and not import those files.

To import those files using the Import Project feature, you first have to open each file in Notepad and delete the entire processing instruction code. You can then import the project, and those files, into Flare using the Import Project feature.

Deleting these processing instructions is easy but tedious because the code may appear in several places in each file, with different syntax, so you have to find and delete each one individually. The differing syntax and multiple lines of code make it hard to reliably use large-scale search-and-replace.

The best solution is probably to wait until MadCap modifies Flare’s Import Project parser to handle RH HTML 8 in a later release. But if you can’t wait, there is a workaround…

Start a new project in Flare and just import the topic files into the project like any HTML or XHTML file. The files will come in, but will show the processing instruction codes when you view the topics in Flare’s XML Editor. Fortunately, users won’t see them in the output. They’re just visually intrusive to us, the authors, while we edit the topics, so we can either delete the codes or just ignore them.

Remaining Questions From the Captivate 4 STC Webinar

From Peter I – How… set Captivate closed captioning to "ON" by default? – The easiest way I found to do this is from http://www.raisingaimee.co.uk/index.php?option=com_content&task=view&id=35&Itemid=28. Thanks to Captiv8r for pointing this out on Adobe's Captivate forum at http://forums.adobe.com/message/153596#153596

From Judith S - Does Captivate 4 capture right-mouse clicks? – Yes, but it has a few quirks and can vary depending on the version of ActionScript. See this thread on the forum - http://forums.adobe.com/message/2058434#2058434.

From Debora G - …published captivate files are of poor quality (fuzzy text and background image) - how can we improve the quality? When we preview in CP it looks crisp – Did you insert the image as a bitmap (GIF, JPG, or PNG) and have you scaled the movie? Let me know by email offline.

From Linda K - is there a way to correct typos made during capture so they're not repeated in the output? – Per Peter I – “One can replace the original typing with animated typing text.” Is that what you need?

From Linda K - when should we use auto recording mode vs full motion recording? – Basically, use auto mode to record standard movies and fmr to record movies that show continuous visual change like drag and drop or, on the more unusual side, something like the view through an electron microscope. Note that you can start recording in auto mode and switch in and out of fmr as necessary by pressing F9 to enter fmr mode and F10 to return to normal.

From Linda K – how… control the size of the frame in the SWF output? – This question may be referring to two things, so I may not be answering the right one. Read this thread on the forum - http://forums.adobe.com/message/718082#718082 – and let me know if that’s NOT what you were referring to, in which case we can talk a bit more offline.

From Linda K - how do we remove the Captivate branding from the... player? – If you’re referring to the Adobe Captivate “button” from the playbar, open the skin editor (Project > Skin Editor), select the Playback Control tab, open the Playbar field pulldown, and select any playbar style other than default.

From Judith S - Can you demo or show us the aggregator? – Are you asking in terms of how it works compared to MenuBuilder or just in general? Shoot me an email offline if you have a chance.

From Judith S - How easy is it to translate… Captivate movies from English to another language? – I’ve done little translation work so this response may not be complete, and I ask anyone who has translated to extend or correct what I say next... It seems fairly straightforward - pick the desired language for the auto-captions and modify the text as necessary, translate your text captions, and re-do any voiceovers (obviously). You may also have to re-shoot any screens in the appropriate foreign language version of your software. Also watch for culturally-based issues. One example that I ran into years ago was the use of a rural post box icon as an email icon, only to find that many people outside the US didn’t know what it was.

From Jeff F - …explain more about widgets? – There’s a pretty good write-up on them in Captivate 4’s help, but email me if you’re looking for more than what’s there and we can discuss it.

Enjoy the tool...

Attendee Questions From My Captivate 4 STC Webinar Last Week

Thank you all for your questions. Here's the first set of responses. Look for the rest over the next few days...

From Cynthia K - file sizes for the two examples you showed - The SWF for the Decimal-Binary Conversion movie was 249K. The SWF for the diaper-changing movie was 2.45 Megs.

From Michael M – …interactivity capabilities of Camtasia vs Captivate? – Overall, I’d say they’re similar. They're both major commercial tools, which usually means they support the same overall set of features and differ in specific areas or capabilities – e.g. they both offer text caption boxes, for example. Check Camtasia’s features at www.techsmith.com/camtasia/enhance.asp for specifics.

From Don W - What is the output format for... Captivate? – There are seven options. I’d say the most common is SWF for the movie, then Print (Word) for producing review copies or handouts. You can also output to Adobe Connect Pro, AVI, EXE, an email attachment with several specific formats, FTP, or a new (in Captivate 4) AIR-based “review” format as a way to move reviews off paper.

From Erin H - can you talk a little bit about how it integrates with other help systems? What things should we be aware of? I woudl like to include movies in online Help (and we use a content management tool for Help). Also, what can be done to minimize file size? – In Flare and RoboHelp, and probably any other tool that lets you insert SWF files, it’s a simple matter to insert a movie into a topic. The problem is that the movie runs automatically every time the user opens that topic, cool at first but wearing thin fast. A better solution is to create a separate topic to hold the movie, then add some link text in the main topic, like “Click here to see a demo” and popup link that text to the help topic that contains the movie. This lets the user decide whether to run the movie. Two points re minimizing the movie files sizes… First, reduce the number of graphics that you insert in the movie. Second, if you’re doing audio narration, do it in one or two takes rather than twenty or thirty to get the audio "just right", since all those takes add up.

From Cynthia K - how many tiers can you branch out to? – As far as I know, there is no technical limit. The only limit may be how many you can keep track of.

From Peter I - can you suggest approach for maintaining captivate movies? For ex., if one screen changes. – I think it depends on the size and nature of the change and its proportion to the overall movie. Overall, there are two main options. Re-shoot the changed material as a new movie, then import its frames into the existing movie and delete the original, now-changed, frames. Or, delete the old slides in the movie and use Cap’s re-record feature ( Insert > Recording Slide). I lean toward the first option because I find it less confusing, but that’s me.

From Susan H - Can we change text to variables after the fact? – You can remove text and replace it with a variable, if that’s what you mean…

From Linda K - may we use the music shipped with Captivate in our movies? are they copyright concerns? – As far as I know, the audio clips that ship with Captivate are freely distributable with no copyright issues, but don’t take my word for this. I'd contact Adobe to check, or else have your legal department do so.

From Susan H - Please confirm that Captivate DOES support double-byte characters. – Per the features page at www.adobe.com/products/captivate/features/, under the Unicode Support heading, it says “Create your content in any language, including double-byte languages, and count on Adobe Captivate to publish it properly thanks to Unicode text encoding”

From Linda K - How to change the default text used in the automatic captions? – Open the appropriate CaptureTextTemplates_.rdl language file in the Program Files\Adobe\Adobe Captivate 4 folder and change the default text as needed. This file is a bit programmatic, so make sure you’re changing the right wording. Back up the original RDL file before changing it.

From Erin H - perhaps you could post a short demo of using Captivate on your blog? – I’m going to run a brief (35 minutes) demo on Wednesday. Let me know if you’re interested in sitting in and I’ll send you the connection info.

More to come...