Author Archives: saprentice

About saprentice

President and Chief Leximator

Automated DITA to PDF Publishing with FMx-Auto

If you’re publishing PDFs from DITA and want high quality with minimal effort, you should consider using DITA-FMx and FMx-Auto. If you’re already using FrameMaker and DITA-FMx, FMx-Auto will enable you to create the same PDFs you’re getting through manually saving the FMx-generated book to a PDF, using scripting or batch processing.

If you’re currently generating PDFs through an XSL-FO based process, and aren’t satisfied with the quality of those PDFs, FMx-Auto will enable you to take advantage of FrameMaker’s layout and formatting capabilities, while still using another XML editor for authoring. These tools support all versions of FrameMaker from FM7.2 on up through 10.

DITA-FMx and FMx-Auto can be installed with FrameMaker Server to provide a PDF publishing solution linked to your CMS or other server-based publishing process.

Just because you’re using DITA doesn’t mean that you have to give up high-quality PDFs!

  • DITA-FMx provides features to control the formatting and layout of a PDF generated from a DITA map. These features are easier to use than similar options you might find in other PDF creation tools.
  • FMx-Auto unlocks the API in DITA-FMx so you can automate the book and PDF creation process. An FMx-Auto installation includes the AutoFM plugin as one way to drive this automation.
  • AutoFM is an XML-based scripting tool for automating processes within FrameMaker. In this case it is used to open a DITA map and run the DITA-FMx Map to Book process to create a fully formatted FrameMaker book, then save that book to a PDF.

See how easy it is to get well formatted PDF output from a DITA map using FMx-Auto and DITA-FMx. This video provides a quick (5 minute) overview of the entire PDF publishing process using FMx-Auto.

» Link to video on YouTube.

Information and download:

Apple iBooks Author and Adobe FrameMaker?

First let me point out that I’m a bit of a Mac-head. After 30+ years of using “IBM PCs” I made the switch to Macs a little over two years ago. Mac desktop (Mini), Mac Server (Mini), Mac laptops (MacBook and MacBook Pro), not to mention the iPhones and iPad. Yeah, completely jumped ship. I do still perform most of my work on Windows, but it’s all in VMs (Virtual Machines) on Apple hardware. It was the best move I’ve ever made .. far more productive, and far fewer problems (both hardware and software). From my perspective, Windows runs best on a Mac.

So, because I’m a late-comer to the Mac world, I wasn’t terribly bothered when FrameMaker dropped the Mac platform (in retrospect, it seems like a bad move, but that’s not the point). Frame works great in my Windows VM .. no problems at all. The fact that it’s not a native Mac application doesn’t really matter to me since I’m usually working in that VM.

I’ve been using FrameMaker for 20+ years, and not only use it for authoring and publishing of content (mostly software and technical manuals), but I also develop plugins and tools for FrameMaker. FrameMaker has its detractors, but in my opinion it’s a very solid authoring and publishing tool for both structured and unstructured content. I like it.

I’ve also been involved with eBook development for the past couple of years, and find that to be an exciting new option for publishing. There is no “perfect” path for creating an eBook from FrameMaker .. lots of options, some better than others depending on your needs, but they all have issues that typically require manual tweaking of the output.

With the release today of Apple’s iBooks Author application (free, but requires the Lion OS), I thought it might be good to explore how this tool potentially fits into the technical document publishing workflow. Also to see if this tool might be a replacement for FrameMaker in certain situations.

In case you missed all of the hype (info and video here), iBooks Author is Apple’s answer to making it easy for authors and publishers to create beautiful and highly interactive eBooks. This syncs up with their effort to provide interactive textbooks for students as eBooks. One caveat is that these eBooks can only be used on the iPad (not even the iPhone, for now), and in fact the license agreement requires that the output from this application can only be used on the iPad and sold through the iTunes bookstore. I won’t get in to whether that’s a good thing or not, but if the iPad is a target device for your content, this may be a useful tool.

If you’re familiar with Apple’s Pages application, you’ll feel quite comfortable with iBooks Author .. it looks like they cloned Pages to make this tool.

