AnswerBook Compatibility Issues

• Backward compatibility of AnswerBook software: The current software that supports AnswerBook viewing (Solaris 2.X) can read all versions of AnswerBook packages, past and present, including those dating from Solaris 2.1.
• Compatibility of earlier AnswerBook viewing software: If you have AnswerBook software that was delivered prior to the Solaris 2.2 release, note that it cannot be used to view AnswerBook packages published later under Solaris 2.2, Solaris 2.3, or any later releases.

AnswerBook Start-up Software

---

Note - Any individual or customized AnswerBook start-up scripts created prior to Solaris 2.2 should be ignored in favor of the generic start-up script, answerbook(1), delivered with Solaris 2.2 and in subsequent releases.

---

• Re answerbook(1): The AnswerBook application is started by a single centralized command, answerbook(1) in /usr/openwin/bin, and delivered as part of the OpenWindows package.

• AnswerBook from the Workspace menu: For users who prefer a graphical user interface for starting applications, AnswerBook is included among the OpenWindows applications that are shipped with Solaris.
• Locally installed AnswerBook packages: Whether invoked by command line or by menu, the answerbook(1) start-up script automatically recognizes and configures any locally installed AnswerBook packages. From the administrator's point of view, no special procedure is necessary to enable use of AnswerBooks on a local system.
• Network setup of AnswerBook packages: If users need to share AnswerBooks on a network, administrative steps are required. All relevant procedures are discussed in Part 2 of this book, particularly in this chapter.

AnswerBook Administrative Software

• ab_admin(1): an administrative utility (executable). To support the AnswerBook user interface for users on a network, Solaris provides a utility called ab_admin(1) in /usr/openwin/bin for adding, removing, and verifying AnswerBook packages. These procedures are described in this chapter. For more background on the user interface, see "The User's View of the AnswerBook Library" on page 53.
• ab_cardcatalog(4): a database file. This file lists installed AnswerBook packages. The administrator maintains this database file using the ab_admin(1) utility. The ab_cardcatalog file is also referred to as the "card catalog" file.

---

Note - Beginning with Solaris 2.2, ab_cardcatalog(4)replaced the original bookinfo mechanism. Any old bookinfo files that may be on your network should be converted to card catalog files using ab_admin(1). (For details on the conversion process, see "Converting a bookinfo File (From Pre-Solaris 2.2)" on page 50). Also, with the release of Solaris 2.2, the old abmerge utility became obsolete. It has been replaced by the Library functionality of ab_admin(1)and ab_cardcatalog(4).

---

Strategies for Network Use of AnswerBook Documentation

AnswerBook packages installed on a network server for access by client systems require the creation of two administrative files: ab_cardcatalog and answerbook_setup. These files must be made accessible to all of the clients that will use the installed AnswerBook documentation.

This section introduces background information on these administrative files and strategies.

About the Master Card Catalog on the Server Side

You must set up a master ab_cardcatalog(4) file that lists all available AnswerBook packages and the configuration information for each one. This file must contain all of the information from every AnswerBook card catalog and bookinfo files (if any), modified to specify network-compatible file path names. This file must be updated whenever an AnswerBook package is added or removed from the network.

For this procedure, see "Setting Up an AnswerBook Package on a Network" on page 42.

About AnswerBook Setup on the Client Side

To facilitate setup of each client on the network, create an answerbook_setup script to point to this master ab_cardcatalog file. When answerbook is started on each client system, the setup script will run, provided it is in each user's path. The script sets the environment variable $AB_CARDCATALOG, which will point to the master ab_cardcatalog(4) file.

See "Setting Up an AnswerBook Package on a Network" on page 42.

What Happens at AnswerBook Start-up

When the user starts AnswerBook on the desktop, the AnswerBook Navigator consults the following:

• $AB_CARDCATALOG (an environment variable that points to one or more card catalog files of available AnswerBook packages)
• The user's own card catalog (~/.ab_cardcatalog)
• The pkginfo(1) database (to find locally installed AnswerBooks)

See "AnswerBook Software Flow Chart" on page 56 for a diagram of this chain of events at answerbook(1) start-up.

Options for the Administrator

To enable all users on a network to browse the same set of AnswerBook titles, you can take either one of the following approaches:

• Server side: You can create a network-wide master card catalog and have all users share it via the environment variable $AB_CARDCATALOG.
• Client side: You can update all users' personal card catalogs (~/.ab_cardcatalog) to reflect network-wide AnswerBook titles.

