This section includes:
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:
If you are not sure if the Documentation Library Service has been installed and configured on your computer, go to Testing the Documentation Library Service.
If you know you need to install or configure the library service, go to Installing the Documentation Library Service.
If the Documentation Library Service has already been installed and configured on your computer, and you now want to install the operating system manuals, go to Installing the AIX Documentation.
If the installation and configured tasks for documentation have already been completed on your computer, or you do not want to do these installations, go to Where Do I Go Next?
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:
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.
If everything is working correctly, and you need to install some of the operating system manuals, go to Installing the AIX Documentation. If you don't need to install any more documents, 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 the AIX Version 4.3 System Management Concepts: Operating System and Devices after you have completed all of your tasks in this guide.
"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.
"Search is not enabled". This means that the service has not been fully installed and configured. Go to Installing the Documentation Library Service.
"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.
"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.
No browser appears. The search service is not installed and configured correctly. Go to 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.
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.
This section describes how to install and configure the AIX Version 4.3.3 Documentation Library Service using the AIX system management tools.
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.
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 must be installed. You can use any web server software that can run CGI (Common Gateway Interface) programs. The Lite NetQuestion web server is installed with the base operating system. This server can serve documents to local users on this computer, but cannot be used to server documents to remote users. If you want to use this server, it is already preinstalled. Additionally, the IBM HTTP Server software is on one of the AIX Version 4.3 Bonus Pack CDs. This web server software can be used to serve documents to both local and remote users. If you want to use this web server, install it now. Or install another web server of your choice.
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.
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 all parts of the packages.
You may see a message saying that the NetQuestion Local HTTP Daemon is not being installed because it is already installed on the system. This is normal and you can ignore this message.
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:
After you install the base operating system, you can install the AIX locale (language environment) for the language you want to add. To install or update an entire locale, 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. This technique assumes you are installing the locale after the the library service was 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 pull-down 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 separate 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.
There are two methods you can use to configure the search service. These methods include:
Change to root user. On a command line, type the fast path:
wsm system
This should 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 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 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.
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.
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.
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.
You can now press the OK button. The Documentation Library Service will be configured.
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.
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 *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.
Return to the web configuration main menu. Select Change Documentation and Search Server.
On the "Documentation and Search Server LOCATION" screen, click on List and select local - this computer for server location. Select OK.
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.
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.
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.
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.
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.
The installation of the Documentation Library 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 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:
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 HTML forms (the Netscape browser is on the AIX Version 4.3 Netscape Products CD).
The AIX 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 these filesets of the package:
The Docsearch Message filesets . When you install the base operating system it automatically installs the messages for the current language of your computer. However, if you want to be able to use the library application 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 CDE desktop.
Note: You must also have the AIX 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 will also be automatically installed. However, if the locale was installed before the library service (for example, you are doing an update install of the operating system), you will need to manually install the library service messages.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 Library Service by using two different methods. These methods include:
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
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 standard 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 *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.
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, 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.
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.
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.
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.
On systems that support a GUI (Graphic User Interface), use the following procedure:
From the command line, type:
wsm system
When the container appears, double-click on the Cultural Environment icon.
Select the Available Resources tab.
Search the list to see if the desired language is shown. If it is shown as installed, go to step 2. If it is not listed, click the Add button and install that language. When the language is installed, the matching documentation library messages will also be installed automatically.
When installation is complete, go to step 4.
On systems that do not support a GUI (Graphic User Interface)., use the following procedure:
From the command line, type:
locale -a
If the language (locale) you want is listed, skip to step 2. If it is not listed, continue here with the next step in this procedure. For a list of what the locale names mean, go to the article Understanding Locale in the System Management Guide: Operating System and Devices.
If the language is not listed, enter the smit mlang command. Next, select Add Additional Language Environments.
Use the next screen to install the both the Cultural convention and Language translation for the language you want. When the language is installed, the matching documentation library messages will also be installed automatically.
When installation is complete, skip to step 4.
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.
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.
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.