summaryrefslogtreecommitdiffstats
path: root/doc/index.docbook
blob: a181e1cf50a9ac708a33295a8bb31abd6fd15070 (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
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
2440
2441
2442
2443
2444
2445
2446
2447
2448
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
2472
2473
2474
2475
2476
2477
2478
2479
2480
2481
2482
2483
2484
2485
2486
2487
2488
2489
2490
2491
2492
2493
2494
2495
2496
2497
2498
2499
2500
2501
2502
2503
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
2514
2515
2516
2517
2518
2519
2520
2521
2522
2523
2524
2525
2526
2527
2528
2529
2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540
2541
2542
2543
2544
2545
2546
2547
2548
2549
2550
2551
2552
2553
2554
2555
2556
2557
2558
2559
2560
2561
2562
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
2576
2577
2578
2579
2580
2581
2582
2583
2584
2585
2586
2587
2588
2589
2590
2591
2592
2593
2594
2595
2596
2597
2598
2599
2600
2601
2602
2603
2604
2605
2606
2607
2608
2609
2610
2611
2612
2613
2614
2615
2616
2617
2618
2619
2620
2621
2622
2623
2624
2625
2626
2627
2628
2629
2630
2631
2632
2633
2634
2635
2636
2637
2638
2639
2640
2641
2642
2643
2644
2645
2646
2647
2648
2649
2650
2651
2652
2653
2654
2655
2656
2657
2658
2659
2660
2661
2662
2663
2664
2665
2666
2667
2668
2669
2670
2671
2672
2673
2674
2675
2676
2677
2678
2679
2680
2681
2682
2683
2684
2685
2686
2687
2688
2689
2690
2691
2692
2693
2694
2695
2696
2697
2698
2699
2700
2701
2702
2703
2704
2705
2706
2707
2708
2709
2710
2711
2712
2713
2714
2715
2716
2717
2718
2719
2720
2721
2722
2723
2724
2725
2726
2727
2728
2729
2730
2731
2732
2733
2734
2735
2736
2737
2738
2739
2740
2741
2742
2743
2744
2745
2746
2747
2748
2749
2750
2751
2752
2753
2754
2755
2756
2757
2758
2759
2760
2761
2762
2763
2764
2765
2766
2767
2768
2769
2770
2771
2772
2773
2774
2775
2776
2777
2778
2779
2780
2781
2782
2783
2784
2785
2786
2787
2788
2789
2790
2791
2792
2793
2794
2795
2796
2797
2798
2799
2800
2801
2802
2803
2804
2805
2806
2807
2808
2809
2810
2811
2812
2813
2814
2815
2816
2817
2818
2819
2820
2821
2822
2823
2824
2825
2826
2827
2828
2829
2830
2831
2832
2833
2834
2835
2836
2837
2838
2839
2840
2841
2842
2843
2844
2845
2846
2847
2848
2849
2850
2851
2852
2853
2854
2855
2856
2857
2858
2859
2860
2861
2862
2863
2864
2865
2866
2867
2868
2869
2870
2871
2872
2873
2874
2875
2876
2877
2878
2879
2880
2881
2882
2883
2884
2885
2886
2887
2888
2889
2890
2891
2892
2893
2894
2895
2896
2897
2898
2899
2900
2901
2902
2903
2904
2905
2906
2907
2908
2909
2910
2911
2912
2913
2914
2915
2916
2917
2918
2919
2920
2921
2922
2923
2924
2925
2926
2927
2928
2929
2930
2931
2932
2933
2934
2935
2936
2937
2938
2939
2940
2941
2942
2943
2944
2945
2946
2947
2948
2949
2950
2951
2952
2953
2954
2955
2956
2957
2958
2959
2960
2961
2962
2963
2964
2965
2966
2967
2968
2969
2970
2971
2972
2973
2974
2975
2976
2977
2978
2979
2980
2981
2982
2983
2984
2985
2986
2987
2988
2989
2990
2991
2992
2993
2994
2995
2996
2997
2998
2999
3000
3001
3002
3003
3004
3005
3006
3007
3008
3009
3010
3011
3012
3013
3014
3015
3016
3017
3018
3019
3020
3021
3022
3023
3024
3025
3026
3027
3028
3029
3030
3031
3032
3033
3034
3035
3036
3037
3038
3039
3040
3041
3042
3043
3044
3045
3046
3047
3048
3049
3050
3051
3052
3053
3054
3055
3056
3057
3058
3059
3060
3061
3062
3063
3064
3065
3066
3067
3068
3069
3070
3071
3072
3073
3074
3075
3076
3077
3078
3079
3080
3081
3082
3083
3084
3085
3086
3087
3088
3089
3090
3091
3092
3093
3094
3095
3096
3097
3098
3099
3100
3101
3102
3103
3104
3105
3106
3107
3108
3109
3110
3111
3112
3113
3114
3115
3116
3117
3118
3119
3120
3121
3122
3123
3124
3125
3126
3127
3128
3129
3130
3131
3132
3133
3134
3135
3136
3137
3138
3139
3140
3141
3142
3143
3144
3145
3146
3147
3148
3149
3150
3151
3152
3153
3154
3155
3156
3157
3158
3159
3160
3161
3162
3163
3164
3165
3166
3167
3168
3169
3170
3171
3172
3173
3174
3175
3176
3177
3178
3179
3180
3181
3182
3183
3184
3185
3186
3187
3188
3189
3190
3191
3192
3193
3194
3195
3196
3197
3198
3199
3200
3201
3202
3203
3204
3205
3206
3207
3208
3209
3210
3211
3212
3213
3214
3215
3216
3217
3218
3219
3220
3221
3222
3223
3224
3225
3226
3227
3228
3229
3230
3231
3232
3233
3234
3235
3236
3237
3238
3239
3240
3241
3242
3243
3244
3245
3246
3247
3248
3249
3250
3251
3252
3253
3254
3255
3256
3257
3258
3259
3260
3261
3262
3263
3264
3265
3266
3267
3268
3269
3270
3271
3272
3273
3274
3275
3276
3277
3278
3279
3280
3281
3282
3283
3284
3285
3286
3287
3288
3289
3290
3291
3292
3293
3294
3295
3296
3297
3298
3299
3300
3301
3302
3303
3304
3305
3306
3307
3308
3309
3310
3311
3312
3313
3314
3315
3316
3317
3318
3319
3320
3321
3322
3323
3324
3325
3326
3327
3328
3329
3330
3331
3332
3333
3334
3335
3336
3337
3338
3339
3340
3341
3342
3343
3344
3345
3346
3347
3348
3349
3350
3351
3352
3353
3354
3355
3356
3357
3358
3359
3360
3361
3362
3363
3364
3365
3366
3367
3368
3369
3370
3371
3372
3373
3374
3375
3376
3377
3378
3379
3380
3381
3382
3383
3384
3385
3386
3387
3388
3389
3390
3391
3392
3393
3394
3395
3396
3397
3398
3399
3400
3401
3402
3403
3404
3405
3406
3407
3408
3409
3410
3411
3412
3413
3414
3415
3416
3417
3418
3419
3420
3421
3422
3423
3424
3425
3426
3427
3428
3429
3430
3431
3432
3433
3434
3435
3436
3437
3438
3439
3440
3441
3442
3443
3444
3445
3446
3447
3448
3449
3450
3451
3452
3453
3454
3455
3456
3457
3458
3459
3460
3461
3462
3463
3464
3465
3466
3467
3468
3469
3470
3471
3472
3473
3474
3475
3476
3477
3478
3479
3480
3481
3482
3483
3484
3485
3486
3487
3488
3489
3490
3491
3492
3493
3494
3495
3496
3497
3498
3499
3500
3501
3502
3503
3504
3505
3506
3507
3508
3509
3510
3511
3512
3513
3514
3515
3516
3517
3518
3519
3520
3521
3522
3523
3524
3525
3526
3527
3528
3529
3530
3531
3532
3533
3534
3535
3536
3537
3538
3539
3540
3541
3542
3543
3544
3545
3546
3547
3548
3549
3550
3551
3552
3553
3554
3555
3556
3557
3558
3559
3560
3561
3562
3563
3564
3565
3566
3567
3568
3569
3570
3571
3572
3573
3574
3575
3576
3577
3578
3579
3580
3581
3582
3583
3584
3585
3586
3587
3588
3589
3590
3591
3592
3593
3594
3595
3596
3597
3598
3599
3600
3601
3602
3603
3604
3605
3606
3607
3608
3609
3610
3611
3612
3613
3614
3615
3616
3617
3618
3619
3620
3621
3622
3623
3624
3625
3626
3627
3628
3629
3630
3631
3632
3633
3634
3635
3636
3637
3638
3639
3640
3641
3642
3643
3644
3645
3646
3647
3648
3649
3650
3651
3652
3653
3654
3655
3656
3657
3658
3659
3660
3661
3662
3663
3664
3665
3666
3667
3668
3669
3670
3671
3672
3673
3674
3675
3676
3677
3678
3679
3680
3681
3682
3683
3684
3685
3686
3687
3688
3689
3690
3691
3692
3693
3694
3695
3696
3697
3698
3699
3700
3701
3702
3703
3704
3705
3706
3707
3708
3709
3710
3711
3712
3713
3714
3715
3716
3717
3718
3719
3720
3721
3722
3723
3724
3725
3726
3727
3728
3729
3730
3731
3732
<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
  <!ENTITY kile "<application>Kile</application>">
  <!ENTITY latex "L<superscript>A</superscript>T<subscript>E</subscript>X">
  <!ENTITY pdflatex "PDFL<superscript>A</superscript>T<subscript>E</subscript>X">
  <!ENTITY tex "T<subscript>E</subscript>X">
  <!ENTITY tetex "<application>teT<subscript>E</subscript>X</application>">
  <!ENTITY texlive "<application>TeX Live</application>">
  <!ENTITY bibtex "BibT<subscript>E</subscript>X">
  <!ENTITY makeindex "makeindex">
  <!ENTITY kbibtex "KBibT<subscript>E</subscript>X">
  <!ENTITY kbib "KBib">
  <!ENTITY asymptote "Asymptote">
  <!ENTITY imagemagick "<application>ImageMagick</application>">
  <!ENTITY kde "<acronym>KDE</acronym>">
  <!ENTITY kdvi "<application>KDVI</application>">
  <!ENTITY dvipng "<application>dvipng</application>">
  <!ENTITY kghostview "<application>KGhostView</application>">
  <!ENTITY kpdf "<application>KPDF</application>">
  <!ENTITY postscript "<application>PostScript</application>">
  <!ENTITY makeidx "<application>makeidx</application>">
  <!ENTITY kate "<application>Kate</application>">
  <!ENTITY cjk "<abbrev>CJK</abbrev>">
  <!ENTITY ucs "<abbrev>ucs</abbrev>">
  <!ENTITY url "<acronym>URL</acronym>">
  <!ENTITY kappname "&kile;">
  <!ENTITY package "kdeextragear-2">
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % English "INCLUDE">
]>

<book lang="&language;">

<bookinfo>
<title>The &kile; Handbook</title>

<authorgroup>
	<author><firstname>Jonathan</firstname><surname>Pechta</surname></author>
	<author><firstname>Federico</firstname><surname>Zenith</surname>
	<affiliation><address><email>zenith@chemeng.ntnu.no</email></address></affiliation></author>
	<author><firstname>Holger</firstname><surname>Danielsson</surname>
	<affiliation><address><email>holger.danielsson@versanet.de</email></address></affiliation></author>
	<author><firstname>Thomas</firstname><surname>Braun</surname></author>
	<author><firstname>Michel</firstname><surname>Ludwig</surname>
	<affiliation><address><email>michel.ludwig@kdemail.net</email></address></affiliation></author>
</authorgroup>

<!-- TRANS:ROLES_OF_TRANSLATORS -->

<copyright>
<year>2003</year>
<holder>Jonathan Pechta</holder>
</copyright>

<copyright>
<year>2003</year><year>2005</year><year>2006</year>
<holder>Federico Zenith</holder>
</copyright>

<copyright>
<year>2005</year><year>2006</year>
<holder>Holger Danielsson</holder>
</copyright>

<copyright>
<year>2007</year>
<holder>Thomas Braun</holder>
</copyright>

<copyright>
<year>2007</year>
<holder>Michel Ludwig</holder>
</copyright>

<date>November 19, 2007</date>
<releaseinfo>2.0</releaseinfo>

<legalnotice>
&FDLNotice;
</legalnotice>

<abstract>
<para>
&kile; is a &tex; and &latex; source editor and shell.
</para>
</abstract>

<keywordset>
<keyword>KDE</keyword>
<keyword>kdenonbeta</keyword>
<keyword>Kile</keyword>
<keyword>LaTeX</keyword>
<keyword>TeX</keyword>
</keywordset>

</bookinfo>

<chapter id="preface">

<title>Preface</title>

	<sect1 id="preface_sect">

		<title>Requirements</title>
			
		<para>To Run &kile;, you will be required to have the following components 
		installed on your system:</para>

		<itemizedlist>
			<listitem><para>Trinity Desktop environment (&tde;):
			&tde; is a popular open-source desktop environment.</para></listitem>
			<listitem><para><ulink url="http://www.trolltech.com/products/qt/">Qt</ulink>: Qt is a C++
			 GUI and network library needed to compile &kile;.</para></listitem>
			<listitem><para><ulink url="http://www.ctan.org/">&latex;</ulink>: high-quality document
			typesetting program. Most likely you want the &texlive; (or on older systems the &tetex;) package, if you are on a
			Unix-like system.</para></listitem>
		</itemizedlist>

		<para>Most of these items might be included in your Linux distribution; please refer to your
		distribution documentation, or refer to your installation CD or DVD, for adding these
		packages to your computer.</para>

		<para>The &kile; project includes several binary packages of &kile; for different distributions that can be easily
		installed and run without having to compile; check out the <ulink url="http://kile.sourceforge.net/">&kile;
		homepage</ulink>.</para>

	</sect1>

	<sect1 id="preface_audience">

		<title>Intended Audience</title>

		<para>This manual is intended for any individual, regardless of her or his experience with
		&latex;, &kde;, &kile; or Linux.</para>

		<para>Advanced users are not likely to read this manual, but all suggestions on
		documentation will be considered. If you would like to contribute to this project or the
		documentation, please consult the <ulink url="http://kile.sourceforge.net/">&kile; web page</ulink>.</para>

		<para>Need answers about &kile;? Are you stuck with your compile? Want to see a new
		feature? The preferred way to ask technical questions or start a discussion is to
		use our mailing list: <email>kile-devel@lists.sourceforge.net</email>.</para>

	</sect1>

</chapter>

