This chapter describes how to test help books and provides a general discussion of how help works. The mechanism for displaying help is the SGI Help Viewer (also know as sgihelp).
The following topics are discussed:
Help generally consists of three parts: the application, the helpmap(s), and the document. In certain situations, the application can bypass the helpmap and go directly to the document.
Figure 8-1 shows the flow of how an application accesses its help information.
Depending on its complexity, an application can include a help menu as well as a help button (context-sensitive). Widget strings are used to tie the application to its helpmap.
The helpmap is the key to making help work correctly. This text file provides a mapping between the help menu in the application and the help topics in the online book. Each helpmap line contains six fields that define the mapping. The third field of the helpmap corresponds to one of the application's Help pulldown menu items and to a help topic in the FrameMaker source used to create the online document.
A menu item appearing in an application's pulldown Help menu corresponds to the third field of a line in the helpmap. The menu item usually matches a heading title in the FrameMaker source, so the third field of a helpmap usually matches a heading title in the FrameMaker source. Example 8-1 shows a few lines from an English book's helpmap.
1;Desktop_UG;Overview;0;schemes_overview;Scheme.scheme.overview 2;Desktop_UG;Choosing a Color Scheme;0;schemes_choose;Scheme.scheme 2;Desktop_UG;Editing a Color Scheme;0;schemes_edit;Scheme.scheme 2;Desktop_UG;Deleting a Color Scheme;0;schemes_delete;Scheme.scheme |
After you build a help book, but before you install it for testing, use the script gethelp to automatically replace the third field of each line of the helpmap(s) with its localized equivalents.
Invoke the script at the same level of the book's directory as the .sgm files.
% gethelp |
As described in the section, “gethelp Script”, this script extracts the help topics out of the individual SGML files and replaces the third field in the helpmap with the corresponding string (or heading title). The help directory (containing the helpmaps) must be present.
The third field is localized automatically by the gethelp script as shown in Example 8-2.
Example 8-2. A Localized Helpmap Sample
1;Desktop_UG;Présentation du visualisateur de schéma de couleurs;0;schemes_overview;Scheme.scheme.overview 2;Desktop_UG;Sélectionner un schéma de couleurs;0;schemes_choose;Scheme.scheme 2;Desktop_UG;Modifier un schéma de couleurs;0;schemes_edit;Scheme.scheme 2;Desktop_UG;Supprimer un schéma de couleurs;0;schemes_delete;Scheme.scheme |
Do a visual check of all the lines in the localized helpmap. Only the third field of each line of a helpmap should be localized. Also check for the SGML representations of extended characters such as umlauts. Figure 8-2 shows an example from the Frame source of a help topic followed by its heading. Notice the ó in “orientación”.
When the book is built, the SGML displays this ó character as “ó”. When the gethelp script is invoked, the localized heading will replace the English equivalent in the third field of the helpmap, as shown in Example 8-3. Notice that the ó is shown as “ó”.
Example 8-3. A Localized Helpmap Entry
0;Desktop_UG;Cambio de orientación de los toolchests;1;window.toolchest;FmPanel.fmPanel |
This string of text must be replaced with the actual extended character for the map to work in SGIHelp. To assist you in this task, Table 8-1 lists most of the extended characters and their SGML representations.
Table 8-1. SGML Representations of Extended Characters
Extended Character | SGML |
---|---|
þä | ä |
ö | ö |
ü | ü |
Å | Ä |
Ö | Ö |
Ü | Ü |
á | á |
é | é |
í | í |
ó | ó |
ú | ú |
ñ | ñ |
à | à |
è | è |
ì | ì |
ò | ò |
ù | ù |
â | â |
ê | ê |
î | î |
ô | ô |
û | û |
Sometimes the gethelp script does not automatically localize the third field, and in those cases, you will need to translate it manually. This occurs when Heading-tagged paragraph is not immediately followed by a Text-tagged paragraph (such as when a Heading1 is followed by a Heading2).
To perform this translation task, and to correct any extended characters, you may do the work on a system other than one manufactured by Silicon Graphics. When these helpmaps are ported back to a system running IRIX, sometimes a foreign character, such as a “^M”, is introduced to the end of each line in the helpmap. Using more to view the helpmap does not show these foreign characters; you must use vi or jot to do the visual QA.
If the foreign characters appear, they must be removed along with any blank space left by their removal. If a helpmap contains these characters, the help will not work when called from the application.
This section discusses the testing procedures for help books.
The first test method, described below, allows you to check the functionality (cross-references, external book links, and glossary items) within the help book and is useful when testing your first hand-off. However, it does not provide a means for checking the help as you would use it from an application. To perform the testing as if the help was being called from an application, see the following sections:
“Quick Answers” for 008-2169-nnn on page 122
“System Monitor Errors Help” for 008-2172-nnn on page 124
“Desktop Errors Message Help” for 008-2173-nnn on page 127
“Insight Help” for 008-2174-nnn on page 128
“SGIHelp Viewer Help” for 008-2181-nnn on page 130
“Confidence Test Help” for 008-2445-nnn on page 132
“Confidence Test Errors Help” for 008-3088-nnn on page 135
The HIDDEN = variable in the Makefile is set to TRUE for help books. Therefore, when help books are built and installed, they do not appear on the IRIS InSight bookshelves, nor can they be launched and viewed in your workarea. By changing the HIDDEN = variable in the built book's booklist.txt file, the book can be launched and viewed in IRIS InSight. This method allows you to check the functionality (cross-references, external book links, and glossary items) within the help book.
To force a help book to appear in IRIS InSight:
Build the book in your workarea:
% make book.full |
Use a text editor, such as vi or jot, to edit the booklist.txt file:
% vi booklist.txt |
Change the HIDDEN = variable from TRUE to FALSE.
<BOOK NAME=”ErrorMessageHelp” EDITION=”19941103” ALIAS=”Error Message Help” TYPE=”generic” HIDE=”FALSE” VERSION=”008-2173-003, 10/94” SORT=”010600” SRCHRES=”TRUE” SRCHTAGS=”TITLE:Titles;CAPTION,FIGURE:Figure Captions:1;CAPTION,TABLE:Table Captions:1;TABLE:Tables;CODE EXAMPLE:Code Examples” GROUP=”SGIDOC”> |
Save the file.
Log in to paranoia (for Japanese books) or gunstar (for European books) and set the environment:
% rlogin <name>@paranoia % setenv LANG ja.JP.EUC |
Change directories to your workarea on midas:
% cd /hosts/midas/online/people/<your_name>/books/1000/007-1366-100JP |
% iiv -f -b /hosts/midas/online/people/workarea/<part_number> . |
The help book should appear on a Help bookshelf in its localized language.
Open and test the book as you would any IRIS InSight book.
The following sections explain how to test each individual online help document. Each section is the name of the book followed by its part number, short_title, helpmaps (if any) for the book, a test script, and an explanation of how to test the helpkeys and the book. Except for Errors Message Help, each help document has a test script associated with it. The test script is used to assist you in finding problems. The section on “To test the book...” for each book describes the preferred method for testing the book. In some cases, using the script may be the only method available to test a book, and if so, it will be indicated in the description.
In order to ensure the localized book behaves the same as its English counterpart, follow these steps:
Build and install the English version on a test machine.
Open two UNIX shells. Resize and position them at the bottom of your screen, as shown in Figure 8-3.
In the left shell, log in to the test machine where the localized book has been installed:
% rlogin guest@gunstar |
Set the environment for the localized book using the BOOK_LANG variable.
Japanese | ||
French | ||
German | ||
Spanish |
![]() | Note: French and German help books cannot be tested against their English equivalents from the same test machine. |
In the right shell, login to the test machine on which the English help book has been installed.
Follow the test instructions in the specific section for your help book:
“Quick Answers” for 008-2169-nnn
“System Monitor Errors Help” for 008-2172-nnn
“Desktop Errors Message Help” for 008-2173-nnn
“Insight Help” for 008-2174-nnn
“SGIHelp Viewer Help” for 008-2181-nnn
“Confidence Test Help” for 008-2445-nnn
“Confidence Test Errors Help” for 008-3088-nnn
The information listed in the following sections explains how to test the localized help books side-by-side against their same-operating system English counterparts.
![]() | Note: Test scripts are slightly different, so look at them closely. |
Part Number: | 008-2169-nnn | |
ShortTitle: | HowDoI_Help | |
Helpmap(s): | ||
Test Script: |
To extract and test helpkeys, perform the following steps:
In the UNIX shell for the localized book, enter
% awk -F\; '$2 == “HowDoI_Help” { print $5;}' < /usr/share/help/BOOK_LANG variable/Desktophelp.helpmap > ~/Desktophelpkeys |
This script extracts the information from the fifth field of the helpmap (for those lines where the second field has this book's short_title) and creates a file containing a listing of these helpkeys (these are the same names as HelpTopic-tagged paragraphs in a book). Because Desktophelp.helpmap contains helpkeys for other books, this script ensures that only the helpkeys associated with this book are extracted.
Open and display the text file Desktophelpkeys using jot or more. Reduce the size of the shell and move it to one side of your desktop.
Enter the following test script into both UNIX shells using the first helpkey from the list. Append the script with -f &:
% sgihelp -b HowDoI_Help -k helpkey_name -f & |
Two SGI Help—Desktophelp viewers should appear, one in English and one in the localized language.
Position the two viewers and shells as shown in Figure 8-3.
Study the layout of the information in each viewer to ensure that the viewers are at the same location within the English book and the localized book.
Highlight and paste the first part of the test script into each shell, but use the next helpkey from the list:
% sgihelp -b HowDoI_Help -k helpkey_name |
If the localized viewer does not jump to the same location as the English viewer, or if a dialog box appears, then there is a problem with the help topic in the Frame source or with the corresponding line in the helpmap.
Repeat the test script for each helpkey in the list.
To test the book, perform the following steps:
In both UNIX shells, enter
% /usr/sbin/desktophelp |
Two SGI Help—Desktophelp viewers should appear, one in English and one in the localized language, each with an index listing in the appropriate language.
Double-click the first index entry in each viewer. Two new viewers should appear.
Position the four viewers as shown in Figure 8-4.
Study the layout of the information in each viewer to ensure that the viewers are at the same location within the English book and the localized book.
If there are any cross-references, click them in both viewers. Ensure that the localized version jumps to the same location in the book as the English version.
If there are any cross-book links, glossary items, or launchable URLS or applications, click them in both viewers to ensure that they work.
Continue checking each and every index entry to ensure the localized version behaves the same as the English version.
If the localized index entry does not launch a viewer, if cross-references do not jump to the correct location, or if cross-links or other active links do not work as they should, make corrections in the FrameMaker source.
Part Number: | 008-2172-nnn | |
ShortTitle: | ||
Helpmap(s): | No helpmaps. This uses the helpmaps from SysMonHelp. | |
Test Script: |
To extract and test helpkeys. perform the following steps:
In the UNIX shell for the localized book, enter
% awk -F\; '$2 == "ErrorHelp" { print $5;}' < /usr/share/help/BOOK_LANG variable/Sysmon.helpmap > ~/SysmonErrorkeys |
This extracts the helpkeys associated with only this help book and writes them to a file named SysmonErrorkeys.
Open and display the text file SysmonErrorkeys using jot or more. Reduce the size of the shell and move it to one side of your desktop.
Type the following test script into both UNIX shells using the first helpkey from the list. Append the script with -f &:
% sgihelp -b ErrorHelp -k helpkey_name -f & |
Two ErrorHelp viewers should appear, one in English and one in the localized language.
Position the two viewers and shells as shown in Figure 8-3.
Study the layout of the information in each viewer to ensure that the viewers are at the same location within the English book and the localized book.
Highlight and paste the first part of the test script into each shell, but use the next helpkey from the list:
% sgihelp -b ErrorHelp -k helpkey_name |
If the localized viewer does not jump to the same location as the English viewer, or if a dialog box appears, make corrections in the Frame source and rebuild and reinstall the book.
Repeat the test script for each helpkey in the list.
To test the book, perform the following steps:
In both UNIX shells, enter
% sysmon |
Two System Log viewers should appear, one in English and one in the localized language, each with an index listing in the appropriate language.
Pull down the Filter menu and ensure that all the items have checkmarks next to them. A series of messages should appear in each viewer.
Pull down the Help menu in both viewers and choose Index. Two new viewers should appear. Close the System Log viewers.
Double-click the first index entry having to do with error messages in each viewer. Two new viewers should appear.
Position the four viewers as shown in Figure 8-5.
Study the layout of the information in each viewer to ensure that the viewers are at the same location within the English book and the localized book.
If there are any cross-references, click on them in both viewers. Ensure that the localized version jumps to the same location in the book as the English version.
If there are any cross-book links, glossary items, or launchable applications or URLs, click on them in both viewers to ensure they work.
Continue checking the remaining index entries to ensure that the localized version behaves the same as the English version.
If the localized index entry does not launch a viewer, or if cross-references do not jump to the correct location or cross-links or other active links do not work as they should, make corrections in the Frame source.
Part Number: | 008-2173-nnn | |
ShortTitle: | ||
Helpmap(s): | No helpmaps | |
Test Script: |
To test the book, perform the following steps:
Open the English version of the FrameMaker document source, error2.doc.
From the Edit menu, choose Find/Change. Set up the dialog box to search for HelpTopic paragraph tags. Press Find.
Enter the following test script into both UNIX shells using the first HelpTopic from the FrameMaker source. Append the script with -f &:
% sgihelp -b ErrorMessageHelp -k HelpTopic -f & |
Two SGI Help viewers should appear, one in English and one in the localized language.
Position the two viewers and shells as shown in Figure 8-3.
Study the layout of the information in each viewer to ensure that the viewers are at the same location within the English book and the localized book.
If there are any cross-references, click them in both viewers. Ensure that the localized version jumps to the same location in the book as the English version.
If there are any cross-book links, glossary items, or launchable applications or URLs, click them in both viewers to ensure they work.
In the Frame source, find the next HelpTopic.
Highlight and paste the first part of the test script into each shell, but use the next HelpTopic from the Frame source.
% sgihelp -b ErrorMessageHelp -k HelpTopic |
If the localized viewer does not “jump” to the same location as the English viewer, or if a dialog box appears, make corrections in the Frame source and rebuild and reinstall the book.
Repeat the test script for each HelpTopic in the FrameMaker source.
Part Number: | 008-2174-nnn | |
ShortTitle: | ||
Helpmap(s): | ||
Test Script: |
To extract and test helpkeys, perform the following steps:
In the UNIX shell for the localized book, type
% awk -F\; '{ print $5;}' < /usr/share/help/BOOK_LANG variable/Insight.helpmap > ~/Insightkeys |
Open and display the text file Insightkeys using jot or more. Reduce the size of the shell and move it to one side of your desktop.
Enter the following test script into both UNIX shells using the first helpkey from the list. Append the script with -f &:
% sgihelp -b InsightHelp -k helpkey_name -f & |
Two SGI Help viewers should appear, one in English and one in the localized language.
Position the two viewers and shells as shown in Figure 8-3.
Study the layout of the information in each viewer to ensure that the viewers are at the same location within the English book and the localized book.
Highlight and paste the first part of the test script into each shell, but use the next helpkey from the list.
% sgihelp -b InsightHelp -k helpkey_name |
If the localized viewer does not jump to the same location as the English viewer, or if a dialog box appears, make corrections in the Frame source.
Repeat the test script for each helpkey in the list.
To test the book, perform the following steps:
In both UNIX shells, enter
% /usr/sbin/insight |
Two IRIS InSight Library viewers should appear, one in English and one in the localized language.
Pull down the Help menu in both viewers and choose the first item. Two IRIS InSight Help viewers should appear.
Position the four viewers as shown in Figure 8-6.
Study the layout of the information in each viewer to ensure that the viewers are at the same location within both books.
If there are any cross-references, click them in both viewers. Ensure that the localized version “jumps” to the same location as the English version.
If there are any cross-book links, glossary items, or URLs, click them in both viewers to ensure they work.
Continue checking the remaining help entries to ensure the localized version behaves the same as the English version.
Position the cursor over a button in the IRIS InSight Help English viewer and press the F1 key. Another help viewer should appear with information about that button. Repeat this for the localized viewer and verify that the same information appears in the help viewer.
Continue checking all the buttons and the menu bar as described in step 8.
Pull down the Help menu in both viewers and choose Index. Two new viewers should appear. Close the IRIS Insight Help viewers.
Double-click the first index entry in each viewer. Two new SGI Help viewers should appear.
Position the four viewers as shown in Figure 8-5.
Study the layout of the information in each viewer to ensure that the viewers are at the same location in both books.
Continue checking the remaining index entries to ensure that the localized version behaves the same as the English version.
If the localized index entry does not launch a viewer, if cross-references do not jump to the correct location, or if cross-links or other active links do not work as they should, make corrections in the Frame source and rebuild and reinstall the book.
Part Number: | 008-2181-nnn | |
ShortTitle: | ||
Helpmap(s): | ||
Test Script: |
To extract and test helpkeys, perform the following steps:
In the UNIX shell for the localized book, enter
% awk -F\; '{ print $5;}' < /usr/share/help/BOOK_LANG variable/SGIHelp.helpmap > ~/SGIHelpkeys |
Open and display the text file SGIHelpkeys using jot or more. Reduce the size of the shell and move it to one side of your desktop.
Enter the following test script into both UNIX shells using the first helpkey from the list. Append the script with -f &:
% sgihelp -b ViewerHelp -k helpkey_name -f & |
Two SGI Help viewers should appear, one in English and one in the localized language.
Position the two viewers and shells as shown in Figure 8-7.
Study the layout of the information in each viewer to ensure that the viewers are at the same location within the English book and the localized book.
Highlight and paste the first part of the test script into each shell, but use the next helpkey from the list.
% sgihelp -b ViewerHelp -k helpkey_name |
If the localized viewer does not jump to the same location as the English viewer, or if a dialog box appears, make corrections in the FrameMaker source.
Repeat the test script for each helpkey in the list.
To test the book, perform the following steps:
In both UNIX shells, enter
% sgihelp -b ViewerHelp -k help_overview |
Two SGIHelp viewers should appear, one in English and one in the localized language.
Pull down the Help menu in both viewers and choose the first item.
![]() | Note: New viewers do not appear; however, the information within each viewer should change. |
Study the layout of the information in each viewer to ensure that the viewers are at the same location within both books.
If there are any cross-references, click them in both viewers. Ensure that the localized version jumps to the same location as the English version.
If there are any glossary items or URLs, click them in both viewers to ensure they work.
Continue checking the remaining help entries to ensure that the localized version behaves the same as the English version.
If cross-references do not jump to the correct location or if other active links do not work as they should, make corrections in the Frame source and rebuild and reinstall the book.
Part Number: | 008-2445-nnn | |
ShortTitle: | ||
Helpmaps: | ||
Test Script: |
To extract and test helpkeys, perform the following steps:
Extract the helpkeys from the Confidence.helpmap. In the UNIX shell for the localized book, enter
% awk -F\; '{ print $5;}' < /usr/share/help/BOOK_LANG variable/Confidence.helpmap > ~/Confidencekeys |
To extract the helpkeys from the ConfTestHelp.helpmap, enter
% awk -F\; '$2 == "ConfTestHelp" { print $5;}' < /usr/share/help/BOOK_LANG variable/ConfTestHelp.helpmap > ~/ConfTestHelpkeys |
Open and display the text file Confidencekeys using jot or more. Reduce the size of the shell and move it to one side of your desktop.
Enter the following test script into both UNIX shells using the first helpkey from the list. Append the script with -f &:
% sgihelp -b ConfTestHelp -k helpkey_name -f & |
Two SGI Help viewers should appear, one in English and one in the localized language.
Position the two viewers and shells as shown in Figure 8-3.
Study the layout of the information in each viewer to ensure that the viewers are at the same location within the English book and the localized book.
Repeat the test script for each helpkey in the list.
Open and display the text file ConfTestHelpkeys using jot or more. Reduce the size of the shell and move it to one side of your desktop.
Highlight and paste the first part of the test script into each shell, but use the first helpkey from the list:
% sgihelp -b ConfTestHelp -k helpkey_name |
If the localized viewer does not jump to the same location as the English viewer, or if a dialog box appears, make corrections in the Frame source.
Repeat the test script for each helpkey in the list.
To test the book, perform the following steps:
In both UNIX shells, enter
% confidence |
Two System Log viewers should appear, one in English and one in the localized language, each with an index listing in the appropriate language.
![]() | Note: An informational dialog box may appear. Press the OK button to continue. |
Pull down the Filter menu and ensure that all the items have checkmarks next to them. A series of messages should appear in each viewer.
Pull down the Help menu in both viewers and choose the item named Overview. Two SGI Help viewers should appear.
Position the four viewers as shown in Figure 8-5.
Study the layout of the information in each viewer to ensure that the viewers are at the same location within both books.
If there are any cross-references, click them in both viewers. Ensure that the localized version jumps to the same location as the English version.
If there are any cross-book links, glossary items, or URLs, click them in both viewers to ensure that they work.
Continue checking the remaining help entries to ensure that the localized version behaves the same as the English version.
If cross-references do not jump to the correct location or if other active links do not work as they should, make corrections in the Frame source and rebuild and reinstall the book.
Position the cursor over a button in the Confidence Tests English viewer and press the F1 key. Another help viewer should appear with information about that button. Repeat this for the localized viewer and verify that the same information appears in the help viewer.
Continue checking all the buttons and the menu bar as described in step 10.
Close the SGI Help viewers.
Pull down the Help menu in both System Log viewers and choose Index. Two new viewers should appear.
Click on the first index entry in each viewer. Two new SGI Help viewers should appear.
Study the layout of the information in each viewer to ensure that the viewers are at the same location in both books.
Continue checking the remaining index entries to ensure the localized version behaves the same as the English version.
If the localized index entry does not launch a viewer, if cross-references do not jump to the correct location, or if cross-links or other active links do not work as they should, make corrections to the FrameMaker source and rebuild and reinstall the book.
Part Number: | 008-3088-nnn | |
ShortTitle: | ||
Helpmap(s): | ||
Test Script: |
To extract and test helpkeys, perform the following steps:
Extract the helpkeys from the ConfTestHelp.helpmap. In the UNIX shell for the localized book, enter
% awk -F\; '$2 == "ConfTestErrors" { print $5;}' < /usr/share/help/BOOK_LANG variable/ConfTestHelp.helpmap > ~/ConfTestHelpkeys |
Open and display the text file ConfTestHelpkeys using jot or more. Reduce the size of the shell and move it to one side of your desktop.
Type the following test script into both UNIX shells using the first helpkey from the list. Append the script with -f &:
% sgihelp -b ConfTestErrors -k helpkey_name -f & |
Two SGI Help viewers should appear, one in English and one in the localized language.
Position the two viewers and shells as shown in Figure 8-3.
Study the layout of the information in each viewer to ensure that the viewers are at the same location within the English book and the localized book.
If the localized viewer does not jump to the same location as the English viewer, or if a dialog box appears, make corrections in the Frame source and rebuild and reinstall the book.
Repeat the test script for each helpkey in the list.