summaryrefslogtreecommitdiffstats
path: root/doc/kompare/index.docbook
blob: 2ca8f97047e5b2ceb20f528279fd8ac6155bf68b (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
<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
   <!ENTITY kappname "&kompare;">
   <!ENTITY version "3.4">
   <!ENTITY package "tdesdk">
   <!ENTITY % addindex "IGNORE">
   <!ENTITY % English "INCLUDE">
]>

<book lang="&language;">

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

 <authorgroup>

<author><firstname>Sean</firstname><surname>Wheller</surname><email>sean@inwords.co.za</email></author>
 <!-- TRANS:ROLES_OF_TRANSLATORS -->
 </authorgroup>

<copyright>
<year>2007</year>
<holder>Sean Wheller</holder>
</copyright>

 <legalnotice>&FDLNotice;</legalnotice>

<date>2007-01-20</date>
<releaseinfo>3.4</releaseinfo>

<!-- Abstract about this handbook -->

<abstract>
<para>
&kompare; is a &GUI; front-end program that enables differences between source files to be viewed and merged. 
&kompare; can be used to compare differences on files or the contents of folders. &kompare; supports a variety 
of diff formats and provide many options to customize the information level displayed.</para>
<para>This document describes &kompare; version &version;.</para>
</abstract>


<keywordset>
<keyword>KDE</keyword>
<keyword>Kompare</keyword>
<keyword>Diff</keyword>
<keyword>Merge</keyword>
<keyword>Patch</keyword>
<keyword>Hunk</keyword>
</keywordset>

</bookinfo>

<chapter id="introduction">
<title>Introduction</title> 

<para>When two or more people are working on a file and passing it back and forth between one another, it becomes difficult to 
see what changes have been made to a new version or copy of the file. Opening the new copy and the original, side-by-side in the 
application used to create it is one solution but, laborious, time consuming, and prone to error. This is where a program to show 
differences, diffs for short, is useful.</para>

<para>As would be expected, an appropriate name for such a program would be &quot;diff&quot;. As it happens, the program diff is installed on 
most &Linux;-based systems and is used for exactly this purpose. Developers often use diff, as a command line tool, to show differences 
between versions of a source code file. However, the use of diff is not limited to showing differences in code source files, 
it can be used on many text-based file types.</para>

<para>Using diff from the command line can be confusing, learning the diff command syntax and deciphering the output can bewilder most people. 
This is where &kompare; comes into play. Providing a graphical front-end to the diff program, the interface displays source and destination files 
side-by-side with all differences automatically highlighted. From this starting point, changes in one file can be sequentially applied to the other file 
on a selective and controlled basis. Not all changes need to be applied and if you do apply a change it can always be &apos;unapplied&apos;. 
When all required changes have been applied they can be saved and will display as normal in the original application used to create the file.</para>

<para>In addition to displaying differences between a source and destination file, &kompare; can be used to create and view a special file called a &apos;diff&apos;. 
This file captures the differences between the two sources into a single file that can be used to view and apply changes to any other copy of the file. 
For example, if two people are editing a document. The first person wants to make changes and send just the changes made to the second person. 
Normally, the first person would send a complete copy of the modified document to the second person, who would then have to compare the modified document 
side-by-side with unmodified version. The process for this is much like what we have described in the previous paragraphs. With &kompare; the first person 
would first make a local copy of the file to be modified, then make changes and compare the original and modified copy. Now using &kompare; a diff file 
can be created that captures only the changes made. This can be sent to the second person in place of a whole file containing the changes.</para>

<para>Using &kompare; the second person can view the diff file, compare it to the local copy of the document and apply the changes made by the first person. 
So the process can go on for many versions of the document, each person making changes, creating diffs, distributing them and applying them.
This process is commonly called &quot;patching&quot;, a term taken from the program named &quot;patch&quot; which is another command line 
tool specifically designed for the purpose of applying diff files.</para>

<para>It sometimes happens that people edit a file at the same time. In this situation it is likely that people will make changes in the document at 
exactly the same line. This creates a problem because, without applied caution, people could be overwriting each others work as they apply the diff files they receive. 
Fortunately the developers of the diff and patch programs took this into consideration and so these tools will not allow such changes to be applied without manual intervention. 
When this state is reached, it is known as a &quot;conflict&quot;. &kompare; will display conflicts so that you can manually resolve them, deciding 
which changes should be applied to which file.</para>

<para>&kompare; is also a great program for comparison of file changes on a folder level. When used to compare folders &kompare; recursively examines subfolders 
and their file contents for differences. In this use case, each file where differences are found are automatically opened and 
listed by &kompare; where easy navigation between the various files is possible.</para>