---

Note - In the rest of this chapter, the notation <ABHOME> represents the path name where an AnswerBook configuration file is installed, such as:

/opt/SUNWaadmin

The first part of the path name is the parent directory (typically /opt), which is defined by the administrator at installation time. The second element is the name of the AnswerBook package being installed and configured for users.

---

For more background information on these topics, see Appendix A, "Concepts of AnswerBook Administration."

Background on AnswerBook Packages Installed Locally

What the Administrator Does

What the Software Does

->

When you install the AnswerBook on a local, standalone system...

The install software copies the AnswerBook to <ABHOME> and creates its card catalog file in <ABHOME>/ab_cardcatalog.

When the user starts Answerbook...

->The answerbook(1) script checks for Answer-Book packages installed on the local system. It also creates an environment variable called $AB_CARDCATALOG. For each AnswerBook pack-age it finds, it appends that package's card catalog file name to $AB_CARDCATALOG. The answerbook(1) script does not find AnswerBook packages that have not been installed using pkgadd(1M) or swmtool(1M). You must convert these manually, using the ab_admin(1) utility with the -convert option. See the ab_admin(1)man page for details. See also "AnswerBook Software Flow Chart" on page 56.

Setting Up an AnswerBook Package on a Network

What the Administrator Does

What the Software Does

->

(1)Install the AnswerBook on the network server. Follow the instructions in Chapter 2, "Answer-Book Package Installation."

The install software copies the AnswerBook to <ABHOME> and creates its card catalog file in <ABHOME>/ab_cardcatalog. Note - If the system has a pre-Solaris 2.2 AnswerBook installed, the bookinfo file for that AnswerBook is typically copied to <ABHOME>/bookinfo.

(2)Decide where to locate the network-wide master card catalog file and note it here. __________________________________________ For example: /net/thor/export/ab_cardcatalog

->The partition where the file resides must be exported. For this example, autofs is used and the card cat-alog is located in /export on the server thor. /net/thor/export/ab_cardcatalog

(3)Use ab_admin to create/update the master card catalog with the entry for the new AnswerBook. #To include older AnswerBooks, type: #

->ab_admin(1) adds the information for the An-swerBook package to the master card catalog. <ABHOME>/ab_cardcatalog <ABHOME>/bookinfo

ab_admin -file /net/thor/export/ab_cardcatalog -merge

ab_admin -file /net/thor/export/ab_cardcatalog -convert

(4)

->The share(1M) command makes the AnswerBook partition network-accessible.

Make the AnswerBook partition available to the network. Edit the /etc/dfs/sharetab file on the server to include the share(1M) command. For instruc- tions, see "How to Set Up Access to a Remote CD- ROM Drive" on page 21. For more detailed infor- mation, see File System Administration.

What the Administrator Does

What the Software Does

(5)Use two ab_admin command options to find the locations of AnswerBook components. # ab_admin -file <ABHOME>/ab_cardcatalog \ -list SUNWab_2_6 Use the resulting package ID (in this example, SUNWab_2_6) as input to the next command. Here <ABHOME> is assumed to be /opt. # ab_admin id=SUNWab_2_6 title=System AnswerBook tocpath=/opt/Sys_AB/toc pspath=/opt/Sys_AB/ps indexpath=/opt/Sys_AB/index

->The -list option lists the id and version numbers of the AnswerBooks. The -match option finds the paths to the AnswerBook components so you can check to be sure they are network-accessible. This example shows a locally installed Answer-Book package called System AnswerBook on a server called thor. -match SUNWab_2_6

-file /net/thor/export/ab_cardcatalog

(6)

If necessary, modify the paths (/net/server) so that the AnswerBook package can be accessed from other systems on the network via the automounter. # ab_admin -file /net/thor tocpath=/net/thor/opt/Sys_AB/toc \ pspath=/net/thor/opt/Sys_AB/ps \ indexpath=/net/thor/opt/Sys_AB/index

The -modify option enables you to adjust the paths to make them network-accessible from client systems. This example uses the server thor accessed by the automounter. (See NFS Administration Guide for more informa- tion.)

/export/ab_cardcatalog -modify SUNWab_2_6 \

->

What the Administrator Does

What the Software Does

(7)Repeat steps 1-6 for every AnswerBook package you add.

