[ Next Article | Previous Article | Book Contents | Library Home | Legal | Search ]
Installation Guide

Installing the Documentation Library Service for AIX Version 4.3.3

This section includes:

Introduction

Beginning with AIX Version 4.3.3, the Documentation Library Service allows users to navigate, read, and search registered HTML documents using their Web browser and the library application. The library application presents documents in a expandable-tree format that can be navigated by clicking on button controls in the tree. This action opens those documents for reading, and also allows users to search keywords using a search form present in the application. The Documentation Library Service searches for those words, and then presents a list of results that are linked to information contained in the online documentation files.

The library service produces two types of GUIs (Graphic User Interface) to the user. These are a global GUI and an application GUI. The AIX global GUI shows users all HTML documents on the document server that are registered with the global GUI. The global views may contain documents from many different applications.

Users can 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 GUIs may be launched from links inside the menus or document pages of an application. The library pages displayed contain information relating to the 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.

With the exception of the search engine, the components of the Documentation Library Service are installed along with the BOS (Base Operating System). The search engine must be installed from the second CD containing the AIX operating system. After installation, the service may need to be configured to ensure proper operation.

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

Where to go next:

Testing the Documentation Library Service

If you are not sure if the search service is installed and configured, you should enter the following command:

docsearch

You will see one of these results or messages:

  1. The library application appears, with no error messages and the search form appears at the top of the page. This search form contains one or more fields where you can enter words you want to search for. There are documents visible in at least one of the views. Try opening a document to read it and then searching keywords to test the operation of the search function.

  2. "There are no documents installed for this view." The library service may be installed, but the service cannot find any installed documents that are registered for the current view you are looking at. Try clicking on the other views to see if they contain documents. Once you find a view with documents try reading and searching the documents.

    The library may be installed and configured correctly, but you cannot fully test the service until documentation has been installed and registered. To install the operating system manuals go to Installing the AIX Documentation. You may also install and register any other documents that register themselves with the library service. After you have done this, return to this section and retest the library functions.

  3. "Search is not enabled". This means that the service has not been fully installed and configured. Go to Installing the Documentation Library Service.

  4. "Search is not supported in this language". The search engine cannot perform searches in a language installed on the system. This is not an error state. This message will always be visible when you are using this language.

    If documents are visible in one of the Views, try reading the documents. If your documents are displayed properly and you can open them for reading, then no further configuration of the library service is necessary. If you cannot read the documents properly, go to Installing the Documentation Library Service. If no documents are available in any views, and you want to install the operating system manuals go to Installing the AIX Documentation. You can install and register any other documents that register themselves with the library service. After you install the manuals, return to this section and retest the library service.

  5. "Cannot find or execute ds_form" The exact wording of this message will vary. The search service is not installed and configured correctly. Go to Installing the Documentation Library Service.

  6. No browser appears. The search service is not installed and configured correctly. Go to Installing the Documentation Library Service.

Installing the Documentation Library Service

If you have a system that supports a GUI (Graphic User Interface) and are running in the X-Windows System, you can use the Configuration Assistant to install and configure the library service, or you can use the manual method. It is highly recommend that you use Configuration Assistant since it will automatically perform some steps for you and is easier to use. Go to Using Configuration Assistant to Installing the Documentation Library Service.

If you have an ASCII system without graphics, you must use the manual method. Go to Manually Installing the Documentation Service.

Using Configuration Assistant to Installing the Documentation Library Service

If you have a system that supports a GUI and you are running in the X-Windows System, you can use the Configuration Assistant to install and configure the Documentation Library Service. It will allow you to configure this computer as a documentation server or it will allow you to configure this computer as a client computer that will get its documents from a remote documentation server.

Note: If you want to install documents on this computer and register them with the Documentation Library Service, HTTP web server software must be installed on this computer. The Configuration Assistant can automatically install the Lite NetQuestion web server software or the IBM HTTP Server software - both come 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.

If you want to configure this computer as a client that get its documents from a remote documentation server, you do not need to install web server software on this computer.

