March 2000: Formatting Topics

This Help Corner column was originally published in March, 2000, and written for RoboHELP Office Version 8.

by Char James-Tanny

In this section...

January 2000: Setting the Tool Options

February 2000: Macros and Scripting

April 2000: Using Dynamic Linking

May 2000: Modular Help

June 2000: Context-sensitive Help

August 2000: Using the Single-Source Wizards in RoboHelp Office

September 2000: RoboHelp Version 9 is here!

October 2000: Generating WebHelp

November 2000: Creating Glossaries

December 2000: Using Browse Sequences

Formatting Topics

How do you decide what font families to use when developing online Help? Font size? Font color? You want to distribute Help files that users can actually read, but the ultimate caution is this: users control how your WinHelp files actually display and, depending on your style sheet, users can also control how your HTML Help and HTML-based Help files display. (They may not always know it, however.)

This month, I'll discuss the formatting options for both RoboHELP for WinHelp (RoboHELP) and RoboHELP for Microsoft HTML Help (RoboHTML), including some tips and tricks to help you present the information the way you want it appear.

A Formatting Overview

Several months ago, a thread on one of the lists reminded me that those of us who have been developing online Help for awhile forget what it's like to be new. This thread discussed the use of font families in online Help files and one poster was upset to discover that we can't just use any font family we want--not if we want users to be able to view it correctly, that is. We also have to be careful when using font colors, or the user's experience could be vastly different from what we were expecting.

Part of the power of Windows is the ability to customize your desktop so that it uses colors that you like. Part of the problem is that it can totally destroy the design of your Help file. Here's a test: change your system desktop properties to use aqua for the window and blue for the text in the Properties dialog box. Then, select Start | Help. Do you really think that this combination was what Microsoft had in mind? I doubt it!

Now, launch Calculator and notice the new application color. Right-click over any button and select What's This? to display the context-sensitive WinHelp topic. Notice the color combination for this topic. Next, select Help | Help Topics from the Calculator menu. Your new color combination appears in the navigation pane and is also used for the text color in the default topic. Then, select a topic from the Table of Contents. The topic displays with the colors as they were set by the developer in the style sheet (in this case, black text on a white background).

Next, open a Windows Help (.hlp) file. You can use one of your own, if you have one, or use Robohelp.hlp. Notice that the window color matches your custom setting. However, the font will either match your setting or it will be another color (typically black). Font colors in WinHelp files are controlled by a Word setting. All text that is formatted to use the default color uses the system setting. All text that is formatted to use a specific color uses that color.

Tip

The safest color combination for WinHelp files is black text on a white or dithered yellow window. These combinations might be boring, but the content will always display. Well, almost always anyway--if the user sets their window color to black (which has to be rare) and you've set the text in your Help file to black, and then the user will see a black Help window. The content is there, but no one can see it.

Font families are another consideration for WinHelp, HTML Help, and HTML-based Help. If the font you've chosen to use doesn't exist on the user's system, another font is used instead. (This is called substitution.) If a font substitute has been entered in win.ini, the substitution font displays. Otherwise, the system displays another font from the user's font table. You can always ship the font on the installation media, but the suggested method is to use a standard system font.

In WinHelp, this leaves us with very few choices--Arial, Times New Roman, and Courier New have long been considered the "safe" fonts. In HTML Help and HTML-based Help, we have a little more flexibility because we can use font sets--a list of font families, one of which eventually (hopefully) matches a font family on the user's system.

Tip

Sans serif fonts, like Arial or Verdana, are the easiest to read in online documents.

In addition, users can modify their browser settings to use specific colors for the window, text, and links. In Netscape, they can also choose to always use their colors instead of yours. In Internet Explorer, select Tools | Internet Options, and then click the Colors and Fonts buttons at the bottom of the screen. In Netscape, select Edit | Preferences, and then click the Fonts and Colors options under Appearance.

Tip

Set your browser options to use different colors and fonts for text, links, and windows. When developing HTML Help or HTML-based Help and viewing the results, these settings will indicate those places where styles haven't been correctly applied. Occasionally, this will affect some sites that you visit. However, most HTML developers use style sheets to verify formatting, so it shouldn't disrupt your surfing too much.

