WebWorks Publisher 2003: True Single Sourcing for Word and FrameMaker Users

By David A. Knopf

Contents

Click a link below to jump to a particular section; click any "CONTENTS" image following a section heading to jump back here.

Introduction to WebWorks Publisher    Link to the article Contents

WebWorks® Publisher is not a Help authoring tool in the traditional sense. It is, rather, a tool for converting documents created in Microsoft® Word (2000 or XP) or Adobe® FrameMaker® (5.5.6 or later) to any of 11 different online output formats, including 5 different flavors of online Help. WebWorks Publisher is a true single sourcing application. Authors create content using either Word or FrameMaker, and then create a WebWorks project to convert the content to the required output format. The WebWorks project defines a set of “conversion rules” that determine how each element in the source documents is converted to the online format.

Each new project is based on a template. WebWorks includes pre-defined templates for 11 different output formats. All content is authored in Word or FrameMaker, and the conversion process itself is fully automated. There is never any need to modify the output files produced by WebWorks. You simply convert your content and then deliver the output to your users.

WebWorks Publisher is developed by Austin-based Quadralay Corporation. The FrameMaker-compatible product was originally released more than 10 years ago. In recent years, Quadralay has expanded its product line, which now includes both FrameMaker and Word versions of its flagship conversion tool, a server-side conversion tool called AutoMap, and a useful utility that enables you to convert RoboHelp® HTML projects, .chm files, and HTML files to either FrameMaker or Word format.

Key Concepts    Link to the article Contents

WebWorks is a conversion tool, not a HAT

Most Help authoring tools include an editor of some kind. For example, RoboHelp HTML includes its own built-in HTML editor; AuthorIT includes a built-in text editor. WebWorks Publisher, however, includes no editor per se. Instead, authors use either FrameMaker or Word to create and edit content. This allows authors to take advantage of the full functionality offered by these editing applications and frees authors from having to learn to use a new editor in order to work with WebWorks.

WebWorks enables style-driven, template-driven conversions

It is possible to use WebWorks to convert legacy documents in which styles have not been used—for example, the classic case of a Word document in which all paragraphs use the Normal style. However, WebWorks works best with documents in which styles have been applied in a regular and consistent manner. The automated conversion process relies on how styles have been applied in the source documents, how styles have been defined in WebWorks, and how you map the source styles to WebWorks styles. If you are working with poorly or inconsistently formatted legacy documents, you may have some clean-up work to do before you can produce the results you want with WebWorks.

WebWorks uses templates to control the conversion process. WebWorks templates define several aspects of the conversion:

  • Page templates control the overall look and content of each topic or HTML page you produce. This makes it easy to add running headers, footers, logos, links to your web site, and other similar elements at the top or bottom of each output page. Each of the templates provided with WebWorks includes a default page template that you can use. However, in most cases, you will want to modify the default page template in order to ensure that your output has the look and feel that’s appropriate for your project. The page templates are simple text files that you can edit with Notepad or another text editor.
  • Output styles determine the appearance of the individual elements in your output files—paragraphs, characters, tables, graphics, and so forth. For example, you might define the Heading1 output style to use Arial, bold, 12 px, with 8 px space below. Each WebWorks Publisher template includes a set of pre-defined output styles for the most common elements in a document, including headings, body paragraphs, bulleted and numbered lists, tables, and so forth.
  • Mappings determine the correspondence between the styles used in your source documents and the output styles you define in WebWorks. As a simple example, if your source documents contain styles named Heading 1, Heading 2, and Heading 3, you would typically map these to output styles that use the <h1>, <h2>, and <h3> HTML tags.

By modifying the default page template, mapping source styles to output styles, and customizing the output styles, you can control the look and feel of your output.

WebWorks produces output for Help, web, & PDA

WebWorks supports a wide variety of different output formats suitable for the web and online Help. Web-ready formats include HTML 3.2 (good for older browsers), XHTML 1.0 with CSS (best for modern browsers), and XML with either CSS or XSL stylesheets. Online Help formats include WinHelp, HTML Help, JavaHelp, Oracle Help for Java, and Quadralay’s own cross-browser, cross-platform format: WebWorks Help. WebWorks also includes templates for the two leading eBook formats: Microsoft Reader and Palm Reader.

