Chapter 8 Accessing Online Documentation

This chapter explains how to install and use the AnswerBook2 product to browse, search, and print online documentation. It includes the following information:

• "Introduction to AnswerBook2"

• "Where's the Documentation?"

• "Getting Started"

• "Installing Document Server Software"

Introduction to AnswerBook2

The AnswerBook2 product is Sun's online documentation system. It uses a web-browser interface that lets you view and print a variety of Solaris information, including SGML-based AnswerBook^TM collections, Display PostScript^TM AnswerBook collections, and man pages.

The AnswerBook2 product provides a robust search engine that lets you find information throughout the documentation library. You can install AnswerBook2 document collections on a centralized documentation server or locally.

Throughout the AnswerBook2 documentation, the term AnswerBook1 refers to the version of the AnswerBook product provided with pre-2.6 versions of the Solaris operating system.

Features and Functions

The AnswerBook2 product provides the following features and functions:

• Uses a web-browser-based interface so that you can view online documentation from any platform (running any operating system), provided that your web browser supports HTML 3.2

• Depending on your web browser's configuration, lets you copy information from AnswerBook2 documents and paste it into other locations, such as your command line

• Provides a robust search engine for finding words and word phrases throughout the documentation library

• Gives you the ability to print pages, chapters, and books directly from the AnswerBook2 interface

• Lets you view old and new AnswerBook documents using a single interface

• Lets you define a subset of document collections (a Personal Library) to be displayed when using a specific document server

• Uses a client-server architecture that allows the documents to be stored in a single location (server) and accessed from the user's desktop (client)

• Provides a command-line interface (CLI) and a browser-based interface (GUI) for performing administrative functions

Differences Between AnswerBook1 and AnswerBook2

The following list identifies the significant differences between the AnswerBook1 and AnswerBook2 products:

• Web-browser-based interface--The AnswerBook2 product uses a web-browser-based interface. As a result, you can use any HTML 3.2-compliant browser on any platform to view online documentation.

• Source flexibility--You can use the AnswerBook2 server to deliver AnswerBook1 (Display Postscript^TM) documents, AnswerBook2 documents (developed in SGML), or regular HTML files.

  ---

  Note -

  Although you can use the server to deliver HTML documents, complete AnswerBook2 functionality is not provided for these files.

  ---

• Client-server support--The AnswerBook2 product supports the client-server architecture, which allows you to install the server and document collections in a central location and view the documents from other systems. In addition, it includes a "fail-over" mechanism in which the document administrator can define multiple document servers so that links between documents always work.

• Cross-platform--For this release, the AnswerBook2 document server must run on a Solaris 2.6 platform (SPARC or Intel). However, AnswerBook2 clients can run on any platform, and future releases might provide server functionality on additional platforms.

• Default search behavior--The AnswerBook2 product uses AND for its default search behavior rather than OR (the default search behavior in the AnswerBook1 product).

Pieces and Parts

The AnswerBook2 product is relatively simple. It consists of the following elements:

• A web browser--The Solaris 2.6 product release includes the HotJava^TM browser; however, you can use any HTML 3.2-compliant browser to view Sun's online documentation.

  ---

  Note -

  If you just want to view online documentation, you only need this element. All other elements are part of the document server system.

  ---

• The AnswerBook2 application and utilities--Includes GUIs for document viewing and printing as well as administrative functions (you can also perform administrative functions from a command-line interface).

• A document and administration server--Performs query functions and "serves" documents to the application; also, performs database, password authentication, and other administrative functions.

• Documents--Can be new (SGML) documents or old (Display PostScript) documents.

Frequently-Asked Questions

This section lists some common questions about the AnswerBook2 product along with answers to those questions.

What is AnswerBook2?

The AnswerBook2 product uses a standards-based document server to deliver Sun's online documentation through your favorite web browser. The AnswerBook2 interface lets you browse, search, and print a variety of Solaris information, including AnswerBook1 collections and man pages.

How is AnswerBook2 different from AnswerBook?

The previous AnswerBook product (now called AnswerBook1) used Display PostScript to display electronic versions of documents primarily developed for paper delivery. The AnswerBook2 product uses a web browser to display documentation developed for online delivery using SGML and to display existing AnswerBook1 documents. Also, the AnswerBook2 product supports a client-server model, where the documents can be kept on a central server and users only need a web browser to view them.

Can I still view my old AnswerBook collections with AnswerBook2?

