[ Previous | Next | Contents | Glossary | Home | Search ]
AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs

Chapter 21. AIX Documentation Search Service

The Documentation Search Service provides a web server search form that allows users to search HTML online documents.

This chapter provides specific instructions for:

The Documentation Search Service is an optionally installable component included in the AIX base operating system starting with 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 on 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 does not actually search through documents. Instead it searches compressed copies, called indexes, of documents. This greatly increases performance. In order to use the service, indexes must be created for 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.

NOTE:

This chapter contains some commands that are VERY long. They are so long that they must be split up so that they will not go off the right side of the page. To make sure that long commands are completely visible, they are split up and displayed on two or three lines. This is an example of a long command line that has been split for viewing: 

/usr/IMNSearch/cli/imnixcrt  index_name 
/usr/docsearch/indexes/index_name/data

When you see a command displayed like this, you MUST type it all on ONE command line, with a space between each part. The above command parts would be typed like the following: 

/usr/IMNSearch/cli/imnixcrt  index_name  /usr/docsearch/indexes/index_name/data

This chapter contains the following topics:

Language Support

Currently, the AIX 4.3 Documentation Search Service can only search documents that are written in supported languages and codesets. Refer to the Language Support Table for specific information.

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.

Writing your HTML Documents

Calling the AIX Documentation Search Service Search Form From Your Documentation

Users can search your documents in two ways:

  1. Search all registered indexes on a system for a given language.

    By default, all registered indexes (compressed copies of document volumes) for a given language will appear in the Documentation Search Service global search form. This form is found by clicking on the Documentation Search Service icon in the CDE desktop Help subpanel. When users do a search using this form, all registered indexes for a given language are available for a search.

  2. Only search the documents for a single application.

    You can provide "Search" links within your GUI or HTML documents that will launch a search form that only shows on and searches in your documents. These search forms will be accessed via an application's help menu ("Search Help") or from links in their documentation pages, "Search" links. For example, The AIX Base Library includes a "Search" link in the header at the top of each page in their documents. Another example is Web-based System Manager, which includes a search link in its Extended Help document pages. The form that is launched from this link searches only Web-based System Manager help documents.

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. This form shows all registered indexes written in the server's default language.

Most likely, you want users to search your specific documents, instead of doing a global search. If so, 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. 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:

  1. Parameters Method
    Include parameters in the launch link command that list the custom elements of your form. The parameter technique is simplest if you just want to use the generic form and specify a few index names.

  2. Configuration File Method
    Include in the launch link just the name of a configuration file. The search service will read the contents of this file to get the custom elements for your search form. 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 to produce 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 instead of using a title parameter method. 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.

The Parameters method for calling a custom search form

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="/cgi-bin/ds_form?parameter1=value&parameter2=value&...">Search</A>

Parameters you can include in the link command to customize your form:

columns Tells the search form CGI how many indexes to display on each line of the search form page. The default value is three.

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="/cgi-bin/ds_form?columns=4">Search</A>

config Instead of including parameters in your HTML link that customize your search form, you can just specify the name of a configuration file (config=filename.lang) that contains your customization information. The configuration file technique is better if you are doing a lot of customization that would require a long parameters list.

Example: To call a configuration file named calculator.en you would use the following link:

<A HREF="/cgi-bin/ds_form?config=calculator.en">Search</A>

See The Configuration File method for calling a custom search form for details on how to use a configuration file.

indexes Instructs the search form CGI which indexes to display for selection.

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 generic search form, and you have two indexes called Book1Sen and Book2Sen that you want to be searched, you might insert the following link in your HTML document:

<A HREF="/cgi-bin/ds_form?indexes=Book1Sen,Book2Sen">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 Book1Sen and Book2Sen available for searching if they exist.

  • If you want the search form to display an index you specified even when it is not found or is in error, put the characters %2B in front of the index name in the HTML link.
    Example: If you want the search form to display the indexes Book1Sen and Book2Sen 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="/cgi-bin/ds_form?indexes=%2BBook1Sen,%2BBook2Sen">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 Book1Sen and Book2Sen, you might insert the following link in your HTML document: 
    <A HREF="/cgi-bin/ds_form?indexes=-Book1Sen,-Book2Sen">Search</A>
  • If you want the Documentation Search Service to automatically fill in the language suffixes for the indexes you named, you can replace the language suffix with TWO underscore characters (__). The search service will automatically replace these two underscores with the correct suffix for the language that is being used when the search for is being called.
    Example: If you want the search form to display the two indexes Book1S and Book2S, and you want the Documentation Search Service to automatically fill in the language suffices, you would insert the following link in your HTML document: 
    <A HREF="/cgi-bin/ds_form?indexes=Book1S__,Book2S__">Search</A>