First hurdle .. how do you get content from FrameMaker into iBooks Author? IBA appears to only import content from an Apple Pages file or a MS Word DOC file. (No XML import and not even an RTF import.) FrameMaker exports to RTF, which you can open in Word and save to a DOC file. Once you’ve got a DOC, you can then insert that file as a “chapter” or a “section” into the IBA file (iBooks Author files have an IBA extension). When adding the DOC file to the IBA you have the option of preserving your document styles, but regardless of the setting of this option, your style names are all lost (as far as I can tell). All paragraphs are tagged with a style name of “Free Form”. YIKES. As a hard-core style user, that sounds like a really bad thing to do. Hopefully I’m missing some option to maintain style names .. if not, that’s a serious flaw. However, even without any style tweaks, the default appearance does look pretty decent.

Update 29 Jan 2012! Sorry .. looks like I was wrong about that. Selecting the “Preserve styles option” does maintain paragraph and character styles (and style names) on import.

When I tried the import process on some of my content, it seemed to have trouble with conditionalized text. This text looked fine in Word (after the export from Frame), but after importing into IBA, the first character of each conditionalized paragraph was missing. If you make use of conditions in FrameMaker, be sure to watch for this. Also, it appears that cross-references don’t convert into anything useful on the IBA side, and referenced images are lost.

Let’s assume that your content has been successfully imported into an IBA file. You’ll need to create the cover and title pages as well as set up the copyright and other frontmatter. You can import directly into pages of these types, or just insert a copyright section page and copy+paste into that page. An interesting “feature” of eBooks created from IBA is that there is a separate table of contents for each chapter. You’ll need to be sure to tag paragraphs appropriately for them to show up in each TOC.

One of the really interesting things about this tool is its ability to add various types of interactive graphics (called Widgets). These can be simple things like a gallery of images (swipe left and right to see more) and movies or audio files. Or, you can create more complex objects like multiple choice review questions, or interactive images with callouts that pop up when tapped. You can also embed a Keynote presentation, interactive 3D images, and HTML content. All of this must be manually created.

When you want to preview your book, just plug your iPad into your computer, and click the Preview button. Within a minute, you’ll be able to page through and review/test the iBook you’ve created.

If Apple is really hoping that people will create lots of these iBooks, they should work a bit more on getting a cleaner import process. Graphics and cross-references should definitely not get deleted, and maintaining the source style names would be very helpful. Otherwise, there’s quite a bit of manual work to import your existing content and creating a new book. Granted, any of the interactive media will need to be created manually since that didn’t exist in the source.

While a conversion from FrameMaker to iBooks Author is probably not the most common workflow scenario, it may be worth the effort if your goal is to create an interactive book for the iPad. I don’t see this application replacing FrameMaker (or Word for that matter) since it really only allows for a very limited type of page-based formatting, and you can’t export to anything other than iBook, PDF, and text.

I’ll be playing with this more over the coming weeks and will post more as I explore the options.

FrameMaker: EDD, template, rules – what is all that and how does it benefit me?

People often complain that it’s too hard to edit XML files in FrameMaker. Before you can effectively edit files you need to set up a structure application for that XML model. A structure application is a set of special files and instructions that tell FrameMaker how to apply formatting to the XML tags and content in an XML file. This information is stored in a file called the structure application definition file, which contains all of the “definitions” for each structure application available to FrameMaker.

If you’re given an XML file to edit, and are provided with the structure application for that XML model, it’s easy to install the structure application files and start editing. However, if you don’t have a structure application, creating one can require a bit of effort when all you want to do is make some edits. If it’s not important to work in a WYSIWYG mode, you can edit your XML file without setting up a structure application as long as the file includes a valid reference to a DTD. You can toggle the tags on or off and make edits to the content as needed. But if you’ll be doing any significant editing, it’s likely that you’ll want some amount of formatting (even if it’s just to distinguish between block and inline elements and make headings bold). This really isn’t all that different from other XML editors that provide a WYSIWYG or “Author” editing mode. They all require some type of configuration or setup to associate elements and contexts with a particular formatted representation of those elements.

Keep in mind that although FrameMaker is often associated with book production and page layout (which it excels in), the formatting applied by your structure application does not need to use or imply page-oriented formatting. In fact, you can make the formatting look very basic, like a simple web page. Personally, I like to encourage this approach when authoring XML documents. If you’re authoring XML, you are probably producing deliverables for many different output formats, and it’s best if the author is not writing with any of those output formats in mind. When working in this way, you’ll have two structure applications, one for authoring which uses a very simple layout, and one for publishing which applies the page-based formatting that you want in a printed book.