->The network-wide master ab_cardcatalog file accumulates the AnswerBook information.

(8)Create a script called answerbook_setup in a directory common to users' search paths, and have it contain the $AB_CARDCATALOG setting. Korn shell: # !/usr/bin/ksh AB_CARDCATALOG=/net/hostname1/export/\ ab_cardcatalog:${AB_CARDCATALOG} Bourne shell: Same as above, but substitute # !/usr/bin/sh and add export AB_CARDCATALOG Make the answerbook_setup file executable: # chmod 755 answerbook_setup Be sure each user's search path can find the answerbook_setup file. To check this, type: # which answerbook_setup

->The answerbook(1) start-up script looks for the answerbook_setup script in the user's search path and sources it, thus gaining a pointer to the network master ab_cardcatalog(4). This is an efficient way of setting up the shared card catalog for users.

(9)Start the Answerbook application. See "Verifying AnswerBook Installation" on page 35.

->The answerbook(1) script checks for Answer-Book packages on the local system. (See "Back-ground on AnswerBook Packages Installed Locally" on page 41). The answerbook(1) script looks for an executable shell script named answerbook_setup in the user's search path, and sources it, thus finding the network master ab_cardcatalog(4). The answerbook(1) script invokes the Answer-Book Navigator. See "AnswerBook Software Flow Chart" on page 56.

AnswerBook Q & A and Troubleshooting Tips

For help with diagnosing AnswerBook configuration problems, see:

• "AnswerBook Administrative Software" on page 38
• "Strategies for Network Use of AnswerBook Documentation" on page 39
• "Setting Up an AnswerBook Package on a Network" on page 42
• "AnswerBook Software Flow Chart" on page 56

AnswerBook Display on Remote Systems and X Terminals

AnswerBook pages are rendered using the Display PostScript^(TM) system from Adobe^(TM) Systems, and can be displayed remotely on any Solaris system that is running the Display PostScript system. This is because appropriate fonts and software are installed by default with the Display PostScript system.

In addition, AnswerBook sets may be displayed remotely on other X-based systems provided that both the following are true:

• The remote X-based system supports the Display PostScript extension to X or supports Adobe Display PostScript NX software's remote display capabilities.
• A complete LWII Type1 font set has been installed on the remote system or appropriate host.

For additional information about the Display PostScript system, send email with your name, company, address, and phone number to:

dps-info@adobe.com

---

Note - AnswerBook sets can also be displayed on remote systems that are running NeWS.

---

If Users Can't Find Installed AnswerBook Titles

If you have installed and configured AnswerBook titles according to the instructions in this book, but users still cannot see the titles in the Navigator Contents list, have users bring up the Modify Library window from the Navigator and select available AnswerBook titles from the scrolling list.

If you have installed AnswerBook packages on the network, but users don't see their titles in the Modify Library scrolling list, you have not yet included the AnswerBooks in the network-wide card catalog using ab_admin(1). See "Setting Up an AnswerBook Package on a Network" on page 42.

If Users Can't Find Pre-Solaris 2.2 AnswerBook Titles

Beginning with Solaris 2.2, the card catalog mechanism explained in this chapter replaced the original bookinfo mechanism. Any old bookinfo files associated with your pre-Solaris 2.2 AnswerBook titles should be converted to card catalog files using ab_admin(1). See "Converting a bookinfo File (From Pre-Solaris 2.2)" on page 50.

Trouble Reading New AnswerBooks on a Pre-Solaris 2.2 System

Unfortunately, newer AnswerBook formats are not readable by systems running Solaris 2.1 or earlier.

What About Merging AnswerBook Sets?

The ab_admin(1) utility and the card catalog mechanism replace the bookinfo file and the abmerge utility from a previous release. Note that although merged AnswerBook sets no longer function according to the old abmerge utility, users can still use the AnswerBook titles individually, and each of them can be converted using the ab_admin(1) utility. See "Converting a bookinfo File (From Pre-Solaris 2.2)" on page 50.

If Users Can't Find Their Older Bookmarks

Bookmarks that users have created in AnswerBook titles that predate Solaris 2.2 are not compatible with the current AnswerBook Navigator.

If Users Can't Print Successfully From the Viewer

The number of pages that can be printed from AnswerBook per user request varies with the capacity of the printer. If users are having trouble printing large print jobs from the AnswerBook Viewer, the only way around this problem is to print section by section.