The supported output formats are:

  • Simple HTML (i.e., HTML 3.2)
  • Dynamic HTML (i.e., XHTML 1.0 with CSS)
  • Microsoft WinHelp
  • Microsoft HTML Help 1.x
  • WebWorks Help
  • Sun JavaHelp
  • Oracle Help for Java
  • XML with CSS
  • XML with XSL
  • Microsoft Reader
  • Palm Reader

WebWorks supports conditional content

WebWorks enables you to include or exclude content from each output format you produce. With a single sourcing workflow, there is commonly a need to vary content, for example, between printed and online versions, or between two different versions of a product. FrameMaker offers native support for conditional content through condition tags, which WebWorks recognizes and supports. For Word users, WebWorks adds a menu to the Word interface, with options you can use to define and apply conditions within a Word document. (WebWorks for Word calls these “media types,” a term which may confuse users accustomed to the term “conditional text.”  The functionality, however, is the same.)

WebWorks supports accessible output

WebWorks fully supports accessible output that conforms to the requirements of Section 508 and the Web Content Accessibility GuidelinesExternal link (WCAG) of the W3C.External link With WebWorks, you can create accessible output in five different formats: XHTML, HTML Help, WebWorks Help, Oracle Help for Java, and Microsoft Reader.

You embed accessibility information, such as alt text and long descriptions for images, directly in your Word or FrameMaker documents. WebWorks recognizes accessibility information you embed in your documents using the standard Word or FrameMaker interface; for example, in Word, if you assign alt text for an image on the Web tab of the Format Picture dialog box, WebWorks uses that alt text in your generated output. However, Word and FrameMaker do not provide a method for entering certain accessibility information, including, for example, table summaries and image long descriptions. In these cases, WebWorks Publisher provides its own method; with FrameMaker, typically this is accomplished using custom markers; with Word, you use the custom WebWorks menu to insert fields containing the necessary accessibility information.

WebWorks also provides an integrated accessibility validator. If you have selected the accessible output option, WebWorks checks your source files and produces an Accessibility Report that identifies any errors in your source files that will result in your output not being Section 508 compliant—for example, if you have neglected to specify alt text for an image. The report is hyperlinked to your actual source files so that you can click each listed error, jump directly to the appropriate location in your source document, and correct the error.

Using the Tool    Link to the article Contents

First Impressions

It is difficult for me to describe my first impressions of WebWorks because I have used five successive releases of the product over the last several years. However, I think that for someone who is accustomed to a traditional, editor-based authoring tool like RoboHelp or Dreamweaver, WebWorks likely seems a bit different at first.

First, the workflow is different in some basic ways from what a RoboHelp or Dreamweaver user would be accustomed to. Rather than writing content topic by topic in a dedicated editor, you map the elements in your source documents to output styles defined in your WebWorks project.

Also, much of the functionality of WebWorks Publisher relies on its own powerful macro language. Although you can accomplish most important tasks in WebWorks without learning anything about the macro language, it can be jarring the first time you bump into it. For example, you may see code like this associated with styles in your project:  

$BP80ExpandingText_End;\
\
$BP80ParaMacroBegin;
$BP80ParaMacroContent;
$BP80ParaMacroEnd;

Although it’s not necessary for most users to be able to edit, or even understand, this code, that may not be immediately apparent to new users. (The macro language does provide enormous capabilities for advanced template developers; more on that under Developer Tools below.)

Stability and Performance

WebWorks is a robust and stable application—more so than either FrameMaker or Word, in my experience. Crashes are extremely infrequent.

WebWorks is one of the more resource-hungry applications that a technical author is likely to use. The conversion process consists essentially of applying a large number of transformation rules to each text element in a document, as well as performing necessary format conversions for graphics (for example, converting bitmap graphics to .gif format for the Web).

The conversion process is both CPU- and RAM-intensive. During conversions, WebWorks frequently utilizes 95% or more of the available CPU cycles on a machine and has a very large memory footprint. The stated system requirements for the product are a Pentium II or later processor with 128 MB of RAM (256 MB recommended). As a practical matter, though, running WebWorks on such a machine would be painfully slow for all but the simplest of projects. (I recommend the fastest possible CPU with at least 512 MB of RAM; using DDR-RAM can further reduce conversion times by 50-75% or more.)