Yes, unless your old AnswerBook documents were created before the release of the Solaris 2.2 operating system. To add AnswerBook1 collections to the AnswerBook2 server's database, use the AnswerBook2 "add collection" function and point to the directory containing the AnswerBook1 ab_cardcatalog file.

Does AnswerBook2 provide the same functionality for AnswerBook1 and AnswerBook2 documents?

No. For consistency, the AnswerBook2 interface for AnswerBook1 documents is similar to the AnswerBook1 product interface. Thus, the AnswerBook2 product provides the following differences in functionality for AnswerBook1 and AnswerBook2 collections:

• You cannot expand or collapse an entire AnswerBook1 table of contents listing; you can only expand or collapse a specific section within the table of contents.

• AnswerBook1 content pages do not include Other Topics sections. To navigate from one page to another, you can use the Next Topic link or return to the Table of Contents and select another section in the book.

• AnswerBook1 content pages display the entire chapter at one time, not smaller sections.

• Search results are not presented in a hierarchical structure for AnswerBook1 books.

• Search results icons poorly represent the probability of a match for AnswerBook1 information; the icons tend to be either completely filled or completely empty.

• Search terms are not highlighted in AnswerBook1 text.

• Some AnswerBook1 graphics cannot be displayed inline; they are identified by an icon that, when clicked on, brings up a PostScript display of the graphic.

Where's the Documentation?

For the Solaris 2.6 operating system release, the document server software and document collections are on the Documentation CD. Figure 8-6 through Figure 8-4 list the specific document collections available and identify those documents that are available only in hardcopy (printed) format.

Figure 8-1 Desktop Documentation

Figure 8-2 Reference Documentation (Man Pages)

Figure 8-3 System Administration Documentation -- Part 1

Figure 8-4 System Administration Documentation -- Part 2

Figure 8-5 Developer Documentation -- Part 1

Figure 8-6 Developer Documentation -- Part 2

Getting Started

The AnswerBook2 product is a replacement for the existing AnswerBook product and is part of the Solaris 2.6 operating system release. To view online documentation, you need an HTML 3.2-compatible browser (such as HotJava^TM, Netscape Navigator^TM, or Lynx^TM) and access to a document server (a URL that identifies a machine on which the document collections are installed and which runs a web-based server to deliver them to you). For more information, choose from the following:

• "What Do I Need to Install?"

• "Launching the AnswerBook2 Viewer"

• "Finding a Document Server"

For detailed information about using the AnswerBook2 product or administering a document server, use the online help once you have a document server to access.

What Do I Need to Install?

Table 8-1 indicates what you need to install to provide specific AnswerBook2 functionality.

Launching the AnswerBook2 Viewer

If you are running the Solaris 2.6 operating system and you select the AnswerBook2 icon provided on the CDE front panel, select AnswerBook2 from the OpenWindows Programs menu, or enter the answerbook2 command, the system launches a web browser with the URL for the document server. It finds the web browser to launch by searching your path and launching HotJava or the first web browser it finds in your path. For information on how the system determines the URL for the document server, see "Finding a Document Server".

If you are not running the Solaris 2.6 operating system, you can also access the AnswerBook2 product from any HTML 3.2-compliant web browser. Start up your web browser and point it to the appropriate document server URL. For example, if your system administrator installed an AnswerBook2 document server on the system imayoyo, you would access the URL http://imayoyo:8888.

Finding a Document Server

If this is the first time you have started the AnswerBook2 viewer, the software displays a list of the complete library (all collections and their books) installed on the "default" document server. The "default" server is identified using one of the following mechanisms:

1. If you have defined the environment variable, AB2_DEFAULTSERVER, the AnswerBook2 viewer launches using the URL defined by that variable. For example, you might have the following line in your .cshrc file:

   setenv AB2_DEFAULTSERVER http://imayoyo.eng.sun.com:8888/

2. If the machine from which you initiated the AnswerBook2 function is a document server, the AnswerBook2 viewer launches using the URL: localhost:8888.

3. If you are using FNS (Federated Naming Services), the AnswerBook2 viewer launches using the document servers it finds under the FNS thisorgunit/answerbook/servers list. For more information about FNS, see "Registering the Server".

If you have no document servers available, you can also access Sun's master document server at http://docs.sun.com.

Installing Document Server Software

This section explains the requirements you must meet and decisions you should make before you install the AnswerBook2 server software.