Before Running AnswerBook Software on a Standalone

To ensure successfully running the AnswerBook Viewer on a standalone Solaris system, do either one of the following steps:

*In a Shell Tool, type xhost + before starting AnswerBook.

* Start OpenWindows with the -noauth flag--

% openwin -noauth

--and then start AnswerBook as usual.

Trouble Accessing AnswerBook Titles From the Navigator

Assuming you have created an answerbook_setup script (see page 44), use this verification procedure:

1. Verify that the answerbook_setup script is in the user's search path.

% which answerbook_setup
/net/hostname/export/answerbook_setup

2. Verify that the answerbook_setup script is readable and executable by all.

% ls -l /net/hostname/export/answerbook_setup
-rwxr-xr-x 1 root other ... /net/hostname/export/answerbook_setup

3. Verify the contents of answerbook_setup.

   Do this either by visual inspection or by typing:

% /bin/ksh
$ . answerbook_setup
$ echo $AB_CARDCATALOG
:/net/hostname/export/ab_cardcatalog

Trouble Accessing an AnswerBook Document

If, when using the Navigator, you receive messages such as:

Can't add AnswerBook '<bs=SUNWab_2_4;vr=>'
invalid AnswerBook: <bs=SUNWab_2_4;vr=>
Can't view document. View Document failed
Can't start new Viewer. Error executing link

Verify that the tocpath, indexpath, and pspath variables in the ab_cardcatalog file for that AnswerBook are correct, and that the directory paths they specify are readable by using the -verify option of ab_admin(1). For example:

# ab_admin -file /net/thor/export/ab_cardcatalog -verify SUNWab_2_6
Invalid index path for 'SUNWab_2_6': \
 '/net/hostname/ot/Sys_AB/index'

You can see in this example that a directory name in the path has been misspelled (ot should have been opt).

Environment Variables Essential to AnswerBook Administration

Be sure these user environment variables are set as shown here to support shared access to AnswerBook packages on the network.

PATH=/usr/openwin/bin:${PATH}
OPENWINHOME=/usr/openwin
LD_LIBRARY_PATH=/usr/openwin/lib
AB_CARDCATALOG=[location of master card catalog]
DISPLAY=hostname:0.0

The DISPLAY setting is helpful when displaying AnswerBook packages on a remote system, for example, a Solaris 4.x machine.

Problem with Adding and Removing Packages

There is a known problem with adding or removing some packages developed prior to Solaris 2.4. If adding or removing the package fails during user interaction, or if you are prompted for user interaction and your responses are ignored, set the following environment variable:

NONABI_SCRIPT=TRUE

Examples for AnswerBook Administrators

The following examples illustrate procedures for administering AnswerBooks on a local system and across the network.

These examples assume the administrator has set up two relevant card catalog files:

• One in the user's home directory (~/.ab_cardcatalog) that contains an entry for one AnswerBook package
• A network-wide master card catalog file with entries for two other AnswerBook packages

(It is not necessary to set up both client and server side card catalogs, but this scenario is used for the sake of the examples, which illustrate both the client and server side of administration.) These examples also assume there are several AnswerBook packages installed on the local system.

In all of these examples, the $AB_CARDCATALOG environment variable points to the shared network-wide master card catalog file.

For more information, see ab_admin(1).

Listing Card Catalogs and AnswerBook Packages

To list card catalogs and packages in the current environment:

Listing a Catalog Entry for an AnswerBook Package

To list the AnswerBook package ID, title, and paths from the card catalog file, do this:

Verifying Card Catalog Entries

To verify AnswerBook packages in the card catalog, do this:

Combining Card Catalog Files

To combine listings from two card catalog files, do this:

Converting a bookinfo File (From Pre-Solaris 2.2)

To convert an older bookinfo file to card-catalog format, do this:

Modifying Paths in a Catalog Entry

To make the paths in a card-catalog entry accessible to other systems on the network, pre-pend /net/<servername> to each path:

Removing a Catalog Entry

To remove a catalog entry for an AnswerBook package (in this example, SUNWab_2_6), do this:

Listing Local AnswerBook Packages

To list packages on a local system, do this:

Finding a Card Catalog

To find the card catalog file of a local AnswerBook package, do this:

Getting the ID of an AnswerBook Package

To find the package ID of an AnswerBook package, do this: