Producing eBooks with FrameMaker and RoboHelp

Adobe RoboHelp is a great tool for producing eBook content, including the EPUB and Kindle formats. Combine great online output with tight integration between FrameMaker content and RoboHelp, and you have a powerful combination.

Earlier in 2013, I (not surprisingly) used FrameMaker to produce the print version of my FrameMaker 11 book, Publishing Fundamentals: Unstructured FrameMaker 11. Once the print version was complete, I then used the TCS integration available between FrameMaker and RoboHelp to produce the EPUB version of the same book.

While the process was straightforward, there were many artifacts in my files (last used to produce the FrameMaker 8 version of the book) that I needed to address.

EPUB is a specific standard, and its rules are more strict than those of even the most ardent FrameMaker users. Many common FrameMaker practices like spaces in filenames and directories, and special characters in index markers can prevent an EPUB from meeting the EPUB3 standard. I hope the story of my first commercial EPUB project will make it easier for you to meet these standards and quickly produce quality EPUB3 output! I’ve included quite a bit of background information here, so feel free to skip the Production overview section and get to the techie content in the EPUB Gotchas section.

Production overview

Publishing Fundamentals: Unstructured FrameMaker 11 is an update to Sarah O’Keefe’s previous FrameMaker 8 reference book (hereafter referred to as “version 8”). The book has a long pedigree, and I was grateful to Sarah and to Alan Pringle (the team at Scriptorium Press) for allowing me to take over the book and bring it in line with FrameMaker 11.

The FrameMaker 8 version really pre-dated eBooks (other than PDF) and was also subject to a previous publisher’s demands for page layout and pagination. As a result, there was a great deal of formatting skullduggery that Scriptorium warned me about prior to starting the project! One of the first things I did was to tweak the catalogs in my chapter template, import formats to the rest of the book, and remove overrides! For me, normalizing the  formatting was the number one task, as I didn’t want to deal with the page-by-page decisions made in formatting the previous book.

From there, I worked on reducing the white space within the book. While white space can be a good thing, version 8 weighed in at about 800 pages, and a good percentage of that page count was empty space around graphics and at the bottom of pages. FrameMaker 11’s new Object Styles allowed me to set up a catalog of formatting choices for screen capture and other graphics, and then quickly apply these choices as I would changes to character or paragraph formatting. Object Styles provided two key benefits:

1. Even after adding new features for versions 9-11, and adding a section on ExtendScript graciously submitted by Rick Quatro of Carmen Publishing, I dropped the page count of the previous content by well over 100 pages. The current version comes in at just over 700 pages.
2. By applying Object Styles to the graphics, and using a FrameMaker conversion template in RoboHelp, I was able to control the formatting of my print graphics independently of my EPUB graphic formatting. This turned out to be a Very Big Deal.

Finally, I got to the task of mapping the FrameMaker formats to their RoboHelp representations. Because EPUB is simply one of many output formats available from RoboHelp, this was no different from any other FrameMaker to RoboHelp linking project. If you’d like more information on that process, please see http://mattrsullivan.com/2013/08/setting-up-basic-framemaker-and-robohelp-integration/ as well as my recorded Adobe webinar available at http://www.adobe.com/cfusion/event/index.cfm?event=register_no_session&id=2266402&loc=en_us. You can also find many tips on specific solutions to problems by referencing mattrsullivan in your web searches on those topics.

Once I was happy (enough) with the RoboHelp conversion, I figured I was ready to go. (Wrong!) Just because your RoboHelp content is solid, and you’re happy with WebHelp or other output, do not assume that EPUB is “just another flavor” of output. Because EPUB is such a simplified format, the rules for producing valid EPUB3 content are stricter than those required to view something using eBook browsers like Adobe Digital Editions or Firefox with a plug-in. Imagine my surprise when my lovely project kicks out about 1500 EPUBCHECK validation errors. Even more surprising: The EPUB with those errors previewed quite well in Adobe Digital Editons, and on my v1 iPad.

Once I caught my breath, and after analyzing some of the error messages, I came up with a few solutions.

EPUB Gotchas

In-line formatting

The discussion related to in-line formula is really quite short and simple. If you use inline formatting (the sort of formatting that can be read in the HTML code itself) you will regret it! What seems so easy while writing your content will create all manner of problems when viewing content on various systems, screen sizes, and software versions. Instead, use styles. Use them in FrameMaker. Use them in MS Word. Use them in RoboHelp! By removing the formatting from the HTML, and handling it via the CSS file for your output, you will have control over your entire system, and not worry about each individual piece of information, and whether it will format properly in each place.

Formatting in general

Minimize your expectations. If they give out awards for EPUB design (and I’m sure they do…) I don’t know what they’re called. Further, your reader doesn’t know what they’re called either. They’re probably reading your EPUB to glean the knowledge contained therein as rapidly and economically as they can. So it’s better to get your content out there, even if the pages have the occasional widow, orphan or strange unsightly line break. The breaks are going to vary based upon font size and reader resolution, so it’s best to get over your lack of formatting control now, or resign yourself only to print and PDF output forevermore!

Spaces

It seems so simple, but extra spaces show up in the darndest places. Like

• in the filenames of your FrameMaker files, RoboHelp topic filenames
• in the paths of placed graphics files

And then come the obscure ones…like

• spaces in the directory names in your project path
• the paths to placed graphics files
• and my personal favorite: Spaces in the spot cross-reference markers within your FrameMaker content

Get rid of ‘em all, and go back as close as possible to the lovely DOS naming conventions that you might have cut your teeth on in the early nineties. Have no idea what I’m talking about? Try Googling 8.3 naming convention.

The trouble with spaces is that different systems interpret them in different ways.Spaces are often represented as %20 within HTML markup, but %20 is not always interepreted as a space character when reading back into a system! As a result, each of these items containing a space character creates an individual EPUB validation error.

Index markers

Imagine my surprise when the wonderfully-crafted index largely handed to me from the version 8 book appeared to cause the majority of the validation errors! The markers in the FrameMaker book were all perfectly legit, worked well in the PDF version of the book, and also processed as expected to RoboHelp. The only problem is that indexes in print and even in RoboHelp are fundamentally different from indexes in EPUB.

• In EPUB, there’s no real page number to reference, and thus no real page range that can be created using the <$startrange> and <$endrange> commands. Fortunately, with a little trial and error I was able to use the Find/Change function to search the marker text and make some tweaks. Specifically, I removed all <$endrange> markers, and modified the <$startrange> markers to be single entries. In other words, I removed the ranges, and marked the first use within the range instead. Not quite as useful in the PDF version, but the only alternative I came up with was to conditionalize the existing markers, and to place a conditional index marker for the EPUB in there as well. It probably took me a whole two minutes to reach that final conclusion.
• EPUB is more strict on the text in an index marker than FrameMaker or RoboHelp. That means that anything using special characters like # (pound sign) $ (dollar sign), parentheses, or other XML markup characters caused a validation error.

Wrapping it up

So there you have it…when creating EPUB, RoboHelp will do all the really heavy lifting. That means for you, the biggest part of creating EPUB is:

• properly identifying your content (use of styles, minimal in-line formatting)
• a lower threshold for typography and design based upon the flexible nature of the EPUB format
• eliminate spaces in paths and markers
• simplify index markers by removing all characters that can be mistaken for HTML markup

Now get out there, and write some content!