Installation Guide

Using the Documentation Library Service

The Documentation Library Service allows you to navigate, read, and search registered HTML-formatted documents through your Web browser. The library service presents documents in a expandable-tree format, through which you can easily navigate by clicking on associated buttons. You can click to view a selected document. You can also search for specific information in one book, a selection of books, or the entire installed library.

The library service produces two types of Graphical User Interfaces (GUIs), a global GUI and an application GUI. The global GUI shows you all HTML documents on the document server that are registered with the global GUI. Global views may contain documents from many different applications. Access the global library application by typing docsearch on the command line or by clicking the Documentation Library icon in the Help subpanel under the CDE Desktop front panel.

The application GUI is launched when you click on a link inside a menu or document of an application. The resulting display shows library pages that contain online information for that application. For example, the Search link in the Web-based System Manager Help menu calls a library page that only displays the documentation for Web-based System Manager.

The components of the Documentation Library Service are installed along with the BOS (Base Operating System). After installation, the service may need to be configured.

Note: If you ordered a preinstalled system from the factory, the complete library service might have already been installed and configured at the factory.

If you are not sure whether the Documentation Library Service is installed and configured on your system, go to Testing the Documentation Library Service.

If you need to install or configure the library service, go to Configuring the Documentation Library Service.

Testing the Documentation Library Service

If you are not sure whether the library service is installed and configured, type docsearch on the command line.

One of the following occurs:

The library service appears, without error messages, and the search form appears at the top of the page. This search form contains one or more fields for entering words that you want to search for. A listing of documents is visible in at least one of the views. When you open a document, you can read its contents. The search function completes successfully.
- The library service appears functional but you cannot read the documents properly. Go to Configuring the Documentation Library Service.
- The library service appears functional but the search fails. Go to Problem Determination in the AIX 5L Version 5.1 System Management Concepts: Operating System and Devices.
You see the message There are no documents installed for this view. The library service might be installed correctly, but the service cannot find any installed documents that are registered for the current view. Try clicking on the other views to see if they contain documents. When you find a view with documents, try reading and searching the documents.
You cannot fully test the library service until all appropriate documentation has been installed and registered. The operating system and all applications that use the library service register themselves during document installation. To install the operating system online documentation, see Installing the Online Documentation. Ensure any application documentation is correctly installed. After you have done this, retest the library functions.
You see the message Search is not enabled. The service has not been fully installed and configured. Go to Configuring the Documentation Library Service.
You see the message Search is not supported in this language. The search engine cannot support searches in the language used by this installation of the operating system. This is not an error. The search function is not compatible with all languages supported by the operating system. This message always displays when you are using a language that the search function cannot support.
If documents are visible in one of the Views, try reading the documents. If your documents display correctly and you can open them for reading, then no further configuration of the library service is necessary. If no documents are available in any view, the documentation has not been installed and registered. The operating system and all applications that use the library service register themselves during document installation. To install the operating system online documentation, see Installing the Online Documentation. Ensure any application documentation is correctly installed. After you have done this, retest the library functions.
You see a message similar to Cannot find or execute ds_form. The exact wording of this message varies, but it means the library service is not installed and configured correctly. Go to Configuring the Documentation Library Service.
No browser appears. The library service is not installed and configured correctly. Go to Configuring the Documentation Library Service.

Configuring the Documentation Library Service

You can set up a machine either as a documentation server or as a documentation client system. When users on a client request a search form or an HTML document, the request is sent to the Web server on a documentation server, which then sends back the requested object. When searches are performed, they are done on the server and the results are then sent back to the user on the client.

A documentation server has the following software installed:

Documentation library service server and client software
Library service search engine
Documents
Document search indexes - for searchable documents. If an application package is using the library service, these indexes are installed automatically when the documents are installed, or the system administrator may manually create indexes for locally written documents. Documents written in certain languages cannot be searched and do not have indexes.
Web server software

A client needs only the Documentation Library Service client software and a Web browser installed.

If you have a standalone machine, both the server and client software are installed. Instead of going to a remote server, requests from users on a standalone machine go to the Web server software on that same computer. A documentation server on a network can also be made standalone in the sense that you can configure its Web server software to accept only requests from users logged in to the documentation server.

If you have a console that supports a graphical user interface and are running in the X-Windows System, you can use the Configuration Assistant to install and configure the library service. Otherwise, you can use commands to install and configure manually. It is highly recommended that you use the Configuration Assistant because it automatically performs some steps for you and is easier to use.

To use the Configuration Assistant, see Using Configuration Assistant for the Documentation Library Service.

To use the manual method, see Manually Installing and Configuring the Documentation Library Service.