There is no specific installation needed to be an AnswerBook2 client. Only the person who wants to serve documentation needs to read this section.

Be aware that there is no client-level access control for this product. If a client machine can access the URL for your document server, it can view the documents on that server.

This section contains the following information:

• "Before Installing Server Software"

• "Installing Server Software"

• "Registering the Server"

• "Name Services and AnswerBook2"

For detailed information about administering a document server, use the online help available from the AnswerBook2 interface once you have installed the document server software.

Before Installing Server Software

Before you start the installation process, verify that your system meets the requirements listed in "Hardware and Software Requirements" and decide where you want to install the software as explained in "Installation Choices".

Hardware and Software Requirements

Before you start the installation process, verify that the system(s) on which you plan to install AnswerBook2 server software meet the hardware and software requirements listed in Table 8-2 and Table 8-3.

In addition, you need to set aside some amount of disk space for the actual book files. The exact amount of space depends on the specific collections.

Installation Choices

Before you install the AnswerBook2 server software, you should consider your installation choices:

• Install Everything on One System

  The AnswerBook2 server software and documentation collections are on the Solaris 2.6 Documentation CD. If you install both parts of the server product on a single system, when you finish the installation process and start the server, it will be ready to serve documents to all clients. See "Installing Server Software" for more information.

• Install Server and Documentation on Separate Systems

  You can install the document server software on one system and point to document collections that are physically located on a different system. You might want to do this if you have minimal space available on your server's system or if you have existing collections location on another system. If you do this, you will need to manually add each collection to the server's database and the Scan for Locally Installed Collections function will not find these collections. See "Installing Server Software" for more information.

• Run from the CD

  If you are operating in a non-networked environment (stand-alone) or you only occassionally view the online documentation, you can run the AnswerBook2 server directly from the Solaris 2.6 Documentation CD. To run the server directly from the CD:

  1. Make sure you are logged in as root. % su -

  2. Change directory to, or bring up file manager and go to, the following location: /cdrom/Solaris_2.6_Doc/

     This directory contains three directories and one executable script (ab2_cd).

  3. Run the following command:./ab2_cd

  4. Access the document server using the following URL: http://localhost:8888

     where localhost is the name of the machine to which the CD is attached.

  5. To stop running the server from the CD, run the following command: /cdrom/Solaris_2.6_Doc/ab2_cd stop

  ---

  Caution -

  Be aware that running the document server directly from the CD is slow. Thus, it is not recommended that you use this approach if you expect other users to access this document server.

  ---

Installing Server Software

To install the AnswerBook2 server software, perform the following steps:

1. Insert the Solaris Documentation CD into your CD-ROM drive.

2. Log in as root on the document server machine and change directory to the location of the installation packages.

   For example, the path to the server software packages for a SPARC server might look like the following:

   # cd cdrom/Solaris_2.6_Doc/sparc/Product/

   where cdrom is the mount-point for the CD-ROM device.

3. Use the pkgadd utility or the swmtool utility and select the following server software packages:

   • SUNWab2r (0.02 Megabytes)--Installs in root partition and provides configuration and start-up files.

   • SUNWab2s (0.21 Megabytes)--Provides shared files for performing document processing.

   • SUNWab2u (21.02 Megabytes)--Provides executable and back-end processing files for server and administration functions.

   ---

   Note -

   To install the server packages into a non-default directory, use the following command: # pkgadd -d . -a none. This causes the pkgadd utility to prompt you for the directory into which you want the software installed.

   ---

4. Start up the server, if needed.

   Installing the packages should cause the server to start up on the default port of 8888. If it does not start, use the following command to start it:

   # /usr/lib/ab2/bin/ab2admin -o start