While FrameMaker is actually very similar to other XML editors in features and functionality, it’s important to keep in mind that FrameMaker is not just another XML editor. In addition to being an editor (for both unstructured and structured documents), it is also a state of the art print publishing engine. Most (all?) other XML editors require a completely different tool in order to render the XML tags and content into a format that is acceptable for a printed page or book. With FrameMaker you get both tools in one, and with that added power comes a bit more effort up front. This is a significant advantage, and in the long run, well worth the extra effort.

I like to think of the FrameMaker XML authoring process as “front-loading” the publishing effort. Once you can edit an XML file in FrameMaker, you can also get a beautiful PDF file ready for printing or online delivery. Other XML editors may allow you to edit the XML file quickly, but in order to generate a PDF, you’ll need to learn XSL-FO (or hire someone who knows it), then buy an FO rendering engine to create the PDF. (XSL-FO is an open source language for transforming XML into PDF.) Yes, there are other options for creating a PDF from XML other than XSL-FO, but they all require considerable amount of knowledge and coding and/or a considerable amount of money.

The icing on the cake is that a PDF generated from FrameMaker is likely to look much nicer than one generated from an FO-based process. XSL-FO just does not support the same level of formatting and layout as that available within FrameMaker, no matter how much time you spend on crafting the FO stylesheets.

Granted, there can be a fair amount of effort required to create a structure application from scratch. It’s often best to start by cloning an existing structure application, but if that’s not possible, you’ll just have to make one yourself or hire a consultant to develop one for you.

The core components of a structure application are:

  • DTD (Document Type Definition). A set of markup declarations that define the elements and their relationship in an XML or SGML data model. The DTD also defines any attributes and their default values.
  • EDD (Element Definition Document). Similar in concept to a DTD, but adds a layer of context rules to allow the mapping of formatting properties to the data model based on the relationship of elements and attribute values. An EDD can be created from a DTD, but the context rules must be added to assign formatting to the document when it is opened. The context rules can assign formatting properties directly, or it can assign paragraph and character styles that are defined in the template.
  • Template. A FrameMaker file that defines the page layout properties, named paragraph and character styles, and other document-specific settings. The EDD is imported into the template file, making the template a single file that contains both the structure rules and formatting information.
  • Read/write rules. A file that defines additional properties of specific elements and how those elements are modified as the XML file is read from or written to disk.
  • XSLT import or export stylesheet. You can optionally include XSLT stylesheets that perform additional processing on the import or export of an XML file.

References to all of these files (and other settings) are included in a structure application definition in the structure application definition file. For details and to learn all that you’ll need, refer to the Structure Application Developer’s Guide (http://www.adobe.com/support/documentation/en/framemaker/).

The nice thing is that once you have the structure application, even if you didn’t create it yourself, you’re likely to be able to make adjustments to the template to affect the layout or formatting of specific elements without assistance from a consultant. This is because you’re just changing properties of a standard FrameMaker template, something that you or someone in your company has probably been doing for years with unstructured FM files. If you’re using an FO-based process, unless you have the necessary expertise in-house, you may need to hire someone to make these modifications. You’ll hear people say that once the template is “set”, you don’t need to worry about further customizations, but that doesn’t mesh with the reality of the publishing process I’ve seen. People are always making little changes.

Another nice thing about using FrameMaker as your PDF publishing tool is the ability to leverage the “generated list” feature for creation of the Table of Contents, Index, and other front or back matter lists. As with the structure application template, setting up a nice looking Table of Contents or Index is just a matter of setting up a generated list template as done with unstructured FrameMaker. No special programming knowledge required, and it’s easy to test and modify as needed.

Publishing from FrameMaker can be done “by hand” on the desktop, by creating a book file from the XML content, then applying the necessary pagination and numbering properties and adding the generated list files. Or you can set up a publishing process that’s partially or completely automated. Because FrameMaker has extensive API support (FDK, ExtendScript, and FrameScript), there are many automation options. This does require purchasing automation add-on components or coding-up your own tools, but much of this can be achieved with minimal expense and/or training.

Both Adobe Technical Communication Suite (TCS) and FrameMaker Server provide a tight integration between FrameMaker and RoboHelp, so in addition to the PDF publishing offered by FrameMaker, you can publish to various types of online Help. This can provide an alternative to using XSL as the method for converting XML into HTML-based output.

When setting up an XML publishing workflow, people are often drawn to XSL and XSL-FO as the means to transform their XML content into online and print deliverables. In some cases one or both of these are in fact the right choice. But if it’s possible that the output formatting will require frequent modifications or if the level of formatting is not sufficient for your needs, FrameMaker is likely to be the best solution.

Because FrameMaker is a standards-compliant XML editor, it can be used in an authoring environment along side other XML editors. FrameMaker can also publish XML content that was authored in other XML editors. The great thing about XML is that it frees your content from being tied to a proprietary authoring or publishing tool. That doesn’t mean you won’t still need to use proprietary tools, you just have the flexibility to mix and match those tools as needed. Your task is to choose the right tools to match your needs. Keep in mind that FrameMaker is not just another XML editor, it might just be the best XML editor for your needs!

— Scott Prentice, President of Leximation, Inc.
Developer of DITA-FMx and FMx-Auto, tools that provide extended DITA authoring and publishing features in FrameMaker.


This article was also posted to the Adobe Technical Communication Blog.

AIR Help Development 101: Install and Test the AIR SDK

In order to create a custom AIR Help application, you must first install the Flex and AIR SDKs. I’ll walk you through the simple installation process, then give you some sample AIR Help source files to test.

This process assumes that you’re not using Flash Builder or another IDE for development. If you are using an IDE, these SDKs are likely to already be installed, and you can skip down to step #3 and start playing with the samples.

0) Make sure that Java is installed.