<chapter id="introduction">

	<title>Introduction</title>

	<sect1 id="intro_about">

		<title>Basic facts</title>

		<sect2>

			<title>About &kile;</title>

			<para>&kile; is an integrated &latex; environment for the &kde; desktop. &kile; gives you the
			ability to use all the functionalities of &latex; in a graphical interface, giving you easy,
			immediate, and customized access to all programs for &latex; codecompletion, compiling, postprocessing,
			debugging, conversion and viewing tools; you also get very handy wizards, a &latex;
			reference and a powerful project management.</para>

		</sect2>

		<sect2>

			<title>What is &latex;</title>

			<para>&latex; is a text-processing system derived from &tex;, a program developed originally in
			1977 by Donald Knuth to help him layout his work professionally, obtaining a work similar 
			to a typesetter's; the typesetter is the professional that styles a document's look according to 
			specifications for the type of document.
			&latex; was created by Leslie Lamport to give authors an automatic typesetter, especially when 
			it came to the expensive and painstaking typesetting of mathematical formulas and expressions,
			that <emphasis>by no chance</emphasis> are enclosed in dollar signs in &latex;.
			Today, word-processing programs let any user be the typesetter; but what you often want
			is a document that looks good, not one that you spent hours on to make it look good.
			&latex; takes that burden, and lets you think of the document, not of the layout. And yes,
			it <emphasis>will</emphasis> look good!</para>

		</sect2>

		<sect2>

			<title>How do you pronounce it? Why that strange typesetting?</title>

			<para>There is a funny traditions of &tex;-related packages to have the strangest pronunciation
			and typesetting possible. &tex; was supposed to be brought in from the Greek <emphasis>τεχ</emphasis>,
			in Latin letters <emphasis>tech</emphasis>. There are a lot of explanations why, but most likely it is because
			&tex; was originally conceived for technical reports, and indeed its foremost ability was the correct and
			easy typesetting of mathematical formulae, then an extremely expensive, time-consuming and
			frustrating business.</para>
			<para>The pronunciation is supposed to be as follows: <emphasis>T</emphasis> as you would expect,
			<emphasis>E</emphasis> as in <emphasis>get</emphasis>, and <emphasis>X</emphasis> as in the
			German i<emphasis>ch</emphasis>. If you do not know what <emphasis>ch</emphasis> sounds like,
			it is more or less as an hissing cat; the IPA symbol is /ç/. Many people report the different pronunciation
			of <emphasis>ach</emphasis> (IPA symbol /x/), but I have personally asked some Greeks, and can
			confirm the first version. You should be aware that a lot of people mispronounce /teks/ or /tek/.</para>
			<para>Last, in &latex; the first L<superscript>A</superscript> is pronounced as
			<emphasis>lay</emphasis>: the idea is that, while raw &tex; is difficult, even a <emphasis>lay</emphasis>man
			can use &latex; macros. A less inspiring, but more realistic explanation is that it stems from the surname of 
			Leslie Lamport, the creator of &latex;. Now you know!</para>

		</sect2>

	</sect1>

	<sect1 id="intro_latexbasics">

		<title>&latex; 101</title>

		<para>The &latex; typesetting system is similar to other markup languages as XML, used for
		many types of documents (including the one you are reading), or HTML, used for web
		pages. The general idea is about having specially wrapped keywords, called <emphasis>
		tags</emphasis>, that tell a program (a word processor, a web browser, or the &latex;
		compiler) how to present text. &kile; offers you a good number of such tags in the
		menu <guimenu>LaTeX</guimenu> in the menu bar.</para>

		<para>While we will try to give you a good idea of what &latex; is, this is not The Definitive
		Book on &latex;. If you want to learn &latex; well, you may want to loan a book in your
		library. The writer has had a good experience with A Guide to &latex; by H. Kopka
		and P. W. Daly, and still keeps it on the shelf.</para>

		<para>As other markup languages, &latex; contains a <emphasis>preamble</emphasis>, which
		sets global commands, such as paper size, page numbering, dimensions of the text on the page,
		and a <emphasis>body</emphasis>, that contains the document text; the preamble contains
		at least the <userinput>\documentclass</userinput> command, and precedes the body, that 
		starts with the command <userinput>\begin{document}</userinput>, and is quite predictably 
		concluded by the command <userinput>\end{document}</userinput>.</para>

	</sect1>

	<sect1 id="intro_mainfeat">

		<title>&kile;'s Main Features</title>

		<sect2 id="intro_docwizard">

			<title>QuickStart Wizard</title>

			<para>The QuickStart wizard built into &kile; is a useful feature to quickly start creating documents
			in &kile;. Choosing the wizard from the menubar gives you several choices
			for the creation of your document.
			You can also specify some options related to the document right away.</para>

			<para>Class options:</para>

			<itemizedlist>
				<listitem><para><guilabel>Document Class</guilabel>: choose the type of document you want to create:
				 article, book, letter, report, scrartcl, scrreprt, scrbook, prosper, beamer or other
				 custom-defined.</para></listitem>
				<listitem><para><guilabel>Typeface Size</guilabel>: tell &kile; what point size (pt) 
				you want to use.</para></listitem>
				<listitem><para><guilabel>Paper Size</guilabel>: choose the size or style of sheets.</para></listitem>
				<listitem><para><guilabel>Encoding</guilabel>: In general it is a good idea to use your systems standard
						encoding. Modern systems now move more and more to UTF-8 as the standard encoding.
						If you can, use utf8x (which is indeed the correct spelling for &latex; documents).
					</para></listitem>
				<listitem><para><guilabel>Other options</guilabel>: this allows you to set further options such as printing, 
				draft, and others.</para></listitem>
			</itemizedlist>
			
			<para>Packages</para>
			<para>This lists some of the most common additional packages used in &latex;. Select the checkbox to include it.</para>

			<para>Document Properties</para>
			<itemizedlist>
				<listitem><para><guilabel>Author</guilabel>: put your name here.</para></listitem>
				<listitem><para><guilabel>Title</guilabel>: add the document title here.</para></listitem>
				<listitem><para><guilabel>Date</guilabel>: specify the date.</para></listitem>
			</itemizedlist>

		</sect2>

		<sect2 id="intro_templates">

			<title>Predefined Templates</title>

			<para>The predefined templates in &kile; are:</para>

			<itemizedlist>
				<listitem><para>Empty document: real freaks start from scratch!</para></listitem>
				<listitem><para>Article: sets the article format, for a document short enough not to
				be broken down to chapters.</para></listitem>
				<listitem><para>Report: sets the report format, for a middle-sized document, with for
				example page numbering on the page's outer edge.</para></listitem>
				<listitem><para>Book: sets the book format, a full-fledged flavor, so powerful that
				it is used to write many university textbooks.</para></listitem>
				<listitem><para>Letter: sets the letter format, that can automatically do those nasty
				indentations that nobody really remembers.</para></listitem>
				<listitem><para>Beamer,HA-Prosper: create nice presentations in PDF with a superior look and all 
						&latex; power.</para></listitem>
				<listitem><para>Scrartcl,Scrbook,Scrreprt,Scrlttr2: the KOMA-Script document classes, 
						especially adapted to german typography. Use them whenever you write german
						texts.</para></listitem>
			</itemizedlist>
			
			<para>New users need not to worry, this list is just a brief description of features,
			and more attention will be paid to complete these tasks in detail later in 
			<xref linkend="quickstart"/>.</para>

		</sect2>

		<sect2 id="intro_highlight">

			<title>Syntax Highlighting</title>

			<para>&kile; is similar to programs that deal with source code and editing, and will
			automatically highlight commands, options and items that are used (and abused).
			&kile; makes it possible to spot easily problem areas: for example, if you see major
			areas of text turned green, it is likely that you forgot closing a math environment somewhere;
			you would have noticed anyway by how crappy the output file would have looked, but
			highlighting really saves you time and frustration.</para>

		</sect2>

		<sect2 id="intro_autocoml">

			<title>Auto-Completion of Environments</title>

			<para>The auto-completion of environments means that, when you begin a new environment by typing
			<userinput>\begin{environment}</userinput>, &kile; will automatically insert a matching
			<userinput>\end{environment}</userinput> command, with a line in between them
			for your text. You can of course deactivate it if you want in 
			<menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure Kile...</guisubmenu>
			<guimenuitem>LaTeX</guimenuitem><guilabel>Environments</guilabel></menuchoice>.</para>

		</sect2>

		<sect2 id="intro_jump">

			<title>Jump to Structure Element</title>

			<para>All documents are normally structured in a hierarchy of some type.
			&latex; allows you to break up documents into the following hierarchy
			(part being highest in the hierarchy, and subparagraph being lowest):</para>

			<itemizedlist>
				<listitem><para>\part</para></listitem>
				<listitem><para>\chapter</para></listitem>
				<listitem><para>\section</para></listitem>
				<listitem><para>\subsection</para></listitem>
				<listitem><para>\subsubsection</para></listitem>
				<listitem><para>\paragraph</para></listitem>
				<listitem><para>\subparagraph</para></listitem>
			</itemizedlist>

			<para>When viewing a document in the <guilabel>Structure</guilabel> view, you can jump 
			between elements by clicking on the element you would like to view.</para>

		</sect2>

		<sect2 id="intro_inverse">

			<title>Inverse Search</title>

			<para>When creating your own &latex; files, inverse search can be very helpful. Once you
			have created a DVI file (DeVice Independent File), you can click the middle-
			mouse button in the DVI viewer and &kile; will jump to the corresponding line in the
			&latex; source code.</para>

			<para>A DVI is a type of file containing a
			description of a formatted document, along with other
			information including character font, and is besides PDF the usual output of
			&tex; or &latex;. A number of utilities exist to view, convert and print DVI files on
			various systems and devices.</para>

		</sect2>

		<sect2 id="intro_forward">

			<title>Forward Search</title>

			<para>When using inverse search, the selection of items in the DVI file is associated with
			the editor, so when you click on the DVI file, the main window jumps to the
			corresponding section of &latex; code in the editor. Forward search is the exact
			opposite of this. Forward search will allow you to click on a specific section of text
			in the &latex; code, and jump to the associated position in the DVI viewer window.</para>

		</sect2>

	</sect1>

	<sect1 id="intro_toolbar">

		<title>The Toolbar</title>

		<itemizedlist>
			<listitem><para><guibutton>New</guibutton>: begin a new document.</para></listitem>
			<listitem><para><guibutton>Open</guibutton>: open a new document.</para></listitem>
			<listitem><para><guibutton>Close</guibutton>: close your document.</para></listitem>
			<listitem><para><guibutton>Define document as master</guibutton>: this is used when working with multiple files.
			Having a master document will let you work more easily with other <literal role="extension">.tex</literal> files included 
			in your document. If you are using projects, you can also set in  <menuchoice><guimenu>Project-></guimenu><guisubmenu>Project
			Options</guisubmenu></menuchoice> a project-wide master document.</para></listitem>
			<listitem><para><guibutton>Quickbuild</guibutton>: compiles your &latex; source code and displays the results
			automatically, unless you have code errors.</para></listitem>
			<listitem><para><guibutton>Watch file mode</guibutton>: this mode will "watch" the DVI file for changes, and
			will not launch a new session of &kdvi; after <guibutton>Quickbuild</guibutton>.</para></listitem>
			<listitem><para><guibutton>View logfile</guibutton>: views the <literal role="extension">.log</literal> file,
					so you can spot errors.</para></listitem>
			<listitem><para><guibutton>Previous error</guibutton>: jumps backward through the 
					<literal role="extension">.log</literal> file 
					and highlights errors in source.</para></listitem>
			<listitem><para><guibutton>Next error</guibutton>: jumps forward through
					<literal role="extension">.log</literal> file and 
			highlights errors in source.</para></listitem>
			<listitem><para><guibutton>Stop</guibutton>: halts current tool.</para></listitem>
			<listitem><para><guibutton>LaTeX</guibutton>: runs &latex; on the active document.</para></listitem>
			<listitem><para><guibutton>View DVI</guibutton>: launches DVI viewer.</para></listitem>
			<listitem><para><guibutton>DVI to PS</guibutton>: converts a DVI to a &postscript; (PS).</para></listitem>
			<listitem><para><guibutton>View PS</guibutton>: launches &postscript; (PS) viewer.</para></listitem>
			<listitem><para><guibutton>PDFLaTeX</guibutton>: runs &pdflatex; on the active document.</para></listitem>
			<listitem><para><guibutton>View PDF</guibutton>: launches the PDF viewer.</para></listitem>
			<listitem><para><guibutton>DVI to PDF</guibutton>: converts a DVI to a PDF.</para></listitem>
			<listitem><para><guibutton>PS to PDF</guibutton>: converts a PS to a PDF.</para></listitem>
			<listitem><para><guibutton>View HTML</guibutton>: views HTML created.</para></listitem>
			<listitem><para><guibutton>Kdvi Forward Search</guibutton>: jump to page that corresponds to the current line in the
			editor.</para></listitem>
		</itemizedlist>

		<para>If you look at the <guilabel>Edit</guilabel> toolbar, you will notice three large 
		drop-down menus. The drop-down menus were designed for you to be able to quickly add
		certain common features into your document. The first drop-down box
		is used for quickly dividing your document by parts, chapter, sections and so on; the
		available commands to add segments to your &latex; source code are:</para>

		<itemizedlist>
			<listitem><para><guilabel>part</guilabel>: highest level of sectioning for a document.</para></listitem>
			<listitem><para><guilabel>chapter</guilabel>: starts a new chapter.</para></listitem>
			<listitem><para><guilabel>section</guilabel>: create a new section.</para></listitem>
			<listitem><para><guilabel>subsection</guilabel>: create a new subsection.</para></listitem>
			<listitem><para><guilabel>subsubsection</guilabel>: a secondary section between subsection and
			paragraph.</para></listitem>
			<listitem><para><guilabel>paragraph</guilabel>: create a new paragraph.</para></listitem>
			<listitem><para><guilabel>subparagraph</guilabel>: create a new subparagraph.</para></listitem>
		</itemizedlist>

		<para>The drop-down box named <guilabel>label</guilabel> is used to insert items to your document such as
		indexes, footnotes, and references; the available commands are:</para>

		<itemizedlist>
			<listitem><para><guilabel>label</guilabel>: a command that produces a label for a chapter, 
			a figure or another element.</para></listitem>
			<listitem><para><guilabel>index</guilabel>: creates an entry for the index.</para></listitem>
			<listitem><para><guilabel>footnote</guilabel>: creates a footnote in your document.</para></listitem>
			<listitem><para><guilabel>ref</guilabel>: used to refer to a predefined label, which
			you can choose from a drop-down list.</para></listitem>
			<listitem><para><guilabel>pageref</guilabel>: just like <guilabel>ref</guilabel>, but refers to 
			a page instead of a structure element.</para></listitem>
			<listitem><para><guilabel>cite</guilabel>: create a reference with data from a bibliography.</para></listitem>
			<listitem><para><guilabel>cite from ViewBib</guilabel>: ask the ViewBib tool for all selected references and insert them.
			Currently this is only avaible with <ulink url="http://user.digisurf.com.au/~thachly/kbib/">&kbib;</ulink> as ViewBib tool.</para></listitem>
		</itemizedlist>

		<screenshot>
			<screeninfo>The <guilabel>Label</guilabel> drop-down menu</screeninfo>
			<mediaobject>
			<imageobject>
			<imagedata fileref="snap_ref_choose.png" format="PNG" />
			</imageobject>
			<textobject>
			<phrase>The <guilabel>Label</guilabel> drop-down menu</phrase>
			</textobject>
			<caption><para>The <guilabel>Label</guilabel> drop-down menu</para></caption>
			</mediaobject>
		</screenshot>

		<screenshot>
			<screeninfo>Selecting the label for a reference</screeninfo>
			<mediaobject>
			<imageobject>
			<imagedata fileref="snap_ref_select.png" format="PNG" />
			</imageobject>
			<textobject>
			<phrase>Selecting the label for a reference</phrase>
			</textobject>
			<caption><para>Selecting the label for a reference</para></caption>
			</mediaobject>
		</screenshot>

		<para>When using <guilabel>cite</guilabel>, you are presented with a drop-down 
		list of bibitems, but if you are using &bibtex; this will only work if the file 
		belongs to a Project. For editing &bibtex; files the usage of specialised editors is recommened.
		The author has made good experience with &kbibtex; and &kbib;. Of course you can also write the &bibtex; files by hand inside &kile;.</para>

		<para>The last drop-down box labeled <guilabel>tiny</guilabel> is used to set the size of the text. You can
		set the size of the main text, of footnotes, and so on. The available commands are:</para>

		<itemizedlist>
			<listitem><para><guilabel>tiny</guilabel>: smallest.</para></listitem>
			<listitem><para><guilabel>scriptsize</guilabel>: very small.</para></listitem>
			<listitem><para><guilabel>footnotesize</guilabel>: smaller.</para></listitem>
			<listitem><para><guilabel>small</guilabel>: small.</para></listitem>
			<listitem><para><guilabel>normalsize</guilabel>: normal.</para></listitem>
			<listitem><para><guilabel>large</guilabel>: large.</para></listitem>
			<listitem><para><guilabel>Large</guilabel>: larger.</para></listitem>
			<listitem><para><guilabel>LARGE</guilabel>: even larger.</para></listitem>
			<listitem><para><guilabel>huge</guilabel>: still larger.</para></listitem>
			<listitem><para><guilabel>Huge</guilabel>: largest.</para></listitem>
		</itemizedlist>

	</sect1>

</chapter>
<chapter id="quickstart">

	<title>Quickstart</title>

	<sect1 id="quick_begin">

		<title>Writing a &latex; Document with &kile; for Beginners</title>

		<para>Users of &kile; have two choices when starting a new document: they can use the 
		<guimenu>Wizard</guimenu> to begin a new document, select the type of document they
		would like to create and options such as font size, paper size, and so on; otherwise, 
		they can write the code by hand.</para>

		<screen><userinput>
		\documentclass[12pt]{article}
		\begin{document}
		Here is a bunch of text coded in \LaTeX.
		\end{document}</userinput></screen>

		<para>Every document in &latex; begins with the command <userinput>
		\documentclass[optional argument]{class}</userinput>, where class specifies the document type.</para>

		<para>Typing in the code example above from the text box gives you the following output:</para>

		<screenshot>
			<screeninfo>Compiled text in DVI output</screeninfo>
			<mediaobject>
				<imageobject>
					<imagedata fileref="latex_example.png" format="PNG" />
				</imageobject>
				<textobject>
					<phrase>Compiled text in DVI output</phrase>
				</textobject>
				<caption><para>Compiled text in DVI output</para></caption>
			</mediaobject>
		</screenshot>

		<para>The brackets that come after the command <userinput>\documentclass</userinput>
		contain the options for the command. The option <userinput>[12pt]</userinput> sets the size
		of the font for your article; if you do not set the font size in the beginning, you can set 
		it later in the text.</para>

		<para>Once you have typed in the code example from the box above, you will need to
		compile your &latex; source code. The easiest way for you to compile &latex; is to
		use the <guimenu>Build</guimenu> menu, or using the <guilabel>Quickbuild</guilabel> button.</para>

		<para><keycombo>&Alt;<keycap>2</keycap></keycombo>
		is the keyboard shortcut to compile your source code.</para>

		<para>You have to save your source code before you can compile; &kile; will do this automatically for you.</para>

		<para>If your document did not compile, check the log for errors. When using the <guilabel>Quickbuild</guilabel>
		key, the &kdvi; viewer should be launched automatically; if it does not, look at the log.</para>

	</sect1>

	<sect1 id="quick_env">
		<title>Environments</title>

		<para>An environment is a segment of text that is managed differently
		than the rest of the document. For example, you create a report with font size 12, 
		but you need to change your font size for a few sentences. The commands 
		<userinput>\begin{environment}</userinput>, <userinput>\huge</userinput> and 
		<userinput>\end{environment}</userinput> will let you temporarily alter the text inside 
		the environment commands to be size huge.</para>

		<para>Changes are only effective from <userinput>\begin{environment}</userinput> to
		<userinput>\end{environment}</userinput>. There are no limits as how many changes
		you can make inside an environment.</para>

		<para>There are many features you can add to your document that will make it more
		readable and user-friendly. You can add features such as specific fonts, bold, italics,
		underline etc. to your document, and these commands will end with either an
		<userinput>\end</userinput> command, or at the end of your environment.</para>

		<itemizedlist>
			<listitem><para><userinput>\begin{emph}</userinput>: this command makes 
			text italicized, and is valid until the code comes across a <userinput>\end{emph}</userinput>,
			<userinput>\end{emph}</userinput> or another environment. To italicize one word in a sentence, you
			can use the syntax: this is <userinput>\emph{my}</userinput> sentence.</para></listitem>
			<listitem><para><userinput>\textbf{I am making this text inside the brackets bold}</userinput>: this
			command makes your text bold.</para></listitem>
			<listitem><para><userinput>\quote</userinput>: to create a quote inside your document; begin your quote
			with <userinput>\begin{quote}</userinput> and end it with <userinput>\end{quote}</userinput>.</para></listitem>
			<listitem><para><userinput>\center</userinput>: centers the text.</para></listitem>
			<listitem><para><userinput>\verse</userinput>: creates offset text for poems.</para></listitem>
			<listitem><para><userinput>\itemize</userinput>: makes an itemized list.</para></listitem>
		</itemizedlist>

	</sect1>

	<sect1 id="quick_using">

		<title>Using &kile;</title>

		<para>Now that we have given you some background about how to write code using the
		&latex; markup language, we will show you how to create a document
		using &kile; step-by-step.</para>

		<procedure>
			<step><para>Start &kile;.</para></step>
			<step><para>Select <menuchoice><guimenu>Wizard</guimenu><guimenuitem>Quick Start</guimenuitem></menuchoice>,
			then choose a format, and set your preferences in the wizard.</para></step>
			<step><para>Once the wizard has entered text, do some customization to make the
			document more readable, add a minimum of one quote, some bold text,
			italics, and a verse to see the difference between the commands.</para></step>
			<step><para>Save your file, and give it the name <filename>intro.tex</filename>.</para></step>
			<step><para>Build your document using <keycombo>&Alt;<keycap>2</keycap></keycombo>, or the
			button labeled <guilabel>LaTeX</guilabel>.</para></step>
			<step><para>Select <guibutton>View DVI</guibutton>.</para></step>
			<step><para>Check out all your new text.</para></step>
			<step><para>When you are done viewing your document, click the <guibutton>Editor View</guibutton>
					button or press <keycombo>&Ctrl;<keycap>e</keycap></keycombo>
					to return to the editor if you are using the embedded 
			viewer, or close the viewer window if you are using a separate viewer.</para></step>
		</procedure>

		<para>That's it! You have just created your first &latex; document!</para>

		<para>Once you have created your DVI, you will be able to print your document, or change
		it into a &postscript; or PDF file if you want. Experiment and have fun!</para>

	</sect1>

	<sect1 id="quick_dvi">

		<title>DVI Files</title>

		<para>DVI stands for <emphasis>DeVice Independent</emphasis> file. These files are produced
		by &tex; or &latex; to be read by a driver of some sort on your computer. There are many different types of output that
		a <literal role="extension">.dvi</literal> can be sent to, such as a printer, &postscript; or PDF file converter, or your computer screen.</para>

	 	<sect2 id="quick_viewdvi">

			<title>Viewing a DVI</title>

			<para>You have already seen how to view a DVI file on the screen by using the <guibutton>View
			DVI</guibutton> button in the toolbar.</para>

		</sect2>

		<sect2 id="quick_printdvi">

		<title>Printing a DVI</title>

			<para>To print a DVI, you can use the same process that you used to create your
			document earlier (see <xref linkend="quick_using"/>). At step 7, after
			clicking <guibutton>View DVI</guibutton>, select
			<menuchoice><guimenu>File</guimenu><guimenuitem>Print</guimenuitem></menuchoice>
			in the viewer, and if you have your printer properly configured, you will be able 
			to print the DVI.</para>

		</sect2>

		<sect2 id="quick_exportdvi">

			<title>Converting DVI files</title>

			<para>The toolbar gives the options of Converting a DVI to other formats. Once you
			have created a DVI from your &latex; source code, you will be able to export it
			to a format of your choice using the toolbar buttons.</para>

		</sect2>

	</sect1>

	<sect1 id="quick_forward">

		<title>Forward Search between &kile; and &kdvi;</title>

		<para>The forward search functions allow you to jump from your
		editor directly into the associated position of the &DVI;
		file. </para>
		<para>&kile; offers a configuration with this option for all &latex; binaries.
		Go to <menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure Kile...</guisubmenu>
		<guimenuitem>Tools</guimenuitem><guilabel>Build</guilabel></menuchoice>
		and always choose the <guilabel>Modern</guilabel> configuration.</para>

		<para>To execute a forward search, position the cursor on a line of source code, and click 
		<guilabel>Kdvi Forward Search</guilabel> to jump to the associated position 
		in the DVI viewer window.</para>
	</sect1>
	
	<sect1 id="quick_inverse">

		<title>Inverse Search between &kile; and &kdvi;</title>

		<para>Inverse search is a very useful feature when you are writing
		a &latex; document yourself. If everything is set up properly, you can
		click into &kdvi;'s window with the &MMB; (on some systems,
		when you do not have a three-button mouse, you can simultaneously
		use the <mousebutton>left</mousebutton> and the
		<mousebutton>right</mousebutton> button). After that kile load the &latex; source file and jump to
		the proper paragraph. To use inverse search, you have to compile your &latex; file with the <guilabel>Modern</guilabel> configuration.</para>

		<para>Inverse search cannot work unless:</para>

		<itemizedlist>
			<listitem><para>The source file has been compiled successfully.</para></listitem>
			<listitem><para>&kdvi; knows which editor you would like to use.</para></listitem>
		</itemizedlist>

		<para>With this feature of &kdvi;, a middle mouse click in the DVI document will
		result in &kile; opening the corresponding &latex; document and attempt to go to the
		corresponding line. Remember to tell &kdvi; to use &kile; as a text editor, in &kdvi;'s
		menu item <menuchoice><guimenu>Settings</guimenu><guimenuitem>DVI Options...</guimenuitem></menuchoice>.</para>
			
		<screenshot>
			<screeninfo>Configuring &kdvi;</screeninfo>
			<mediaobject>
			<imageobject>
			<imagedata fileref="snap_kdvi_settings.png" format="PNG" />
			</imageobject>
			<textobject>
			<phrase>Configuring &kdvi;</phrase>
			</textobject>
			<caption><para>Configuring &kdvi;</para></caption>
			</mediaobject>
		</screenshot>
	</sect1>

	<sect1 id="quick_errors">

		<title>Resolving Errors</title>

		<para>If you are trying to use quickbuild, and the DVI viewer does not open, chances are
		you have an error. If you have an error, it will be visible in the log file / message area,
		and the summary of the error will be given.</para>

		<para>The log file will explain the source of the error in your code. In the
		editor, you can use the buttons in the toolbar labeled <guibutton>Previous LaTeX Error</guibutton>
		and <guibutton>Next LaTeX Error</guibutton> to jump to and from errors. The log file always states
		in which line the error occurred. To view the line where an error occurred, click on the error
		in the log window, and &kile; will take you to error's line.</para>

	</sect1>

