summaryrefslogtreecommitdiffstats
path: root/doc/kdevelop/setup.docbook
blob: e5449a993cdb68daebd0e17ada462f1359e06515 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
<chapter id="setup">

<chapterinfo>
  <authorgroup>
    <author><firstname>Bernd</firstname><surname>Pol</surname></author>
    <!-- ROLES_OF_TRANSLATORS -->
  </authorgroup>
</chapterinfo>

<title>Configuring &kdevelop;</title>

<para>
&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.
</para>

<screenshot>
  <mediaobject>
    <imageobject>
      <imagedata fileref="configure-select.png" format="PNG"/>
    </imageobject>
<textobject>
<phrase>Select a configuration item</phrase>
</textobject>
    <caption><para>
    Select a configuration item
    </para></caption>
  </mediaobject>
</screenshot>

<para>
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.
</para>
<para>
If you want directly look up a certain configuration item use one of the following links.
</para>

<simplelist>
  <member><link linkend="setup-main">General</link></member>
  <member><link linkend="setup-ui">User Interface</link></member>
  <member><link linkend="setup-templates">File Templates</link></member>
<member><link linkend="setup-editor">Editor</link></member>
 <member><link linkend="setup-abbrev">Abbreviations</link></member>
 <member><link linkend="setup-scripting">Scripting</link></member>
  <member><link linkend="setup-menu-standard">Tools Menu</link></member>
  <member><link linkend="setup-menu-external">External Tools</link></member>
  <member><link linkend="setup-docu">Documentation</link></member>
  <member><link linkend="setup-snippets">Code Snippets</link></member>
  <member><link linkend="setup-file-list">File List</link></member>
  <member><link linkend="setup-file-selector">File Selector</link></member>
  <member><link linkend="setup-cpp-generator">C++ Class generator</link></member>
  <member><link linkend="setup-format">Formatting</link></member>
  <member><link linkend="setup-cpp-parsing">C++ Parsing</link></member>
</simplelist>

<sect1 id="setup-general">
<title>General Configuration</title>

<para>
General configuration concerns the more common tasks of tailoring &kdevelop; as there are:
</para>
<itemizedlist>
  <listitem><para>
  <link linkend="setup-main">General Setup</link>
  </para></listitem>
  <listitem><para>
  <link linkend="setup-ui">Selecting the User Interface</link>
  </para></listitem>
  <listitem>
    <itemizedlist>
<title>Source Edit Tasks</title>
      <listitem><para>
      <link linkend="setup-editor">Selecting an Editor</link>
      </para></listitem>
      <listitem><para>
      <link linkend="setup-format">Selecting a Source Format Style</link>
      </para></listitem>
      <listitem><para>
      <link linkend="setup-snippets">Setting Up the Code Snippets Tool</link>
      </para></listitem>
    </itemizedlist>
  </listitem>
  <listitem><para>
  <link linkend="setup-file-selector">Configuring the File Selector</link>
  </para></listitem>
</itemizedlist>

<sect2 id="setup-main">
<title>General Setup</title>

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

<variablelist>
<varlistentry>
<term>General project options such as</term>
<listitem>
    <itemizedlist>
      <listitem><para>
      defining a <link linkend="setup-main-projects">default parent directory</link> &kdevelop; shall use for new projects.
      </para></listitem>
       <listitem><para>
      deciding whether you want &kdevelop; to <link linkend="setup-main-preload">automatically load</link> the project you last worked on.
      </para></listitem>
   </itemizedlist>
  </listitem>
</varlistentry>

<varlistentry>
<term>Selecting a font for the most commonly used output view windows,
namely:</term>
<listitem>

<itemizedlist>
<listitem>
<para>the <link linkend="setup-main-messages-font">Messages Output
View</link> &kdevelop; uses to communicate &eg; compilation progresses,
and</para>
</listitem>
<listitem>
<para>the <!--<link linkend="setup-main-applications-font">-->Application Output
View<!--</link>--> which will show error and state information concerning a running
application.</para>
</listitem>
</itemizedlist>

</listitem>
</varlistentry>

<varlistentry>
<term>Some common behaviour concerning the displayed lines in the
<guilabel>Messages Output View</guilabel> window, namely:</term>
<listitem>
    <itemizedlist>
<listitem>
<para>whether long lines will <link linkend="setup-main-wrap">wrap
      around</link>, and </para>
</listitem>
<listitem>
<para>if <link linkend="setup-main-navigation">directory entry and exit
messages</link> issued by <command>make</command> will be shown.</para>
</listitem>
</itemizedlist>

<para>The <link linkend="setup-main-compile">level of detail</link> of
  messages concerning the compilation process shown in the
  <guilabel>Messages Output View</guilabel> window.</para>
</listitem>
</varlistentry>
</variablelist>

<screenshot>
  <mediaobject>
    <imageobject>
      <imagedata fileref="configure-general.png" format="PNG"/>
    </imageobject>
    <caption><para>
    The general configuration dialog
    </para></caption>
  </mediaobject>
</screenshot>

<variablelist>
<varlistentry>
<term id="setup-main-preload"><guilabel>Load last project on
startup</guilabel></term>
<listitem>
<para>
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.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term id="setup-main-projects">
<guilabel>Default projects directory:</guilabel></term>
<listitem>
<para>
By default, &kdevelop; uses a common parent directory for all new
projects. Enter the absolute path of this common directory in the box or
select it from your directory structure. &kdevelop; will place the any new
project here as a subdirectory.</para>
<note><para>
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>.
</para></note>
</listitem>
</varlistentry>

<varlistentry>
<term id="setup-main-messages-font"><guilabel>Window font:</guilabel></term>
<listitem>
<para>
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 informations the applications usually sends to the console when run stand-alone. So you do not need to leave the IDE when testing the application you currently work on.
</para>
<para>
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.
</para>
<note><para>
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 explicitely reselect the <guilabel>Messages Output View</guilabel> window font.
</para></note>
</listitem>
</varlistentry>

