Implementing Help-Specific Features with a FrameMaker EDD

Summary

This project contains a FrameMaker EDD, FrameMaker page template, corresponding WebWorks ePublisher Pro template, sample output, and a paper presented at the WebWorks Round Up 2007 User Conference entitled “Implementing Help Specific Features with a FrameMaker EDD.” Click WebWorks EDD.zip if you would like to download the project.

This project contains a complete workflow for producing printed and on-line documentation with ePublisher Pro. At the heart of the system is a structured FrameMaker template with an underlying EDD. The minimalist EDD contains a scant nine content elements and yet automatically assigns more than 120 paragraph styles that implement help specific-behaviors in the corresponding ePublisher Pro template.

The underlying EDD contains one set of context-based formatting rules that formats the document for print, and a second set of context-based formatting rules that apply paragraph style names for the sole purpose of controlling WebWorks.

This approach offers the following advantages:

Feel free to use and experiment with the sample files. Should you have any questions or feedback, you may reach me at the following E-mail address: msmith@apexcovantage.com.

If you would like additional assistance, I am available as a consultant though Apex CoVantage. I specialize in FrameMaker internal programming and develop end-to-end workflows for embedded help, context-sensitive help, database integration and publishing, and compliance auditing. More information is available from my personal page here.

Detailed Description

I prefer using FrameMaker in structured mode when single-sourcing printed and on-line documentation because I can encode the logic for controlling the help system into the EDD. I find this preferable to creating paragraph styles that are visually identical in the printed book but enable different features in the on-line help system. For example, consider a manual that contains three to four levels of headings in each chapter. The paragraph style names used to format the chapter title and headings might include the following: ChapterTitle

In the corresponding ePublisher template, paragraph styles Chapter Title, Heading 1, and Heading 2 would likely become new topics in the help system. Heading 3 paragraphs would likely become mid-topics in the help system. If your projects require more flexibility over topic / mid-topic breaks you have two choices: preview the help system in ePublisher and modify topic / mid-topic breaks on a case-by-case basis, or add additional paragraph styles to the document. To control topic / mid-topic breaks using paragraph styles we need to modify our original list of paragraph styles to include the following:

Adding paragraph styles to control additional help-specific features such as drop-down sections and pop-ups further expands the list of paragraph styles to include the following:

In addition, one would also need special versions of every paragraph style that can be a member of a drop-down or pop-up, because a paragraph style's membership in drop-down's and pop-ups is also controlled through the WebWorks Style Designer.

As the number of paragraph styles multiplies, the impracticality of this approach becomes clear. A writer must choose from one of six paragraph styles to format a first level heading. All six variations of the heading would be formatted identically in the source document, with the only distinction being the name of the paragraph style used to format the text. For this reason, ePublisher provides the Document Designer, which allows for the inclusion of topic / mid-topic breaks and help-specific features on a case-by-case basis.

Working with the Document Designer to change topic / mid-topic breaks and add help-specific features adds an additional step in the document production workflow, as changes are made for the benefit of the on-line help system after the final text is complete and ready for production. In order to achieve a true, single-source-publishing workflow where all help-specific features are defined in the source file, there needs to be a way to format documents for print independent of the paragraph styles used to produce the help system. For Adobe FrameMaker users, this is a possibility if they adapt a structured workflow.

Using Attribute Values to Control Topic/MidTopic Breaks in WebWorks

Every element definition in the sample EDD contains one set of context formatting rules that assigns paragraph style names for the benefit of WebWorks. Every element also has a second set of context formatting rules that formats the text for print, based on the context of the element in the structural hierarchy of the document.

When an author using the sample EDD inserts a Section element, FrameMaker prompts for the value for the TopicType attribute. Choices for TopicType include Topic or MidTopic. The value the writer selects determines whether the section is formatted as a topic or mid-topic in the resulting help system.

When the writer selects the TopicType and inserts the Section element, the sample EDD automatically applies one of five paragraph tags to the heading, depending on the section’s nesting level and the value of the TopicType attribute. These paragraph tags include the following:

The sample WebWorks Template contains more than 120 paragraph style definitions that align with the paragraph style names automatically assigned by the sample EDD.

Specialized Elements for Help-Specific Features

The sample EDD contains a special SubSection element that authors can use to control the help-specific features of WebWorks ePublisher Pro. The SubSection element automatically applies all of the paragraph styles necessary to create drop-downs and pop-up windows.