To launch the Configuration Assistant, make sure you are logged onto the system as the root user, and enter the following command:

configassist

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

After you have finished installation and configuration, go to Adding Language Support to the Documentation Library.

Manually Installing the Documentation Service

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

Installation of Server and Client

A computer can be set up as either a documentation server or as a documentation client system. When users on a client computer 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 computer and the results are then sent back to the user on the client computer.

A documentation server computer has the following software installed:

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

If you have a standalone computer, both the server and client software are installed on the same standalone computer. Instead of going to a remote computer, requests from users on the standalone computer go to the web server software on their own 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 on to the documentation server computer.

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

Installing the Server

Use this procedure if you want to set up a computer to be a documentation server, where you will install your online documentation. A server can be a networked computer that serves remote clients, or it can be a standalone computer that serves only its own users.

To create a documentation search server, the following steps are completed in this sequence. Be sure to follow the instructions under each step:

  1. Install the Web Server Software
  2. Configure and Start Web Server Software
  3. Install the Documentation Search Engine
  4. Configure the Documentation Library Service
  5. Install or Register Your Documentation
  6. Completed Server Installation

Install the Web Server Software

If the following software is not already installed on your system, install it now. If you are not sure what is already installed, type:

smit list_installed

Configure and Start your Web Server Software

If you are going to use the Lite NetQuestion server, skip to the next section, Install the Documentation Search Engine

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 them in their default locations, you do not need to know the directory names: IBM HTTP Server, IBM Internet Connection Server, Apache web server, and the Lotus Domino Go Webserver. Some other web servers may not automatically create these HTML and CGI directories. If not, you must create them before you continue.

You must also configure your web server software's permissions to allow access from the users and remote computers that will be using this computer as their documentation search server.

Install the Documentation Search Engine

If the documentation search engine is not already installed on your system, install it now. If you are not sure what is already installed, type:

smit list_installed

Check to see if all the following packages are installed:

Install any of the above packages that are missing. The AIX documentation IMNSearch search engine package (IMNSearch.rte and IMNSearch.bld) is contained on Volume 2 of the AIX Version 4.3 CD-ROM.

Notes:

Install the Documentation Library Service Messages for Additional Languages

You may want this documentation server to be able to serve documents that are written in a language that is different than the language this computer is using during operating system installation. If this is the case, you must install additional language environments (locale) and message filesets for the other languages you want to serve. The message filesets include translated error messages, buttons and controls the appear in the library application GUI.

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 both English and Spanish documents from the documentation server. The English messages will be automatically installed since that is the language in use during operating system install. So, you only need to manually install the Spanish language environment and message sets.

There are two ways to install the library service messages for another language:

Configure the Documentation Library Service

There are two methods you can use to configure the search service. These methods include:

Using Web-based System Manager

  1. Change to root user. On a command line, type the fast path:

    wsm system

    This should display the Web-based System Manager System container.

  2. Double-click the Internet Environment icon to open it. The Default Browser page of the properties notebook displays.

  3. In the Browser command field, you must type the command that will set the default browser for all users on this computer. Include any flags that are required when a URL is included in the command. For example, if you want your browser to open with the www.rs6000.ibm.com/aix/library page open inside, you would type the following on a command line:

    YourWebBrowser -u http://www.rs6000.ibm.com/aix/library

    To set the default browser in Web-based System Manager, enter the following line into the Browser command field:

    YourWebBrowser -u
    Note: Many browsers (for example, Netscape) do not require a flag.
  4. Click OK to return to the System container.

  5. Double-click the Internet Environment icon to reopen it. The Default Browser page of the properties notebook displays.

  6. Select the Documentation Server tab. The Documentation Server page displays.

  7. Select the Local server radio button.

  8. Under the heading Location of documents and CGI programs on local server, select the web server software you installed on this computer. If the name of your web server software is not listed, select Other.

    Note: If you have installed any of the named web servers anywhere other than the default location on your system, or you set up the servers to use nonstandard locations for their CGI-BIN or HTML directories, you must select Other.
  9. If you selected Other, type in the full path names of the CGI directory and the Documents directory. If you selected one of the named default web server packages, skip to the next step.

  10. In the Server port field, type in the port number that the web server software is using. The standard port number is 80. Leave it set it to 80, if you aren't sure of the port number. However, if you are using the Lite NetQuestion web server, the port number must be set to 49213.

  11. Optionally, scroll down and change the Default Documentation Language. This is the language users will see when they launch the library using the docsearch command or the library icon in the Help subpanel in the CDE desktop front panel.

  12. You can now press the OK button. The Documentation Library Service will be configured.

  13. Your documentation server is configured, and the configuration for the new web server software is now complete. Any users who were logged in when configuration was done must log out, and then log back in to activate the library service.

