The K Desktop Environment

13.5. Documentation

13.5.1. Directories

For setting up the documentation browser to work correctly, KDevelop needs some information about where the HTML- documentation is placed on the system. Therefore, the Documentation Path properties dialog needs the path of the Qt- online documentation in HTML as well as the path to the KDE-library documentation.

Usually, the Qt-documentation is placed in the same directory where Qt is installed; e.g. if Qt resides in /usr/local/qt, the path you have to enter is /usr/local/qt/html. For the KDE- Documentation, you have to set the directory to the root of the documentation, assumed all KDE-Libs documentation resides in the same directory. Both path's can be selected by pressing the according buttons, displaying a path-selection. If your system doesn't contain the documentation for the KDE-libs, you should first enter the next configuration dialog, Update KDE-Documentation. This will create the documentation to a path of your choice, also setting the KDE Library Doc path automatically.

13.5.2. Options

13.5.2.1. Update KDE-Documentation

For those users who don't have a recent documentation of the KDE-libraries, especially the documentation for the files installed on the system, the Update KDE-Documentation dialog creates a new one or updates existing documentations. This function requires your system to have kdoc and qt2kdoc installed, included in the kdesdk package. First of, you have to set up the path to your recent kdelibs sources, which is not the include-path for KDE ! Just enter the path to the sources, like: /home/rnolden/kdelibs-1.1/.

Then, you can choose three different installation modes, as:

  • Delete old Documentation and install to recent Documentationpath: this assumes that youalready have a documentation installed and is placed in the path the Documentation Path-dialog was entered. This will delete all documentation and install the newly generated documentation into the recent path.

  • Delete old Documentation and install to new Documentationpath: this will result in deleting the old documentation as well as above, but gives you the choice to set up a new documentation place.

  • Leave old Documentation untouched and install to new Documentation path: This is recommended for a new generation of the kdelibs documentation for users who didn't have one before and for those who want to keep the last documentation for an older kdelibs version.

The "new KDE Libs Documentation path" is to be set for option 2 and 3 of the installation mode. This is also recommended for users who generate a new documentation from scratch.

After pressing the OK button, KDevelop will create a subdirectory "kdoc-reference" in the documentation path containing the kdoc reference files. First, the qt library documentation classes will be indexed to connect the Qt documentation with the documentation to be generated for the kdelibs. So it is important that you have set up the Qt documentation path first to ensure that it can be found by qt2kdoc. Finally, the KDE libs will be indexed and the documentation will be build with crossreferences to give browsing the most functionality.

13.5.2.2. Create Search Database

The Create Search Database dialog, accessed via the create-button, allows the programmer to create a database to search for a keyword interactively. To create and use the documentation search function, you must have the program glimpse 4.1 installed. Preset are the options to index the given KDE-library documentation as well as the Qt-documentation, assuming the path to the documentation files were set in the "Documentation Path" dialog of the options- menu. Additionally, the index can include directories the user can set up himself by the "additional directories to index"-field. After setting a path to an addional directory, the "Add" - button must be pushed to set the path. A path once set can be removed from the index by selecting the path in the path field and pushing "Remove". Furthermore, the user is offered three different modes for the index size: tiny, small and medium. The higher the index size, the more the index files will grow. On the other hand, a search in a bigger searchdatabase will be faster and more successful, so we suggest choosing a "medium" size. For using the search function, see section Using the Documentation Browser.