lang Instructs the search form CGI in which language to display the search form. See the Language Support Table for more information on possible values for the lang parameter.

If you have created indexes for translated versions of your documents, in the Search link in those documents, you must call a search form that is displayed in the same language as the translated documents. This is required so that the readers of that language will be able to understand the search form labels and buttons. It is also required so that the language(codeset) of the user-entered searched terms and the documents match. If they mismatch erroneous results may occur.

To call a search form in a specific language, you must include a lang=locale parameter in the HTML link that calls the search form.

If you include index names as parameters (indexes=), you must specify the language of each index. There are two ways you can specify the language of the index.

  1. Make the last two characters of the index name specify the language that is inside the index. For example, if an index is Spanish (es), you might name it index_namees.

  2. Make the last two characters of the index name TWO underscores (__). The language suffix will then be automatically be filled in using the value specified in the lang=locale parameter. For example, if lang=es_ES (Spanish) and you have two indexes named index_nameA__ and index_nameB__ ,the two underscores will automatically be replaced with es when the search form is built.

    This technique is valuable if you are translating the sames indexes into many different languages. You can then just copy the same HTML search link statement into the all the different language versions of your documents. Within the different translations, you only need to change the value of the lang parameter, and not the index names.

Example: Assume your documents are written in German. You want to call a German search form and you want to have two German indexes (cal413de,cal567de) displayed for search. You could insert the following search (Suche) link in your German HTML documents: 

<A HREF="/cgi-bin/ds_form?/lang=de_DE&indexes=cal413de,cal567de">Suche</A>

Or, if you're using the underscore method, the link would look like this: 

<A HREF="/cgi-bin/ds_form?/lang=de_DE&indexes=cal413__,cal567__">Suche</A>

results_title Instructs the search form CGI what to display as the title of the search results page.

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="/cgi-bin/ds_form?results_title=Results+of+My+Search">Search</A>
Note: All spaces in the title must be replaced with pluses (+).

title Instructs the search form CGI what to display as the title of the search form page.

Example: If you want the title of the search form to be Search My Documents, you might insert the following link in your HTML document: 

<A HREF="/cgi-bin/ds_form?title=Search+My+Documents">Search</A>
Note: All spaces in the title must be replaced with pluses (+).

The Configuration File method for calling a custom search form

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.

Instead of listing a long list of customization parameters in the HTML link that calls your search form, you can create a configuration file and insert all of your customization information inside that file. Then in your link you just include the name of the configuration file as the parameter config=filename.lang where lang is the two letter specification of the language you want to the search form to display. Use the same language suffixes that are used when you specify the language in an index name. For example if you want the configuration file to call an English search form name the file filename.en. Language suffixes are listed in the Language Support Table.

Creating configuration files that call search forms in different languages

If you have created indexes for translated versions of your documents, in the Search link in those documents, you must call a search form that is displayed in the same language as the translated documents. This is required so that the readers of that language will be able to understand the search form labels and buttons. It is also required so that the the language(codeset) of the user-entered searched terms and the documents match. If they mismatch erroneous results may occur.

If a lang= parameter is also specified in the HTML link that calls the search form, that parameter will supersede a language suffix in a configuration file name.

There are two techniques for using configuration files to specify the language of a search form and the search form's indexes.

Use the Generic Search Form Technique if you just want the generic search form and do not need a custom title or text in the form.

Use the Custom Search Form Technique if you want to create a customized search form that contains a custom title or text.