5. Install the book collections.

   Your document server cannot do its job if no documents are installed for it to serve. You can install collections from the Solaris 2.6 Documentation CD or from other locations, such as existing document collections or collections that come with other products. Table 8-4 lists the document collections available on the Solaris 2.6 Documentation CD.

   Table 8-4 Solaris 2.6 Documentation CD Book Packages

   Package Name	Collection Title
   SUNWabe	Solaris 2.6 User Collection
   SUNWAxg	Solaris XGL 3.3 AnswerBook
   SUNWAxi	Solaris XIL 1.3 AnswerBook
   SUNWapex	PEX AnswerBook
   SUNWaman	Reference Manual AnswerBook
   SUNWabsdk	Solaris 2.6 Software Developer Collection Vol 1
   SUNWaadm	Solaris 2.6 System Administrator Collection
   SUNWakcs	KCMS AnswerBook
   SUNWdtad	Solaris Common Desktop Environment Developer AnswerBook
   SUNWabdev	Solaris 2.6 Software Developer AnswerBook Vol 2

   1. Use the pkgadd utility or the swmtool utility to install new book collections onto your server.

      The document collection packages are located in the following directory on the Solaris 2.6 Documentation CD:

      # cd cdrom/Solaris_2.6_Doc/common/Product/

      If you install document collection packages from this CD, the collections are automatically added to the document server's database during the pkgadd process. If you install collection packages from any other location, you need to use either the Admin GUI's Add Collection to List function or the ab2admin -o add_coll command to add these collections to the document server's database.

   2. If collection packages are already installed on your system, you can use the server's Scan for Locally Installed Collections function or the ab2admin -o scan command to have them automatically found and added to the server's document database.

      This function only works for locally installed packages.

      To serve document collections located on some other system, use the Add Collection to List function or the ab2admin -o add_coll command and provide the full path name to the ab_cardcatalog or collinfo file. For example, if the document server is imayoyo and you want it to serve document collections located on the system elsewhere, you might use the following command: ab2admin -o add_coll -d /net/elsewhere/books/SUNWdtad

6. (Optional) Register the server.

   If you want other users to automatically find your document server through Federated Naming Services (FNS), you need to register the server. To register your server, use the following command:

   # /usr/lib/ab2/bin/ab2regsvr server_url

   where server_url is the fully qualified URL to get to this server (for example: imayoyo.eng.sun.com:8888). See "Registering the Server" for more information.

Registering the Server

To include your document server in a pool of servers for a site, or to give users the ability to choose from several document servers, you can register the name of your server with the Federated Naming Services system. Users can still access unregistered document servers if they know the URL.

To register your server, use the ab2regsvr command. The ab2regsvr command looks at your system's configuration and, depending on the naming service you are using, sets up the appropriate name space for your server.

To register your server, use the following command:

# /usr/lib/ab2/bin/ab2regsvr server_url

where server_url is the fully qualified URL to get to this server (for example: imayoyo.eng.sun.com:8888).

To find out what servers are currently registered, use the following command:

% fnlookup -v thisorgunit/service/answerbook2

This returns a list of registered servers that looks similar to the following:

Reference type: onc_answerbook2
Address type: onc_addr_answerbook2
  length: 19
  data: 0x68 0x74 0x74 0x70 0x3a 0x2f 0x2f 0x61 0x6e 0x73  http://ans
        0x77 0x65 0x72 0x73 0x3a 0x38 0x38 0x38 0x38       wers:8888

In this example, the registered server is answers:8888.

If you get a response similar to the following, then no document servers are registered.

Lookup of 'thisorgunit/service/answerbook2' failed: Name Not Found: 'answerbook2'

Name Services and AnswerBook2

In the Solaris environment, the primary name services are:

• NIS+ (Network Information Service Plus)

  NIS+ is the primary name service used for Solaris 2.6 and is a redesigned version of NIS that takes into account recent changes in client/server environments. NIS+ was introduced in the SunOS 5.0 (Solaris 2.0) release. If your system is using NIS+, you can run ab2regsvr on the document server system. It creates an entry like this: thisorgunit/service/answerbook2.

• NIS (Network Information Service)

  NIS was the standard name service provided in SunOS 4.x (Solaris 1.x) environments. If your system is using NIS, you must contact your NIS administrator and have that person run ab2regsvr on the NIS master system to set up the name space for AnswerBook2 servers.

• File System

  If a user chooses not to run either NIS or NIS+, the AnswerBook2 product also works with a file-system defined naming system in which all names are manually entered into data files. In this instance, these files would be stored in the directory /var/fn. The server would need to export this directory and any clients that wanted to access documents on this server would need to mount this directory.

Rather than using the described name services to find a document server, the user can define a default AnswerBook2 server using the environment variable AB2_DEFAULTSERVER. For example, the user could have the following line in the .cshrc file:

setenv AB2_DEFAULTSERVER http://imayoyo.eng.sun.com:8888

If the user has not defined an environment variable, when the user launches AnswerBook2 from the desktop, the system performs an fnlookup thisorgunit/service/answerbook2 command to find out what document servers are available. It then chooses one of those servers and launches the AnswerBook2 browser using that server name for the URL.