Before we continue, you might want to reset your system colors to their original settings. (I know that I've seen enough aqua for now!)

Formatting Topics in RoboHELP 2000 for WinHelp

Because RoboHELP sits on Microsoft Word, you should take full advantage of Word when formatting your topics. This includes using Word to modify the document template, the current document only, or individual words or phrases.

You can use any styles or formats to achieve the layout you want. With a few exceptions, the formatting you apply in Word displays in your Help project.

Tip

The better you know Word, the easier it will be to use RoboHELP.

Document templates let you standardize formatting, text, and graphics for consistency across documents. They can also be used to save styles, macros, and other customized settings. RoboHELP comes with a Word template called RoboHELP.dot which includes RoboHELP styles, macros, menu items, and toolbars. RoboHELP applies this template to every Help project document automatically. If you assign a different template to a Help document, you'll lose all of RoboHELP's functionality.

The styles in the RoboHELP template are formatted specifically for Help authors to use in Help projects. The RoboHELP template includes the following styles:

Style	Used for	Notes
Heading 1 Heading 2	Topic titles for jump and popup topics	Help authors generally assign Keep With Next formatting to Heading 1 to create non-scrolling regions. However, if you assign Keep With Next to headings associated with popup topics, only the heading displays. Therefore, most Help Authors use Heading 2 for their popup topics. Use the Advanced Settings dialog box under the RoboHELP menu option in Word to assign Heading 2 to topics that will be popup targets.
Normal	Topic text	With one exception (Tip/Note Text Bulleted), all styles are based on Normal, which is defined as 8 point Arial. This enables you to update Normal and have all other styles update automatically. See below for more information.
Tip/Note Heading	Tip or note heading
Tip/Note Text	Tip or note text
Tip/Note Text Bulleted	Bulleted list in a tip or note	This style is based on Tip/Note Text style.
Topic Text Numbered	Numbered list for procedure topic	This style uses Auto- Numbering, with the number hard-coded to 8 point Courier New. (If you change the point size of the style, the formatting of the number itself doesn't change.) See below for more information.
Topic Text Onestep	Single step in a procedure topic	To implement this style correctly, you have to insert the onestep graphic , followed by a tab.
Topic Text Indent	Indented text for use after the onestep style or between items in a numbered or bulleted list	This style allows you to insert indented paragraphs that will align correctly after text that uses numbers, bullets, or the onestep graphic.

Changing the Format of the Styles

When developing WinHelp files, the only effect that works is All Caps in the Effects section of the Font dialog box. No other effect in this section displays correctly. Also, make sure that the font color you select works with the color of the window assigned to the topic.

You can easily change the format of any style in RoboHELP by using the Style dialog box. Note that this is the only way to change the formatting of the Normal style.

Select Format | Style.
Select the style from the style list.
Click Modify to display the Modify Style dialog box and change the style as necessary.
When you're finished, click OK.
Repeat steps 1-4 for any other styles that you want to modify.
When you're finished, click Close (if your cursor is not positioned in the style you just modified) or Apply (if your cursor is positioned in the style you just modified).

Word 97 allows you to globally modify any style except Normal within the current document without using the Style dialog box. To change a style:

Select some text within the paragraph.
Modify it accordingly.
Making sure the text is still selected, click the drop- down arrow next to the Style box on the Word formatting toolbar.
Select the same style from the Style list. The Modify Style dialog box displays.
Click OK to update the style within this document.

Neither of these methods updates the template. If you want to modify the template, you must select the Add to Template checkbox on the Modify Styles dialog box. When you save the file, save the changes to the template at the Do you also want to save changes to document template? prompt.

What's the difference between these options? If you modify a style, either through the Style dialog box or globally, the changes affect only the current document. However, if you modify a style with the Style dialog box and click the Add to Template option, the template is permanently modified (until you change the style again). This means that all new documents created with this template will use the modified style.

However, existing documents that use the template won't necessarily be updated. You can set a document to automatically compare its formatting to the template by selecting the Automatically Update Document Styles option on the Tools | Templates and Add-Ins dialog box. Any styles that you have "tweaked" will be reset to the template style. If this option is not selected, the new changes won't be applied unless you do it manually.

Working Around the Auto-numbering Problem

Auto-numbering doesn't always work correctly in Word, which means it doesn't always work correctly in RoboHELP. There are two workarounds:

Create an indented style and number the paragraphs manually.
Visit Knopf Online and learn how to apply numbering with {SEQ} fields in Word.

Working with Tables

Tables allow you to control the layout of your topics. The default table layout in Word usually produces a horizontal scroll bar in your Help file, since WinHelp wants to be sure that users see everything in the .doc file (including the far side of the table).

You can prevent the scroll bar from displaying and also make a table that is auto-sizing--that is, if the user resizes the window, the table will resize to match.

To remove the horizontal scroll bar, select Table | Cell Height and Width. On the Row tab, select the Center alignment option. This options doesn't center the text inside the table, just the table itself.

To create an auto-sizing table, make sure that the total table width is two inches. Therefore, the total of all column widths must be two inches. Each column sizes proportionally, based on comparing its width to the total table width. For example:

If you want an equally-distributed two-column table, create two one-inch columns.
If you want an equally-distributed four-column table, create four half-inch columns.
If you have a two-column table and want one column to be 25% of the total table and another column to be 75%, create one half-inch column and one one-and- one-half inch column.

I know that this can be confusing, especially at first. But if you practice with several different tables, you'll soon get the hang of it--and your users will love it :-) . I have used this technique with as many as 11 columns.

WinHelp, and therefore RoboHELP, doesn't allow table formatting such as borders, shading, and so on. If you enter any of these formatting elements, the compiler displays a note that you have uncompilable table elements or that table cell borders are not supported. Your finished Help file omits these elements, although it retains the table formatting. When you insert a table in Word 97, it automatically creates a grid border. Remove any table borders before compiling, or you will get a compiler note. However, this doesn't affect the compiled help file. (The border isn't displayed, and the text displays as formatted).

Formatting Topics in RoboHELP 2000 for Microsoft HTML Help

RoboHTML uses style sheets and tags to determine formatting. Because it relies on HTML, you'll find more flexibility and functionality. Better yet, some of the things that you can't use in WinHelp (such as superscripting, subscripting, and table borders), can be used in HTML Help and HTML-based Help.

Instead of templates, HTML uses Cascading Style Sheets (CSS), which are ASCII (text) files with .css extensions. CSSs allow you to separate the display from the content and contain "instructions" for the browser concerning the display of content in your HTML files. A CSS is similar to a word processing template, with one major difference: any change to a CSS is reflected the next time any associated HTML files are displayed in the browser (or reloaded, if a file is already open).

RoboHTML's WYSIWYG Editor uses the CSS to interpret the tags and display the HTML files while you're developing your project. The TrueCode Editor displays the tags and content with no formatting.

Instead of, or in addition to, using a CSS, you might choose to embed style information in the HTML file. If you are using a CSS, this lets you selectively replace styles in an HTML file. If you aren't using a CSS, this lets you include specific style information for the HTML file. Embedded style information can be copied between HTML files. For example, this column uses embedded style information.

You can also use inline styles to format specific text within the HTML file. For example, to display a word as bold, you can apply bold formatting to the word. The word then always displays as bold, even if the font changes or if users change the browser settings. If you associated a CSS with the HTML file, the definition for bold is retrieved from the CSS.

Style sheets follow a specific progression:

Unless explicitly overridden elsewhere, the Body document style controls all initial display settings for paragraph and character styles. For example, if you set Body style to 10 point Verdana, Normal also uses 10 point Verdana (unless you change it to something else in the Paragraph style dialog box).
You also need to be aware of another factor that will influence your styles: inheritance. In most cases, styles inherit their settings from Body or the style on which they are based. However, some styles don't inherit any properties from other styles, which means you have to include all style information when designing the style. You can get more information from the Cascading Style Sheets section at the World Wide Web Consortium.
Inline styles override embedded styles, which in turn override style sheet styles.

For example, your CSS specifies that the Heading 1 style is an 18 point font. Assume you manually format each Heading 1 style in an HTML file to use a 16 point font. You will no longer be able to use the CSS to change the font size for Heading 1 in this file because you have overridden the style at the Character level.

As much as possible, use your style sheet to control your display. It takes time at the beginning to get it set correctly, but it will save an immense amount of time later if you decide to change the display.

Internet Explorer (IE) and Netscape Navigator display HTML files differently. While Netscape tends to strictly follow the W3C standards, IE tends to be much more forgiving of mistakes. This is compounded by the fact that CSS bugs in Netscape will drive you insane when you are developing WebHelp. You can get more information on bugs for both browsers from WebReview and CSS Pointers Group (Bugs and Workarounds). One thing to pay strict attention to: if any property is incorrect in a Netscape style sheet, the entire style is ignored.

One of the biggest differences between HTML Help and WinHelp is that you can control the background color of each topic. (This explains why the earlier examples displayed the HTML files correctly.) You can also control the colors for the fonts.

RoboHTML includes the 16 standard Windows colors in various drop-down boxes. However, you can also create custom colors for your background and fonts.

To create a custom color:

Click the font color drop-down arrow and select the last option in the list (Define in the Style Sheet Editor or Custom from the Font Color drop-down box on the Formatting toolbar). The Define Color dialog box displays.
Type the new color name in the Define Color input box. This activates the Add button.
Create the color by setting the Hue, Saturation and Luminosity values, or by setting the Red, Green, and Blue values, or by dragging your cursor around the color box.
When you're finished, click Add.
Click OK to close the dialog box.

Once you create a custom color, it is available throughout your project at the bottom of the drop-down box.

You should always use the Web-safe color palette when designing HTML pages. While there are numerous color combinations (especially when using a monitor set to 16-bit color), the RGB code of the safe colors include 00, 33, 66, 99, CC, and FF. For one (of many) samples on the Web, visit the Webwork Hexidecimal Color Sampler.

Selecting Browser-Safe Fonts

Before you create your CSS, you need to determine which fonts you will use. This isn't as important if you're creating HTML Help, because you know the Help file will run on a 32- bit Windows system with Internet Explorer installed. In that case, you use a Windows system font (such as Arial or Verdana). However, if you're developing WebHelp, you need to specify fonts that display on other systems (for example, Sans Serif, Helvetica, or Geneva for Macintosh systems or Helvetica for UNIX systems).

In order to select fonts that work in WebHelp, create a font set that lists multiple fonts. The user's browser looks for the first font in the list. If it's found, that font is used for the display. If it's not found, the browser looks for the next font in the list. This lets you control the display even if you specify fonts that might not be on the user's system. A typical cross-browser font set includes Arial, Verdana, MS Sans Serif, Helvetica, and Sans Serif.

According to CNET Builder, the most common fonts for all platforms include Arial, Helvetica, and Times. PC and Macintosh users who install Internet Explorer 4.0 can also take advantage of Verdana.

To create a font set with RoboHTML:

Select Format | Font Sets. The Font Set dialog box displays.
Click New.
Add a name for the font set, and then add the fonts (in the order that you want the user's browser to look for them).
When you're finished, click OK and Done.

If you are creating WebHelp, you'll discover that only Windows system fonts display in the Font Set dialog box. To add the necessary font names for UNIX and Macintosh, type them in the input box above the list of font names and then click Add.

Once you've created a font set, the name of the font set displays in the font family list. You can specify it when creating your style sheet or you can use it when modifying text in the WYSIWYG Editor.

Creating a New Style Sheet

To create a style sheet, click New on the Appearance tab of the Topic Properties dialog box for any topic. The Save dialog box displays. Type a name for the style sheet and click Save. To modify a style sheet, double-click the style sheet name on the Projects tab (under the Style Sheets folder) or click Edit on the Appearance tab. The Edit Style Sheet dialog box displays.

You can modify any document, paragraph (default), and character styles. Document styles apply to the entire document. Paragraph styles apply to blocks of text. Character styles apply to characters (usually words) within a paragraph.

To modify an existing style:

Click the drop-down arrow next to Style Type and select Document, Paragraph, or Character. The Style: box lists all available styles of that type.
Select a style from the list.
Click Edit.

You can also create new paragraph and character styles. To create a new style:

Select an existing style. (The new style is based on the style you select.)
Delete the name of the style in the input box.
Type the new style name.
Click New. (The New button doesn't activate until you type over the existing style name.)
When you add a style, the name displays in the style list indented under the name of the style it was based on.
You must then edit the new style to design its attributes.

If you find yourself constantly formatting certain text the same way (for example, a company name that should always display as bold maroon), it will be easier and more efficient to design an inline or paragraph style.

One exception is popup hyperlinks. CSSs include descriptions for links (as they first display), active links (when a user positions the cursor over the link), and visited links (after the user has visited the target). However, as far as the browsers are concerned, there isn't any difference between standard hyperlinks and popup hyperlinks. Therefore, all links display according to the style sheet.

This was different in WinHelp, which formats standard hyperlinks with a single underline and popup hyperlinks with a dotted underline. To differentiate between the types of links, you have to reformat all your standard hyperlinks or all your popup hyperlinks. For one client, I used maroon text to indicate standard hyperlinks (from the style sheet) and navy underline to indicate popup hyperlinks (reformatted).

It doesn't matter which one you reformat, as long as you are consistent.

Assigning Style Sheets to Topics

After you create a style sheet, it is assigned to the current file by default. Every file you create from then on will use that same style sheet.

To change the associated style sheet:

Display the Appearance tab in the Topic Properties dialog box, click the Open File icon to the left of the Edit button, and select the desired style sheet. If you select a style sheet that's not currently in the project folder, you have to confirm the Copy message.
Display the Appearance tab in the Topic Properties dialog box and click the New button to create a new style sheet.
On the Topics tab, select a group of topics and then click Properties. On the Appearance tab, select the style sheet for these topics.
Display the Appearance tab in the Topic Properties dialog box, click the drop-down arrow to the right of Style Sheet, and select the desired style sheet.
In the WYSIWYG Editor, click the drop-down arrow next to Style Sheet and select the desired style sheet.

The only style sheets that display in the drop-down boxes for the last two options are those currently in use in your project. If you want to attach a style sheet that's in your project folder but not currently associated with a file, you must use the Open File icon on the Appearance tab in the Topic Properties dialog box.

Working with Tables

Tables in HTML are fully functional (this means something if you are familiar with WinHelp, which didn't allow formatted tables). You can use shading and borders to control your display. You can control the table size using the Table Properties or Cell Properties dialog box.

The default size for a table is 100% of the window. The default size (width) for columns uses the equation: table width divided by number of columns. For example, two columns would each be 50% wide; three columns, 33%; four columns, 25%. You can change the width of the table and other table properties by using Table Properties. Click inside the table (you don't have to select the table) and either:

Select Table | Table Properties.
Right-click and select Table Properties.

The Table Properties dialog box displays. Specify the width of the table (pixels or percent), table border thickness, cell border thickness, and cell padding (the number of pixels between the text in a cell and the cell border, whether or not it displays). You can only set the cell border if you have set a table border.

You can also modify individual cells. Cells are the individual components that make up a table (where a row and a column intersect). Using Cell Properties, you can modify individual cells to produce the desired table effects.

To change the cell properties, click inside the cell and either:

Select Table | Cell Properties.
Right-click and select Cell Properties.

The Cell Properties dialog box displays. Specify the vertical alignment of the content in a cell, the color of the cell, minimum height, and cell width (pixels or percent).

Unless you really need absolute control over the table and cell width, you should use percentages for the width. This lets the table expand and contract to match the window size. In addition, if you change the default percentage value for a column, make sure that all columns add up to 100% or the table might not display as you intended.

You can modify cells by merging them, which combines two or more cells. You might use merged cells for table headings or other content that should display across the table.

Select the cells you want to merge.
Select Tables | Merge Cells. The cells merge into one.

Merged cells can be split back into their original cells (if you accidentally spanned cells or if you change the table design).

Position your cursor inside a spanned cell.
Select Tables | Split Cells. The original cells display.

Material in this section is taken from Using RoboHELP 2000 for WinHelp, a training seminar provided by SOLUTIONS, Inc. and taught by Char James-Tanny, and Sams Teach Yourself RoboHELP 2000 for HTML Help in 24 Hours by Char James-Tanny, ISBN 0-672-31625-0. Used with permission from Macmillan Computer Publishing USA.