Some of the Flex and AIR build tools are Java utilities, so you must have Java JRE 1.5 or higher installed. This is only required for the AIR Help developer; Java is not required for the end user.

1) Download and install the Flex SDK.

Download from .. www.adobe.com/go/flex4_sdk

The Flex SDK is platform independent; there is one SDK for all platforms, Mac, Windows, and Linux.

After downloading, copy the archive file to a folder on your file system and extract the contents. On my computer, the Flex SDK will end up in the following locations:

  • Mac/Linux: /Users/USERNAME/Tools/Flex/flex_sdk_4
  • Windows: C:\Tools\Flex\flex_sdk_4

2) Download and “overlay” the AIR SDK.

Download from .. www.adobe.com/go/air_sdk

A separate download is provided for the Mac, Windows, and Linux versions of the AIR SDK; download the version appropriate for your OS.

After downloading, copy the archive file to your Flex SDK folder (flex_sdk_4) and extract the contents into that directory. On Windows, this would likely be a Right-click > Extract All. On a Mac you’ll need to go into a Terminal window, navigate to the Flex SDK folder, and execute the following command:

tar jxvf AdobeAIRSDK.tbz2

If you have trouble overwriting files due to file permissions, try using sudo before that command.

This overlay process will copy the AIR SDK files into the existing Flex SDK folder structure and may replace a few files with newer versions.

3) You are now ready to start coding, testing, and compiling your own AIR Help applications!

To help you do this, I’m providing some sample files.

Download .. airhelp-hello.zip v.0.01

These sample files are set up for people compiling their AIR application from the command line. If you’re using Flash Builder or another IDE, you should be able to use the Flex source files, but won’t need the provided batch/script files.

airhelp_hello_html – This is a very simple example of an HTML-based AIR application which is is basically a custom web browser. All of the layout, formatting, and functionality is controlled by the HTML files and any JavaScript within them. It contains a help folder with a few HTML files. Feel free to replace those files with some of your own.

HTML-based AIR Help

airhelp_hello_mxml – Virtually the same as the airhelp_hello_html app, but this one uses MXML to define the layout and functionality of the application. This allows you to add Flex-defined interface components and use ActionScript for programmatic interactions. This sample uses an HTML component to display the HTML content (same content as the airhelp_hello_html app), but adds some buttons and a text box to the interface. You can experiment by adding more components to your application.

MXML-based AIR Help

Create a Projects folder in your Flex folder. The sample files include batch/script files that are set up to work with a Flex SDK folder named flex_sdk_4 that is at the same level as your Projects folder. Other than that, the directory structure above that won’t matter. The recommended locations for the Projects folder is:

  • Mac/Linux: /Users/USERNAME/Tools/Flex/Projects
  • Windows: C:\Tools\Flex\Projects

Extract the contents of the airhelp_hello_* samples into the Projects folder. Your folder structure should look like the following:

Sample project folders