</chapter>

<chapter id="using">
<title>Using &kompare;</title>

<sect1 id="getting-started">
<title>Getting Started</title>

<para>This section provides instructions for starting &kompare; and provides a quick tour to the &kompare; main interface.</para>

<sect2 id="starting-kompare">
<title>Starting &kompare;</title>

<para>A shortcut for starting &kompare; can be found in the K menu in the Development group 
<menuchoice><guimenu>Development</guimenu><guimenuitem>Kompare</guimenuitem></menuchoice>.</para>

<para>When &kompare; starts the first thing it does is display a dialog from 
which to select the files you wish to compare. Special settings for the properties of the diff and the apprearance thereof can also be selected. 
In the file form select a source and destination source to compare. This can be any two files, folders or a &URL; and a file. 
Once the source and destination are selected click the <guibutton>Compare</guibutton> button.</para>

<para>Once &kompare; has discovered the differences it will display the main interface. 
When comparing two files or a url and a file the process takes just a few seconds. However, when comparing folders 
with many subfolders and files, this process can take awhile.</para>

<para>For explanation of the options available from diff and appearance forms see <xref linkend="configure-preferences"/>.</para>
</sect2>

<sect2 id="main-interface">
<title>The Main Interface</title>

<para>This section provides a quick tour of the main interface which is comprised of the following areas:</para>
<itemizedlist>
<listitem><para>Menus</para></listitem>
<listitem><para>Toolbar</para></listitem>
<listitem><para>Source and Destination Folders</para></listitem>
<listitem><para>Source and Destination Files</para></listitem>
<listitem><para>Source and Destination Line Changes</para></listitem>
<listitem><para>Source and Destination Text View</para></listitem>
<listitem><para>Statusbar</para></listitem>
</itemizedlist>

<sect3 id="menus">
<title>Menus</title>
<para>&kompare; provides a menu driven interface. Explanation to the menu items and their options is provided in <xref linkend="command-reference"/>.</para>
</sect3>

<sect3 id="toolbar">
<title>Toolbar</title>
<para>The &kompare; toolbar provides shortcuts to the most frequently used diff and merge operations. 
The toolbar orientation, text postioning, icon size properties and which shortcut icons are displayed can be customized from the 
toobar context menu accessed when right-clicking the toolbar with the mouse. The toobar content menu also enables the toobar to be hidden. 
If the toolbar is hidden and you wish to unhide it, select <menuchoice><guimenu>Settings</guimenu><guimenuitem>Show Toolbar</guimenuitem></menuchoice>.</para>
</sect3>

<sect3 id="source-destination-folders">
<title>Source and Destination Folders</title>
<para>The source folder and destination folder panes display the folders in which compared files reside. 
When many subfolders are included in the comparison, then selecting a folder will display the first document in 
that folder where a difference was found between the source and destination.</para>
</sect3>

<sect3 id="source-destination-files">
<title>Source and Destination Files</title>
<para>The source and destination file pane displays files where a difference was found for the currently selected source or destination folder. 
When a folder has multiple documents containing differences, all documents with a difference are listed. The selected document is displayed.</para>
</sect3>

<sect3 id="source-destination-lines">
<title>Source and Destination Line Changes</title>
<para>The source and destination line changes pane summarizes the differences found between the current source and destination documents. 
Selecting a record within the pane highlights and selects the difference. This is a useful way to navigate and inspect long documents with many differences.</para>
</sect3>

<sect3 id="source-destination-view">
<title>Source and Destination View</title>
<para>The source and destination view is the main workspace of &kompare;. 
The contents and highlighted differences of the currently selected source and destination file are displayed here with line numbers..</para>
</sect3>

<sect3 id="text-view">
<title>Text View</title>
<para>The <guilabel>Text View</guilabel> is not displayed by default. It can be opened by selecting 
<menuchoice><guimenu>Settings</guimenu><guimenuitem>Show Text View</guimenuitem></menuchoice>.</para>
<!-- Other than a notepad, what is this text view good for?  -->
</sect3>

<sect3 id="statusbar">
<title>Statusbar</title>
<para>The status bar provides a summary of the current source and destination file or folder under comparison. 
The status bar also reports the number of changes found in the current document and counts the differences that have been applied. 
Furthermore, the status bar shows the overall number of documents containing differences and the current document number selected from this set. 
For example, a comparison run over two folders may return 1890 files with differences. The currently selected document is number 18 of 1890.</para>
</sect3>
</sect2>
</sect1>

<sect1 id="viewing-differences">
<title>Viewing Differences</title>