<varlistentry>
<term id="setup-main-compile"><guilabel>Compiler Output</guilabel></term>
<listitem>
<para>
&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 dropdown box in this field.
</para>
<variablelist>
<varlistentry>
<term><guilabel>Very Short</guilabel></term>
<listitem><para>
Displays only warnings, errors, and the filenames which are compiled.
</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Short</guilabel></term>
<listitem><para>
Suppresses all compiler flags and formats the output to be more readable.
</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Full</guilabel></term>
<listitem><para>
Displays all output messages unmodified.
</para></listitem>
</varlistentry>
</variablelist>

<tip><para>
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.
</para></tip>
</listitem>
</varlistentry>

<varlistentry>
<term id="setup-main-wrap"><guilabel>Line wrapping</guilabel></term>
<listitem>
<para>
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.
</para>
<tip><para>
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.
</para></tip>
</listitem>
</varlistentry>

<varlistentry>
<term id="setup-main-navigation"><guilabel>Directory navigation
messages</guilabel></term>
<listitem>
<para>
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.
</para>
<note><para>
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.
</para></note>
</listitem>
</varlistentry>

<varlistentry>
<term id="ui-designer-integration"><guilabel>UI Designer  Integration</guilabel></term>
<listitem>
<para>
This let you choose the way you want <filename>.ui</filename> files to be displayed in &kdevelop;. &kdevelop; comes with its own UI designer called KDeveDesigner that can either be embedded or be run as a separate program. Qt Designer can also be used to edit <filename>.ui</filename> files.
</para>
<itemizedlist>
  <listitem><para>
  Use &kdevelop;'s embedded designer
  </para><para>This uses &kdevelop; own designer embedded within &kdevelop;</para></listitem>
  <listitem><para>
  Run &kdevelop;'s designer as a separate application
  </para><para>The KDevDesigner application will be run separately in its own window.</para>
<screenshot>
  <mediaobject>
    <imageobject>
      <imagedata fileref="kdevdesigner.png" format="PNG"/>
    </imageobject>
    <caption><para>
   KDevDesigner in its own window
    </para></caption>
  </mediaobject>
</screenshot>
</listitem>
  <listitem><para>
Run Qt Designer
  </para><para>Qt Designer from your Qt installation will be started externally whenever you click on a <filename>.ui</filename> file in &kdevelop;.</para></listitem>
</itemizedlist>
</listitem>
</varlistentry>

<varlistentry>
<term id="terminal-emulation"><guilabel>Terminal Emulation</guilabel></term>
<listitem>
<para>
You choose here which terminal you want to be integrated within KDevelop.
</para>
<itemizedlist>
  <listitem><para>
  Use &kde; setting
  </para><para>This uses &kde; setting as set in &kcontrol; in <guilabel>&kde; component</guilabel> <guilabel>Component Chooser</guilabel> tab which sets the default terminal emulator used by all &kde; applications that need a terminal.</para></listitem>
  <listitem><para>
  Other
  </para><para>Choose some other terminal different from the default one.</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>

</variablelist>

</sect2> <!-- setup-main -->

<sect2 id="setup-ui">
<title>Selecting the User Interface</title>

<indexterm zone="setup-ui">
  <primary>user interface</primary>
  <secondary>switch modes</secondary></indexterm>
<indexterm zone="setup-ui">
  <primary>switch UI modes</primary></indexterm>

<para>
As already said in the <link linkend="uimodes-survey">Available User Interface Modes</link> chapter there are five different ways the &kdevelop; work area may be set up, namely:
</para>
<itemizedlist>
  <listitem><para>
  <link linkend="ideal-desc">Simplified IDEAl window mode</link>
  </para><para>This is a simplified version of the IDEA user interface. It is designed to be simple and clean. It also does not uses docked toolviews.</para></listitem>
  <listitem><para>
  <link linkend="ideal-desc">IDEAl window mode</link>
  </para><para>This is a clone of the IDEA user interface, similar to the Tabbed pages mode and is default.</para></listitem>
  <listitem><para>
  <link linkend="mdi-desc">Childframe window mode</link>
  </para><para>All tool views are initially docked to the mainframe.
Editor and browser views will live like toplevel windows within a view area of the mainframe.
A typical example of this user interface mode is MS Visual Studio 6.0.</para></listitem>
  <listitem><para>
  <link linkend="tabbed-desc">Tabbed pages mode</link>
  </para><para>All tool views are initially docked to the mainframe.
Editor and browser views will be stacked in a tab window.
A typical example of this user interface mode is KDEStudio, our friend C++-IDE in the world of KDE.</para></listitem>
  <listitem><para>
  <link linkend="toplevel-desc">Toplevel window mode</link>
  </para><para>All editor, browser and tool views will be toplevel windows (directly on desktop).
The main widget contains the menu, toolbars and statusbar only.
A typical example of this user interface mode is Borland Delphi 6.0.</para></listitem>
</itemizedlist>

<para>
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>

<screenshot>
  <mediaobject>
    <imageobject>
      <imagedata fileref="select-user-interface-0.png" format="PNG"/>
    </imageobject>
<textobject><phrase>Select a user interface mode</phrase></textobject>
    <caption><para>
    Select a user interface mode
    </para></caption>
  </mediaobject>
</screenshot>

<para>
Select the radio button of the user interface mode you want to switch to, then click <guibutton>OK</guibutton>.
</para>

<note><para>
Do not forget to restart &kdevelop; in order to let any of these selections take effect.
</para></note>

<para>
When you selected either the <guilabel>Simplified IDEAl window mode</guilabel> or 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.
</para>

<para>
In <guilabel>Simplified IDEAl window mode</guilabel> and 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.
</para>

<variablelist>
<varlistentry>
<term id="setup-ui-tabs">Configuring the Documents Tab Bar Display</term>
<listitem>
<para>
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.
</para>

<variablelist>
<varlistentry>
  <term><guilabel>Always</guilabel></term>
  <listitem><para>
  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.
  </para></listitem>
</varlistentry>
<varlistentry>
  <term><guilabel>When more than one</guilabel></term>
  <listitem><para>
  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.
  </para></listitem>