Contents of Configuration Files

  1. Create a configuration file

    Create a configuration file that contains the custom elements for our search form.If the Documentation Search Service is installed on your computer, a sample configuration file can be found in /usr/docsearch/sample.cfg.

    There are two types of configuration file entries, and there are two formats for configurations that can be set in a configuration file:

    1. Configuration file entries of the type: 
      	parameter=value
      columns Tells the search form CGI how many indexes to display on each line of the search form page. The default value is three.

      Example: If you want the search form to contain four columns of indexes, you might insert the following in your configuration file: 

      columns=4

      If a columns parameter is also specified in the HTML link, the parameter will supersede the columns configuration file entry.

      indexes Instructs the search form CGI which indexes to display for selection.

      • 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 Book1Sen and Book2Sen, you might insert the following in your configuration file: 

        indexes=Book1Sen,Book2Sen

      • 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 Book1Sen and Book2Sen regardless of whether or not they can be found on the documentation server, you might insert the following in your configuration file: 

        indexes=+Book1Sen,+Book2Sen

      • 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 Book1Sen and Book2Sen, you might insert the following in your configuration file: 

        indexes=-Book1Sen,-Book2Sen

      • The data from an indexes parameter specified in the HTML link is cumulative with the data in the indexes configuration file entry.

        Example: If the HTML link is: 

        <A HREF="/cgi-bin/ds_form?indexes=Book1Sen,Book2Sen&=
	/tmp/config.cfg">Search</A>
        and the configuration file /tmp/config.cfg contains the line: 
        indexes=Book3Sen,Book4Sen
        The search form will display Book1Sen, Book2Sen, Book3Sen and Book4Sen.

      • The data from an indexes parameter specified in the HTML link will override the data in the indexes configuration file entry.

        Example: If the HTML link is: 

        <A HREF="/cgi-bin/ds_form?indexes=Book1Sen,Book2Sen&=
	/tmp/config.cfg">Search</A>
        and the configuration file contains the line: 
        indexes=-Book2Sen
        The search form will display both Book1Sen and Book2Sen.

      lang Instructs the search form CGI in what language to display the search form.

      Example: If you want the search page to be displayed in German, insert the following line in the configuration file: 

      	lang=de_DE

      Any locale supported by the Documentation Search Service can be specified by inserting a lang=locale file entry in the configuration file. See the Language Support Table for more information on possible values for the lang parameter.

      Note: Only one value for lang can be specified at a time. Do not include more than one lang entry in a configuration file. The language suffix of any index name specified in an indexes= entry, must match the language specified in the lang= entry or the indexes will not be shown on the Search Form.

      results_title Instructs the search form CGI what to display as the title of the search results page.

      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: 

      results_title=Results of My Search
      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.

      search_page Redirects the web browser to another URL without changing the HTML link in the document.

      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: 

      search_page=http://my.other.site/mypath/mypage.html
      Note: Specifying a search_page configuration will cause all other settings to be ignored.

      title Instructs the search form CGI what to display as the title of the search form page.

      Example: If you want the title of the search form to be Search My Documents, you might insert the following in your configuration file: 

      title=Search My Documents
      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.

    2. Configuration file entries of the type: 
      	configuration_begin
	<your HTML code>
	configuration_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.

      search_top Replaces the default HTML header of the search form page with the HTML code between the search_top_begin and search_top_end tags.

      Example: If you want the top of your search form page to contain an image named myimage.gif which is in the web server's /images directory, and the title of your search form page to be Search My Documents, you might insert the following in your configuration file: 

      search_top_begin
<HTML>
<HEAD>
<TITLE>Search My Documents</TITLE>
<BODY>
<CENTER><IMG SRC="/images/myimage.gif"></CENTER>
<P>
search_top_end
      Note : Any title parameter or title configuration file entry specified will be ignored.

      search_bottom Replaces the default HTML footer of the search form page with the HTML code between the search_bottom_begin and search_bottom_end tags.

      Example: If you want the bottom of the search form page to have a MAILTO link so that users can send mail to you, you might insert the following in your configuration file: 

      search_bottom_begin
<HR><P>
<CENTER><A HREF="MAILTO:me@my.site"></CENTER>
</BODY>
</HTML>
search_bottom_end

      results_top Replaces the default HTML header of the results page with the HTML code between the results_top_begin and results_top_end tags.

      Example: If you want the top of your results page to contain an image named myimage.gif which is in the web server's images directory, and the title of your results page to be Results of My Search, you might insert the following in your configuration file: 

      results_top_begin