<sect2 id="managing-screen-real-estate">
<title>Managing Screen Real-Estate</title>
<para>&kompare; displays the source and destination file under using equal percentage of the main interface view work area. 
This view area provides some features that help optimize use of screen real-estate while viewing differences, including:</para>
<variablelist>
<varlistentry>
<term>Dual Scrollbars</term>
<listitem><para>The most obvious feature is that scrollbars are provided both on the right and bottom edges of the view area. 
Using the scrollbars it is possible to move rapidly through the comparison.</para></listitem>
</varlistentry>
<varlistentry>
<term>Share Grip Handle</term>
<listitem><para>The vertical space between the source and destination view not only makes it possible to clearly see the start and end of lines in each of the panes, 
but is also a grip handle that allows adjustment of percentage occupied between the source and destinate views that comprise the view pane. 
To change pane size for one of the views, hover the mouse pointer over the grip handle then hold down the mouse button and drag left or right. 
Naturally, increasing the area of one pane will decrease the area available to the opposite pane within the view panel area.</para></listitem>
</varlistentry>
<varlistentry>
<term>Docking</term>
<listitem><para>The main workspace can be undocked from the main interface by clicking the <guibutton>undock</guibutton> button located top right of the main workspace panel. 
This opens the main workspace in a window of its own, allowing it to be maximized and resized across the screen.</para></listitem>
</varlistentry>
<varlistentry>
<term>Statusbar Toggle</term>
<listitem>
<para>The status bar of the view panel can be toggled ON/OFF by selecting <menuchoice><guimenu>Settings</guimenu><guimenuitem>Hide/Show Statusbar</guimenuitem></menuchoice>.</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>

<sect2 id="switching-source-and-destination-view">
<title>Switching Source and Destination Views</title>

<para>Sometimes it can be useful to consider what the file to which differences where to be applied as the source. 
For example, when comparing two modified versions of a file and discovering that the one file has many more modifications that the other.
The file with more changed would be better as the source, since then fewer differences would need to be applied.</para>
<para>In this case select <menuchoice><guimenu>File</guimenu><guimenuitem>Swap Source with Destination</guimenuitem></menuchoice>. 
This will switch the files displayed in all &kompare; panels.</para>
</sect2>
	
<sect2 id="display-difference-statistics">
<title>Displaying Difference Statistics</title>
<para>For a quick overview of the differences, select <menuchoice><guimenu>File</guimenu><guimenuitem>Show Statistics</guimenuitem></menuchoice>. 
This will display the <guilabel>Diff Statistics</guilabel> dialog. The following information is provided:</para>
<variablelist>
<varlistentry>
<term><guilabel>Old file:</guilabel></term>
<listitem><para>The file name of what is usually the destination file or file that is unmodified and to which differences will be applied.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>New file:</guilabel></term>
<listitem><para>The file name of what is usually the source file or file that is modified.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Format:</guilabel></term>
<listitem><para>The diff format used to display the difference (see <xref linkend="diff-format"/>).</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Number of hunks:</guilabel></term>
<listitem>
<para>The number of hunks found in the difference.</para>
<para>A hunk is a <quote>c<emphasis>hunk</emphasis></quote> of lines that have been marked as different between 
source and destination and may include context lines depending on the diff format <guilabel>Lines of Context</guilabel> value (see <xref linkend="diff-format"/>).</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Number of differences</guilabel></term>
<listitem><para>The actual number of differences found, not hunks. A hunk can contain one or more differences 
when the line change range and the context lines of any two or more changes overlap.</para></listitem>
</varlistentry>
</variablelist>
</sect2>

<sect2 id="navigating-the-difference-view">
<title>Navigating the Difference View</title>
<para>&kompare; enables rapid navigation of differences on a file level and of multiple difference files when comparing folder trees.</para>

<sect3 id="selecting-a-difference">
<title>Selecting a Difference</title>
<para>A difference can be selected using by:</para>
<itemizedlist>
<listitem><para>clicking a line in the Source and Destination Line Changes pane (top right of the main window).</para></listitem>
<listitem><para>clicking the highlighted difference in the View pane.</para></listitem>
<listitem><para>traversing the listed differences in a comparison (see <xref linkend="traversing-differences"/>).</para></listitem>
</itemizedlist>
<para>When a difference is selected it is considered to be <quote>in focus</quote> and is displayed in a brighter color that non-selected differences.</para>
</sect3>
			