</varlistentry>
<varlistentry>
  <term><guilabel>Never</guilabel></term>
  <listitem><para>
  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.
  </para></listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>

<varlistentry>
<term id="setup-ui-hover">Setting Up to Close a Document by a Click On Its
Tab</term>
<listitem>
<para>
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> coniguration section for this.
</para>

<variablelist>
<varlistentry>
  <term><guilabel>No</guilabel></term>
  <listitem><para>
  This is standard behaviour. No extra functionality is added to the tabs. They may be used only to select document windows on &LMB; clicks.
  </para></listitem>
</varlistentry>
<varlistentry>
  <term><guilabel>Yes</guilabel></term>
  <listitem><para>
  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.
  </para></listitem>
</varlistentry>
<varlistentry>
  <term><guilabel>Yes, Delayed</guilabel></term>
  <listitem><para>
  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.
  </para></listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>

<varlistentry>
<term id="setup-ui-toolview">Configuring the Toolview Tab Layout</term>
<listitem>
<para>
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.
</para>

<variablelist>
<varlistentry>
  <term><guilabel>Icons</guilabel></term>
  <listitem>
  <para>
  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.
  </para>
  <para>
  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.
  </para>
  </listitem>
</varlistentry>
<varlistentry>
  <term><guilabel>Text</guilabel></term>
  <listitem><para>
  This is the default toolview tab display mode. Each tab displays the name of its associated toolwiew.
  </para></listitem>
</varlistentry>
<varlistentry>
  <term><guilabel>Text and Icons</guilabel></term>
  <listitem><para>
  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.
  </para></listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>

<varlistentry>
<term>Folded Toolview Tabs</term>
<listitem>
<para>
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:
</para>

<screenshot>
  <mediaobject id="folded-toolview-tabs">
    <imageobject>
      <imagedata fileref="folded-tabs.png" format="PNG"/>
    </imageobject>
<textobject><phrase>Toolview tabs fold to not be hidden behind another view window</phrase></textobject>
    <caption><para>
    Toolview tabs fold to not be hidden behind another view window
    </para></caption>
  </mediaobject>
</screenshot>

<note><para>
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.
</para></note>
</listitem>
</varlistentry>
</variablelist>

</sect2> <!-- setup-ui -->

<sect2 id="setup-templates">
<title>File Templates</title>
<!--TODO fill--><para></para>

<screenshot>
  <mediaobject>
    <imageobject>
      <imagedata fileref="configure-file-templates.png" format="PNG"/>
    </imageobject>
<textobject><phrase>Configure File Templates</phrase></textobject>
    <caption><para>
    Configure File Templates
    </para></caption>
  </mediaobject>
</screenshot>
</sect2> <!-- setup-templates -->

<sect2 id="setup-editor">
<title>Selecting an Editor</title>

<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.
</para>

<screenshot>
  <mediaobject>
    <imageobject>
      <imagedata fileref="configure-editor.png" format="PNG"/>
    </imageobject>
<textobject><phrase>Select an editor</phrase></textobject>
    <caption><para>
    Select an editor
    </para></caption>
  </mediaobject>
</screenshot>

<para>
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 two possibilities:
</para>

<variablelist>
  <varlistentry>
  <term><guilabel>Embedded Advanced Text Editor</guilabel></term>
  <listitem><para>
  This is the &kde; standard <application>Kate</application> editor part.
  </para></listitem>
  </varlistentry>

  <varlistentry>
  <term><guilabel>Qt Designer Based Text Editor</guilabel></term>
  <listitem><para>
  This is the editor &Qt; provides in its <application>Designer</application> component.
  </para></listitem>
  </varlistentry>
</variablelist>

<para>
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.
</para>

<note><para>
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.
</para></note>

<important id="setup-editor-kparts"><para>
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.
</para></important>

<para>What to do if the file has been changed externally:</para>
<variablelist>
  <varlistentry>
  <term><guilabel>Do nothing</guilabel></term>
  <listitem><para>
 The file will be marked as externally changed and the user will be asked to verify any attempt to overwrite it.
  </para></listitem>
  </varlistentry>
  <varlistentry>
  <term><guilabel>Alert the user</guilabel></term>
  <listitem><para>
  A dialog will alert the user that a file has changed and offer the user to reload the file.
  </para></listitem>
  </varlistentry>
  <varlistentry>
  <term><guilabel>Automatically reload the file if safe, alert the user if not</guilabel></term>
  <listitem><para>
  Any files that are not modified in memory are reloaded and an alert is shown for any conflicts.
  </para></listitem>
  </varlistentry>
</variablelist>
</sect2> <!-- setup-editor -->

<sect2 id="setup-abbrev">
<title>Abbreviations for the Word Completion</title>

<para>
(... to be written ...)
</para>
</sect2> <!-- setup-abbrev -->

<sect2 id="setup-scripting">
<title>Scripting</title>

<para>
(... to be written ...)
</para>
</sect2> <!-- setup-scripting -->

<sect2 id="setup-menu-standard">
<title>Adding &kde; Standard Applications to the Tools Menu</title>

<para>
(... to be written ...)
</para>
</sect2> <!-- setup-menu-standard  Tools Menu-->

<sect2 id="setup-menu-external">
<title>Adding External Applications to Menus</title>

<para>
(... to be written ...)
</para>

<sect3 id="setup-menu-external-tools">
<title>Adding to the Tools Menu</title>

<para>
(... to be written ...)
</para>
</sect3> <!-- setup-menu-external-tools -->

<sect3 id="setup-menu-external-filecontext">
<title>Adding to the File Context Menu</title>

<para>
(... to be written ...)
</para>
</sect3> <!-- setup-menu-external-filecontext -->

<sect3 id="setup-menu-external-dircontext">
<title>Adding to the Directory Context Menu</title>

<para>
(... to be written ...)
</para>
</sect3> <!-- setup-menu-external-dircontext -->

</sect2> <!-- setup-menu-external -->