<HTML>
<HEAD>
<TITLE>Results of My Search</CENTER>
<BODY>
<CENTER><IMG SRC="/images/myimage.gif"></CENTER>
<P>
results_top_end
      Note: Any title parameter or title configuration file entry specified will be ignored.

      results_bottom Replaces the default HTML footer of the results page with the HTML code between the results_bottom_begin and results_bottom_end tags.

      Example: If you want the bottom of the results page to have a MAILTO link so that users can send mail to you, you might insert the following in your configuration file: 

      results_bottom_begin
<HR><P>
<CENTER><A HREF="MAILTO:me@my.site"></CENTER>
</BODY>
</HTML>
results_bottom_end

  2. Insert Search links into your documents

    Insert into your documents the Search links that specify a configuration file to generate your custom search form. See the previous section for information on specifying a configuration file in an HTML link.

Creating Indexes of your Documentation

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.

Before beginning to create your indexes, make sure you meet the following requirements

Building the indexes

Each index you create will have its own selection checkbox in the search form. Typically, you create one index that contains text from multiple documents. 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:

  1. Choose a unique index name

    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 conflicts, it is recommended that certain naming conventions be followed:

  2. Create a new directory

    Create a new directory to hold the documents that will go into the index. We will call this directory the build directory. The build directory can be any place you want it. In our examples we are building indexes for a calculator application, so our build directory will be named /usr/work/calculator. Inside this build directory, arrange the documents into a directory tree structure exactly as you want them to be installed/placed relative to each other on a documentation search server computer.

    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 one rule about the pathnames is that the first directory in the permanent part of the pathname must be the index name.

    For example, your application is called calculator. The online documents for the application are written in US English. There are two user guide documents (doc1, doc2) and one administrator document (doc3). All three documents will go into a single index named cal413en. You could place the documents like this in the filesystem on the computer on which you are building the indexes:

    /usr/work/calculator/cal413en/user/doc1.html
/usr/work/calculator/cal413en/user/doc2.html
/usr/work/calculator/cal413en/admin/doc3.html

    You can place your build directory anywhere, but all documents that go into a single index must be placed under the index_name directory which acts as the common top directory so that they form a single tree. In the example, cal413en is the common top directory.

  3. Create an ASCII file

    For each index, create a document list file. Place inside this file a list of all the documents you want to be in the index. For each document, list it by using the full pathname that specifies where the document can be currently found on your development computer. Note that the working locations of these documents do not need to be the same location where the documents will be eventually installed on a documentation server. This document list file can be named anything and placed in any directory. Put each pathname on its own line in the file.

    If you arranged your documents like the example above, your ASCII file would have the following contents:

    /usr/work/calculator/cal413en/user/doc1.html
/usr/work/calculator/cal413en/user/doc2.html
/usr/work/calculator/cal413en/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 (the build directory pathname) with a commercial at symbol (@). When the index is created, only the part of each pathname that is to the right of the @ will be saved in the index.

    For example, the above example file would now be modified to look like this:

    /usr/work/calculator@cal413en/user/doc1.html
/usr/work/calculator@cal413en/user/doc2.html
/usr/work/calculator@cal413en/admin/doc3.html

    The slash after the application name (calculator) was replaced with an @ since it is the last slash in the temporary part of the path.

  4. Choose a title for your index

    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 150 characters.

  5. Create an empty index

    You must then create an empty index. After the index is created you will fill it. To prepare for index creation, you must check the following:

    1. Single-Byte Languages

      The index creation command for a single-byte language has the syntax (Type the following three command parts, all on one command line with a space between each part):

      /usr/IMNSearch/cli/imnixcrt  index_name 
/usr/docsearch/indexes/index_name/data  
/usr/docsearch/indexes/index_name/work  WT

      where index_name is the 8 character name of the index and the last argument is WT.

      Following our example, to create a single byte English index, you could type (Type the following three command parts, all on one command line with a space between each part): 

      /usr/IMNSearch/cli/imnixcrt  cal413en 
