# Configuring &kdevelop;

&kdevelop; is a very powerful and flexible IDE which offers many ways to taylor it to your needs. To start configuration select Settings Configure KDevelop.... This will cause the configuration dialog to pop up consisting of a selection window to the left and the configuration dialog on the right hand side whose contents will vary upon the configuration item you did select.

Select a configuration item

We will discuss these configurations in a different order, split up into the main topics of General Configuration, Configuring the Documentation Tree, and Advanced Configuration which makes for a more intuitive reading.

If you want directly look up a certain configuration item use one of the following links.

- General
- Plugins
- Source Formatter
- User Interface
- Editor
- Abbreviations
- Tools Menu
- External Tools
- Code Snippets
- File Selector
- Documentation Tree

## General Configuration

General configuration concerns the more common tasks of tayloring &kdevelop; as there are:

- General Setup

- Selecting the User Interface

- Source Edit Tasks

  - Selecting an Editor

  - Selecting a Source Format Style

  - Setting Up the Code Snippets Tool

- Configuring the File Selector

### General Setup

The General configuration dialog allows you to define some basic &kdevelop; behaviour which seldom will change in everyday work. This concerns:

- General project options as

  - defining a default parent directory &kdevelop; shall use for new projects.

  - deciding whether you want &kdevelop; to automatically load the project you last worked on.

- Selecting a font for the most commonly used output view windows, namely

  - the Messages Output View &kdevelop; uses to communicate ⪚ compilation progresses, and

  - the Application Output View which will show error and state information concerning a running application.

- Some common behaviour concerning the displayed lines in the Messages Output View window, namely

  - whether long lines will wrap around, and

  - if directory entry and exit messages issued by `Make` will be shown.

- The level of detail of messages concerning the compilation process shown in the Messages Output View window.

The general configuration dialog

### Load Last Project on Startup

Mark this checkbox if you want to continue to work with the last project you worked on. This will cause &kdevelop; to automatically load this project on start-up. It will usually be shown in the state you left work so you can readily proceed.

### Default Projects Directory

By default, &kdevelop; uses a common parent directory for all new projects. Enter the absolute path of this common directory in the box or select it from your directory structure. &kdevelop; will place the any new project here as a subdirectory.

You may of course change the directory path of a new project at the time you set it up in the &appwizard;.

### Messages Output View Window Font

To select a font suitable for the Messages Output View window click the Window Font button showing the currently selected font (it says Luxi Sans in the above illustration). The &kde; standard Select Font dialog will pop up from which you may select the font to be used.

On first start-up, &kdevelop; initializes this font setting to the standard font for which your &kde; user has been configured. This setting is fixed, so if you alter Preferences Appearances & Themes Fonts in the Control Center, this will not effect this &kdevelop; font selection. You will have to explicitely reselect the Messages Output View window font.

### Line Wrapping

By default, &kdevelop; will wrap long lines around in the Messages Output View window so that valuable information will not be easily overlooked. In some cases this will clutter long message lists. Remove the checkbox mark if you do not want the lines wrap around.

There is an alternative way to switch the line wrapping. Just right click in the Messages Output View window and mark/unmark the Line Wrapping entry in the menu which will pop up.

### Directory Navigation Messages

The `Make` tool usually will display messages like Entering directory, or Leaving directory when it switches the directories it currently works in. As this clutters the messages list in the Messages Output View window, &kdevelop; suppresses those messages by default. Mark the checkbox if you want to protocol which directories `Make` worked in.

Changes in this setting effect the processing of new messages only. Old directory navigation messages will be kept visible when you switch this feature off.

### Compiler Output

&kdevelop; preprocesses the messages the Messages Output View window receives during the build processes in order to filter superfluous information. You can control the level of detail &kdevelop; will display using the radio buttons in this field.

Very Short

- Displays only warnings, errors, and the filenames which are compiled.

Short

- Suppresses all compiler flags and formats the output to be more readable.