<sect2 id="setup-format">
<title>Selecting a Source Format Style</title>

<para>
&kdevelop; automatically formats a source text in a predefined style. This style is highly configurable.
</para>

<note><para>
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.
</para></note>

<para>
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>.
</para>

<tip><para>
Any style changes apply to newly entered text only. If you want to change the formatting style of an already existing source text you will have to explicitely use the <menuchoice><guimenu>Edit</guimenu><guimenuitem>Reformat Source</guimenuitem></menuchoice> command.
</para></tip>

<note><para>
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.
</para></note>

<warning><para>
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.
</para></warning>

<sect3 id="setup-format-general">
<title>General Formatting Setup</title>

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

<screenshot>
  <mediaobject>
    <imageobject>
      <imagedata fileref="SF-general.png" format="PNG"/>
    </imageobject>
<textobject><phrase>Source format style general setup</phrase></textobject>
    <caption><para>
    Source format style general setup
    </para></caption>
  </mediaobject>
</screenshot>

<para>
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.
</para>

<note><para>
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.
</para></note>

</sect3> <!-- setup-format-general -->

<sect3 id="setup-format-indent">
<title>Indentation Style Setup</title>

<para>
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.
</para>

<screenshot>
  <mediaobject>
    <imageobject>
      <imagedata fileref="SF-indent.png" format="PNG"/>
    </imageobject>
<textobject><phrase>Source format indentation style setup</phrase></textobject>
    <caption><para>
    Source format indentation style setup
    </para></caption>
  </mediaobject>
</screenshot>

<variablelist>
<varlistentry>
<term>Default Settings</term>
<listitem>
<para>The preset format choices will cause the source text to resemble the
ANSI formatting style:</para>

<screen>
namespace foospace
{
  int Foo()
  {
    if (isBar)
    {
      bar();
      return 1;
    }
    else
      return 0;
  }
}
</screen>
</listitem>
</varlistentry>

<varlistentry>
<term id="setup-format-indent-filling">Defining Indentation Width and Characters</term>
<listitem>
<para>The radio buttons grouped in the <guilabel>Filling</guilabel> group
define how indents in the source text will be drawn.</para>

<variablelist>
  <varlistentry>
    <term><guilabel>Use tabs</guilabel></term>
    <listitem>
    <para>
    This will cause the editor to insert a tab character for each
indentation level. The tab width is predefined in the editor settings (8 or
4 character columns usually). Use <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure Editor...</guimenuitem></menuchoice> to redefine it.
    </para>
    <note><para>
    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.
    </para></note>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><guilabel>Use spaces</guilabel></term>
    <listitem><para>
    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.
    </para></listitem>
  </varlistentry>
</variablelist>
</listitem>
</varlistentry>

<varlistentry>
<term>Indented Entities</term>
<listitem>
<para>This defines which of the (C/C++) entities will be formatted with an
extra indent beyond the current indentation level.</para>

<para>By default only <guilabel>namespaces</guilabel> and
<guilabel>labels</guilabel> will be extra indented. You may want to
experiment with various settings to tailor those extra indents to your
liking.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>Continuation</term>
<listitem>
<para>
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.
</para>

<note><para>
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.
</para></note>

<variablelist>
  <varlistentry>
    <term><guilabel>Maximum in statement</guilabel></term>
    <listitem>
    <para>
    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.
    </para>
    <para>
    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.
    </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><guilabel>Minimum in conditional</guilabel></term>
    <listitem>
    <para>
    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.
    </para>
    <para>
    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.
    </para>
    </listitem>
  </varlistentry>
</variablelist>
</listitem>
</varlistentry>
</variablelist>

</sect3> <!-- setup-format-indent -->

<sect3 id="setup-format-other">
<title>Other Formatting Setup</title>

<screenshot>
  <mediaobject>
    <imageobject>
      <imagedata fileref="SF-other.png" format="PNG"/>
    </imageobject>
<textobject><phrase>Other source format style settings</phrase></textobject>
    <caption><para>
    Other source format style settings
    </para></caption>
  </mediaobject>
</screenshot>

<variablelist>
<varlistentry>
<term>Controlling the position of braces</term>
<listitem>
<para>The radio buttons the (somewhat misnamed)
<guilabel>Brackets</guilabel> group control the position of block delimiting
braces in a (C/C++) source text. There are three possibilities from which
you can select.</para>

<variablelist>
  <varlistentry>
    <term><guilabel>Break</guilabel></term>
    <listitem>
    <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>

<screen>
namespace foospace
{
  int Foo()
  {
    if (isBar)
    {
      bar();
      return 1;
    }
    else
      return 0;
  }
}
</screen>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><guilabel>Attach</guilabel></term>
    <listitem>
    <para>
    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.
    </para>
<screen>
namespace foospace {
  int Foo() {
    if (isBar) {
      bar();
      return 1;
    } else
      return 0;
  }
}
</screen>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><guilabel>Linux Style</guilabel></term>
    <listitem>
    <para>
    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.
    </para>
<screen>
namespace foospace
{
  int Foo()
  {
    if (isBar) {
      bar();
      return 1;
    } else
      return 0;
  }
}
</screen>
    </listitem>
  </varlistentry>
</variablelist>
</listitem>
</varlistentry>

<varlistentry>
<term>Controlling Extra Spaces</term>
<listitem>
<para>
By default &kdevelop; does minimize the use of spaces in source texts.
</para>


<screen>
if (isBar(fooArg)==barValue)
</screen>

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

<variablelist>
  <varlistentry>
    <term><guilabel>Add spaces around parentheses</guilabel></term>
    <listitem>
    <para>In fact what is meant is to add spaces around the text put in parentheses. This enhances the readabilitiy of function arguments and conditionals.</para>
<screen>
if ( isBar( fooArg )==barValue )
</screen>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><guilabel>Add spaces around operators</guilabel></term>
    <listitem>
    <para>This will put spaces around assignment and comparison operators to enhance the readability.</para>
<screen>
if (isBar(fooArg) == barValue)
</screen>
    </listitem>
  </varlistentry>