</chapter>
<chapter id="startnew">

	<title>Starting a New Document</title>

	<para>When you click the button in the toolbar to begin a new document a dialog appears,
	asking which type of template you would like to use to write your document. The
	default choices are:</para>

	<itemizedlist>
		<listitem><para>Empty document</para></listitem>
		<listitem><para>Article</para></listitem>
		<listitem><para>Beamer</para></listitem>
		<listitem><para>Book</para></listitem>
		<listitem><para>HA-Prosper</para></listitem>
		<listitem><para>Letter</para></listitem>
		<listitem><para>Report</para></listitem>
		<listitem><para>Scrartcl (from the KOMA-Script package)</para></listitem>
		<listitem><para>Scrbook (from the KOMA-Script package)</para></listitem>
		<listitem><para>Scrlttr2 (from the KOMA-Script package)</para></listitem>
		<listitem><para>Scrreprt (from the KOMA-Script package)</para></listitem>
	</itemizedlist>

	<para>If you selected an <guilabel>Empty document</guilabel>, you can either start 
	writing a document from scratch, or you can use the wizard to quickly start a new 
	document (see <xref linkend="intro_docwizard"/>).</para>


	<sect1 id="startnew_templates">

		<title>Templates</title>

		<para>Frequent users of &latex; typically use the same preamble for almost every document they use. 
		Templates can be created, saved and loaded within &kile; to make it easier to start a new document.</para>


		<sect2>
			<title>Create a New Template</title>

			<para>To create a new template, you must first either open a &tex; / &latex; file, or create a file
			of your own. &kile; can generate a template from an existing document by opening the desired document and selecting
			<menuchoice><guimenu>File</guimenu><guimenuitem>Create Template from Document</guimenuitem></menuchoice>.</para>

		</sect2>

		<sect2>

			<title>Configuring Automatic Substitutions</title>

			<para>When creating a new document by selecting a template from
			<menuchoice><guimenu>File</guimenu><guimenuitem>New</guimenuitem></menuchoice>,
			certain character combinations will be replaced by data such as your name, 
			or the character encoding your are using. These variables can be configured in
			<menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure Kile...</guisubmenu>
			<guimenuitem>Settings</guimenuitem><guilabel>General</guilabel></menuchoice>.</para>

			<para>When designing your own template, it is useful to known which character 
			combinations are replaced by which template variables:</para>

			<itemizedlist>
				<listitem><para><userinput>$$AUTHOR$$</userinput>: This string
				will be replaced by the author variable.</para></listitem>
				<listitem><para><userinput>$$DOCUMENTCLASSOPTIONS$$</userinput>: This string will be replaced 
				by the documentclass options variable. Typically this is used as follows:
				<userinput>\documentclass[$$DOCUMENTCLASSOPTIONS$$]{article}</userinput>.</para></listitem>
				<listitem><para><userinput>$$INPUTENCODING$$</userinput>: If the
				inputencoding variable is set to, say, <userinput>latin1</userinput> this string is replaced by
				<userinput>\input[latin1]{inputenc}</userinput>.</para></listitem>
			</itemizedlist>

		</sect2>

		<sect2 id="templ_wiz">

			<title>Create a Template from the Wizard</title>

			<para>The easiest way to create a new template is to start the wizard,
			and then add commands in the editor. Once you have your
			document set up the way you like:</para>

			<procedure>
				<step><para>Save your file;</para></step>
				<step><para>Go to <guimenu>File</guimenu>;</para></step>
				<step><para>Choose <guimenuitem>Create Template from Document</guimenuitem>;</para></step>
				<step><para>Make any corrections necessary to the template;</para></step>
				<step><para>Enter a name for your new template;</para></step>
				<step><para>Click <guibutton>OK</guibutton> to add your template to the menu.</para></step>
			</procedure>

			<para>Next time you start up a new document, you will be able to choose 
			your customized template instead of the default ones.</para>

		</sect2>

		<sect2>

			<title>Creating a Template from any File</title>

			<para>A template can be created from any &latex; file. If you are looking for an easy way to
			configure a template, go find one you like on the Internet and follow the same steps
			listed in <xref linkend="templ_wiz"/>.</para>

			<para>For instance, you may want to create a full-fledged A0 poster. These posters are usually seen
			at scientific conferences, and &latex; will help you making an attractive, catchy poster. You can get a
			template for A0 posters at <ulink url="http://www.stats.ox.ac.uk/~marchini/a0poster.html">Jonathan Marchini's 
			home page</ulink>, but many more are available. Remember that you will need the <filename>a0poster</filename> 
			package, which is normally not in standard tex distributions included. Download it from
			<ulink url="http://www.ctan.org/tex-archive/macros/latex/contrib/a0poster/">here</ulink> and place it in the same directory as your &latex; file.</para>
		</sect2>

		 <sect2 id="templ_rem">

	 		<title>Removing a Template</title>

			<para>To remove a template from &kile;, do as follows:</para>

			<procedure>
				<step><para>Go to <menuchoice><guimenu>File</guimenu><guimenuitem>Remove 
				Template...</guimenuitem></menuchoice>;</para></step>
				<step><para>A dialog box will appear with all templates listed: select a template;</para></step>
				<step><para>Click <guilabel>OK</guilabel>, and your template will be removed.</para></step>
			</procedure>
			
			<para>Templates marked with an asterisk (*) cannot be removed without the proper permission.</para>

		</sect2>

	</sect1>

</chapter>
<chapter id="editing">

	<title>Editing &latex; Documents</title>

	<para>The internal editor that &kile; uses is &kate;.
	Kate is a text editor created for programmers, which incorporates the ability to read
	and highlight many different types of text files, among which are &latex; and &bibtex;; you can access
	many options for &kate; directly from &kile;'s <guimenu>Tools</guimenu> menu.</para>

	 <para>To learn more about &kate; and its capabilities, see the <ulink url="help:kate">Kate Handbook</ulink>.
	&kile; users can start reading from the chapter <quote>Working with the Kate Editor</quote>.</para>

	 <sect1 id="editing_sect">

		<title>The &latex; Reference</title>

		<para>&kile; features a very practical &latex; tag reference, which you can access
		by choosing <menuchoice><guimenu>Help</guimenu><guimenuitem>LaTeX 
		Reference</guimenuitem></menuchoice>. It contains a thorough description
		of almost all the commands that you may use in &latex; and their syntax.</para>

	</sect1>

	<sect1 id="editing_cursor">

	 	<title>Cursor Movements</title>
		
		<para>To select text, you have the following options:</para>

		<itemizedlist>
			<listitem><para>Hold left mouse button, and drag mouse to highlight text.</para></listitem>
			<listitem><para>Click once on a word to move the cursor to a new area.</para></listitem>
			<listitem><para>Click twice on a word to select the whole word.</para></listitem>
			<listitem><para>Click twice on a word and pressing <keycombo>&Ctrl;</keycombo> to select the whole tex word.
      This means clicking in this way on <userinput>\par</userinput> from <userinput>\par\bigskip</userinput> only select \par.</para></listitem>
			<listitem><para>Click three times to select the whole sentence.</para></listitem>
		</itemizedlist>

		<para>Holding the left mouse button, and dragging the text you want to select,
		automatically copies the selected text to the clipboard.</para>

		<para>Holding shift and using the arrow keys allows you to select portions of the source
		code in the editor window.</para>

	</sect1>

	<sect1 id="editing_bracket">

		<title>Brackets</title>

		<para>Bracket completion is a visual tool that the editor view uses to indicate you
		which bracket matches which. If you open any <literal role="extension">.tex</literal> file, 
		and select any bracket, whether it be a parenthesis (), square brackets [] or braces {}, the 
		editor will highlight the bracket and its match in yellow (this default color can be changed). 
		So, for example, if you position the cursor on the braces in 
		<userinput>\section{Introduction}</userinput>, you would see
		<userinput>\section{Introduction}</userinput> in the default yellow highlight,
		showing you the location of the beginning and ending brackets.</para>

	</sect1>

	<sect1 id="editing_highlight">

		<title>Highlighting</title>

		<para>&kile; has the ability to look for and highlight different types of code. For example, &latex; commands
			are distinguished from normal text, and math formulas are highlighted also in a different color.</para>
	
	</sect1>

	<sect1 id="editing_bullets">

		<title>Bullets</title>

		<para>Many wizards can insert optional bullets, a special kind of bookmarks within the text. The
		menu entries <menuchoice><guimenu>Edit</guimenu><guisubmenu>Bullets</guisubmenu></menuchoice> or 
		the corresponding keyboards shortcuts will allow you to jump to the next or last bullet. 
		This will also highlight this bullet so that it will be deleted automatically, 
		when you enter your first letter.</para>
		
		<screenshot>
			<screeninfo>Bullets</screeninfo>
			<mediaobject>
			<imageobject>
			<imagedata fileref="bullets.png" format="PNG" />
			</imageobject>
			<textobject>
			<phrase>Bullets</phrase>
			</textobject>
			</mediaobject>
		</screenshot>

		<variablelist>
		
		<varlistentry><term><menuchoice>
		<shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>Right</keycap></keycombo></shortcut>
		<guimenuitem>Next Bullet</guimenuitem></menuchoice></term>
		<listitem><para>Jump to the next bullet in the text if there is one.</para></listitem>
		</varlistentry>
	 
		<varlistentry><term><menuchoice>
		<shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>Left</keycap></keycombo></shortcut>
		<guimenuitem>Last Bullet</guimenuitem></menuchoice></term>
		<listitem><para>Jump to the previous bullet in the text if there is one.</para></listitem>
		</varlistentry>
		
		</variablelist>
		
	</sect1>
	
	<sect1 id="editing_select">

		<title>Select</title>
	
		<para>Editing is of course one of the main aspects when you use a program like &kile;. 
		Although &kate; already has great capabilities, &kile; adds some important features, 
		which are especially needed to write &latex; source. &latex; always needs a lot of 
		environments and groups, so &kile; supports very special commands to select them. 
		Under <menuchoice><guimenu>Edit</guimenu><guisubmenu>Select</guisubmenu></menuchoice> 
		you will find the following commands to select text.</para> 

		<screenshot>
			<screeninfo>Edit->Select items</screeninfo>
			<mediaobject>
			<imageobject>
			<imagedata fileref="select.png" format="PNG" />
			</imageobject>
			<textobject>
				<phrase>Edit->Select items</phrase>
			</textobject>
			</mediaobject>
		</screenshot>
		
		<variablelist>
		<varlistentry><term><menuchoice>
		<shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>S</keycap></keycombo>
		<keycap>E</keycap></shortcut>
		<guimenuitem>Environment (inside)</guimenuitem></menuchoice></term>
		<listitem><para>Select an environment 
		without the surrounding tags.</para></listitem>
		</varlistentry>
		
		<varlistentry><term><menuchoice>
		<shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>S</keycap></keycombo>
		<keycap>F</keycap></shortcut>
		<guimenuitem>Environment (outside)</guimenuitem></menuchoice></term>
		<listitem><para>Select an environment 
		including the surrounding tags.</para></listitem>
		</varlistentry>
		
		<varlistentry><term><menuchoice>
		<shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>S</keycap></keycombo>
		<keycap>T</keycap></shortcut>
		<guimenuitem>TeX Group (inside)</guimenuitem></menuchoice></term>
		<listitem><para>Select a TeX group 
		inside the surrounding braces.</para></listitem>
		</varlistentry>
				
		<varlistentry><term><menuchoice>
		<shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>S</keycap></keycombo>
		<keycap>U</keycap></shortcut>
		<guimenuitem>TeX Group (outside)</guimenuitem></menuchoice></term>
		<listitem><para>Select a TeX group 
		including the surrounding braces.</para></listitem>
		</varlistentry>
		
		<varlistentry><term><menuchoice>
					<shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>S</keycap></keycombo>
						<keycap>M</keycap></shortcut>
					<guimenuitem>Math Group</guimenuitem></menuchoice></term>
			<listitem><para>Select the current math group including the math commands.</para></listitem>
		</varlistentry>
		
		<varlistentry><term><menuchoice>
		<shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>S</keycap></keycombo>
		<keycap>P</keycap></shortcut>
		<guimenuitem>Paragraph</guimenuitem></menuchoice></term>
		<listitem><para>Select a whole paragraph, 
		&ie; a group of text lines separated on both sides by empty lines.
		A paragraph does not mean just continuous lines of text, as it is
		in other text editors. This extended meaning also includes tables, &latex; 
		commands and all other lines of source. The only important thing for &kile;
		is that kind of paragraph is separated by two empty lines.</para></listitem>
		</varlistentry>

		<varlistentry><term><menuchoice>
		<shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>S</keycap></keycombo>
		<keycap>L</keycap></shortcut>
		<guimenuitem>Line</guimenuitem></menuchoice></term>
		<listitem><para>Select the text line of the 
		current cursor position.</para></listitem>
		</varlistentry>
		
		<varlistentry><term><menuchoice>
		<shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>S</keycap></keycombo>
		<keycap>W</keycap></shortcut>
		<guimenuitem>TeX Word</guimenuitem></menuchoice></term>
		<listitem><para>Select the word under 
		the current cursor position. This selection has also en extended meaning, 
		because this command can also select &latex; commands, which begin with a 
		backslash and may also have an optional star at the 
		end.</para></listitem>
		</varlistentry>

		</variablelist>
		
	</sect1>

	<sect1 id="editing_delete">

		<title>Delete</title>
	
		<para>To delete some parts of a document you can of course select them, and then 
		use the <keycombo><keycap>Delete</keycap></keycombo> key. Kate also offers the command
		<keycombo>&Ctrl;<keycap>K</keycap></keycombo> which deletes the hole line.But &kile; offers a 
		faster way with its own delete commands.
		Under <menuchoice><guimenu>Edit</guimenu><guisubmenu>Delete</guisubmenu></menuchoice> 
		you will find following commands to delete text.</para> 

		<screenshot>
			<screeninfo>Edit->Delete items</screeninfo>
			<mediaobject>
			<imageobject>
			<imagedata fileref="delete.png" format="PNG" />
			</imageobject>
			<textobject>
				<phrase>Edit->Delete items</phrase>
			</textobject>
			</mediaobject>
		</screenshot>
		
		<variablelist>
		<varlistentry><term><menuchoice>
		<shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>T</keycap></keycombo>
		<keycap>E</keycap></shortcut>
		<guimenuitem>Environment (inside)</guimenuitem></menuchoice></term>
		<listitem><para>Delete an environment without the surrounding tags.</para></listitem>
		</varlistentry>

		<varlistentry><term><menuchoice>
		<shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>T</keycap></keycombo>
		<keycap>F</keycap></shortcut>
		<guimenuitem>Environment (outside)</guimenuitem></menuchoice></term>
		<listitem><para>Delete an environment including the surrounding tags.</para></listitem>
		</varlistentry>

		<varlistentry><term><menuchoice>
		<shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>T</keycap></keycombo>
		<keycap>T</keycap></shortcut>
		<guimenuitem>TeX Group (inside)</guimenuitem></menuchoice></term>
		<listitem><para>Delete a TeX group inside the surrounding braces.</para></listitem>
		</varlistentry>

		<varlistentry><term><menuchoice>
		<shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>T</keycap></keycombo>
		<keycap>U</keycap></shortcut>
		<guimenuitem>TeX Group (outside)</guimenuitem></menuchoice></term>
		<listitem><para>Delete a TeX group including the surrounding braces.</para></listitem>
		</varlistentry>
		
		<varlistentry><term><menuchoice>
					<shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>T</keycap></keycombo>
						<keycap>M</keycap></shortcut>
					<guimenuitem>Math Group</guimenuitem></menuchoice></term>
			<listitem><para>Delete the current math group including the math commands.</para></listitem>
		</varlistentry>

		<varlistentry><term><menuchoice>
		<shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>T</keycap></keycombo>
		<keycap>P</keycap></shortcut>
		<guimenuitem>Paragraph</guimenuitem></menuchoice></term>
		<listitem><para>Delete a whole paragraph. Look at the 
		<menuchoice><guisubmenu>Select</guisubmenu><guimenuitem>Paragraph</guimenuitem></menuchoice>
		command, how a paragraph is 
		defined in &kile;.</para></listitem>
		</varlistentry>
		
		
		<varlistentry><term><menuchoice>
					<shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>T</keycap></keycombo>
						<keycap>I</keycap></shortcut>
					<guimenuitem>To End of Line</guimenuitem></menuchoice></term>
			<listitem><para>Delete the text from the current cursor position to the end of the line.
				</para></listitem>
		</varlistentry>

		<varlistentry><term><menuchoice>
		<shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>T</keycap></keycombo>
		<keycap>W</keycap></shortcut>
		<guimenuitem>TeX Word</guimenuitem></menuchoice></term>
		<listitem><para>Delete the word or &latex;
		 command under the current cursor position.</para></listitem>
		</varlistentry>
		
		</variablelist>

	</sect1>

	<sect1 id="editing_environment">

		<title>Environment</title>
	
		<para>It was already mentioned that environments are a central point in &latex;.
		So &kile; offers five other commands to make the work with &latex; as easy as possible 
		under submenus <menuchoice><guimenu>Edit</guimenu><guisubmenu>Environment</guisubmenu></menuchoice>.</para>

		<screenshot>
			<screeninfo>Edit->Environment items</screeninfo>
			<mediaobject>
			<imageobject>
			<imagedata fileref="environment.png" format="PNG" />
			</imageobject>
			<textobject>
				<phrase>Edit->Environment items</phrase>
			</textobject>
			</mediaobject>
		</screenshot>
		
		<variablelist>
		
		<varlistentry><term><menuchoice>
		<shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>E</keycap></keycombo>
		<keycap>B</keycap></shortcut>
		<guimenuitem>Go to Begin</guimenuitem></menuchoice></term>
		<listitem><para>This command will jump to the beginning of the current environment, 
		wherever your current position is. The cursor will be placed directly 
		in front of the opening environment tag.</para></listitem>
		</varlistentry>
		
		<varlistentry><term><menuchoice>
		<shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>E</keycap></keycombo>
		<keycap>E</keycap></shortcut>
		<guimenuitem>Go to End</guimenuitem></menuchoice></term>
		<listitem><para>This command will jump to the end of the current environment, 
		wherever your current position is. The cursor will be placed directly 
		behind the closing environment tag.</para></listitem>
		</varlistentry>

		<varlistentry><term><menuchoice>
		<shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>E</keycap></keycombo>
		<keycap>M</keycap></shortcut>
		<guimenuitem>Match</guimenuitem></menuchoice></term>
		<listitem><para>When your cursor is placed in front of or above the 
		<userinput>\begin{environment}</userinput> tag, it will be moved to the 
		opposite end of the environment and vice versa.</para></listitem>
		</varlistentry>

		<varlistentry><term><menuchoice>
		<shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>E</keycap></keycombo>
		<keycap>C</keycap></shortcut>
		<guimenuitem>Close</guimenuitem></menuchoice></term>
		<listitem><para>Typing a lot of nested environment tags, you may lose 
		control of all those environments. This command will close the last 
		opened environment, so that the nested structure of environments 
		will not be broken.</para></listitem>
		</varlistentry>

		<varlistentry><term><menuchoice>
					<shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>E</keycap></keycombo>
						<keycap>A</keycap></shortcut>
					<guimenuitem>Close All</guimenuitem></menuchoice></term>
			<listitem><para>This closes all open environments, not only the last opened environment.</para></listitem>
		</varlistentry>

		</variablelist>
		
	</sect1>
	
	<sect1 id="editing_texgroup">

		<title>&tex; Group</title>
		
		<para>&kile; also offers some special commands for &latex; groups;, 
		which are determined by braces <userinput>{...}</userinput>. In submenu 
		<menuchoice><guimenu>Edit</guimenu><guisubmenu>TeX Group</guisubmenu></menuchoice>
		you will find some important commands, which correspond to those from
		<menuchoice><guimenu>Edit</guimenu><guisubmenu>Environment</guisubmenu></menuchoice>.
		</para>
		
		<screenshot>
			<screeninfo>Edit->TeX Group</screeninfo>
			<mediaobject>
			<imageobject>
			<imagedata fileref="texgroup.png" format="PNG" />
			</imageobject>
			<textobject>
				<phrase>Edit->TeX Group</phrase>
			</textobject>
			</mediaobject>
		</screenshot>
		
		<variablelist>
		<varlistentry><term><menuchoice>
		<shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>G</keycap></keycombo>
		<keycap>B</keycap></shortcut>
		<guimenuitem>Go to Begin</guimenuitem></menuchoice></term>
		<listitem><para>This command will jump to the beginning of the current group, 
		wherever your current position is. The cursor will be placed directly in front 
		of the opening brace.</para></listitem>
		</varlistentry>

		<varlistentry><term><menuchoice>
		<shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>G</keycap></keycombo>
		<keycap>E</keycap></shortcut>
		<guimenuitem>Go to End</guimenuitem></menuchoice></term>
		<listitem><para>This command will jump to the end of the current group, 
		wherever your current position is. The cursor will be placed directly 
		behind the closing brace.</para></listitem>
		</varlistentry>

		<varlistentry><term><menuchoice>
		<shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>G</keycap></keycombo>
		<keycap>M</keycap></shortcut>
		<guimenuitem>Match</guimenuitem></menuchoice></term>
		<listitem><para>When your cursor is placed in front of or behind an 
		opening brace of a &tex; group, he will be moved to the opposite end of 
		the group and vice versa.</para></listitem>
		</varlistentry>

		<varlistentry><term><menuchoice>
		<shortcut><keycombo action="simul">&Ctrl;&Alt;<keycap>G</keycap></keycombo>
		<keycap>C</keycap></shortcut>
		<guimenuitem>Close</guimenuitem></menuchoice></term>
		<listitem><para>Typing a lot of nested group braces may be hard work. 
		This command will close the last opened group, so that the nested 
		structure of &tex; groups will not be broken.</para></listitem>
		</varlistentry>
		
		</variablelist>
		
	</sect1>

	<sect1 id="editing_dblquotes">

		<title>Double Quotes</title>

		<para>In &latex;, two single quotes are used as double quotes. To  
		help you insert these efficiently, &kile; allows you to press 
		<keycap>"</keycap> to insert two opening 
		single quotes. Furthermore, if you want to close a quotation, you also 
		have to press <keycap>"</keycap>. &kile; will 
		be smart enough to recognize this case and inserts two closing quotes 
		for &latex;.</para>

		<para>To get a literal double quote on the other side, press 
		<keycap>"</keycap> twice.</para>

		<para>You can enable or disable this auto insertion of opening and 
		closing double quotes in section 
		<menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure
		Kile...</guisubmenu><guimenuitem>LaTeX</guimenuitem></menuchoice>.</para>

		<screenshot>
			<screeninfo>Double Quotes</screeninfo>
			<mediaobject>
			<imageobject>
			<imagedata fileref="config-dblquotes.png" format="PNG" />
			</imageobject>
			<textobject>
			<phrase>Double Quotes</phrase>
			</textobject>
			</mediaobject>
		</screenshot>

		<para>If you also include language-specific options 
		like <userinput>ngerman</userinput> or <userinput>french</userinput>, 
		you will also be able to use German or French double quotes. Many more languages are available.
    </para>

	</sect1>

	<sect1 id="editing_smartnewline">

		<title>Smart Newline</title>

		<para>If you press <keycombo>&Shift;<keycap>Return</keycap></keycombo>, 
		&kile; inserts an intelligent newline. If your current position 
		is inside a list environment, like <userinput>enumerate</userinput> 
		or <userinput>itemize</userinput>, &kile; will not only insert 
		a newline, but also add a <userinput>\item</userinput> command.</para>

		<para>If you are inside a tabular environment, &kile; will finish the 
		current line with <userinput>\\</userinput>, followed by the newline.</para>
  
    <para>If you are inside a &latex; comment, &kile; will start the next line with a
    <userinput>%</userinput>.</para>

		<para>Even better, &kile; is smart enough to support predefined &latex;
		and user defined environment, which can be added in section 
		<menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure
		Kile...</guisubmenu><guimenuitem>LaTeX</guimenuitem></menuchoice>.</para>

	</sect1>

	<sect1 id="editing_tabulator">

		<title>Smart Tabulator</title>

		<para>Some users like to arrange columns in tabular environments and
		put all ampersand characters <keycap>&amp;</keycap> beneath each other. &kile; tries
		to support this. If you press <keycombo>&Shift;&Alt;<keycap>&amp;</keycap></keycombo>, 
		&kile; will look for the next tab in the row above. Although his which may not the  
		corresponding tab, &kile; will add some spaces to adjust the column position with 
		the current tab.</para>

	</sect1>