<sect3 id="traversing-differences">
<title>Traversing Differences</title>
<para>When a comparison finds many differences one of the best ways to approach reviewing them is to traverse the differences in a logical order, usually from top to bottom.</para>
<para>By default &kompare; selects the first difference found in a comparison. By selecting 
<menuchoice><guimenu>Difference</guimenu><guimenuitem>Next Difference</guimenuitem></menuchoice> 
(<keycombo action="simul">&Ctrl;<keycap>Down</keycap></keycombo>) the difference following the current selection is brought into focus. 
To select the difference before the current difference 
select <menuchoice><guimenu>Difference</guimenu><guimenuitem>Previous Difference</guimenuitem></menuchoice> 
(<keycombo action="simul">&Ctrl;<keycap>Up</keycap></keycombo>).</para>
<para>In this way it is possible to traverse differences in an orderly manner, applying and unapply differences upon review.</para>
</sect3>

<sect3 id="switching-between-files">
<title>Switching Between Files</title>
<para>When a comparison is performed on folder level, many files may be found with differences. 
A complete list of the files compared with difference found is provided in the <quote>Source and Destination Folders</quote>, 
and <quote>Source and Destination Files</quote> panes. However, &kompare; displays differences between source and destination one comparison at time.</para>
<para>To switch between documents in this scenario the following options are available:</para>
<itemizedlist>
<listitem><para>Select the <quote>Source and Destination Folders</quote> pane to display file differences found in the 
<quote>Source and Destination Files</quote> pane, then select a file.</para></listitem>
<listitem><para>Select <menuchoice><guimenu>Difference</guimenu><guimenuitem>Previous File</guimenuitem></menuchoice> 
(<keycombo action="simul">&Ctrl;<keycap>PageUp</keycap></keycombo>) or 
<menuchoice><guimenu>Difference</guimenu><guimenuitem>Next File</guimenuitem></menuchoice> 
(<keycombo action="simul">&Ctrl;<keycap>PageDown</keycap></keycombo>) to 
display the previous or next difference file found in the <quote>Source and Destination Files</quote> pane.</para>
</listitem>
</itemizedlist>
</sect3>
</sect2>
</sect1>

<sect1 id="merging-differences">
<title>Merging Differences</title>

<para>&kompare; makes the task of applying and unapplying differences as simple as point and click. 
Multiple apply and unapply operations can be performed on a difference as all operations are performed in memory and not written to the files on disk until the save operation is performed.</para>

<sect2 id="applying-a-difference">
<title>Applying a Difference</title>
<para>To apply a difference, click the highlighted difference region, then select 
<menuchoice><guimenu>Difference</guimenu><guimenuitem>Apply Difference</guimenuitem></menuchoice> (<keycombo><keycap>Space</keycap></keycombo>).</para>
</sect2>

<sect2 id="unapplying-a-difference">
<title>Unapplying a Difference</title>
<para>To unapply a difference, click the highlighted difference region previously applied, then select 
<menuchoice><guimenu>Difference</guimenu><guimenuitem>Unapply Difference</guimenuitem></menuchoice> (<keycombo><keycap>Backspace</keycap></keycombo>).</para>
</sect2>
	
<sect2 id="applying-all-differences">
<title>Applying All Differences</title>
<para>After reviewing differences between files and finding all acceptable it is possible apply them all with a single operation by selecting 
<menuchoice><guimenu>Difference</guimenu><guimenuitem>Apply All</guimenuitem></menuchoice> (<keycombo action="simul">&Ctrl;<keycap>A</keycap></keycombo>).</para>
</sect2>

<sect2 id="unapplying-all-differences">
<title>Unapplying All Differences</title>
<para>To differences that have been applied select 
<menuchoice><guimenu>Difference</guimenu><guimenuitem>Unapply All</guimenuitem></menuchoice> (<keycombo action="simul">&Ctrl;<keycap>U</keycap></keycombo>).</para>
</sect2>

<sect2 id="saving-changes">
<title>Saving Changes</title>
<para>Once differences have been applied they can be saved by selecting 
<menuchoice><guimenu>File</guimenu><guimenuitem>Save</guimenuitem></menuchoice> or 
<menuchoice><guimenu>File</guimenu><guimenuitem>Save All...</guimenuitem></menuchoice>.</para>
<para>Applied differences are saved to both the source and destination file.</para>
</sect2>
</sect1>

<sect1 id="working-with-diff-files">
<title>Working with Diff Files</title>
<para>Diff files contain only the changes made between files, or a set of files within a folder system, and may or may not contain a number of context lines before and after line changes. 
The sum of a line change and its context lines is known a hunk. A diff file therefore may contain multiple hunks from one or more files. 
When the context lines of two or more hunks overlap, they are considered a single hunk. Diff files can be used to:</para>
<itemizedlist>
<listitem><para>Apply the changes contained in the hunks to an original file.</para></listitem>
<listitem><para>Apply the changes contained in the hunks to a file or set of original files within a folder system.</para></listitem>
<listitem><para>Modified before being applied to an original file or set of original files within a folder system.</para></listitem>
</itemizedlist>