</variablelist>
</listitem>
</varlistentry>

<varlistentry>
<term>Controlling the formatting of one-line constructs</term>
<listitem>
<para>There are a few cases where you don't want the source formatter to
split a long line apart. For C/C++ code this can be controlled here.</para>

<variablelist>
  <varlistentry>
    <term><guilabel>Keep one-line statements</guilabel></term>
    <listitem><para>
    This keeps single line statements together in some situations even if they exceed a fixed maximum line length.
    </para></listitem>
  </varlistentry>
  <varlistentry>
    <term><guilabel>Keep one-line blocks</guilabel></term>
    <listitem><para>
    This keeps single line blocks together in some situations even if they exceed a fixed maximum line length.
    </para></listitem>
  </varlistentry>
</variablelist>
</listitem>
</varlistentry>
</variablelist>


</sect3> <!-- setup-format-other -->

</sect2> <!-- setup-format -->

<sect2 id="setup-snippets">
<title>Setting Up the Code Snippets Tool</title>

<para>
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.
</para>

<screenshot>
  <mediaobject>
    <imageobject>
      <imagedata fileref="configure-snippets.png" format="PNG"/>
    </imageobject>
<textobject><phrase>Configuring the code snippets tool</phrase></textobject>
    <caption><para>
    Configuring the Code Snippets tool
    </para></caption>
  </mediaobject>
</screenshot>

<variablelist>
<varlistentry>
<term>Activate Snippet Preview</term>
<listitem>
<para>Mark the <guilabel>Show snippet's text in tooltip</guilabel> checkbox
if you want to view the stored text in a tooltip window whenever you keep
the mouse cursor over the title of that snippet.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>Working with Snippet Variables</term>
<listitem>
<para>The <guilabel>Code Snippets</guilabel> tool allows for a variable text
in predefined places any time you insert a snippet into a file. To
accomplish this  <guilabel>Code Snippets</guilabel> provides its own
variables' mechanism. You can set up it's behaviour in the
<guilabel>Variables</guilabel> group.</para>

<variablelist>
  <varlistentry>
    <term><guilabel>Delimiter</guilabel></term>
    <listitem><para>
    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.
    </para></listitem>
  </varlistentry>
  <varlistentry>
    <term><guilabel>Input method for variables</guilabel></term>
    <listitem><itemizedlist>
      <listitem><para>
      <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.
      </para></listitem>
      <listitem><para>
      <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
      </para></listitem>
    </itemizedlist></listitem>
  </varlistentry>
</variablelist>
</listitem>
</varlistentry>
</variablelist>

</sect2> <!-- setup-snippets -->

<sect2 id="setup-file-list">
<title>File List</title>

<para>
(... to be written ...)
</para>

</sect2> <!-- setup-file-list-->

<sect2 id="setup-file-selector">
<title>Configuring the File Selector</title>

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

<screenshot id="setup-fileselector-image">
  <mediaobject>
    <imageobject>
      <imagedata fileref="file-selector.png" format="PNG"/>
    </imageobject>
<textobject><phrase>The file selector in IDEAl mode</phrase></textobject>
    <caption><para>
    The file selector (IDEAl mode)
    </para></caption>
  </mediaobject>
</screenshot>

<para>The behaviour of the <guilabel>File Selector</guilabel> can be highly
configured. 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>File Selector</guilabel> in the left hand
tree. This will show the following dialog in the right hand side.</para>


<screenshot>
  <mediaobject>
    <imageobject>
      <imagedata fileref="configure-file-selector.png" format="PNG"/>
    </imageobject>
<textobject><phrase>Configuring the file selector</phrase></textobject>
    <caption><para>
    Configuring the file selector
    </para></caption>
  </mediaobject>
</screenshot>

<variablelist>
<varlistentry>
<term>Configuring the Toolbar</term>
<listitem>
<para>There is a toolbar on top of the <guilabel>File Selector</guilabel>
which can be configured as usual in the <guilabel>Toolbar</guilabel>
group.</para>

<procedure id="setup-fileselector-add-action">
  <title>Add an Action to the Toolbar</title>
  <step>
    <para>
    Select an item in the right hand <guilabel>Selected actions</guilabel> list after which the new action should be inserted.
    </para>
  </step>
  <step>
    <para>
    Select the action to be inserted in the left hand <guilabel>Available actions</guilabel> list.
    </para>
  </step>
  <step>
    <para>
    Click the right (upper) arrow between both lists.
    </para>
    <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.
    </para>
  </step>
</procedure>

<procedure>
  <title>Remove an Action from the Toolbar</title>
  <step>
    <para>
    Select the item to be removed in the right hand <guilabel>Selected actions</guilabel> list.
    </para>
  </step>
  <step>
    <para>
    Click the left (lower) arrow between both lists.
    </para>
    <para>The selected item will be removed from the <guilabel>Selected actions</guilabel> list and put back into the <guilabel>Available actions</guilabel> list.
    </para>
  </step>
</procedure>

<procedure>
  <title>Reorder the Actions on the Toolbar</title>
  <step>
    <para>
    Select the action to be moved in the right hand <guilabel>Selected actions</guilabel> list.
    </para>
  </step>
  <step>
    <para>
    Click the up or down arrow to the right of this list.
    </para>
    <para>The selected item will be moved up or down the <guilabel>Selected actions</guilabel> list.
    </para>
  </step>
</procedure>
</listitem>
</varlistentry>

<varlistentry>
<term id="setup-fileselector-autosync">Defining When the Contents Should
Change</term>
<listitem>
<para>
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 explicitely want to refresh its contents.
</para>

<note><para>
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.
</para></note>

<para>
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.
</para>

<variablelist>
  <varlistentry>
    <term><guilabel>When a document becomes active</guilabel></term>
    <listitem><para>
    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.
    </para></listitem>
  </varlistentry>
  <varlistentry>
    <term><guilabel>When a document is opened</guilabel></term>
    <listitem><para>
    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.
    </para></listitem>
  </varlistentry>
  <varlistentry>
    <term><guilabel>When the file selector becomes visible</guilabel></term>
    <listitem><para>
    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.
    </para></listitem>
  </varlistentry>