WebWorks maintains temporary copies of all the source files in a project. These are stored in an intermediary format that WebWorks uses during the conversion process. A side effect of this approach is that WebWorks periodically needs to rescan all the source documents in a project to determine if they have changed and, if they have, to generate updated temporary copies. For a large project (hundreds of pages and hundreds of graphics), the rescan can take several minutes. One annoyance, particularly on slower machines, is the frequency with which these rescans are required.

User Interface

For many years, WebWorks had a well deserved reputation for its challenging user interface. Older versions of the product were designed to work identically on Windows, UNIX, and Macintosh—with all the compromises that entails—and were just plain clunky for users accustomed to more modern interfaces like those found in Microsoft Office or RoboHelp.

WebWorks Publisher 2003, however, sports a completely redesigned user interface. The product is no longer available for UNIX or Macintosh, and the interface has been modernized and updated to have the look and feel of a modern Windows application, with full support for modern functionality like drag and drop and XP themes.

Creating a project

When you create a new project, WebWorks guides you through the required steps with a multi-page wizard that prompts you for all the necessary information. First, you choose which output format you want to produce (HTML Help, JavaHelp, WebWorks Help, etc.) and assign a name for your project and choose a folder in which to store it. Next, you identify one or more Word or FrameMaker documents to include in your project. Next, you can set preliminary mappings for the paragraph, character, and table styles used in your source documents. If you've used conditional text in your source documents, you can set which conditions will be included and excluded from the online version; and you can customize how cross-references will be converted.

When you complete the New Project Wizard, WebWorks displays your new project:

WebWorks Publisher’s project window

WebWorks Publisher’s project window

The Source + Generated Files folder lists all of the Word or FrameMaker documents you added to your project. The Support Files folder lists all of the support files that will be used to produce the output from your project. The support files are included in the WebWorks template and vary depending on which output format you have selected. For the most part, you don’t need to modify these files, though there are some exceptions; for example, the document.css file shown in the illustration above contains some default CSS styles that you may choose to modify.

Having created a basic project using the New Project Wizard, you can continue with the other main steps: mapping source styles to WebWorks styles and customizing WebWorks styles.  

Mapping Source Styles to WebWorks Styles

Like Word and FrameMaker documents, WebWorks projects include a set of pre-defined styles, called WebWorks Styles. Mapping styles is the process of relating the styles in your source documents to the styles in your WebWorks project. For example, mapping the Word style named Body Text to the WebWorks style named Body tells WebWorks to use its Body style for all paragraphs in your source documents to which the Body Text style has been applied. You map styles using the Project Mappings dialog box:

Mapping the Body Text style to one of the pre-defined WebWorks styles

Mapping the Body Text style to one of the pre-defined WebWorks styles

In this illustration, the styles listed in the Source Style column are those that have been used in a particular Microsoft Word document. The WebWorks Style column lists the WebWorks styles to which the source styles have been mapped. You can change the mapping of each style by clicking and selecting the style you want from a drop-down list. Checking the Split column forces WebWorks to start a new HTML page whenever it encounters the source style you checked. For example, in the illustration above, WebWorks will start a new page each time it encounters a paragraph in the Word document that uses the Heading 2 style.

Tabs along the bottom of the dialog box allow you to set mappings for paragraph, character, and table styles, as well as for fields (markers in FrameMaker), and fonts.

Customizing styles

You can customize the attributes of each WebWorks style in your project using the Style Designer, a sophisticated, multi-tabbed dialog box you use to define all of the output styles in a WebWorks project. You can customize the pre-defined styles included in every project, and you can define your own styles from scratch:

Designing a paragraph style in the Style Designer

Designing a paragraph style in the Style Designer

Using the tabs across the top of the dialog box, you can define styles for basic project elements like paragraphs, characters, pages, graphics, and tables. The subtabs along the bottom of the dialog box group related categories of style information.