<sect2 id="creating-a-diff">
<title>Creating a Diff</title>
<para>To create a diff file a comparison must be displayed in &kompare;. Assuming this is the case, then select <menuchoice><guimenu>File</guimenu><guimenuitem>Save .diff</guimenuitem></menuchoice>. 
This will display the <guilabel>Diff Options</guilabel> dialog (see <xref linkend="diff-settings"/> for more information on diff formats and options). 
After configuring these options, click the <guibutton>Save</guibutton> button and save the diff to a file with the extension <filename class="extension">.diff</filename>.</para>
</sect2>

<sect2 id="displaying-a-diff">
<title>Displaying a Diff</title>
<para>It is possible to display the contents of a diff file within &kompare; by opening the diff file from <menuchoice><guimenu>File</guimenu><guimenuitem>Open Diff...</guimenuitem></menuchoice>.</para>
<para>When viewing a diff file the hunks between the source and destination file are shown, remember that only the hunks are shown, no unmodified lines will be shown. 
In some cases a diff file is created with 0 lines of context. In this case only the changed lines will be displayed.</para>
<para>When a diff file contains hunks from multiple files &kompare; displays the hunks from each file one at a time and you can 
switch between files as though they were real files even though this information is only provided by the diff file contents.</para>
</sect2>

<sect2 id="applying-a-diff">
<title>Applying Differences in a Diff File</title>
<para>When viewing differences in a diff file it is possible to apply difference as you would when comparing source and destination files (see <xref linkend="merging-differences"/>).</para>
</sect2>

<sect2 id="blending-a-diff">
<title>Blending a &URL; with a Diff</title>
<para>In cases where a diff file is provided it is possible to compare the hunks in the diff against a file or folder. 
To do this select <menuchoice><guimenu>File</guimenu><guimenuitem>Blend URL with Diff...</guimenuitem></menuchoice>. 
Then input the <guilabel>File/Folder</guilabel> and <guilabel>Diff Output</guilabel> paths.</para>
<para>When viewing differences between a source file and a diff file it is possible to apply difference as you would when comparing source and destination files (see <xref linkend="merging-differences"/>).</para>
</sect2>

</sect1>
</chapter>

<chapter id="configure-preferences">
<title>Configuring Preferences</title>

<para>&kompare; enables users to set appearance preferences for difference formatting in the main interface and set behavioural properties of the diff program. 
The <guilabel>Preferences</guilabel> dialog can be accessed by selecting 
<menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure &kompare;...</guisubmenu></menuchoice>.</para>

<para>To configure preferences for appearance select the <guilabel>View</guilabel> menu item (see <xref linkend="view-settings"/>).</para>

<para>To configure preferences for diff program properties select the <guilabel>Diff</guilabel> menu item (see <xref linkend="diff-settings"/>).</para>

<sect1 id="view-settings">
<title>View Settings</title>
<para>The <guimenu>View</guimenu> menu found on the <guilabel>Preferences</guilabel> dialog displays the <guilabel>Appearance</guilabel> 
and <guilabel>Fonts</guilabel> tabbed forms.</para>

<sect2 id="appearance">
<title>Appearance</title>
<para>The <guilabel>Appearance</guilabel> form provides controls to manage the <guilabel>Colors</guilabel> used 
to denote difference in the main interface, behaviour of the <guilabel>Mouse Wheel</guilabel> when jogging up and down 
and how <guilabel>Tabs to Spaces</guilabel> conversion is managed.</para>
<screenshot>
<screeninfo>&kompare; Appearance Settings</screeninfo>
    <mediaobject>
      <imageobject>
        <imagedata fileref="settings-view1.png" format="PNG"/>
      </imageobject>
        <textobject>
        <phrase>&kompare; Appearance Settings</phrase>
      </textobject>
    </mediaobject>
</screenshot>
<variablelist>
<title>Color Group</title>
<para>To adjust color preferences used when displaying differences, click the color button to display the <guilabel>Select Color</guilabel> dialog for the following states:</para>
<varlistentry>
<term><guilabel>Removed color</guilabel></term>
<listitem><para>Lines that have been removed, do not exist, between source and destination.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Changed color</guilabel></term>
<listitem><para>Lines that have been changed, modified, between source and destination. </para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Added color</guilabel></term>
<listitem><para>Lines that have been added between source and destination.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Applied color</guilabel></term>
<listitem><para>Any of the above states where the difference has been applied between source and destination.</para></listitem>
</varlistentry>
</variablelist>
<variablelist>
<title>Mouse Wheel</title>
<varlistentry>
<term><guilabel>Number of lines</guilabel></term>
<listitem><para>The number of lines to jog the differences when turning the mouse wheel forward or backward.</para></listitem>
</varlistentry>
</variablelist>
<variablelist>
<title>Tabs to Spaces</title>
<varlistentry>
<term><guilabel>Number of spaces to convert a tab character to</guilabel></term>
<listitem><para>Convert each tab character to n space characters.</para></listitem>
</varlistentry>
</variablelist>
</sect2>