/usr/docsearch/indexes/cal413en/data 
/usr/docsearch/indexes/cal413en/work  WT
      Note: After you create your index, you should check to make sure that your index is listed with the Documentation Search Service in /usr/IMNSearch/cli/imnixlst.

    2. Double-Byte Languages

      To create indexes for double-byte documents, replace imnixcrt in the above command with imqixcrt. Then add a space after WT in the command and add a 3 letter language id to identify the language of the documents being indexed. The language IDs are listed in the table below. The index creation command for a double-byte language has the syntax (Type the following three command parts, all on one command line with a space between each part):

      /usr/IMNSearch/cli/imqixcrt  index_name>
/usr/docsearch/indexes/index_name/data 
/usr/docsearch/indexes/index_name/work  WT  language_ID
      Language language_ID
      Chinese Simplified CHS
      Chinese Traditional CHT
      Japanese JAP
      Korean KOR
      Note: After you create your index, you should check to make sure that your index is listed with the Documentation Search Service in /usr/IMNSearch/cli/imqixlst.

      As an additional example, to create a Japanese double-byte index, you could type the following (Type the following three command parts, all on one command line with a space between each part):

      /usr/IMNSearch/cli/imqixcrt  cal413jp 
/usr/docsearch/indexes/cal413jp/data
/usr/docsearch/indexes/cal413jp/work  WT  JAP

  6. Add your Documents to the Update List

    Next you must tell the Documentation Search Service the name of the file that contains the list of the documents that will go into the the empty index you just created. Then later you will run an update command and those documents will be indexed and the results will be inserted in the index.

    1. Single-Byte Languages

      Use the following command to add your documents to the list of documents that will get inserted into the index (where document_list_file is the name of the ASCII file you created that contains your list of documents):

      /usr/IMNSearch/cli/imndoadd  index_name  document_list_file
      Note: Test to make sure that your documents were added successfully. Type: /usr/IMNSearch/cli/imnixsta. The number after scheduled: should equal the number of documents in your index.

    2. Double-Byte Languages

      Use the following command to create the document list (where document_list_file is the name of the ASCII file you created that contains your list of documents):

      /usr/IMNSearch/cli/imxqoadd  index_name  document_list_file
      Note: Test to make sure that your documents were added successfully. Type: /usr/IMNSearch/cli/imqixsta. The number after scheduled: should equal the number of documents in your index.

  7. Start the index updating process to build your index

    Start the index updating process. This will take the documents that are in your document update list, index them, and put the results into the empty index to build your final complete index.

    Note: Indexing may take a significant amount of time to complete. You CANNOT move onto the "Update the registration table" step until indexing is complete. Use the status command below to tell when indexing is done.
    1. Single-Byte Languages

      Use the following update command:

      /usr/IMNSearch/cli/imnixupd  index_name
      Note: Test to make sure that you documents were added successfully. Type: /usr/IMNSearch/cli/imnixsta. The number after primary: should equal the number of documents in your index.

    2. Double-Byte Languages

      Use the following update command:

      /usr/IMNSearch/cli/imqixupd  index_name
      Note: Test to make sure that you documents were added successfully. Type: /usr/IMNSearch/cli/imnixsta. The number after primary: should equal the number of documents in your index.

  8. Update the registration table

    Next you need to register the new index in the registration table of your development computer so that the search service knows the index exists and you can do a test searches of the index.

    To update the registration table on the development computer, do the following (Type the following three command parts, all on one command line with a space between each part):

    Note: There must be a final slash (/) after the application_name.
    1. Single-Byte Languages 
      /usr/IMNSearch/cli/imndomap 
/var/docsearch/indexes  -c  index_name 
/doc_link/locale/application_name/   index_title

    2. Double-Byte Languages 
      /usr/IMNSearch/cli/imqdomap 