Full

- Displays all output messages unmodified.

There is an alternative way to switch the compiler output detail. Just right click in the Messages Output View window and select the according detail level from the popup menu.

### Application Output View Window Font

The Application Output View window is used to display error and state information from applications which are run from inside &kdevelop;. These are informations the applications usually sends to the console when run stand-alone. So you do not need to leave the IDE when testing the application you currently work on.

To select a font suitable for the Application Output View window click the Window Font button showing the currently selected font (it says Luxi Sans in the above illustration). The &kde; standard Select Font dialog will pop up from which you may select the font to be used.

On first start-up, &kdevelop; initializes this font setting to the standard font for which your &kde; user has been configured. This setting is fixed, so if you alter Preferences Appearances & Themes Fonts in the Control Center, this will not effect this &kdevelop; font selection. You will have to explicitely reselect the Application Output View window font.

### Selecting the User Interface

As already said in the Available User Interface Modes chapter there are four different ways the &kdevelop; work area may be set up, namely:

- IDEAl Mode

- Child Frame Windows Mode

- Tabbed Pages Mode

- Toplevel Windows Mode

To switch the user interface mode select Settings Configure KDevelop... from the menus. The Customize KDevelop dialog will pop up, where you have to select User Interface in the left hand tree. This will display the followig settings dialog to the right.

Select a user interface mode

Select the radio button of the user interface mode you want to switch to, then click OK.

### Selecting an Editor

&kdevelop; allows you to select your favorite text editor tool. Mark the Editor entry in the left hand side selections tree of the Configure KDevelop window. The following dialog will be displayed to the right.

Select an editor

To select a new editor, click on the arrow on the drop down list field. Depending on the editor parts interfaces your &kde; version has compiled in you will be provided with a list of editors you may select from (see the Important note below for this). Click on the editor of your liking and click OK. Currently there are tree possibilities:

Embedded Advanced Text Editor

- This is the &kde; standard Kate editor part.

Embedded Vim Component

- This provides the look and feel of the base Linux vi editor.

  - You need to have a suitable Vim application installed. Have a look at the KVim website for more information.

  - Furthermore you need to configure the KParts Vim component in the &kde; Control Center (KDE Components Vim Component Configuration) before you can use it.

Qt Designer Based Text Editor

- This is the editor Qt provides in its Designer component.

These editor interfaces are fully integrated in the &kdevelop; IDE concept. Particularly the possibility to jump to the offending source code line by just clicking on an error message in the Messages Output View window has been provided.

Changing the editor will not effect already open files. There are two possibilities to proceed. Either close all open text windows and reopen them one by one. Or simply close the whole project and reopen it again. The windows will then automatically open under the new text editor interface.

KDevelop lets you use editor interfaces which have registered with &kde; and that provide a KatePart interface. If you miss one one of the selections shown above check your &kde; installation if the corresponding KPart was correctly installed.

### Selecting a Source Format Style

&kdevelop; automatically formats a source text in a predefined style. This style is highly configurable. Select Settings Configure KDevelop... from the menubar. The Customize KDevelop dialog will pop up, where you have to select Source Formatter in the left hand tree. This will display a series of three settings dialog tabs to the right, namely a General Formatting Setup, a Indentation Style Setup, and a Other Formatting Setup.

Any style changes apply to newly entered text only. If you want to change the formatting style of an already existing source text you will have to explicitely use the Edit Reformat Source command.

The exact outcome of these style formatting definitions depends on the editor you use. Currently, most settings are taylored to the Kate editor part (the Embedded Advanced Text Editor). Some other editors (⪚ the Qt editor) may rely on their own configuration settings. You will have to experiment in this case to find out the exact effects of the style settings provided here.

Tere may be incompatibilities between the configuration style settings provided here and the editor you use up to the extent that in extreme cases it even might destroy your files. Make sure you have a backup of your source files before you try out these settings with an none KDE standard editor.

