This section includes:
With the Documentation Search Service, users can search registered HTML documents using a search form that appears in the web browser. When users type words into the search form, the service searches for those words, and then presents a search results page containing links that lead to the documents containing the target words.
If the Documentation Search Service is not already installed and configured on your computer, it is highly recommended that it be installed and configured now, since it is the search engine for the AIX documentation and the Web-based System Manager application. It is also used by some applications as the search function for their online documentation.
The AIX global search form allows users to search all documents that are registered on a computer. Users can access the global search form by typing docsearch on the command line or by clicking the search service icon in the CDE Desktop Help subpanel. Search forms that search only a subset of the registered documents may also be launched from "Search" links inside the document pages of applications such as Web-based System Manager.
The Documentation Search Service is an optionally installable component of AIX. If you ordered a preinstalled system from the factory, the search service may have already been installed and configured at the factory.
If you are not sure that the Documentation Search Service has been installed and configured on your computer, go to Testing the Search Service.
If you need to install or configure the search service, go to Installation of Server and Client.
If the Documentation Search Service has been installed and configured on your computer, or you do not want to install it, go to Where Do I Go Next?
If you are not sure if the search service is installed and configured, you should try the following test, which requires that you be running in the X-Windows System or the CDE Desktop:
At the command line, type: docsearch. You will see one of three results:
The search form appears, with no error messages. Try searching for a word to see if the search is working correctly.
If the search works correctly, go to Where Do I Go Next? to complete the rest of your AIX installation tasks.
If the search fails, go to Problem Determination in AIX Version 4.3 System Management Guide: Operating System and Devices after you have completed all of your tasks in this guide.
The browser opens, but you get a message saying that there are no volumes (indexes) to search. The search service may be installed, but the search service cannot find any installed documents that are registered with the search service.
Your next step is to install searchable documents. After you have installed some documents that register themselves with the search service (for example, the AIX Version 4.3 documentation), return to this chapter and retest the search service.
No browser appears, or the browser appears containing a message saying it cannot find the path or URL. The search service is not installed and configured correctly. Go to Installation of Server and Client to install and configure the search service.
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 Search 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.
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:
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
A web browser that can display forms (the Netscape browser is on the AIX Version 4.3 Netscape Products CD).
Web server software that can run CGI (Common Gateway Interface) programs ( the Lotus Domino Go Webserver is on one of the AIX Version 4.3 Bonus Pack CDs).
Consult the documentation that came with your web server software to configure and start your web server software. Make note of and keep handy the full path names of the web server directories where the server starts looking for HTML documents and CGI programs, unless you are using the Lotus Domino Go webserver and you installed it in its default location. In addition, some web servers may not automatically create these directories. If not, you must create them before you continue.
You must also configure your web server software to allow access from the users and remote computers that will be using this computer as their documentation search server.
If the Documentation Search Service is not already installed on your system, install it now. If you are not sure what is already installed, type:
smit list_installed
The AIX Documentation Search Service (bos.docsearch) is contained on Volume 2 of the AIX Version 4.3 CD. This package must be installed after you have installed and configured your web server.
Notes:
Install all parts of the package, except that if you do not use the CDE Desktop, you do not have to install the Docsearch Client - CDE Desktop Icons and Actions fileset.
If you are installing the Documentation Search Service on a system that has a previous version of the search service installed, the installation process may fail saying that it cannot install the IMN search package. If this happens, unselect the Documentation Search Service for installation and then manually select just the IMN search package and install it. After that install completes, try again to install the Documentation Search Service package.
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 installation. If this is the case, you must install additional message filesets for the other languages you want to serve. The message filesets include translated error messages and the translated buttons and controls the appear in the search form.
For example, assume that your server is running in English when you are installing the docsearch package and you want users to be able to search both English and Spanish documents from the documentation server. The English messages will be automatically installed since that is the language in use during install. So you only need to manually select the Spanish message sets for installation. Additionally, you must also have the AIX Base Operating System locale (language environment) for Spanish installed.
There are different ways to install the search service messages for another language:
After you install the Documentation Search Service (docsearch), you can install the AIX locale (language environment) for the language you want to add. Do this even if you have already installed the locale before. This will automatically install all of that language's messages for all applications that are already installed on your computer. If you have already installed the locale once, it will just install the messages for any applications you installed after you first installed the locale.
This is the easiest technique, but the disadvantage is that it installs all messages for all applications installed on your computer. This makes install take longer and uses up more disk space. To install or update an entire locale, first install docsearch, then type the command:
smit mle_add_lang
Select the additional languages you want in both the cultural conventions and language translation fields. Installation may take a long time depending on how may other applications you have installed.
If the locale for the desired language was installed before the docsearch package was installed, you can just install the docsearch messages. The methods for doing this include:
Using Web-based System Manager
From the command line, type:
wsm software
When the Software container is displayed, a list of installed items for the computer your are installing to will be displayed. Click on the bos icon to generate an expanded list of the installed BOS filesets. Determine if the filesets you want to install are already present on the system. If not, continue to the next step.
Select the New Software (Install/Update)-->Install Additional Software (Custom) from the software menu.
When the dialog appears, use either the pulldown menu or type the device or directory into the Specify or select a software source field.
Click on the Install specific software from source button, and then enter the fileset name in the Specify or select software to install field. If you are unsure as the available languages or fileset names, you may click on the Browse button to find and select the appropriate filesets.
You should always install the Common messages, however, if you have the desktop installed on your system, you should 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 will be 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 AIX BOS messages packages (bos.msg.locale, where locale=desired language) and are named:
Click on the Add button to place the fileset into the Selected Software window.
After you have added all of the filesets you wish to install into the window, click on the OK button.
A message dialog is displayed, showing the status of the installation. If the process completes with no problems, you should see a message box display a Success message.
Using SMIT
From the command line, type:
smit install_all
You should always install the Common messages, however, if you have the desktop installed on your system, you should 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 will be 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 AIX BOS messages packages (bos.msg.locale, where locale=desired language) and are named:
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.
When the next dialog appears, enter the fileset names you wish to install. If you want to install more than one fileset at this time, you must seperate each fileset name with a space. If you do not know the exact name of the fileset you wish to install, or would like to browse the available languages, click on the List button. Highlight the packages you would like to install from the list.
Click on OK.
You have different methods available to you for configuring the Documentation Search Service. These methods include:
Using Web-based System Manager
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
Double-click on Internet Environment icon to open it. The Default Browser page of the properties notebook displays.
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
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.
Click OK to return to the System container.
Double-click the Internet Environment icon to reopen it. The Default Browser page of the properties notebook displays.
Select the Documentation Server tab. The Documentation Server page displays.
Select the Local server radio button.
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 Lotus Domino Go Webserver or Internet Connection Server 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.
If you selected Other, type in the full path names of the CGI directory and the Documents directory. If you selected one of the default web server packages, skip to the next step.
In the Server port field, type in the port number that the web server software is using. The most commonly used port number is 80. Click OK.
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 search service.
Go to Where Do I Go Next? for information on continuing your AIX installation tasks.
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.
Select Change/Show Default Browser. After the Change/Show Default Browser dialog is displayed, type the browser and any required flags into the Default Browser LAUNCH COMMAND field. For example, if you are opening your Web browser to the www.rs6000.ibm.com/aix/library page from the command line, you would type the following:
YourWebBrowser -u http://www.rs6000.ibm.com/aix/library
To set the default browser in SMIT, enter the following line into the Default Browser LAUNCH COMMAND field:
YourWebBrowser -u
Note: Many browsers, such as Netscape, do not require a flag.
Return to the Web configuration main menu. Select Change Documentation and Search Server.
In the Documentation and Search Server LOCATION dialog, click on List and select local - this computer for server location, and then click on OK.
In the Web Server SOFTWARE dialog, click on List. Select the web server software you are using, and then click on OK.
Note: If you have installed Lotus Domino Go Webserver or Internet Connection Server 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.
When the Change Local Documentation and Search Server dialog appears, type in the full path names of the cgi-bin and HTML Web-server directories. If you selected one of the two default servers, the path names should already be displayed. If you want to set your web server to use a port other than the standard port 80, type in that port number. Select OK.
SMIT should now configure your system. When this process is complete, you should see the Documentation server configuration completed! message at the bottom of the results panel.
The Documentation Search Service installation and configuration is now complete.
Note: Any users who were logged in when configuration was done must log out and then log back in to activate the search service.
The Configuration Assistant is an automated guide designed to walk you through the configuration tasks one step at a time. It asks you a series of questions and then configures the system for you. This is the simplest configuration tool to use.
As root user, enter configassist on the command line.
When the Configuration Assistant appears, press the Next button.
On the second screen, select the task Configure Online Documentation and Search, then press Next.
Follow the instructions on the following screens to complete configuration.
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, see AIX Documentation Search Service in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.
The installation of the Documentation Search Service is complete. Go to Where Do I Go Next? for information on continuing your AIX installation tasks.
Use this procedure if you want to set up a computer to be a client of a remote documentation search server computer. When users on this computer want to search online documentation, the request is sent to a remote documentation search server, where the search is conducted and the results then sent back to a web browser on this client computer.
To create a search client, complete the following steps:
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
A web browser that can display forms (the Netscape browser is on the AIX Version 4.3 Netscape Products CD).
The AIX Documentation Search Service package (the bos.docsearch package is on Volume 2 of the AIX Version 4.3 CD-ROM). You do not need to install the Docsearch Server fileset. From this package, install:
The Docsearch Message filesets . When you install the docsearch package it automatically installs the current language of your computer. However, if you want to be able to search documents in other languages, you must also install the docsearch message sets for those languages. The message filesets are stored in the AIX 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 desktop.
Note: You must also have the AIX BOS locale (language environment) installed for any language you want to use.For example, assume that your server is running in English when you are installing and you want to be able to serve English and Spanish documents from the documentation server. The English messages will be automatically installed. So you only need to manually select Spanish. You would look in the installation list under the heading bos.msg.es_ES and install the filesets DocSearch CDE Action - Spanish and DocSearch Common Messages - Spanish.
You can configure the Documentation Search Service; by using two different methods. These methods include:
On the client computer, change to root user. On a command line, type the fast path: wsm system to display the Web-based System Manager System container.
Double-click the Internet Environment icon to open it. The Default Browser page of the properties notebook displays.
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.
Click OK to return to the System container.
Double-click the Internet Environment icon to reopen it. The Default Browser page of the properties notebook displays.
Select the Documentation Server tab. The Documentation Server page displays.
Select the Remote server radio button.
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.
In the Server port field, type in the port number the web server software is using. The most commonly used port is 80.
Click OK to complete the configuration. Close the Web-based System Manager application.
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.
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.
Select Change/Show Default Browser. In the ??? 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. 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 SMIT, enter the following line into the ???? field:
YourWebBrowser -u
Note: Many browsers (for example, Netscape) do not require a flag.
Return to the web configuration main menu. Select Change Documentation and Search Server.
On the "Documentation Search Server LOCATION" screen, click on List and select Remote computer for server location. Select OK.
When the next screen appears, type into the NAME of remote documentation server field the name of the remote documentation search server computer that you want this client computer to send its search requests to. 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, type in the port number. Select OK to configure your client system. When it is done, you should see the Documentation server configuration completed! message at the bottom of the results panel.
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.
Go to Where Do I Go Next? for information on continuing your AIX installation tasks.