Using Configuration Assistant for the Documentation Library Service

The Configuration Assistant helps you configure this system as a documentation server or as a client that gets its documents from a remote documentation server.

Note: HTTP Web server software must be installed on this computer before you can install documents and register them with the Documentation Library Service. The Configuration Assistant can automatically install the Lite NetQuestion Web server software or the IBM HTTP Server software. Both options are shipped with the operating system.
If you want to use different Web server software, that software must have been installed and configured before you launch the Configuration Assistant. You must also know the full pathnames of the Web server's HTML documents home directory and the CGI-BIN directory.
This machine does not need Web server software if you are configuring it as a client that obtains its documents from a remote documentation server.

To launch the Configuration Assistant, make sure you are logged in to the system as the root user, and enter the configassist command

When the Configuration Assistant opens, press the Next button. Then select Configure Online Documentation and Search. The Configuration Assistant guides you through installation and configuration.

After you have finished, use the same procedure as shown in 3 to add language support.

Manually Installing and Configuring the Documentation Library Service

This section describes how to install and configure the Documentation Library Service using the system management tools.

The following sections describe the procedures for Installing the Server and Installing the Client.

Installing the Server

Use this procedure if you want to configure this machine as a documentation server, where you will install your online documentation. A server can be networked to serve remote clients, or it can be standalone to serve only its own users.

To create a documentation search server, complete the following steps:

Install the Web server and browser software, if needed.
Web server software must be installed. You can use any Web server software that can run CGI (Common Gateway Interface) programs. The Lite NetQuestion Web server is automatically installed with the base operating system, but it can serve only local users, not remote users.
To serve both local and remote users, the IBM HTTP Server software can be installed from a CD shipped with AIX 5.1. Or, if you prefer, you can install a different Web server.
To verify what is already installed, type smit list_installed on the command line.
A Web browser that can display forms must be installed. (The Netscape browser is on the AIX 5.1 Netscape Products CD.)
Configure and start Web server software.
Unless you are using the automatically installed Lite NetQuestion server, you must configure your Web server software to perform correctly with your system. Consult the documentation that came with your Web server software to configure and start your Web server software. Write down the full path names of the Web server directories where the server starts looking for HTML documents and CGI programs. If you are using one of the following Web servers, and you installed to the default location, you do not need to know the directory name:
- IBM HTTP Server
- IBM Internet Connection Server
Other Web servers might not automatically create the HTML and CGI directories. If yours does not, you must create these directories before you continue.
You must also configure your Web server software's permissions to allow access from the users and remote computers who should use this computer as their documentation search server.
Configure the Documentation Library Service for additional languages, if needed.
You might want this documentation server to be able to serve documents that are written in a different language than the one used by the operating system installed on this machine. If this is the case, you must install additional language support filesets for the other languages you want to serve.
For example, assume that you are using English when you are installing the base operating system and you want users to be able to access documents in both English and Spanish from the documentation server. The English messages will be automatically installed because that is the language in use during the operating system installation. So, you only need to manually install the Spanish language support package.
There are two ways to install the library service package for another language:
- After you install the base operating system and the Documentation Library Service, you can install the operating system locale (language environment) for the language you want to add. Installing a language's locale installs the available support for all applications that are currently installed on your system.
  To install or update an entire locale, type smit mle_add_lang on the command line. Use the online help if you need additional explanation.
- If the locale for the desired language has been installed before the bos.docsearch package was installed, you can install only the Documentation Library Service messages.
To install library service messages using Web-based System Manager:
1. Start the Web-based System Manager by typing wsm on the command line.
2. Expand the machine name.
3. Expand System Environment in the Navigation area.
4. Select Settings.
5. Select Cultural then Available Resources.
6. When the dialog appears, use either the pull-down menu or select Add and install the language.
  Always install the Common messages. If you have the desktop installed on your system, also install the CDE messages. For example, assume that your server is configured for English when you are installing and you want to be able to serve both English and Spanish documents from the documentation server. The English messages are automatically installed. Therefore, you only need to manually select Spanish.
  The message filesets are not inside the docsearch package; instead, they are stored in the BOS messages packages (bos.msg.locale, where locale=desired language) and are named:
  - bos.msg.locale.docsearch.client.com DocSearch CDE Action - locale
  - bos.msg.locale.docsearch.client.Dt DocSearch Common Messages - locale
