[ Previous | Next | Contents | Glossary | Home | Search ]
AIX Version 4.3 System Management Guide: Operating System and Devices

Documents and Indexes

This section covers system management operations on documents and indexes for the documentation search service:

Registering Documents for Online Searching

Not all documents on a documentation server can be searched. Two things must occur before a document can be searched using the Documentation Search Service:

  1. An index of the document must be created on the server, and
  2. The index must be registered with the search service.

Documents are registered in two ways:

  1. If an application ships pre-built indexes for its documents, the indexes may be automatically registered when they are installed on your system, or
  2. A system administrator may manually create indexes for documents that are already on the server and then manually register the indexes.

To create an index, you will complete the following steps. When you are ready to create the index, see the chapter Documentation Search Service in the AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs book for more information.

  1. Write your document in HTML.
  2. Create the index.
  3. If you are an application developer who is creating this index for inclusion in an installp package, your next step is to go to the Documentation Search Service section in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs. Follow the steps to include the index in your installation package and do automatic registration of your indexes during your package's post-installation process.

    If you are the system administrator of a documentation server, the next step is to register the new indexes on the server.

  4. Register the index.

    After your indexes are registered, they will appear for searching in the global Documentation Search Service search form that is launched by typing the docsearch command or by opening the Documentation Search Service icon in the CDE Desktop. You can also create your own custom search form that only shows a subset of all registered indexes. For instructions, read the section on creating your own search forms in the Documentation Search Service chapter in the AIX 4.3 General Programming Concepts book.

    For detailed instructions on creating and registering an index, see the chapter Documentation Search Service in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs for more information.

Deleting or Uninstalling Documents

If a document and its index were automatically registered when an application was installed on the server, you must use the uninstall process to remove the document. If you simply delete a registered document or its index, it will still be registered with the search service. This will generate error messages during searches since the search service will still try to search the missing index.

Note: If you uninstall a package and it does not correctly remove all its indexes, use the procedure below to clean up your system.

If you want to delete a document that was manually registered by the system administrator, see the instructions in section Removing Indexes in Your Documentation, AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.

Updating Documents

If a document's contents change, the index of the document must be updated to reflect the changes to the contents of the document.

If you are installing an updated application and it automatically registers its documents, it should automatically update the old indexes with the new ones.

If you are updating a document that a user created, you will have to manually update the index for the document.

  1. Unregister and delete the old index. You cannot just delete an index. This will leave the search service corrupted. Follow the procedure in Removing Indexes in Your Documentation in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs
  2. Re-build the index. See Building the Index in the chapter Documentation Search Service for more information.

Moving Documents

You should not move application documents that were automatically installed with an application. For example, you should not move AIX Base documentation after it is installed. If you move automatically registered documents, the search service will not be able to find the documents and error messages will occur.

You can move documents that you wrote and manually indexed and registered. But when you move a document, you must tell the search service how that document's path has changed or the service will no longer be able to find the document.

The first part of a document's path is stored in the index registration table, and the last part is stored inside the index for that document. There are two methods for changing a document's path depending on which part of the path you are changing.

To determine which method you need to use, type, as root (or a member of the imnadm group>, the following command:

  1. /usr/IMNSearch/cli/imndomap /var/docsearch/indexes -l <index_name>

    where <index_name> is replaced with the name of the index that contains the documents you want to move.

    The command will output something like this: 

    Index <index_name> - <index_title>,
documents in: <path>
NetQ function completed.

    The <path> in the output shows you the part of your document's path that is stored in the registration table. If you are only changing the names of directories that are listed within the <path>, you can use the first move method described below. Write down the current index_name, index_title, and path. Then skip to the next numbered step to change this part of the document path.

    However, if you need to change any part of the path that is lower (to the right) of the part of the path shown in the output, you must instead update the index. This is because the  lower part of the path is stored inside the index. To update the index, go back to the Updating Documents section and complete all the instructions in that section. You should also go to that section if you need to make changes in both the upper and lower parts of the document path. In either case, you do not need to do any other steps in this section.

  2. To change the upper part of the document's path in the index registration table, type the following two command parts. These two parts must all be typed on one command line with a single space between each part.
    Note: There must be a final slash (/) after the <path> as shown below.
    In the above commands you replace the "/<path>/" part of the command with the new path where you moved your document.  You replace <index_name> and <index_title> with the values you wrote down from the output of the command in the first step.

    For example, your documents are in the acctn3en English(single-byte) index and the index title is "Accounting Documents". You moved these document's tree from the /doclink/en_US/engineering directory into the /doclink /en_US/accounting directory. You would type (all on one line): 

    /usr/IMNSearch/cli/imndomap
    /var/docsearch/indexes -u acctn3en
    /doc_link/en_US/accounting/  Accounting Documents
    Note: If you need to, you can change the index title by typing a new title in the above command. You cannot change the index_name.

  3. Next, you need to copy the index registration table with the changed entry over the backup copy of the regsitration. 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
Changing of the document's search service location is now complete. If you haven't already done so, go ahead and move your documents. Next you should test your changes by searching for a word that is inside the moved documents. The document's link in the search results page should correctly display the document.

Security

You should follow your normal security procedures for the documents on the documentation server.In addition, a documentation server also has the added security elements of the document indexes and the webserver software.

Indexes should be treated as files that include a list of all the words in the original documents. If the documents contain confidential information, then the indexes themselves should be treated with the same care as the documents.

There are three levels of security you can set up for indexes:

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