#### General Formatting Setup

The General tab of the Source Formatter dialog allows you to select one out of five predefined source format styles.

Source format style general setup

A formatted source example will be displayed in the field to the right. If none of the predefined styles is to your liking, you may click the top User defined radio button and define your own source formatting style preferences on the other two tabs which will become available then.

Currently only the predefined source formatting styles will be demonstrated by an example text. If you decide to define your own style, no example display will be available. You have to experiment on an actual source text to taylor the settings to your liking.

#### Indentation Style Setup

Proper indentation is the main means to enhance readability of a source text. I you selected the Indentation tab of the Source Formatter dialog you will be presented with a series of indentation formatting choices grouped into three boxes as following.

Source format indentation style setup

#### Default Settings

The preset format choices will cause the source text to resemble the ANSI formatting style:

    namespace foospace
    {
      int Foo()
      {
        if (isBar)
        {
          bar();
          return 1;
        }
        else
          return 0;
      }
    }

#### Defining Indentation Width and Characters

The radio buttons grouped in the Filling group define how indents in the source text will be drawn.

Use tabs

- This will cause the editor to insert a tab character for each indentation level. The tab width is predefined in the editor settings (8 or 4 character columns usually). Use Settings Configure Editor... to redefine it.

  The actual tab width definition procedure depends on the editor you selected in the Selecting an Editor configuration step. You will have to look up the corresponding editor help to find out.

Use spaces

- If you select this radio button, the editor will enter a number of spaces for each indentation level. Change the number from the default 2 to the indentation width you prefer.

#### Indented Entities

This defines which of the (C/C++) entities will be formatted with an extra indent beyond the current indentation level.

By default only namespaces and labels will be extra indented. You may want to experiment with various settings to taylor those extra indents to your liking.

#### Continuation

The settings grouped here apply to those cases where the source formatter automatically wraps around long source lines. It takes two special cases in account, namely that in deeply nested indents there should remain enough room for the source and that conditionals should get extra indent levels on continuation to make them stand out properly.

This applies to static word wrap cases only where a fixed maximum line width is used in the source text. If you set up your editor to dynamically wrap around long lines in display only (which is possible in the Kate editor part) the effects of these settings usually will not show.

Maximum in statement

- This setting limits the maximum possible indentation for the continuation lines so that enough space will remain to keep the text readable. No continuation line will ever be indented beyond the number of columns you selected in this field.

  The default is set to 40 character columns (half a standard 80 column page). You may want to increase this value to account for wider paper (e.g if you use landscape printing for your sources). Or decrease the value accordingly to take larger margin settings of your printouts into account.

Minimum in conditional

- Conditionals or source following ⪚ an assignment operator should usually get an extra indent on continuation lines in order to keep the text readable. The amount of this extra indent is defined here.

  The default is set to Twice current which means that continued conditionals will get an extra indent level of the standard indentation size you selected in the Filling group. You may change this extra indent to another fixed width (including zero) using the arrows or by entering the value directly.

#### Other Formatting Setup

Other source format style settings

#### Controlling the Position of Braces

The radio buttons the (somewhat misnamed) Brackets group control the position of block delimiting braces in a (C/C++) source text. There are three possibilities from which you can select.

Break

- This inserts a line break before each opening brace. Both delimiting braces of any block will be put at the same indentation level as the block head statement.

      namespace foospace
      {
        int Foo()
        {
          if (isBar)
          {
            bar();
            return 1;
          }
          else
            return 0;
        }
      }

Attach

- This will keep the opening brace of a block in line with the block head statement. Closing braces will be on the same indentation level as the block head statement. The else of an if statement will be kept in line with the closing brace of the preceding block.

      namespace foospace {
        int Foo() {
          if (isBar) {
            bar();
            return 1;
          } else
            return 0;
        }
      }

Linux Style