</variablelist>

<para>
You may freely combine these settings to tailor the actualization behaviour of the <guilabel>File Selector</guilabel> to your liking.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>Controlling the History in the Comboboxes</term>
<listitem>
<para>There are two comboboxes on top and bottom of the <guilabel>File
Selector</guilabel> contents window which control the directory to be
displayed (top combobox) and the filters to be applied to the file display
(bottom combobox). A history of the most recent settings is kept in the
selection field of each combobox. You can configure the number of history
entries as follows.</para>

<variablelist>
  <varlistentry>
    <term><guilabel>Remember locations</guilabel></term>
    <listitem><para>
    Enter here the maximum number of directory selections the upper combobox shall remember.
    </para></listitem>
  </varlistentry>
  <varlistentry>
    <term><guilabel>Remember filters</guilabel></term>
    <listitem><para>
    Enter here the maximum number of filter definitions the lower combobox shall remember.
    </para></listitem>
  </varlistentry>

<varlistentry>
<term>Controlling What Should be Remembered Between Sessions</term>
<listitem>
<para>
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.
</para>

<note><para>
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.
</para></note>
</listitem>
</varlistentry>

  <varlistentry>
    <term><guilabel>Restore location</guilabel></term>
    <listitem>
    <para>
    Remove the checkbox mark here if you don't want the displayed location be remembered between sessions.
    </para>
    <note><para>
    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.
    </para></note>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><guilabel>Restore filters</guilabel></term>
    <listitem>
    <para>
    Remove the checkbox mark here if you don't want the filters applied to the display be remembered between sessions.
    </para>
    </listitem>
  </varlistentry>
</variablelist>
</listitem>
</varlistentry>
</variablelist>

</sect2> <!-- setup-file-selector -->

<sect2 id="setup-cpp-generator">
<title>C++ Class Generator</title>

<para>
(... to be written ...)
</para>

</sect2> <!-- setup-c++-generator-->

<sect2 id="setup-formatting">
<title>Formatting</title>

<para>
(... to be written ...)
</para>

</sect2> <!-- setup-formatting-->

<sect2 id="setup-cpp-parsing">
<title>C++ Parsing</title>

<para>
(... to be written ...)
</para>

</sect2> <!-- setup-c++-parsing-->

</sect1> <!-- setup-general -->

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

<sect1 id="setup-docu">
<title>Configuring the Documentation</title>

<para>
&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.
</para>

<screenshot>
  <mediaobject>
    <imageobject>
      <imagedata fileref="documents-contents.png" format="PNG"/>
    </imageobject>
<textobject><phrase>The &kdevelop; documentation window in IDEAl mode</phrase></textobject>
    <caption><para>
    The &kdevelop; documentation window (IDEAl mode)
    </para></caption>
  </mediaobject>
</screenshot>

<note><para>
&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.
</para></note>

<para>
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.
</para>

<para>
The thus displayed <link linkend="configure-docu-general">configuration page</link> shows three tabbed configuration dialog pages, namely:
</para>

<simplelist>
  <member><link linkend="setup-docu-general">Documentation Collections</link></member>
  <member><link linkend="setup-docu-textsearch">Full Text Search</link></member>
  <member><link linkend="setup-docu-other">Other</link></member>
</simplelist>

<sect2 id="setup-docu-general">
<title>Setting Up Documentation Collections</title>

<para>
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.
</para>
<para>
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:
</para>
<simplelist>
  <member><link linkend="setup-docu-general-qt">&Qt; Documentation Collection</link></member>
  <member><link linkend="setup-docu-general-chm">CHM Documentation Collection</link></member>
  <member><link linkend="setup-docu-general-dox">Doxygen Documentation Collection</link></member>
  <member><link linkend="setup-docu-general-toc">&kdevelop; TOC Documentation Collection</link></member>
  <member><link linkend="setup-docu-general-devhelp">Devhelp Documentation Collection</link></member>
  <member><link linkend="setup-docu-general-custom">Custom Documentation Collection</link></member>
</simplelist>

<para id="configure-docu-general">
<screenshot>
  <mediaobject>
    <imageobject>
      <imagedata fileref="configure-docu-general.png" format="PNG"/>
    </imageobject>
<textobject><phrase>Setting up documentation collections</phrase></textobject>
    <caption><para>
    Setting up documentation collections
    </para></caption>
  </mediaobject>
</screenshot>
</para>

<sect3 id="setup-docu-general-common">
<title>Common Documentation Setup Structure</title>

<para>
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.
</para>

<variablelist>
<varlistentry>
<term id="setup-docu-buttons">Buttons to Maintain Documentation List Contents</term>
<listitem>
<para>
There are three buttons available to maintain the contents of the documentation setup pages:
</para>

<variablelist>
  <varlistentry>
    <term><guibutton>Add</guibutton></term>
    <listitem>
      <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>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><guibutton>Edit</guibutton></term>
    <listitem>
      <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>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><guibutton>Remove</guibutton></term>
    <listitem>
      <para>Removes the selected documentation entry from the list.</para>
      <note><para>
      The entry will be removed from the list only. Actual documentation sources remain untouched. You will have to remove them explicitely by other means.
      </para></note>
    </listitem>
  </varlistentry>
</variablelist>

<screenshot>
  <mediaobject>
    <imageobject>
      <imagedata fileref="configure-docu-edit.png" format="PNG"/>
    </imageobject>
    <caption><para>
    Add or change a documentation item
    </para></caption>
  </mediaobject>
</screenshot>

<para>
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.
</para>
<para>
The <guilabel>Title</guilabel> field may not be accessible, depending on the documentation type to be maintained.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term id="setup-docu-columns">Documentation List Structure</term>
<listitem>
<para>
Every documentation setup page shows the listed documentation items in a table with four columns:
</para>

