General Programming Concepts:
Writing and Debugging Programs

Packaging your Application's Documentation

Include a Search Index

To include a search index in your application's 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.

Create the install script
You must perform the following steps to create a registration script. This script will automatically register your indexes with the Documentation Library Service during the installation of your application's 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.
  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.
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.
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.

Register your Documentation

To have your application's installp installation package automatically register your documentation into a view you will need to complete the following steps:

Ship your configuration file to the appropriate directory in /usr/docsearch/views
See the section titled Create a View Set Configuration File.
Create a view definition file for every view in which you want your documents to appear
See the section titled Create a View Definition File.
Modify the install script After the call to /usr/sbin/index_config.sh, put a line to register a view definition file for each view into which you want to register your documentation.
See the section titled Register the Contents of each of your View Definition Files.
Modify the uninstall and pre_rm scripts After the call to /usr/sbin/index_config.sh, put a line to unregister a view definition file for each view into which you registered your documentation.
See the section titled Register the Contents of each of your View Definition Files.

Create an install package

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

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

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.
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.
Place the pre_rm script in your installp package so that it will be run when the fileset containing the index is uninstalled.
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.
During installation, have your package install your documentation and indexes.

Packaging Book Guidelines