- This is a compromise of the above listed styles. Functional block delimiting braces will be put on extra lines. Braces opening a block in a conditional or loop statement will be kept in line.

      namespace foospace
      {
        int Foo()
        {
          if (isBar) {
            bar();
            return 1;
          } else
            return 0;
        }
      }

#### Controlling Extra Spaces

By default &kdevelop; does minimize the use of spaces in source texts.

    if (isBar(fooArg)==barValue)

You may enhance readability if you force the source formatter to insert extra spaces in special positions.

Add spaces around parentheses

- In fact what is meant is to add spaces around the text put in parentheses. This enhances the readbilitiy of function arguments and conditionals.

      if ( isBar( fooArg )==barValue )

Add spaces around operators

- This will put spaces around assignment and comparison operators to enhance the readability.

      if (isBar(fooArg) == barValue)

#### Controlling the Formatting of One-Line Constructs

There are a few cases where you don't want the source formatter to split a long line apart. For C/C++ code this can be controlled here.

Keep one-line statements

- This keeps single line statements together in some situations even if they exceed a fixed maximum line length.

Keep one-line blocks

- This keeps single line blocks together in some situations even if they exceed a fixed maximum line length.

### Setting Up the Code Snippets Tool

When editing in &kdevelop; you can store often used parts of code as Code Snippets. To configure the capabilities of the code snippets part select Settings Configure KDevelop... from the menubar. The Customize KDevelop dialog will pop up, where you have to select Code Snippets in the left hand tree. This will show the following dialog in the right hand side.

Configuring the Code Snippets tool

### Activate Snippet Preview

Mark the Show snippet's text in tooltip checkbox if you want to view the stored text in a tooltip window whenever you keep the mouse cursor over the title of that snippet.

### Working With Snippet Variables

The Code Snippets tool allows for a variable text in predefined places any time you insert a snippet into a file. To accomplish this Code Snippets provides its own variables' mechanism. You can set up it's behaviour in the Variables group.

Delimiter

- The Code Snippets tool distinguishes variables in the text by surrounding the variable name with special delimiter symbols. To use your own delimiter symbol, change the predefined $ character in the Delimiter field.

Input method for variables

- - Single dialog for each variable within a snippet – will in turn pop up a separate dialog for each variable which the tool finds when inserting the selected code snippet.

  - One dialog for all variables within a snippet – will pop up a common dialog where the user has to fill in the values of all variables before the snippet will be inserted

### Configuring the File Selector

&kdevelop; provides a File Selector plugin which, when loaded at start-up, allows to navigate to any file or directory in the system.

The file selector (IDEAl mode)

The behaviour of the File Selector can be highly configured. Select Settings Configure KDevelop... from the menubar. The Customize KDevelop dialog will pop up, where you have to select File Selector in the left hand tree. This will show the following dialog in the right hand side.

Configuring the file selector

### Configuring the Toolbar

There is a toolbar on top of the File Selector which can be configured as usual in the Toolbar group.

### Add an Action to the Toolbar

1. Select an item in the right hand Selected actions list after which the new action should be inserted.

2. Select the action to be inserted in the left hand Available actions list.

3. Click the right (upper) arrow between both lists.

   The action will be removed from the Available actions list and inserted into the Selected actions list below the selected item.

### Remove an Action from the Toolbar

1. Select the item to be removed in the right hand Selected actions list.

2. Click the left (lower) arrow between both lists.

   The selected item will be removed from the Selected actions list and put back into the Available actions list.

### Reorder the Actions on the Toolbar

1. Select the action to be moved in the right hand Selected actions list.

2. Click the up or down arrow to the right of this list.

   The selected item will be moved up or down the Selected actions list.

### Defining When the Contents Should Change

Updating the contents in the File Selector window takes time and resources, esp. when changing to another directory. Therefore File Selector is set up by default in such a way that its contents change only on demand, &ie; when you select another directory or when you explicitely want to refresh its contents.

