← Back to branch summary

~ubuntu-branches/debian/sid/kdevelop/sid

« back to all changes in this revision

Viewing changes to doc/kdevelop3_outdated/setup.docbook

  • Committer: Bazaar Package Importer
  • Author(s): Jeremy Lainé
  • Date: 2010-05-05 07:21:55 UTC
  • mfrom: (1.2.3 upstream) (5.1.2 squeeze)
  • Revision ID: james.westby@ubuntu.com-20100505072155-h78lx19pu04sbhtn
Tags: 4:4.0.0-2
http://bugs.debian.org/579947
http://bugs.debian.org/481832
http://bugs.debian.org/562410
http://bugs.debian.org/546961
* Upload to unstable (Closes: #579947, #481832).
* Acknowledge obsolete NMU fixes (Closes: #562410, #546961).

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/kdevelop3_outdated/setup.docbook
 
1
<chapter id="setup">
 
2
 
 
3
<chapterinfo>
 
4
  <authorgroup>
 
5
    <author><firstname>Bernd</firstname><surname>Pol</surname></author>
 
6
    <!-- TRANS:ROLES_OF_TRANSLATORS -->
 
7
  </authorgroup>
 
8
</chapterinfo>
 
9
 
 
10
<title>Configuring &kdevelop;</title>
 
11
 
 
12
<para>
 
13
&kdevelop; is a very powerful and flexible IDE which offers many ways to tailor it to your needs. To start configuration select <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure KDevelop...</guimenuitem></menuchoice>. 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.
 
14
</para>
 
15
 
 
16
<screenshot>
 
17
  <mediaobject>
 
18
    <imageobject>
 
19
      <imagedata fileref="configure-select.png" format="PNG"/>
 
20
    </imageobject>
 
21
<textobject>
 
22
<phrase>Select a configuration item</phrase>
 
23
</textobject>
 
24
    <caption><para>
 
25
    Select a configuration item
 
26
    </para></caption>
 
27
  </mediaobject>
 
28
</screenshot>
 
29
 
 
30
<para>
 
31
We will discuss these configurations in a different order, split up into the main topics of <link linkend="setup-general">General Configuration</link>, <link linkend="setup-docu">Configuring the Documentation</link>, and <link linkend="setup-advanced">Advanced Configuration</link> which makes for a more intuitive reading.
 
32
</para>
 
33
<para>
 
34
If you want directly look up a certain configuration item use one of the following links.
 
35
</para>
 
36
<simplelist>
 
37
  <member><link linkend="setup-main">General</link></member>
 
38
  <member><link linkend="setup-plugins">Plugins</link></member>
 
39
  <member><link linkend="setup-format">Source Formatter</link></member>
 
40
  <member><link linkend="setup-new-file-wizard">New File Wizard</link></member>
 
41
  <member><link linkend="setup-ui">User Interface</link></member>
 
42
  <member><link linkend="setup-editor">Editor</link></member>
 
43
  <member><link linkend="setup-abbrev">Abbreviations</link></member>
 
44
  <member><link linkend="setup-menu-standard">Tools Menu</link></member>
 
45
  <member><link linkend="setup-menu-external">External Tools</link></member>
 
46
  <member><link linkend="setup-docu">Documentation</link></member>
 
47
  <member><link linkend="setup-snippets">Code Snippets</link></member>
 
48
  <member><link linkend="setup-fileselector">File Selector</link></member>
 
49
</simplelist>
 
50
 
 
51
<sect1 id="setup-general">
 
52
<title>General Configuration</title>
 
53
 
 
54
<para>
 
55
General configuration concerns the more common tasks of tailoring &kdevelop; as there are:
 
56
</para>
 
57
<itemizedlist>
 
58
  <listitem><para>
 
59
  <link linkend="setup-main">General Setup</link>
 
60
  </para></listitem>
 
61
  <listitem><para>
 
62
  <link linkend="setup-ui">Selecting the User Interface</link>
 
63
  </para></listitem>
 
64
  <listitem>
 
65
    <itemizedlist>
 
66
<title>Source Edit Tasks</title>
 
67
      <listitem><para>
 
68
      <link linkend="setup-editor">Selecting an Editor</link>
 
69
      </para></listitem>
 
70
      <listitem><para>
 
71
      <link linkend="setup-format">Selecting a Source Format Style</link>
 
72
      </para></listitem>
 
73
      <listitem><para>
 
74
      <link linkend="setup-snippets">Setting Up the Code Snippets Tool</link>
 
75
      </para></listitem>
 
76
    </itemizedlist>
 
77
  </listitem>
 
78
  <listitem><para>
 
79
  <link linkend="setup-fileselector">Configuring the File Selector</link>
 
80
  </para></listitem>
 
81
</itemizedlist>
 
82
 
 
83
<sect2 id="setup-main">
 
84
<title>General Setup</title>
 
85
 
 
86
<para>
 
87
The <guilabel>General</guilabel> configuration dialog allows you to define some basic &kdevelop; behaviour which seldom will change in everyday work. This concerns:
 
88
</para>
 
89
 
 
90
<variablelist>
 
91
<varlistentry>
 
92
<term>General project options such as</term>
 
93
<listitem>
 
94
    <itemizedlist>
 
95
      <listitem><para>
 
96
      defining a <link linkend="setup-main-projects">default parent directory</link> &kdevelop; shall use for new projects.
 
97
      </para></listitem>
 
98
       <listitem><para>
 
99
      deciding whether you want &kdevelop; to <link linkend="setup-main-preload">automatically load</link> the project you last worked on.
 
100
      </para></listitem>
 
101
   </itemizedlist>
 
102
  </listitem>
 
103
</varlistentry>
 
104
 
 
105
<varlistentry>
 
106
<term>Selecting a font for the most commonly used output view windows,
 
107
namely:</term>
 
108
<listitem>
 
109
 
 
110
<itemizedlist>
 
111
<listitem>
 
112
<para>the <link linkend="setup-main-messages-font">Messages Output
 
113
View</link> &kdevelop; uses to communicate &eg; compilation progresses,
 
114
and</para>
 
115
</listitem>
 
116
<listitem>
 
117
<para>the <link linkend="setup-main-applications-font">Application Output
 
118
View</link> which will show error and state information concerning a running
 
119
application.</para>
 
120
</listitem>
 
121
</itemizedlist>
 
122
 
 
123
</listitem>
 
124
</varlistentry>
 
125
 
 
126
<varlistentry>
 
127
<term>Some common behaviour concerning the displayed lines in the
 
128
<guilabel>Messages Output View</guilabel> window, namely:</term>
 
129
<listitem>
 
130
    <itemizedlist>
 
131
<listitem>
 
132
<para>whether long lines will <link linkend="setup-main-wrap">wrap
 
133
      around</link>, and </para>
 
134
</listitem>
 
135
<listitem>
 
136
<para>if <link linkend="setup-main-navigation">directory entry and exit
 
137
messages</link> issued by <command>make</command> will be shown.</para>
 
138
</listitem>
 
139
</itemizedlist>
 
140
 
 
141
<para>The <link linkend="setup-main-compile">level of detail</link> of
 
142
  messages concerning the compilation process shown in the
 
143
  <guilabel>Messages Output View</guilabel> window.</para>
 
144
</listitem>
 
145
</varlistentry>
 
146
</variablelist>
 
147
 
 
148
<screenshot>
 
149
  <mediaobject>
 
150
    <imageobject>
 
151
      <imagedata fileref="configure-general.png" format="PNG"/>
 
152
    </imageobject>
 
153
    <caption><para>
 
154
    The general configuration dialog
 
155
    </para></caption>
 
156
  </mediaobject>
 
157
</screenshot>
 
158
 
 
159
<variablelist>
 
160
<varlistentry>
 
161
<term id="setup-main-preload"><guilabel>Load last project on
 
162
startup</guilabel></term>
 
163
<listitem>
 
164
<para>
 
165
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.
 
166
</para>
 
167
</listitem>
 
168
</varlistentry>
 
169
 
 
170
<varlistentry>
 
171
<term id="setup-main-projects">
 
172
<guilabel>Default projects directory:</guilabel></term>
 
173
<listitem>
 
174
<para>
 
175
By default, &kdevelop; uses a common parent directory for all new
 
176
projects. Enter the absolute path of this common directory in the box or
 
177
select it from your directory structure. &kdevelop; will place the any new
 
178
project here as a subdirectory.</para>
 
179
<note><para>
 
180
You may of course change the directory path of a new project at the time you set it up in the <link linkend="applicationwizard">&appwizard;</link>.
 
181
</para></note>
 
182
</listitem>
 
183
</varlistentry>
 
184
 
 
185
<varlistentry>
 
186
<term id="setup-main-messages-font"><guilabel>Window font:</guilabel></term>
 
187
<listitem>
 
188
<para>
 
189
To select a font suitable for the <guilabel>Messages Output View</guilabel> window click the <guilabel>Window Font</guilabel> button showing the currently selected font (it says <quote>Luxi Sans</quote> in the above illustration). The &kde; standard <guilabel>Select Font</guilabel> dialog will pop up from which you may select the font to be used.
 
190
</para>
 
191
<note><para>
 
192
On first start-up, &kdevelop; initializes this font setting to the standard font for which your &kde; user has been configured. <emphasis>This setting is fixed</emphasis>, so if you alter <menuchoice><guimenuitem>Preferences</guimenuitem><guimenuitem>Appearances &amp; Themes</guimenuitem><guimenuitem>Fonts</guimenuitem></menuchoice> in the <guilabel>Control Center</guilabel>, this will not effect this &kdevelop; font selection. You will have to explicitly reselect the <guilabel>Messages Output View</guilabel> window font.
 
193
</para></note>
 
194
</listitem>
 
195
</varlistentry>
 
196
 
 
197
<varlistentry>
 
198
<term id="setup-main-wrap"><guilabel>Line wrapping</guilabel></term>
 
199
<listitem>
 
200
<para>
 
201
By default, &kdevelop; will wrap long lines around in the <guilabel>Messages Output View</guilabel> 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.
 
202
</para>
 
203
<tip><para>
 
204
There is an alternative way to switch the line wrapping. Just &RMB; click in the <guilabel>Messages Output View</guilabel> window and mark/unmark the <guimenuitem>Line Wrapping</guimenuitem> entry in the menu which will pop up.
 
205
</para></tip>
 
206
</listitem>
 
207
</varlistentry>
 
208
 
 
209
<varlistentry>
 
210
<term id="setup-main-navigation"><guilabel>Directory navigation
 
211
messages</guilabel></term>
 
212
<listitem>
 
213
<para>
 
214
The <command>make</command> tool usually will display messages like <quote>Entering directory</quote>, or <quote>Leaving directory</quote> when it switches the directories it currently works in. As this clutters the messages list in the <guilabel>Messages Output View</guilabel> window, &kdevelop; suppresses those messages by default. Mark the checkbox if you want to protocol which directories <command>make</command> worked in.
 
215
</para>
 
216
<note><para>
 
217
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.
 
218
</para></note>
 
219
</listitem>
 
220
</varlistentry>
 
221
 
 
222
<varlistentry>
 
223
<term id="setup-main-compile"><guilabel>Compiler Output</guilabel></term>
 
224
<listitem>
 
225
<para>
 
226
&kdevelop; preprocesses the messages the <guilabel>Messages Output View</guilabel> 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.
 
227
</para>
 
228
<variablelist>
 
229
  <varlistentry>
 
230
    <term><guilabel>Very Short</guilabel></term>
 
231
    <listitem><para>
 
232
    Displays only warnings, errors, and the filenames which are compiled.
 
233
    </para></listitem>
 
234
  </varlistentry>
 
235
  <varlistentry>
 
236
    <term><guilabel>Short</guilabel></term>
 
237
    <listitem><para>
 
238
    Suppresses all compiler flags and formats the output to be more readable.
 
239
    </para></listitem>
 
240
  </varlistentry>
 
241
  <varlistentry>
 
242
    <term><guilabel>Full</guilabel></term>
 
243
    <listitem><para>
 
244
    Displays all output messages unmodified.
 
245
    </para></listitem>
 
246
  </varlistentry>
 
247
</variablelist>
 
248
 
 
249
<tip><para>
 
250
There is an alternative way to switch the compiler output detail. Just right click in the <guilabel>Messages Output View</guilabel> window and select the according detail level from the popup menu.
 
251
</para></tip>
 
252
</listitem>
 
253
</varlistentry>
 
254
 
 
255
<varlistentry>
 
256
<term id="setup-main-applications-font"><guilabel>Application Output
 
257
View</guilabel> <guilabel>Window font:</guilabel></term>
 
258
<listitem>
 
259
<para>
 
260
The <guilabel>Application Output View</guilabel> window is used to display error and state information from applications which are run from inside &kdevelop;. These are information 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.
 
261
</para>
 
262
 
 
263
<para>
 
264
To select a font suitable for the <guilabel>Application Output View</guilabel> window click the <guilabel>Window Font</guilabel> button showing the currently selected font (it says <quote>Luxi Sans</quote> in the above illustration). The &kde; standard <guilabel>Select Font</guilabel> dialog will pop up from which you may select the font to be used.
 
265
</para>
 
266
<note><para>
 
267
On first start-up, &kdevelop; initializes this font setting to the standard font for which your &kde; user has been configured. <emphasis>This setting is fixed</emphasis>, so if you alter <menuchoice><guimenuitem>Preferences</guimenuitem><guimenuitem>Appearances &amp; Themes</guimenuitem><guimenuitem>Fonts</guimenuitem></menuchoice> in the <guilabel>Control Center</guilabel>, this will not effect this &kdevelop; font selection. You will have to explicitly reselect the <guilabel>Application Output View</guilabel> window font.
 
268
</para></note>
 
269
</listitem>
 
270
</varlistentry>
 
271
</variablelist>
 
272
 
 
273
</sect2> <!-- setup-main -->
 
274
 
 
275
<sect2 id="setup-ui">
 
276
<title>Selecting the User Interface</title>
 
277
 
 
278
<indexterm zone="setup-ui">
 
279
  <primary>user interface</primary>
 
280
  <secondary>switch modes</secondary></indexterm>
 
281
<indexterm zone="setup-ui">
 
282
  <primary>switch UI modes</primary></indexterm>
 
283
 
 
284
<para>
 
285
As already said in the <link linkend="uimodes-survey">Available User Interface Modes</link> chapter there are four different ways the &kdevelop; work area may be set up, namely:
 
286
</para>
 
287
<itemizedlist>
 
288
  <listitem><para>
 
289
  <link linkend="ideal-desc">IDEAl Mode</link>
 
290
  </para></listitem>
 
291
  <listitem><para>
 
292
  <link linkend="mdi-desc">Child Frame Windows Mode</link>
 
293
  </para></listitem>
 
294
  <listitem><para>
 
295
  <link linkend="tabbed-desc">Tabbed Pages Mode</link>
 
296
  </para></listitem>
 
297
  <listitem><para>
 
298
  <link linkend="toplevel-desc">Toplevel Windows Mode</link>
 
299
  </para></listitem>
 
300
</itemizedlist>
 
301
 
 
302
<para>
 
303
To switch the user interface mode select <menuchoice> <guimenu>Settings</guimenu> <guimenuitem>Configure KDevelop...</guimenuitem> </menuchoice> from the menus. The <guilabel>Customize KDevelop</guilabel> dialog will pop up, where you have to select <guilabel>User Interface</guilabel> in the left hand tree. This will display the following settings dialog to the right.</para>
 
304
 
 
305
<screenshot>
 
306
  <mediaobject>
 
307
    <imageobject>
 
308
      <imagedata fileref="select-user-interface-0.png" format="PNG"/>
 
309
    </imageobject>
 
310
<textobject><phrase>Select a user interface mode</phrase></textobject>
 
311
    <caption><para>
 
312
    Select a user interface mode
 
313
    </para></caption>
 
314
  </mediaobject>
 
315
</screenshot>
 
316
 
 
317
<para>
 
318
Select the radio button of the user interface mode you want to switch to, then click <guibutton>OK</guibutton>.
 
319
</para>
 
320
 
 
321
<note><para>
 
322
Do not forget to restart &kdevelop; in order to let any of these selections take effect.
 
323
</para></note>
 
324
 
 
325
<para>
 
326
When you selected either the <guilabel>IDEAl window mode</guilabel> or the <guilabel>Tabbed pages mode</guilabel> two more configuration sections will become available: <link linkend="setup-ui-tabs">Use Tabs</link> and <link linkend="setup-ui-hover">Use Close On Hover</link>. These allow to configure under which circumstances tabs will be shown on top of the document windows and whether you may close the document by a click on the tab icon.
 
327
</para>
 
328
 
 
329
<para>
 
330
In <guilabel>IDEAl window mode</guilabel> only yet another configuration section will be available, <link linkend="setup-ui-toolview">Toolview Tab Layout</link> which effectively allows to select between different sizes of the toolview tabs which surround the main working area in this mode.
 
331
</para>
 
332
 
 
333
<variablelist>
 
334
<varlistentry>
 
335
<term id="setup-ui-tabs">Configuring the Documents Tab Bar Display</term>
 
336
<listitem>
 
337
<para>
 
338
In the IDEAl and tabbed pages modes there will be named tabs on top of the document windows by default, so you can easily select different documents with a &LMB; click. If you prefer to provide more space for the document windows in the &kdevelop; main work area, you may change to another behaviour in the <guilabel>Use Tabs</guilabel> configuration section.
 
339
</para>
 
340
 
 
341
<variablelist>
 
342
<varlistentry>
 
343
  <term><guilabel>Always</guilabel></term>
 
344
  <listitem><para>
 
345
  This is the default &mdash; show a tab comprising an icon and the document name on top of any document window in the &kdevelop; main area display.
 
346
  </para></listitem>
 
347
</varlistentry>
 
348
<varlistentry>
 
349
  <term><guilabel>When more than one</guilabel></term>
 
350
  <listitem><para>
 
351
  Do not show a tab when only one document is displayed. If there is more than one document, however, &kdevelop; will display an according tab bar as in the <guilabel>Always</guilabel> selection above. You may want to select this mode if you work on a single document most of the time as this provides more vertical space.
 
352
  </para></listitem>
 
353
</varlistentry>
 
354
<varlistentry>
 
355
  <term><guilabel>Never</guilabel></term>
 
356
  <listitem><para>
 
357
  Never show any document selection tab. You may prefer this mode if you seldom use the mouse to switch between documents. It provides more vertical space for all document windows. To select another the document window or to close any, use the &kdevelop; <guimenu>Window</guimenu> menu.
 
358
  </para></listitem>
 
359
</varlistentry>
 
360
</variablelist>
 
361
</listitem>
 
362
</varlistentry>
 
363
 
 
364
<varlistentry>
 
365
<term id="setup-ui-hover">Setting Up to Close a Document by a Click On Its
 
366
Tab</term>
 
367
<listitem>
 
368
<para>
 
369
When you configured &kdevelop; to display the documents tab bar, either always or when more than one document is displayed in the main work area, you may add more functionality to the tabs beyond their document selection capability. Use the <guilabel>Use Close On Hover</guilabel> configuration section for this.
 
370
</para>
 
371
 
 
372
<variablelist>
 
373
<varlistentry>
 
374
  <term><guilabel>No</guilabel></term>
 
375
  <listitem><para>
 
376
  This is standard behaviour. No extra functionality is added to the tabs. They may be used only to select document windows on &LMB; clicks.
 
377
  </para></listitem>
 
378
</varlistentry>
 
379
<varlistentry>
 
380
  <term><guilabel>Yes</guilabel></term>
 
381
  <listitem><para>
 
382
  When you selected this radio button, &kdevelop; will allow to close a document window by a &LMB; click. Use the mouse to point at the small icon on the on the left tab border. It will change to a close symbol. Now click with the &LMB; on this changed symbol and &kdevelop; will close the according document window.
 
383
  </para></listitem>
 
384
</varlistentry>
 
385
<varlistentry>
 
386
  <term><guilabel>Yes, Delayed</guilabel></term>
 
387
  <listitem><para>
 
388
  After selecting this radio button, &kdevelop; will allow to close a document window as shown in the <guilabel>Yes</guilabel> case above. The icon will not change instantly, however, but there will be a short delay before the close icon shows up.
 
389
  </para></listitem>
 
390
</varlistentry>
 
391
</variablelist>
 
392
</listitem>
 
393
</varlistentry>
 
394
 
 
395
<varlistentry>
 
396
<term id="setup-ui-toolview">Configuring the Toolview Tab Layout</term>
 
397
<listitem>
 
398
<para>
 
399
The <guilabel>Toolview Tab Layout</guilabel> configuration section will be available in IDEAl mode only. Use these radio buttons to set up the look of the toolview tabs which surround the main working area in this mode.
 
400
</para>
 
401
 
 
402
<variablelist>
 
403
<varlistentry>
 
404
  <term><guilabel>Icons</guilabel></term>
 
405
  <listitem>
 
406
  <para>
 
407
  Each tab will show an icon only. If the associated toolview is displayed, the tab will open and a descriptive text for this toolview be shown. You may want to use this mode if you work on a monitor with limited resolution.
 
408
  </para>
 
409
  <para>
 
410
  The icons are not very descriptive, however. If you want to find out which toolview is assigned to a given tab, point at it with the mouse and wait a second. A short tooltip will then pop up with the toolview name.
 
411
  </para>
 
412
  </listitem>
 
413
</varlistentry>
 
414
<varlistentry>
 
415
  <term><guilabel>Text</guilabel></term>
 
416
  <listitem><para>
 
417
  This is the default toolview tab display mode. Each tab displays the name of its associated toolview.
 
418
  </para></listitem>
 
419
</varlistentry>
 
420
<varlistentry>
 
421
  <term><guilabel>Text and Icons</guilabel></term>
 
422
  <listitem><para>
 
423
  If the standard text toolview display looks too flat to you and you are working on a high-resolution monitor you may want to select this radio button. It will cause the name of the associated toolview be displayed on each tab plus an icon to the left of it, making the tabs easier to distinguish. See the <link linkend="folded-toolview-tabs">Folded Toolview Tabs</link> illustration below for an example.
 
424
  </para></listitem>
 
425
</varlistentry>
 
426
</variablelist>
 
427
</listitem>
 
428
</varlistentry>
 
429
 
 
430
<varlistentry>
 
431
<term>Folded Toolview Tabs</term>
 
432
<listitem>
 
433
<para>
 
434
If you selected the IDEAl mode toolview tabs to display texts (with or without accompanying icons) you need not worry about them being hidden behind some toolview window. If one of the bottom toolview windows occupies more space than is available to display all (vertical) tabs, they will fold around as this illustration shows:
 
435
</para>
 
436
 
 
437
<screenshot>
 
438
  <mediaobject id="folded-toolview-tabs">
 
439
    <imageobject>
 
440
      <imagedata fileref="folded-tabs.png" format="PNG"/>
 
441
    </imageobject>
 
442
<textobject><phrase>Toolview tabs fold to not be hidden behind another view window</phrase></textobject>
 
443
    <caption><para>
 
444
    Toolview tabs fold to not be hidden behind another view window
 
445
    </para></caption>
 
446
  </mediaobject>
 
447
</screenshot>
 
448
 
 
449
<note><para>
 
450
The active toolview window must be shown fixed (non-overlap mode), sharing the work area with the other windows, to force such tab folding. Press the small square in the window border to accomplish this as shown in the example.
 
451
</para></note>
 
452
</listitem>
 
453
</varlistentry>
 
454
</variablelist>
 
455
 
 
456
</sect2> <!-- setup-ui -->
 
457
 
 
458
<sect2 id="setup-editor">
 
459
<title>Selecting an Editor</title>
 
460
 
 
461
<para>&kdevelop; allows you to select your favorite text editor tool. Mark the <guilabel>Editor</guilabel> entry in the left hand side selections tree of the <guilabel>Configure KDevelop</guilabel> window. The following dialog will be displayed to the right.
 
462
</para>
 
463
 
 
464
<screenshot>
 
465
  <mediaobject>
 
466
    <imageobject>
 
467
      <imagedata fileref="configure-editor.png" format="PNG"/>
 
468
    </imageobject>
 
469
<textobject><phrase>Select an editor</phrase></textobject>
 
470
    <caption><para>
 
471
    Select an editor
 
472
    </para></caption>
 
473
  </mediaobject>
 
474
</screenshot>
 
475
 
 
476
<para>
 
477
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 <link linkend="setup-editor-kparts">Important</link> note below for this). Click on the editor of your liking and click <guilabel>OK</guilabel>. Currently there are tree possibilities:
 
478
</para>
 
479
 
 
480
<variablelist>
 
481
  <varlistentry>
 
482
  <term><guilabel>Embedded Advanced Text Editor</guilabel></term>
 
483
  <listitem><para>
 
484
  This is the &kde; standard <application>Kate</application> editor part.
 
485
  </para></listitem>
 
486
  </varlistentry>
 
487
  <varlistentry>
 
488
  <term><guilabel>Embedded Vim Component</guilabel></term>
 
489
  <listitem>
 
490
    <para>
 
491
    This provides the look and feel of the base &Linux; <application>vi</application> editor.
 
492
    </para>
 
493
    <note><itemizedlist>
 
494
      <listitem><para>
 
495
      You need to have a suitable <application>Vim</application> application installed. Have a look at the <ulink url="http://www.freehackers.org/kvim/">KVim</ulink> website for more information.
 
496
      </para></listitem>
 
497
      <listitem><para>
 
498
      Furthermore you need to configure the KParts Vim component in the <guilabel>&kde; Control Center</guilabel> (<menuchoice><guimenuitem>KDE Components</guimenuitem><guimenuitem>Vim Component Configuration</guimenuitem></menuchoice>) before you can use it.
 
499
      </para></listitem>
 
500
    </itemizedlist></note>
 
501
  </listitem>
 
502
  </varlistentry>
 
503
  <varlistentry>
 
504
  <term><guilabel>Qt Designer Based Text Editor</guilabel></term>
 
505
  <listitem><para>
 
506
  This is the editor &Qt; provides in its <application>Designer</application> component.
 
507
  </para></listitem>
 
508
  </varlistentry>
 
509
</variablelist>
 
510
 
 
511
<para>
 
512
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 <guilabel>Messages Output View</guilabel> window has been provided.
 
513
</para>
 
514
 
 
515
<note><para>
 
516
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.
 
517
</para></note>
 
518
 
 
519
<important id="setup-editor-kparts"><para>
 
520
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.
 
521
</para></important>
 
522
</sect2> <!-- setup-editor -->
 
523
 
 
524
<sect2 id="setup-format">
 
525
<title>Selecting a Source Format Style</title>
 
526
 
 
527
<para>
 
528
&kdevelop; automatically formats a source text in a predefined style. This style is highly configurable.
 
529
</para>
 
530
 
 
531
<note><para>
 
532
The reformat source feature is currently available for C, C++, and &Java; only. Especially you cannot use it for scripting languages like &eg; PHP. This is because &kdevelop; uses the <ulink url="http://astyle.sourceforge.net/">astyle</ulink> application to implement this feature.
 
533
</para></note>
 
534
 
 
535
<para>
 
536
To set up a specific format style, select <menuchoice> <guimenu>Settings</guimenu> <guimenuitem>Configure KDevelop...</guimenuitem> </menuchoice> from the menubar. The <guilabel>Customize KDevelop</guilabel> dialog will pop up, where you have to select <guilabel>Source Formatter</guilabel> in the left hand tree. This will display a series of three settings dialog tabs to the right, namely a <link linkend="setup-format-general">General Formatting Setup</link>, a <link linkend="setup-format-indent">Indentation Style Setup</link>, and a <link linkend="setup-format-other">Other Formatting Setup</link>.
 
537
</para>
 
538
 
 
539
<tip><para>
 
540
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 explicitly use the <menuchoice><guimenu>Edit</guimenu><guimenuitem>Reformat Source</guimenuitem></menuchoice> command.
 
541
</para></tip>
 
542
 
 
543
<note><para>
 
544
The exact outcome of these style formatting definitions depends on the <link linkend="setup-editor">editor</link> you use. Currently, most settings are tailored to the Kate editor part (the <quote>Embedded Advanced Text Editor</quote>). Some other editors (&eg; 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.
 
545
</para></note>
 
546
 
 
547
<warning><para>
 
548
There 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.
 
549
</para></warning>
 
550
 
 
551
<sect3 id="setup-format-general">
 
552
<title>General Formatting Setup</title>
 
553
 
 
554
<para>
 
555
The <guilabel>General</guilabel> tab of the <guilabel>Source Formatter</guilabel> dialog allows you to select one out of five predefined source format styles.
 
556
</para>
 
557
 
 
558
<screenshot>
 
559
  <mediaobject>
 
560
    <imageobject>
 
561
      <imagedata fileref="SF-general.png" format="PNG"/>
 
562
    </imageobject>
 
563
<textobject><phrase>Source format style general setup</phrase></textobject>
 
564
    <caption><para>
 
565
    Source format style general setup
 
566
    </para></caption>
 
567
  </mediaobject>
 
568
</screenshot>
 
569
 
 
570
<para>
 
571
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 <guilabel>User defined</guilabel> radio button and define your own source formatting style preferences on the other two tabs which will become available then.
 
572
</para>
 
573
 
 
574
<note><para>
 
575
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 tailor the settings to your liking.
 
576
</para></note>
 
577
 
 
578
</sect3> <!-- setup-format-general -->
 
579
 
 
580
<sect3 id="setup-format-indent">
 
581
<title>Indentation Style Setup</title>
 
582
 
 
583
<para>
 
584
Proper indentation is the main means to enhance readability of a source text. I you selected the <guilabel>Indentation</guilabel> tab of the <guilabel>Source Formatter</guilabel> dialog you will be presented with a series of indentation formatting choices grouped into three boxes as following.
 
585
</para>
 
586
 
 
587
<screenshot>
 
588
  <mediaobject>
 
589
    <imageobject>
 
590
      <imagedata fileref="SF-indent.png" format="PNG"/>
 
591
    </imageobject>
 
592
<textobject><phrase>Source format indentation style setup</phrase></textobject>
 
593
    <caption><para>
 
594
    Source format indentation style setup
 
595
    </para></caption>
 
596
  </mediaobject>
 
597
</screenshot>
 
598
 
 
599
<variablelist>
 
600
<varlistentry>
 
601
<term>Default Settings</term>
 
602
<listitem>
 
603
<para>The preset format choices will cause the source text to resemble the
 
604
ANSI formatting style:</para>
 
605
 
 
606
<screen>
 
607
namespace foospace
 
608
{
 
609
  int Foo()
 
610
  {
 
611
    if (isBar)
 
612
    {
 
613
      bar();
 
614
      return 1;
 
615
    }
 
616
    else
 
617
      return 0;
 
618
  }
 
619
}
 
620
</screen>
 
621
</listitem>
 
622
</varlistentry>
 
623
 
 
624
<varlistentry>
 
625
<term id="setup-format-indent-filling">Defining Indentation Width and Characters</term>
 
626
<listitem>
 
627
<para>The radio buttons grouped in the <guilabel>Filling</guilabel> group
 
628
define how indents in the source text will be drawn.</para>
 
629
 
 
630
<variablelist>
 
631
  <varlistentry>
 
632
    <term><guilabel>Use tabs</guilabel></term>
 
633
    <listitem>
 
634
    <para>
 
635
    This will cause the editor to insert a tab character for each
 
636
indentation level. The tab width is predefined in the editor settings (8 or
 
637
4 character columns usually). Use <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure Editor...</guimenuitem></menuchoice> to redefine it.
 
638
    </para>
 
639
    <note><para>
 
640
    The actual tab width definition procedure depends on the editor you selected in the <link linkend="setup-editor">Selecting an Editor</link> configuration step. You will have to look up the corresponding editor help to find out.
 
641
    </para></note>
 
642
    </listitem>
 
643
  </varlistentry>
 
644
  <varlistentry>
 
645
    <term><guilabel>Use spaces</guilabel></term>
 
646
    <listitem><para>
 
647
    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.
 
648
    </para></listitem>
 
649
  </varlistentry>
 
650
</variablelist>
 
651
</listitem>
 
652
</varlistentry>
 
653
 
 
654
<varlistentry>
 
655
<term>Indented Entities</term>
 
656
<listitem>
 
657
<para>This defines which of the (C/C++) entities will be formatted with an
 
658
extra indent beyond the current indentation level.</para>
 
659
 
 
660
<para>By default only <guilabel>namespaces</guilabel> and
 
661
<guilabel>labels</guilabel> will be extra indented. You may want to
 
662
experiment with various settings to tailor those extra indents to your
 
663
liking.</para>
 
664
</listitem>
 
665
</varlistentry>
 
666
 
 
667
<varlistentry>
 
668
<term>Continuation</term>
 
669
<listitem>
 
670
<para>
 
671
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.
 
672
</para>
 
673
 
 
674
<note><para>
 
675
This applies to <emphasis>static word wrap cases</emphasis> 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.
 
676
</para></note>
 
677
 
 
678
<variablelist>
 
679
  <varlistentry>
 
680
    <term><guilabel>Maximum in statement</guilabel></term>
 
681
    <listitem>
 
682
    <para>
 
683
    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.
 
684
    </para>
 
685
    <para>
 
686
    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.
 
687
    </para>
 
688
    </listitem>
 
689
  </varlistentry>
 
690
  <varlistentry>
 
691
    <term><guilabel>Minimum in conditional</guilabel></term>
 
692
    <listitem>
 
693
    <para>
 
694
    Conditionals or source following &eg; 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.
 
695
    </para>
 
696
    <para>
 
697
    The default is set to <quote>Twice current</quote> which means that continued conditionals will get an extra indent level of the standard indentation size you selected in the <link linkend="setup-format-indent-filling">Filling</link> group. You may change this extra indent to another fixed width (including zero) using the arrows or by entering the value directly.
 
698
    </para>
 
699
    </listitem>
 
700
  </varlistentry>
 
701
</variablelist>
 
702
</listitem>
 
703
</varlistentry>
 
704
</variablelist>
 
705
 
 
706
</sect3> <!-- setup-format-indent -->
 
707
 
 
708
<sect3 id="setup-format-other">
 
709
<title>Other Formatting Setup</title>
 
710
 
 
711
<screenshot>
 
712
  <mediaobject>
 
713
    <imageobject>
 
714
      <imagedata fileref="SF-other.png" format="PNG"/>
 
715
    </imageobject>
 
716
<textobject><phrase>Other source format style settings</phrase></textobject>
 
717
    <caption><para>
 
718
    Other source format style settings
 
719
    </para></caption>
 
720
  </mediaobject>
 
721
</screenshot>
 
722
 
 
723
<variablelist>
 
724
<varlistentry>
 
725
<term>Controlling the position of braces</term>
 
726
<listitem>
 
727
<para>The radio buttons the (somewhat misnamed)
 
728
<guilabel>Brackets</guilabel> group control the position of block delimiting
 
729
braces in a (C/C++) source text. There are three possibilities from which
 
730
you can select.</para>
 
731
 
 
732
<variablelist>
 
733
  <varlistentry>
 
734
    <term><guilabel>Break</guilabel></term>
 
735
    <listitem>
 
736
    <para>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.</para>
 
737
 
 
738
<screen>
 
739
namespace foospace
 
740
{
 
741
  int Foo()
 
742
  {
 
743
    if (isBar)
 
744
    {
 
745
      bar();
 
746
      return 1;
 
747
    }
 
748
    else
 
749
      return 0;
 
750
  }
 
751
}
 
752
</screen>
 
753
    </listitem>
 
754
  </varlistentry>
 
755
  <varlistentry>
 
756
    <term><guilabel>Attach</guilabel></term>
 
757
    <listitem>
 
758
    <para>
 
759
    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 <token>else</token> of an <token>if</token> statement will be kept in line with the closing brace of the preceding block.
 
760
    </para>
 
761
<screen>
 
762
namespace foospace {
 
763
  int Foo() {
 
764
    if (isBar) {
 
765
      bar();
 
766
      return 1;
 
767
    } else
 
768
      return 0;
 
769
  }
 
770
}
 
771
</screen>
 
772
    </listitem>
 
773
  </varlistentry>
 
774
  <varlistentry>
 
775
    <term><guilabel>Linux Style</guilabel></term>
 
776
    <listitem>
 
777
    <para>
 
778
    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.
 
779
    </para>
 
780
<screen>
 
781
namespace foospace
 
782
{
 
783
  int Foo()
 
784
  {
 
785
    if (isBar) {
 
786
      bar();
 
787
      return 1;
 
788
    } else
 
789
      return 0;
 
790
  }
 
791
}
 
792
</screen>
 
793
    </listitem>
 
794
  </varlistentry>
 
795
</variablelist>
 
796
</listitem>
 
797
</varlistentry>
 
798
 
 
799
<varlistentry>
 
800
<term>Controlling Extra Spaces</term>
 
801
<listitem>
 
802
<para>
 
803
By default &kdevelop; does minimize the use of spaces in source texts.
 
804
</para>
 
805
 
 
806
 
 
807
<screen>
 
808
if (isBar(fooArg)==barValue)
 
809
</screen>
 
810
 
 
811
<para>You may enhance readability if you force the source formatter to
 
812
insert extra spaces in special positions.</para>
 
813
 
 
814
<variablelist>
 
815
  <varlistentry>
 
816
    <term><guilabel>Add spaces around parentheses</guilabel></term>
 
817
    <listitem>
 
818
    <para>In fact what is meant is to add spaces around the text put in parentheses. This enhances the readability of function arguments and conditionals.</para>
 
819
<screen>
 
820
if ( isBar( fooArg )==barValue )
 
821
</screen>
 
822
    </listitem>
 
823
  </varlistentry>
 
824
  <varlistentry>
 
825
    <term><guilabel>Add spaces around operators</guilabel></term>
 
826
    <listitem>
 
827
    <para>This will put spaces around assignment and comparison operators to enhance the readability.</para>
 
828
<screen>
 
829
if (isBar(fooArg) == barValue)
 
830
</screen>
 
831
    </listitem>
 
832
  </varlistentry>
 
833
</variablelist>
 
834
</listitem>
 
835
</varlistentry>
 
836
 
 
837
<varlistentry>
 
838
<term>Controlling the formatting of one-line constructs</term>
 
839
<listitem>
 
840
<para>There are a few cases where you don't want the source formatter to
 
841
split a long line apart. For C/C++ code this can be controlled here.</para>
 
842
 
 
843
<variablelist>
 
844
  <varlistentry>
 
845
    <term><guilabel>Keep one-line statements</guilabel></term>
 
846
    <listitem><para>
 
847
    This keeps single line statements together in some situations even if they exceed a fixed maximum line length.
 
848
    </para></listitem>
 
849
  </varlistentry>
 
850
  <varlistentry>
 
851
    <term><guilabel>Keep one-line blocks</guilabel></term>
 
852
    <listitem><para>
 
853
    This keeps single line blocks together in some situations even if they exceed a fixed maximum line length.
 
854
    </para></listitem>
 
855
  </varlistentry>
 
856
</variablelist>
 
857
</listitem>
 
858
</varlistentry>
 
859
</variablelist>
 
860
 
 
861
 
 
862
</sect3> <!-- setup-format-other -->
 
863
 
 
864
</sect2> <!-- setup-format -->
 
865
 
 
866
<sect2 id="setup-snippets">
 
867
<title>Setting Up the Code Snippets Tool</title>
 
868
 
 
869
<para>
 
870
When editing in &kdevelop; you can store often used parts of code as <link linkend="editing-snippets">Code Snippets</link>. To configure the capabilities of the code snippets part select <menuchoice> <guimenu>Settings</guimenu> <guimenuitem>Configure KDevelop...</guimenuitem> </menuchoice> from the menubar. The <guilabel>Customize KDevelop</guilabel> dialog will pop up, where you have to select <guilabel>Code Snippets</guilabel> in the left hand tree. This will show the following dialog in the right hand side.
 
871
</para>
 
872
 
 
873
<screenshot>
 
874
  <mediaobject>
 
875
    <imageobject>
 
876
      <imagedata fileref="configure-snippets.png" format="PNG"/>
 
877
    </imageobject>
 
878
<textobject><phrase>Configuring the code snippets tool</phrase></textobject>
 
879
    <caption><para>
 
880
    Configuring the Code Snippets tool
 
881
    </para></caption>
 
882
  </mediaobject>
 
883
</screenshot>
 
884
 
 
885
<variablelist>
 
886
<varlistentry>
 
887
<term>Activate Snippet Preview</term>
 
888
<listitem>
 
889
<para>Mark the <guilabel>Show snippet's text in tooltip</guilabel> checkbox
 
890
if you want to view the stored text in a tooltip window whenever you keep
 
891
the mouse cursor over the title of that snippet.</para>
 
892
</listitem>
 
893
</varlistentry>
 
894
 
 
895
<varlistentry>
 
896
<term>Working with Snippet Variables</term>
 
897
<listitem>
 
898
<para>The <guilabel>Code Snippets</guilabel> tool allows for a variable text
 
899
in predefined places any time you insert a snippet into a file. To
 
900
accomplish this  <guilabel>Code Snippets</guilabel> provides its own
 
901
variables' mechanism. You can set up its behaviour in the
 
902
<guilabel>Variables</guilabel> group.</para>
 
903
 
 
904
<variablelist>
 
905
  <varlistentry>
 
906
    <term><guilabel>Delimiter</guilabel></term>
 
907
    <listitem><para>
 
908
    The <guilabel>Code Snippets</guilabel> tool distinguishes variables in the text by surrounding the variable name with special delimiter symbols. To use your own delimiter symbol, change the predefined <guilabel>$</guilabel> character in the <guilabel>Delimiter</guilabel> field.
 
909
    </para></listitem>
 
910
  </varlistentry>
 
911
  <varlistentry>
 
912
    <term><guilabel>Input method for variables</guilabel></term>
 
913
    <listitem><itemizedlist>
 
914
      <listitem><para>
 
915
      <guilabel>Single dialog for each variable within a snippet</guilabel> &ndash; will in turn pop up a separate dialog for each variable which the tool finds when inserting the selected code snippet.
 
916
      </para></listitem>
 
917
      <listitem><para>
 
918
      <guilabel>One dialog for all variables within a snippet</guilabel> &ndash; will pop up a common dialog where the user has to fill in the values of all variables before the snippet will be inserted
 
919
      </para></listitem>
 
920
    </itemizedlist></listitem>
 
921
  </varlistentry>
 
922
</variablelist>
 
923
</listitem>
 
924
</varlistentry>
 
925
</variablelist>
 
926
 
 
927
</sect2> <!-- setup-snippets -->
 
928
 
 
929
<sect2 id="setup-fileselector">
 
930
<title>Configuring the File Selector</title>
 
931
 
 
932
<para>
 
933
&kdevelop; provides a <guilabel>File Selector</guilabel> plugin which, when
 
934
loaded at start-up, allows to navigate to any file or directory in the
 
935
system.
 
936
</para>
 
937
 
 
938
<screenshot id="setup-fileselector-image">
 
939
  <mediaobject>
 
940
    <imageobject>
 
941
      <imagedata fileref="file-selector.png" format="PNG"/>
 
942
    </imageobject>
 
943
<textobject><phrase>The file selector in IDEAl mode</phrase></textobject>
 
944
    <caption><para>
 
945
    The file selector (IDEAl mode)
 
946
    </para></caption>
 
947
  </mediaobject>
 
948
</screenshot>
 
949
 
 
950
<para>The behaviour of the <guilabel>File Selector</guilabel> can be highly
 
951
configured. Select <menuchoice> <guimenu>Settings</guimenu>
 
952
<guimenuitem>Configure KDevelop...</guimenuitem> </menuchoice> from the
 
953
menubar. The <guilabel>Customize KDevelop</guilabel> dialog will pop up,
 
954
where you have to select <guilabel>File Selector</guilabel> in the left hand
 
955
tree. This will show the following dialog in the right hand side.</para>
 
956
 
 
957
 
 
958
<screenshot>
 
959
  <mediaobject>
 
960
    <imageobject>
 
961
      <imagedata fileref="configure-file-selector.png" format="PNG"/>
 
962
    </imageobject>
 
963
<textobject><phrase>Configuring the file selector</phrase></textobject>
 
964
    <caption><para>
 
965
    Configuring the file selector
 
966
    </para></caption>
 
967
  </mediaobject>
 
968
</screenshot>
 
969
 
 
970
<variablelist>
 
971
<varlistentry>
 
972
<term>Configuring the Toolbar</term>
 
973
<listitem>
 
974
<para>There is a toolbar on top of the <guilabel>File Selector</guilabel>
 
975
which can be configured as usual in the <guilabel>Toolbar</guilabel>
 
976
group.</para>
 
977
 
 
978
<procedure id="setup-fileselector-add-action">
 
979
  <title>Add an Action to the Toolbar</title>
 
980
  <step>
 
981
    <para>
 
982
    Select an item in the right hand <guilabel>Selected actions</guilabel> list after which the new action should be inserted.
 
983
    </para>
 
984
  </step>
 
985
  <step>
 
986
    <para>
 
987
    Select the action to be inserted in the left hand <guilabel>Available actions</guilabel> list.
 
988
    </para>
 
989
  </step>
 
990
  <step>
 
991
    <para>
 
992
    Click the right (upper) arrow between both lists.
 
993
    </para>
 
994
    <para>The action will be removed from the <guilabel>Available actions</guilabel> list and inserted into the <guilabel>Selected actions</guilabel> list below the selected item.
 
995
    </para>
 
996
  </step>
 
997
</procedure>
 
998
 
 
999
<procedure>
 
1000
  <title>Remove an Action from the Toolbar</title>
 
1001
  <step>
 
1002
    <para>
 
1003
    Select the item to be removed in the right hand <guilabel>Selected actions</guilabel> list.
 
1004
    </para>
 
1005
  </step>
 
1006
  <step>
 
1007
    <para>
 
1008
    Click the left (lower) arrow between both lists.
 
1009
    </para>
 
1010
    <para>The selected item will be removed from the <guilabel>Selected actions</guilabel> list and put back into the <guilabel>Available actions</guilabel> list.
 
1011
    </para>
 
1012
  </step>
 
1013
</procedure>
 
1014
 
 
1015
<procedure>
 
1016
  <title>Reorder the Actions on the Toolbar</title>
 
1017
  <step>
 
1018
    <para>
 
1019
    Select the action to be moved in the right hand <guilabel>Selected actions</guilabel> list.
 
1020
    </para>
 
1021
  </step>
 
1022
  <step>
 
1023
    <para>
 
1024
    Click the up or down arrow to the right of this list.
 
1025
    </para>
 
1026
    <para>The selected item will be moved up or down the <guilabel>Selected actions</guilabel> list.
 
1027
    </para>
 
1028
  </step>
 
1029
</procedure>
 
1030
</listitem>
 
1031
</varlistentry>
 
1032
 
 
1033
<varlistentry>
 
1034
<term id="setup-fileselector-autosync">Defining When the Contents Should
 
1035
Change</term>
 
1036
<listitem>
 
1037
<para>
 
1038
Updating the contents in the <guilabel>File Selector</guilabel> window takes time and resources, esp. when changing to another directory. Therefore  <guilabel>File Selector</guilabel> 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 explicitly want to refresh its contents.
 
1039
</para>
 
1040
 
 
1041
<note><para>
 
1042
Click the <guilabel>Reload</guilabel> button in the toolbar to update the contents of the <guilabel>File Selector</guilabel>. This toolbar button is not available by default, however. You must <link linkend="setup-fileselector-add-action">insert it there</link> first.
 
1043
</para></note>
 
1044
 
 
1045
<para>
 
1046
You can configure the <guilabel>File Selector</guilabel> to immediately reflect certain changes in your work. The settings in the <guilabel>Auto Synchronization</guilabel> group of the configuration dialog are responsible for this.
 
1047
</para>
 
1048
 
 
1049
<variablelist>
 
1050
  <varlistentry>
 
1051
    <term><guilabel>When a document becomes active</guilabel></term>
 
1052
    <listitem><para>
 
1053
    If you select this checkbox, the contents in the <guilabel>File Selector</guilabel> window will be updated whenever you go to another already open document, &eg; when you click on the tab of the according edit window in IDEAl mode. If necessary the <guilabel>File Selector</guilabel> will switch to the directory this file belongs to and update the display to show the actual contents in there.
 
1054
    </para></listitem>
 
1055
  </varlistentry>
 
1056
  <varlistentry>
 
1057
    <term><guilabel>When a document is opened</guilabel></term>
 
1058
    <listitem><para>
 
1059
    If you select this checkbox, the contents in the <guilabel>File Selector</guilabel> window will be updated whenever a document will be opened, &eg; by the <menuchoice><guimenu>File</guimenu><guimenuitem>Open</guimenuitem></menuchoice> menu. If necessary the <guilabel>File Selector</guilabel> will switch to the directory this file belongs to and update the display to show the actual contents in there.
 
1060
    </para></listitem>
 
1061
  </varlistentry>
 
1062
  <varlistentry>
 
1063
    <term><guilabel>When the file selector becomes visible</guilabel></term>
 
1064
    <listitem><para>
 
1065
    If you select this checkbox, the contents in the <guilabel>File Selector</guilabel> 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.
 
1066
    </para></listitem>
 
1067
  </varlistentry>
 
1068
</variablelist>
 
1069
 
 
1070
<para>
 
1071
You may freely combine these settings to tailor the actualization behaviour of the <guilabel>File Selector</guilabel> to your liking.
 
1072
</para>
 
1073
</listitem>
 
1074
</varlistentry>
 
1075
 
 
1076
<varlistentry>
 
1077
<term>Controlling the History in the Comboboxes</term>
 
1078
<listitem>
 
1079
<para>There are two comboboxes on top and bottom of the <guilabel>File
 
1080
Selector</guilabel> contents window which control the directory to be
 
1081
displayed (top combobox) and the filters to be applied to the file display
 
1082
(bottom combobox). A history of the most recent settings is kept in the
 
1083
selection field of each combobox. You can configure the number of history
 
1084
entries as follows.</para>
 
1085
 
 
1086
<variablelist>
 
1087
  <varlistentry>
 
1088
    <term><guilabel>Remember locations</guilabel></term>
 
1089
    <listitem><para>
 
1090
    Enter here the maximum number of directory selections the upper combobox shall remember.
 
1091
    </para></listitem>
 
1092
  </varlistentry>
 
1093
  <varlistentry>
 
1094
    <term><guilabel>Remember filters</guilabel></term>
 
1095
    <listitem><para>
 
1096
    Enter here the maximum number of filter definitions the lower combobox shall remember.
 
1097
    </para></listitem>
 
1098
  </varlistentry>
 
1099
 
 
1100
<varlistentry>
 
1101
<term>Controlling What Should be Remembered Between Sessions</term>
 
1102
<listitem>
 
1103
<para>
 
1104
By default the <guilabel>File Selector</guilabel> 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 <guilabel>Session</guilabel> configuration group.
 
1105
</para>
 
1106
 
 
1107
<note><para>
 
1108
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.
 
1109
</para></note>
 
1110
</listitem>
 
1111
</varlistentry>
 
1112
 
 
1113
  <varlistentry>
 
1114
    <term><guilabel>Restore location</guilabel></term>
 
1115
    <listitem>
 
1116
    <para>
 
1117
    Remove the checkbox mark here if you don't want the displayed location be remembered between sessions.
 
1118
    </para>
 
1119
    <note><para>
 
1120
    If you selected one of the <link linkend="setup-fileselector-autosync">automatic update</link> settings the displayed location might automatically change regardless what has been remembered from the recent session.
 
1121
    </para></note>
 
1122
    </listitem>
 
1123
  </varlistentry>
 
1124
  <varlistentry>
 
1125
    <term><guilabel>Restore filters</guilabel></term>
 
1126
    <listitem>
 
1127
    <para>
 
1128
    Remove the checkbox mark here if you don't want the filters applied to the display be remembered between sessions.
 
1129
    </para>
 
1130
    </listitem>
 
1131
  </varlistentry>
 
1132
</variablelist>
 
1133
</listitem>
 
1134
</varlistentry>
 
1135
</variablelist>
 
1136
 
 
1137
</sect2> <!-- setup-fileselector -->
 
1138
 
 
1139
<sect2 id="setup-new-file-wizard">
 
1140
<title>Configuring the New File Wizard</title>
 
1141
 
 
1142
<para>
 
1143
(... to be written ...)
 
1144
</para>
 
1145
 
 
1146
</sect2> <!-- setup-new-file-wizard -->
 
1147
 
 
1148
</sect1> <!-- setup-general -->
 
1149
 
 
1150
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
 
1151
 
 
1152
<sect1 id="setup-docu">
 
1153
<title>Configuring the Documentation</title>
 
1154
 
 
1155
<para>
 
1156
&kdevelop; contains a very powerful documentation facility which provides access to several kinds of extensive documentation. In &eg; IDEAl mode you find a <guilabel>Documentation</guilabel> tab at the right border of the work area.
 
1157
</para>
 
1158
 
 
1159
<screenshot>
 
1160
  <mediaobject>
 
1161
    <imageobject>
 
1162
      <imagedata fileref="documents-contents.png" format="PNG"/>
 
1163
    </imageobject>
 
1164
<textobject><phrase>The &kdevelop; documentation window in IDEAl mode</phrase></textobject>
 
1165
    <caption><para>
 
1166
    The &kdevelop; documentation window (IDEAl mode)
 
1167
    </para></caption>
 
1168
  </mediaobject>
 
1169
</screenshot>
 
1170
 
 
1171
<note><para>
 
1172
&kdevelop; must have loaded the <guilabel>Documentation</guilabel> plugin in order to view the documentation tree. See the <link linkend="setup-plugins">Plugin Tools</link> section for more info.
 
1173
</para></note>
 
1174
 
 
1175
<para>
 
1176
You may set up contents and behaviour of the various parts of this documentation window if you select <menuchoice> <guimenu>Settings</guimenu> <guimenuitem>Configure KDevelop...</guimenuitem> </menuchoice> from the menubar. The <guilabel>Customize KDevelop</guilabel> dialog will pop up, where you have to select <guilabel>Documentation</guilabel> in the left hand window.
 
1177
</para>
 
1178
 
 
1179
<para>
 
1180
The thus displayed <link linkend="configure-docu-general">configuration page</link> shows three tabbed configuration dialog pages, namely:
 
1181
</para>
 
1182
 
 
1183
<simplelist>
 
1184
  <member><link linkend="setup-docu-general">Documentation Collections</link></member>
 
1185
  <member><link linkend="setup-docu-textsearch">Full Text Search</link></member>
 
1186
  <member><link linkend="setup-docu-other">Other</link></member>
 
1187
</simplelist>
 
1188
 
 
1189
<sect2 id="setup-docu-general">
 
1190
<title>Setting Up Documentation Collections</title>
 
1191
 
 
1192
<para>
 
1193
The documentation configuration settings have been divided into a series of documentation collections, each providing access to documentation files of some unique format and content type. These setups control which documentation items will be listed on the <guilabel>Contents</guilabel> page of the &kdevelop; <guilabel>Documentation</guilabel> facility, and how the user may access documentation details by indexed and full text searches.
 
1194
</para>
 
1195
<para>
 
1196
The <guilabel>Documentation</guilabel> tab provides a series of configuration pages which are ordered vertically like a stack of index cards. One page at a time will open after a click on its index card title:
 
1197
</para>
 
1198
<simplelist>
 
1199
  <member><link linkend="setup-docu-general-qt">&Qt; Documentation Collection</link></member>
 
1200
  <member><link linkend="setup-docu-general-chm">CHM Documentation Collection</link></member>
 
1201
  <member><link linkend="setup-docu-general-dox">Doxygen Documentation Collection</link></member>
 
1202
  <member><link linkend="setup-docu-general-toc">&kdevelop; TOC Documentation Collection</link></member>
 
1203
  <member><link linkend="setup-docu-general-devhelp">Devhelp Documentation Collection</link></member>
 
1204
  <member><link linkend="setup-docu-general-custom">Custom Documentation Collection</link></member>
 
1205
</simplelist>
 
1206
 
 
1207
<para id="configure-docu-general">
 
1208
<screenshot>
 
1209
  <mediaobject>
 
1210
    <imageobject>
 
1211
      <imagedata fileref="configure-docu-general.png" format="PNG"/>
 
1212
    </imageobject>
 
1213
<textobject><phrase>Setting up documentation collections</phrase></textobject>
 
1214
    <caption><para>
 
1215
    Setting up documentation collections
 
1216
    </para></caption>
 
1217
  </mediaobject>
 
1218
</screenshot>
 
1219
</para>
 
1220
 
 
1221
<sect3 id="setup-docu-general-common">
 
1222
<title>Common Documentation Setup Structure</title>
 
1223
 
 
1224
<para>
 
1225
All configurations pages on the <guilabel>Documentation</guilabel> tab use a common layout. You will find the currently available documentation items of this type listed on the open page to the left and a set of buttons to the right.
 
1226
</para>
 
1227
 
 
1228
<variablelist>
 
1229
<varlistentry>
 
1230
<term id="setup-docu-buttons">Buttons to Maintain Documentation List Contents</term>
 
1231
<listitem>
 
1232
<para>
 
1233
There are three buttons available to maintain the contents of the documentation setup pages:
 
1234
</para>
 
1235
 
 
1236
<variablelist>
 
1237
  <varlistentry>
 
1238
    <term><guibutton>Add</guibutton></term>
 
1239
    <listitem>
 
1240
      <para>Opens a <guilabel>Documentation Catalog Properties</guilabel> dialog as shown below where you can select the source location of the documentation item to be added and name it.</para>
 
1241
    </listitem>
 
1242
  </varlistentry>
 
1243
  <varlistentry>
 
1244
    <term><guibutton>Edit</guibutton></term>
 
1245
    <listitem>
 
1246
      <para>Opens a <guilabel>Documentation Catalog Properties</guilabel> dialog as shown below where you can change the source location of the documentation item previously selected in the list and rename it.</para>
 
1247
    </listitem>
 
1248
  </varlistentry>
 
1249
  <varlistentry>
 
1250
    <term><guibutton>Remove</guibutton></term>
 
1251
    <listitem>
 
1252
      <para>Removes the selected documentation entry from the list.</para>
 
1253
      <note><para>
 
1254
      The entry will be removed from the list only. Actual documentation sources remain untouched. You will have to remove them explicitly by other means.
 
1255
      </para></note>
 
1256
    </listitem>
 
1257
  </varlistentry>
 
1258
</variablelist>
 
1259
 
 
1260
<screenshot>
 
1261
  <mediaobject>
 
1262
    <imageobject>
 
1263
      <imagedata fileref="configure-docu-edit.png" format="PNG"/>
 
1264
    </imageobject>
 
1265
    <caption><para>
 
1266
    Add or change a documentation item
 
1267
    </para></caption>
 
1268
  </mediaobject>
 
1269
</screenshot>
 
1270
 
 
1271
<para>
 
1272
The button to the right of the <guilabel>Location</guilabel> field opens a directory dialog whose entries usually will be filtered according to the file type of the selected configuration page.
 
1273
</para>
 
1274
<para>
 
1275
The <guilabel>Title</guilabel> field may not be accessible, depending on the documentation type to be maintained.
 
1276
</para>
 
1277
</listitem>
 
1278
</varlistentry>
 
1279
<varlistentry>
 
1280
<term id="setup-docu-columns">Documentation List Structure</term>
 
1281
<listitem>
 
1282
<para>
 
1283
Every documentation setup page shows the listed documentation items in a table with four columns:
 
1284
</para>
 
1285
 
 
1286
<variablelist>
 
1287
  <varlistentry>
 
1288
    <term><guilabel>TOC</guilabel></term>
 
1289
    <listitem>
 
1290
      <para>
 
1291
      If this check box is marked, this documentation item will show up on the <guilabel>Contents</guilabel> page of the &kdevelop; <guilabel>Documentation</guilabel> facility.
 
1292
      </para>
 
1293
      <note><para>
 
1294
      Unchecking the <guilabel>TOC</guilabel> check box will in turn disable the <guilabel>Index</guilabel> and <guilabel>Search</guilabel> check boxes (see below). Thus you cannot have documentation collection items indexed but not shown in the contents.
 
1295
      </para></note>
 
1296
    </listitem>
 
1297
  </varlistentry>
 
1298
  <varlistentry>
 
1299
    <term><guilabel>Index</guilabel></term>
 
1300
    <listitem>
 
1301
      <para>
 
1302
      If this check box is marked, an internal index will be built of this documentation item. This provides fast access to the documentation by the use of the <guilabel>Index</guilabel> and (optionally) <guilabel>Finder</guilabel> pages of the &kdevelop; <guilabel>Documentation</guilabel> facility.
 
1303
      </para>
 
1304
      <note>
 
1305
        <para>
 
1306
        The internal index will be built the first time the user selects the <guilabel>Index</guilabel> page. This will delay the first access noticeably, because the index will be read from disk and then cached.
 
1307
        </para>
 
1308
        <para>
 
1309
        All subsequent indexed searches will however use this chache and thus work significantly faster.
 
1310
        </para>
 
1311
      </note>
 
1312
    </listitem>
 
1313
  </varlistentry>
 
1314
  <varlistentry>
 
1315
    <term><guilabel>Search</guilabel></term>
 
1316
    <listitem>
 
1317
      <para>
 
1318
      If this check box is marked, the contents of this documentation item will be included in the full text search path of the <guilabel>Search</guilabel> page of the &kdevelop; <guilabel>Documentation</guilabel> facility.
 
1319
      </para>
 
1320
      <note>
 
1321
        <para>
 
1322
        &kdevelop; utilizes the htdig application collection to perform full text searches. This search is done over an internal index, the htdig machinery has to build before it can be used.
 
1323
        </para>
 
1324
        <para>
 
1325
        Any change of the <guilabel>Search</guilabel> check box marks will thus effect the search runs only after you rebuilt the index on the  <guilabel>Search</guilabel> page of the &kdevelop; <guilabel>Documentation</guilabel> facility.
 
1326
        </para>
 
1327
      </note>
 
1328
    </listitem>
 
1329
  </varlistentry>
 
1330
  <varlistentry>
 
1331
    <term><guilabel>Title</guilabel></term>
 
1332
    <listitem><para>
 
1333
    This is the name of the Documentation item as it will be shown on the <guilabel>Contents</guilabel> page of the &kdevelop; <guilabel>Documentation</guilabel> facility.
 
1334
    </para></listitem>
 
1335
  </varlistentry>
 
1336
</variablelist>
 
1337
 
 
1338
<note><para>
 
1339
Former &kdevelop; versions allowed to select the documentation items to be displayed on a per-project basis. This is not available any more.
 
1340
</para></note>
 
1341
</listitem>
 
1342
</varlistentry>
 
1343
</variablelist>
 
1344
 
 
1345
</sect3> <!-- setup-docu-general-common -->
 
1346
 
 
1347
<sect3 id="setup-docu-general-qt">
 
1348
<title>&Qt; Documentation Collections</title>
 
1349
 
 
1350
<para>
 
1351
On this configuration page all &Qt; documentation is set up.
 
1352
</para>
 
1353
 
 
1354
<screenshot>
 
1355
  <mediaobject>
 
1356
    <imageobject>
 
1357
      <imagedata fileref="configure-docu-general.png" format="PNG"/>
 
1358
    </imageobject>
 
1359
<textobject><phrase>Setting up the &Qt; documentation collection</phrase></textobject>
 
1360
    <caption><para>
 
1361
    Setting up the &Qt; documentation collection
 
1362
    </para></caption>
 
1363
  </mediaobject>
 
1364
</screenshot>
 
1365
 
 
1366
<para>
 
1367
Normally &kdevelop; will fill this in on its first start-up. It looks for standard <filename>*.xml</filename>, or <filename>*.dcf</filename> documentation files in the &Qt; installation directory. The table to the left lists the files &kdevelop; found by their standard titles.
 
1368
</para>
 
1369
 
 
1370
<para>
 
1371
If you have a non-standard installation, either there will be no information listed at all or the entries will possibly refer to improper locations (&eg; to another &Qt; installation available in your system). You may adjust the entries using the <link linkend="setup-docu-buttons">buttons</link> to the right of the list field.
 
1372
</para>
 
1373
 
 
1374
<note><para>
 
1375
&kdevelop; will use the titles already provided by the installed &Qt; documentation. Hence the <guilabel>Title</guilabel> field in the <guilabel>Documentation Catalog Properties</guilabel> dialog is inaccessible.
 
1376
</para></note>
 
1377
 
 
1378
<para>
 
1379
By default, not all &Qt; documentation will be shown on the <guilabel>Contents</guilabel> page of the &kdevelop; <guilabel>Documentation</guilabel> facility. Use the <guilabel>TOC</guilabel> check box in the <link linkend="setup-docu-columns">setup table</link> to select the documentation to be shown.
 
1380
</para>
 
1381
 
 
1382
<para>
 
1383
If you want to have some specific &Qt; documentation included in the search indexes or full text search use the <guilabel>Index</guilabel> and <guilabel>Search</guilabel>check boxes in the <link linkend="setup-docu-columns">setup table</link>.
 
1384
</para>
 
1385
 
 
1386
</sect3> <!-- setup-docu-general-qt -->
 
1387
 
 
1388
<sect3 id="setup-docu-general-chm">
 
1389
<title>Setting Up the CHM Documentation Collection</title>
 
1390
 
 
1391
<para>
 
1392
On this configuration page you may collect documentation according to the &Microsoft; CHM help file standard.
 
1393
</para>
 
1394
 
 
1395
<screenshot>
 
1396
  <mediaobject>
 
1397
    <imageobject>
 
1398
      <imagedata fileref="configure-docu-chm.png" format="PNG"/>
 
1399
    </imageobject>
 
1400
<textobject><phrase>Setting up &Microsoft; CHM standard documentation files</phrase></textobject>
 
1401
    <caption><para>
 
1402
    Setting up &Microsoft; CHM standard documentation files
 
1403
    </para></caption>
 
1404
  </mediaobject>
 
1405
</screenshot>
 
1406
 
 
1407
<para>
 
1408
By default, this configuration page will be empty (as shown above). You may add new entries using the <link linkend="setup-docu-buttons">buttons</link> to the right of the list field. &kdevelop; will filter <filename>*.chm</filename> files in the directory dialog associated to the <guibutton>Add</guibutton> and <guibutton>Edit</guibutton> buttons.
 
1409
</para>
 
1410
 
 
1411
<para>
 
1412
For more information on the format of &Microsoft; <filename>*.chm</filename> files see &eg; PHP: Documentation - Extended CHM Format at <ulink url="http://de2.php.net/docs-echm.php">http://de2.php.net/docs-echm.php</ulink>.
 
1413
</para>
 
1414
 
 
1415
</sect3> <!-- setup-docu-general-chm -->
 
1416
 
 
1417
<sect3 id="setup-docu-general-dox">
 
1418
<title>Documentation Generated by Doxygen</title>
 
1419
 
 
1420
<para>
 
1421
On this configuration page all &API; documentation generated by &doxygen; is set up.
 
1422
</para>
 
1423
 
 
1424
<screenshot>
 
1425
  <mediaobject>
 
1426
    <imageobject>
 
1427
      <imagedata fileref="configure-docu-dox.png" format="PNG"/>
 
1428
    </imageobject>
 
1429
<textobject><phrase>Setting up Doxygen generated &API; documentation</phrase></textobject>
 
1430
    <caption><para>
 
1431
    Setting up Doxygen generated &API; documentation
 
1432
    </para></caption>
 
1433
  </mediaobject>
 
1434
</screenshot>
 
1435
 
 
1436
<para>
 
1437
In short, such an &API; documents the interface to certain library functions. The &API; documentation on this page should be produced by the externally provided <ulink url="http://www.stack.nl/~dimitri/doxygen/">&doxygen;</ulink> tool.
 
1438
</para>
 
1439
<para>
 
1440
&doxygen; generated &API; documentationconsists of a series of <filename>html</filename> files, starting with <filename>index.html</filename>. Additionally there may exist <filename>tag</filename> files which contain information to link to already existing &API; documentations. Thus &kdevelop; will look for <filename>index.html</filename> and <filename>*.tag</filename> files when searching for &doxygen; generated &API; documentation.
 
1441
</para>
 
1442
<para>
 
1443
There are some structural constraints assumed when searching for &doxygen; generated &API; documentation. The directory in which the <filename>index.html</filename> file resides should contain subdirectories with separate documentation collections. Each of these subdirectories is assumed to contain a <filename>.tag</filename> file and a <filename class="directory">html/</filename> subdirectory.
 
1444
</para>
 
1445
<para>
 
1446
You may have a look at <filename class="directory">$<envar>KDEDIR</envar>/share/doc/HTML/en/kdelibs-apidocs</filename> for an example of such a &doxygen; &API; documentation layout.
 
1447
</para>
 
1448
 
 
1449
<note><para>
 
1450
The older &kde; <ulink url="http://sirtaj.net/projects/kdoc/">KDoc</ulink> generated &API; format is not directly supported any more. If you still want to use such documentation, you may add it on the <link linkend="setup-docu-general-custom">Custom Documentation Collection</link> page.
 
1451
</para></note>
 
1452
 
 
1453
<para>
 
1454
&kdevelop; will have filled in a link to the current &kde; Libraries &API;, provided it found one. There are several ways for &kdevelop; to find out:
 
1455
</para>
 
1456
 
 
1457
<itemizedlist>
 
1458
  <listitem><para>
 
1459
  Either you provided the <command>configure</command> command with the
 
1460
  <option>--with-kdelibsdoxy-dir</option> option when you compiled
 
1461
  &kdevelop; (see the <link linkend="make-api">How to Obtain a &kdevelop; &API; Documentation</link> chapter).
 
1462
  </para></listitem>
 
1463
  <listitem><para>
 
1464
  Or the <command>configure</command> command did automatically find a &doxygen; generated &kde; Libraries &API; in one of several standard locations it knows of.
 
1465
  </para></listitem>
 
1466
  <listitem><para>
 
1467
  Or as a last resort the <filename class="directory">$<envar>KDEDIR</envar>/share/doc/HTML/en/kdelibs-apidocs/</filename> was found at the first &kdevelop; startup.
 
1468
  </para></listitem>
 
1469
</itemizedlist>
 
1470
 
 
1471
<para>
 
1472
If &kdevelop; did not find a valid &doxygen; generated &kde; Libraries &API; at its first start-up the <guilabel>Doxygen Documentation Collection</guilabel> list will be empty.
 
1473
</para>
 
1474
 
 
1475
<para>
 
1476
You may add your own &API; documentation entries (&eg; from your current projects) by using the <link linkend="setup-docu-buttons">buttons</link> to the right. If you want to have them included in the indexed and/or full text search mark the <guilabel>Index</guilabel> or <guilabel>Search</guilabel> check boxes in the <link linkend="setup-docu-columns">setup table</link>.
 
1477
</para>
 
1478
 
 
1479
<note><para>
 
1480
&kdevelop; uses the title information from the <filename>index.html</filename>. Hence the <guilabel>Title</guilabel> field in the <guilabel>Documentation Catalog Properties</guilabel> dialog is inaccessible.
 
1481
</para></note>
 
1482
 
 
1483
<tip>
 
1484
  <para>
 
1485
  The &kde; system provides more &API; documentation than the &kde; Libraries &API; only. You will need additional interfaces information if you want to &eg; 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 <ulink url="http://developer.kde.org/source/index.html">sources</ulink> (using the <command>make apidox</command> and <command>make install</command> commands on the <filename class="directory">kdebase</filename> sources) and then add an entry to the <guilabel>Doxygen Documentation Collection</guilabel> list like this:
 
1486
  </para>
 
1487
  <screenshot><mediaobject>
 
1488
      <imageobject>
 
1489
        <imagedata fileref="configure-adddialog-baselibs.png" format="PNG"/>
 
1490
      </imageobject>
 
1491
<textobject><phrase>Adding a &kde; base &API; to the list</phrase></textobject>
 
1492
      <caption><para>
 
1493
      Adding a &kde; Base &API; to the list
 
1494
      </para></caption>
 
1495
    </mediaobject></screenshot>
 
1496
  <para>
 
1497
  (Of course you should replace the <filename class="directory">/home/dev/mykde-system/</filename> directory in the <guilabel>Location</guilabel> field example with the path to your &kde; installation.)
 
1498
  </para>
 
1499
</tip>
 
1500
 
 
1501
<note><para>
 
1502
You must put the &API; of your current project into this <guilabel>Doxygen Documentation Collection</guilabel> as well. Former &kdevelop; versions did put it into the documentation tree on a per-project basis. This is not provided any more.
 
1503
</para></note>
 
1504
 
 
1505
</sect3> <!-- setup-docu-general-dox -->
 
1506
 
 
1507
<sect3 id="setup-docu-general-toc">
 
1508
<title>Handling Structured Documentation (KDevelopTOC Files)</title>
 
1509
 
 
1510
<para>
 
1511
The main bulk of the &kdevelop; documentation facility provides immediate access to structured documentation, local as well as remote ones. You can configure this on the <guilabel>KDevelopTOC Documentation Collection</guilabel> page.
 
1512
</para>
 
1513
 
 
1514
<screenshot>
 
1515
  <mediaobject>
 
1516
    <imageobject>
 
1517
      <imagedata fileref="configure-docu-toc.png" format="PNG"/>
 
1518
    </imageobject>
 
1519
    <caption><para>
 
1520
    Providing KDevelopTOC structured documentation access
 
1521
    </para></caption>
 
1522
  </mediaobject>
 
1523
</screenshot>
 
1524
 
 
1525
<para>
 
1526
&kdevelop; comes with a bunch of predefined KDevelopTOC files which are automatically entered in the table at installation time. To keep the display manageable only the most often used will initially be marked for display. If you want to see another documentation, mark the <guilabel>TOC</guilabel> check box in the <link linkend="setup-docu-columns">setup table</link>.
 
1527
</para>
 
1528
 
 
1529
<para>
 
1530
KDevelopTOC files cannot be indexed to perform a full text search because they usually point to a remote location. On the other hand, such a <filename>.toc</filename> file can have an index manually defined, using the <computeroutput>&lt;index&gt;</computeroutput> tag. Thus the <guilabel>Index</guilabel> check box will be enabled ony when &kdevelop; finds an <computeroutput>&lt;index&gt;</computeroutput> tag in the <filename>.toc</filename> file. (For more detail see the description below in the <link linkend="setup-docu-general-toc-files">&kdevelop; TOC Files</link> section.)
 
1531
</para>
 
1532
<para>
 
1533
The <guilabel>Search</guilabel> check box in the <link linkend="setup-docu-columns">setup table</link> will always be disabled.
 
1534
</para>
 
1535
 
 
1536
<para>
 
1537
You may add new entries using the <link linkend="setup-docu-buttons">buttons</link> to the right of the list field. &kdevelop; will filter <filename>*.toc</filename> files in the directory dialog associated to the <guibutton>Add</guibutton> and <guibutton>Edit</guibutton> buttons.
 
1538
</para>
 
1539
 
 
1540
<note><para>
 
1541
Other than former &kdevelop; versions will the <guibutton>Remove</guibutton> button not change the <filename>*.toc</filename> files on disk, so the remove operation is safe now.
 
1542
</para></note>
 
1543
 
 
1544
</sect3> <!-- setup-docu-general-toc -->
 
1545
 
 
1546
<sect3 id="setup-docu-general-toc-files">
 
1547
<title>&kdevelop; TOC Files</title>
 
1548
 
 
1549
<para>
 
1550
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 (&eg; <quote>KDE2 Development Book (kde.org)</quote>). 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 <emphasis>remote</emphasis> documentation file.
 
1551
</para>
 
1552
 
 
1553
<para>
 
1554
The rationale behind this is not only to locally navigate remote documentation without wasting net access resources, but to provide the developer with easy, structured access to the documentation he/she needs. Using these tools one can access almost any local or remote documentation in a structured fashion even if the original is laid out flat or structured in another way. All that is needed is access to files and/or parts of files which are displayable by the Konqueror.
 
1555
</para>
 
1556
 
 
1557
<para>
 
1558
Such structured access is made possible through the use of special <quote>table of content</quote> files, which are denoted by <filename>.toc</filename> filename extensions. Any such &kdevelop; TOC file contains an &XML; structured description of the document to be accessed.
 
1559
</para>
 
1560
 
 
1561
<variablelist>
 
1562
<varlistentry>
 
1563
<term>Standard Directory of &kdevelop; TOC Files</term>
 
1564
<listitem>
 
1565
<para>
 
1566
When &kdevelop; was installed usually a series of predefined <filename>.toc</filename> files has been put into the <filename class="directory">$KDEDIR/share/apps/kdevdocumentation/tocs</filename> directory. These are fairly simple, structured text files. You may look at them using a text editor or other text display facility.
 
1567
</para>
 
1568
</listitem>
 
1569
</varlistentry></variablelist>
 
1570
 
 
1571
<!-- FIXME: Lauri Watts (2005-05-03) This could be marked up a whole lot -->
 
1572
<!-- more clearly with the sgmltags stuff.  Making a note to do that once -->
 
1573
<!-- this first revision is done. -->
 
1574
 
 
1575
<variablelist id="toc-file-structure">
 
1576
  <title>Basic Structure of &kdevelop; TOC Files</title>
 
1577
  <varlistentry>
 
1578
    <term>header</term>
 
1579
    <listitem>
 
1580
      <simplelist>
 
1581
        <member>
 
1582
          <computeroutput>&lt;!DOCTYPE kdeveloptoc&gt;</computeroutput>
 
1583
        </member>
 
1584
        <member>
 
1585
          <computeroutput>&lt;kdeveloptoc&gt;</computeroutput>
 
1586
        </member>
 
1587
        <member>
 
1588
          <emphasis>(title)</emphasis>
 
1589
        </member>
 
1590
        <member>
 
1591
          <emphasis>(base address)</emphasis>
 
1592
        </member>
 
1593
        <member>
 
1594
          <emphasis>(content structure)</emphasis>
 
1595
        </member>
 
1596
        <member>
 
1597
          <emphasis>(index structure)</emphasis>
 
1598
        </member>
 
1599
        <member>
 
1600
          <computeroutput>&lt;/kdeveloptoc&gt;</computeroutput>
 
1601
        </member>
 
1602
      </simplelist>
 
1603
      <para>
 
1604
      This &XML; structure will be parsed by the &kdevelop; <guilabel>Documentation</guilabel> 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.
 
1605
      </para>
 
1606
    </listitem>
 
1607
  </varlistentry>
 
1608
  <varlistentry>
 
1609
    <term>title</term>
 
1610
    <listitem>
 
1611
      <simplelist>
 
1612
        <member>
 
1613
          <computeroutput>&lt;title&gt;</computeroutput>
 
1614
          <emphasis>(some title string)</emphasis>
 
1615
          <computeroutput>&lt;/title&gt;</computeroutput>
 
1616
        </member>
 
1617
      </simplelist>
 
1618
      <para>
 
1619
      This is the title &kdevelop; will display at the basic levels in the documentation tree.
 
1620
      </para>
 
1621
      <note><para>
 
1622
      This displayed title cannot be changed by the user. If you want another text be displayed, you must manually change the <computeroutput>&lt;title&gt;</computeroutput> entry in the <filename>.toc</filename> file.
 
1623
      </para></note>
 
1624
    </listitem>
 
1625
  </varlistentry>
 
1626
  <varlistentry>
 
1627
    <term>base address</term>
 
1628
    <listitem>
 
1629
      <simplelist>
 
1630
        <member>
 
1631
          <computeroutput>&lt;base href="</computeroutput>
 
1632
          <emphasis>(base document &URL;)</emphasis>
 
1633
          <computeroutput>"/&gt;</computeroutput>
 
1634
        </member>
 
1635
      </simplelist>
 
1636
      <para>
 
1637
      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 &eg; downloaded a documentation from a remote server, all you need to display the files from this new location is to change its <computeroutput>&lt;base&gt;</computeroutput> &URL;.
 
1638
      </para>
 
1639
    </listitem>
 
1640
  </varlistentry>
 
1641
  <varlistentry>
 
1642
    <term>content structure</term>
 
1643
    <listitem>
 
1644
      <simplelist>
 
1645
        <member>
 
1646
          <computeroutput>&lt;tocsect1 name="</computeroutput>
 
1647
          <emphasis>(section title)</emphasis>
 
1648
          <computeroutput>" url="</computeroutput>
 
1649
          <emphasis>(section &URL;)</emphasis>
 
1650
          <computeroutput>"&gt;</computeroutput>
 
1651
        </member>
 
1652
        <member>...</member>
 
1653
        <member>
 
1654
          <computeroutput>&lt;tocsectn name="</computeroutput>
 
1655
          <emphasis>(section title)</emphasis>
 
1656
          <computeroutput>" url="</computeroutput>
 
1657
          <emphasis>(section &URL;)</emphasis>
 
1658
          <computeroutput>"/&gt;</computeroutput>
 
1659
        </member>
 
1660
        <member>...</member>
 
1661
        <member>
 
1662
          <computeroutput>&lt;/tocsect1&gt;</computeroutput>
 
1663
        </member>
 
1664
      </simplelist>
 
1665
      <para>
 
1666
      All remaining navigation and access information is stored in a series of nested <computeroutput>&lt;tocsecti&gt;</computeroutput> ... <computeroutput>&lt;/tocsecti&gt;</computeroutput> pairs. Each <emphasis>i</emphasis> denotes a consecutive nesting level down to number <emphasis>n</emphasis> which will correspond to the finally displayed documentation section.
 
1667
      </para>
 
1668
      <para>
 
1669
      Any <computeroutput>&lt;tocsecti&gt;</computeroutput> entry must have a <computeroutput>name="xxx"</computeroutput> attribute associated with it (the "xxx" denotes the actual title string). This name will be displayed as level title in the documentation tree. It should correspond to an actual documentation section.
 
1670
      </para>
 
1671
      <para>
 
1672
      There may be an <computeroutput>url=""</computeroutput> attribute associated with any <emphasis>i</emphasis> 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;.
 
1673
      </para>
 
1674
      <para>
 
1675
      The <computeroutput>&lt;tocsectn/&gt;</computeroutput> entry must have an <computeroutput>url=""</computeroutput> attribute whatsoever.
 
1676
      This final nested <computeroutput>&lt;tocsectn/&gt;</computeroutput> does not come in pairs but will immediately be closed by a <computeroutput>/</computeroutput> before the <computeroutput>&gt;</computeroutput> bracket.
 
1677
      </para>
 
1678
      <note><para>
 
1679
      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: <filename>/base-url/section-url#anchor-mark</filename>.
 
1680
      </para></note>
 
1681
    </listitem>
 
1682
  </varlistentry>
 
1683
  <varlistentry>
 
1684
    <term>index structure</term>
 
1685
    <listitem>
 
1686
      <simplelist>
 
1687
        <member>
 
1688
          <computeroutput>&lt;index&gt;</computeroutput>
 
1689
        </member>
 
1690
        <member>
 
1691
          <computeroutput>&lt;entry name="</computeroutput>
 
1692
          <emphasis>(index entry title)</emphasis>
 
1693
          <computeroutput>" url="</computeroutput>
 
1694
          <emphasis>(index section &URL;)</emphasis>
 
1695
          <computeroutput>"/&gt;</computeroutput>
 
1696
        </member>
 
1697
        <member>
 
1698
          <computeroutput>&lt;/index&gt;</computeroutput>
 
1699
        </member>
 
1700
      </simplelist>
 
1701
      <para>
 
1702
      Index is a plain list of index entries - pairs of title and &URL;. Index is not mandatory.
 
1703
      </para>
 
1704
    </listitem>
 
1705
  </varlistentry>
 
1706
</variablelist>
 
1707
<!-- FIXME: End -->
 
1708
 
 
1709
</sect3> <!-- setup-docu-general-toc-files  -->
 
1710
 
 
1711
<sect3 id="setup-docu-general-devhelp">
 
1712
<title>DevHelp Documentation</title>
 
1713
 
 
1714
<para>
 
1715
DevHelp documentation is another means of structured documentation access. It uses structured table of content files denoted by a <filename>.devhelp</filename> extension similar to <link linkend="setup-docu-general-toc-files">&kdevelop; TOC files</link> to access documentation for the GNOME 2 desktop.
 
1716
</para>
 
1717
<para>
 
1718
You can control which DevHelp files should be accessible on the <guilabel>DevHelp Documentation Collection</guilabel> configuration page.
 
1719
</para>
 
1720
 
 
1721
<screenshot>
 
1722
  <mediaobject>
 
1723
    <imageobject>
 
1724
      <imagedata fileref="configure-docu-devhelp.png" format="PNG"/>
 
1725
    </imageobject>
 
1726
    <caption><para>
 
1727
    Providing DevHelp documentation
 
1728
    </para></caption>
 
1729
  </mediaobject>
 
1730
</screenshot>
 
1731
 
 
1732
<para>
 
1733
DevHelp files originally were accessible on the <ulink url="http://lidn.sourceforge.net/">LiDN</ulink> website, but this seems to be not maintained for some time now. More recent DevHelp documentation is available at the <ulink url="http://htmlhelp.berlios.de/books/devhelp.php">DevHelp Books Download</ulink> web page.
 
1734
</para>
 
1735
 
 
1736
<para>
 
1737
When &kdevelop; is installed it will attempt to find all <filename>.devhelp</filename> files in some standard places in the system, &eg; in the subdirectories of <filename class="directory">/opt/gnome/share/</filename>. Initially these files will not be marked for display.  If you want to see another documentation, mark the <guilabel>TOC</guilabel> check box in the <link linkend="setup-docu-columns">setup table</link>.
 
1738
</para>
 
1739
 
 
1740
<para>
 
1741
You may add new entries using the <link linkend="setup-docu-buttons">buttons</link> to the right of the list field. &kdevelop; will filter <filename>*.toc</filename> files in the directory dialog associated to the <guibutton>Add</guibutton> and <guibutton>Edit</guibutton> buttons.
 
1742
</para>
 
1743
 
 
1744
</sect3> <!-- setup-docu-general-devhelp -->
 
1745
 
 
1746
<sect3 id="setup-docu-general-custom">
 
1747
<title>Setting Up Custom Documentation Collections</title>
 
1748
 
 
1749
<para>
 
1750
This is for your own purpose. You may add almost any documentation files here, provided they can be displayed by the &konqueror; plugins.
 
1751
</para>
 
1752
 
 
1753
<screenshot>
 
1754
  <mediaobject>
 
1755
    <imageobject>
 
1756
      <imagedata fileref="configure-docu-custom.png" format="PNG"/>
 
1757
    </imageobject>
 
1758
    <caption><para>
 
1759
    Providing custom documentation
 
1760
    </para></caption>
 
1761
  </mediaobject>
 
1762
</screenshot>
 
1763
 
 
1764
<para>
 
1765
Usually this collection will be empty at first &kdevelop; startup. We have filled in a deliberate item to show the entry structure.
 
1766
</para>
 
1767
<para>
 
1768
Handling is straightforward here. Use the <link linkend="setup-docu-buttons">buttons</link> to the right of the list field to add, edit or remove the document items. &kdevelop; will not filter anything in the directory dialog associated to the <guibutton>Add</guibutton> and <guibutton>Edit</guibutton> buttons.
 
1769
</para>
 
1770
 
 
1771
<para>
 
1772
You will have to explicitly select the items for display in the &kdevelop; documentation facility. Mark the <guilabel>TOC</guilabel> check box of the entry in the <link linkend="setup-docu-columns">setup table</link>.
 
1773
</para>
 
1774
 
 
1775
<note><para>
 
1776
Custom documentation cannot be indexed or searched. Thus the <guilabel>Index</guilabel> and <guilabel>Search</guilabel> check boxes have no effect here as shown above.
 
1777
</para></note>
 
1778
 
 
1779
</sect3> <!--- setup-docu-general-custom -->
 
1780
 
 
1781
</sect2> <!-- setup-docu-general -->
 
1782
 
 
1783
<sect2 id="setup-docu-textsearch">
 
1784
<title>Setting Up Text Search Indexes</title>
 
1785
 
 
1786
<para>
 
1787
(... to be written ...)
 
1788
</para>
 
1789
 
 
1790
<screenshot>
 
1791
  <mediaobject>
 
1792
    <imageobject>
 
1793
      <imagedata fileref="configure-doctree-textsearch.png" format="PNG"/>
 
1794
    </imageobject>
 
1795
    <caption><para>
 
1796
    Setting up text search indexes
 
1797
    </para></caption>
 
1798
  </mediaobject>
 
1799
</screenshot>
 
1800
 
 
1801
</sect2> <!-- setup-docu-textsearch -->
 
1802
 
 
1803
<sect2 id="setup-docu-other">
 
1804
<title>Other Documentation Configuration Settings</title>
 
1805
 
 
1806
<para>
 
1807
(... to be written ...)
 
1808
</para>
 
1809
 
 
1810
</sect2> <!-- setup-docu-other -->
 
1811
 
 
1812
</sect1> <!-- setup-docu -->
 
1813
 
 
1814
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
 
1815
 
 
1816
<sect1 id="setup-advanced">
 
1817
<title>Advanced Configuration</title>
 
1818
 
 
1819
<para>
 
1820
(... to be written ...)
 
1821
</para>
 
1822
 
 
1823
<sect2 id="setup-plugins">
 
1824
<title>Plugin Tools</title>
 
1825
 
 
1826
<para>
 
1827
(... to be written ...)
 
1828
</para>
 
1829
</sect2> <!-- setup-plugins -->
 
1830
 
 
1831
<sect2 id="setup-abbrev">
 
1832
<title>Abbreviations for the Word Completion</title>
 
1833
 
 
1834
<para>
 
1835
(... to be written ...)
 
1836
</para>
 
1837
</sect2> <!-- setup-abbrev -->
 
1838
 
 
1839
<sect2 id="setup-menu-standard">
 
1840
<title>Adding &kde; Standard Applications to the Tools Menu</title>
 
1841
 
 
1842
<para>
 
1843
(... to be written ...)
 
1844
</para>
 
1845
</sect2> <!-- setup-menu-standard -->
 
1846
 
 
1847
 
 
1848
<sect2 id="setup-menu-external">
 
1849
<title>Adding External Applications to Menus</title>
 
1850
 
 
1851
<para>
 
1852
(... to be written ...)
 
1853
</para>
 
1854
 
 
1855
<sect3 id="setup-menu-external-tools">
 
1856
<title>Adding to the Tools Menu</title>
 
1857
 
 
1858
<para>
 
1859
(... to be written ...)
 
1860
</para>
 
1861
</sect3> <!-- setup-menu-external-tools -->
 
1862
 
 
1863
<sect3 id="setup-menu-external-filecontext">
 
1864
<title>Adding to the File Context Menu</title>
 
1865
 
 
1866
<para>
 
1867
(... to be written ...)
 
1868
</para>
 
1869
</sect3> <!-- setup-menu-external-filecontext -->
 
1870
 
 
1871
<sect3 id="setup-menu-external-dircontext">
 
1872
<title>Adding to the Directory Context Menu</title>
 
1873
 
 
1874
<para>
 
1875
(... to be written ...)
 
1876
</para>
 
1877
</sect3> <!-- setup-menu-external-dircontext -->
 
1878
 
 
1879
</sect2> <!-- setup-menu-external -->
 
1880
 
 
1881
</sect1> <!-- setup-advanced -->
 
1882
 
 
1883
</chapter> <!-- setup -->