</chapter>

<chapter id="completion">

	<title>Code Completion</title>
	
	<para>Although &kate; already offers a good completion mode, &kile; extended 
	code completion to support some special methods especially for &latex;. Five different 
	modes are integrated. Three of them work on demand, the other two are autocompletion 
	modes. All modes can be configured to work very differently at 
	<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure Kile...</guimenuitem></menuchoice>.</para>

	<sect1 id="complete_autoenvironment">

		<title>Automatic Environment Completion</title>

		<para>When you begin a new environment, typing <userinput>\begin{environment}</userinput>,
		&kile; will automatically add an <userinput>\end{environment}</userinput> command, with a 
		line in between for your text.</para>

		<para>Autocompletion can be turned off in the &latex; section of
		<menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure Kile...</guisubmenu>
		<guimenuitem>LaTeX</guimenuitem><guilabel>Environments</guilabel></menuchoice>.</para>

		<screenshot>
			<screeninfo>Completing an Equation Environment</screeninfo>
			<mediaobject>
			<imageobject>
			<imagedata fileref="snap_autocomplete.png" format="PNG" />
			</imageobject>
			<textobject>
			<phrase>Completing an Equation Environment</phrase>
			</textobject>
			<caption><para>Completing an Equation Environment</para></caption>
			</mediaobject>
		</screenshot>

	</sect1>
	
	<sect1 id="complete_command">
	
		<title>&latex; Commands</title>

		<para>When you type some letters, you can activate this completion mode for &latex; commands 
		and normal words with <menuchoice><guimenu>Edit</guimenu><guisubmenu>Complete</guisubmenu><guimenuitem>(La)TeX Command</guimenuitem></menuchoice> or the keyboard shortcut 
		<keycombo>&Ctrl;<keycap>Space</keycap></keycombo>. 
		&kile; first reads the letters from the current cursor position to the 
		left and stops at the first non-letter character or a backslash. If this 
		pattern begins with a backslash, &kile; will enter completion mode for &tex; or &latex; 
		commands. Otherwise it enters normal dictionary mode, where you will not find any 
		&latex; commands. Depending on the chosen mode, a completion box will be opened. 
		You will see all commands or words whose beginning matches the current pattern. 
		You can navigate with the cursor keys through this list and select one entry with 
		&Enter; or a double click with the mouse.</para>

		<screenshot>
			<screeninfo>Completing a LaTeX Command</screeninfo>
			<mediaobject>
			<imageobject>
			<imagedata fileref="complete_cmd1.png" format="PNG" />
			</imageobject>
			<textobject>
			<phrase>Completing a LaTeX Command</phrase>
			</textobject>
			</mediaobject>
		</screenshot>
		
		<para>When you push the &Backspace; key, the last letter of your 
		pattern will be deleted, and the completion list may grow. On the other hand, if 
		you type another letter will expand the pattern and the 
		visible word list may shrink.</para>

		<para>If you decide not to select any of the suggestions, you can leave this 
		dialog with &Esc;.</para>

		<para>You will see that all commands are written with a short description of 
		their parameters. These descriptions are of course stripped when you select a command. 
		Optionally you can let &kile; insert bullets at these places, so that you can easily 
		jump to the these positions with <menuchoice><guimenu>Edit</guimenu><guisubmenu>Bullets</guisubmenu><guimenuitem>Next Bullet</guimenuitem></menuchoice> 
		and insert the parameter you want.</para>

		<screenshot>
			<screeninfo>Completing a LaTeX Command</screeninfo>
			<mediaobject>
			<imageobject>
			<imagedata fileref="complete_cmd2.png" format="PNG" />
			</imageobject>
			<textobject>
			<phrase>Completing a LaTeX Command</phrase>
			</textobject>
			</mediaobject>
		</screenshot>
		
		<para>Go to 
		<menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure Kile...</guisubmenu>
		<guimenuitem>Kile</guimenuitem><guilabel>Complete</guilabel></menuchoice>
		to configure one or more of these lists. You can choose different word lists 
		for &tex; and &latex; commands and dictionary mode for normal words.</para> 
		
	</sect1>

	<sect1 id="complete_environment">

		<title>Environments</title>
		
		<para>The <emphasis>command mode</emphasis> is not useful to complete environments. 
		You always have to type some letters of <userinput>\begin</userinput>, and invoking 
		the completion mode will result in a huge list of environments tags. On the other 
		hand, environments are so often used that &kile; offers a special mode to complete 
		environments. Forget the opening tag and write, for example, <userinput>eq</userinput>.</para> 

		<para>When you call the completion mode with 
		<menuchoice><guimenu>Edit</guimenu><guisubmenu>Complete</guisubmenu><guimenuitem>Environment</guimenuitem></menuchoice> or keyboard shortcut <keycombo>&Alt;<keycap>Space</keycap></keycombo>,
		the opening tag is automatically added and you will see <userinput>\begin{eq}</userinput>. 
		After this change, the completion list is much less cluttered.</para>

		<screenshot>
			<screeninfo>Completing a LaTeX Command</screeninfo>
			<mediaobject>
			<imageobject>
			<imagedata fileref="complete_env1.png" format="PNG" />
			</imageobject>
			<textobject>
			<phrase>Completing a LaTeX Command</phrase>
			</textobject>
			</mediaobject>
		</screenshot>

		<para>Now select an environment, and you will see that it is also automatically closed. 
		Even more, if &kile; recognizes it as a list environment, it will also insert a first 
		<userinput>\item</userinput> tag.</para>
		
		<screenshot>
			<screeninfo>Completing a LaTeX Command</screeninfo>
			<mediaobject>
			<imageobject>
			<imagedata fileref="complete_env2.png" format="PNG" />
			</imageobject>
			<textobject>
			<phrase>Completing a LaTeX Command</phrase>
			</textobject>
			</mediaobject>
		</screenshot>
		
		<para>Go to 
		<menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure Kile...</guisubmenu>
		<guimenuitem>Kile</guimenuitem><guilabel>Complete</guilabel></menuchoice>
		to configure one or more of these lists. This mode uses the same word lists as the 
		completion mode for &tex; and &latex; commands.</para> 

	</sect1>
	
	<sect1 id="complete_abbreviation">

		<title>Abbreviations</title>

		<para>&kile; supports user defined lists of abbreviations, which are replaced 
		on demand by longer text strings. Look at 
		<menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure Kile...</guisubmenu>
		<guimenuitem>Kile</guimenuitem><guilabel>Complete</guilabel></menuchoice>
		to configure one or more of theses lists. For the example given here, the 
		abbreviation list in <filename>example.cwl</filename> must be chosen. 
		In this file you will find for example the entry <userinput>L=\LaTeX</userinput> for example.</para>

		<para>For example, type only the letter <userinput>L</userinput>. Now invoke 
		the abbreviation mode of word completion with 
		<menuchoice><guimenu>Edit</guimenu><guisubmenu>Complete</guisubmenu><guimenuitem>Abbreviation</guimenuitem></menuchoice> or keyboard shortcut <keycombo>&Ctrl;&Alt;<keycap>Space</keycap></keycombo>,
		and the letter <userinput>L</userinput> is replaced by the string 
		<userinput>\LaTeX</userinput>.</para>

	</sect1>
	
	<sect1 id="complete_auto">

		<title>Autocompletion Modes</title>

		<sect2 id="complete_autolatex">

			<title>&latex; Commands</title>

			<para>You can also enable an autocompletion mode for &latex; commands. 
			When a given threshold of letters (default: 3) is entered, a popup window opens 
			with a list of all matching &latex; commands. You can select one of these commands, 
			or ignore this window and type further letters. The entries of the completion box 
			will always change and match your currently typed word.</para>

			<para>Go to 
			<menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure Kile...</guisubmenu>
			<guimenuitem>Kile</guimenuitem><guilabel>Complete</guilabel></menuchoice>
			to enable or disable this mode or to change the threshold.</para>
			
		<screenshot>
			<screeninfo>Completing an Equation Environment</screeninfo>
			<mediaobject>
			<imageobject>
			<imagedata fileref="config-complete.png" format="PNG" />
			</imageobject>
			<textobject>
			<phrase>Completing an Equation Environment</phrase>
			</textobject>
			</mediaobject>
		</screenshot>
		
		</sect2>
		
		<sect2 id="complete_autotext">

			<title>Document Words</title>

			<para>Large dictionaries are not useful in autocompletion mode. But, we have seen 
			that a lot of words in a document are typed more than once. So &kile; offers a 
			completion for all words from the document that the user has already typed before.</para>

			<para>If you want to turn this mode on or off, go to
			<menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure Kile...</guisubmenu>
			<guimenuitem>Kile</guimenuitem><guilabel>Complete</guilabel></menuchoice>.
			In this configuration dialog you can also change the threshold at which 
			the completion box pops up.</para>
	
		</sect2>	

	</sect1>
	
	<sect1 id="complete_own_files">

		<title>Writing Own Completion Files</title>

    <para>The specification of the completion file format can found in the <ulink url="http://websvn.kde.org/*checkout*/tags/kile/2.0/src/README.cwl">
		CWL file format specification</ulink>.
		</para>

		<para>
		Completion files can be installed in a user's home directory under the <filename>~/.kde/share/apps/kile/complete/&lt;mode&gt;/</filename>
		subdirectory, where <parameter>&lt;mode&gt;</parameter> either stands for <constant>abbreviation</constant>, <constant>dictionary</constant> or	<constant>tex</constant>.
		</para>

	</sect1>
</chapter>

<chapter id="wizard">

	<title>Wizards and Dialogs</title>

	<sect1 id="wizard_graphics">

		<title>Include Graphics</title>

		<para>The <guilabel>Include Graphics</guilabel> dialog makes insertion of
		graphics as easy as possible. Please take a look at 
		<xref linkend="build_graphics"/> and <xref linkend="build_epsgraphics"/> to
		get an overview of some basic facts concerning graphic formats.</para>

		<screenshot>
			<screeninfo>Including a graphics element</screeninfo>
			<mediaobject>
			<imageobject>
			<imagedata fileref="includegraphics.png" format="PNG" />
			</imageobject>
			<textobject>
			<phrase>Including a graphics element</phrase>
			</textobject>
			</mediaobject>
		</screenshot>

		<procedure>
		<step><para>Choose a graphics file. This can be a JPEG, PNG, EPS 
		or even a zipped or gzipped EPS file. If you have installed 
		<ulink url="http://www.imagemagick.org/">&imagemagick;</ulink>
		and also configured &kile; to use it 
		(<menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure Kile...</guisubmenu>
		<guimenuitem>LaTeX</guimenuitem><guilabel>General</guilabel></menuchoice>), 
		the width and the height of the graphic is automatically shown. 
		If &imagemagick; can determine a resolution, the size of the graphics 
		is also shown in centimeters.</para></step>

		<step><para>Decide whether your image shall be centered on the page.</para></step>

		<step><para>Choose either traditional &latex; or &pdflatex;. 
		Please remember that &pdflatex; can also create DVI output, 
		not only PDF.</para></step>

		<step><para>You can choose whether the filename should be taken 
		relative. This is the preferred way, when you use the
		<userinput>\graphicspath</userinput> command.</para>

		<para>By default graphics files have to be in the same 
		folder than your master document. However 
		it is possible to put them in other folders to make 
		things tidier. Without a <userinput>\graphicspath</userinput> 
		command, &kile; would include the path for the graphics file. 
		But if you use <userinput>\graphicspath</userinput>,
		like:</para>

<programlisting>
	\graphicspath{{/path/to/my/graphics}{other/path/to/more/graphics}} 
</programlisting>

		<para>and check this option, &kile; with only use the 
		base name of the graphics file.</para>

		<para>Another example: if you set <userinput>\graphicspath</userinput> 
		command like:</para>

<programlisting>
	\graphicspath{{./}{camera/}{images/}}