/var/docsearch/indexes  -c  index_name 
/doc_link/locale/application_name/   index_title

    The locale variable is the name of the language directory under /usr/share/man/info where the index's documents are stored. The variable index_name is the name of your index, and index_title is the search form title of your index. The title is the text you want the user to see in the bottom of the search form when they are selecting which indexes to search. Remember that the title should be written using the same language and codeset as the documents inside the index.

    Additionally, for index titles, it is recommended that you specify the title as an HTML link. The title will then appear as a link in the search form. This allows a user to click on the title in the search form to open the first document in the index for reading.

    Note:

    Every web server has an internal document home directory where it starts its search for documents. 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 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.

    The link that the Documentation Search Service puts into your web server's starting directory is:

    	doc_link  ->  /usr/share/man/info

    Your web server will be able to serve the documentation with URLs like:

    	http://your.machine.name/doc_link/en_US/calculator/user/doc1.html

    For example, you might want the title of your index to be "Calculator Application Manuals". You have three documents(manuals) inside this one index which is named cal413en. You decide that when the title link is clicked it would be best for the Beginners Guide document to be opened. So, you would insert in the title the URL that opens the Beginners Guide document. If you would normally type the URL /doc_link/en_US/calculator/cal413en/user/doc1.htm (doc_link is the link to the /usr/share/man/info directory in AIX) to open the Beginners Guide document, you would use the following update command (Type the following three command parts, all on one command line with a space between each part):

    /usr/IMNSearch/cli/imndomap 
/var/docsearch/indexes  -c  cal413en 
/doc_link/en_US/calculator/
"<A HREF='/doc_link/en_US/calculator/cal413en/user/doc1.htm'>
Calculator Application Manuals</A>"

    Next, you need to copy the new index registration table over the backup copy of the index registration table. You must do this because the Documentation Search Service sometimes requires two copies of the table to process. Type:

    cp  /var/docsearch/indexes/imnmap.dat  /usr/docsearch/indexes

  9. Copy your HTML documents from the build directory into the documentation directory

    You must now copy your HTML documents into the location where they can be read by your users. Your documents should be placed under the directory /usr/share/man/info/locale/application_name/index_name. Using our example, the Calculator Application's English documents would be placed in /usr/share/man/info/en_US/calculator/cal413en.

    1. Find out if the language directory /usr/share/man/info/locale already exists. If it does not exist, create it. When you create this directory, make sure that it is executable and readable by all users.

      Using our example, the English directory is named: /usr/share/man/info/en_US.

    2. Create your application directory under the language directory. The directory structure should now look like: /usr/share/man/info/locale/application_name.

      Using our example, the application's directory is named: /usr/share/man/info/en_US/calculator.

    3. Copy the build subdirectory that contains your documents and place it under the application directory you just created. The directory structure should now look like:

      /usr/share/man/info/locale/application_name/index_name/documents.

      Using our example, you would use the following command to copy the calculator's documents from the build directory into the directory where they will be read by users (Type the following three command parts, all on one command line with a space between each part): 

      cp -R /usr/work/calculator/cal413en 
/usr/share/man/info/en_US/calculator/cal413en

      The calculator's documents would then end up in these locations: 

      /usr/share/man/info/en_US/calculator/cal413en/user/doc1.html