The Documentation Library is now ready to accept documents. Go to Install or Register your Documentation.

Using SMIT:

  1. On the client computer, change to root user. On a command line, type the fast path:

    smit web_configure

    The web configuration screen should open.

  2. Select Change/Show Default Browser. In the *Default browser LAUNCH COMMAND field, type the command that will set 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, then you must place the URL after the command to open the browser. For example, if you want your browser to open with the www.rs6000.ibm.com/aix/library displayed first, type the following in the *Default browser LAUNCH COMMAND field:

    YourWebBrowser -u http://www.rs6000.ibm.com/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 and Search Server LOCATION" screen, click on List and select local - this computer for server location. Select OK.

  5. On the "Web Server SOFTWARE" screen, click on List. Select the web server software you are using.

    Note: If you have installed any of the listed and named web server software in a nondefault location on your system or you set up the servers to use nonstandard locations for their CGI-BIN or HTML directories, you must select Other.

    Select OK.

  6. When the next screen appears, type in the full path names of the two directories. If you selected one of the default servers, the path names should already be displayed. If you set up your web server to use some port other than the standard port 80, type in the port number. Leave it set it to 80 if you aren't sure of the port number. However, if you are using the Lite NetQuestion web server, the port number must be set to 49213. Select OK. SMIT then configures your system. When it is completed, you should see a Documentation server configuration completed! message at the bottom of the results panel.

  7. Optionally, you can specify a default documentation language. This is the language users will see when they launch the library using the docsearch command or the library icon in the Help subpanel in the CDE desktop front panel. To do this, return to the web configuration main menu and select the choice to set default documentation language. Complete the following screen to set the language.

  8. You can now close SMIT. The documentation search service installation and configuration is now complete. Any users who were logged in when configuration was done must log out and then log back in to activate the search service.

    The Documentation Library is now ready to accept documents. Go to Install or Register Your Documentation.

Install or Register your Documentation

Before any document can be searched using the documentation search service, it must have an index created, and the index must be registered with the search service.

Some applications ship prebuilt document indexes inside their install package. When the application is installed, the indexes are automatically registered. The AIX Version 4.3 documentation and the Web-based System Manager application both ship prebuilt indexes for their documents.

You can also create indexes for your own HTML documents and register them with the search engine so that they can be searched online. For further information on how to create indexes, seeAIX Documentation Library Service in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.

Completed Server Installation

The installation of the Documentation Library Service is complete. Go to Where Do I Go Next? for information on continuing your AIX installation tasks.

Installing the Client

Use this procedure if you want to set up a computer to be a client of a remote documentation library server computer. 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 computer.

Note: Search is not supported in all languages.

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

  1. Install the Client Software
  2. Configure the Documentation Library Service

Install the Client Software

If the following software is not already installed on your client system, install it now. If you are not sure what is already installed, type:

smit list_installed

Configure the Documentation Library Service

You can configure the Documentation Library Service by using two different methods. These methods include:

