This section covers system management operations on documents and indexes for the documentation search service:
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:
The document and its index must be created or installed on the document server; and,
You can register documents two ways:
If an application ships pre-built indexes for its documents, you can register the indexes automatically when you install them on your system; or,
You can manually create indexes for documents that are already on the server and then manually register the indexes.
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.
Write your document in HTML.
Create the index of the document.
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.
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.
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.
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.
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.
Rebuild the index. See Building the Index in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs for more information.
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:
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.
Note: There must be a final slash (/) after the <path> as shown below.
/usr/IMNSearch/cli/imndomap
/var/docsearch/indexes -u <index_name> /<path>/ <index_title>
/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.
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.
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:
By default, the permissions on the indexes directory are set so that all webserver users can both search and read all index files.
All webserver users can search inside indexes for key words, but cannot open an index file to directly read its contents. This makes it more difficult for users to obtain confidential data, but a person can sometimes still gain a lot of information just by knowing if certain key words are inside a document. Assuming you store all your indexes in the standard location, you can set this level of security by setting the permissions of the /usr/docsearch/indexes directory. It is set to the user:group imnadm:imnadm with all permissions for others disabled so that only members of the imnadm search administration group can read the index files. To set these permissions type the following two commands:
chown -R imnadm:imnadm /usr/docsearch/indexes
chmod -R o-rwx /usr/docsearch/indexes
Note: The user imnadm must always be able to read and execute the directory where you store indexes. This is because the search engine runs as user imnadm when it searches inside indexes.
This is done by setting the permissions as in level two above (to prevent reading of index files). In addition, a user's permission to use the search service webserver is disabled (this prevents searches). The user will be unable to search indexes because the webserver will not let them open the search form. This security level is set up using the administration functions in your webserver software to turn off a user's permission to use the webserver. See the documentation that came with your webserver to determine how to configure your webserver software to prevent access by specific users.