/usr/share/man/info/en_US/calculator/cal413en/user/doc2.html
/usr/share/man/info/en_US/calculator/cal413en/admin/doc3.html

  10. Test your Index

    You have now completed the creation and registration of an index on this development computer. You should now test the index by opening the search form, selecting the new index for search, and searching for words that you know are in the index. If the index does not work properly and you need to remove it so you can build it again, go to the section called Removing Indexes in your Documentation. When you are satisfied that the index is working correctly, go on to the next step:

  11. What to do Next

  12. Copy and register the index to the documentation server

    On the computer where you just created your index, do the following steps.

    1. Type the command: 
      cd  /usr/docsearch/indexes
    2. An index is not a single file, it is really a collection of files. You need to create a tar file that contains copies all of the files that make up your index. To create the tar file, type this command: 
      tar  cvf  index_name.tar  index_name
    3. Next move this tar file to the documentation server by using the ftp command to put it into the /usr/docsearch/indexes directory on the destination machine.
      Note: Be sure to transfer the tar file in binary mode.
    4. Log on to the destination documentation server as root.

    5. Type the command: 
      cd  /usr/docsearch/indexes
    6. Untar the tar file. 
      tar  vxf  index_name.tar
    7. Change the ownership of the indexes. 
      chown  -R  imnadm:imnadm  index_name
    8. Stop the search server.

      1. Single-Byte Indexes 
        imnss  -stop  imnhelp

      2. Double-Byte Indexes 
        imqss  -stop  dbcshelp

    9. Update the master table.

      1. Single-Byte Indexes

        Type (Type the following three command parts, all on one command line with a space between each part):

        imnmtupd  /etc/IMNSearch  
	/usr/docsearch/indexes/index_name/data
	/usr/docsearch/indexes/index_name/work  index_name

      2. Double-Byte Indexes

        Type (Type the following three command parts, all on one command line with a space between each part):

        imqmtupd  -m  /etc/IMNSearch/dbcshelp  -i  
	/usr/docsearch/indexes/index_name/data  -w 
	/usr/docsearch/indexes/index_name/work  -n  index_name

    10. Restart the search server.

      1. Single-Byte Indexes 
        imnss  -start  imnhelp

      2. Double-Byte Indexes 
        imqss  -start  dbcshelp

    11. Next, you need to register the new index in the registration table of your documentation server computer so that the search service knows the index exists and you can do a test search of the index.

      To update the registration table on the development computer, do the following (Type the following three command parts, all on one command line with a space between each part):

      Note: The following command must end with a slash (/) after the application_name.
      1. Single-Byte Languages 
        /usr/IMNSearch/cli/imndomap  
	/var/docsearch/indexes  -c  index_name 
	/doc_link/locale/application_name/  index_title

      2. Double-Byte Languages 
        /usr/IMNSearch/cli/imqdomap 
	/var/docsearch/indexes  -c  index_name 
	/doc_link/locale/application_name/  index_title

      The locale variable is the name of the language directory under /usr/share/man/info where the index's documents are stored. The variable index_name is the name of your index, and index_title is the search from title of your index. The title is the text you want the user to see in the bottom of the search form when they are selecting which indexes to search. Remember that the title should be written using the same language and codeset as the documents inside the index.

      Additionally, for index titles, it is recommended that you specify the title as an HTML link. The title will then appear as a link in the search form. This allows a user to click on the title in the search form to open your primary document in the index for reading.

      For example, you might want the title of your index to be "Calculator Application Manuals". You have three documents (manuals) inside this one index which is named cal413en. You decide that when the title link is clicked it would be best for the Beginners Guide document to be opened. So, you would insert in the title the URL that opens the Beginners Guide document. If you would normally type the URL /doc_link/en_US/calculator/cal413en/usr/doc1.htm (doc_link is the link to the /usr/share/man/info directory in AIX) to open the Beginners Guide document, you would use the following update command (Type the following three command parts, all on one command line with a space between each part):

      /usr/IMNSearch/cli/imndomap  
	/var/docsearch/indexes  -c  cal413en  
	/doc_link/en_US/calculator/
	"<A HREF='/doc_link/en_US/calculator/cal413en/usr/doc1.htm'>
	Calculator Application Manuals</A>"
    12. Next, you need to copy the new index registration table over the backup copy of the index registration table. You must do this because sometimes the Documentation Search Service needs two copies of the table to process.

      Type:

      cp  /var/docsearch/indexes/imnmap.dat  /usr/docsearch/indexes

      You have now finished the copy and registration of the index on the documentation server. You should do test searches of the index to make sure it is working correctly.

Removing Indexes in your Documentation

You cannot just delete files to remove an index from a server. This will leave the search service corrupted. Use the following steps to remove an index:

  1. Delete the index.

    For single-byte languages, type:

    /usr/IMNSearch/cli/imnixdel  index_name

    For double-byte languages, type:

    /usr/IMNSearch/cli/imqixdel  index_name
  2. Remove the index entry in the registration table.

    1. Single-Byte Languages 

      /usr/IMNSearch/cli/imndomap  /var/docsearch/indexes  -d  index_name

    2. Double-Byte Languages 

      /usr/IMNSearch/cli/imqdomap  /var/docsearch/indexes  -d  index_name

  3. Copy the changed index registration table over the backup copy of the index registration table so that the backup copy is updated.

    Type: 

    cp  /var/docsearch/indexes/imnmap.dat  /usr/docsearch/indexes

  4. Then delete the empty index directories that held the index files: 
    rm  -r  /usr/docsearch/indexes/index_name