The Style Designer essentially gives you a point-and-click interface for defining the Cascading Stylesheet (CSS) that controls the appearance of content in XHTML, HTML Help, Oracle Help for Java, and WebWorks Help. This makes it easy to create a CSS file even if you are not familiar with CSS syntax. If you are experienced with CSS and prefer to build your own stylesheet or if you need to use an existing stylesheet, you can do so by modifying the page template to reference your stylesheet. However, in most cases, you will have to assign names to the styles in your stylesheet that match the style names in the HTML produced by WebWorks. 

The ability to define output styles using the point-and-click interface is not available for all output formats. It is not provided for HTML 3.2 (because HTML 3.2 does not use CSS), nor is it available for JavaHelp, XML, or WinHelp. For these output formats, you must define style information by editing style macros or project support files, which can add time and complexity to the task, especially in the case of WinHelp, for which some style customizations require that you practice the dying art of hand-editing raw RTF code.

Cross-references and Hyperlinks

Cross-references and hyperlinks that you include in your Word or FrameMaker source documents are automatically converted to hyperlinks in your generated output. WebWorks can automatically remove page numbers from cross-references so that, for example, a cross-reference in your source document that reads, “See ‘Configuration’ on page 4-22”, is automatically converted to an online hyperlink that reads simply, “See Configuration”.

You can further customize the conversion of cross-references on the XREFs tab in the Project Mappings dialog box. By specifying search and replace patterns that use the actual syntax in your source documents (typically REF or PAGEREF fields in Word or cross-reference building blocks in FrameMaker), you can customize the way that cross-references are converted:

Customizing Microsoft Word cross-reference mappings in the Project Mappings dialog box

Customizing Microsoft Word cross-reference mappings in the Project Mappings dialog box

Customizing FrameMaker cross-reference mappings in the Project Mappings dialog box

Customizing FrameMaker cross-reference mappings in the Project Mappings dialog box

Conditional Content

There are several techniques you can use to create conditional content with WebWorks Publisher.

  • First, you can easily exclude content from the online version of a document based on styles. For example, if you want to include a large number of screen shots in your printed documentation but exclude them from the online Help, you can easily do so. Just place your graphics in paragraphs that use a unique paragraph style, say GraphicPrintOnly. Then, map that paragraph style to the NoOuput WebWorks style. WebWorks will automatically exclude the graphics from your generated output.
  • Second, you can define and apply conditions in your Word or FrameMaker documents and then include or exclude conditions from your generated output. For example, if you are producing both a printed document and an online Help system, you might define PrintOnly and HelpOnly condition tags, exclude content marked PrintOnly from your online Help system, and exclude content marked HelpOnly from your printed documents.

    • Setting options for conditional text (called “media types” in WebWorks for Word)

    Setting options for conditional text (called “media types” in WebWorks for Word)

    You can use a similar approach to create different versions of a document for different versions of a product (for example, a Lite and Pro version), and for different audience groups.

  • Finally, you can also include and exclude content from a project by segregating it into separate Word or FrameMaker documents. For example, if you plan to create context-sensitive Help, you can write all the context-sensitive Help topics in a separate Word or FrameMaker document, and then include that document in your WebWorks Publisher project, while excluding it from your printed documents.

One limitation is that overlapping conditions do not work well in FrameMaker and are not supported by the Word version of WebWorks Publisher. Despite this limitation, however, the three techniques for managing conditional content give you considerable flexibility to create printed and online documents that vary significantly in their content.

Publishing content and merging helpsets

WebWorks includes a Deploy/Merge Wizard that you can use to publish your generated output to a local directory, network share, WebDAV server, or FrontPage folder. The Deploy/Merge wizard also automates the process of creating multi-volume helpsets in HTML Help or WebWorks Help format. For HTML Help, the wizard automatically creates a master .chm file and merges a set of slave .chm files. The wizard can also consolidate and merge multiple WebWorks Help projects into a single, multi-volume system.

Importing External Documents    Link to the article Contents

WebWorks Publisher works directly with source documents created in Microsoft Word or FrameMaker, and these documents do not need to be “imported” in the traditional sense of the word. However, if you have legacy content created with another Help authoring tool or HTML editor, you may want to migrate that content to Word or FrameMaker so you can start single sourcing with WebWorks Publisher. WebWorks itself does not offer the capability of importing such external projects, but Quadralay offers an add-on utility, the WebWorks Publisher Import Utility, which does just that.  