Using Web-based System Manager:

  1. On the client computer, change to root user. Open the Web-based System Manager System container from the command line by typing the follwing fast path:

    wsm system
  2. Double-click on Internet Environment icon to open it. The Default Browser page of the properties notebook displays.

  3. In the Browser command field, you must type the command that will set the default browser for all users on this computer. Include any flags that are required when a URL is included in the command. For example, if you want your browser to open with the www.rs6000.ibm.com/aix/library page open inside, you would type the following on a command line:

    YourWebBrowser -u http://www.rs6000.ibm.com/aix/library

    To set the default browser in Web-based System Manager, enter the following line into the Browser command field:

    YourWebBrowser -u
    Note: Many browsers (for example, Netscape) do not require a flag.
  4. Click OK to return to the System container.

  5. Double-click the Internet Environment icon to reopen it. The Default Browser page of the properties notebook displays.

  6. Select the Documentation Server tab. The Documentation Server page displays.

  7. Select the Remote server radio button.

  8. Under the Remote server button, type into the Computer name field the name of the documentation server computer. This is the server computer that contains the documents that you want this client computer to be able to search.

  9. In the Server port field, type in the port number the web server software is using. The standard port is 80.

  10. Click OK to complete the configuration. Close the Web-based System Manager application.

  11. Your client computer is configured, the documentation search service is installed, and the configuration for the new web server software is now complete. Any users who were logged in when configuration was done must log out, and then log back in to activate the search service.

Installation of the documentation search service is complete. Go to Where Do I Go Next? for information on continuing your AIX installation tasks.

Using SMIT:

  1. On the client computer, change to root user. On a command line, type the fast path:

    smit web_configure

    The web configuration screen should open.

  2. Select Change/Show Default Browser. In the *Default browser LAUNCH COMMAND field, type the command that will set 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, then you must place the URL after the command to open the browser. For example, if you want your browser to open with the www.rs6000.ibm.com/aix/library displayed first, type the following in the *Default browser LAUNCH COMMAND field:

    YourWebBrowser -u http://www.rs6000.ibm.com/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. Select OK.

  5. When the next screen appears, enter the name of the remote documentation search server computer you want the client computer to send its search requests to in the NAME of remote documentation server field.

    You can type in 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. Select OK to configure your client system. When it is done, you should see a Documentation server configuration completed! message at the bottom of the results panel.

  6. The documentation search functions on this client computer should now be ready to use. Any users logged on this client computer before configuration finished must log off and then log back in to use the search functions.

Adding Language Support to the Documentation Library

You may want users of this computer to be able to use the documentation library in more than one language.

If you do not need to support multiple languages, Go to Where Do I Go Next? for information on continuing your AIX installation tasks.

If you do need to support more than one language, continue with the following steps:

Note: You may be able to read documents in a language, but the search functions in the library service do not work in all languages and codesets. For a list of supported languages, see the Documentation Library Service chapter in the General Programming Concepts: Writing and Debugging Programs guide.
  1. Is the language environment(locale) for the language already installed?

    To see if a locale is installed, use one of the techniques under this step. If YES, the locale is already installed, go to step 2, if NO continue reading this step.

  2. Are the Documentation Library Service messages installed? If YES, go to step 4, if NO, go to step 3. To see if the messages are installed, use the following command:

    lslpp -l "bos.msg*docsearch*"

    You will get back a list that shows you the languages with library messages installed. Each language may have two message sets installed - DocSearch CDE Action and DocSearch Common Messages. If the messages for your language are installed, skip to step 4. If they are not installed, go to step 3.

  3. Use SMIT or the Web-based System Management tool and install the messages for your language. The messages are stored on your operating system CD or tape in the BOS messages packages (bos.msg locale). Install DocSearch Common Messages - language (where language is your language name). And optionally, if you are using the CDE desktop, install DocSearch CDE Action - language.

  4. The Documentation Library Service installation and configuration is now complete and is ready to be used in the language. If you need another language, return to step 1 above. If you are done installing languages and need to install operating system manuals, go to Installing the AIX Documentation. If you don't need to install these manuals, go to Where Do I Go Next? for information on continuing your AIX installation tasks.


[ Next Article | Previous Article | Book Contents | Library Home | Legal | Search ]