</programlisting>

		<para>&latex; will search in the current folder, then in 
		<filename>camera</filename> and finally in 
		<filename>images</filename> to find your graphics file.</para></step>

		<step><para>If you choose either a width or a height, the whole graphics 
		will be proportionally scaled. If you set two values for width and height 
		at the same time, width and height may be scaled with different factors,
		and this could not be what you want. See also the information near the top 
		of dialog to know the original size of the graphics.</para></step>

		<step><para>Insert an angle by which to rotate the graphics counterclockwise.</para></step>

		<step><para>The bounding-box information is set automatically 
		when you choose a graphics file. This information is only needed 
		when you work with traditional &latex; and bitmapped graphics. 
		See the discussion of <link linkend="build_epsgraphics">EPS graphics</link>. 
		</para></step> 

		<step><para>Your last choice is whether to embed this graphics into a 
		figure environment. If you decide to do so, you can also insert a 
		caption and a label. It is a good idea to add a different prefix to 
		each kind of label. It is common to use the prefix 
		<userinput>fig:</userinput> for images.</para></step> 
		</procedure>
		
	</sect1>
	
	<sect1 id="wizard_array">

		<title>Array Wizard</title>

		<para>One of the most boring jobs one can do in &latex; is to write a matrix or a 
		tabular environment. One has to keep track of all the elements, ensure that the environment
		is well formed, and that all things are where they are supposed to be. Good indentation helps, 
		but there is a simpler way: using &kile;'s <guimenu>Wizard</guimenu> menu. It contains
		<guimenuitem>Tabular</guimenuitem> and <guimenuitem>Array</guimenuitem> (used in math environments).
		You will then have a matrix-formed input form that you can easily fill in with your entries. This dialog also 
		offers some options to typeset the tabular material.</para>

		<screenshot>
			<screeninfo>Inserting a tabular environment</screeninfo>
			<mediaobject>
			<imageobject>
			<imagedata fileref="dialog-tabular.png" format="PNG" />
			</imageobject>
			<textobject>
			<phrase>Inserting a tabular environment</phrase>
			</textobject>
			</mediaobject>
		</screenshot>

		<para>The <guimenuitem>Tabbing</guimenuitem> option will display a simpler menu 
		to set up a tabbing environment. In all these environments, you can easily set the
		number of rows and columns, along with other specific options.</para>
	</sect1>

	<sect1 id="wizard_postscript">

		<title>&postscript; Utilities</title>

		<para>PS files are not so popular as PDF files, but are an excellent base 
		for manipulations and rearrangements of pages. If you need PDF
		output, you can rearrange pages with some &postscript; utilities and then 
		convert it to PDF with <command>ps2pdf</command>.</para>
		
		<para>The <emphasis>&postscript; Wizard</emphasis> will suggest the most 
		popular rearrangements, but you are free to do your own choice. Work is done 
		by the programs <command>pstops</command> and <command>psselect</command>, which
		you will find in most distributions in the package <userinput>psutils</userinput>.
		If one of these programs is not available, the corresponding item will not 
		be visible.</para>
		
		<screenshot>
			<screeninfo>Dialog PSTools</screeninfo>
			<mediaobject>
			<imageobject>
			<imagedata fileref="dialog-pstools.png" format="PNG" />
			</imageobject>
			<textobject>
				<phrase>Dialog PSTools</phrase>
			</textobject>
			</mediaobject>
		</screenshot>

		<para>First choose your input file. If &kile; finds a PS file corresponding to your 
		current master document, it is already filled in as input file, but you are also free 
		to choose another file. Then choose an output file, and select one of the tasks. 
		Finally, you have to decide whether you want to do the conversion only, or also invoke
		&kghostview; to view the result.</para>
		
		<variablelist>
		
		<varlistentry>
		<term>1 A5 page + empty page --> A4</term>
		<listitem><para>Combine one A5 page together with one empty page 
		on one A4 page. Whenever two A5 pages are combined together, 
		they are rotated 90 degrees and will be arranged 
		on an A4 page in landscape mode.</para>
		<screenshot>
			<screeninfo>A5 + empty page</screeninfo>
			<mediaobject>
			<imageobject>
			<imagedata fileref="psutils1.png" format="PNG" />
			</imageobject>
			<textobject>
			<phrase>A5 + empty page</phrase>
			</textobject>
			</mediaobject>
		</screenshot>
		</listitem>
		</varlistentry>
	
		<varlistentry>
		<term>1 A5 page + duplicate --> A4</term>
		<listitem><para>Put one A5 page and a duplicate together
		on one A4 page.</para>
		<screenshot>
			<screeninfo>duplicate A5 pages</screeninfo>
			<mediaobject>
			<imageobject>
			<imagedata fileref="psutils2.png" format="PNG" />
			</imageobject>
			<textobject>
			<phrase>Duplicate an A5 page</phrase>
			</textobject>
			</mediaobject>
		</screenshot>
		</listitem>
		</varlistentry>
		
		<varlistentry>
		<term>2 A5 pages --> A4</term>
		<listitem><para>Put two consecutive A5 pages together
		on one A4 page.</para>
		<screenshot>
			<screeninfo>Combine two A5 pages</screeninfo>
			<mediaobject>
			<imageobject>
			<imagedata fileref="psutils3.png" format="PNG" />
			</imageobject>
			<textobject>
			<phrase>Combine two A5 pages</phrase>
			</textobject>
			</mediaobject>
		</screenshot>
		</listitem>
		</varlistentry>
		
		<varlistentry>
		<term>2 A5L pages --> A4</term>
		<listitem><para>Put two consecutive A5 pages in landscape mode together
		on one A4 page.</para></listitem>
		</varlistentry>
		
		<varlistentry>
		<term>4 A5 pages --> A4</term>
		<listitem><para>Combine four consecutive A5 pages together on one 
		A4 page. The A5 pages have to be scaled with factor 0.7 to fit 
		on the page.</para>
		<screenshot>
			<screeninfo>4 A5 pages --> A4</screeninfo>
			<mediaobject>
			<imageobject>
			<imagedata fileref="psutils5.png" format="PNG" />
			</imageobject>
			<textobject>
			<phrase>4 A5 pages --> A4</phrase>
			</textobject>
			</mediaobject>
		</screenshot>
		</listitem>
		</varlistentry>
		
		<varlistentry>
		<term>1 A4 page + empty page --> A4</term>
		<listitem><para>Combine one A4 page together with one empty page 
		on one A4 page. Whenever two A4 pages are combined together on one 
		resulting A4 page, they have to be scaled with factor 0.7 and will 
		be arranged in portrait mode.</para>
		<screenshot>
			<screeninfo>1 A4 page + empty page --> A4</screeninfo>
			<mediaobject>
			<imageobject>
			<imagedata fileref="psutils6.png" format="PNG" />
			</imageobject>
			<textobject>
			<phrase>1 A4 page + empty page --> A4</phrase>
			</textobject>
			</mediaobject>
		</screenshot>
		</listitem>
		</varlistentry>
		
		<varlistentry>
		<term>1 A4 page + duplicate --> A4</term>
		<listitem><para>Put one A4 page and a duplicate together
		on one A4 page.</para>
		<screenshot>
			<screeninfo>1 A4 page + duplicate --> A4</screeninfo>
			<mediaobject>
			<imageobject>
			<imagedata fileref="psutils7.png" format="PNG" />
			</imageobject>
			<textobject>
			<phrase>1 A4 page + duplicate --> A4</phrase>
			</textobject>
			</mediaobject>
		</screenshot>
		</listitem>
		</varlistentry>
		
		<varlistentry>
		<term>2 A4 pages --> A4</term>
		<listitem><para>Put two consecutive A4 pages together
		on one A4 page.</para>
		<screenshot>
			<screeninfo>Combine two A4 pages</screeninfo>
			<mediaobject>
			<imageobject>
			<imagedata fileref="psutils8.png" format="PNG" />
			</imageobject>
			<textobject>
			<phrase>Combine two A4 pages</phrase>
			</textobject>
			</mediaobject>
		</screenshot>
		</listitem>
		</varlistentry>
			
		<varlistentry>
		<term>2 A4L pages --> A4</term>
		<listitem><para>Put two consecutive A4 pages in landscape mode together
		on one A4 page.</para></listitem>
		</varlistentry>
			
		<varlistentry>
		<term>select even pages</term>
		<listitem><para>Select all even pages of a document.</para></listitem>
		</varlistentry>
			
		<varlistentry>
		<term>select odd pages</term>
		<listitem><para>Select all odd pages of a document.</para></listitem>
		</varlistentry>
			
		<varlistentry>
		<term>select even pages (reverse order)</term>
		<listitem><para>Select all even pages of a document and reverse the order.</para></listitem>
		</varlistentry>
			
		<varlistentry>
		<term>select odd pages (reverse order)</term>
		<listitem><para>Select all even pages of a document and reverse the order.</para></listitem>
		</varlistentry>
			
		<varlistentry>
		<term>reverse all pages</term>
		<listitem><para>Reverse all pages of a document.</para></listitem>
		</varlistentry>
			
		<varlistentry>
		<term>copy all pages (sorted)</term>
		<listitem><para>Copy all pages of a document. You have to
		choose the number of sorted copies.</para>
		<screenshot>
			<screeninfo>Copy all pages (sorted)</screeninfo>
			<mediaobject>
			<imageobject>
			<imagedata fileref="psutils15.png" format="PNG" />
			</imageobject>
			<textobject>
			<phrase>Copy all pages (sorted)</phrase>
			</textobject>
			</mediaobject>
		</screenshot>
		</listitem>
		</varlistentry>
			
		<varlistentry>
		<term>copy all pages (unsorted)</term>
		<listitem><para>Copy all pages of a document. You have to
		choose the number of non-sorted copies.</para>
		<screenshot>
			<screeninfo>Copy all pages (unsorted)</screeninfo>
			<mediaobject>
			<imageobject>
			<imagedata fileref="psutils16.png" format="PNG" />
			</imageobject>
			<textobject>
			<phrase>Copy all pages (unsorted)</phrase>
			</textobject>
			</mediaobject>
		</screenshot>
		</listitem>
		</varlistentry>
			
		<varlistentry>
		<term>pstops: choose parameter</term>
		<listitem><para>There are many options for &postscript; utilities 
		<command>pstops</command> and <command>psselect</command>. If you 
		need a very special one, you can invoke <command>pstops</command> with 
		an option of your choice. Please read the manual for all possible
		options.</para></listitem>
		</varlistentry>
			
		<varlistentry>
		<term>psselect: choose parameter</term>
		<listitem><para>You can invoke <command>psselect</command> with 
		an option of your choice. Please read the manual for all possible
		options.</para></listitem>
		</varlistentry>
		
		</variablelist>
		
	</sect1>

	<sect1 id="statistics">	
		<title>Document Statistics</title>
		
		<para>The statistics dialog gives you an statistical overview for a selection,
		a document or an hole project. It includes the number of words, &latex; 
		commands/environments and also includes the number of characters for each type.
		The statistical numbers can be copied as text or as a nice formatted &latex; tabular
		to the clipboard. If you want to get statistics for the hole project you can use 
		<menuchoice><guimenu>File</guimenu><guisubmenu>Open All Project Files</guisubmenu></menuchoice>
    for an easy and quick way to open all source files of your project.</para>
		<para>A note of caution has to be sounded about the accuracy of the numbers.
		We have included some logic to get a good estimate, e. g. K\"uhler gives one word and one command,
		with six resp. two characters. But there are other combinations in which parts of commands
		are counted as words and vice versa. It has also to be beared in mind that the algorithm
		was developed and tested for languages similiar to english or german.
		So don't take the numbers for granted. If you have to make an report with an
		exact numbers of words or characters, make some tests to check whether &kile;'s accuracy satisfies your needs.</para>
	</sect1>

</chapter>