“Import Utility” is a bit misleading because this utility does not so much “import” as “convert.” You can use it to convert all of the content in  a RoboHelp HTML project, a .chm file, or a set of HTML files to Microsoft Word or FrameMaker format. The result is a Word or FrameMaker document that you can use with WebWorks Publisher.

Using the Import Utility, you can directly import RoboHelp HTML projects created with RoboHelp 2000 or later, a .chm file created with any authoring tool, or any collection of HTML files. When you convert RoboHelp projects, the resulting Word or FrameMaker documents include all of the content that was included in the RoboHelp project, including topics, graphics, hypertext links, Related Topics links, See Also links, and topic IDs for context-sensitive Help. Conversion of HTML Help and HTML files likewise preserves all of the content in the resulting FrameMaker or Word documents.

The import utility worked well with most of the projects I tested. Depending on how the original projects were created, the utility did not always get it right on my first attempt. However, there is a dizzying array of conversion options to choose from, and once I found the right combination of settings, most projects were converted smoothly.

Customization options in the WebWorks Publisher Import Utility

Customization options in the WebWorks Publisher Import Utility

The import utility does not convert WinHelp projects created in RoboHelp, nor can it convert compiled .hlp files. The recommendation for converting WinHelp projects is to use the original authoring tool to produce a version in .chm format, and then run that through the Import Utility. In our testing, this sometimes works well, but sometimes does not.

The import utility is specifically geared toward producing Word and FrameMaker files that are set up to work correctly with WebWorks Publisher. As a result, specific elements, such as Related Topics links, See Also links, and topic IDs for context-sensitive Help are embedded in the Word or FrameMaker documents in accordance with WebWorks Publisher’s own rules for such elements.

The WebWorks Help Output Format    Link to the article Contents

WebWorks Help is Quadralay’s cross-browser, cross-platform online Help format, designed for delivering online Help and online documentation over the Web or in any environment that requires support for a variety of different browsers or platforms. WebWorks Help supports the core functionality that users expect in online Help, including the familiar Contents/Index/Search/Favorites tabs, Related Topics links, See Also links, drop-down hotspots, and context-sensitive Help:

WebWorks Publisher’s online Help in WebWorks Help format

WebWorks Publisher’s online Help in WebWorks Help format

Each WebWorks Help system you create includes two distinct implementations: one uses a Java applet to provide the navigational controls in the left frame (shown in the illustration above). The other uses JavaScript to provide the same navigational controls except for the Favorites tab, which is only available in the Java applet. You can choose whether your users see the Java or JavaScript version; even if you choose the Java version, though, the JavaScript version serves as a “fallback” in case an end user’s machine does not support Java or is behind a firewall that blocks Java applets. However, there is no “pure HTML” implementation of WebWorks Help, so the end user’s browser must be able to support either Java or JavaScript.

WebWorks Help fully supports accessibility, so you can produce WebWorks Help that conforms to the requirements of Section 508 and the WCAG. The integrated accessibility validator makes it much easier to create accessible, cross-browser content with WebWorks than with other authoring tools I have used.

WebWorks Help does not include integrated support for natural language queries, however, and does not offer a server-side component that tracks and reports on how the Help system is being used.

Workgroup Support    Link to the article Contents

WebWorks Publisher is a desktop application designed to be used by a single content producer; only one user at a time can edit a WebWorks project. However, both FrameMaker and Word enable multiple authors to edit different documents simultaneously. Therefore, multiple users can edit the various Word or FrameMaker documents that are included in a single WebWorks project.

A companion product, WebWorks Publisher AutoMap, can be installed on a workgroup or enterprise server and used by multiple content producers in several different ways. AutoMap is essentially a server-side version of WebWorks Publisher. With AutoMap installed, content authors can launch conversions using the AutoMap client directly from the FrameMaker or Word interface. The conversions are then processed automatically on the AutoMap server.

Moreover, AutoMap can be driven from the command line and therefore can be controlled by scripts. This makes it possible to configure AutoMap to process any number of conversions at pre-determined times. For a workgroup producing multiple deliverables, this can be a real time-saver. For example, each night at 10:00 P.M., a script can launch AutoMap, access all of the Word or FrameMaker documents that comprise the workgroup’s information products, and automatically produce online versions in any of the 11 supported formats. Authors arriving at work the next morning can review the output and distribute it appropriately.