Click the Reload button in the toolbar to update the contents of the File Selector. This toolbar button is not availble by default, however. You must insert it there first.

You can configure the File Selector to immediately reflect certain changes in your work. The settings in the Auto Synchronization group of the configuration dialog are responsible for this.

When a document becomes active

- If you select this checkbox, the contents in the File Selector window will be updated whenever you go to another already open document, ⪚ when you click on the tab of the according edit window in IDEAl mode. If necessary the File Selector will switch to the directory this file belongs to and update the display to show the actual contents in there.

When a document is opened

- If you select this checkbox, the contents in the File Selector window will be updated whenever a document will be opened, ⪚ by the File Open menu. If necessary the File Selector will switch to the directory this file belongs to and update the display to show the actual contents in there.

When the file selector becomes visible

- If you select this checkbox, the contents in the File Selector window will be updated whenever it gets visible again. If necessary it will switch to the directory the actual document belongs to and update the display to show the actual contents in there.

You may freely combine these settings to taylor the actualization behaviour of the File Selector to your liking.

### Controlling the History in the Comboboxes

There are two comboboxes on top and bottom of the File Selector contents window which control the directory to be diplayed (top combobox) and the filters to be applied to the file display (bottom combobox). A history of the most recent settings is kept in the selection field of each combobox. You can configure the number of history entries as follows.

Remember locations

- Enter here the maximum number of directory selections the upper combobox shall remember.

Remember filters

- Enter here the maximum number of filter definitions the lower combobox shall remember.

### Controlling What Should be Remembered Between Sessions

By default the File Selector is set up so that it shows the display of the most recent session again at the next &kdevelop; start-up. You may change this behaviour in the Session configuration group.

If &kdevelop; was automatically restarted by the KDE session manager the changes in these settings will have no effect. In this case location and filter settings of the most recent KDE session will always be restored.

Restore location

- Remove the checkbox mark here if you don't want the displayed location be remembered between sessions.

  If you selected one of the automatic update settings the displayed location might automatically change regardless what has been remembered from the recent session.

Restore filters

- Remove the checkbox mark here if you don't want the filters applied to the display be remembered between sessions.

## Configuring the Documentation

&kdevelop; contains a very powerful documentation facility which provides access to several kinds of extensive documentation. In ⪚ IDEAl mode you find a Documentation tab at the right border of the work area.

The &kdevelop; documentation tree (IDEAl mode)

You may set up the contents of this documentation tree if you select Settings Configure KDevelop... from the menubar. The Customize KDevelop dialog will pop up, where you have to select Documentation Tree in the left hand tree.

&kdevelop; must have loaded the Documentation plugin in order to view the documentation tree. See the Plugin Tools section for more info.

## Alternative Method to Call Up the Configuration Page

There is a shortcut way to call up this configuration. Open the documentation tree (⪚ by clicking on the Documentation tab in IDEAl mode), then right-click into the list. From the popup dialog select Properties which in turn will display a Customize Documentation Tree window.

The thus displayed configuration page shows a series of tabbed configuration dialog pages, namely:

- General
- Full Text Search
- Bookmarks
- KDevelopTOC Documentation
- DevHelp Documentation

Additionally you have the option to select what the documentatione tree should display as

- Project Documentation

on a per project basis.

For a more intuitive reading we will discuss these configuration dialogs in slightly different order. Use one of the links above if you want to directly look at the help for one of the tabbed configure dialog sections.

You should at least configure the Full Text Search section. It is mandatory to immediately access the &Qt; and &kde; Libraries API help from within a source text.

### Changing Documentation Entries

Most of these tabbed configuration dialogs provide a set of Add, Edit, and Remove buttons to the right of some list field. Use these to change the listed entries or add your own.

If you click one of the Add or Edit buttons you will be shown an Add Documentation Entry dialog like this (deliberately filled in by an example):

Adding or changing a documentation entry

### Local and Remote Documentation

