The Power of Hyperwise

by Cathy Longenberger

In previous issues of The Developer Connection News we've examined many of the features of Hyperwise, the authoring tool that lets you create online documents that can be exported in many different formats. In this article, we'll examine two powerful features of Hyperwise:

The Hyperwise Element List, which lets you select the format of text in your document (for example, paragraphs and lists). All selections in the list are based upon commonly used tag languages. We'll give you some tips to reduce confusion about elements, describe the most common elements, and show you what characteristics you can change.
The Hyperwise User Preference dialog, which contains 16 ways to enhance your editing environment. You'll learn about each one and see the power and flexibility Hyperwise offers.

The Element List

The Hyperwise Element List contains selections such as paragraphs and lists. Each selection is designed with a specific format. For example, an unordered list starts with a blank line, displays a bullet and a blank space, and then the text begins. An ordered list has the same format, but it displays a number to begin a list item. You'll find that you probably won't need all of the elements in the Element List for most of the online books and help that you write.

Hyperwise has two element lists: the one most commonly used is associated with PANEL.STY (in Europe, HYP*.STY). The other element list is associated with PAGE.STY.

To use any element, double-click on the element name in the list or use the fast path keys that appear to the right of the name. For example, to create a paragraph using your keyboard, press Ctrl+P.

To create another paragraph or repeat the preceding element, just press the Enter key.

Customizing the Element List

Note: The following paragraphs refer to the Element List that is associated with PANEL.STY (HYP*.STY in Europe). This is the style used for online help or book documents.

The PANEL.STY Element List is comprised of all the elements that are part of the IPF tag language. You'll see that in Hyperwise the elements have the same names and formats as they have in IPF. If you are not familiar with the IPF tag language, you might find that it is easier to learn Hyperwise if you reduce the Element List to nine basic elements, which are the same elements found in most word processors. (The "extra" elements have exactly the same formats with different names.) Once you are proficient at using Hyperwise, you can restore your full Element List at any time. To eliminate the extra elements, do the following:

Open an existing document or create a new one. The Element List automatically appears.
Highlight Begin im and press the Spacebar. Notice that the icon in front of the element name disappears.
Repeat Step 2 to remove the icon from each of these elements:
- Caution
- Character Graphics
- Comment
- Danger
- End im
- Figure
- Figure Caption
- Hidden
- List Part
- NT
- Parameter List
- Warning
Click on Document.
Click on User preference.
Click on Show Full Element List (so it is not selected).
Click on OK.

Now the Element List is reduced to the nine basic elements. If you want to restore the full Element List to its original format, perform Steps 4 through 7 above (making sure Show Full Element List is selected in Step 6). To display the icons in front of the element names again, highlight each element name and press the Spacebar.

Note: The reduced Element List is associated only with the document that is currently open. To make the reduced Element List permanent, you can save it with a new name by using these steps:

Click on Document.
Click on User preference.
Click on Enable Advanced Mode.
Click on OK.
Click on Styles.
Click on Save.

When prompted for a name, use a name that is different from PANEL.STY. For example, type PANELST.STY.

Click on OK.

Now, whenever you want to use the short Element List, select PANELST.STY when you create a new document.

Using the Basic Elements in the List

Let's look at the nine elements that are in the reduced list. All nine fit into two categories: either a list or a paragraph. The differences are really in appearance.

Default acts just like an ASCII editor. There is no automatic formatting. Default is used in tables.

The Definition List is used for things like glossaries. A term (that is, the glossary word) and its definition are separated by deliberate spacing. By default, the Definition List looks like this:

term Definition of the term that is displayed on the left.

where the word and the definition appear on the same line of text. But you can also make the definition appear one line below the word, as follows:

term

Definition of the term that is displayed on the left.

To make the definition appear on the line below the glossary word, double-click on Definition List in the Element List with mouse button 2 and change the Prefix field from idl_Same to idl_New.