<chapter id="latex">

	<title>Special Tags in &latex;</title>

	<sect1 id="latex_library">
		<title>Using the &latex; Tag Library</title>

		<para>&latex; has thousands of tags for symbols and special characters.
		The easiest way to insert these tags is to use the sidebar menu, 
		left of the editor window.</para>

		<screenshot>
			<screeninfo>The Sidebar Menu</screeninfo>
			<mediaobject>
			<imageobject>
			<imagedata fileref="snap_sidebarmenu.png" format="PNG" />
			</imageobject>
			<textobject>
			<phrase>The Sidebar Menu</phrase>
			</textobject>
			<caption><para>The Sidebar Menu</para></caption>
			</mediaobject>
		</screenshot>
		<para>The following types are avaible:</para>

		<itemizedlist>
			<listitem><para>Most Frequently Used</para></listitem>
			<listitem><para>Relation</para></listitem>
			<listitem><para>Operators</para></listitem>
			<listitem><para>Arrows</para></listitem>
			<listitem><para>Miscellaneous Math</para></listitem>
			<listitem><para>Miscellaneous Text</para></listitem>
			<listitem><para>Delimiters</para></listitem>
			<listitem><para>Greek</para></listitem>
			<listitem><para>Special Characters</para></listitem>
			<listitem><para>Cyrillic Characters</para></listitem>
			<listitem><para>User Defined</para></listitem>
		</itemizedlist>
		<para>The tooltips of the icons show the &latex; commands and additionally needed packages.</para>
		<para>Pressing <keycombo>&Shift;</keycombo> and clicking a symbol will result in 
		<userinput>$\symbolcmd$</userinput> being inserted. Similiar pressing <keycombo>&Ctrl;</keycombo> 
		inserts it in curly brackets.</para>
		<para>If you insert a command which requires a package which is not included in your &latex; document,
		you will see a warning message in the logview window.</para>
		<para>The first list of symbols holds the <guilabel>Most Frequently Used</guilabel> symbols. Inserted symbols will be 
			added to this list, for quick and easy reference. The ordering of the symbols will not be changed
			upon addition of new symbols, instead a reference counter is incremented. If the number of items
			would exceed 30 items, the item wit the lowest count will get removed.</para>
		<para>The <guilabel>User Defined</guilabel> symbol list can hold your own symbols.
		To create your own symbols you need the program gesymb and the file definitions.tex from the kile source package.
 		Additionaly you need a &latex; compiler (what a surprise) and 
		<ulink url="http://www.dvipng.sourceforge.net">&dvipng;</ulink> (version 1.7 or later).
 		The procedure is so that you create a &latex; file with <userinput>\input{definitions}</userinput>,
 		which makes the commands listed below available, and let <userinput>gesymb mysymbols.tex user</userinput> 
		(which calles &latex; and &dvipng;) create the icons. After copying them to 
		<userinput>$HOME/.kde/share/apps/kile/mathsymbols/user/</userinput> and restarting kile you can use your own symbols.
		</para>
		<para>
		The following commands are defined in definitions.tex:
		<itemizedlist>
			<listitem>
				<para>
					<userinput>\command[\optarg]{\symbol}</userinput>: Include the symbol <userinput>\symbol</userinput> in the
					symbol list, the optional argument <userinput>\optarg</userinput> specifies the command which kile should insert.
					If it is not given the command in the mandatory argument is used.
				</para>
			</listitem>
			<listitem>
				<para>
					<userinput>\mathcommand[\optarg]{\symbol}</userinput>: Same as above, except that the command in the mandatory
					argument is inserted in math mode.
				</para>
			</listitem>
			<listitem>
				<para>
					<userinput>\pkgs[arg]{pkg}</userinput>: Declare that the command given in this line needs the &latex; package
					<userinput>pkg</userinput> with the optional argument <userinput>arg</userinput>. This command has to be in
					front of the <userinput>\command</userinput> command and overrides any package specification by the neededpkgs
					enviroment.
				</para>
			</listitem>
			<listitem>
				<para>
					<userinput>\begin{neededpkgs}[pkgs-args]{pkgs} ... \end{neededpkgs}</userinput>: Has the same effect as
					above, but for all enclosed commands.
				</para>
			</listitem>
		</itemizedlist>
		</para>
		<para>
		An example for completeness is given here:
 		<screen><userinput>
		\documentclass[a4paper,10pt]{article}
		\usepackage{amssymb}
		\input{definitions}
		%
		\begin{document}
		\pagestyle{empty}
		%
		\begin{neededpkgs}{amssymb}
		\mathcommand{\surd}
		\pkgs{amsmath}\mathcommand[\ddddot{}]{\ddddot{a}}
		\mathcommand{\angle}
		\end{neededpkgs}
		\command{\"A}
		\mathcommand{\exists}
		\mathcommand[\stackrel{}{}]{\stackrel{abc}{=}}
		
		%\begin{neededpkgs}[russian,koi8-r,T2C,]{babel,inputenc,fontenc,mathtext}
		%   	
		%   \end{neededpkgs}
		% this would need to include the packages
		% \usepackage{mathtext}
		% \usepackage[T2C]{fontenc}
		% \usepackage[russian]{babel}
		% \usepackage[koi8-r]{inputenc}
		%  just to explain the format
		\end{document}
		</userinput></screen>
		</para>
	</sect1>

	<sect1 id="latex_bib">

		<title>Using Bibitems</title>

		<para><userinput>\bibitem</userinput> is a command used to enter a reference in a
		<userinput>thebibliography</userinput> environment in your document. The syntax for using
		<userinput>\bibitem</userinput> is <userinput>\bibitem[label]{key}</userinput>.</para>

		<para>The optional <userinput>[label]</userinput> is for you to add your own 
		labeling system for the bibliography entry. If no label is set, the entries 
		will be set in numerical order: [1], [2], [3], etc.</para>

		<para>The argument <userinput>{key}</userinput> is used to reference and link the commands
		<userinput>\bibitem</userinput> and <userinput>\cite</userinput> to
		each other and the information they contain. The command <userinput>\cite</userinput> contains the
		label associated with the intended <userinput>\bibitem</userinput>, which is located inside a
		<userinput>thebibliography</userinput> environment, and contains the reference data.
		Both corresponding <userinput>\bibitem</userinput> and <userinput>\cite</userinput> must
		have the same <userinput>{key}</userinput>; the easiest way to organize keys is by 
		the author's last name. The secondary braces in the <userinput>thebibliography</userinput> 
		environment denote the longest bibliography label you expect to have. 
		So, inserting <userinput>{<replaceable>foo</replaceable>}</userinput> means 
		you can have any label shorter or as large as the expression 
		<userinput><replaceable>foo</replaceable></userinput>. Failure to set this parameter correctly 
		may result in a not so attractive indentation of your bibliography.</para>

		<para>The bibliography is a section apart from your main document, and an example of
		code for the bibliography would look like the following:</para>

		<screen><userinput>
		\begin{thebibliography}{50}
		\bibitem{Simpson} Homer J. Simpson. \textsl{Mmmmm...donuts}.
		Evergreen Terrace Printing Co., Springfield, SomewhereUSA, 1998
		\end{thebibliography)</userinput></screen>

		<para>Then, your main source code would contain the location of the information relating to
		the <userinput>\bibitem</userinput> using <userinput>\cite</userinput>. That source code would look similar to this:</para>

		<screen><userinput>
		My thesis, about the philosophy of The Simpsons\copyright
		comes from my favorite book \cite{Simpson}.</userinput></screen>

		<para>As it is often difficult to remember the exact citation key once you have many 
		references, &kile; provides an easy way to insert a citation. On the <guilabel>Edit</guilabel> 
		toolbar click on the second drop-down box (usually it reads <guilabel>label</guilabel>) and select 
		<guilabel>cite</guilabel>. A list with all the citation keys pops up: select the correct 
		reference and a citation will be inserted into your document. To update the list of keys, 
		either save the file,<menuchoice><guimenu>Edit</guimenu><guimenuitem>Refresh 
		Structure</guimenuitem></menuchoice> or press <keycap>F12</keycap>.</para>

		<para>The final product in your document's bibliography would then look like this:</para>

		<para><computeroutput>[1] Homer J. Simpson. Mmmmm...donuts. Evergreen Terrace Printing Co.,
		Springfield, SomewhereUSA, 1998.</computeroutput></para>

		<para>The easiest way to work with <userinput>\bibitem</userinput> and
		<userinput>\cite</userinput> is to use the toolbar drop-down box marked
		<guilabel>cite</guilabel>. When you select a citation to insert, you will be given the list of
		<userinput>bibitem</userinput>s you have created so far, and will be able to select the
		reference from the list. &kile; can also work together with &bibtex; editor applications,
		such as &kbibtex; to help make citations easier.</para>

	</sect1>

	<sect1 id="latex_usertags">

		<title>User-Defined Tags</title>

		<para>&kile; gives you the ability to make your own tags. A tag is similar
		to a shortcut that launches some command or writes frequently-used text.
		For example, Joe Sixpack uses often the sentences <userinput>I prefer \LaTeX\ 
		to \TeX\</userinput> and <userinput>What would I do without Linux?</userinput>. 
		To create user-defined tags to write these sentences, he would access 
		<menuchoice><guimenu>LaTeX</guimenu><guisubmenu>User Tags</guisubmenu><guimenuitem>Edit 
		User Tags...</guimenuitem></menuchoice>; this will present him a dialog where he can create 
		his own user-defined tags.</para>
		<screenshot>
			<screeninfo>The Edit User Tags Dialog</screeninfo>
			<mediaobject>
			<imageobject>
			<imagedata fileref="snap_editusertag.png" format="PNG" />
			</imageobject>
			<textobject>
			<phrase>The Edit User Tags Dialog</phrase>
			</textobject>
			<caption><para>The Edit User Tags Dialog</para></caption>
			</mediaobject>
		</screenshot>

		<screenshot>
			<screeninfo>Invoking a User-Defined Tag</screeninfo>
			<mediaobject>
			<imageobject>
			<imagedata fileref="snap_usertag.png" format="PNG" />
			</imageobject>
			<textobject>
			<phrase>Invoking a User Defined Tag</phrase>
			</textobject>
			<caption><para>Invoking a User Defined Tag</para></caption>
			</mediaobject>
		</screenshot>

		<para>He would probably give each tag a name that can clearly identify it. The name you give your tag 
		is entered in the section marked <guilabel>Menu item</guilabel>, and the text of frequently-used command 
		should be entered into the section labeled <guilabel>Value</guilabel>. Once the commands are entered, 
		he can use them quickly using the shortcut <keycombo>&Ctrl;&Shift;<keycap>1</keycap></keycombo> for 
		the first tag to enter <userinput>I prefer \LaTeX\ to \TeX\</userinput> and <keycombo>&Ctrl;&Shift;
		<keycap>2</keycap></keycombo> to enter <userinput>What would I do without Linux?</userinput>.</para>

		<sect2 id="latex_usertags_uc">

			<title>Placeholders in User-Defined Tags</title>

			<para>There are some placeholders you can use in user-defined tags: 
			they are <userinput>%B</userinput>, <userinput>%C</userinput>, <userinput>%M</userinput> and
			<userinput>%S</userinput>.</para>

			<itemizedlist>
				<listitem><para><userinput>%B</userinput>: will be replaced by a bullet.</para></listitem>
				<listitem><para><userinput>%C</userinput>: this is where the cursor will be placed after the insertion of a
				user-defined tag.</para></listitem>
				<listitem><para><userinput>%M</userinput>: this stands for marked text; the selected text is
				inserted in its place when inserting user-defined tags.</para></listitem>
				<listitem><para><userinput>%S</userinput>: will be replaced by the source file's name without file extension.</para></listitem>
			</itemizedlist>

			<para>To show you how this works let's say for example that we have a user-defined tag,
			which contains the value <userinput>\bfseries{%M}%C</userinput>, and I have a selection of text
			highlighted in my document that we want to turn into bold text. So, we highlight the
			phrase <userinput>I love Fridays</userinput>, apply our user-defined tag by pressing
			<keycombo>&Ctrl;&Shift;<keycap>1</keycap></keycombo>, and we get the text
			<userinput>\bfseries{I love Fridays}</userinput>, with the cursor 
			placed at the end of the text.</para>

		</sect2>

	</sect1>

</chapter>

<chapter id="build">

	<title>The Build Tools</title>

	<sect1 id="build_sect">

		<title>Compiling, converting and viewing</title>

		<para>To view the result of your work, you first need to compile the source. All the build 
		tools are grouped closely together in the
		<menuchoice><guimenu>Build</guimenu><guisubmenu>Compile</guisubmenu></menuchoice>,
		<menuchoice><guimenu>Build</guimenu><guisubmenu>Convert</guisubmenu></menuchoice>,
		and <menuchoice><guimenu>Build</guimenu><guisubmenu>View</guisubmenu></menuchoice> 
		menus.</para>

		<para>To compile your source code for screen viewers like &kdvi;, &kghostview;, &kpdf; or
		further conversion, you can use the shortcut <keycombo>&Alt;<keycap>2</keycap></keycombo>.
		Then you can view the DVI file using your default viewer with 
		<keycombo>&Alt;<keycap>3</keycap></keycombo>, convert 
		the DVI to a PS file with <keycombo>&Alt;<keycap>4</keycap></keycombo>, 
		and view the PS file with <keycombo>&Alt;<keycap>5</keycap></keycombo>.</para>

		<sect2>

		<title>&bibtex;</title>

			<para>If you are using <ulink url="http://www.ecst.csuchico.edu/~jacobsd/bib/formats/bibtex.html">&bibtex;</ulink> 
			for your bibliography entries, you usually have to follow a special compiling scheme.
      This means calling &latex; and then &bibtex; and then &latex; twice again. Fortunately &kile; is clever enough to
      detect automatically if it is necessary to call additional tools like &bibtex;, &makeidx; and &asymptote;.
      This logic is by default turned on and can be changed in <menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure
      Kile...</guisubmenu><guisubmenu>Tools</guisubmenu><guilabel>Build</guilabel></menuchoice> in the <guilabel>General</guilabel> tab in the &latex; and &pdflatex; tools.
      </para>

		</sect2>

		<sect2>

			<title>&makeidx;</title>

			<para>If you are using the <ulink url="http://ipagwww.med.yale.edu/latex/makeindex.pdf">&makeidx;</ulink> 
			package to make a final, alphabetical index for your document, you have also to follow a certain
			compilation pattern or let &kile; do this for you in the same way as with &bibtex; files.</para>

		</sect2>

		<sect2>

			<title>MetaPost and Asymptote</title>

			<para>If you want to compile your document with <application>MetaPost</application> or <application>Asymptote</application>, picture drawing programs, you can do it with 
			<menuchoice><guimenu>Build</guimenu><guisubmenu>Compile</guisubmenu><guimenuitem>Metapost</guimenuitem></menuchoice>.
			or <menuchoice><guimenu>Build</guimenu><guisubmenu>Other</guisubmenu><guimenuitem>Asymptote</guimenuitem></menuchoice>.</para>

		</sect2>
		
		<sect2>

			<title>&pdflatex;</title>

			<para>There is also another way to compile your document, if you want a PDF: you can run 
			&pdflatex;, that will compile the source directly into a PDF file, with 
			<keycombo>&Alt;<keycap>6</keycap></keycombo>: you can then view the compiled 
			file pressing <keycombo>&Alt;<keycap>7</keycap></keycombo>.</para>

			<para>Alternatively, you can convert a PS into a PDF with 
			<keycombo>&Alt;<keycap>8</keycap></keycombo>, or directly a 
			DVI into a PDF with <keycombo>&Alt;<keycap>9</keycap></keycombo>.</para>

			<para>Using &pdflatex; instead of &latex; may be just a matter of simplicity or habit,
			but sometimes the behavior of the two program can differ.</para>
			
		</sect2>

		<sect2>

			<title>&latex; to Web</title>

			<para>Finally, you may want to publish your work on the web and not just on paper. You may
			then use the <application>latex2html</application> program, that can be called from &kile;'s menu
			<menuchoice><guimenu>Build</guimenu><guisubmenu>Convert</guisubmenu><guimenuitem>LaTeX
			to Web</guimenuitem></menuchoice>. The result will be placed in a subfolder of the work folder,
			and you will be able to see the result of the conversion choosing the menu item 
			<menuchoice><guimenu>Build</guimenu><guisubmenu>View</guisubmenu><guimenuitem>View
			HTML</guimenuitem></menuchoice>.</para>

		</sect2>

		<sect2 id="build_cl">

			<title>Passing Command-Line Parameters</title>

			<para>If you want to pass some specific command-line parameters to the compile, convert 
			or view tools, you can configure their call in <menuchoice><guimenu>Settings</guimenu>
			<guisubmenu>Configure Kile...</guisubmenu><guisubmenu>Tools</guisubmenu><guilabel>Build</guilabel></menuchoice>.</para>

		</sect2>
				
	</sect1>

	<sect1 id="build_preview">
		<title>Quick Preview</title>

		<para>You will always need some time to view the result, when working with &latex;. 
		&latex; has to compile the source and the viewer has to be called. This can be 
		annoying if you only changed some letters in an equation difficult to typeset.
		&kile; offers a <emphasis>Quick Preview</emphasis> mode, where you can compile 
		only a part of a document and save a lot of time. It supports four different modes,
		which can be combined with seven configurations.</para> 
		
		<screenshot>
			<screeninfo>Quick Preview</screeninfo>
			<mediaobject>
			<imageobject>
			<imagedata fileref="quickpreview.png" format="PNG" />
			</imageobject>
			<textobject>
			<phrase>Quick Preview</phrase>
			</textobject>
			</mediaobject>
		</screenshot>

		<para>All settings must be done in 
		<menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure Kile...</guisubmenu>
		<guimenuitem>Tools</guimenuitem><guilabel>Preview</guilabel></menuchoice>.</para>

		<screenshot>
			<screeninfo>Quick Preview Configuration</screeninfo>
			<mediaobject>
			<imageobject>
			<imagedata fileref="config-quickpreview.png" format="PNG" />
			</imageobject>
			<textobject>
			<phrase>Quick Preview Configuration</phrase>
			</textobject>
			</mediaobject>
		</screenshot>

		<sect2 id="build_qp_selection">
		
			<title>Selection Mode</title>

			<para>The user has to select a part of the document. Menu entry <menuchoice><guimenu>Build</guimenu><guisubmenu>QuickPreview</guisubmenu><guimenuitem>Selection</guimenuitem></menuchoice>
			or the keyboard shortcut <keycombo action="simul">&Ctrl;&Alt;<keycap>P</keycap></keycombo>,<keycap>S</keycap>
			will start the selected programs. &kile; takes the preamble of the original text, so that 
			all packages and user defined commands are included. The user can choose one 
			of seven predefined configurations:</para>

			<itemizedlist>
			<listitem><para><application>LaTeX+DVI (embedded viewer)</application></para></listitem>
			<listitem><para><application>LaTeX+DVI (KDVI)</application></para></listitem>
			<listitem><para><application>LaTeX+PS (embedded viewer)</application></para></listitem>
			<listitem><para><application>LaTeX+PS (KGhostView)</application></para></listitem>
			<listitem><para><application>PDFLaTeX+PDF (embedded viewer)</application></para></listitem>
			<listitem><para><application>PDFLaTeX+PDF (KGhostView)</application></para></listitem>
			<listitem><para><application>PDFLaTeX+PDF (KPDF)</application></para></listitem>
			</itemizedlist>

			<para>This should be sufficient for all situations for which a quick preview is needed.</para>

		</sect2>
		
		<sect2 id="build_qp_environment">
		
			<title>Environment Mode</title>
			
			<para>Very often you want to preview the current environment, and especially mathematic
			environments, which sometimes may be difficult to write. &kile; offers a very fast way 
			to do this. No selection is needed, only choose
			<menuchoice><guimenu>Build</guimenu><guisubmenu>QuickPreview</guisubmenu><guimenuitem>Environment</guimenuitem></menuchoice>
			or the keyboard shortcut <keycombo action="simul">&Ctrl;&Alt;<keycap>P</keycap></keycombo>,<keycap>E</keycap>
			 and the current environment will be compiled and shown.</para>

		</sect2>
		
		<sect2 id="build_qp_subdocument">
		
			<title>Subdocument Mode</title>
			
			<para>If you have a large project with a lot of documents, compiling the whole 
			project is not a great idea, if you have made changes only in one single document. 
			&kile; is able to compile and show a preview of the current subdocument. It 
			takes the preamble from the master document and only compiles the current part
			when you choose <menuchoice><guimenu>Build</guimenu><guisubmenu>QuickPreview</guisubmenu><guimenuitem>Subdocument</guimenuitem></menuchoice>
			or the keyboard shortcut <keycombo action="simul">&Ctrl;&Alt;<keycap>P</keycap></keycombo>,<keycap>D</keycap>.</para> 
			
		</sect2>

		<sect2 id="build_qp_mathgroup">
		
			<title>Mathgroup Mode</title>
			
			<para>The mathgroup preview mode allows you to preview the mathgroup you are currently editing. &kile; 
			takes the preamble from the master document and only compiles the mathgroup the cursor is currently in
			when you choose <menuchoice><guimenu>Build</guimenu><guisubmenu>QuickPreview</guisubmenu><guimenuitem>Mathgroup</guimenuitem></menuchoice>
			or the keyboard shortcut <keycombo action="simul">&Ctrl;&Alt;<keycap>P</keycap></keycombo>,<keycap>M</keycap>.</para> 
			
		</sect2>

		<sect2 id="qp_bottombar">
		
			<title>Quick Preview in Bottom Bar</title>
			
			<para>Instead of showing the preview in a new document &kile; can also be configured to use the bottom bar for preview
			compilations. You can activate this feature in the quick preview configuration panel.</para>	
			
		</sect2>

	</sect1>	
		
	<sect1 id="build_graphics">

		<title>Graphic File Formats</title>

		<sect2 id="build_graphics_latex">
		
		<title>&latex; and &pdflatex;</title>
		
		<para>&pdflatex;, when used with <userinput>graphics</userinput> or
		<userinput>graphicx</userinput> packages, can compile correctly PNG and JPG files into
		DVI or PDF, but is not able to handle EPS files. Conversely, the process of compiling 
		with &latex; to DVI and converting to PS and eventually PDF does support EPS, but does 
		not support PNG and JPG.</para> 
		
		<para>A lot of users want to create PDF documents, but also want to use of the excellent
		<application>Pstricks</application> package to create &postscript; graphics, or they want 
		to use the &postscript; output of mathematical and scientific software like 
		<application>Mathematica</application>, <application>Maple</application> or <application>MuPAD</application>. 
		These &latex; users have to compile first in &postscript;, even if they want to create 
		PDF documents, because these programs produce &postscript; code which cannot be managed 
		by &pdflatex;. However, it is not so hard as it may sound, because &kile; will help.</para>
		
		</sect2>
		
		<sect2 id="build_graphics_conversion">
		
		<title>Graphics Conversion</title>

		<para>To overcome this frustrating loop, in case you want to include both &postscript; code and PNG or JPG files, 
		you have a number of workarounds:</para>

		<itemizedlist>
			<listitem><para>If you need a file in PS format, but have JPG or PNG graphics, you can also
			simply use &pdflatex; with DVI output first, and then run <application>dvips</application> 
			to create the PS file. You see that &pdflatex; is a very good choice, if your source contains
			no &postscript; code at all.</para></listitem>
			
			<listitem><para>You can convert EPS files to PNG or other formats with utilities as the
			<ulink url="http://www.gimp.org/"><application>Gimp</application></ulink> or
			<ulink url="http://www.imagemagick.org/">&imagemagick;</ulink> 
			and use &pdflatex;.</para></listitem>
			
			<listitem><para><anchor id="build_graphics_epstopdf"></anchor>A preferred way 
			is to convert EPS graphics to PDF graphics with 
			<command>epstopdf</command>, which comes with every &tex; distribution
			distribution and then use &pdflatex;. It produces high quality graphics, 
			and you can even control the result with some of the following options: 
			 
<programlisting>
	-dAutoFilterColorImages=false
	-dAutoFilterGrayImages=false
	-sColorImageFilter=FlateEncode
	-sGrayImageFilter=FlateEncode
	-dPDFSETTINGS=/prepress
	-dUseFlateCompression=true
</programlisting>
			</para>
			
			<para>Even better: if your system allows <userinput>shell-escape</userinput>, conversion
			can be done on the fly. All you have to do is to include the <application>epstopdf</application> package,
			which is part of all &tex; distributions, with command <userinput>\usepackage{epstopdf}</userinput>.
			Assuming that your code is
			
<programlisting>
	\includegraphics[width=5cm]{test.eps}
</programlisting>
			
			When you call &pdflatex; with option <option>--shell-escape</option>,
			graphics <filename>test.eps</filename> is automatically converted into <filename>test.pdf</filename>.</para>
			
			<para>This conversion will take place each time you run &pdflatex;. 
			If your graphics command is given implicitly:
			
<programlisting>
	\includegraphics[width=5cm]{test}
</programlisting>
			
			<application>epstopdf</application> checks whether <filename>test.pdf</filename> is already 
			available, so that conversion step can be skipped.</para></listitem>

			<listitem><para>You can convert the other way around, and use &latex; and PS-PDF conversion.
			This is not always a good idea, since EPS encapsulation of JPG or PNG can yield larger 
			files, that in turn yield unnecessarily large documents. This is however <emphasis>highly</emphasis> 
			dependent on the graphic utility that you use, since EPS can encapsulate other graphics, 
			but not all applications support this perfectly. Some might actually try to build your JPG image 
			with vectors and various scripting, which will result in gigantic files. Conversion of
			all graphics formats to EPS can be done by
			<ulink url="http://www.imagemagick.org/">&imagemagick;</ulink>. 
			Another simple program that does this process correctly is 
			<ulink url="http://www.tex.uniyar.ac.ru/win32/tools/jpg2ps/"><application>jpg2ps</application></ulink>.
			</para></listitem>
			
			<listitem><para>You can also use an automatic conversion. All graphic files are 
			converted on the fly to EPS, and inserted into the PS document. This is a comfortable 
			way, but you have to set up your system properly. This is discussed in the section 
			<link linkend="build_epsgraphics">EPS Graphics</link>.</para></listitem>
			
		</itemizedlist>

		</sect2>
		
		<sect2 id="build_graphics_type">
		
		<title>Use the right File for the right Graphic</title>

	 	<itemizedlist>
			<listitem><para>EPS is sort of a graphic vector scripting language, describing
			all the lines and dots the graph is made of; it looks good even when magnified beyond its
			default size, and suits best diagrams and vectorial graphic natively produced in EPS, 
			which look very clear and sharp while maintaining a very small byte size.</para></listitem>
			<listitem><para>PNG (or the deprecated GIF) is a <emphasis>non-lossy</emphasis> file format, 
			with good compression and quality. It is very good for diagrams, scans of drawings, 
			or anything whose sharpness you do want to retain. It is sometimes overkill 
			when used for photos.</para></listitem>
			<listitem><para>JPG is a <emphasis>lossy</emphasis> format, that compresses files better than PNG 
			at the price of some loss in the picture detail. This is usually irrelevant for photos, 
			but may cause bad quality for diagrams, drawings, and may make some thin lines disappear outright; 
			in those cases use EPS or PNG.</para></listitem>
		</itemizedlist>

		<para>But always remember: garbage in, garbage out! No conversion will make a bad picture good.</para>

		</sect2>
		
	</sect1>

	<sect1 id="build_epsgraphics">
		
		<title>EPS Graphics</title>
		
		<para>EPS graphics files are the traditional way to insert graphics files into
		&latex; documents. As mailing lists are full with questions concerning
		EPS graphics, we will discuss some important aspects and
		demonstrate how &kile; supports them.</para>
		
		<sect2 id="build_graphics_eps">
		
		<title>&latex; and EPS Graphics</title>

		<para>If you decided to use the traditional &latex; to produce
		PS or PDF output, you will probably run into some problems
		with graphics. You have to use EPS graphics (Encapsulated &postscript;), 
		no JPEG or PNG files. This should be no problem, as there are a lot of 
		<link linkend="build_graphics_conversion">converters</link> like 
		<command>convert</command> from the excellent 
		<ulink url="http://www.imagemagick.org/">&imagemagick;</ulink> 
		package. But, it needs some time of course.</para> 
		
		<para>The EPS files are used by both &latex; and the DVI-PS converter:</para>
		
		<itemizedlist>
		<listitem><para>&latex; scans the EPS file for the bounding box 
		line, which tells &latex; how much space to reserve for the 
		graphics.</para></listitem>
		
		<listitem><para>The DVI-PS converter then reads the EPS file and 
		inserts the graphics in the PS file.</para></listitem>
		</itemizedlist>

		<para>This has some implications:</para>
 
		<itemizedlist>
		<listitem><para>&latex; never reads the EPS file if the bounding-box 
		parameters are specified in the graphics-insertion command.</para></listitem>

		<listitem><para>Since &latex; cannot read non-ASCII files, 
		it cannot read the bounding-box information from compressed or non-EPS 
		graphics files.</para></listitem>
		
		<listitem><para>The EPS graphics are not included in the DVI file. Since the
		EPS files must be present when the DVI file is converted to
		PS, the EPS files must accompany DVI files whenever they are 
		moved.</para></listitem>
		</itemizedlist>
		
		<para>Now you can call &latex;, and a DVI-PS converter like <application>dvips</application>
		to create your &postscript; document. If your goal is a PDF document, you should run
		<command>dvips</command> with option <option>-Ppdf</option> and then call
		<command>ps2pdf</command>. You will find a lot of documents describing this solution.</para>
	
		</sect2>
	
		<sect2 id="build_graphics_epskile">
		
		<title>The &postscript; Way of &kile;</title>
		
		<para>&kile; helps you to get the bounding-box information. If you have installed 
		<ulink url="http://www.imagemagick.org/">&imagemagick;</ulink> 
		package, &kile; will extract this information from the EPS file and insert it as an
		option. This is done automatically when you select the graphics file. 
		There are two advantages to proceed like this:</para>

		<itemizedlist>
		<listitem><para>The information is already scanned in the dialog, and 
		need not to be done by &latex; later on.</para></listitem>
		<listitem><para>Even more important is that the width and height of the picture 
		can be calculated, when the its resolution is known. This information will be shown 
		near the top of the dialog, and may serve as a clue when you want to scale the 
		graphics.</para></listitem>
		<listitem><para>&kile; can also support zipped or gzipped EPS files,
		which are much smaller than uncompressed EPS files. But, this feature can only be used 
		with a special system setup and a change of your local graphics configuration, 
		like it is described in the <link linkend="build_graphics_bitmap">Bitmap Graphics</link> 
		section.</para></listitem> 
		</itemizedlist>
	<!-- FIXME I don't understand the following sentence, tbraun	
		<para> The <emphasis>&postscript; Way of &kile;</emphasis> can be turned off or on in
		<menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure Kile...</guisubmenu>
		<guimenuitem>LaTeX</guimenuitem><guilabel>General</guilabel></menuchoice>.</para>
		-->
	</sect2>
		
	<sect2 id="build_graphics_bitmap">
		
		<title>The &postscript; Way and Bitmap Graphics</title>
		
		<para>If your systems allows <userinput>shell-escape</userinput>, &kile;
		also supports an easy way to include bitmap graphics, if you set up your &tex;
		system properly. There is no need to convert JPEG or PNG graphics, 
		this can be done automatically when the DVI file is converted to PS.</para>
		
		<para>&latex; needs some information about the file suffixes. The package 
		<userinput>graphicx</userinput> looks for a file <filename>graphics.cfg</filename>, 
		which must be somewhere in your search path for &latex; documents. Search for 
		entries like:</para>

<programlisting>
   \DeclareGraphicsRule{.pz}{eps}{.bb}{}%
   \DeclareGraphicsRule{.eps.Z}{eps}{.eps.bb}{}%
   \DeclareGraphicsRule{.ps.Z}{eps}{.ps.bb}{}%
   \DeclareGraphicsRule{.ps.gz}{eps}{.ps.bb}{}%
   \DeclareGraphicsRule{.eps.gz}{eps}{.eps.bb}{}%
</programlisting>

		<para>and replace these lines with:</para>
		
<programlisting>
   \DeclareGraphicsRule{.pz}{eps}{.bb}{}%
   \DeclareGraphicsRule{.eps.Z}{eps}{.eps.bb}{}%
   \DeclareGraphicsRule{.ps.Z}{eps}{.ps.bb}{}%
   \DeclareGraphicsRule{.ps.gz}{eps}{.ps.bb}{}%
   % changed or new graphic rules
   \DeclareGraphicsRule{.eps.zip}{eps}{.eps.bb}{`unzip -p #1}%   zipped EPS 
   \DeclareGraphicsRule{.eps.gz}{eps}{.eps.bb}{`gunzip -c #1}%   gzipped EPS
   \DeclareGraphicsRule{.jpg}{eps}{}{`convert #1 eps:-}%         JPEG
   \DeclareGraphicsRule{.gif}{eps}{.bb}{`convert #1 eps:-}%      GIF
   \DeclareGraphicsRule{.png}{eps}{.bb}{`convert #1 eps:-}%      PNG
   \DeclareGraphicsRule{.tif}{eps}{.bb}{`convert #1 eps:-}%      TIFF
   \DeclareGraphicsRule{.pdf}{eps}{.bb}{`convert #1 eps:-}%      PDF-graphics
</programlisting>

		<para>You will find this file, for example in Debian, at 
		<filename>/etc/texmf/latex/graphics.cfg</filename>. The best way to proceed is to copy this
		file to your local texpath and then change this file. See the yours &tex; distribution manual
		to learn how to get a list of your &tex; folders.</para>
		
		<para>With this configuration file you are able to insert bitmap graphics and 
		zipped or gzipped EPS files in &latex;. The command for conversion 
		is given by <command>dvips</command>. When you look 
		at the conversion command you will see that no extra file is created. 
		The result of the conversion process is directly piped into the PS file. 
		The only thing &latex; must know is the size of the graphics, and
		therefore we need the bounding box, which is provided by &kile;.</para>
		
		<para>Some say that this way is insecure; you have to decide on how to work. 
		In any case, you need no bounding box, as &kile; will extract this information 
		from all types of graphics.</para>

		</sect2>
		
		<sect2 id="build_graphics_pdflatex">
		
		<title>&pdflatex; and EPS Graphics</title>

		<para>As already stated, &pdflatex; is not able to handle EPS graphic files, 
		but converters like <link linkend="build_graphics_epstopdf">epstopdf</link> 
		will help. The best way is to include package <filename>epstopdf</filename>, 
		which must follow the <userinput>graphicx</userinput> package.</para>
		
<programlisting>
   \usepackage[pdftex]{graphicx}
   \usepackage{epstopdf}
</programlisting>

		<para>Now you can already include EPS graphics, if you run <command>pdflatex</command>
		with option <option>--shell-escape</option>, but we can make it even better
		and also handle zipped or gzipped EPS files. Again we have to change 
		the graphics configuration file <filename>graphics.cfg</filename> like above.
		This time we search for:</para>

<programlisting>
   % pdfTeX is running in pdf mode
   \ExecuteOptions{pdftex}%
</programlisting>

		<para>and simply add some lines.</para>
		
<programlisting>
   % pdfTeX is running in pdf mode
   \ExecuteOptions{pdftex}%
   \AtEndOfPackage{%
      \g@addto@macro\Gin@extensions{.eps.gz,.eps.zip}%
      \@namedef{Gin@rule@.eps.gz}#1{{pdf}{.pdf}{`gunzip -c #1 | epstopdf -f >\Gin@base.pdf}}%
      \@namedef{Gin@rule@.eps.zip}#1{{pdf}{.pdf}{`unzip -p #1 | epstopdf -f >\Gin@base.pdf}}%
   }%
</programlisting>
		
		<para>With these lines, &pdflatex; is able to handle EPS files,
		and hopefully there should be no more issues concerning graphics.</para>
	
	</sect2>
		
	</sect1>
 
	<sect1 id="build_master">

		<title>Master Document</title>

		<para>Defining your document as a master allows you to work with separated files,
		which gives you a parent document (or Master document), and child documents that
		make up a complete work. After having defined your Master document, with the
		corresponding command in the <guimenu>Settings</guimenu>
		menu, all the commands of the <guimenu>Tools</guimenu>
		menu will apply only to this document, even when you are working on the child
		documents. You can even close the Master document.</para>
	</sect1>

	<sect1 id="build_errorhandling">

		<title>Error Handling</title>

		<para>After you have compiled something, &kile; takes a look at the error messages 
		that were generated. If there are any errors or warnings, they will be briefly reported 
		in the <guilabel>Log and Messages</guilabel> window. One can take a closer look at the
		messages by selecting <menuchoice><guimenu>Build</guimenu><guimenuitem>View Log File</guimenuitem></menuchoice>,
		or by using the keyboard shortcut <keycombo>&Alt;<keycap>0</keycap></keycombo>.
		The generated log is then displayed in the <guilabel>Log and Messages</guilabel> view; errors and warnings are highlighted.</para>

		<screenshot>
			<screeninfo>Viewing the log</screeninfo>
			<mediaobject>
			<imageobject>
			<imagedata fileref="snap_compile_error.png" format="PNG" />
			</imageobject>
			<textobject>
			<phrase>Viewing the log</phrase>
			</textobject>
			<caption><para>Viewing the log</para></caption>
			</mediaobject>
		</screenshot>

		<para>You can easily jump from one message in the log file to another by using the
		<menuchoice><guimenu>Build</guimenu><guimenuitem>Next / Previous
		LaTeX Error / Warning</guimenuitem></menuchoice> menu items, or by using
		the corresponding toolbar buttons.</para>

		<para>To jump to the line in the &latex; source where the error or warning occurred,
		click on the error or warning in the <guilabel>Log and Messages</guilabel> view.
		&kile; will take you automatically to the offending line.</para>

	</sect1>

	<sect1 id="build_watch">

			<title>The Watch File Mode</title>

			<para>When you launch the <guibutton>Quickbuild</guibutton> command, a viewer of
			some sort will normally be called after the compilation. If you are not using an embedded 
			viewer, a new window will be open every time.</para>

			<para>If you are adjusting the look of your document, you might launch
			<guibutton>Quickbuild</guibutton> very often, and have many viewer windows open on
			your desktop; to avoid this confusion, you can activate the <guibutton>Watch file</guibutton>
			mode, that will prevent <guibutton>Quickbuild</guibutton> from launching a viewer.</para>
			
			<para>Presently, &kdvi; supports continuous updating of the viewed DVI file, but
			&kghostview; is not as perfect: to update the document after compiling, you will have
			to change page, and the number of pages will not be changed in &kghostview;'s visualization.</para>
			
			<para>This mode is of course useless with the embedded viewers, as you have to close them
			anyway to get back to editing the document and recompiling.</para>

	</sect1>

</chapter>

<chapter id="navigating">

	<title>Navigating the &latex; Source</title>

	<sect1 id="navigating_struct">

		<title>Using the Structure View</title>

		<para>The <guilabel>Structure</guilabel> view shows the hierarchy of the document
		being created in &kile;, and allows you to quickly navigate it, showing its segmentation. 
		To navigate around your document, all you need to do is to left click on any label, chapter, 
		section, subsection, etc., and you will be taken to the beginning of
		the corresponding area.</para>
		
		<para>If you included a separate &latex; file in your source using
		the <userinput>\input</userinput> or <userinput>\include</userinput> tags, these files will
		be referred to in the <guilabel>Structure</guilabel> view; double-clicking on their names in
		it will make &kile; bring up the included file in the editor window.</para>
		
		<para>The hierarchy tree has also a separate branch for labels used in the text.</para>

		<screenshot>
			<screeninfo>Using the Structure View</screeninfo>
			<mediaobject>
			<imageobject>
			<imagedata fileref="snap_structview_label.png" format="PNG" />
			</imageobject>
			<textobject>
			<phrase>Using the Structure View</phrase>
			</textobject>
			<caption><para>Using the Structure View</para></caption>
			</mediaobject>
		</screenshot>

		<sect2 id="navigating_update">

			<title>Updating the Structure View</title>

			<para>To update your structure view you can either go to 
			<menuchoice><guimenu>Edit</guimenu><guimenuitem>Refresh 
			Structure</guimenuitem></menuchoice>, hit <keycombo><keycap>F12</keycap></keycombo>, or you can save your document,
			which will make &kile; update its <guilabel>Structure</guilabel> view.</para>

		</sect2>

	</sect1>

	<sect1 id="navigating_bookmarks">

		<title>Bookmarks</title>

		<para>Bookmarks are your reference to a segment of text or a line inside the &kile;
		environment. To use a bookmark, select a specific line of your document
		you would like to return to, then press <keycombo>&Ctrl;
		<keycap>B</keycap></keycombo>, and &kile; will add a bookmark to this line. 
		Alternatively, you can also set a bookmark by highlighting a line and choosing 
		the menu labeled <menuchoice><guimenu>Bookmark</guimenu><guimenuitem>Toggle 
		Bookmark</guimenuitem></menuchoice>.</para>

		<para>To remove all your bookmarks, select <menuchoice><guimenu>Bookmarks</guimenu>
		<guimenuitem>Clear Bookmarks</guimenuitem></menuchoice>.</para>

    <para>Please note that currently the bookmarks are not saved after exiting &kile;.</para>

	</sect1>

</chapter>

<chapter id="projects">

	<title>Projects</title>

	<sect1 id="projects_working">
	
		<title>Working with Projects</title>

		<para>In &kile; you can create and work with <emphasis>projects</emphasis>. A project is a 
		group of &latex;, graphic, &bibtex; or other files that contain all the information that is used to build 
		your complete document. A typical project would be a document consisting of several chapters, 
		written in different <literal role="extension">.tex</literal> files; all of them could be included in
		a project, to make the whole document easier to manage. The specifications of the project are stored in a special file, 
		with extension <literal role="extension">.kilepr</literal>.</para>

		<para>A Project adds the following functionalities:</para>

		<itemizedlist>
			<listitem><para>You need not set a master document, &kile; does this automatically.</para></listitem>
			<listitem><para>Project files can easily be archived together by going to <menuchoice><guimenu>Build</guimenu><guisubmenu>Other</guisubmenu><guimenuitem>Archive</guimenuitem></menuchoice></para></listitem>
			<listitem><para>The <guilabel>Files and Project</guilabel> view shows which files are included
			in the project.</para></listitem>
			<listitem><para>After opening a project, any file that was previously opened will be
			restored with the original encoding and highlightning.</para></listitem>
      <listitem><para> Code completion works across all project files.</para></listitem> 
      <listitem><para> Reference completion works across all project files.</para></listitem> 
      <listitem><para> Citation completion works across all project files.</para></listitem> 
      <listitem><para> Search in all project files.</para></listitem> 
      <listitem><para> Specify custom quickbuild and &makeidx; command.</para></listitem>
		</itemizedlist>

	</sect1>

	<sect1 id="projects_creating">

		<title>Creating a Project</title>

		<para>To create a project, select <menuchoice><guimenu>Project</guimenu>
		<guimenuitem>New Project...</guimenuitem></menuchoice>. You will be
		asked to give the following information to create your project:</para>
		<itemizedlist>
			<listitem><para>Title of your project.</para></listitem>
			<listitem><para>Name of the project file with <literal role="extension">.kilepr</literal> extension.</para></listitem>
			<listitem><para>Filename.</para></listitem>
			<listitem><para>Type of file creating: Empty Document, Article, Book, Letter, Report, ....</para></listitem>
		</itemizedlist>

		<para>When you fill out the <guilabel>filename</guilabel> box, you have to include a relative 
		path from where the <literal role="extension">.kilepr</literal> project file is stored to the file.</para>

	</sect1>

	<sect1 id="projects_view">

		<title>The File and Project View</title>

		<para>The <guilabel>File and Project</guilabel> view is a button of the sidebar menu. 
		From this view, you can see the structure of your project, its files, 
		and the name of the <literal role="extension">.kilepr</literal> file that stores the project information. 
		Adding, removing, or changing options in your project is done via
		the <guilabel>File and Projects</guilabel> view.</para>

		<screenshot>
			<screeninfo>The File and Project View</screeninfo>
			<mediaobject>
			<imageobject>
			<imagedata fileref="snap_projectview.png" format="PNG" />
			</imageobject>
			<textobject>
			<phrase>The File and Project View</phrase>
			</textobject>
			<caption><para>The File and Project View</para></caption>
			</mediaobject>
		</screenshot>

	</sect1>

	<sect1 id="projects_adding">

		<title>Adding and Removing Files</title>

		<para>To add a file to your project, open any &tex; file, right click on its name in the
		<guilabel>Files and Project</guilabel> view, and select <guilabel>Add to
		Project</guilabel>. If you have multiple projects open, a dialog box will ask
		you which project the file has to be added to.</para>

		<para>If you have multiple files to be added to a project, you can select the
		project from the <guilabel>Files and Project</guilabel> view and right-click then select
		<guilabel>Add Files</guilabel>; you will then be able to select your files in a dialog box.</para>
		
		<para>You can also right-click on the project's name in the <guilabel>Files and 
		Project</guilabel> view, and select <guilabel>Add Files...</guilabel> to bring
		up a file selection dialog.</para>

		<screenshot>
			<screeninfo>Adding a file to a project</screeninfo>
			<mediaobject>
			<imageobject>
			<imagedata fileref="snap_projectview_add.png" format="PNG" />
			</imageobject>
			<textobject>
			<phrase>Adding a file to a project</phrase>
			</textobject>
			<caption><para>Adding a file to a project</para></caption>
			</mediaobject>
		</screenshot>

		<para>To remove a file from a project, right-click on it and select <guilabel>Remove File</guilabel>.
		This does <emphasis>not</emphasis> delete your file (and also does not close it), but only removes it from the list 
		of files contained in the <literal role="extension">.kilepr</literal> extension.</para>

	</sect1>

	<sect1 id="projects_options">

		<title>Project Options</title>

		<para>&kile; has a few options related to your project that can be set. To change them,
		right-click on the title of your project and select <guilabel>Project Options</guilabel>,
		and you will have the option of changing:</para>

		<itemizedlist>
			<listitem><para>The title of your project.</para></listitem>
 			<listitem><para>The Master document.</para></listitem>
 			<listitem><para>The Quickbuild command.</para></listitem>
 			<listitem><para>The &makeidx; options.</para></listitem>
		</itemizedlist>

		<sect2 id="projects_archive">

			<title>Archiving your Project</title>

			<para>&kile; allows you to easily backup your project by storing all its files 
			into a single archive (often known as <emphasis>tarball</emphasis>). To archive your project 
			right-click on its name in the <guilabel>Files and Project</guilabel> view, or select 
			<menuchoice><guimenu>Project</guimenu><guimenuitem>Archive</guimenuitem></menuchoice>.</para>

			<para>By default, all files in a project are added to the archive. If you do not want to include 
			a certain file in the archive, right-click on it in the <guilabel>Files and Project</guilabel> 
			view, and uncheck the <guilabel>Include in Archive</guilabel> option.</para>

			<para>Archive commands are simple shell commands that are executed from the project
			folder (where the <literal role="extension">.kilepr</literal> file is located).</para>

		</sect2>

<!-- FIXME not working in kile, tbraun 11/3/2007
		<sect2 id="projects_ext">

			<title>Extensions for Non-Source Files</title>

			<para>Non-source files are files such as pictures, PDF or &postscript; files, etc. that are 
			to be included in the project, but are not source files with the extension <literal role="extension">.tex</literal>. You have 
			the option to use your own regular expressions to match non-source files.</para>
		</sect2>
-->

	</sect1>

	<sect1 id="projects_closing">

		<title>Closing a Project</title>

		<para>To close a project, select the <guilabel>Files and Project</guilabel> view from
		the vertical toolbar, right click on your project title, and then select <guimenuitem>
		Close</guimenuitem>. This will close your project, all the files associated with your project,
		and will also add the name of the project you just closed to <guisubmenu>Open Recent
		Project...</guisubmenu> in the <guimenu>Project</guimenu> menu.</para>

	</sect1>

</chapter>

<chapter id="lang">

	<title>Document Encoding</title>

	<para>The &kile; editor allows you to read, convert and set the text to the encoding 
	your document needs. This allows you to use non-standard letters and symbols; 
	you can use, for example, accented characters for Italian or French.
	Selecting the encoding for your document can be done in three ways:</para>

	<itemizedlist>
		<listitem><para>One way to set the encoding is to use the <guilabel>Set encoding</guilabel> combo
		box, located at the bottom of the <guilabel>Open File</guilabel> sidebar view.</para></listitem>
		<listitem><para>Another way is using the submenu 
		<menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure
		Kile...</guisubmenu><guimenuitem>Editor</guimenuitem></menuchoice>,
		where you can set the default character encoding for all files.</para>
		<screenshot>
			<screeninfo>Set the default character encoding</screeninfo>
			<mediaobject>
			<imageobject>
			<imagedata fileref="config-encoding.png" format="PNG" />
			</imageobject>
			<textobject>
			<phrase>Set the default character encoding</phrase>
			</textobject>
			</mediaobject>
		</screenshot>
		</listitem>
		<listitem><para>A third way to set the encoding for a document is to set the option
		when you use the wizard to create a new document.</para></listitem>
	</itemizedlist>

	<para>&latex; itself understands only ASCII, a very limited set of characters, so you could not use
	accented or special letters directly. To use accented letters, a special syntax was created: 
	such as for example <userinput>\"e</userinput> for <computeroutput>ë</computeroutput>. 
	There is a package to help you with this, called <application>inputenc</application>, and is included 
	in the preamble using <userinput>\usepackage[latin1]{inputenc}</userinput>, where the optional argument 
	is the encoding you would like to use (nowadays in most cases <userinput>utf8x</userinput>). This tells &latex;
	to translate all of the <userinput>ë</userinput>'s you wrote to <userinput>\"e</userinput>'s before
	compiling. Please refer to the <application>inputenc</application> documents directly for more
	information on <application>inputenc</application>. Last but not least: remember to make sure that 
	your file is <emphasis>actually</emphasis> encoded in the same encoding you told 
	<application>inputenc</application>!</para>

	<screenshot>
		<screeninfo>Choosing the source file's encoding</screeninfo>
		<mediaobject>
		<imageobject>
		<imagedata fileref="snap_encoding.png" format="PNG" />
		</imageobject>
		<textobject>
		<phrase>Choosing the source file's encoding</phrase>
		</textobject>
		<caption><para>Choosing the source file's encoding</para></caption>
		</mediaobject>
	</screenshot>

	<para>This host of different character coding tables has been creating problems on 
	many applications: for example, you cannot write a course of Turkish in French without 
	losing one language's special characters. There is general agreement that, sooner or later, 
	everybody will switch to <ulink url="http://www.unicode.org">Unicode</ulink>. There
	are many implementations of Unicode, and <abbrev>UTF-8</abbrev> is the most
	successful in Linux; Windows&reg; relies instead on the more cumbersome and
	less flexible <abbrev>UCS-2</abbrev>. Some distributions, as RedHat, have already
	begun setting their default encoding to <abbrev>UTF-8</abbrev>, and therefore you
	may be very interested in using of the <userinput>utf8x</userinput> argument to the
	<userinput>inputenc</userinput> package.</para>

	<sect1 id="ucs">
	
		<title>The &ucs; Package</title>
		<para>If you don't have the &ucs; package installed, you can proceed as follows:</para>
		<itemizedlist>
		<listitem><para>Get the &ucs; package from the home page of 
		<ulink url="http://www.unruh.de/DniQ/latex/unicode/">Unicode support for 
		&latex;</ulink>, by Dominique Unruh from the University of Karlsruhe.</para></listitem>
		<listitem>
		<para>To install it, unpack the downloaded file and place it in a directory listed
		 in your $<envar>TEXINPUTS</envar> envirnoment variable. This can also be set inside kile.</para>
		</listitem>
		</itemizedlist>
		<screen><userinput>
		\usepackage{ucs}
		\usepackage[utf8x]{inputenc}</userinput></screen>
		
	</sect1>
	
	<sect1 id="cjk">
		
		<title>&cjk; Support</title>
		
		<para>Adding support for ideographic languages is quite tricky. However, once
		you are done with it, it will work quite well. Other than installing packages,
		there is some extra configuration work to do.</para>
		
		<tip><para>Your Linux distribution might already have a &cjk; (Chinese, Japanese,
		Korean) package ready for you, so you might be saved the hassle of manually
		installing everything. Do check before going forward!</para></tip>
		
		<para>There is the possibility of using the &ucs; package in order to write
		short snippets of &cjk; text, but that option is seriously limited as it does
		not handle, among other things, newlines. We will instead install the complete
		&cjk;-&latex; package and make it work for both &latex; and &pdflatex;. A lot
		of this material has been inspired by <ulink url="http://www.ece.uci.edu/~chou/">Pai
		H. Chou</ulink>'s <ulink url="http://www.ece.uci.edu/~chou/unicode-tex.html">page 
		about how to setup &pdflatex;</ulink>.</para>
		
		<orderedlist>
		
		<listitem><para>Download the <ulink 
		url="http://www.ctan.org/tex-archive/help/Catalogue/entries/cjk.html">&cjk;</ulink> 
		package. Copy its unpacked files to an appropriate subfolder of 
		$<envar>TEXMF</envar>, just like you did with the &ucs; package 
		before (see <xref linkend="ucs"/>). The files will be unpacked in a 
		<filename>CJK/X_Y.Z</filename> folder, it is not important that you 
		take them out, though it will probably be tidier for you to 
		maintain.</para></listitem>
		
		<listitem><para>Now you have to download a font that supports all the &cjk; characters 
		you need. You can choose any <literal role="extension">*.ttf</literal> file that
		covers them, but in this walkthrough we will use <ulink
		url="ftp://ftp.netscape.com/pub/communicator/extras/fonts/windows/Cyberbit.ZIP">Cyberbit</ulink>.
		Unzip the file and rename <filename>Cyberbit.ttf</filename> to 
		<filename>cyberbit.ttf</filename>, since uppercase might confuse your system.</para>
		<para>Place <filename>cyberbit.ttf</filename> in a folder together with
		<ulink url="http://delloye.free.fr/Unicode.sfd"><filename>Unicode.sfd</filename></ulink>,
		and generate the <literal role="extension">*.tfm</literal> and 
		<literal role="extension">*.enc</literal> files with the command 
		<userinput><command>$ ttf2tfm cyberbit.ttf -w cyberbit@Unicode@</command></userinput>. 
		For some reasons, sometimes this does not produce the hundreds 
		of files it should. Should that be your case, you can download both 
		<ulink url="http://www.ece.uci.edu/~chou/unicode/cyberbit-tfm.tgz"><literal
		role="extension">*.tfm</literal></ulink> and 
		<ulink url="http://www.ece.uci.edu/~chou/unicode/cyberbit-enc.tgz"><literal
		role="extension">*.enc</literal></ulink> files.</para>
		<para>Place the <literal role="extension">*.tfm</literal> files in an 
		appropriate folder, say <filename>$<envar>TEXMF</envar>/fonts/tfm/bitstream/cyberbit/</filename>;
		the <literal role="extension">*.enc</literal> files may be installed in
		<filename>$<envar>TEXMF</envar>/pdftex/enc/cyberbit/</filename>.</para></listitem>
		
		<listitem><para>Now we need a map file to connect the <literal
		role="extension">*.enc</literal> files to the font. Download <ulink
		url="http://delloye.free.fr/cyberbit.map"><filename>cyberbit.map</filename></ulink> 
				and install it in <filename>$<envar>TEXMF</envar>/pdftex/config/</filename>.</para></listitem>
		
		<listitem><para>Download another file, <ulink 
		url="http://delloye.free.fr/c70cyberbit.fd"><filename>c70cyberbit.fd</filename></ulink>,
		and place it in an appropriate folder. You may choose, for example, 
		<filename>$<envar>TEXMF</envar>/tex/misc/</filename>.</para></listitem>
		
		<listitem><para>The last file we have to generate is a &postscript; Type 1
		font, necessary to read DVI files generated with &latex;. Run the command
		<userinput><command>$ ttf2pfb cyberbit.ttf -o cyberbit.pfb</command></userinput>, and copy the
		resulting <filename>cyberbit.pfb</filename> in a folder like
		<filename>$<envar>TEXMF</envar>/fonts/type1/cyberbit/</filename>.</para></listitem>
		
		<listitem><para>Let's now place <filename>cyberbit.ttf</filename> among the fonts 
		where &latex; can find it. You could place it in a folder named 
		<filename>$<envar>TEXMF</envar>/fonts/truetype/</filename>.</para></listitem>
		
		<listitem><para>Check the configuration file you find at
		<filename>$<envar>TEXMF</envar>/web2c/texmf.cnf</filename>, and make sure that the 
		line mentioning <envar>TTFONTS</envar> is uncommented and points to 
		the folder where you saved <filename>cyberbit.ttf</filename>.</para></listitem>
		
		<listitem><para>To make it possible for &pdflatex; to use your &cjk; 
		fonts, it is necessary that you add a line in configuration file
		<filename>$<envar>TEXMF</envar>/pdftex/config/pdftex.cfg</filename>. Add 
		<userinput>map +cyberbit.map</userinput> in the file to complete the
		configuration for &pdflatex;.</para></listitem>
		
		<listitem><para>To configure &latex; so that you can produce DVI 
		files with &cjk; characters, you have to add a line in file 
		<filename>ttfonts.map</filename>. The file might be in a folder named 
		<filename>$<envar>TEXMF</envar>/ttf2pk/</filename>, but you will probably have to look 
		for it. Add the line <userinput>cyberbit@Unicode@ cyberbit.ttf</userinput>
		into it.</para></listitem>
		
		<listitem><para>Now, you only have to run <userinput><command>texhash</command></userinput> 
		and the system should be ready.</para></listitem>
		
		</orderedlist>
		
		<para>To test whether your configuration is correct, you can try to compile
		<ulink url="http://www.math.nus.edu.sg/aslaksen/cs/sample-utf8.tex">this test
		file</ulink>.</para>
		
		<sect2>
			<title>&cjk; Troubleshooting</title>
			
			<para>There are many things that can go wrong when setting &cjk; 
			support manually. If something seems not to work, the following 
			checklist might help you.</para>
			
			<itemizedlist>
			
			<listitem><para>Obviously, since you run &latex; as a user and
			not as root, you must <emphasis>allow</emphasis> ordinary users
			to access the new files. Make sure all folders and files are 
			accessible using the <command>chmod</command> command.</para></listitem>
			
			<listitem><para>If &latex; writes a DVI without problems, but you
			cannot view it, it is almost certainly because of some problems in the
			automatic generation of <literal role="extension">*.pk</literal> 
			fonts. They are supposed to be generated on the fly when viewing a
			DVI file, but this might fail for a number of reasons: double-check
			<filename>ttfonts.map</filename> for your custom line first. However,
			it might happen that your <command>ttf2pk</command> command, which 
			is usually invoked by the DVI viewer, has been compiled 
			<emphasis>without</emphasis> support for the 
			<application>kpathsea</application> libraries. If this is the case,
			<userinput><command>ttf2pk</command> <option>--version</option></userinput> 
			will make no mention of <application>kpathsea</application>. As support for 
			these libraries is necessary, you might have to find a new package, or 
			recompile <application>FreeType 1</application> by yourself.</para></listitem>
			
			</itemizedlist>
			
		</sect2>
			
		
		<sect2>
		
			<title>How do I input &cjk; in Unicode?</title>
			
			<para>There are a number of different input engines, and the choice can
			depend also on personal preference. The author uses <ulink 
			url="http://www.scim-im.org/projects/skim"><application>Skim</application></ulink>,
			a port to &kde; of the <ulink 
			url="http://www.scim-im.org"><application>Scim</application></ulink>
			engine. Refer to your distribution's documentation to learn how to 
			install these programs. Configuration of such programs can be tricky
			too, in the case of <application>Skim</application> you will have to 
			define an environment variable <userinput><envar>XMODIFIERS</envar>="@im=SCIM"</userinput> 
			<emphasis>before</emphasis> starting <application>X</application>.</para>
		
		</sect2>
	
	</sect1>

</chapter>

<chapter id="scripting">

	<title>Scripting</title>

	<sect1 id="scripting_test">

		<title>Scripting in &kile;</title>

		<para>
			&kile;'s scripting feature allows for the execution of ECMAScript code. Scripts can be managed through the
			scripting panel in the sidebar.
		</para>

	</sect1>

	<sect1 id="scripting_api">

		<title>API Reference</title>

		<para>In this section we describe &kile;'s scripting programming interface.</para>

		<important>
			<para>
				Please note that the scripting API has not been finalized yet. The API described below might change in
				future versions of &kile;.
			</para>
		</important>

		<para>
			First of all, &kile;'s script execution environment provides a global object called "kile", which owns the following
			methods:
		</para>

		<variablelist>
			<varlistentry>
				<term>(kile).<function>currentTextDocument()</function></term>
				<listitem>
					<para>
						Returns a <classname>KileTextDocument</classname> object which reflects the currently active 
						text document. Returns <constant>null</constant> if no text document is active.
					</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>(kile).<function>getInputValue(<parameter>caption</parameter>, <parameter>label</parameter>)</function></term>
				<listitem>
					<para>
						Opens a dialog with the given caption and label. Returns the value that user has entered.
					</para>
				</listitem>
			</varlistentry>
		</variablelist>

		<para>
			Objects of the type <classname>KileTextDocument</classname> represent text documents in &kile;. They have the following
			properties:
		</para>

		<variablelist>
			<varlistentry>
				<term>(KileTextDocument).<function>backspace()</function></term>
				<listitem>
					<para>
						Deletes the character that is located immediately before the current cursor position and moves the cursor
						one position backward in the text.
					</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>(KileTextDocument).<function>cursorLeft()</function></term>
				<listitem>
					<para>Moves the cursor one position backward in the text.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>(KileTextDocument).<function>cursorRight()</function></term>
				<listitem>
					<para>Moves the cursor one position forward in the text.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>(KileTextDocument).<function>insertText(<parameter>text</parameter>)</function></term>
				<listitem>
					<para>
						Inserts the text contained in the variable <parameter>text</parameter> into the document at the current
						cursor location.
					</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>(KileTextDocument).<function>insertBullet()</function></term>
				<listitem>
					<para>Inserts a bullet into the document at the current cursor position.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>(KileTextDocument).<function>nextBullet()</function></term>
				<listitem>
					<para>
						Selects the first bullet located in the document immediately after the
						current cursor location.
					</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>(KileTextDocument).<function>previousBullet()</function></term>
				<listitem>
					<para>
						Selects the first bullet located in the document immediately before the
						current cursor location.
					</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>(KileTextDocument).<function>up()</function></term>
				<listitem>
					<para>Moves the cursor one line up in the document.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>(KileTextDocument).<function>down()</function></term>
				<listitem>
					<para>Moves the cursor one line down in the document.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>(KileTextDocument).<function>cursorLine()</function></term>
				<listitem>
					<para>Returns the line which the cursor is currently located at.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>(KileTextDocument).<function>cursorColumn()</function></term>
				<listitem>
					<para>Returns the column which the cursor is currently located at.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>(KileTextDocument).<function>setCursorLine(<parameter>line</parameter>)</function></term>
				<listitem>
					<para>Moves the cursor to the line denoted by <parameter>line</parameter>.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>(KileTextDocument).<function>setCursorColumn(<parameter>column</parameter>)</function></term>
				<listitem>
					<para>Moves the cursor to the column denoted by <parameter>line</parameter>.</para>
				</listitem>
			</varlistentry>
		</variablelist>

	</sect1>
	
</chapter>

<chapter id="help">
	
	<title>Help</title>
	
	<sect1 id="help_documents">
		
		<title>Help Documents</title>

		<para>&latex; is a rather sophisticated system, where the basic features
		can be expanded by a great variety of additional packages.
		&kile; provides a lot of different help to support the user.</para>

		<variablelist>

		<varlistentry>
		<term><guimenu>LaTeX Reference</guimenu></term> 
		<listitem><para>An alphabetical index of the most 
		common &latex; commands.</para></listitem>
		</varlistentry>
		
		<varlistentry>
		<term><guimenu>TeX Documentation</guimenu></term>
		<listitem><para>&tetex;/&texlive; comes with a huge amount of documents. 
		This includes a documentation for all included packages and an additional &latex; 
		reference.</para></listitem>
		</varlistentry>

		<varlistentry>
		<term><guimenu>LaTeX</guimenu></term>
		<listitem><para>A full reference for &tex; and friends. This is not 
		only a description of all programs, some important packages are also 
		mentioned. And it includes a full reference manual of &latex; 
		commands&mdash;ideal for looking up a particular piece of formatting 
		while writing a document. As this document is really extensive, 
		&kile; separates it with three important bookmarks.</para></listitem>
		</varlistentry>

		<varlistentry>
		<term><guimenu>LaTeX Command</guimenu></term>
		<listitem><para>Another alphabetical index of the most common 
		&latex; commands.</para></listitem>
		</varlistentry>

		<varlistentry>
		<term><guimenu>LaTeX Subject</guimenu></term>
		<listitem><para>A description of important &latex; 
		subjects.</para></listitem>
		</varlistentry>

		<varlistentry>
		<term><guimenu>LaTeX Env</guimenu></term>
		<listitem><para>An alphabetical index of the most common 
		&latex; environments.</para></listitem>
		</varlistentry>

		</variablelist>
		
	</sect1>
	
	<sect1 id="help_contextsentitive">
	
		<title>Context Sensitive Help</title>

		<para>&kile; also support a context sensitive help, which is called
		with <keycombo action="simul">&Ctrl;&Alt;<keycap>H</keycap></keycombo>,<keycap>K</keycap>.
		In <menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure Kile...</guisubmenu>
		<guimenuitem>Kile</guimenuitem><guilabel>Help</guilabel></menuchoice>
		you can choose whether you want to use &kile;'s &latex; reference or the
		help system of &tetex;/&texlive;, which is the default setting.</para>

		<screenshot>
			<screeninfo>Bullets</screeninfo>
			<mediaobject>
			<imageobject>
			<imagedata fileref="config-userhelp.png" format="PNG" />
			</imageobject>
			<textobject>
			<phrase>Bullets</phrase>
			</textobject>
			</mediaobject>
		</screenshot>

	</sect1>
	
	<sect1 id="help_search">
	
		<title>Searching for Keywords</title>
		
		<para>It is not always easy to find the right document, as &tetex;/&texlive; 
		comes with a huge amount of documents. As one possible help, &tetex;/&texlive; 
		provides a tiny program <application>texdoctk</application>. 
		It comes with a database of all documents that &kile; uses to offer 
		an interface to it.</para>

		<screenshot>
			<screeninfo>Bullets</screeninfo>
			<mediaobject>
			<imageobject>
			<imagedata fileref="dialog-docbrowser1.png" format="PNG" />
			</imageobject>
			<textobject>
			<phrase>Bullets</phrase>
			</textobject>
			</mediaobject>
		</screenshot>

		<para>All documents are grouped into some categories, and the main 
		advantage is that you can search for packages names or keywords. 
		&kile; will then show only the results.</para> 
		
		<screenshot>
			<screeninfo>Bullets</screeninfo>
			<mediaobject>
			<imageobject>
			<imagedata fileref="dialog-docbrowser2.png" format="PNG" />
			</imageobject>
			<textobject>
			<phrase>Bullets</phrase>
			</textobject>
			</mediaobject>
		</screenshot>
		
		<para>A mouse double click or the <keycap>Space</keycap> key will start the 
		viewer for this document. This can be a arbitrary document, not only a 
		DVI, PS, PDF or HTML document. &kile; will take &konqueror; settings to 
		start a appropriate viewer.</para>

		
	</sect1>
	
	<sect1 id="help_userdefined">
	
		<title>User Defined Help</title>
	
		<para>Beside this static &tetex;/&texlive; documentation, &kile; supports also 
		another variable way for user-help documents. In <guimenu>Help</guimenu> 
		menu &kile; has a special <guimenu>User help</guimenu> 
		submenu, where the user can add documents of his own choice. 
		These can be the most important documents of &tetex;/&texlive; documentation, or even 
		self written documents. It is even possible to choose some Web URLs.</para> 

		<para>Go to 
		<menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure Kile...</guisubmenu>
		<guimenuitem>Kile</guimenuitem><guilabel>Help</guilabel></menuchoice>
		and choose <guibutton>Configure</guibutton> button
		to configure this <guimenu>User help</guimenu> menu. You can add, 
		remove or navigate menu entries, and also insert separators to get 
		a better structure.</para>

		<para>Pressing the <guibutton>Add</guibutton> button will open 
		another dialog, where you must edit the name of the menu entry, 
		and choose the corresponding file or Web &url;. If you choose a Web &url;, 
		&konqueror; is started and you should copy the final &url;.</para>

		<screenshot>
			<screeninfo>Bullets</screeninfo>
			<mediaobject>
			<imageobject>
			<imagedata fileref="dialog-addhelp.png" format="PNG" />
			</imageobject>
			<textobject>
			<phrase>Bullets</phrase>
			</textobject>
			</mediaobject>
		</screenshot>

	</sect1>

</chapter>

<chapter id="credits">

	<title>Credits and License</title>

	<para>&kile; is an open-source user-friendly &latex; / &tex; source code editor. It will run on systems
	with the &kde; Desktop Environment installed. &kde; is available for several architectures
	with Linux and other Unix-like systems installed. &kile; is also part of the Fink project,
	which means you can run &kile; on a Mac with OS-X.</para>

	<para>Many thanks are owed to those who strive to continue the &kile; project, and the many
	hours of contributions made by those who sacrifice their time to develop tools we can all
	use under the <acronym>GNU</acronym> license. Up-to-date information about contributors can be found in
	the <guimenuitem>About &kile;</guimenuitem> dialog from the <guimenu>Help</guimenu> menu.
	</para>

	<para>Contributions among others from: Rob Lensen, Roland Schulz, Michael Margraf, Holger Danielsson</para>

	<para>Many thanks to all those involved!</para>

	&underFDL;		<!-- FDL: do not remove -->
	&underGPL;		<!-- GPL License -->

</chapter>


&documentation.index;

</book>

<!--
Local Variables:
mode: xml
sgml-minimize-attributes:nil
sgml-general-insert-case:lower
sgml-indent-step:0
sgml-indent-data:nil
End:

vim:tabstop=2:shiftwidth=2:expandtab
-->