[ Next Article | Previous Article | Book Contents | Library Home | Legal | Search ]
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 read and searched within the library service application. Two things must occur before a document can be accessed using the Documentation Library Service:

  1. The document and its index must be created or installed on the document server; and,

  2. The document and its index must be registered with the library service.

You can register documents two ways:

This section gives an overview of the steps to register a document and create an index of the document. When you are ready to actually do this work, see Documentation Library Service in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs for the detailed instructions on completing these steps.

  1. Write your document in HTML.

  2. Create the index of the document.

  3. If you are an application developer who is creating this index for inclusion in an installp package, see Documentation Library Service in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs and 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. Now register the index. After your indexes are registered, they will display for reading and searching in the global Documentation Library Service application that is launched by typing the docsearch command or by opening the Documentation Library Service icon in the CDE Desktop. You can also create your own custom library application that only shows a subset of all registered documents on a documentation sever. For example, you may want a library application that only shows accounting documents. For instructions, read the section on creating your own custom library applications in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs

    For detailed instructions on creating and registering a document and index, see Creating Indexes of your Documentation in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.

Deleting or Uninstalling Documents

If a document and its index were automatically registered when an application was installed on the documentation server, you must use the operating system's normal software uninstall tools to remove the document. If you simply delete a registered document or its index, it will still be registered with the library 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, follow the instructions in Removing Indexes in Your Documentation in 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. Rebuild the index. See Building the Index in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs for more information.

Moving Documents

You should not move application documents that were automatically installed with an application. For example, you should not move operating system base documentation after it is installed. If you move automatically registered documents, the search service will be unable to find the documents and errors will occur.

You can move documents that you wrote and manually indexed and registered. However, when you move a document, you must tell the search service how that document's path has changed so that the service can 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.
  3. If your document is written in a single-byte language, type the following two commands, pressing Enter after each:
    /usr/IMNSearch/cli/imndomap
    /var/docsearch/indexes -u <index_name>  /<path>/  <index_title>
  4. If double-byte language, type (all on one line):
    /usr/IMNSearch/cli/imqdomap
    /var/docsearch/indexes -u <index_name> /<path>/ <index_title>

    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.
  5. Next, copy the index registration table with the changed entry over the backup copy of the registration. Type:
    cp /var/docsearch/indexes/imnmap.dat /usr/docsearch/indexes

    then press Enter. You must do this because the Documentation Library Service sometimes requires two copies of the table to process.

    Changing of the document's library service location is now complete. If you haven't already done so, you can now move your documents. Next, 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

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:


[ Next Article | Previous Article | Book Contents | Library Home | Legal | Search ]