If you are fortunate enough to be attending the STC Summit in Sacramento this year, please stop by the Adobe booth to say “Hi”

I’ll also be presenting an STC conference session on using Adobe products to create ePub and apps from your FrameMaker and RoboHelp content.

Check out  http://blogs.roundpeg.com/2010/03/fm-char-palette-util/ for a writeup of the easy-to-use FrameMaker Character Palette utility, complete with an interactive simulation. For Frame users, WAY easier than the Windows Character Map utility

Borrowed from http://forums.adobe.com/message/2584446#2584446. Thanks to Adriana Harper and Stefan4321 for their posts! 

Scenario: 

• Using FrameMaker to single source print, pdf and online docs
  • Inserting markers to link to external PDF resources
• Linking files with RoboHelp using Technical Communication Suite 2

Issue: 

• Print and PDF are handled properly, but RoboHelp project links are broken

Solution: 

Since the hypertext marker has the following syntax: “message URL Path/MyFile.pdf”, create a folder called Path inside RoboHelp baggage files folder. Place the “MyFile.pdf” in there and your generated Help should properly contain the link to the PDF. 

Hint: The trick is to make sure that the PDF exists in both the place that FM looks for it, as well as the place that RoboHelp looks for it.

Introduction

Understand a typical FrameMaker workflow

Review the FrameMaker interface

Review of the elements that make up a template

Basic document setup

Set up a new blank document

• Pagination and page size
• Sidehead area

Import text with stylesheet

Create and modify paragraph formats

Control simple autonumbering

Create and apply custom colors

Create and modify character formats

Styling and applying master pages

Understanding text frame types

Custom page numbers

Inserting running headers and footers

Assigning master pages to specific paragraph formats

Complex autonumbering

Working out number formats needed

Assigning autonumberings to paragraph formats

Cross Reference Formats

Creating formats as complete units

Using character formats to style cross references

Tables

Creating and modifying table formats

• Changing existing formats
• Assigning paragraph formats to table formats

Books

Creating a table of contents template

• Using the TOC reference page
• Adding the Table of Contents text
• Formatting entries
• Adding dot leaders
• Uniform appearance of page numbers
• Controlling display of page numbers and autonumbers

Creating an index template

• Using the IX reference page
• Adding columns as needed
• Adding the Index text
• Formatting entries
• Adjusting group titles

In the past few weeks we’ve been helping a few clients navigate to a decision on structured (DITA, XML) or “normal” unstructured authoring.

**See the end of this post for a list of some popular structured authoring tools

I have plenty of colleagues that heavily favor structured authoring, and I agree that there are huge advantages to moving in that direction:

Advantages of Structured Authoring

• Economies of scale in large multi-author environments
• Better reuse of content
• Enforced content model

However, I feel the reasons that structured authoring has yet to take over the world are as follows:

Resistance to Structured Authoring

• Limited selection of tools for editing
• Higher learning curve for authors/editors
• Higher initial investment in formatting and templates
• Higher cost of coversion for legacy documents

So, how to choose?

Key factors in evaluating a move from unstructured to structured documentation

• Document length (longer documents may be more manageable in structured environments)
• Need for consistency of both format and content
• Number of authors and organizations involved in editing content

Structured Authoring Tools

Thanks to Yves Barbion (@yvesbarbion) for this short-list of tools and their weblinks

- http://leximation.com/dita-fmx/
- http://na.justsystems.com/content-xmetal-author
- http://www.oxygenxml.com/
- http://www.syntext.com/products/serna/index.html

Thanks to Art Campbell (@ArtC1209) for posting this link http://www.adobe.com/support/downloads/product.jsp?product=22&platform=Windows to the FrameMaker downloads page. (Posted on frameusers.com)

You’ll also find links to the current version’s downloads and other good stuff there.

Shlomo Perets (@ShlomoPerets) also shared the link to his site at http://www.microtype.com/FrameMakerTemplates.html

Anyone know of others to add to this list?

Click here for a PDF version of the info below: FrameMaker Training Options from roundpeg

FrameMaker has 2 different workflows…

It’s important to know which you are likely to use before jumping in with both feet.