Within each of the sample projects are folders named for each operating system (_linux, _mac, _windows). These OS folders contain batch and script files which run commands in the SDK.

The Mac and Linux folders contain shell scripts which are run from a Terminal window. Launch a Terminal window, then navigate to the appropriate location and run the scripts by entering their names at the prompt. For example, to test an AIR Help application without installing the AIR file, run the air-test.sh script by entering the following at a shell prompt:

./air-test.sh

The Windows folder contains batch files, which can be run by double-clicking the file in Windows Explorer.

Each of the sample projects have the same named batch/script files:

  • air-cert – Creates a self-signed digital certificate. This is used for testing purposes only. Before you deliver your AIR Help file to end users you should purchase a real digital certificate. You can edit the batch/script file to change the certificate filename and password as needed.
  • air-compileswf – Compiles the source files into a SWF (this is not needed for HTML-based AIR applications). Before you can test your MXML-based AIR Help, you must compile the SWF.
  • air-test – Runs the AIR application in a debug mode, letting you view and test the current state of your application. The typical development process would be to edit your code, then test, then edit your code and test again.
  • air-packager – Runs the packager utility to create the .air file deliverable. The .air file created by this utility can be given to colleagues for testing. If you have your own digital certificate, you’d edit this batch/script file to change the certificate file name and the password.

Download .. airhelp-hello.zip v.0.01

Give it a try and let me know how it goes. Once you’re able to compile these samples, you can make copies of the projects and change the code to experiment with your own customizations. I highly recommend using Flash Builder if you want to do some serious work with AIR Help development. It’s got a 60-day trial period, so you’ll have time to get the feel fro it before buying.

Feel free to post comments and questions and I’ll try to respond quickly with answers.

AIR Help Primer

Before we can discuss AIR Help, you need to understand the basics of Adobe AIR. So let’s start there…

What is Adobe AIR?

Adobe AIR (Adobe Integrated Runtime) is an application development technology for creating native desktop executables that can be installed on multiple operating systems. The AIR development technology provides the developer with a rich assortment of user interface components as well as a powerful programming language that can leverage web technologies as well as access to content on the local file system.

The installation of an AIR application requires the prior installation of the AIR runtime. AIR applications and the AIR runtime are conceptually similar to Java applications and the Java runtime; in order to run the application, the runtime must be installed. The AIR runtime is a quick and easy install, and may already be installed on your computer since it is installed along with many current Adobe products. AIR applications are delivered as a file with a .air extension. The same .air file can be installed on Windows, Mac, and Linux systems.

AIR is based on Open Source technologies, including Flex (ActionScript and MXML), WebKit, SQLite, and Flash. Everything that you need to develop and create an AIR application is available as a free download from adobe.com (Flex and AIR SDKs). Because AIR applications are Unicode enabled, they support all languages, however the current installer supports only 16 languages. The types of applications that can be developed with Adobe AIR are essentially unlimited. Adobe provides the Adobe AIR Marketplace where people can offer their AIR applications to others.

What is AIR Help?

AIR Help is a term that refers to any user assistance application created with the Adobe AIR development technology. In practice, this is more of a concept than a tangible thing. Because AIR is so flexible, each Help system developed using this technology may provide very different features. Unlike some Help technologies, when someone says they’ve got an AIR Help system, you really have no idea what features that Help system may have. The functionality common to all AIR Help systems is that they are all locally installed on the end user’s computer. Remember that AIR is a technology for creating desktop applications; AIR is not installed on a server and although an AIR application can leverage web technologies it is itself not a web application. You might think of AIR Help as a highly customized web browser (although, for some situations it may be designed to limit access to the local file system).

I coined the term “AIR Help” in 2007 after learning about Adobe’s new AIR technology. Because of the relative ease of development and the ability to incorporate web and local file system components, AIR seemed like the ideal platform for the development of user assistance applications.

There are currently two commercially available tools for creating AIR Help, Adobe’s RoboHelp 8 and MadCap Software’s Flare 6 (also Flare 4 and 5). Adobe also provides a utility called RoboHelp Packager for AIR, for creating AIR Help from RoboHelp 6 or 7 webhelp files. If the features offered by the commercial tools don’t provide the functionality that you’re looking for, you can create your own custom AIR Help system. Sample custom AIR Help prototypes are available from leximation.com. Leximation is also developing a DITA to AIR Help plugin for the DITA Open Toolkit as well as a utility for creating AIR Help from CHM (HTML Help) source files.

