IBM Director help

This topic describes providing html help files for each of the eight supported languages.

Subtopics

Related information

Related sample code

Overview

The IBM Director help system has multilingual support. The current product ships in eight languages. IBM Director console extensions can provide HTML files for other languages and an index that supports these help html files. The index file has associated with it a resource bundle of strings for each language (see Help index for more details).

There are specific character sets, code pages, and a common style sheet that the console and all Console Extensions must use. These ensure product consistency (see the sections on Character set and Style sheet for more details).

The product name is subject to change. Macros are provided for phrases containing the product name. These macros permit the product name to change without impacting translation and development resources. The product name should never be entered directly anywhere in an html help file; the appropriate macro should be inserted (see the section on Product Name Macros for more details).

The IBM Director help viewer is based on Java's JEditorPane widget and HTMLEditorKit class. Under the current JRE, HTML 3.2 support is provided. The JEditorPane is not as forgiving as other browser products such as Netscape and Internet Explorer. HTML is expected to be written to specification. Just as Netscape and IE can render HTML differently, JEditorPane is also unique. When developing help, it is required that help file updates are tested for layout and white space using the target version of the installed product. Testing changes to help files and new help sections is simple because files might be replaced and/or added into the appropriate directories and the console restarted.

Help file installation

For each language, help files will be installed into the:
product classes/doc/country/extdirectory,
where country indicates the country. Console Extension developers can select an appropriate name for extdirectory. In the absence of translated files, English files from:
classes/doc/en
will be used.

Note: de, en, es, fr, ja, ko, zh_CN and zh_TW are not modifiable by developers. They must be exactly as listed in the following example or the IBM Director help facility will not find them.

Example 1: Rack Manager help

English, considered the Default help, is installed into directory:
    classes/doc/en/nfrackmgr 
German Rack Manager help files are installed into directory:
    classes/doc/de/nfrackmgr
French Rack Manager help files are installed into directory:
    classes/doc/fr/nfrackmgr
Spanish Rack Manager help files are installed into directory:
    classes/doc/es/nfrackmgr
Japanese Rack Manager help files are installed into directory:
    classes/doc/ja/nfrackmgr
Korean Rack Manager help files are installed into directory:
    classes/doc/ko/nfrackmgr
Simplified Chinese Rack Manager help files are installed into directory:
    classes/doc/zh_CN/nfrackmgr
Traditional Chinese Rack Manager help files are installed into directory:
    classes/doc/zh_TW/nfrackmgr

Help index

Augmenting the index

IBM Director help index is created from xxx.idx files where xxx is a help function name. For example Help for Software Distribution is indexed in the file sw_dist.idx or Inventory would be in the file inventory.idx. For ease-of-maintenance, the IDX file should use the name of the directory containing its help files. Common naming helps to associate these groups during development and TVT. IDX files are installed into the classes/index directory of the IBM Director product.

Layout/Syntax of a simple IDX file:

index.nls_bundle=com.tivoli.twg.console.nfdindexnls
index.1.label=Assetcare
index.1.link=../assetcare/tsk_assetcare.html
index.1.1.label=Assetcareasset
index.1.1.link=../assetcare/asset.htm
index.1.2.label=Assetcarelease
index.1.2.link=../assetcare/lease.htm
index.1.3.label=Assetcarepersonalization
index.1.3.link=../assetcare/personalization.htm
index.1.4.label=Assetcareserialization
index.1.4.link=../assetcare/serialization.htm
index.1.5.label=Assetcaresystem
index.1.5.link=../assetcare/system.htm
index.1.6.label=Assetcareuser
index.1.6.link=../assetcare/user.htm
index.1.7.label=Assetcarewarranty
index.1.7.link=../assetcare/warranty.htm
index.2.label=cimsnmp
index.2.link=../cimsnmp/tsk_cimsnmp.html
index.2.1.label=addingcommunityname
index.2.1.link=../cimsnmp/adding_a_community_name.htm

An IDX file is a Java property file that consists of a set of "key=value" combinations describing how a particular portion of the index is to be created. Strings must be extracted from locale-specific bundles, therefore the first "key=value" item in the IDX file tells the index generator the name of the bundle that contains the strings for this portion of the index. In the previous example, the bundle that contains the strings is com.tivoli.twg.console.nfdindexnls. There will be one of these bundles for each country.