<variablelist>
  <varlistentry>
    <term><guilabel>TOC</guilabel></term>
    <listitem>
      <para>
      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.
      </para>
      <note><para>
      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.
      </para></note>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><guilabel>Index</guilabel></term>
    <listitem>
      <para>
      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.
      </para>
      <note>
        <para>
        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.
        </para>
        <para>
        All subsequent indexed searches will however use this chache and thus work significally faster.
        </para>
      </note>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><guilabel>Search</guilabel></term>
    <listitem>
      <para>
      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.
      </para>
      <note>
        <para>
        &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.
        </para>
        <para>
        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.
        </para>
      </note>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><guilabel>Title</guilabel></term>
    <listitem><para>
    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.
    </para></listitem>
  </varlistentry>
</variablelist>

<note><para>
Former &kdevelop; versions allowed to select the documentation items to be displayed on a per-project basis. This is not available any more.
</para></note>
</listitem>
</varlistentry>
</variablelist>

</sect3> <!-- setup-docu-general-common -->

<sect3 id="setup-docu-general-qt">
<title>&Qt; Documentation Collections</title>

<para>
On this configuration page all &Qt; documentation is set up.
</para>

<screenshot>
  <mediaobject>
    <imageobject>
      <imagedata fileref="configure-docu-general.png" format="PNG"/>
    </imageobject>
<textobject><phrase>Setting up the &Qt; documentation collection</phrase></textobject>
    <caption><para>
    Setting up the &Qt; documentation collection
    </para></caption>
  </mediaobject>
</screenshot>

<para>
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.
</para>

<para>
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.
</para>

<note><para>
&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.
</para></note>

<para>
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.
</para>

<para>
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>.
</para>

</sect3> <!-- setup-docu-general-qt -->

<sect3 id="setup-docu-general-chm">
<title>Setting Up the CHM Documentation Collection</title>

<para>
On this configuration page you may collect documentation according to the &Microsoft; CHM help file standard.
</para>

<screenshot>
  <mediaobject>
    <imageobject>
      <imagedata fileref="configure-docu-chm.png" format="PNG"/>
    </imageobject>
<textobject><phrase>Setting up &Microsoft; CHM standard documentation files</phrase></textobject>
    <caption><para>
    Setting up &Microsoft; CHM standard documentation files
    </para></caption>
  </mediaobject>
</screenshot>

<para>
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.
</para>

<para>
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>.
</para>

</sect3> <!-- setup-docu-general-chm -->

<sect3 id="setup-docu-general-dox">
<title>Documentation Generated by Doxygen</title>

<para>
On this configuration page all &API; documentation generated by &doxygen; is set up.
</para>

<screenshot>
  <mediaobject>
    <imageobject>
      <imagedata fileref="configure-docu-dox.png" format="PNG"/>
    </imageobject>
<textobject><phrase>Setting up Doxygen generated &API; documentation</phrase></textobject>
    <caption><para>
    Setting up Doxygen generated &API; documentation
    </para></caption>
  </mediaobject>
</screenshot>

<para>
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.
</para>
<para>
&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 seaching for &doxygen; generated &API; documentation.
</para>
<para>
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.
</para>
<para>
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.
</para>

<note><para>
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.
</para></note>

<para>
&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:
</para>

<itemizedlist>
  <listitem><para>
  Either you provided the <command>configure</command> command with the
  <option>--with-kdelibsdoxy-dir</option> option when you compiled
  &kdevelop; (see the <link linkend="make-api">How to Obtain a &kdevelop; &API; Documentation</link> chapter).
  </para></listitem>
  <listitem><para>
  Or the <command>configure</command> command did automatically find a &doxygen; generated &kde; Libraries &API; in one of several standard locations it knows of.
  </para></listitem>
  <listitem><para>
  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.
  </para></listitem>
</itemizedlist>

<para>
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.
</para>

<para>
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>.
</para>

<note><para>
&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.
</para></note>

<tip>
  <para>
  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:
  </para>
  <screenshot><mediaobject>
      <imageobject>
        <imagedata fileref="configure-adddialog-baselibs.png" format="PNG"/>
      </imageobject>
<textobject><phrase>Adding a &kde; base &API; to the list</phrase></textobject>
      <caption><para>
      Adding a &kde; Base &API; to the list
      </para></caption>
    </mediaobject></screenshot>
  <para>
  (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.)
  </para>
</tip>

<note><para>
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.
</para></note>

</sect3> <!-- setup-docu-general-dox -->

<sect3 id="setup-docu-general-toc">
<title>Handling Structured Documentation (KDevelopTOC Files)</title>

<para>
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.
</para>

<screenshot>
  <mediaobject>
    <imageobject>
      <imagedata fileref="configure-docu-toc.png" format="PNG"/>
    </imageobject>
    <caption><para>
    Providing KDevelopTOC structured documentation access
    </para></caption>
  </mediaobject>
</screenshot>

<para>
&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>.
</para>

<para>
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.)
</para>
<para>
The <guilabel>Search</guilabel> check box in the <link linkend="setup-docu-columns">setup table</link> will alway be disabled.
</para>

<para>
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.
</para>

<note><para>
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.
</para></note>

</sect3> <!-- setup-docu-general-toc -->

<sect3 id="setup-docu-general-toc-files">
<title>&kdevelop; TOC Files</title>

<para>
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.
</para>

<para>
The rationale behind this is not only to locally navigate remote documentation without wasting net access ressources, 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.
</para>

<para>
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.
</para>

<variablelist>
<varlistentry>
<term>Standard Directory of &kdevelop; TOC Files</term>
<listitem>
<para>
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.
</para>
</listitem>
</varlistentry></variablelist>

<!-- FIXME: Lauri Watts (2005-05-03) This could be marked up a whole lot -->
<!-- more clearly with the sgmltags stuff.  Making a note to do that once -->
<!-- this first revision is done. -->

