There are two different sets of "developers" who may need to read this chapter: a) application developers who are including HTML documentation with their application and want to use the Documentation Search Service to provide search functions for their manuals; and b) document authors who want to place a document on a system and allow users to use the Documentation Search Service to search their document.
The Documentation Search Service provides a web server search form that allows users to search HTML online documents. Users can begin searching in two ways. In the CDE Desktop Help subpanel, the global search form can be opened. This search form allows users to search all registered documents that are installed on a system. Alternately, applications can provide search forms that are accessed from their help menus ("Search Help") or from links in their documentation pages, a "Search" link. Typically, these application search forms just search a single document or all the documents for that application.
The Documentation Search Service is an optionally installable component included in the AIX base operating system starting in version 4.3. The service includes a search engine and a CGI layer. The CGI layer is stored in, and run by a web server on a documentation server computer.
When the CGI layer is called by an application, it automatically generates a search form inside the browser, passes the user's search query to the search engine, and displays the search results in results pages. A default generic form is provided. However, using command parameters or a configuration file, you can customize the search form to change things in the form such as the title, text, graphics, and book volumes (indexes) that are searched.
The Documentation Search Service doesn't really search your documents. Instead it searches compressed copies, called indexes, of your documents. This greatly increases performance. So, to use the service, you must create indexes for your documents. When the indexes are copied or installed on a system, the indexes must be registered with the search service so that the service knows their names and locations.
Currently, the AIX 4.3 Documentation Search Service can only search documents that meet two criteria. The documents must be written:
Keep in mind that even if a document is written in one of the supported languages, it cannot be indexed and searched unless it is also written in the ISO 8859-1 Code Set. For information on any changes in language support, make sure to read the README files that come with any updates to the AIX Documentation Search Service.
The first step is to create your HTML documents.
Users can search your documents in two ways.
You call a search form by calling the ds_form CGI program that is installed in the web server cgi-bin directory on the documentation server. If you call this program without specifying any parameters, it will, by default, return the generic global search form which shows all registered indexes on the system.
Normally, instead of the global form, you only want users to search your specific documents. Therefore, you should include in the link command the parameters that tell the search service to create a custom search form that only searches your documents. Additionally, you can also change other elements of the form such as the title and text at the top of the search form, graphics, and almost any other HTML element of a page. You can also change the appearance of the results page.
There are two different ways to specify a custom search form: a) include parameters in the launch link command that list the custom elements of your form; or b) include just the name of a configuration file. The search service will then read the contents of this file to get the custom elements for your search form. The parameter technique is simplest if you just want to use the generic from and specify a few index names. The configuration file technique is better if you want to make a custom form or have a lot of index names to specify.
Note: If you plan on producing translated versions of your search forms and you want a custom title for your search form, we suggest that you use the configuration file method (number 2 below) instead of using a title parameter (method 1 below). The title parameter is part of a call to a CGI program. The CGI standards limit the character codes that can be passed to a CGI program. For title text that is inside a configuration file you can use any character codes that your browser can display. This should make translation of the search form title easier.
To include parameters in the HTML link, after the URL of the search form CGI add a question-mark (?) followed by an ampersand (&) separated list of parameters and their corresponding values.
<A href="../../../../../search/index.html">Search</A>
Example: If you want the generic search form, and you have two indexes called Book1S and Book2S that you want to be searched, you might insert the following link in your HTML document:
<A href="../../../../../search/index.html">Search</A>
This will create a link called "Search" in your documents. When this link is clicked, it will open a generic search form with only the two indexes Book1S and Book2S available for searching if they exist.
Besides the indexes parameter, there are other parameters you can include in the link command to customize your form:
Example: If you want the search form to contain four columns of indexes, you might insert the following link in your HTML document:
<A href="../../../../../search/index.html">Search</A>
Example: If you want the search form to be configured based on the config information in /mypath/myconfig.cfg where /mypath/myconfig is a file on the documentation server machine, you might insert the following link in your HTML document:
<A href="../../../../../search/index.html">Search</A>
When you give a list of indexes to display the search form will contain only those indexes that are in the list and can be found on that documentation server. Any index specified that is not found on the documentation server will not be displayed.
If you want the search form to display an index you specified even when it is not found or is in error, put a plus (+) in front of the index name in the HTML link.
Example: If you want the search form to display the indexes Book1S and Book2S regardless of whether or not they can be found on the documentation server, you might insert the following link in your HTML document:
<A href="../../../../../search/index.html">Search</A>
If you want the search form to prevent a specific index from being displayed and selectable for searching, you can put a minus (-) in front of the index name in the HTML link.
Example: If you want the search form to display all of the indexes except the indexes Book1S and Book2S, you might insert the following link in your HTML document:
<A href="../../../../../search/index.html">Search</A>
Example: If you want the search form to be displayed in Spanish, you might insert the following link in your HTML document:
<A href="../../../../../search/index.html">Search</A>
Of course, you would probably replace the word "Search" with the translated version.
Example: If you want the title of the results page to be "Results of My Search", you might insert the following link in your HTML document:
<A href="../../../../../search/index.html">Search</A>
Note: All spaces in the title must be replaced with pluses (+).
Example: If you want the title of the search form to be "Searching My Documents", you might insert the following link in your HTML document:
<A href="../../../../../search/index.html">Search</A>
Note: All spaces in the title must be replaced with pluses (+).
This is the recommended method if you want a custom search form or have more than a few indexes you want to search.
Note: With the exception of the indexes configuration file entry, a parameter will supersede any configuration file entry of the same name.
There are two formats for configurations that can be set in a configuration file:
Example: If you want the search form to contain four columns of indexes, you might insert the following in your configuration file:
If a columns parameter is also specified in the HTML link, the parameter will supersede the columns configuration file entry.
When you give a list of indexes to display the search form will contain only those indexes that are in the list and can be found on that documentation server. Any index specified that is not found on the documentation server will not be displayed.
Example: If you want the search form to display only the indexes Book1S and Book2S, you might insert the following in your configuration file:
If you want the search form to display an index you specified even when it is not found or is in error, put a plus (+) in front of the index name in the configuration file.
Example: If you want the search form to display the indexes Book1S and Book2S regardless of whether or not they can be found on the documentation server, you might insert the following in your configuration file:
If you want the search form to prevent a specific index from being displayed and selectable for searching, you can put a minus (-) in front of the index name in the configuration file.
Example: If you want the search form to display all of the indexes except the indexes Book1S and Book2S, you might insert the following in your configuration file:
The data from an indexes parameter specified in the HTML link is cumulative with the data in the indexes configuration file entry.
and the configuration file /tmp/config.cfg contains the line:
The search form will display Book1S, Book2S, Book3S and Book4S.
The data from an indexes parameter specified in the HTML link will override the data in the indexes configuration file entry.
and the configuration file contains the line:
The search form will display both Book1S and Book2S.
Example: If you want the search form to be displayed in Spanish, you might insert the following in your configuration file:
If a lang parameter is also specified in the HTML link, the parameter will supersede the lang configuration file entry.
Example: If you want the title of the results page to be "Results of My Search", you might insert the following in your configuration file:
If a results_title parameter is also specified in the HTML link, the parameter will supersede the results_title configuration file entry.
Note: The results title parameter will be ignored if a results_top configuration file entry is given.
Example: If you had a configuration file for users wanting to search your documentation, but now want them to search the documentation at some remote site instead, you might change the contents of your configuration file to:
Note: Specifying a search_page configuration will cause all other settings to be ignored.
Example: If you want the title of the search form to be "Searching My Documents", you might insert the following in your configuration file:
If a title parameter is also specified in the HTML link, the parameter will supersede any title configuration file entry.
Note: The title configuration will be ignored if the search_top configuration is given.
| Configurations of the type: | configuration_begin
<your HTML code> parameter_end |
Notice that all of these configurations have _begin appended to their name to indicate the start of the HTML code fragment, and _end appended to their name to indicate the end of the HTML code fragment.
Cound not get ride of SRC for /images/myimage.gif in
Note: Any title parameter or title configuration file entry specified will be ignored.
Cound not get ride of SRC for /images/myimage.gif in
Note: Any title parameter or title configuration file entry specified will be ignored.
The search engine does not search your actual documentation files. Instead it searches indexes that are created from your documentation. Very simplistically, indexes are compressed copies of your files. This greatly speeds up the searches. Therefore, if you want to use the search service to search your documents, you must create at least one index that will be installed with your documents.
To Create Indexes:
Each index you create will have its own selection checkbox in the search form. You can create one index for each of your documents. Or you can create one index that combines text from multiple documents. But keep in mind that each time that index is selected for search, all the documents in that index will be searched. So when you combine documents into an index, you should think about what documents your user will want to search together.
Also, if you are creating an installp package, all documents that are within one index should be placed inside the same installable unit (fileset) of documentation. Otherwise users might only install some of the documents within the index and they would get "missing document" errors when they try to open the documents from the search results page.
For each index you want to create, repeat the following steps
The result is that each document will have a full pathname that is composed of a "temporary" part, and a "permanent" part. The temporary part is the pathname of the build directory. The permanent part of the path specifies the location of the document inside your document tree. Once an index is built, the permanent part of a document's pathname cannot be changed. The two rules about the pathnames is that the first directory in the permanent part of the pathname must be named the name of the language the documents are written in and the second directory must be your application's name.
For example, your application is called "calculator". The online documents for the application are written in English. There are two user guide documents (doc1, doc2) and one administrator document (doc3). You could place the documents like this in the filesystem on the computer on which you are building the indexes:
/usr/share/man/info/en_US/calculator/user/doc1.html
/usr/share/man/info/en_US/calculator/user/doc2.html
/usr/share/man/info/en_US/calculator/admin/doc3.html
You can arrange your documents anywhere and in any way you like, except that all documents that go into a single index must share a common top directory so that they form a single tree. In the example, "calculator" is the common top directory. Your documentation can be in any directory when you are indexing them.
If you arranged your documents like the example above, your ASCII file would have the following contents:
/usr/share/man/info/en_US/calculator/user/doc1.html
/usr/share/man/info/en_US/calculator/user/doc2.html
/usr/share/man/info/en_US/calculator/admin/doc3.html
Next you must indicate where the temporary part of each pathname ends and where the permanent "installed" part of the pathnames start. You do this by replacing the last slash "/" in the temporary part of the document pathnames with an ampersand "@". When the index is created, only the part of each pathname that is to the right of the @ will be saved in the index definition file.
For example, the above example file would now be modified to look like this:
/usr/share/man/info/en_US@calculator/user/doc1.html
/usr/share/man/info/en_US@calculator/user/doc2.html
/usr/share/man/info/en_US@calculator/admin/doc3.html
The slash after the "en_US" was replaced with a @ since it is the last slash in the temporary part of the path.
Every web server has an internal home directory where it starts its search for documents that requested by. When the Documentation Search Server is installed and configured, a filesystem link is placed in this directory. This link points to the standard location of documents in the AIX filesystem: /usr/share/man/info. Since your web server's will automatically go to this location to find your documents, the search engine only needs the portion of the document path from this location forward.
Index Naming Conventions
When you create a search index for a document you must specify an eight (8) character name for the index. However, the search service will not let you register your new index if there is already a registered index that has the same name as your index. To reduce the probability of naming conficts, it is recommended that certian naming conventions be followed:
For example, if you are creating an index for a document you wrote in English, you might name it 999ak2en .
For example, if your application is called Calculator, and the document you are indexing is written in Spanish, you could name the index cal2b4es .
Note: If your documents are written in English the index name should end in en .
The title of your index is the text that will appear next to the index's checkbox in the search form. The title should uniquely describe the document or documents that are in the index and contain a maximum of 256 characters.
Note: The imnixcrt command will attempt to create the data and work directories and any missing higher directories. However, the directory structure must be writable by the user 'imnadm' for the imnixcrt command to create the directories.
Before you can create your first index you will need to make the /usr/docsearch directory writable by the user 'imnadm'. You will only need to do this step before you create your first index.
The index creation command has the syntax (all on one line):
where <index name> is the 8 character name of the index and the last argument is WT.
Following our example, you could type (all on one line)
/usr/IMNSearch/cli/imnixcrt cal413es /usr/docsearch/indexes/cal413es/data /usr/docsearch/indexes/cal413es/work WT
To update the registration table on the development computer:
/usr/IMNSearch/cli/imndomap /var/docsearch/indexes -c <indexname> /doc_link/en_US/ "<index title>"
Where <indexname> is the name of your index, and <index title> is the title of your index (the text you want the user to see when they are selecting which indexes to search).
Then copy the new index registration table over the backup copy of the index registration table by typing:
cp /var/docsearch/indexes/imnmap.dat /usr/docsearch/indexes
If you are creating an index to put in an application's AIX installp package, continue to "Packaging your application's index(es) with your application's documentation".
The index build tool assumes all documents are in the codeset ISO 8859-1. If your documents are not in this codeset when you build your indexes, searches on those indexes may generate unexpected results.
If you are building indexes of documents written in a language other than English, you should replace references to the locale 'en_US' with the locale that corresponds to the language in which your documents are written. See "Locale Overview" in AIX Version 4.3 System Management Guide: Operating System and Devices for more information on possible locales.
To Remove an Index:
Note: You must repeat these steps for each separately installable fileset in your package that contains one or more indexes.
Example: To install the indexes Book1S and Book2S which are being installed in /usr/docsearch/indexes/Book1S and /usr/docsearch/indexes/Book2S , have the titles Book #1 and Book #2 , and whose documents are in /usr/share/man/info/en_US/calendar/... you might have lines in the script like:indexdir_name_1="Book1S" indexdir_name_2="Book2S" index_title_1="Book #1" index_title_2="Book #2" index_loc_1="/usr/docsearch/indexes/Book1S" index_loc_2="/usr/docsearch/indexes/Book2S" document_loc_1="/doc_link/en_US/" document_loc_2="/doc_link/en_US/"
Example: If you have two indexes with the names cal2b4es and cal3c5es your copy of the pre_rm script would have lines like:indexdir_name_1="cal2b4es" indexdir_name_2="cal3c5es"