7. After you have added all of the filesets you want to install into the window, click on the OK button.
8. A message dialog displays, showing the status of the installation. If the process completes with no problems, a Success message displays.
To install library service support using SMIT:
1. From the command line, type smit install_all.
2. Always install the Common messages. If you have the desktop installed on your system, also install the CDE messages. For example, assume that your server is configured for English when you are installing and you want to be able to serve both English and Spanish documents from the documentation server. The English messages are automatically installed. Therefore, you only need to manually select Spanish.
  The message filesets are not inside the bos.docsearch package; they are stored in the BOS messages packages (bos.msg.locale, where locale is the desired language) and are named:
  - bos.msg.locale.docsearch.client.com DocSearch CDE Action - locale
  - bos.msg.locale.docsearch.client.Dt DocSearch Common Messages - locale
  In the dialog box that displays, type in the location of the filesets you want to install in the INPUT device / directory for software field, or click on the List button for a list of the available devices and directories.
3. When the next dialog displays, enter the fileset names you want to install. If you want to install more than one fileset at this time, separate each fileset name with a space. If you do not know the exact name of the fileset you want to install, or want to browse the available languages, click on the List button. Highlight the packages you want to install from the list.
4. Click on OK.
Configure the Documentation Library Service.
To configure the Documentation Library Service using Web-based System Manager:
1. As root user, start the Web-based System Manager by typing wsm on the command line.
2. Expand the machine name.
3. Expand System Environment in the Navigation area.
4. From the System Environment menu, choose Settings --> Documentation Server.
5. In the Browser command field, type the name of the command that launches the Web browser with a URL. This selection will be the default Web browser for all users of this computer.
  - If you are using the Netscape browswer, type netscape in the Browser field and continue with the next step.
  - If you are using another browser, you must include any necessary flags that include a URL in the launch command. For example, if launching your Web browser to a specific site requires a -u flag, and your launch command looks similar to the following:
```
YourWebBrowser -u http://www.w3.org
```
    Your entry in the Browser field would be:
```
YourWebBrowser -u
```
    You do not include the URL itself in the Browser field entry.
    
    Note: Many browsers (for example, Netscape) do not require a flag.
6. Click OK.
7. Select Settings --> Documentation Server again.
8. Select Local server.
9. Under the Location of document and CGI programs on local server, select your Web server software. If the name of your Web server software is not listed, select Other, then type the full path names of the CGI directory and the Documents directory. If you selected your Web server from the listing, continue with the next step.
  
  Note: If you installed any of the listed Web servers in any location other than the default, or if you have set up servers to use nonstandard locations for their CGI-BIN and HTML directories, you must select Other.
10. In the Server port field, type in the port number that the Web server software is using. The standard port is 80. If you are not certain of the actual port number, set it to 80. If you are using the Lite NetQuestion Web server, the port number must be set to 49213.
11. Optionally, you can change the Default Documentation Language from this same screen. This is the language users see when they launch the library using the docsearch command or the library icon in the Help subpanel of the CDE desktop front panel.
12. Click OK to complete the configuration.
To configure the Documentation Library Service using SMIT:
1. On the server, change to root user. On a command line, type smit web_configure.
2. Select Change/Show Default Browser. In the *Default browser LAUNCH COMMAND field, type the command that sets the default browser for all users on this computer. Include any flags that are required when a URL is included in the command. If you want to have the default browser to open to a specific URL, also add the URL after the command to open the browser. For example, if you want your browser to open with the www.ibm.com/servers/aix/library page, type the following in the *Default browser LAUNCH COMMAND field:
```
YourWebBrowser flag http://www.ibm.com/servers/aix/library
```
  Note: Many browsers (for example, Netscape) do not require a flag.
3. Return to the Web configuration main menu. Select Change Documentation and Search Server.
4. On the Documentation Search Server LOCATION screen, click on List and select local - this computer for server location. Click OK.
5. On the Web Server SOFTWARE screen, click on List and select the Web server software that you are using.
  
  Note: If you installed any of the listed Web servers in any location other than the default, or if you have set up servers to use nonstandard locations for their CGI-BIN and HTML directories, you must select Other.
6. On the next screen, type in the full path names of the CGI directory and the Documents directory. If you selected a listed Web server that is installed in its default location, the correct path names should be already displayed.
  If you set up your Web server to use a port other than the standard port 80, enter that port number. Leave it set to 80 if you are not sure of the port number. If you are using Lite NetQuestion, the port number must be set to 49213.