<sect2 id="fonts">
<title>Fonts</title>
<screenshot>
<screeninfo>&kompare; Fonts Settings</screeninfo>
    <mediaobject>
      <imageobject>
        <imagedata fileref="settings-view2.png" format="PNG"/>
      </imageobject>
        <textobject>
        <phrase>&kompare; Fonts Settings</phrase>
      </textobject>
    </mediaobject>
</screenshot>
<para>Select the font family and size to display when displaying differences.</para>
</sect2>
</sect1>

<sect1 id="diff-settings">
<title>Diff Settings</title>
<para>The <guimenu>Diff</guimenu> menu found on the <guilabel>Preferences</guilabel> dialog displays the <guilabel>Diff</guilabel>, 
<guilabel>Format</guilabel>, <guilabel>Options</guilabel> and <guilabel>Exclude</guilabel> tabbed forms. These forms can be used to configure the 
behavioural properties of the Diff program.</para>

<sect2 id="diff">
<title>Diff</title>
<screenshot>
<screeninfo>&kompare; Diff Settings</screeninfo>
    <mediaobject>
      <imageobject>
        <imagedata fileref="settings-diff1.png" format="PNG"/>
      </imageobject>
        <textobject>
        <phrase>&kompare; Diff Settings</phrase>
      </textobject>
    </mediaobject>
</screenshot>
<para>The command used to run the diff program (default <application>diff</application>).</para>
</sect2>

<sect2 id="diff-format">
<title>Format</title>
<screenshot>
<screeninfo>&kompare; Format Settings</screeninfo>
    <mediaobject>
      <imageobject>
        <imagedata fileref="settings-diff2.png" format="PNG"/>
      </imageobject>
        <textobject>
        <phrase>&kompare; Format Settings</phrase>
      </textobject>
    </mediaobject>
</screenshot>
<para>Adjust options for the <guilabel>Output Format</guilabel> and number of <guilabel>Lines of Context</guilabel>.</para>
<variablelist>
<title>Output Format</title>
<varlistentry>
<term><guilabel>Context</guilabel></term>
<listitem>
<para>The context output format adds several lines of context around the lines that differ.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Ed</guilabel></term>
<listitem>
<para>diff can produce commands that direct the ed text editor to change the first file into the second file. 
Historically, this was the only output mode suitable for automatically editing one file into another. 
With the advent of <application>patch</application> this option is hardly ever used.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Normal</guilabel></term>
<listitem>
<para>The normal output format displays differing lines without any surrounding lines of context. </para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>RCS</guilabel></term>
<listitem>
<para>The RCS output format is designed specifically for use by the Revision Control System (<acronym>RCS</acronym>). 
Like Ed format, this format is rarely used since the <application>patch</application> program was introduced.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Unified</guilabel></term>
<listitem>
<para>The unified output format is a variation on the context format. It is considered better than context because the 
output is more compact than that of context as it omits redundant context lines.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Side-by-side</guilabel></term>
<listitem>
<para>Use the side by side output format which displays files listed in two columns with a gutter between them. This option is only available from the <guilabel>Diff Options</guilabel> dialog (see <xref linkend="creating-a-diff"/>).</para>
</listitem>
</varlistentry>
</variablelist>
<variablelist>
<title>Lines of Context</title>
<varlistentry>
<term><guilabel>Number of context lines</guilabel></term>
<listitem>
<para>When performing a diff with context or unified output format use this parameter to control the number of context lines included.</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>

<sect2 id="options">
<title>Options</title>
<screenshot>
<screeninfo>&kompare; OptionsSettings</screeninfo>
    <mediaobject>
      <imageobject>
        <imagedata fileref="settings-diff3.png" format="PNG"/>
      </imageobject>
        <textobject>
        <phrase>&kompare; Options Settings</phrase>
      </textobject>
    </mediaobject>