The &kdevelop; documentation tree may access local (system internal) documentation files as well as remote (external, mostly accessible via the web) ones. You only need to enter the proper &URL; addresses in the Location field. (In fact, most predefined entries in the documentation tree at initial &kdevelop; start-up consist of links to external documention.)

You may at any time change from remote to local documentation (if you ⪚ downloaded the files into your system) and vice versa. Just alter the &URL; accordingly as shown below.

Don't forget to provide working net access before you select one of the external documentation entries in the &kdevelop; documentation tree.

### Documentation List Change Buttons

Add

- When you click this button you will be presented with an empty Add Documentation Entry dialog.

  Enter a suitable Title text and the &URL; address where the documentation will be found in the Location field.

  If you don't know the exact address (or rather want not type) click the folder-labeled button to the right of the Location field. The usual file selection dialog will then pop up where you can navigate to the file you want to be added.

Edit

- First select the entry you want to change in the list field, then click the Edit button. The Add Documentation Entry dialog will then pop up with its fields preset with informations from the selected list item (see the example above where the fields are filled in for the &kde; Libraries documentation).

  Enter a more suitable Title text and/or change the &URL; address in the Location field to the location where this documentation will be found in your system.

  If you don't know the exact address (or rather want not type) click the folder-labeled button to the right of the Location field. The usual file selection dialog will then pop up where you can navigate to the file you want to be added.

Remove

- First select the entry you want to remove in the list field, then click the Remove button. This will delete the selected documentation from the stored entries.

  Think twice before you remove a documentation form the list!

  There is usually no easy way to undo this operation. In most cases you will have to add the documentation manually again. So, if you are unsure, try to backup the configuration files (if known) or at least note &URL; and title of the selected documentation before you click Remove.

### Predefined File Selections

In some cases when you called the file selection dialog from Add Documentation Entry you may find the display of available files limited by a preset Filter field (located at the dialog bottom). This may ⪚ read *.xml *.dcf in the case of changing the &Qt; documentation files. If you are unsure about the files you need, best stick to such predefined selections.

### Basic &Qt; and &kde; Documentation

The General tab of the Documentation Tree configuration page contains information to access the basic documentation sets needed for &kde; programming. Accordingly there are three dialog groups:

- Qt documentation collections
- Documentation generated by Doxygen
- Documentation generated by KDoc

Setting up &kde; basic documentation sets

#### Qt Documentation Collections

Normally &kdevelop; will fill this in on its first start-up. It looks for standard documentation files in the &Qt; installation directory. The table to the left lists the files &kdevelop; found by their standard title and &URL; address.

If you have a non-standard installation, either there will be no information listed at all or the addresses will possibly point to improper locations (⪚ to another &Qt; installation available in your system). You may adjust the entries using the buttons to the right of the list field.

Pressing the Add or Edit to change a &Qt; list entry will pop up a slightly different dialog:

Adding or changing a &Qt; documentation entry

Normally &kdevelop; will use the titles already provided by the installed &Qt; documentation. Hence the Title field will be grayed and inaccessible when this Add Documentation Entry dialog starts up. If you want to use your own title text in the documentation tree of &kdevelop; you must first check the Custom title field. This will provide access to the Title field contents where you then may fill in any text you like.

#### KDE API Documentations

The other two lists on the General documentation tree configuration page concern API documentations provided by the &kde; system.

In short, such an API documents the interface to certain library functions. There are two common ways to produce an API documentation from the sources, namely the older one using the &kde; KDoc application and the far more versatile using the externally provided &doxygen; tool.

#### Documentation Generated by Doxygen

&kdevelop; will have filled in a link to the current &kde; Libraries API, provided it found one at installation time. There are two basic ways for &kdevelop; to find out:

- Either you provided the `configure` command with the `--with-kdelibsdoxy-dir` option when you compiled &kdevelop; (see the How to Obtain a KDevelop API Documentation chapter).