Introduction to Drop-Downs and Pop-Up Windows

WebWorks ePublisher Pro allows you to create drop-down sections that behave in two different ways:

WebWorks ePublisher Pro also offers two variations of PopUp windows:

Creating drop-downs and pop-ups within the source files presents a unique set of challenges for help authors. Not only do you need to use special paragraph tags to mark the beginning of the drop-down or pop-up, you need to tag all of the subsequent paragraphs that get included in the resulting drop-down or pop-up window. The need to apply a designated paragraph tag to the member paragraphs has the potential of tripling the number of paragraph styles used to format the text. This is where using an EDD to automatically assign paragraph styles for WebWorks really makes a difference.

When an author using the sample FrameMaker template inserts a SubSection element, FrameMaker prompts for the value of the TopicType attribute. Choices for the TopicType attribute include the following:

The EDD requires that a SubSection begin with a Heading followed by a Para element. Once this initial sequence of elements is complete, a writer can select from the following element types:

As a writer adds content to the SubSection element, FrameMaker automatically applies the correct paragraph tags to all of the paragraphs contained within the drop-down section or pop-up. This is possible because of the hierarchical nature of a structured document. Because all of the elements in the drop-down or pop-up are wrapped inside the SubSection element, the underlying EDD is able to detect where these help-specific features begin and end in the FrameMaker source files and automatically assign the correct paragraph tags.

Creating Drop-Downs

To insert a SubSection element that will become a drop-down section in the resulting help system, do the following:

  1. Using the structure view, navigate to the location in your document where you would like to begin a drop-down section.

  2. Double-click on the SubSection element in the Elements catalog.

  3. Select DropDown: Start Closed or DropDown: Start Open and click the Insert Element button.

    • Select DropDown: Start Closed to create a drop-down that is initially collapsed by the help system.

    • Select DropDown: Start Open to create a drop-down that is initially expanded by the help system.

  4. Type the text for the drop-down heading.
  5. Insert a paragraph element and type the initial paragraph of the drop-down.
  6. Continue adding text to the drop-down, as necessary. A dropdown may contain any assortment of paragraphs, bulleted lists, numbered lists, and alerts.

All of the content inside the SubSection element will become part of the drop-down when you generate the help system.

To end the drop-down section do the following:

  1. Collapse the SubSection element in the structure view.

  2. Insert the next element after the DropDown element.

Only the elements contained within the SubSection element will be included in the drop-down.

Creating Pop-Up Windows

The SubSection element can also be used to create pop-up windows. WebWorks allows you to create two types of pop-up windows: pop-up windows that exclude text from a topic and pop-up windows that duplicate text from a topic.

To create a pop-up window in the help system, do the following:

  1. Using the structure view, navigate to the location in your document where you would like to create a pop-up window.

  2. Double-click on the SubSection element in the Elements catalog.

  3. Select PopUp: Include Text or PopUp: Exclude Text and click the Insert Element button.

    • Select PopUp: Exclude Text to create a pop-up that excludes text from the current topic. The only way for the help system to display this text, is to create a cross reference to the Heading element at the beginning of the DropDown element.

    • Select PopUp: Include Text to create a pop-up that contains text from the current topic. In order to display the text as a Pop-Up you need to insert a cross reference to the heading at the beginning of the DropDown element.

  4. Type the text for the Pop-Up heading.
  5. Insert a paragraph element and type the initial paragraph of the pop-up.
  6. Continue adding text to the pop-up, as necessary. A pop-up may contain any assortment of paragraphs, bulleted lists, numbered lists, and alerts.

    • All of the content inside the SubSection element will become part of the pop-up when you generate the help system.

To end the pop-up section do the following:

  1. Collapse the SubSection element in the structure view.

  2. Insert the next element after the DropDown element.

Only the elements contained within the SubSection element will be included in the pop-up.

Additional Instructions

The sample project (WebWorks EDD.zip) expands into a directory named WebWorks EDD. This directory contains the following sub-directories:

The conference paper provides more detailed information about working with the sample templates and EDD.

Have fun!

:) :)) :( ;) :\ |) X-( B)

How_I_Use_ePublisher/Implementing_Help_Specific_Features_with_a_FrameMaker_EDD (last edited 2008-02-13 06:18:27 by localhost)