I’m hoping that other Help Authoring Tool vendors will throw their hats into this arena and show us what they can do with AIR. If you’re using a HAT that doesn’t export to AIR, tell them that you’re interested in seeing what they can do with this technology.

Benefits of AIR Help

As mentioned earlier, AIR Help is cross-platform, so you can install the same .air file on Windows and Mac systems as well as a number of Linux distributions (Fedora, Ubuntu, and OpenSuse). (See adobe.com for details on system requirements.) The AIR Help package is contained within a single .air file, making it easy to deliver to end users. AIR provides a built-in update mechanism. This means that you can ship an early version of your Help, then once the documentation is complete you can upload the updated .air file to your website, and your users will be notified that a new version is available. The update process is quick and easy.

AIR provides an embedded browser component that is built from WebKit (the technology underlying the Safari browser). HTML content that is rendered in an AIR Help system will use this browser instead of one that’s installed on the user’s computer. This means that any CSS and JavaScript that you use in your HTML only needs to be designed for that one browser, WebKit. No need for “browser sniffing” code, and no need to worry about testing on multiple browsers. To me, this is a HUGE benefit of AIR Help over other user assistance options. If you’re currently delivering a “webhelp” system, you probably spend a lot of time developing for and testing on multiple browsers, then get a little worried when another browser comes out that you haven’t tested on. With AIR Help there’s no need for that extra time or worry.

AIR provides many features that make it easy to seamlessly leverage web-based content and data. And because AIR can read from (and write to) the local file system, if you’ve created a custom AIR Help system, it could be designed to monitor the current state of your user’s interaction with the software application you’re documenting. With a custom AIR Help system you could also perform dynamic filtering of content based on the user’s role or input. This has the potential to provide truly a useful, interactive, and intelligent Help system, something people have been striving for since online Help was invented.

All AIR applications must be digitally signed by the publisher. This is seen by some as an annoyance, but really isn’t that big of a deal. During development, you can use a “self-signed” certificate, and when you’re ready to ship, you just need to purchase a certificate from one of the many certificate vendors. An AIR code-signing certificate costs $150 or more per year, and gives your end users the comfort of knowing where the application actually came from.

Last but not least, because AIR is built on Open Source technologies it costs nothing to start exploring custom AIR Help development. Serious development is typically done with Adobe’s Flash Builder (previously called Flex Builder), but it’s easy to get started using just a simple text editor. There are other development environment alternatives such as Aptana Studio that may be worth looking into.

Adobe RoboHelp AIR Help Output

Adobe RoboHelp 8 natively exports an AIR Help deliverable that provides many nice features without the need to do any coding or development. It provides all of the typical features that you expect in an online Help system, such as Contents, Index, Search, Glossary, Favorites, Print, and Forward/Back buttons. It supports context sensitive Help calls, and offers a handful of skins and themes to customize the appearance. The search results include a snippet from the topic (like Google) to provide additional information. The AIR-based auto-update feature is available, as well as the ability to include additional web-based content on Resource tabs and via an RSS feed. One fundamental feature that is lacking is window size and position persistence; when I position my Help window, I like to see it appear at the same location and size the next time I run Help.

RoboHelp’s AIR Help also provides a comments feature that allows end users within a domain (those with access to a common shared server) to share notes on the topics. These notes display combined in a panel at the bottom of the Help application. You can also make use of this comments feature during development as a review tool. Reviewers make notes on topics, then send you the comments XML file. You are able to review all of the comments from all reviewers and make corrections as needed. As you navigate topics, a mini-TOC panel displays links to the sub-headings within that topic. This is a great little feature that simplifies the authoring process as well as making it easier for users to navigate longer topics.

Even though AIR Help provides Help as a single deliverable, once installed the HTML and other system and support files are typically loose in folders within the application installation directory. RoboHelp offers an option to install a single file Help package as opposed to the loose HTML files. For those people still using RoboHelp 6 or 7, Adobe offers a free utility for creating AIR Help from a webhelp project; RoboHelp Packager for AIR.

MadCap Flare AIR Help Output

MadCap’s Flare 6 natively exports an AIR Help deliverable. Flare’s AIR Help is what I call a “wrapped” webhelp system. All of the features in this Help system are HTML-based, and does not take advantage of programmatic Flex or ActionScript coding. Basically, whatever features you can include in their webhelp output, you can include in their AIR Help output.