</screenshot>
<para>The <guilabel>Options</guilabel> tab form allows configuration of the options supported by the diff program.</para>
<variablelist>
<title>General</title>
<varlistentry>
<term><guilabel>Look for smaller changes</guilabel></term>
<listitem><para>Forces diff to display changes in case, punctuation, space, &etc; when checked.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Optimise for large files</guilabel></term>
<listitem><para>Switches diff to process files with high-speed when checked.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Ignore changes in case</guilabel></term>
<listitem><para>Lower and Uppercase character changes are omitted when this option is checked.</para></listitem>
</varlistentry>
</variablelist>
<variablelist>
<title>Ignore regexp</title>
<varlistentry>
<term><guilabel>Ignore regexp</guilabel></term>
<listitem><para>Ignore lines matching a regular expression.</para></listitem>
</varlistentry>
</variablelist>
<variablelist>
<title>Whitespace</title>
<varlistentry>
<term><guilabel>Expand tabs to spaces in output</guilabel></term>
<listitem><para>When checked diff outputs will converts tab characters to the number of spaces defined in the 
<guilabel>Preferences</guilabel> dialog <guimenu>View</guimenu> menu <guilabel>Tabs to Spaces</guilabel> option.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Ignore added or removed empty lines</guilabel></term>
<listitem><para>lines of zero length that differ between source and destination are ignored when this option is checked.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Ignore changes in the amount of whitespace</guilabel></term>
<listitem><para>White space before, after and between lines may change depending on different editors. 
When this option is checked such changes are ignored.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Ignore all whitespace</guilabel></term>
<listitem><para>when checked white space differences are completely ignored.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Ignore changes due to tab expansion</guilabel></term>
<listitem><para>when checked white space resulting from tab characters is ignored.</para></listitem>
</varlistentry>
</variablelist>
</sect2>

<sect2 id="exclude">
<title>Exclude</title>
<para>The <guilabel>Exclude</guilabel> form enables use of the filter options provided by the diff program.</para>
<screenshot>
<screeninfo>&kompare; Exclude Settings</screeninfo>
    <mediaobject>
      <imageobject>
        <imagedata fileref="settings-diff4.png" format="PNG"/>
      </imageobject>
        <textobject>
        <phrase>&kompare; Exclude Settings</phrase>
      </textobject>
    </mediaobject>
</screenshot>
<variablelist>
<title>File Pattern to Exclude</title>
<varlistentry>
<term><guilabel>File Pattern to Exclude</guilabel></term>
<listitem><para>Exclude files based on wild card filtering</para></listitem>
</varlistentry>
</variablelist>
<variablelist>
<title>File with Filenames to Exclude</title>
<varlistentry>
<term><guilabel>File with Filenames to Exclude</guilabel></term>
<listitem><para>Define the filter based on the content of an externally managed file.</para></listitem>
</varlistentry>
</variablelist>
</sect2>
</sect1>

</chapter>

<chapter id="command-reference">
<title>Command Reference</title>

<sect1 id="file-menu">
<title>The <guimenu>File</guimenu> Menu</title>
<variablelist>
<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;<keycap>O</keycap></keycombo>
</shortcut>
<guimenu>File</guimenu><guimenuitem>Open Diff...</guimenuitem></menuchoice></term>
<listitem><para>Displays the <guilabel>Open</guilabel> dialog.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;<keycap>C</keycap></keycombo>
</shortcut>
<guimenu>File</guimenu><guimenuitem>Compare Files...</guimenuitem></menuchoice></term>
<listitem><para>Displays the <guilabel>Compare Files or Folders</guilabel> dialog.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;<keycap>B</keycap></keycombo>
</shortcut>
<guimenu>File</guimenu><guimenuitem>Blend URL with Diff...</guimenuitem></menuchoice></term>
<listitem><para>Displays the <guilabel>Blend File/Folder with diff Output</guilabel> dialog.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;<keycap>S</keycap></keycombo>
</shortcut>
<guimenu>File</guimenu><guimenuitem>Save</guimenuitem></menuchoice></term>
<listitem><para>Writes applied differences to current source and or destination file.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice><guimenu>File</guimenu><guimenuitem>Save All</guimenuitem></menuchoice></term>
<listitem><para>Writes applied differences to all source and or destination files.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice><guimenu>File</guimenu><guimenuitem>Save .diff</guimenuitem></menuchoice></term>
<listitem><para>Displays the <guilabel>Diff Options</guilabel> dialog to define diff format and options.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice><guimenu>File</guimenu><guimenuitem>Swap Source with Destination</guimenuitem></menuchoice></term>
<listitem><para>Changes source and destination.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>File</guimenu><guimenuitem>Show Statistics</guimenuitem></menuchoice></term>
<listitem><para>Displays the <guilabel>Display Statistics</guilabel> dialog.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo>
</shortcut>
<guimenu>File</guimenu><guimenuitem>Quit</guimenuitem></menuchoice></term>
<listitem><para>Exits &kompare;.</para></listitem>
</varlistentry>
</variablelist>
</sect1>