<variablelist id="toc-file-structure">
  <title>Basic Structure of &kdevelop; TOC Files</title>
  <varlistentry>
    <term>header</term>
    <listitem>
      <simplelist>
        <member>
          <computeroutput>&lt;!DOCTYPE kdeveloptoc&gt;</computeroutput>
        </member>
        <member>
          <computeroutput>&lt;kdeveloptoc&gt;</computeroutput>
        </member>
        <member>
          <emphasis>(title)</emphasis>
        </member>
        <member>
          <emphasis>(base address)</emphasis>
        </member>
        <member>
          <emphasis>(content structure)</emphasis>
        </member>
        <member>
          <emphasis>(index structure)</emphasis>
        </member>
        <member>
          <computeroutput>&lt;/kdeveloptoc&gt;</computeroutput>
        </member>
      </simplelist>
      <para>
      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.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>title</term>
    <listitem>
      <simplelist>
        <member>
          <computeroutput>&lt;title&gt;</computeroutput>
          <emphasis>(some title string)</emphasis>
          <computeroutput>&lt;/title&gt;</computeroutput>
        </member>
      </simplelist>
      <para>
      This is the title &kdevelop; will display at the basic levels in the documentation tree.
      </para>
      <note><para>
      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.
      </para></note>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>base address</term>
    <listitem>
      <simplelist>
        <member>
          <computeroutput>&lt;base href="</computeroutput>
          <emphasis>(base document &URL;)</emphasis>
          <computeroutput>"/&gt;</computeroutput>
        </member>
      </simplelist>
      <para>
      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;.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>content structure</term>
    <listitem>
      <simplelist>
        <member>
          <computeroutput>&lt;tocsect1 name="</computeroutput>
          <emphasis>(section title)</emphasis>
          <computeroutput>" url="</computeroutput>
          <emphasis>(section &URL;)</emphasis>
          <computeroutput>"&gt;</computeroutput>
        </member>
        <member>...</member>
        <member>
          <computeroutput>&lt;tocsectn name="</computeroutput>
          <emphasis>(section title)</emphasis>
          <computeroutput>" url="</computeroutput>
          <emphasis>(section &URL;)</emphasis>
          <computeroutput>"/&gt;</computeroutput>
        </member>
        <member>...</member>
        <member>
          <computeroutput>&lt;/tocsect1&gt;</computeroutput>
        </member>
      </simplelist>
      <para>
      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.
      </para>
      <para>
      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.
      </para>
      <para>
      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;.
      </para>
      <para>
      The <computeroutput>&lt;tocsectn/&gt;</computeroutput> entry must have an <computeroutput>url=""</computeroutput> attribute whatsoever.
      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.
      </para>
      <note><para>
      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>.
      </para></note>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>index structure</term>
    <listitem>
      <simplelist>
        <member>
          <computeroutput>&lt;index&gt;</computeroutput>
        </member>
        <member>
          <computeroutput>&lt;entry name="</computeroutput>
          <emphasis>(index entry title)</emphasis>
          <computeroutput>" url="</computeroutput>
          <emphasis>(index section &URL;)</emphasis>
          <computeroutput>"/&gt;</computeroutput>
        </member>
        <member>
          <computeroutput>&lt;/index&gt;</computeroutput>
        </member>
      </simplelist>
      <para>
      Index is a plain list of index entries - pairs of title and &URL;. Index is not mandatory.
      </para>
    </listitem>
  </varlistentry>
</variablelist>
<!-- FIXME: End -->

</sect3> <!-- setup-docu-general-toc-files  -->

<sect3 id="setup-docu-general-devhelp">
<title>DevHelp Documentation</title>

<para>
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.
</para>
<para>
You can control which DevHelp files should be accessible on the <guilabel>DevHelp Documentation Collection</guilabel> configuration page.
</para>

<screenshot>
  <mediaobject>
    <imageobject>
      <imagedata fileref="configure-docu-devhelp.png" format="PNG"/>
    </imageobject>
    <caption><para>
    Providing DevHelp documentation
    </para></caption>
  </mediaobject>
</screenshot>

<para>
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.
</para>

<para>
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>.
</para>

<para>
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.
</para>

</sect3> <!-- setup-docu-general-devhelp -->

<sect3 id="setup-docu-general-custom">
<title>Setting Up Custom Documentation Collections</title>

<para>
This is for your own purpose. You may add almost any documentation files here, provided they can be displayed by the &konqueror; plugins.
</para>

<screenshot>
  <mediaobject>
    <imageobject>
      <imagedata fileref="configure-docu-custom.png" format="PNG"/>
    </imageobject>
    <caption><para>
    Providing custom documentation
    </para></caption>
  </mediaobject>
</screenshot>

<para>
Usually this collection will be empty at first &kdevelop; startup. We have filled in a deliberate item to show the entry structure.
</para>
<para>
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.
</para>

<para>
You will have to explicitely 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>.
</para>

<note><para>
Custom documention cannot be indexed or searched. Thus the <guilabel>Index</guilabel> and <guilabel>Search</guilabel> check boxes have no effect here as shown above.
</para></note>

</sect3> <!--- setup-docu-general-custom -->

</sect2> <!-- setup-docu-general -->

<sect2 id="setup-docu-textsearch">
<title>Setting Up Text Search Indexes</title>

<para>
(... to be written ...)
</para>

<screenshot>
  <mediaobject>
    <imageobject>
      <imagedata fileref="configure-doctree-textsearch.png" format="PNG"/>
    </imageobject>
    <caption><para>
    Setting up text search indexes
    </para></caption>
  </mediaobject>
</screenshot>

</sect2> <!-- setup-docu-textsearch -->

<sect2 id="setup-docu-other">
<title>Other Documentation Configuration Settings</title>

<para>
(... to be written ...)
</para>

</sect2> <!-- setup-docu-other -->

</sect1> <!-- setup-docu -->

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

<sect1 id="setup-advanced">
<title>Advanced Configuration</title>

<para>
(... to be written ...)
</para>

<sect2 id="setup-plugins">
<title>Plugin Tools</title>

<para>
(... to be written ...)
</para>
</sect2> <!-- setup-plugins -->

</sect1> <!-- setup-advanced -->

</chapter> <!-- setup -->