The .label=value keys are followed by a String key which must be defined in the specified index bundle. These bundles are the same bundles described in NLS for IBM Director Console Extensions. This label will added to the index, associated with its corresponding link. The numbering in the index.X.label or index.X.Y.label describes the hierarchy of the index to the index generator.

Index terms

The Index for IBM Director Helps will follow the guidelines set fourth in the IBM Style Guide. There should be at least one entry for every major help window/topic but no more than five per page.

Do not index glossaries. 

Follow these guidelines to create the terms for your index:

Use nouns or noun phrases for primary entries, but avoid using generic terms such as "using" or "changing" as primary entries.
Examples:
account, IRQ
IRQ account
    setting up
    deleting

Use gerunds as primary entries sparingly; use gerunds that readers will not find ambiguous.
Examples: backing up the hard disk
printing
    help topics
    online books

Examples (incorrect):
adding an account
creating an account
making a new account
setting up an account

The preceding incorrect examples show some of the ways a reader might think of "creating an account." A primary entry for "account" followed by one of these gerunds as a subentry would be a better choice.
Example:
account, creating

Use adjectives, gerunds, nouns, or noun phrases for subentries.
Examples:
IRQ account
    accessing
    deleting

subroutines
    first
    utility

Limit the use of prepositions and articles to those required for clarity.
Examples:
records
    reading from
    viewing list of
    writing to

Check each subentry to determine whether it should also be included as a primary entry.

Include all meaningful variations for multiple word entries.
Examples:
C shell command interpreter
command interpreter, C shell
interpreter, C shell command

Use a comma to separate the noun from the modifying words.
Examples:
storage, magnetic tape
tape storage, magnetic

Use lowercase letters unless the subject appears in the text in all capital letters (for example, abbreviations) or with initial capital letters, such as for proper names.
Examples:
FORTRAN language
Polish notation
Western Union messages

Use the plural forms of nouns unless the subject is normally singular, such as control panel.

Character set

Character sets encoded into the HTML files and code pages used to create these files are as follows:

Language Character Set Code page
English ISO-8859-1 850
French ISO-8859-1 850
German ISO-8859-1 850
Spanish ISO-8859-1 850
Japanese Shift JIS SJIS
Korean EUC-KR 949
Chinese, simplified GB2312 1381
Chinese, traditional Big5 950

Style sheet

IBM Director Console and console extensions use a common cascading style sheet (CSS). The style sheet (director.css) ensures consistency of the product help. Styles defined in director.css are open to change as the appearance of the product help is designed and reviewed by Human Factors and others. The file is installed into classes/doc.

Note that no rules including color, font or font size have been specified. Colors are user-configurable, consequently color-related style rules are added dynamically by the IBM Director help facility after help documents have been loaded. Note that it became necessary to revisit the original IBM Director Version 4.2 use of director.css in IBM Director Version 5.1 because the Help Viewer must be responsive to font-size changes to satisfy the Accessibility requirement. It was necessary for style rules to be dynamically added to documents by the help viewer based on the font size setting selected by the user.

p                { margin-top: 10px; margin-bottom: 10px }
pre             { margin-left: 6}
a:visited      { text-decoration: underline }
ul                { margin-top: 0; margin-bottom: 10 }
li                 { margin-top: 2; margin-bottom: 0 }
li p              { margin-top: 0; margin-bottom: 0 }
ol                { margin-top: 0; margin-bottom: 10 }
dl                { margin-top: 0; margin-bottom: 10 }
dt                { margin-top: 3; margin-bottom: 0; font-weight: bold }
dd               { margin-top: 0; margin-bottom: 0 }
strong          { font-weight: bold}

Product name macros

The product name should not be used directly in Console Extension help or as values in index string property files because the product name periodically changes. The IBM Director help facility recognizes a set of macros and will make the appropriate substitutions based on locale. Macros are case-sensitive and bounded by '%' marks. Only exact matches will be substituted.

Macro

English string associated with macro

%FullProductName%

IBM Director

%ProductName%

IBM Director

%ProductServerName%

IBM Director Server

%UserGuideName%

IBM Director Systems Management Guide