Example is used very often in programming books to clarify a previous instruction or to display code samples. It is also useful when you need to line up columns of information (but don't want to create a table). When you use the Example element, the text does not wrap and it appears in a monospaced font, as follows:

C:\OS2\DLL\HELPMGR.DLL

Lines are used for various types of information. One common use of Lines is as an informal way to title a small section of text. You can use Lines in the default mode or in Centered mode. The following is a Lines element in its default (left-justified) mode:

This is a Left-Justified Title

This is the Lines element in the Centered mode: This is a Centered Title

The Lines element uses the system font and does not wrap the text. To center the Lines element text, double-click with mouse button 2 on the element name, select Center from the Alignment column, and then click on OK.

A Note is a paragraph preceded by the word Note: in bold type. It looks like this:

Note: This is a note that is a paragraph. It wraps text and uses the system font. A note can be one line long or several lines long.

The Ordered List is sometimes called a numbered list in other editors. It looks like this:

This is item one.

This is item two.

To nest lists (that is, place one list within another), press Ctrl+N or click on Create from the action bar and then click on Nested list. A nested ordered list looks like this:

This is main item one.

This is a nested item.

And another nested item.

This is main item two. Notice that each new nested list starts a new style of ordering (for example, 1, 2, 3; then a, b, c; then 1, 2, 3).

A Paragraph is exactly what you are reading. Paragraphs leave a blank line above and below surrounding text, use the system font, and wrap text.

A Simple List is like other lists but it has no preceding characters or numbers. A Simple List can be nested like other lists, like:

This is a Simple List item.

This is the nest to the first Simple List item.

This is a nest to the second item.

An Unordered List is one that shows no particular order of its items. Each item in this list can be preceded by a symbol (which you can change). The Unordered List in Hyperwise looks like:

This is an Unordered List item.
This is another Unordered List item.

If you are familiar with the ASCII character symbols, you can change the preceding symbol. For example, Alt+257 creates a "smiley" face; Alt+254 creates a filled box.

To change the preceding symbol in the Unordered List, double-click with mouse button 2 on Unordered List in the Element List, and then click on Update next to Prefix. In the Prefix field, delete the o and enter the ASCII character. Then click on OK. Be aware that when you change the character, AIX or Windows 3.1 code page doesn't match OS/2. So if you plan to use the same document on IPF for AIX, or IPF for Windows, you will need to ensure each code page supports the character.

A Word About Fonts

Although most of the elements discussed above use the system font by default, all the fonts can be changed and can be displayed by IPF on OS/2, AIX, or Windows.

To change an element's font, mark the text, click on the Font icon on the tool bar, and then double-click on the font of your choice. For example, the following centered title was marked and a bold, italic font was selected: A Centered Title in Bold Italics

You can also create your own font style and use it instead of the ones available in Hyperwise. For example, you can create a font called Title. The rule is to make it a "fixed" (height and width are specified) or "bitmap" font so it is displayable by IPF. Our "Title" font is Helvetica, 37x14. A Centered Title in Our Own Font Style

Hyperwise User Preference Dialog

The User Preference dialog is used most often when you are editing and testing a Hyperwise document. Most of the functions available in the User Preference dialog make the editing environment easy for you to use. The following editing selections are available:

Enable Dialog - Show Full Element List
Sorted Panel List - Show Hidden Text
Show Icon View - Highlight Symbols
Show Panel Res - Auto Save
Show Structure Markers - Disable Autolinks
Show Keys - Enable Advanced Mode
Editors (Bitmap, Video, and Audio)

The remaining functions on the User Preference dialog help you see how your finished product works before you export or compile it. One advantage is that you can see your links work as soon as you have created them. You're always in test and build mode with Hyperwise. Because you can see how your document "behaves" before you compile it, you save time. The selections related to viewing the behavior of your finished product are:

Enable Group/Clear
Show Contents Only
Show Push Buttons

User Preference Editing Functions

Enable Dialog

To create links in Hyperwise, you use a drag/drop method. As you perform the drag/drop operation, it is useful to be able to identify attributes of the item you're linking to "on the spot." For example, the object may be in another document (called an external database in Hyperwise). Or the panel you're linking to may need a panel identifier (necessary for autolinked panels). Or you may want that target panel to appear from a link in a completely different style than the one in which it was created.

The ability to change a panel's style from a link is a little-known feature of Hyperwise and IPF. The concept of reuse is very real with this function.

Click on Enable Dialog, mark text in one panel, drag and drop onto another panel, and change its style. Double-click the link and double-click on the same panel from the Panel List and Table of Contents. See what appears.

Sorted Panel List

Panels are displayed in the Panel List in the order in which they are created. That's usable when there are few panels, but locating a panel when there are many requires a sort to make it easier to find a specific panel. When you click on Sorted Panel List, the Panel List appears in alphabetic order.

Show Icon View

Clicking on this option displays your Panel List in an icon or picture-like view.

Show Panel Res

This option in Hyperwise 2.0 displays resource (res) IDs in the Panel List. A help panel's res ID is used by an application to call that particular panel. You enter the res ID in the Number field on the Panel Properties dialog while authoring the panel. If you have many panels and are trying to locate a particular one, or if you are trying to see if you've already used a res ID, Show Panel Res lets you scan res IDs at a glance.

Show Structure Markers

Structure markers are colored markers placed before and after structures such as definition lists, ordered lists, examples, and so on. Markers help you determine whether to place the next element inside or outside the structure. For example, if you start an ordered list and decide to write a paragraph explaining one of the list items, you would probably want the paragraph to be indented so that it looks like it belongs with the list item. If the same paragraph is placed outside the structure markers, it looks to the reader as if the paragraph is introducing another thought. Most word processors make that decision for you. Hyperwise does not.

Show Keys

Hyperwise supports conditional assembly of text. If you have one document and want to use it for two purposes, conditional assembly may be a help to you. Within IBM, conditional assembly is most often used with documents that are updated from one product release to the next. For example, OS/2 Version 2.0 was updated for Version 2.1. A great percentage of the information remained the same; however, the text that was unique to Version 2.0 had to be hidden in Version 2.1, and vice versa.

Any unique text must be hidden under lock and key. The key is the password that unlocks the text.

After a document is open in Hyperwise, a lock icon appears on the Hyperwise desktop. To see the function in action, mark any text with mouse button 1 and drag and drop the text onto the lock icon. A dialog appears asking for a key password. That same key must be stored in an environment variable called KEY= when your product ships and is installed. Then when you start up OS/2, the information associated with that key is the only "viewable" information.

The Show Keys flag displays a key icon wherever you have unique information that is protected by a password.

Show Full Element List

The Element List was discussed earlier in this article. If you have reduced the size of your Element List and want to restore the full list, click on this option to do so.

Show Hiddden Text

This function has nothing to do with the "lock and key" function discussed above.

Most IPF and BookMaster files contain comments written by the author for other developers to read. Comments are usually hidden when the document is imported into Hyperwise. Both IPF and BookMaster have elements that are not formatted, such as :userdoc. and :title.. These elements are also hidden when they are imported. The reason they are hidden is simply to make the document more readable. If you want to edit the comments or the non-displayable text, click on Show Hidden Text to display the text (it will appear in red). If you receive the message "Reset the element properties....," you should set the Show Hidden Text flag.

Disable Autolinks

To set an autolink, select Panel and then Link from the action bar, and then select the object that is to be automatically linked. That means the object will be displayed right after the panel is displayed. While editing, you might find that the second object appears; if this happens, edit the originating panel. Set Disable Autolinks to stop the link from executing.

Enable Advanced Mode

To create your own fonts, panel styles, elements, prefixes, and more, click on this option. The one advanced feature you can use without restriction is creating your own panel styles. Another commonly used function is creating your own font (the restriction is "fixed" font for IPF view). Don't use elements or prefixes in anything other than prototyping projects, because elements and prefixes are too tightly associated with IPF or BookMaster.

Highlight Symbols

In the IPF and BookMaster tag languages, colons, ampersands, and carats are symbols. The Highlight Symbols option puts a yellow box around symbols so you can spot them easily.

Hyperwise has "signals" for symbols because operating systems have different code pages and print formatters, and display engines have varying ways to present the same elements. It's easier to change the name of an element or the name of a symbol than it is to change a program formatter or a system code page.

Auto Save

By default, Hyperwise automatically saves your document after 10 minutes. If you want the save time to be more often or less often, or you don't want to autosave at all, you can change the Auto Save setting as desired.

Editors

Type the path and name of a particular graphics, video, or audio editor in the appropriate field. That way, you can automatically edit a multimedia element while in Hyperwise.

To see this in action, type the path and name of the icon editor (typically ICONEDIT.EXE) in the Bitmap field. Then display bitmaps (select the Graphics icon from the action bar and then select the View push button). Double-click with mouse button 2 on any bitmap; the icon editor is automatically called and the bitmap appears in the editor. You can edit, save, and then continue your work in Hyperwise.

User Preference Behavior Functions

Enable Group/Clear

Grouping panels in Hyperwise is a very important and powerful function. Volume 8 of The Developer Connection News included an article called "Hyperwise 2.0: Helpful Hints and Tips" that explained the group attribute. To repeat, all panels have a default grouping of zero. Specifically designed for IPF viewing, this ensures swapping, which in turn ensures minimum memory usage. Giving a panel style a unique attribute means that it can be displayed next to or overlap another panel that has a unique and different group number. For specific steps on how to change a panel style's grouping, read the article in Volume 8.

The Clear flag can be set on any panel style to actually close all other help panels. To locate the Clear attribute, click on View, then Panel Style List, and then double-click with mouse button 2 on any panel style name. On the lower right you will see all the possible attributes for a panel style.

Show Contents Only

In the latest version of Hyperwise, hidden panels are displayed in the Table of Contents. This feature is helpful if you want to change the order of the panels (if you have imported an IPF file). Click on Show Contents Only to see what entries are available to the customer from the Table of Contents.

When Show Contents Only is enabled, the order of the contents list cannot be changed.

Show Push Buttons

There are up to seven push buttons available to you for use in your .INF and .HLP files: Previous, Search, Print, Index, Contents, Back, and Forward. The Previous button displays the panel you were viewing before the current panel was displayed. Back moves you back one panel in the document's order. (The Table of contents determines the order of your document.)

Choose from any one of these buttons to create your own group of push buttons and then associate them with your document. To see which push buttons are associated with your document, click on Show Push Buttons. They are not functional in Hyperwise but are functional as an .INF or .HLP file.

Conclusion

The Element List and User Preference dialog are two powerful features of Hyperwise. We've given you tips on using and customizing the Elements List. You learned how to enhance your editing and testing environment with the User Preference dialog. Refer to previous issues of The Developer Connection News to learn about other Hyperwise features that help you enhance your text and graphics based presentations with sound effects, music, video, and animation.