Chapter 7. Testing Online Books

This chapter describes how to install and test an online book and includes the following sections:

See Chapter 8, “Testing Help Books,” for information on installing and testing help books.

Viewing and Testing an Uninstalled Book

Some localized documents, such as French, German, and Spanish non-help books, can be opened and tested in IRIS InSight from the workareas in which they have been built. Japanese non-help books can be opened and tested from a test machine as long as the test machine has the Japanese environment and kanji fonts installed on it. These books do not have to be “installed” in order for quality assurance testing to ensue. Other books must be installed on a test machine running the same operating system for which the books are intended before quality assurance testing can begin.

Setting Your Environment for Japanese

For Japanese books, your environment must have its LANG set to ja_JP.EUC. To test what LANG variable is set, enter

% env | grep LANG 

To set the LANG variable for Japanese, enter

% setenv LANG ja_JP.EUC

Viewing a Book in Your Workarea

Use the following command to display a book with IRIS InSight during the book development process. This command assumes that your local working directory is the current directory:

% iiv -b . 

In the previous entry, the argument to the iiv command (-b .) directs IRIS InSight to open the book in the current directory. You can also specify other pathnames (including relative pathnames) in an iiv command to open books in different directories. However, any directory that you specify must contain a local books directory that was created by a successful book build.

For example, the following command opens a book from the user's home directory:

% iiv -b ~/books/1000/007-1761-010

To view an uninstalled book on a different workstation, use a remote login to the workstation (% rlogin hostname).

Testing a Book in Your Workarea

Scroll through the online book carefully. Here are a few things to review:

  • Do the links work? Do they take you to the right places? If you find a broken cross-reference, check to make sure it's correctly formatted in the FrameMaker file (see “Creating Online Links” for instructions).

  • Are the Table of Contents, List of Figures, List of Tables, and Index correctly formatted? If not, try deleting those files and replacing them with the appropriate template files from the IRIS InSight Professional Publisher template.

  • Do all figures appear in the online text? If not, make sure that you set them up correctly (according to the instructions in “Working With Figures”). If figures do appear, do they display correctly?

Installing a Localized Book for Testing

To install a book on a test machine:

  1. Log in to the test machine:

    % rlogin name@machine_name 

  2. Change directories to the workarea where the book files are located:

    % cd /.../books/1000/007-1366-100JP 

  3. Become superuser (root) and install the book using the installtestbooks script:

    % su 
    # set filec 
    # /path/to/the/script/installtestbooks real 

  4. If the book is already installed on the test machine, the script will ask you to confirm information. Type N and press Enter.

    PerSysAdmin already exists on the /usr/share/Insight/library/ja_JP.EUC_bookshelves/SGI_EndUser_Japanese bookshelf.
    You should use “versions remove” to remove PerSysAdmin to avoid any potential conflicts.
    Do you want to exit now and do a “versions remove” (Y/N)? N 

  5. At the next prompt, exit the test machine:

    # exit 

This completes the installation of the localized book.

Preparing for Comparative Testing

Prior to testing the localized book, its English equivalent must be built and installed on a test machine or be viewable in your workarea.

  1. Build the book:

    % make book.full 

  2. Check the .full file to make sure there are no errors or unresolved cross references:

    % more *.full 

  3. Launch IRIS InSight:

    % iiv -f . 

    The -f argument runs IRIS InSight in the foreground.

  4. Click on the book and position its viewer on the left side of your desktop. Set up the viewer so the Table of Contents is at the top:

    Choose Options > Settings... and deselect Side-by-Side View of Books?

  5. Log in to the test machine where the localized book has been installed:

    % rlogin guest@machine_name 

  6. Set the environment for the language of the localized book:


    % setenv LANG ja.JP.EUC


    % setenv LANG fr


    % setenv LANG dr


    % setenv LANG es

    Note: French, German, and Spanish help books cannot be tested against their English equivalents from the same test machine.

  7. Launch IRIS InSight:

    % iiv -f . 

  8. Click on the book and position its viewer on right side of your desktop (side-by-side with the English version). Set up the viewer so the Table of Contents is at the top:

    Choose Options > Settings... and deselect Side-by-Side View of Books?

Testing an Installed Book

Viewing the installed image shows the final form of the online book as it will appear to the intended audience. An installed book also allows for a complete quality assurance test of external book links as well as all the “launchables and linkables” a book may contain.

Note: Before using this procedure, be sure that your workstation contains the disk space that the book requires. If you are viewing Help material, follow the instructions in Chapter 8, “Testing Help Books,” for installation and test procedures.

Testing Localized Books

Localized books should have the same functionality and overall layout (bulleted lists, numbered lists, number of paragraphs, and so on) as their English equivalents.

  1. Study the layout of the information in each viewer to ensure that the viewers are at the same location within both books.

  2. Test the links from the Table of Contents, List of Figures, List of Tables, and List of Examples (if applicable). Ensure that the localized version “jumps” to the same location as the English version.

  3. 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.

  4. If there are any cross-book links, glossary items, or URLs, click them in both viewers to ensure they work.

  5. Ensure there are the same number of paragraphs, numbered list items, bulleted items, and so on in the localized book as there are in the English book.

    Note: German books tend to have about twenty percent more text than their English equivalent, although the number of paragraphs should still track with the English book.

  6. If cross-references do not jump to the correct location, or if other active links do not work as they should, or if anything seems to be missing, make the necessary corrections in the FrameMaker source and rebuild and reinstall the book.