- Or the `configure` command did automatically find a &doxygen; generated &kde; Libraries API in one of several standard locations it knows of.

If &kdevelop; did not find a valid &doxygen; generated &kde; Libraries API at its first start-up the Documentation Generated by Doxygen list will be empty.

You may change the entries in the Documentation Generated by Doxygen list using the buttons to the right.

After you first started up &kdevelop; after a new installation you should in any case check whether the &kde; Libraries API had been correctly set up in the documentation tree. It is advisable to have this API documentation at hand because it is basic to all &kde; programming.

The &kde; system provides more API documentation than the &kde; Libraries API only. You will need additional interfaces information if you want to ⪚ include the &kate; part into you programs. For this &kate; part API for example you should compile and install the &kde; Base Libraries API from the sources (using the `make apidox` and `make install` commands on the `kdebase` sources) and then add an entry to the Documentation Generated by Doxygen list like this:

Adding a &kde; Base API to the list

(Of course you should replace the `/opt/kde-cvs/` directory in the Location field example with the path to your &kde; installation.)

#### Documentation Generated by KDoc

There is not much KDoc based API documentation around these days. Hence this list will be empty after the first &kdevelop; start-up. If you want to add some KDoc based API documentation use the buttons to the right of this list.

### Handling Structured Documentation (KDevelopTOC Files)

The main bulk of &kdevelop;'s documentation tree provides immediate access to structured documentation, local as well as remote ones. You can configure this on the KDevelopTOC Documentation tab of the Documentation Tree configuration page.

Providing standard documentations listed in &kdevelop;

There is a special feature associated with this. To illustrate, follow these steps: In the documentation tree find an entry shortly below the &Qt;/&kde; documentation (⪚ KDE2 Development Book (kde.org)). Click on the plus sign next to it. A tree will open where you can quickly navigate to subsequent chapters nested several levels deep, all offline. But if you finally select one of the chapters, &kdevelop; will in many cases try to access a remote documentation file.

#### &kdevelop; TOC Files

So you can locally navigate remote documentation without wasting net access ressources. &kdevelop; makes this possible through the use of special table of content files, which are denoted by `.toc` filename extensions. Any such &kdevelop; TOC file contains an &XML; structured description of the document to be accessed.

#### Standard Directory of &kdevelop; TOC Files

When &kdevelop; was installed usually a series of predefined `.toc` files has been put into the `$KDEDIR/share/apps/kdevdoctreeview/tocs` directory. These are fairly simple, structured text files. You may look at them using a text editor or other text display facility.

#### Basic Structure of &kdevelop; TOC Files

header

- - `<!DOCTYPE kdeveloptoc>`
  - `<kdeveloptoc>`
  - (title)
  - (base address)
  - (content structure)
  - `</kdeveloptoc>`

  This &XML; structure will be parsed by the &kdevelop; Documentation plugin to set up the documentation tree contents and to guide the user in navigating the documentation. It contains all information necessary to display titles and access the documentation file contents.

title

- - `<title>` (some title string) `</title>`

  This is the title &kdevelop; will display at the basic levels in the documentation tree.

  This displayed title currently cannot be changed by the user. If you want another text be displayed, you must manually change the `<title>` entry in the `.toc` file.

base address

- - `<base href="` (base document &URL;) `"/>`

  This &URL; points to the location where all files of this documentation are located. It will be prepended before each section &URL; in the following content structure list. So, if you ⪚ downloaded a documentation from a remote server, all you need to display the files from this new location is to change its `<base>` &URL;.

  You need not change the `.toc` file, however. Better use the Edit button on the KDevelopTOC Documentation tab of the documentation customization page as shown below.

content structure