The standard AIR Help output includes the common features such as Contents, Index, Search, Glossary, Favorites, and Forward/Back buttons. Additional features like including web content or RSS feeds can be included by modifying the underlying webhelp project. MadCap does offer a Feedback Server application that can be used to provide a nice comment/feedback user experience. Unfortunately, Flare’s AIR Help does not provide the auto-update feature, and as with the RoboHelp AIR Help, Flare’s AIR Help window size and position are also not persistent.

Custom AIR Help Options

If you’re looking for features beyond those offered by RoboHelp or Flare, you’ll need to develop your own AIR application. There are two basic types of AIR applications, an HTML-based application or an MXML-based application.

For a user assistance application the HTML-based approach works well if you’d like to create a “wrapped” AIR Help system from an existing webhelp project. In general, you should be able to wrap your current set of HTML files and wrap them in an AIR container. This will let you leverage your existing Help development and take advantage of AIR’s embedded browser and simplified packaging and delivery options.

In order to make use of the programmatic controls and interface widgets provided by Flex and AIR, you’ll need to develop an MXML-based AIR application. MXML is an XML format used to arrange user interface components, similar to the way you can build an input form using HTML. In this type of application, ActionScript is used to handle events and dynamic interaction with the interface components. ActionScript is an object oriented programming language similar to JavaScript. Your application can be designed to take on the operating system’s look and functionality for the window elements, or it can be customized. You can even create windows that are a shape other than a rectangle.

Leximation is developing some AIR application code that provides the standard Help system features. This code is intended to be used as a framework from which people will customize, modify, and extend to develop a Help system that’s ideal for their users and products. These features include the standard navigation elements of Contents, Index, and Search, plus Forward/Back, Next/Previous, Home, and Sync with TOC buttons. Options include Auto-Sync, Keep on Top, and Check for Updates. The search functionality includes the ability to search a “remote” index, providing links to web-based content from a local search. This remote index can be generated from content such as your user forums or knowledge base articles, and can be updated daily or as needed. And as you might expect, this AIR Help application does provide persistent window size and position. Samples of prototype AIR Help files are available for download from leximation.com, most include the source files for you to experiment with.

Possible extensions to this framework might include, a commenting or feedback system, a topic rating system, or a chat module that lets users of your Help system chat with others. You might even set up a feature that lets end users extend and customize the Help system in certain ways. It’s even fairly easy to add a Twitter feed or allow the user to actually post tweets from AIR Help.

Leximation’s AIR Help framework will be available as a DITA to AIR Help plugin for the DITA Open Toolkit and as a utility to generate AIR Help from a CHM (HTML Help) project. If you’re interested in beta testing either of these options, please contact Leximation.

The Choice is Yours

Whether you choose to use a commercial tool to build your AIR Help or decide to try the custom route, using Adobe AIR as your Help delivery option can provide your users with a more interactive and useful user assistance experience. You might even find that AIR helps to blur the lines between your software application and online Help, and might just make your Help more helpful.

–Scott Prentice, Leximation, Inc.

Myth #2: FrameMaker is only appropriate for printed books

While it is true that FrameMaker excels at the creation of printed content and PDF files, there is absolutely no reason that it should be limited to the creation of chapter-based and book-centric content. FrameMaker works with files, you get to decide what those files represent .. books, chapters, sections, topics, or snippets. For years, people have been using FrameMaker along with tools like Mif2Go, WebWorks, and others, to create both PDF/print output as well as numerous online formats. In those workflows, people generally authored in unstructured, chapter-based files.

With the growing popularity of XML (and DITA in particular), FrameMaker can still be used to author content in a chapter-oriented paradigm, but it can also be used to author individual topics just as easily as any other XML editor. Using DITA maps to organize the topic files (which may represent books, chapters, or other collections). These map and topic can then be passed to external processing tools (like the DITA Open Toolkit) to be generated into specific deliverable formats, and can also be processed within FrameMaker to be assembled into books.

You might suggest that authoring in FrameMaker forces people to think in a book-centric manner because of the print format of the WYSIWYG authoring view. Although this may be the way you’ve seen FrameMaker used, this is completely up to you as the author to format the authoring view however it makes sense for your workflow and writers. When opening an XML file, you select a structure application to use, which applies a template which defined the way the content is rendered on screen. You can set up this structure application with a print-focused layout or you can choose to use fonts and a layout that looks very simple.