<sect1 id="difference-menu">
<title>The <guimenu>Difference</guimenu> Menu</title>
<variablelist>
<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;<keycap>U</keycap></keycombo>
</shortcut>
<guimenu>Difference</guimenu><guimenuitem>Unapply All</guimenuitem></menuchoice></term>
<listitem><para>Unapply all differences previously applied between source and destination.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut><keycap>Backspace</keycap></shortcut>
<guimenu>Difference</guimenu><guimenuitem>Unapply Difference</guimenuitem></menuchoice></term>
<listitem><para>Revert a selected difference previously applied.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut><keycap>Space</keycap></shortcut>
<guimenu>Difference</guimenu><guimenuitem>Apply Difference</guimenuitem></menuchoice></term>
<listitem><para>Apply a selected difference.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;<keycap>A</keycap></keycombo>
</shortcut>
<guimenu>Difference</guimenu><guimenuitem>Apply All</guimenuitem></menuchoice></term>
<listitem><para>Apply all differences between source and destination.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;<keycap>PageUp</keycap></keycombo>
</shortcut>
<guimenu>Difference</guimenu><guimenuitem>Previous File</guimenuitem></menuchoice></term>
<listitem><para>Make the previous difference, in the list of differences, the current file in the view pane.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;<keycap>PageDown</keycap></keycombo>
</shortcut>
<guimenu>Difference</guimenu><guimenuitem>Next File</guimenuitem></menuchoice></term>
<listitem><para>Make the next difference, in the list of differences, the current file in the view pane.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;<keycap>Up</keycap></keycombo>
</shortcut>
<guimenu>Difference</guimenu><guimenuitem>Previous Difference</guimenuitem></menuchoice></term>
<listitem><para>Select the difference above the currently selected difference.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;<keycap>Down</keycap></keycombo>
</shortcut>
<guimenu>Difference</guimenu><guimenuitem>Next Difference</guimenuitem></menuchoice></term>
<listitem><para>Select the difference below the currently selected difference.</para></listitem>
</varlistentry>
</variablelist>
</sect1>

<sect1 id="settingsmenu">
<title>The <guimenu>Settings</guimenu> Menu</title>
<variablelist>
<varlistentry>
<term><menuchoice><guimenu>Settings</guimenu><guimenuitem>Hide/Show Toolbar</guimenuitem></menuchoice></term>
<listitem><para>Toggle the toolbar display ON/OFF.</para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice><guimenu>Settings</guimenu><guimenuitem>Show/Hide Statusbar</guimenuitem></menuchoice></term>
<listitem><para>Toggle the status bar display ON/OFF.</para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice><guimenu>Settings</guimenu><guimenuitem>Show Text View</guimenuitem></menuchoice></term>
<listitem><para>Display the <guilabel>Text View</guilabel> pane.</para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure Shortcuts...</guimenuitem></menuchoice></term>
<listitem><para>Display the <guilabel>Configure Shortcuts</guilabel> dialog.</para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure Toolbars...</guimenuitem></menuchoice></term>
<listitem><para>Display the <guilabel>Configure Toolbar</guilabel>.</para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure &kompare;...</guimenuitem></menuchoice></term>
<listitem><para>Display the &kompare; <guilabel>Preference</guilabel> dialog.</para></listitem>
</varlistentry>
</variablelist>
</sect1>

<sect1 id="help-menu">
<title>The <guimenu>Help</guimenu> Menu</title>

&help.menu.documentation;
</sect1>
</chapter>

<chapter id="credits">

<title>Credits and License</title>

<para>
&kompare;
</para>
<para>
Program copyright 2001-2004, &John.Firebaugh; &John.Firebaugh.mail;
and Otto Bruggeman<email>otto.bruggeman@home.nl</email>
</para>

<para>
Documentation Copyright &copy; 2007 Sean Wheller <email>sean@inwords.co.za</email>
</para>

<!-- TRANS:CREDIT_FOR_TRANSLATORS -->

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

</chapter>

<appendix id="installation">
<title>Installation</title>

<sect1 id="getting-kapp">
<title>How to obtain &kompare;</title>

&install.intro.documentation;

</sect1>


<sect1 id="compilation">
<title>Compilation and Installation</title>

&install.compile.documentation;

</sect1>


</appendix>

&documentation.index; 
</book>

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

// vim:ts=2:sw=2:tw=78:noet
-->