Packaging your application's indexes with your application's documentation

To include the search index in your application's AIX installp installation package, you will need to complete the following steps:

Note: You must repeat these steps for each separately installable fileset in your package that contains one or more indexes.

  1. Create Install Script

    You must perform the following steps to create a registration script. This script will automatically register your indexes with the Documentation Search Service during the installation of your application's AIX installp installation package. You will be using and modifying an example script to create your own registration script.

    1. Make a copy of the example script /usr/docsearch/tools/index_config.sh. You can use any name for the copy.

    2. Edit the script and change:

      Note: The script is designed to install one or more indexes. In each of the following variables, replace the X character with the number for the index you are specifying.
      1. index_type to DBCS if you are registering double-byte codeset indexes.

      2. indexdir_name_X to the name of your index (repeat for each index).

      3. index_title_X to the title of your index.

      4. index_loc_X to /usr/docsearch/indexes. This is where installp will be placing your index when your application is installed in AIX.

      5. document_loc_X to the temporary portion of the document path. This path segment must begin and end with a slash (/).

      Example: To install the indexes Book1Sen and Book2Sen, which are being installed in /usr/docsearch/indexes/Book1Sen and /usr/docsearch/indexes/Book2Sen, have the titles Book #1 and Book #2, and whose documents are in /usr/share/man/info/en_US/calculator/... you might have lines in the script like:

      indexdir_name_1="Book1Sen"
indexdir_name_2="Book2Sen"

index_title_1="<A HREF='/doc_link/en_US/calculator/Book1S.html'>Book #1</A>"
index_title_2="<A HREF='/doc_link/en_US/calculator/Book2S.html'>Book #2</A>"

index_loc_1="/usr/docsearch/indexes/Book1Sen"
index_loc_2="/usr/docsearch/indexes/Book2Sen"

document_loc_1="/doc_link/en_US/"
document_loc_2="/doc_link/en_US/"

    3. Delete all other indexXXX variable assignments from the script. There should only be as many lines of the form indexdir_name_X="..." as there are indexes you want to install. The same holds true for index_title_X, index_loc_X, and document_loc_X.

  2. Create the uninstall script

    Create the uninstall script that will cleanly unregister your index if your application is uninstalled.

    1. Make a copy of the unconfig script in /usr/docsearch/tools/index_unconfig.sh

    2. Edit the script and change index_type to DBCS if the indexes you are unregistering are double-byte indexes.

    3. Edit the script and change indexdir_name_X to the name of your index (repeat for each index).

    4. Delete all other indexdir_name_X variable assignments from the script. There should only be as many lines of the form indexdir_name_X="..." as there are indexes you want to uninstall.

  3. Create the pre_rm script

    Create the pre_rm script that will cleanly unregister your index when your application is reinstalled using a force install or updated in preparation for installing new versions of your index.

    1. Make a copy of the pre_rm script that is in /usr/docsearch/tools/index_pre_rm.sh

    2. Edit the script and change index_type to DBCS if you are unregistering any double-byte indexes.

    3. Edit your copy of the script and change indexdir_name_X to the name of your index (repeat for each index).

      Example: If you have two indexes with the names cal413en and cal567en, your copy of the pre_rm script would have lines like: 

      indexdir_name_1="cal413en"
indexdir_name_2="cal567en"

    4. Delete all other indexdir_name_X variable assignments from the script. There should only be as many lines of the form indexdir_name_X="..." as there are indexes in your fileset.

  4. Create an AIX install package

    Create a normal AIX install package for your documentation or application. If you need instructions on how to create an AIX install package, see "Packaging Software for Installation".

    In addition to the normal packaging steps, do the following:

    1. Place the install script in your installp package so that it will be run in your post-install process when the fileset containing the index is installed.

    2. Place the uninstall script in your installp package so that it will be run in your uninstall process when the fileset containing the index is uninstalled.

    3. Place the pre_rm script in your installp package so that it will be run when the fileset containing the index is uninstalled.

    4. If you are using configuration files, have your package create your application's config directory, put your configuration file(s) there, and set permissions for the directories and configuration files.

    5. During installation, have your package install your documentation and indexes.

[ Previous | Next | Contents | Glossary | Home | Search ]