- - `<tocsect1 name="` (section title) `" url="` (section &URL;) `">`
  - ...
  - `<tocsectn name="` (section title) `" url="` (section &URL;) `"/>`
  - ...
  - `</tocsect1>`

  All remaining navigation and access information is stored in a series of nested `<tocsecti>` ... `</tocsecti>` pairs. Each i denotes a consecutive nesting level down to number n which will correspond to the finally displayed documentation section.

  Any `<tocsecti>` entry must have a `name=""` attribute associated with it. This will be displayed as level title in the documentation tree. It should correspond to an actual documentation section.

  There may be an `url=""` attribute associated with any i nesting level. When the user clicks on a section title in the documentation tree &kdevelop; will try to access the file at the location pointed to by the combined base and section &URL;.

  The `<tocsectn/>` entry must have an `url=""` attribute whatsoever. This final nested `<tocsectn/>` does not come in pairs but will immediately be closed by a `/` before the `>` bracket.

  Any address combined of base and section &URL; must point to some displayable text file. Usually this will be an HTML-structured file. It is possible to link to anchor marks within such an HTML file using the standard # notation of the format: `/base-url/section-url#anchor-mark`.

#### Altering the &kdevelop; TOC Documentation

There are two ways to alter the &kdevelop; TOC Documentation. You may change the docuentation tree list, &ie; add to or remove entries from the KDevelopTOC Documentation tab of the Documentation Tree configuration page. Additionally you may point an existing documentation to another base location.

#### Adding &kdevelop; TOC Files

Adding an entry to the KDevelopTOC Documentation tab is fairly straightforward. At first you need a `.toc` file to some structured documentation following the structure shown above. This is easily constructed using any standard text editor. Then add this file using the Add button on the configuration page.

#### Removing a &kdevelop; TOC Entry

To remove an entry from the KDevelopTOC Documentation tab first select it in the list, then click on the Remove button on the configuration page.

Think twice before you click on the Remove button!

&kdevelop; will not only remove the list entry but also delete the `.toc` file from the directorye. You may want to keep a backup copy if the documentation was valuable.

If the `.toc` file cannot be removed (&ie; if you have no write access), the entry will remain in the KDevelopTOC Documentation list.

#### Changing the Base Address of a &kdevelop; TOC Entry

If the documentation in an already listed `.toc` file should be read from another location, tell &kdevelop; to alter the documentation base address. Select the file in the KDevelopTOC Documentation list, then click on the Edit button.

For historical reasons clicking the Edit button will pop up a different dialog which stems from an older approach to structured library documentation:

Changing the base address of a &kdevelop; TOC entry

The Library name field shows the name of the `.toc` file which was selected in the list. As this is for information only, the field remains inaccessible.

The Documentation path field contains the base address which &kdevelop; currently uses to access this documentation. Change it to point to the new documentation origin &kdevelop; shall subsequently use. Then press OK to alter the access.

The remaining Library source path dialog field is of no importance. Just ignore it.

#### Reverting to the Default Base Address

&kdevelop; will not change the `.toc` file contents. Instead it keeps the current base address in an internal list.

If you want to get the original documentation base address back, use the Default button in this Library Documentation dialog. &kdevelop; will replace its internal documentation base pointer by the contents of the `<base>` field in the corresponding `.toc` file.

### DevHelp Documentation

(... to be written ...)

Providing DevHelp documentation

### Displaying Selected Documentation in a Project

(... to be written ...)

### Bookmarked Documentation

(... to be written ...)

Eplicitely adding documentation to the bookmarks

Adding existing documentation to the bookmarks

### Setting Up Text Search Indexes

(... to be written ...)

Setting up text search indexes

## Advanced Configuration

(... to be written ...)

### Plugin Tools

(... to be written ...)

### Abbreviations for the Word Completion

(... to be written ...)

### Adding &kde; Standard Applications to the Tools Menu

(... to be written ...)

### Adding External Applications to Menus

(... to be written ...)

#### Adding to the Tools Menu

(... to be written ...)

#### Adding to the File Context Menu

(... to be written ...)

#### Adding to the Directory Context Menu

(... to be written ...)