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. 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.
If you are not sure whether the library service is installed and configured, type docsearch on the command line.
One of the following occurs:
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.
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 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:
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 AIXwindows, 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.
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.
This section describes how to install and configure the Documentation Library Service using the system management tools.
For information about installing the client, see Installing the Client.
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:
Web server software must be installed. You can use any Web server software that can run CGI 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, you must install server software. Any compatible HTTP server software can be used; however, the IBM HTTP Server software can be installed from a CD shipped with AIX 5.2.
To verify what is already installed, type smit list_installed on the command line.
To manually install the IBM HTTP Server software using SMIT, do the following:
To manually install the IBM HTTP Server software from the command line, do the following:
# geninstall -d. -IacYXg -f HTTP_Server.bnd
If the software product contains a license agreement, the -Y flag accepts the new license agreement.
A Web browser that can display forms must be installed. (The Netscape browser is on the AIX 5.2 Expansion Pack CD.)
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:
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.
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. You need only to manually install the Spanish language support package.
There are two ways to install the library service package for another language:
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.
To install library service messages using Web-based System Manager:
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:
To install library service support using SMIT:
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:
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.
To configure the Documentation Library Service using Web-based System Manager:
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.
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.
To configure the Documentation Library Service using SMIT:
YourWebBrowser flag http://publib16.boulder.ibm.com/pseries/en_US/infocenter/base
Note: Many browsers (for example, Netscape) do not require a flag.
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.
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.
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.
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.2 General Programming Concepts: Writing and Debugging Programs.
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:
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:
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 procedure as shown in step 3 of Installing the Server.
To configure the Documentation Library Service using Web-based System Manager:
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.
To configure the Documentation Library Service using SMIT:
YourWebBrowser flag http://publib16.boulder.ibm.com/pseries/en_US/infocenter/base
Note: Many browsers (for example, Netscape) do not require a flag.
If the Web server on the remote server is set to use some port other than the standard port 80, enter that port number.
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.