7. Click OK. When the configuration is completed, a Documentation server configuration completed! message displays in the results panel.
8. Optionally, you can change the Default Documentation Language from this same screen. This is the language users see when they launch the library using the docsearch command or the library icon in the Help subpanel of the CDE desktop front panel.
9. Click OK to complete the configuration.
The documentation search functions on this server should now be ready to use. Any users logged in to this system before configuration finished must log off and then log back in to use the search functions.
Install/register your documentation.
Before any document can be searched using the Documentation Library Service, it must have an existing index that is registered with the library service. Some applications, such as Web-based System Manager, ship prebuilt documents inside their install package. When the application is installed, the indexes are automatically registered. Indexes for all operating system documentation are registered during installation.
You can create indexes for your own HTML documents and register them with the library service so they can be searched online. For information about creating and registering indexes, see AIX 5L Version 5.1 General Programming Concepts: Writing and Debugging Programs.

Installing the Client

Use this procedure if you want to set up a client of a remote documentation library server. When users on this computer want to read or search online documentation, the request is sent to a remote documentation library server, where the request is handled and the results then sent back to a Web browser on this client.

Note: The search function is not supported in all languages.

To create a documentation library client, complete the following steps:

Install the client software.
First, check the list of software that is installed on your system by typing smit list_installed on the command line. If the following software is not already installed on your client system, install it now:
- A Web browser that can display HTML forms. (The Netscape browser is on the base operating system Netscape Products CD.)
- The Documentation Library Service package (bos.docsearch). This package is installed by default with the base operating system. If it has been removed from your system, you only need to install the following filesets of the package:
  - Docsearch Client fileset
  - Docsearch Client - CDE Desktop Icons and Actions fileset (if you are using the CDE Desktop).
  - Docsearch Support filesets. When you install the base operating system, it automatically installs support for the language used by this system. However, if you want to be able to use the library service in other languages, you must also install the docsearch support filesets for those languages. The support filesets are stored in the BOS messages packages (bos.msg locale) and are named DocSearch CDE Action - language and DocSearch Common Messages - language. You do not need to install the CDE message set if you are not using the CDE desktop.
    
    Note: You must also have the BOS locale (language environment) installed for any language you want to use. If you install the locale after the Documentation Library Service is installed on your system, the messages for that language are also automatically installed. However, if the locale was installed before the library service (for example, you are updating the operating system), you must manually install the library service messages.
    
    For instructions on adding language support, use the same procedure as shown in Installing the Server, step 3
Configure the Documentation Library Service.
To configure the Documentation Library Service using Web-based System Manager:
1. As root user, start the Web-based System Manager by typing wsm on the command line.
2. Expand the machine name.
3. Expand System Environment in the Navigation area.
4. From the System Environment menu, choose Settings --> Documentation Server.
5. In the Browser command field, type the name of the command that launches the Web browser with a URL. This selection will be the default Web browser for all users of this computer.
  - If you are using the Netscape browser, type netscape in the Browser field and continue with the next step.
  - If you are using another browser, you must include any necessary flags that include a URL in the launch command. For example, if launching your Web browser to a specific site requires a -u flag, and your launch command looks similar to the following:
```
YourWebBrowser -u http://www.w3.org
```
    Your entry in the Browser field would be:
```
YourWebBrowser -u
```
    You do not include the URL itself in the Browser field entry.
    
    Note: Many browsers (for example, Netscape) do not require a flag.
6. Click OK.
7. Select Settings --> Documentation Server again.
8. Select Remote server.
9. Type the name of the documentation server into the Computer name field. This documentation server contains the documents that you want this client to be able to search.
10. In the Server port field, type in the port number the Web server software is using. The standard port is 80.
11. Click OK to complete the configuration.
12. Close the Web-based System Manager.
To configure the Documentation Library Service using SMIT:
1. On the client, change to root user. On a command line, type smit web_configure.
2. Select Change/Show Default Browser. In the *Default browser LAUNCH COMMAND field, type the command that sets the default browser for all users on this computer. Include any flags that are required when a URL is included in the command. If you want to have the default browser to open to a specific URL, also add the URL after the command to open the browser. For example, if you want your browser to open with the www.ibm.com/servers/aix/library page, type the following in the *Default browser LAUNCH COMMAND field:
```
YourWebBrowser flag http://www.ibm.com/servers/aix/library
```
  Note: Many browsers (for example, Netscape) do not require a flag.
3. Return to the Web configuration main menu. Select Change Documentation and Search Server.
4. On the Documentation Search Server LOCATION screen, click on List and select Remote computer for server location. Click OK.
5. On the next screen, enter the name of the remote documentation search server you want the client to send its search requests to in the NAME of remote documentation server field. You can type a name or an IP address.
  If the Web server on the remote server is set to use some port other than the standard port 80, enter that port number.
6. Click OK to configure your client system. When it is finished, a Documentation server configuration completed! message displays at the bottom of the results panel.
The documentation search functions on this client are now ready to use. Any users logged in to this client before configuration finished must log off and then log back in to use the search functions.