One example of this is found in the default DITA-FMx 1.1 Topic application which has no indents, uses Verdana as the font throughout and looks more like a web page than a printed book. If you choose to create a PDF from the DITA map and use the default Book application, the print formatting is applied. But while authoring, using the Topic application, you are encouraged to focus on the content rather than the formatting since it’s likely that you are creating deliverables for multiple output formats, of which print (PDF) is only one.

Just because FrameMaker has traditionally been the standard tool for authoring long documents doesn’t mean that it can’t be used for topic-based authoring as well. It is a very flexible and customizable authoring tool, which should be evaluated carefully with other tools when selecting an appropriate XML editor.

PDF Publishing with DITA-FMx 1.1

FrameMaker and DITA-FMx provide the easiest and least expensive way to get the highest quality PDF output from your DITA content. In addition to the numerous authoring features in DITA-FMx, it also provides many useful publishing options. Some of the more popular are listed below:

  • Add related links from relationship tables
  • Flatten conrefs and ensure that links are functional in PDF output
  • Apply ditaval filtering to the generated book files
  • Move figure titles so the follow the image
  • Enable table titles to display on all pages for tables that span pages
  • Assign proper numbering and pagination throughout the book
  • Replace “list” files with generated FrameMaker lists (e.g. TOC, Index)
  • Run custom scripts to perform additional pagination and cleanup

See how easy it is to get properly formatted PDF output from a DITA map using DITA-FMx. This video walks you through the basic process of configuring DITA-FMx for PDF publishing.

If you’re a new user of DITA-FMx or are considering a purchase, you should review this video.

» Link to video on YouTube.

Myth #1: FrameMaker isn’t a “real” XML editor

Well .. I guess you’d have to define “real XML editor,” but if by real you mean that the editor can open XML files on disk, and write the edited XML back to disk, then it’s as real as any other XML editor that I’ve seen. All XML editors have different features, and you may prefer one editor over another because of its features. But FrameMaker is definitely a real XML editor, because it can open, edit, and save XML files.

I hear people say that FrameMaker’s not a real XML editor because it uses a proprietary binary format and you can’t edit the XML tags directly. The truth is that all XML editors convert the XML on disk to some internal binary format while the file is open for editing. That’s how you get that nice tag coloring and fonts. Just because the XML you’re editing looks like the XML you think is in the file, that’s just eyewash. Granted, FrameMaker doesn’t let you edit the XML structure by entering tag names in angle-bracketed code, but that doesn’t change the fact that you are editing the same XML structure that you would with any other XML editor. It’s just a different rendering of the XML on disk than you’ll see in other tools. (It would be nice if FM provided a “code view” .. I hope that’s added in the future.)

FrameMaker does provide a number of views into the structure of the XML. It offers a “structure view” which is a collapsible tree of element nodes, allowing you to easily modify attribute values and rearrange the elements by dragging and dropping the nodes into new locations. It also offers a “tags view” which lets you see the element boundaries and their names in the content authoring window (similar to a code view, but you can’t actually edit the tags directly).

FrameMaker is actually one of the oldest XML editors on the market. There are valid reasons to use an XML editor other than FrameMaker, but the issue of it not being a “real XML editor” is not one of them.

Creating New Files in DITA-FMx 1.1

DITA-FMx offers some features that make new file creation simple and easy. Entering the title for the new topic in the New File dialog box automatically creates the file name based on a format that you have defined using special building blocks. You can also create new files using “element templates” which pre-populate the topic with boilerplate content that you have set up. Prolog metadata in new files can automatically be set with the author’s name and creation date, and each time you update a file, the revision date metadata can be automatically set.

This video introduces these and other features for creating new DITA files with DITA-FMx.

If you’re a new user of DITA-FMx or are considering a purchase, you should review this video.

» Link to video on YouTube.

Overview of the Map Authoring Features in DITA-FMx 1.1

DITA-FMx 1.1 provides a number of authoring features not available in standard FrameMaker 8 or 9. Some of these features are not available in other DITA editors, and are typically found only with a content management system. This video provides a quick tour of those features.

If you’re a new user of DITA-FMx or are considering a purchase, you should review this video.

» Link to video on YouTube.