Unstructured, or “regular” FrameMaker is paragraph based, and is similar to editing in MS Word or Adobe InDesign. There are powerful formatting features, but nothing to keep you from “breaking rules” (Like using a Heading 2 before using a Heading 1, or putting more than one Chapter Title in a chapter)

Structured FrameMaker relies on your specified content model, and thus can be whatever you want it to be. You can describe exactly what makes up a valid section or chapter, and then enforce those rules for content. Structured FrameMaker is also more rigid in formatting, allowing less deviation from the approved format of a document.

Once you’ve figured out which version of FrameMaker you need, here’s an outline of the traditional FrameMaker classes we offer:

When processing linked FrameMaker 9 files, RH 8.02 seems to put underscores under some, but not all of the topic titles generated from the headings in a FrameMaker file.

This isn’t a huge problem, until you use the Search capability in your Help output. Since the Topic Title is what is displayed in the search results, the end product is in need of a little polish.

Further, for topics created from linked FrameMaker 9 files, the Topic Title is not editable from the Topic Properties. If it was, at least I could change the offending titles prior to final generation of output. (though the titles would revert on the next update of the FrameMaker source content)

RoboHelp has a great FrameMaker document linking feature…except for a few hiccups.

While it’s fairly common to place cross references or hypertext markers (like links to email or to roundpeg.com) in the middle of paragraphs, the resulting processed RoboHelp topics give unexpected results.

If the following sentence in a FrameMaker 9 document

See roundpeg.com for more info.

where

• a Frame Character style,  FMLink has been applied to roundpeg.com
• a valid hypertext marker has been placed in the middle of roundpeg.com

is processed into RoboHelp, and the

• FMLink character style is mapped to a CSS style called RHLink

will result in the following html:

<p>See <span><a href=”http://roundpeg.com>roundpeg.com</span> for more info</a></p>

 (I typed this from memory, so pardon any html syntax errors)

The result is the link and the underlined text extends to the end of the paragraph 

 The only (weak) workarounds I found are

• to ensure that my <a>’s all exist at the end of paragraphs
• are formatted as bulleted lists
• exist as separate entries in table cells (with no text after link)

Anyone know a better solution?

Background on FrameMaker, RoboHelp, and TCS2 Integration

Adobe’s Technical Communication Suite 2 (TCS2) has some amazing integration features. The implementation of these features is much more intuitive and stable than in the initial release of the TCS. 

However, folks (including me) still seem to experience crashes far too often. I suspect that this often has a lot to do with hiccups in opening and updating FM source files (missing fonts, unresolved XREF’s, etc.) 

The next time you crash, go through these steps and you’ll likely be back on track in less than 15 minutes, with a stable system to boot! 

Linked Frame file checklist

If I’ve missed anything, or if you disagree with the steps below, please comment & help to make this a more complete list! 

I see 2 things that seem to increase the # of crashes: 

1. If your FM book and all chapters are not open and freshly updated, RH seems to choke on it more often. This means all missing resources (fonts, graphics, xrefs) should be resolved such that the book updates without any errors or dialogs.
2. Intial mapping of styles, and their first application to the content. I can’t prove this, but it seems that the noodling of the mappings can affect the odds of that first conversion.

So how to stop it?? 

1. When mapping FM styles to the RH equivalents, you can export the .isf after you do mappings, but before you apply settings. Then, if you have a crash, you can quickly import the .isf back into the project.
2. If your project crashes after restarting your computer
   • Crashing on opening- Delete the .cpd cache file and re-open
   • Repeated crashing when Update All is invoked-
     1. Update individual chapters in book, then Update All (then, if that doesn’t solve it)
     2. Create new project
        • Import FM book again, opening and updating all files as noted above
        • Import .isf
        • Update All by right-clicking on the FrameMaker book file within RoboHelp in your Project Files pod
     3. Consider creating a new RH project, and importing a new “dummy” FM file with only a few paras and headings to verify that the software is working properly

**Addendum: Both Ashish Gupta and our Aussie pal Mark at tcs-users@googlegroups.com noted that the RoboHelp 8.02 update seem to crash their systems. Uninstalling just the 8.02 patch may provide some relief on some systems.  

 Let me know if this works for you! 

-Matt