Developer Tools    Link to the article Contents

It seems to me that WebWorks Publisher is really two tools in one. On the one hand, there is the easy-to-use, point-and-click, GUI-driven product I have written about so far, which enables users to automate conversions based on the 11 templates that are provided with the product. Behind the scenes, though, there is much, much more.

WebWorks Publisher incorporates a sophisticated and powerful macro programming language. This language incorporates approximately 200 individual functions that template developers can use to create and customize WebWorks Publisher templates. The language includes functions for manipulating files, variables, counters, lists, and text strings; accessing information about individual objects in source documents such as tables and graphics; and executing code conditionally using such common programming constructs as if-then-else and loop-while statements. Most of the functionality in the 11 templates provided with WebWorks Publisher is, in fact, implemented through code written in the WebWorks macro language.

Learning the WebWorks macro language requires a solid understanding of some basic programming concepts and a healthy dose of patience and persistence. Fortunately, it is completely unnecessary for the vast majority of users to learn much, if anything, about the macro language. However, for specialist users, such as template developers within a large enterprise publications group, the macro language makes possible an almost unlimited ability to customize and automate document conversions.

Online Help    Link to the article Contents

I cannot offer a completely unbiased review of the documentation and online Help for WebWorks Publisher because I played a part, as a consultant, in their development. I can, however, describe what is provided with the product.

WebWorks comes with complete printed documentation, comprising three separate volumes: a User Guide with operational instructions and task-based instructions for using all of the product’s main features, a Template Guide with detailed information about creating and customizing output for each of the 11 supported output formats, and a Developer Guide, which completely documents the WebWorks macro language. The documentation set is approximately 1,000 pages.

Essentially all of the product documentation is also available in the online Help, which is delivered in WebWorks Help format. The online Help also includes context-sensitive topics for all of the main UI elements, as well as a Template Reference, which is a hyperlinked compendium of all the elements that make up each of the 11 templates provided with the product. The User Guide and the Template Guide are intended for end users. The Developer Guide and the Template Reference are primarily of interest to template developers.

Comments about the documentation in public discussion groups have been generally positive.

Summary    Link to the article Contents

It is difficult to compare WebWorks Publisher with traditional authoring tools like RoboHelp or with database-driven tools like AuthorIT®. WebWorks takes a different approach and requires a different workflow.

WebWorks Publisher is a solid product whose greatest strengths lie in true single sourcing and hands-off, automated conversions. If you have one 50-page document you need to convert to HTML, WebWorks is overkill. If you have a significant volume of content to deliver in multiple output formats, WebWorks is a compelling solution that can help you produce deliverables more rapidly and more cost-effectively than other, less automated solutions.

My view of the key strengths and weaknesses of WebWorks Publisher are as follows:

Key Strengths

  • Strong automation features make one-click single sourcing a reality.
  • Direct integration with Microsoft Word or FrameMaker means that authors create all content in Word or FrameMaker and do not need to waste time importing content into other tools.
  • HTML and XHTML outputs support all major version 4+ browsers.
  • Supports 11 different output formats out-of-the-box.
  • Supports conversions in over 20 different languages and encodings including Unicode.
  • Generated output is ready to publish.
  • WebWorks Help output format provides true cross-platform, cross-browser online Help for IE4+, Netscape4+, Mozilla, Konqueror, and Safari.
  • The Style Designer and macro language give authors nearly total control over the HTML, XHTML, XML, and RTF output, meaning that customization possibilities are limitless.

Key Weaknesses

  • Complexity of the WebWorks macro language makes some customizations challenging.
  • Poorly or inconsistently formatted source documents likely need rework before you can produce high-quality results with WebWorks Publisher.
  • Long generation times and frequent project rescanning can be time-consuming on slower machines.
  • There is no preview feature that lets you see how a particular page will look before you generate output.  

David Knopf is the president and founder of Knopf Online, a San Francisco-based consulting firm that specializes in solutions for technical communication, including content authoring, structured authoring, single sourcing, and information design. David has expertise in a wide variety of authoring tools and technologies and has been a popular speaker at WinWriters conferences for the last several years. David can be reached at david@knopf.com

up