Mercurial > hg > easyhg-kdiff3
comparison kdiff3/doc/en/index.docbook @ 11:ce3ab464a615
KDiff3 version 0.9.70
(KDE's meinproc generates the html-files from this input file.)
| author | joachim99 |
|---|---|
| date | Mon, 06 Oct 2003 19:01:52 +0000 |
| parents | |
| children | c59d5a3a8ff3 |
comparison
equal
deleted
inserted
replaced
| 10:922a2b458fb2 | 11:ce3ab464a615 |
|---|---|
| 1 <?xml version="1.0" ?> | |
| 2 <!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.1.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ | |
| 3 <!ENTITY kdiff3 "<application>KDiff3</application>"> | |
| 4 <!ENTITY kappname "&kdiff3;"> | |
| 5 <!ENTITY package "kdeextragear-1"> | |
| 6 <!ENTITY % addindex "IGNORE"> | |
| 7 <!ENTITY % English "INCLUDE"> | |
| 8 ]> | |
| 9 | |
| 10 <book lang="&language;"> | |
| 11 | |
| 12 <!-- This header contains all of the meta-information for the document such | |
| 13 as Authors, publish date, the abstract, and Keywords --> | |
| 14 | |
| 15 <bookinfo> | |
| 16 <title>The &kdiff3; Handbook</title> | |
| 17 | |
| 18 <authorgroup> | |
| 19 <author> | |
| 20 <!--<personname>--> | |
| 21 <firstname>Joachim</firstname> | |
| 22 <surname>Eibl</surname> | |
| 23 <!--</personname>--> | |
| 24 <affiliation><address> | |
| 25 <email>joachim.eibl@gmx.de</email> | |
| 26 </address></affiliation> | |
| 27 </author> | |
| 28 </authorgroup> | |
| 29 | |
| 30 <!-- TRANS:ROLES_OF_TRANSLATORS --> | |
| 31 | |
| 32 <copyright> | |
| 33 <year>2002-2003</year> | |
| 34 <holder>Joachim Eibl</holder> | |
| 35 </copyright> | |
| 36 <!-- Translators: put here the copyright notice of the translation --> | |
| 37 <!-- Put here the FDL notice. Read the explanation in fdl-notice.docbook | |
| 38 and in the FDL itself on how to use it. --> | |
| 39 <legalnotice>&FDLNotice;</legalnotice> | |
| 40 | |
| 41 <!-- Date and version information of the documentation | |
| 42 Don't forget to include this last date and this last revision number, we | |
| 43 need them for translation coordination ! | |
| 44 Please respect the format of the date (YYYY-MM-DD) and of the version | |
| 45 (V.MM.LL), it could be used by automation scripts. | |
| 46 Do NOT change these in the translation. --> | |
| 47 | |
| 48 <date>2003-09-15</date> | |
| 49 <releaseinfo>0.9.70</releaseinfo> | |
| 50 | |
| 51 | |
| 52 <abstract> | |
| 53 <para></para> | |
| 54 <para> | |
| 55 &kdiff3; is a file and directory diff and merge tool which | |
| 56 <itemizedlist> | |
| 57 <listitem><para>compares and merges two or three text input files or directories,</para></listitem> | |
| 58 <listitem><para>shows the differences line by line and character by character(!),</para></listitem> | |
| 59 <listitem><para>provides an automatic merge-facility,</para></listitem> | |
| 60 <listitem><para>has an editor for comfortable solving of merge-conflicts,</para></listitem> | |
| 61 <listitem><para>provides networktransparency via KIO,</para></listitem> | |
| 62 <listitem><para>and is very colorful (by default) :-)</para></listitem> | |
| 63 </itemizedlist> | |
| 64 </para><para> | |
| 65 This document describes KDiff3-version 0.9.70. | |
| 66 </para> | |
| 67 </abstract> | |
| 68 | |
| 69 <!-- This is a set of Keywords for indexing by search engines. | |
| 70 Please at least include KDE, the KDE package it is in, the name | |
| 71 of your application, and a few relevant keywords. --> | |
| 72 | |
| 73 <keywordset> | |
| 74 <keyword>KDE</keyword> | |
| 75 <keyword>kdeextragear</keyword> | |
| 76 <keyword>kdiff3</keyword> | |
| 77 <keyword>diff</keyword> | |
| 78 <keyword>merge</keyword> | |
| 79 <keyword>CVS</keyword> | |
| 80 <keyword>triplediff</keyword> | |
| 81 <keyword>compare</keyword> | |
| 82 <keyword>files</keyword> | |
| 83 <keyword>directories</keyword> | |
| 84 <keyword>version control</keyword> | |
| 85 <keyword>three-way-merge</keyword> | |
| 86 <keyword>in-line-differences</keyword> | |
| 87 <keyword>synchronise</keyword> | |
| 88 <keyword>kpart</keyword> | |
| 89 <keyword>kio</keyword> | |
| 90 <keyword>networktransparent</keyword> | |
| 91 <keyword>editor</keyword> | |
| 92 </keywordset> | |
| 93 | |
| 94 </bookinfo> | |
| 95 | |
| 96 <chapter id="introduction"><title>Introduction</title> | |
| 97 <sect1 id="why"><title>Yet Another Diff Frontend?</title> | |
| 98 <para> | |
| 99 Several graphical diff tools exist. Why choose KDiff3? Let me say, why I wrote it. | |
| 100 </para><para> | |
| 101 KDiff3 started because I had to do a difficult merge. Merging is necessary when several | |
| 102 people work on the same files in a project. A merge can be somewhat automated, when the | |
| 103 merge-tool not only has the new modified files (called "branches"), but also the original file | |
| 104 (called "base"). The merge tool will automatically choose any modification that was only | |
| 105 done in one branch. When several contributors change the same lines, then the merge tool | |
| 106 detects a conflict which must be solved manually. | |
| 107 </para><para> | |
| 108 The merge then was difficult because one contributor had changed many things and corrected | |
| 109 the indentation in many places. Another contributor also had changed much text in the same file, | |
| 110 which resulted in several merge conflicts. | |
| 111 </para><para> | |
| 112 The tool I used then, only showed the changed lines, but not what had changed within these | |
| 113 lines. And there was no information about where only the indentation was changed. The merge | |
| 114 was a little nightmare. | |
| 115 </para><para> | |
| 116 So this was the start. The first version could show differences within a line and showed white space differences. | |
| 117 Later many other features were added to increase the usefulness. | |
| 118 </para><para> | |
| 119 For example if you want to compare some text quickly, then you can copy it to the clipboard and | |
| 120 paste it into either diff window. | |
| 121 </para><para> | |
| 122 A feature that required a big effort was the directory comparison and merge facility, which turned | |
| 123 the program almost into a full file browser. | |
| 124 </para><para> | |
| 125 I hope KDiff3 works for you too. Have fun! | |
| 126 </para><para> | |
| 127 Joachim Eibl (2003) | |
| 128 </para> | |
| 129 </sect1> | |
| 130 | |
| 131 <sect1 id="screenshots"><title>Screenshots and Features</title> | |
| 132 <para>This screenshot shows the difference between two text files</para> | |
| 133 <para>(Using an early version of KDiff3):</para> | |
| 134 <screenshot><mediaobject> | |
| 135 <imageobject><imagedata fileref="screenshot_diff.png" format="PNG"/></imageobject> | |
| 136 </mediaobject></screenshot> | |
| 137 | |
| 138 <para> | |
| 139 3-way-merging is fully supported. This is useful if two people change code independently. | |
| 140 The original file (the base) is used to help KDiff3 to automatically select the correct | |
| 141 changes. | |
| 142 The merge-editor below the diff-windows allows you to solve conflicts, while showing you the output you will get. | |
| 143 You can even edit the output. | |
| 144 This screenshot shows three input files being merged: | |
| 145 </para><para> | |
| 146 <screenshot><mediaobject> | |
| 147 <imageobject><imagedata fileref="screenshot_merge.png" format="PNG"/></imageobject> | |
| 148 </mediaobject></screenshot> | |
| 149 </para> | |
| 150 | |
| 151 <para id="dirmergebigscreenshot">KDiff3 also helps you to compare and merge complete directories. | |
| 152 This screenshot shows KDiff3 during a directory merge: | |
| 153 </para><para> | |
| 154 <screenshot><mediaobject> | |
| 155 <imageobject><imagedata fileref="dirmergebig.png" format="PNG"/></imageobject> | |
| 156 </mediaobject></screenshot> | |
| 157 </para> | |
| 158 </sect1> | |
| 159 | |
| 160 <sect1 id="features"><title>More Features</title> | |
| 161 <sect2><title> Line-By-Line And Char-By-Char Diff-Viewer</title> | |
| 162 <para>By using the possiblities of a graphical color display KDiff3 shows | |
| 163 exactly what the difference is. When you have to do many code-reviews, you will like this. | |
| 164 </para> | |
| 165 <screenshot><mediaobject> | |
| 166 <imageobject><imagedata fileref="letter_by_letter.png" format="PNG"/></imageobject> | |
| 167 </mediaobject></screenshot> | |
| 168 </sect2> | |
| 169 | |
| 170 <sect2><title> See White-Space Differences At One Glance</title> | |
| 171 <para>Spaces and tabs that differ appear visibly. When lines differ only | |
| 172 in the amount of white space this can be seen at one look in the summary | |
| 173 column on the left side. (No more worries when people change the indentation.) | |
| 174 </para> | |
| 175 <screenshot><mediaobject> | |
| 176 <imageobject><imagedata fileref="white_space.png" format="PNG"/></imageobject> | |
| 177 </mediaobject></screenshot> | |
| 178 </sect2> | |
| 179 | |
| 180 <sect2><title> Triple-Diff</title> | |
| 181 <para> Analyze three files and see where they differ. | |
| 182 </para><para> | |
| 183 The left/middle/right windows are named A/B/C and have the blue/green/magenta | |
| 184 color respectively. | |
| 185 </para><para> | |
| 186 If one file is the same and one file is different on a line then the | |
| 187 color shows which file is different. The red color means that both other | |
| 188 files are different. | |
| 189 </para> | |
| 190 <screenshot><mediaobject> | |
| 191 <imageobject><imagedata fileref="triple_diff.png" format="PNG"/></imageobject> | |
| 192 </mediaobject></screenshot> | |
| 193 </sect2> | |
| 194 | |
| 195 <sect2><title> Comfortable Merge Of Two Or Three Input Files</title> | |
| 196 <para> KDiff3 can be used to merge two or three input files and automatically | |
| 197 merges as much as possible. The result is presented in an editable window | |
| 198 where most conflicts can be solved with a single mouseclick: Select the | |
| 199 buttons A/B/C from the button-bar to select the source that should be used. | |
| 200 You can also select more than one source. Since this output window is an | |
| 201 editor even conflicts which need further corrections can be solved here without | |
| 202 requiring another tool. | |
| 203 </para> | |
| 204 </sect2> | |
| 205 | |
| 206 <sect2><title> And ...</title> | |
| 207 <itemizedlist> | |
| 208 <listitem><para> Fast navigation via buttons.</para></listitem> | |
| 209 <listitem><para> A mouse-click into a summary column sync's all windows to show the same position.</para></listitem> | |
| 210 <listitem><para> Select and copy from any window and paste into the merge result window.</para></listitem> | |
| 211 <listitem><para> Overview column that shows where the changes and conflicts are.</para></listitem> | |
| 212 <listitem><para> The colors are adjustable to your specific preferences.</para></listitem> | |
| 213 <listitem><para> Adjustable Tab size.</para></listitem> | |
| 214 <listitem><para> Option to insert spaces instead of tabs.</para></listitem> | |
| 215 <listitem><para> Open files comfortably via dialog or specify files on the command line.</para></listitem> | |
| 216 <listitem><para> Search for strings in all text windows. Find (Ctrl-F) and Find Next (F3)</para></listitem> | |
| 217 <listitem><para> Show the line numbers for each line. </para></listitem> | |
| 218 <listitem><para> Paste clipboard or drag text into a diff input window.</para></listitem> | |
| 219 <listitem><para> Networktransparency via KIO.</para></listitem> | |
| 220 <listitem><para> ...</para></listitem> | |
| 221 </itemizedlist> | |
| 222 </sect2> | |
| 223 </sect1> | |
| 224 </chapter> | |
| 225 | |
| 226 <chapter id="documentation"><title>Documentation of File Comparison And Merge</title> | |
| 227 | |
| 228 <sect1 id="commandline"><title>Command-Line Options</title> | |
| 229 | |
| 230 <sect2><title>Comparing 2 files: </title> | |
| 231 <screen> | |
| 232 <command>kdiff3</command> <replaceable>file1 file2</replaceable> | |
| 233 </screen> | |
| 234 </sect2> | |
| 235 | |
| 236 <sect2><title>Merging 2 files: </title> | |
| 237 <screen> | |
| 238 <command>kdiff3</command> <replaceable>file1 file2</replaceable> -m | |
| 239 <command>kdiff3</command> <replaceable>file1 file2</replaceable> -o <replaceable>outputfile</replaceable> | |
| 240 </screen> | |
| 241 </sect2> | |
| 242 | |
| 243 <sect2><title>Comparing 3 files: </title> | |
| 244 <screen> | |
| 245 <command>kdiff3</command> <replaceable>file1 file2 file3</replaceable> | |
| 246 </screen> | |
| 247 </sect2> | |
| 248 | |
| 249 <sect2><title>Merging 3 files: </title> | |
| 250 <screen> | |
| 251 <command>kdiff3</command> <replaceable>file1 file2 file3</replaceable> -m | |
| 252 <command>kdiff3</command> <replaceable>file1 file2 file3</replaceable> -o <replaceable>outputfile</replaceable> | |
| 253 </screen> | |
| 254 <para> | |
| 255 Note that <replaceable>file1</replaceable> will be treated as | |
| 256 base of <replaceable>file2</replaceable> and | |
| 257 <replaceable>file3</replaceable>. | |
| 258 </para> | |
| 259 </sect2> | |
| 260 | |
| 261 <sect2><title>Special case: Files with the same name </title> | |
| 262 <para> | |
| 263 If all files have the same name but are in different directories, you can | |
| 264 reduce typework by specifying the filename only for the first file. E.g.: | |
| 265 </para> | |
| 266 <screen> | |
| 267 <command>kdiff3</command> <replaceable>dir1/filename dir2 dir3</replaceable> | |
| 268 </screen> | |
| 269 </sect2> | |
| 270 | |
| 271 <sect2><title>Commandline for starting a directory comparison or merge: </title> | |
| 272 <para>This is very similar, but now it's about directories.</para> | |
| 273 <screen> | |
| 274 <command>kdiff3</command> <replaceable>dir1 dir2</replaceable> | |
| 275 <command>kdiff3</command> <replaceable>dir1 dir2</replaceable> -o <replaceable>destdir</replaceable> | |
| 276 <command>kdiff3</command> <replaceable>dir1 dir2 dir3</replaceable> | |
| 277 <command>kdiff3</command> <replaceable>dir1 dir2 dir3</replaceable> -o <replaceable>destdir</replaceable> | |
| 278 </screen> | |
| 279 <para>For directory comparison and merge you can continue to read <link linkend="dirmerge">here</link>.</para> | |
| 280 </sect2> | |
| 281 | |
| 282 <sect2><title>For more information on command line options use: </title> | |
| 283 <screen> | |
| 284 <command>kdiff3</command> --help | |
| 285 </screen> | |
| 286 </sect2> | |
| 287 | |
| 288 </sect1> | |
| 289 | |
| 290 <sect1 id="opendialog"><title>Open-Dialog</title> | |
| 291 <para> | |
| 292 Since many input files must be selectable, the program has a special open dialog: | |
| 293 </para> | |
| 294 <screenshot><mediaobject> | |
| 295 <imageobject><imagedata fileref="open_dialog.png" format="PNG"/></imageobject> | |
| 296 </mediaobject></screenshot> | |
| 297 <para> | |
| 298 The open dialog allows to edit the filenames by hand, selecting a file | |
| 299 via the file-browser ("File...") or allows to choose recent files from | |
| 300 the drop-down lists. If you open the dialog again, then the current names | |
| 301 still remain there. The third input file is not required. If the | |
| 302 entry for "C" remains empty, then only a two file diff analysis will be | |
| 303 done. | |
| 304 </para><para> | |
| 305 You can also select a directory via "Dir...". If for A a directory is specified | |
| 306 then a directory-comparison/merge starts. If A specifies a file but B, C or | |
| 307 the output specify a directory, then KDiff3 uses the filename from A in the | |
| 308 specified directories. | |
| 309 </para><para> | |
| 310 If "Merge" is selected, then the "Output"-line becomes editable. But it | |
| 311 is not required to specify the output filename immediately. You can also | |
| 312 postpone this until saving. | |
| 313 </para><para> | |
| 314 The "Configure..."-button opens the options-dialog, so that you can set | |
| 315 the options before running the analysis. | |
| 316 </para> | |
| 317 </sect1> | |
| 318 | |
| 319 <sect1 id="pasteinput"><title>Paste and Drop Input</title> | |
| 320 <para> | |
| 321 Sometimes you want to compare parts of a text that is not an own file. KDiff3 also | |
| 322 allows you to paste text from the clipboard into the diff input window that has the focus. | |
| 323 The diff analysis happens immediately then. | |
| 324 In the open dialog you need not specify files then, but just close it via "Cancel". | |
| 325 </para><para> | |
| 326 You can also use drag and drop: Drag a file from a file manager | |
| 327 or selected text from an editor and drop it onto a diff input window. | |
| 328 </para><para> | |
| 329 What's the idea? Sometimes a file contains two similar functions, but checking how similar | |
| 330 they really are is a big effort if you first must create two files and then load them. Now | |
| 331 you can simply copy, paste and compare the relevant sections. | |
| 332 </para><para> | |
| 333 Note: Currently you can't drag anything from KDiff3. Only dropping in the diff input | |
| 334 is supported. | |
| 335 </para><para> | |
| 336 Warning: Some editors still interpret the drag and drop into another program like cut | |
| 337 (instead of copy) and paste. Your original data might be lost then. | |
| 338 </para> | |
| 339 </sect1> | |
| 340 | |
| 341 <sect1 id="interpretinginformation"><title>Interpreting The Information In The Input Windows</title> | |
| 342 <screenshot><mediaobject> | |
| 343 <imageobject><imagedata fileref="screenshot_diff.png" format="PNG"/></imageobject> | |
| 344 </mediaobject></screenshot> | |
| 345 <para> | |
| 346 At the top of each text window is its "info line". The info lines of | |
| 347 the input windows contain a letter "A", "B" or "C", the filename and the | |
| 348 line number of the first visible line in the window. (Note that window | |
| 349 "C" is optional.) Each info line appears in a different color. (If the paths | |
| 350 are too long to fit, then you can move the mouse onto the info line and | |
| 351 a tooltip will show the complete name.) | |
| 352 </para><para> | |
| 353 The three input windows are assigned the letters "A", "B" and "C". | |
| 354 "A" has color blue, "B" has green and "C" has magenta. (These are the | |
| 355 defaults, but can be changed in the Settings-Menu.) | |
| 356 </para><para> | |
| 357 When a difference is detected then the color shows which input file | |
| 358 differs. When both other input files differ then the color used to express | |
| 359 this is red by default ("Conflict color" in the Settings). | |
| 360 This colorscheme is especially useful in the case of three input files, which will be | |
| 361 seen in the next section (<link linkend="merging">Merging</link>). | |
| 362 </para><para> | |
| 363 Left of each text is the "summary column". If differences occurred on a | |
| 364 line then the summary column shows the respective color. For a white-space-only | |
| 365 difference the summary is chequered. For programming languages where white | |
| 366 space is not so important this is useful to see at one glance if anything | |
| 367 of importance was modified. (In C/C++ white space is only interesting within | |
| 368 strings, comments, for the preprocessor, and some only very esoteric situations.) | |
| 369 </para><para> | |
| 370 The vertical line separating the summary column and the text is interrupted | |
| 371 if the input file had no lines there. | |
| 372 </para><para> | |
| 373 On the right side a "overview"-column is visible left of the vertical scrollbar. | |
| 374 It shows the compressed summary column of input "A". All the differences | |
| 375 and conflicts are visible at one glance. When only two input windows are | |
| 376 used, then all differences appear red here because every difference is | |
| 377 also a conflict. A black rectangle frames the visible part of the inputs. | |
| 378 For very long input files, when the number of input lines is bigger than | |
| 379 the height of the overview column in pixels, then several input lines share | |
| 380 one overview line. A conflict then has top priority over simple differences, | |
| 381 which have priority over no change, so that no difference or conflict is | |
| 382 lost here. By clicking into this overview column the corresponding text | |
| 383 will be shown. | |
| 384 </para> | |
| 385 </sect1> | |
| 386 | |
| 387 | |
| 388 <sect1 id="merging"><title>Merging And The Merge Output Editor Window</title> | |
| 389 <screenshot><mediaobject> | |
| 390 <imageobject><imagedata fileref="screenshot_merge.png" format="PNG"/></imageobject> | |
| 391 </mediaobject></screenshot> | |
| 392 <para> | |
| 393 The merge output editor window (below the diff input windows) also has an info line at the top showing "Output:", the | |
| 394 filename and "[Modified]" if you edited something. Usually it will contain | |
| 395 some text through the automatic merge facilities, but often it will also | |
| 396 contain conflicts. | |
| 397 </para><para> | |
| 398 !!! Saving is disabled until all conflicts are resolved !!! (Use the "Go | |
| 399 to prev/next unsolved conflicts"-buttons to find the remaining conflicts.) | |
| 400 </para><para> | |
| 401 With only two input files every difference is also a conflict that must | |
| 402 be solved manually. | |
| 403 </para><para> | |
| 404 With three input files the first file is treated as base, while the | |
| 405 second and third input files contain modifications. When at any line only | |
| 406 either input B or input C have changed but not both then the changed source | |
| 407 will automatically be selected. Only when B and C have changed on the same | |
| 408 lines, then the tool detects a conflict that must be solved manually. | |
| 409 When B and C are the same, but not the same as A, then C is selected. | |
| 410 </para><para> | |
| 411 The merge output editor window also has a summary column on the left. It shows the | |
| 412 letter of the input from which a line was selected or nothing if all three | |
| 413 sources where equal on a line. For conflicts it shows a questionmark "?" | |
| 414 and the line shows "<Merge Conflict>", all in red. Because solving | |
| 415 conflicts line by line would take very long, the lines are grouped into | |
| 416 groups that have the same difference and conflict characteristics. | |
| 417 But only-white-space-conflicts are separated from non-white-space-conflicts | |
| 418 in order to ease the merging of files were the indentation changed for many | |
| 419 lines. | |
| 420 </para><para> | |
| 421 When clicking into the summary column with the left mouse button in either | |
| 422 window then the group belonging to that line will be selected in all windows | |
| 423 and the beginning of that group will be shown. (This might involve an automatic | |
| 424 position jump in the windows if the beginning of a group is not visible.) | |
| 425 This group then becomes the "current group". It is highlighted with the | |
| 426 "Current range (diff) background color" and | |
| 427 a black bar appears on the left side of the text. | |
| 428 </para><para> | |
| 429 Note the input selector buttons containing the letters "A", "B" and | |
| 430 "C" in the button bar below the menu bar. When clicking on either input | |
| 431 selector button, the lines from that input will be added at the end of the | |
| 432 selected group if that group didn't contain that source before. Otherwise | |
| 433 the lines from that input will be removed. | |
| 434 </para><para> | |
| 435 Besides, you can directly edit any line. The summary column will show "m" | |
| 436 for every line that was modified. | |
| 437 </para><para> | |
| 438 Sometimes, when a line is removed either by automatic merge or by editing | |
| 439 and no other lines remain in that group, then the text <No src line> | |
| 440 will appear in that line. This is just a placeholder for the group for | |
| 441 when you might change your mind and select some source again. This text won't | |
| 442 appear in the saved file or in any selections you want to copy and paste. | |
| 443 </para><para> | |
| 444 The text "<Merge Conflict>" will appear in the clipboard if you | |
| 445 copy and paste some text containing such a line. But still be careful to | |
| 446 do so. | |
| 447 </para><para> | |
| 448 The "Merge" menu contains some actions that let you select "A", "B" or | |
| 449 "C" everywhere. When you select "Automatically solve simple conflicts" then | |
| 450 KDiff3 restarts the merge and solves as many conflicts as it can. "Set deltas | |
| 451 to conflicts" does the opposite: Even simple conflicts have to be solved | |
| 452 manually then. For all these actions the manual selections that happened | |
| 453 before are lost. (KDiff3 will tell you so, before proceeding.) | |
| 454 </para> | |
| 455 </sect1> | |
| 456 | |
| 457 <sect1 id="navigation"><title>Navigation And Editing</title> | |
| 458 <para> | |
| 459 Much navigation will be done with the scroll bars and the mouse but | |
| 460 you can also navigate with the keys. If you click into either window then | |
| 461 you can use the cursor buttons left, right, up, down, page up, page down, | |
| 462 home, end, ctrl-home, ctrl-end as you would in other programs. The overview-column | |
| 463 next to the vertical scroll bar of the input files can also be used for | |
| 464 navigating by clicking into it. | |
| 465 </para><para> | |
| 466 You can also use the wheel mouse to scroll up and down. | |
| 467 </para><para> | |
| 468 In the merge output editor you can also use the other keys for editing. | |
| 469 You can toggle between insert and overwrite mode with the insert key. (Default | |
| 470 is insert-mode.) | |
| 471 </para><para> | |
| 472 A left-mouse-button-click into any summary column will synchronise all | |
| 473 windows to show the beginning of the same group of lines (as explained | |
| 474 in section <link linkend="merging">"Merging"</link>). | |
| 475 </para><para> | |
| 476 The button bar also contains seven navigation buttons with which you can | |
| 477 jump to the current/first/last difference, to the next/previous difference | |
| 478 (ctrl-down/ctrl-up), to the next/previous conflict (ctrl-pgdown/ctrl-pgup), | |
| 479 or to the next/previous unsolved conflict. Note that for KDiff3 a "conflict" | |
| 480 that was not automatically solved at the start of the merge stays a "conflict" | |
| 481 even if it is solved. Hence the necessity to distinguish "unsolved conflicts". | |
| 482 </para><para> | |
| 483 There also is a button "Automatically go to next unsolved conflict after | |
| 484 source selection" (Auto-Advance). If you enable this, then, when one source | |
| 485 is selected, then KDiff3 will jump to and select the next unsolved conflict | |
| 486 automatically. This can help when you always want to choose one source only. | |
| 487 When you need both sources, or you want to edit after selecting, then you | |
| 488 probably want to switch this off. Before proceeding to the next unsolved conflict | |
| 489 KDiff3 shows you the effect of your choice for a short time. This delay is | |
| 490 adjustable in the Diff- & Merge-Settings: You can | |
| 491 specify the "Auto-Advance delay" in milli seconds between 0 and 2000. Hint: | |
| 492 Tired of many clicks? - Use a small Auto-Advance-delay and the shortcuts | |
| 493 Ctrl-1/2/3 to select A/B/C for many conflicts. | |
| 494 </para> | |
| 495 </sect1> | |
| 496 | |
| 497 <sect1 id="selections"><title>Select, Copy And Paste</title> | |
| 498 <para> | |
| 499 The input windows don't show a cursor, so selections must be made | |
| 500 with the mouse by clicking with the left mouse button at the start, holding | |
| 501 down the mousebutton and moving to the end, where you release the mouse | |
| 502 button again. You can also select a word by double clicking it. In the merge | |
| 503 output editor you can also select via the keyboard by holding the "shift"-button | |
| 504 and navigation with the cursor keys. | |
| 505 </para><para> | |
| 506 To copy to the clipboard you must press the "Copy"-button (Ctrl-C or Ctrl-Insert). | |
| 507 But there exists an option "Auto Copy Selection". If this is enabled, | |
| 508 then whatever you select is copied immediately and you don't need to explicitely | |
| 509 copy. But pay attention when using this because the contents of the clipboard | |
| 510 might then be destroyed accidentally. | |
| 511 </para><para> | |
| 512 "Cut" (Ctrl-X or Shift-Delete) copies to the clipboard and deletes the | |
| 513 selected text and "Paste" (Ctrl-V or Shift-Insert) inserts the text in | |
| 514 the clipboard at the cursorposition or over the current selection. | |
| 515 </para> | |
| 516 </sect1> | |
| 517 | |
| 518 <sect1 id="saving"><title>Saving</title> | |
| 519 <para> | |
| 520 Saving will only be allowed, when all conflicts were solved. If the file | |
| 521 already exists and the "Backup files"-option is enabled then the existing | |
| 522 file will be renamed with an ".orig"-extension, but if such a file exists | |
| 523 it will be deleted. When you exit or start another diff-analysis and data | |
| 524 wasn't saved yet, then KDiff3 will ask if you want to save, cancel or proceed | |
| 525 without saving. (KDiff3 does not catch any signals. So if you "kill" KDiff3 | |
| 526 then your data will be lost.) | |
| 527 </para><para> | |
| 528 Line endings are saved according to the normal method on the underlying | |
| 529 operating system. For Unices each line ends with an linefeed-character "\n", | |
| 530 while for Win32-based systems each line ends with a carriage-return + a linefeed | |
| 531 "\r\n". KDiff3 does not preserve the line-endings of the input files, which | |
| 532 also means that you shouldn't use KDiff3 with binary files. | |
| 533 </para> | |
| 534 </sect1> | |
| 535 | |
| 536 <sect1 id="find"><title>Finding Strings</title> | |
| 537 <para> | |
| 538 You can search for a string in any text-window of KDiff3. The "Find ..."-command | |
| 539 (Ctrl-F) in the Edit-menu opens a dialog that lets you specify the string | |
| 540 to search for. You can also select the windows which should be searched. | |
| 541 Searching will always start at the top. Use the "Find Next"-command (F3) | |
| 542 to proceed to the next occurance. If you select to search several windows then the first | |
| 543 window will be searched from top to bottom before the search starts in the next | |
| 544 window at the top again, etc. | |
| 545 </para> | |
| 546 </sect1> | |
| 547 | |
| 548 | |
| 549 <sect1 id="options"><title>Options</title> | |
| 550 <para> | |
| 551 Options and the recent-file-list will be saved when you exit the program, | |
| 552 and reloaded when you start it. (Menu Settings->Configure KDiff3 ...) | |
| 553 </para> | |
| 554 <sect2><title>Font</title> | |
| 555 <para> | |
| 556 Select a fixed width font. (On some systems this dialog will also | |
| 557 present variable width fonts, but you should not use them.) | |
| 558 </para> | |
| 559 <variablelist> | |
| 560 <varlistentry><term><emphasis>Italic Font for Deltas:</emphasis></term><listitem><para> If you select this, then text differences | |
| 561 will be drawn with the italic version of the selected font. If the font | |
| 562 doesn't support italic, then this does nothing.</para> | |
| 563 </listitem></varlistentry> | |
| 564 </variablelist> | |
| 565 </sect2> | |
| 566 | |
| 567 <sect2><title>Colors</title> | |
| 568 <variablelist> | |
| 569 <varlistentry><term><emphasis>Foreground color:</emphasis></term><listitem><para> Usually black. </para></listitem></varlistentry> | |
| 570 <varlistentry><term><emphasis>Background color:</emphasis></term><listitem><para> Usually white. </para></listitem></varlistentry> | |
| 571 <varlistentry><term><emphasis>Diff Background color:</emphasis></term><listitem><para> Usually light gray. </para></listitem></varlistentry> | |
| 572 <varlistentry><term><emphasis>Color A:</emphasis></term><listitem><para> Usually dark blue. </para></listitem></varlistentry> | |
| 573 <varlistentry><term><emphasis>Color B:</emphasis></term><listitem><para> Usually dark green. </para></listitem></varlistentry> | |
| 574 <varlistentry><term><emphasis>Color C:</emphasis></term><listitem><para> Usually dark magenta. </para></listitem></varlistentry> | |
| 575 <varlistentry><term><emphasis>Conflict Color:</emphasis></term><listitem><para> Usually red.</para></listitem></varlistentry> | |
| 576 <varlistentry><term><emphasis>Current range background color:</emphasis></term><listitem><para> Usually light yellow.</para></listitem></varlistentry> | |
| 577 <varlistentry><term><emphasis>Current range diff background color:</emphasis></term><listitem><para> Usually dark yellow.</para></listitem></varlistentry> | |
| 578 </variablelist> | |
| 579 <para> | |
| 580 On systems with only 16 or 256 colors some colors are not available in pure | |
| 581 form. On such systems the "Defaults"-button will choose a pure color. | |
| 582 </para> | |
| 583 </sect2> | |
| 584 | |
| 585 <sect2><title>Editor Settings</title> | |
| 586 <variablelist> | |
| 587 <varlistentry><term><emphasis>Tab inserts spaces:</emphasis></term><listitem><para> If this is disabled and you press the | |
| 588 tabulator key, a tab-character is inserted, otherwise the appropriate | |
| 589 amount of characters is inserted.</para></listitem></varlistentry> | |
| 590 <varlistentry><term><emphasis> Tab size:</emphasis></term><listitem><para> Can be adjusted for your specific needs. Default is 8. </para></listitem></varlistentry> | |
| 591 <varlistentry><term><emphasis> Auto indentation:</emphasis></term><listitem><para> When pressing Enter or Return the indentation | |
| 592 of the previous line is used for the new line. </para></listitem></varlistentry> | |
| 593 <varlistentry><term><emphasis> Auto copy selection:</emphasis></term><listitem><para> Every selection is immediately copied | |
| 594 to the clipboard when active and you needn't explicitely copy it. </para></listitem></varlistentry> | |
| 595 </variablelist> | |
| 596 </sect2> | |
| 597 | |
| 598 <sect2><title>Diff & Merge Settings</title> | |
| 599 <para> | |
| 600 When comparing files, KDiff3 first it tries to match lines that are equal | |
| 601 in all input files. Only during this step it might ignore white space. The | |
| 602 second step compares each line. In this step white space will not be ignored. | |
| 603 Also during the merge white space will not be ignored. | |
| 604 </para> | |
| 605 | |
| 606 <variablelist> | |
| 607 <varlistentry><term><emphasis>Ignore white space:</emphasis></term><listitem><para> Default is on. White space will be | |
| 608 ignored in the first part of the analysis in which the line matching is | |
| 609 done. In the result the white space differences will be shown nevertheless. | |
| 610 </para></listitem></varlistentry> | |
| 611 <varlistentry><term><emphasis>Preserve Carriage Return:</emphasis></term><listitem><para> Some editors (on some systems) save | |
| 612 carriage return '\r' and linefeed '\n'-characters at the end of line, while | |
| 613 others will only save the linefeed '\n'. Usually KDiff3 ignores the carriage | |
| 614 return, but then files that don't have equal sizes, look equal in side by | |
| 615 side comparison. When this option is on, then the carriage return characters | |
| 616 are made visible but are treated as white space. This option must be off | |
| 617 during a merge. Default is off.</para></listitem></varlistentry> | |
| 618 <varlistentry><term><emphasis>Ignore numbers:</emphasis></term><listitem><para> Default is off. Number characters ('0'-'9', '.', '-') | |
| 619 will be ignored in the first part of the analysis in which the line matching is | |
| 620 done. In the result the differences will be shown nevertheless, but they are treated | |
| 621 as white space. | |
| 622 </para></listitem></varlistentry> | |
| 623 <varlistentry><term><emphasis>Convert to Upper Case:</emphasis></term><listitem><para> Default is off. Converts the input to upper case | |
| 624 while reading. Hence the comparison is not case sensitive. Take care during merging | |
| 625 because the case information will be lost in the merge-result too. | |
| 626 </para></listitem></varlistentry> | |
| 627 <varlistentry><term><emphasis>Preprocessor-Command:</emphasis></term><listitem><para> | |
| 628 When any file is read, it will be piped through this external command. | |
| 629 The output of this command will be visible instead of the original file. | |
| 630 You can write your own preprocessor that fulfills your specific needs. | |
| 631 Use this to cut away disturbing parts of the file, or to automatically | |
| 632 correct the indentation etc. | |
| 633 </para></listitem></varlistentry> | |
| 634 <varlistentry><term><emphasis>Line-Matching Preprocessor-Command:</emphasis></term><listitem><para> | |
| 635 When any file is read, it will be piped through this external command. If | |
| 636 a preprocessor-command (see above) is also specified, then the output of the | |
| 637 preprocessor is the input of the line-matching preprocessor. | |
| 638 The output will only be used during the line matching phase of the analysis. | |
| 639 You can write your own preprocessor that fulfills your specific needs. | |
| 640 Each input line must have a corresponding output line. | |
| 641 </para></listitem></varlistentry> | |
| 642 <varlistentry><term><emphasis>Use external diff:</emphasis></term><listitem><para> If you have an external diff-tool (e.g. GNU-diff) | |
| 643 you can use it for the line matching phase. For some complicated files this | |
| 644 might be better than the internal algorithm of KDiff3. | |
| 645 </para></listitem></varlistentry> | |
| 646 <varlistentry><term><emphasis>Try Hard:</emphasis></term><listitem><para> Passes the "--minimal"-option to the external diff | |
| 647 tool, which then will try hard to find an even smaller delta. This will probably | |
| 648 be effective for complicated and big files. And slow for very big files. | |
| 649 </para></listitem></varlistentry> | |
| 650 <varlistentry><term><emphasis>Ignore trivial matches:</emphasis></term><listitem><para> Default is on. When trivial lines | |
| 651 match after an difference, this will be ignored and the search for a nontrivial | |
| 652 matching line continues. This improves the results for inputs with empty | |
| 653 lines and lines containing only a open or close-brace character, which is | |
| 654 often the case for C/C++-programs. | |
| 655 </para></listitem></varlistentry> | |
| 656 <varlistentry><term><emphasis>Max search length:</emphasis></term><listitem><para> Searching for a match is aborted after this | |
| 657 number of lines. The diff might fail for small values but take too long | |
| 658 for big values. Default is 1000. | |
| 659 </para></listitem></varlistentry> | |
| 660 <varlistentry><term><emphasis>Auto Advance Delay (ms):</emphasis></term><listitem><para> When in auto-advance-mode this setting specifies | |
| 661 how long to show the result of the selection before jumping to the next unsolved | |
| 662 conflict. | |
| 663 </para></listitem></varlistentry> | |
| 664 </variablelist> | |
| 665 | |
| 666 </sect2> | |
| 667 | |
| 668 <sect2><title>Directory Merge</title> | |
| 669 <para> | |
| 670 These options are concerned with scanning the directory and handling the | |
| 671 merge: See the <link linkend="dirmergeoptions">Directory Comparison/Merge | |
| 672 Docs</link> for details. | |
| 673 </para><para> | |
| 674 Yet there is one option here that is also relevant for saving single files: | |
| 675 </para> | |
| 676 <variablelist> | |
| 677 <varlistentry><term><emphasis>Backup files:</emphasis></term><listitem><para> When a file is saved and an older version already | |
| 678 exists, then the original version will be renamed with an ".orig" extension. | |
| 679 If an old backup file with ".orig" extension already exists then this will | |
| 680 be deleted without backup. | |
| 681 </para></listitem></varlistentry> | |
| 682 </variablelist> | |
| 683 </sect2> | |
| 684 | |
| 685 <sect2><title>Miscellaneous</title> | |
| 686 <para>(These options and actions are available in menus or the buttonbar.)</para> | |
| 687 <variablelist> | |
| 688 <varlistentry><term><emphasis>Show line numbers:</emphasis></term><listitem><para> You can select if line numbers should be | |
| 689 shown for the input files.</para></listitem></varlistentry> | |
| 690 <varlistentry><term><emphasis>Show space and tabulator characters for differences:</emphasis></term><listitem><para> Sometimes | |
| 691 the visible spaces and tabs are disturbing. You can turn this off.</para></listitem></varlistentry> | |
| 692 <varlistentry><term><emphasis>Show Window A/B/C:</emphasis></term><listitem><para> Sometimes you want to use the space on | |
| 693 the screen better for long lines. Hide the windows that are not important. | |
| 694 (In the Windows-menu.)</para></listitem></varlistentry> | |
| 695 <varlistentry><term><emphasis>Toggle Split Orientation:</emphasis></term><listitem><para> | |
| 696 Switch between diff windows shown next to each other (A left of B left of C) or above | |
| 697 each other (A above B above C). This should also help for long lines. (In the Windows-menu.) | |
| 698 </para></listitem></varlistentry> | |
| 699 <varlistentry><term><emphasis>Start a merge quickly:</emphasis></term><listitem><para> Sometimes you are viewing the deltas | |
| 700 and decide to merge. <inlinemediaobject><imageobject><imagedata fileref="merge_current.png" format="PNG"/></imageobject></inlinemediaobject> | |
| 701 "Merge current file" in the Directory-menu also works if you only compare | |
| 702 two files. A single click starts the merge and uses the filename of the last | |
| 703 input-file as the default output filename. (When this is used to restart | |
| 704 a merge, then the output filename will be preserved.)</para></listitem></varlistentry> | |
| 705 </variablelist> | |
| 706 </sect2> | |
| 707 | |
| 708 <sect2 id="shortcuts"><title>Configuring Keyboard-Shortcuts</title> | |
| 709 <para> | |
| 710 Currently only the KDE-version supports user-configurable keyboard-shortcuts. | |
| 711 (Menu Settings->Configure Shortcuts...) | |
| 712 </para> | |
| 713 </sect2> | |
| 714 </sect1> | |
| 715 </chapter> | |
| 716 | |
| 717 | |
| 718 <chapter id="dirmerge"><title>Directory Comparison and Merge with KDiff3</title> | |
| 719 <sect1 id="dirmergeintro"><title>Introduction</title> | |
| 720 <para> | |
| 721 Often programmers must modify many files in a directory to achieve their | |
| 722 purpose. For this KDiff3 also lets you compare and merge complete directories | |
| 723 recursively! | |
| 724 </para><para> | |
| 725 Even though comparing and merging directories seems to be quite obvious, | |
| 726 there are several details that you should know about. Most important is of | |
| 727 course the fact that now many files might be affected by each operation. | |
| 728 If you don't have backups of your original data, then it can be very hard | |
| 729 or even impossible to return to the original state. So before starting a merge, | |
| 730 make sure that your data is safe, and going back is possible. If you make | |
| 731 an archive or use some version control system is your decision, but even | |
| 732 experienced programmers and integrators need the old sources now and then. | |
| 733 And note that even though I (the author of KDiff3) try to do my best, I can't | |
| 734 guarantee that there are no bugs. According to the GNU-GPL there is NO WARRANTY | |
| 735 whatsoever for this program. So be humble and always keep in mind: | |
| 736 </para> | |
| 737 <blockquote><para> | |
| 738 <emphasis>To err is human, but to really mess things up you need a computer.</emphasis> | |
| 739 </para></blockquote> | |
| 740 <para> | |
| 741 So this is what this program can do for you: KDiff3 ... | |
| 742 </para> | |
| 743 <itemizedlist> | |
| 744 <listitem><para>... reads and compares two or three directories recursively,</para></listitem> | |
| 745 <listitem><para>... takes special care of symbolic links,</para></listitem> | |
| 746 <listitem><para>... lets you browse files on mouse double click,</para></listitem> | |
| 747 <listitem><para>... for each item proposes a merge operation, which you can change | |
| 748 before starting the directory merge,</para></listitem> | |
| 749 <listitem><para>... lets you simulate the merge and lists the actions that would | |
| 750 take place, without actually doing them,</para></listitem> | |
| 751 <listitem><para>... lets you really do the merge, and lets you interact whenever | |
| 752 manual interaction is needed,</para></listitem> | |
| 753 <listitem><para>... lets you continue the merge after manual interaction with key F5,</para></listitem> | |
| 754 <listitem><para>... optionally creates backups, with the ".orig" extension,</para></listitem> | |
| 755 <listitem><para>...</para></listitem> | |
| 756 </itemizedlist> | |
| 757 </sect1> | |
| 758 | |
| 759 <sect1 id="startingdirmerge"><title>Starting Directory Comparison Or Merge</title> | |
| 760 <para> | |
| 761 This is very similar to the single file merge and comparison. You just | |
| 762 have to specify directories on the command line or in the file-open | |
| 763 dialog. | |
| 764 </para> | |
| 765 <sect2><title>Compare/Merge two directories: </title> | |
| 766 <screen> | |
| 767 <command>kdiff3</command> <replaceable>dir1 dir2</replaceable> | |
| 768 <command>kdiff3</command> <replaceable>dir1 dir2</replaceable> -o <replaceable>destdir</replaceable> | |
| 769 </screen> | |
| 770 <para> | |
| 771 If no destination directory is specified, then KDiff3 will use <replaceable>dir2</replaceable>. | |
| 772 </para> | |
| 773 </sect2> | |
| 774 | |
| 775 <sect2><title>Compare/Merge three directories: </title> | |
| 776 <screen> | |
| 777 <command>kdiff3</command> <replaceable>dir1 dir2 dir3</replaceable> | |
| 778 <command>kdiff3</command> <replaceable>dir1 dir2 dir3</replaceable> -o <replaceable>destdir</replaceable> | |
| 779 </screen> | |
| 780 <para> | |
| 781 When three directories are merged then <replaceable>dir1</replaceable> | |
| 782 is used as the base for the merge. | |
| 783 If no destination directory is specified, then KDiff3 will use <replaceable>dir3</replaceable> | |
| 784 as the destination directory for the merge. | |
| 785 </para> | |
| 786 | |
| 787 <para> | |
| 788 Note that only the comparison starts automatically, not the merge. For this you first must | |
| 789 select a menu entry or the key F5. (More details later.) | |
| 790 </para> | |
| 791 </sect2> | |
| 792 </sect1> | |
| 793 | |
| 794 <sect1 id="dirmergevisible"><title>Visible Information</title> | |
| 795 <para> | |
| 796 While reading the directories a message-box appears that informs you of | |
| 797 the progress. If you abort the directory scan, then only files that have | |
| 798 been compared until then will be listed. | |
| 799 </para><para> | |
| 800 When the directory scan is complete then KDiff3 will show a listbox with | |
| 801 the results left, ... | |
| 802 </para> | |
| 803 <screenshot><mediaobject> | |
| 804 <imageobject><imagedata fileref="dirbrowser.png" format="PNG"/></imageobject> <!--alt="Image of the directory browser."--> | |
| 805 </mediaobject></screenshot> | |
| 806 <para> | |
| 807 ... and details about the currently selected item on the right: | |
| 808 </para> | |
| 809 <screenshot><mediaobject> | |
| 810 <imageobject><imagedata fileref="iteminfo.png" format="PNG"/></imageobject> | |
| 811 <!--alt="Image with information about the selected item."--> | |
| 812 </mediaobject></screenshot> | |
| 813 | |
| 814 <sect2 id="name"><title>The Name Column</title> | |
| 815 <para> | |
| 816 Each file and directory that was found during the scan is shown here in | |
| 817 a tree. You can select an item by clicking it with the mouse once. | |
| 818 </para><para> | |
| 819 The directories are collapsed by default. You can expand and collapse | |
| 820 them by clicking on the "+"/"-" or by double-clicking the item or | |
| 821 by using the left/right-arrow-keys. The "Directory"-menu also contains two | |
| 822 actions "Fold all subdirs" and "Unfold all subdirs" with which you can | |
| 823 collapse or expand all directories at once. | |
| 824 </para><para> | |
| 825 If you double-click a file item then the file comparison starts and the | |
| 826 file-diff-window will appear. | |
| 827 </para> | |
| 828 <para> | |
| 829 The image in the name column reflects the file type in the first | |
| 830 directory ("A"). It can be one of these: | |
| 831 </para> | |
| 832 <itemizedlist> | |
| 833 <listitem><para>Normal file</para></listitem> | |
| 834 <listitem><para>Normal directory (directory-image)</para></listitem> | |
| 835 <listitem><para>Link to a file (file-image with a link arrow)</para></listitem> | |
| 836 <listitem><para>Link to a directory (directory-image with a link arrow)</para></listitem> | |
| 837 </itemizedlist> | |
| 838 <para> | |
| 839 If the file type is different in the other directories, then this is visible | |
| 840 in the columns A/B/C and in the window that shows the details about the selected | |
| 841 item. Note that for such a case no merge operation can be selected automatically. | |
| 842 When starting the merge, then the user will be informed of problems of that | |
| 843 kind. | |
| 844 </para> | |
| 845 </sect2> | |
| 846 | |
| 847 <sect2 id="coloring"><title>The Columns A/B/C and the Coloring Scheme</title> | |
| 848 <para> | |
| 849 As can be seen in the image above the colors red, green, yellow and black | |
| 850 are used in the columns A/B/C. | |
| 851 </para> | |
| 852 <itemizedlist> | |
| 853 <listitem><para>Black: This item doesn't exist in this directory.</para></listitem> | |
| 854 <listitem><para>Green: Newest item.</para></listitem> | |
| 855 <listitem><para>Yellow: Older than green, newer than red.</para></listitem> | |
| 856 <listitem><para>Red: Oldest item.</para></listitem> | |
| 857 </itemizedlist> | |
| 858 <para> | |
| 859 But for items that were identical in the comparison their color also is | |
| 860 identical even if the age is not. | |
| 861 </para><para> | |
| 862 Directories are considered equal if all items they contain are identical. | |
| 863 Then they also will have the same color. But the age of a directory is not | |
| 864 considered for its color. | |
| 865 </para><para> | |
| 866 The idea for this coloring scheme I came upon in | |
| 867 <ulink url="http://samba.org/cgi-bin/cvsweb/dirdiff">dirdiff</ulink>. The colors | |
| 868 resemble the colors of a leaf that is green when new, turns yellow later and red | |
| 869 when old. | |
| 870 </para> | |
| 871 | |
| 872 </sect2><sect2 id="operation"><title>The Operation Column</title> | |
| 873 <para> | |
| 874 After comparing the directories KDiff3 also evaluates a proposal for a | |
| 875 merge operation. This is shown in the "Operation" column. You can modify | |
| 876 the operation by clicking on the operation you want to change. A small menu | |
| 877 will popup and allows you to select an operation for that item. This operation | |
| 878 will be executed during the merge. It depends on the item and on the merge-mode | |
| 879 you are in, what operations are available. The merge-mode is one of | |
| 880 </para> | |
| 881 <itemizedlist> | |
| 882 <listitem><para>Three directory-merge (A is treated as older base of both).</para></listitem> | |
| 883 <listitem><para>Two directory-merge.</para></listitem> | |
| 884 <listitem><para>Two directory-sync-mode (activate via option "Synchronize Directories").</para></listitem> | |
| 885 </itemizedlist> | |
| 886 <para> | |
| 887 In three directory merge the operation proposal will be: If for an item ... | |
| 888 </para> | |
| 889 <itemizedlist> | |
| 890 <listitem><para>... all three directories are equal: Copy from C</para></listitem> | |
| 891 <listitem><para>... A and C are equal but B is not: Copy from B (or if B does not | |
| 892 exist, delete the destination if exists)</para></listitem> | |
| 893 <listitem><para>... A and B are equal but C is not: Copy from C (or if C does not | |
| 894 exist, delete the destination if exists)</para></listitem> | |
| 895 <listitem><para>... B and C are equal but A is not: Copy from C (or if C does not | |
| 896 exist, delete the destination if exists)</para></listitem> | |
| 897 <listitem><para>... only A exists: Delete the destination (if exists)</para></listitem> | |
| 898 <listitem><para>... only B exists: Copy from B</para></listitem> | |
| 899 <listitem><para>... only C exists: Copy from C</para></listitem> | |
| 900 <listitem><para>... A, B and C are not equal: Merge</para></listitem> | |
| 901 <listitem><para>... A, B and C don't have the same file type (e.g. A is a directory, | |
| 902 B is a file): "Error: Conflicting File Types". While such items exist the | |
| 903 directory merge cannot start.</para></listitem> | |
| 904 </itemizedlist> | |
| 905 <para> | |
| 906 In two directory merge the operation proposal will be: If for an item ... | |
| 907 </para> | |
| 908 <itemizedlist> | |
| 909 <listitem><para>... both directories are equal: Copy from B</para></listitem> | |
| 910 <listitem><para>... A exists, but not B: Copy from A</para></listitem> | |
| 911 <listitem><para>... B exists, but not A: Copy from B</para></listitem> | |
| 912 <listitem><para>... A and B exist but are not equal: Merge</para></listitem> | |
| 913 <listitem><para>... A and B don't have the same file type (e.g. A is a directory, | |
| 914 B is a file): "Error: Conflicting File Types". While such items exist the | |
| 915 directory merge cannot start.</para></listitem> | |
| 916 </itemizedlist> | |
| 917 <para> | |
| 918 Sync-mode is active if only two directories and no explicit destination | |
| 919 were specified and if the option "Synchronize directories" is active. KDiff3 | |
| 920 then selects a default operation so that both directories are the same afterwards. | |
| 921 If for an item ... | |
| 922 </para> | |
| 923 <itemizedlist> | |
| 924 <listitem><para>... both directories are equal: Nothing will be done.</para></listitem> | |
| 925 <listitem><para>... A exists, but not B: Copy A to B</para></listitem> | |
| 926 <listitem><para>... B exists, but not A: Copy B to A</para></listitem> | |
| 927 <listitem><para>... A and B exist, but are not equal: Merge and store the result | |
| 928 in both directories. (For the user the visible save-filename is B, | |
| 929 but then KDiff3 copies B also to A.)</para></listitem> | |
| 930 <listitem><para>... A and B don't have the same file type (e.g. A is a directory, | |
| 931 B is a file): "Error: Conflicting File Types". While such items exist the | |
| 932 directory merge cannot start.</para></listitem> | |
| 933 </itemizedlist> | |
| 934 <para> | |
| 935 When two directories are merged and the option "Copy newer instead of merging" is selected, | |
| 936 then KDiff3 looks at the dates and proposes to choose the newer file. If the files are not | |
| 937 equal but have equal dates, then the operation will contain | |
| 938 "Error: Dates are equal but files are not." While such items exist the | |
| 939 directory merge cannot start. | |
| 940 </para> | |
| 941 </sect2> | |
| 942 | |
| 943 <sect2 id="status"><title>The Status Column</title> | |
| 944 <para> | |
| 945 During the merge one file after the other will be processed. The status | |
| 946 column will show "Done" for items where the merge operation has succeeded, | |
| 947 and other texts if something unexpected happened. When a merge is complete, | |
| 948 then you should make a last check to see if the status for all items is | |
| 949 agreeable. | |
| 950 </para> | |
| 951 </sect2> | |
| 952 </sect1> | |
| 953 | |
| 954 | |
| 955 <sect1 id="dothemerge"><title>Doing A Merge</title> | |
| 956 <para> | |
| 957 When you have made all your operation choices (in all subdirectories too) | |
| 958 then you can start the merge. | |
| 959 </para><para> | |
| 960 Be aware that if you didn't specify a destination directory explicitely, | |
| 961 then the destination will be "C" in three directory mode, "B" in two directory | |
| 962 merge mode, and in sync-mode it will be "A" or/and "B". | |
| 963 </para><para> | |
| 964 If you have specified a destination directory also check that all items | |
| 965 that should be in the output, are in the tree. There are some options that | |
| 966 cause certain items to be omitted from the directory comparison and merge. | |
| 967 Check these options to avoid unpleasant surprises: | |
| 968 </para> | |
| 969 <itemizedlist> | |
| 970 <listitem><para>"Recursive Directories": If this is off, then items in subdirectories | |
| 971 will not be found.</para></listitem> | |
| 972 <listitem><para>"Pattern"/"Anti-Pattern": Include/exclude items that match</para></listitem> | |
| 973 <listitem><para>"Exclude Hidden Files"</para></listitem> | |
| 974 <listitem><para>"List only Deltas": Files that match in all directories don't appear | |
| 975 in the tree, and hence also not in the destination.</para></listitem> | |
| 976 </itemizedlist> | |
| 977 <para> | |
| 978 (In the current version, you must do a rescan yourself, after changing | |
| 979 options affecting the directory scan.) | |
| 980 </para><para> | |
| 981 If you are satisfied so far, the rest is easy. | |
| 982 </para><para> | |
| 983 In the "Directory"-menu select "Start/Continue directory merge" or press | |
| 984 F5 (which is the shortcut). | |
| 985 </para><para> | |
| 986 If due to conflicting filetypes still some items with invalid operations | |
| 987 exist, then a messagebox will appear and these items will be pointed out, | |
| 988 so you can select a valid operation for the item. | |
| 989 </para><para> | |
| 990 Otherwise a dialog will appear giving you the options "Do it", "Simulate | |
| 991 it" and "Cancel". | |
| 992 </para> | |
| 993 <itemizedlist> | |
| 994 <listitem><para>Select "Simulate it" if you want to see what would be done without | |
| 995 actually doing it. A verbose list of all operations will be shown.</para></listitem> | |
| 996 <listitem><para>Otherwise select "Do it" to really start merging.</para></listitem> | |
| 997 </itemizedlist> | |
| 998 <para> | |
| 999 Then KDiff3 will run the specified operation for all items. If manual | |
| 1000 interaction is required (single file merge), then a merge window will open | |
| 1001 (<link linkend="dirmergebigscreenshot">see the big screenshot</link>). | |
| 1002 </para><para> | |
| 1003 When you have finished with a file, again select "Start/Continue directory | |
| 1004 merge" or the key F5. If you haven't saved yet, a dialog will ask you to | |
| 1005 do so. Then KDiff3 will continue with the next item. | |
| 1006 </para><para> | |
| 1007 When KDiff3 encounters an error, it will tell you so and will show the | |
| 1008 verbose-status-information. At the bottom of this list, there will be some | |
| 1009 error messages which should help you to understand the cause of the problem. | |
| 1010 When you continue merging (F5 key) KDiff3 will give you the choice to retry | |
| 1011 or skip the item that caused the problem. This means that before continuing | |
| 1012 you can choose another operation or solve the problem by other means. | |
| 1013 </para><para> | |
| 1014 When the merge is complete, then KDiff3 will inform you via a message | |
| 1015 box. | |
| 1016 </para> | |
| 1017 </sect1> | |
| 1018 | |
| 1019 <sect1 id="dirmergeoptions"><title>Options for Comparing and Merging Directories</title> | |
| 1020 <para> | |
| 1021 The KDiff3-preferences (menu "Settings"->"Configure KDiff3") now has | |
| 1022 a section called "Directory Merge" with these options: | |
| 1023 </para> | |
| 1024 | |
| 1025 <variablelist> | |
| 1026 <varlistentry><term><emphasis>Recursive Directories:</emphasis></term><listitem><para> Select whether to search directories | |
| 1027 recursively.</para></listitem></varlistentry> | |
| 1028 <varlistentry><term><emphasis>File Pattern(s):</emphasis></term><listitem><para> Only files that match any pattern here will | |
| 1029 be put in the tree. More than one pattern may be specified here via using | |
| 1030 the semicolon ";" as separator. Valid wildcards: '*' and '?'. (e.g. "*.cpp;*.h"). | |
| 1031 Default is "*". Directories need not match this pattern.</para></listitem></varlistentry> | |
| 1032 <varlistentry><term><emphasis>Anti-Pattern(s):</emphasis></term><listitem><para> Files and directories that match this pattern | |
| 1033 will be excluded from the tree. More than one pattern may be specified here | |
| 1034 via using the semicolon ";" as separator. Valid wildcards: '*' and '?'. Default | |
| 1035 is "*.orig;*.o".</para></listitem></varlistentry> | |
| 1036 <varlistentry><term><emphasis>Use CVS-Ignore:</emphasis></term><listitem><para> | |
| 1037 Ignore files and directories that would also be ignored by CVS. | |
| 1038 Many automatically generated files are ignored by CVS. | |
| 1039 The big advantage is that this can be directory specific via a local ".cvsignore"-file. | |
| 1040 (See <ulink url="info:/cvs/cvsignore">info:/cvs/cvsignore</ulink>.)</para></listitem></varlistentry> | |
| 1041 <varlistentry><term><emphasis>Find Hidden Files and Directories:</emphasis></term><listitem><para> On some filesystems files | |
| 1042 have an "Hidden"-attribute. On other systems a filename starting with a dot | |
| 1043 "." causes it to be hidden. This option allows you to decide whether to | |
| 1044 include these files in the tree or not. Default is on.</para></listitem></varlistentry> | |
| 1045 <varlistentry><term><emphasis>Follow File Links:</emphasis></term><listitem><para> For links to files: When disabled, then | |
| 1046 the symbolic links are compared. When enabled, then the files behind the | |
| 1047 links are compared. Default is off.</para></listitem></varlistentry> | |
| 1048 <varlistentry><term><emphasis>Follow Directory Links:</emphasis></term><listitem><para> For links to directories: When disabled, | |
| 1049 then the symbolic links will be compared. When enabled then the link will | |
| 1050 be treated like a directory and it will be scanned recursively. (Note that | |
| 1051 the program doesn't check if the link is "recursive". So for example a directory | |
| 1052 that contains a link to the directory would cause an infinite loop, and after | |
| 1053 some time when the stack overflows or all memory is used up, crash the program.) | |
| 1054 Default is off.</para></listitem></varlistentry> | |
| 1055 <varlistentry><term><emphasis>List only deltas:</emphasis></term><listitem><para> Only items that are not equal in all input | |
| 1056 directories will be listed and only the changed files are visible. Hence | |
| 1057 files that are equal in all directories won't be copied during a merge and | |
| 1058 if the destination dir does not contain the files before the merge, you might | |
| 1059 miss some files later. (This option is likely to be changed in a later version.) | |
| 1060 Default is off.</para></listitem></varlistentry> | |
| 1061 <varlistentry><term><emphasis>Trust the modification date:</emphasis></term><listitem><para> If you compare big directories | |
| 1062 over a slow network, it might be faster to compare the modification dates | |
| 1063 and file length alone. But this speed improvement comes with the price of | |
| 1064 a little uncertainty. Use this option with care. Default is off.</para></listitem></varlistentry> | |
| 1065 <varlistentry><term><emphasis>Synchronize Directories:</emphasis></term><listitem><para> Activates "Sync-Mode" when two directories | |
| 1066 are compared and no explicit destination directory was specified. In this | |
| 1067 mode the proposed operations will be chosen so that both source directories | |
| 1068 are equal afterwards. Also the merge result will be written to both directories. | |
| 1069 Default is off.</para></listitem></varlistentry> | |
| 1070 <varlistentry><term><emphasis>Copy newer instead of merging:</emphasis></term><listitem><para> Instead of merging the proposed | |
| 1071 operation will copy the newer source if changes happened. (Considered unsafe, | |
| 1072 because it implies that the knowledge, that the other file hasn't been edited | |
| 1073 too. Check to make sure in every case.) Default is off.</para></listitem></varlistentry> | |
| 1074 <varlistentry><term><emphasis>Backup files:</emphasis></term><listitem><para> If a file or complete directory is replaced | |
| 1075 by another or is deleted then the original version will be renamed with an | |
| 1076 ".orig" extension. If an old backup file with ".orig" extension already exists | |
| 1077 then this will be deleted without backup. This also affects the normal merging | |
| 1078 of single files, not only in directory-merge mode. Default is on.</para></listitem></varlistentry> | |
| 1079 </variablelist> | |
| 1080 </sect1> | |
| 1081 | |
| 1082 <sect1 id="other"><title>Other Functions</title> | |
| 1083 <sect2><title>Split/Full Screen Mode</title> | |
| 1084 <para> | |
| 1085 Usually the directory merge list view remains visible while a single file | |
| 1086 is compared or merged. With the mouse you can move the the splitter bar that | |
| 1087 separates the file list from the text-diff windows. If you don't want this, | |
| 1088 you can disable "Split Screen View" in the "Directory"-menu. Then you can | |
| 1089 use "Toggle View" in the "Directory"-menu to switch between the file list | |
| 1090 and the text-diff view that then occupy the full screen. | |
| 1091 </para> | |
| 1092 </sect2> | |
| 1093 <sect2><title>Comparing or Merging a Single File</title> | |
| 1094 <para> | |
| 1095 Probably you will prefer a simple double mouse click on a file in order | |
| 1096 to compare it. Nevertheless there also exists an entry in the "Directory"-menu. | |
| 1097 You can also directly merge a single file, without starting the directory | |
| 1098 merge via the "Merge single file" in the "Directory"-Menu. On saving the | |
| 1099 result, the status will be set to done, and the file will not be merged again | |
| 1100 if a directory merge is started. | |
| 1101 </para><para> | |
| 1102 But note that this status information will be lost when you rerun a directory | |
| 1103 scan: "Directory"-menu: "Rescan" | |
| 1104 </para> | |
| 1105 </sect2> | |
| 1106 </sect1> | |
| 1107 </chapter> | |
| 1108 | |
| 1109 <chapter id="misc"> | |
| 1110 <title>Miscellaneous Topics</title> | |
| 1111 <sect1 id="networktransparency"> | |
| 1112 <title>Networktransparency via KIO</title> | |
| 1113 <sect2><title>KIO-Slaves</title> | |
| 1114 <para> | |
| 1115 KDE supports networktransparency via KIO-slaves. KDiff3 uses this | |
| 1116 for reading input files and for scanning directories. | |
| 1117 This means that you can specify files and directories on local and | |
| 1118 remote ressources via URLs. | |
| 1119 </para><para> | |
| 1120 Example: | |
| 1121 </para><para> | |
| 1122 <screen> | |
| 1123 <command>kdiff3</command> test.cpp ftp://ftp.faraway.org/test.cpp | |
| 1124 <command>kdiff3</command> tar:/home/hacker/archive.tar.gz/dir ./dir | |
| 1125 </screen> | |
| 1126 </para> | |
| 1127 <para>The first line compares a local file with a file on an FTP-server. The second line | |
| 1128 compares a directory within an compressed archive with a local directory. | |
| 1129 </para><para> | |
| 1130 Other KIO-slaves that are interesting are: | |
| 1131 </para> | |
| 1132 <itemizedlist> | |
| 1133 <listitem><para>Files from the WWW (http:),</para></listitem> | |
| 1134 <listitem><para>Files from the FTP (ftp:),</para></listitem> | |
| 1135 <listitem><para>Encrypted file transfer (fish:, sftp:),</para></listitem> | |
| 1136 <listitem><para>Windows-ressources (smb:),</para></listitem> | |
| 1137 <listitem><para>Local files (file:),</para></listitem> | |
| 1138 </itemizedlist> | |
| 1139 <para> | |
| 1140 Other things that are possible, but probably less useful are: | |
| 1141 </para> | |
| 1142 <itemizedlist> | |
| 1143 <listitem><para>Man-pages (man:),</para></listitem> | |
| 1144 <listitem><para>Info-pages (info:),</para></listitem> | |
| 1145 </itemizedlist> | |
| 1146 </sect2> | |
| 1147 | |
| 1148 <sect2><title>How To Write URLs</title> | |
| 1149 <para> | |
| 1150 An URL has a different syntax compared with paths for local files and directories. | |
| 1151 Some things should be considered: | |
| 1152 </para> | |
| 1153 <itemizedlist> | |
| 1154 <listitem><para> | |
| 1155 A path can be relative and can contain "." or "..". This is not possible for URLs which are always absolute. | |
| 1156 </para></listitem><listitem><para> | |
| 1157 Special characters must be written with "escaping". ("#"->"%23", space->"%20", etc.) | |
| 1158 E.g. A file with the name "/#foo#" would have the URL "file:/%23foo%23". | |
| 1159 </para></listitem><listitem><para> | |
| 1160 When URLs don't work as expected, try to open them in Konqueror first. | |
| 1161 </para></listitem> | |
| 1162 </itemizedlist> | |
| 1163 | |
| 1164 </sect2> | |
| 1165 | |
| 1166 <sect2><title>Capabilities of KIO-Slaves</title> | |
| 1167 <para> | |
| 1168 Networktransparency has one drawback: Not all ressources have the same cababilities. | |
| 1169 </para><para> | |
| 1170 Sometimes this is due to the filesystem of the server, sometimes due to the protocol. | |
| 1171 Here is a short list of restrictions: | |
| 1172 </para> | |
| 1173 <itemizedlist> | |
| 1174 <listitem><para> | |
| 1175 Sometimes there is no support for links. | |
| 1176 </para></listitem><listitem><para> | |
| 1177 Or there is no way to distinguish if a link points to a file or a directory; always assuming a file. (ftp:, sftp:). | |
| 1178 </para></listitem><listitem><para> | |
| 1179 Can't always determine the filesize. | |
| 1180 </para></listitem><listitem><para> | |
| 1181 Limited support for permissions. | |
| 1182 </para></listitem><listitem><para> | |
| 1183 No possibility to modify permissions or modification time, so permissions or time of a copy will differ from the original. | |
| 1184 (Only possible for local files.) | |
| 1185 </para></listitem> | |
| 1186 </itemizedlist> | |
| 1187 </sect2> | |
| 1188 </sect1> | |
| 1189 | |
| 1190 <sect1 id="kpart"> | |
| 1191 <title>Using &kdiff3; as a KPart</title> | |
| 1192 <para> | |
| 1193 &kdiff3; is a KPart. Currently it implements the KParts::ReadOnlyPart-interface. | |
| 1194 </para><para> | |
| 1195 It's main use is as difference-viewer in KDevelop. KDevelop always starts the | |
| 1196 internal difference viewer first. To invoke KDiff3 press the right mouse button | |
| 1197 on the difference viewer window and select "Show in KDiff3Part" from the contextmenu. | |
| 1198 </para><para> | |
| 1199 KDiff3 normally requires two complete files as input. When used as part KDiff3 | |
| 1200 will assume that the inputfile is a patch-file in the unified format. KDiff3 | |
| 1201 then retrieves the original filenames from the patch-file. At least one of | |
| 1202 the two files must be available. KDiff3 will then invoke <command>patch</command> to | |
| 1203 recreate the second file. | |
| 1204 </para><para> | |
| 1205 In Konqueror you can select a patch-file and select "Preview in"-"KDiff3Part" from | |
| 1206 the contextmenu. Be aware that this won't work if none of the original files are | |
| 1207 available, and it is not reliable if the original file(s) have changed since the | |
| 1208 patch-file was generated. | |
| 1209 </para><para> | |
| 1210 When run as a part KDiff3 only provides the a two-file-diff, a very small toolbar | |
| 1211 and menu. Merging or directory-comparison are not supported then. | |
| 1212 </para> | |
| 1213 </sect1> | |
| 1214 </chapter> | |
| 1215 | |
| 1216 <chapter id="faq"> | |
| 1217 <title>Questions and Answers</title> | |
| 1218 | |
| 1219 &reporting.bugs; | |
| 1220 &updating.documentation; | |
| 1221 | |
| 1222 <qandaset id="faqlist"> | |
| 1223 | |
| 1224 <qandaentry><question><para> | |
| 1225 Why is it called "KDiff3"? | |
| 1226 </para></question><answer><para> | |
| 1227 Tools named "KDiff" and "KDiff2" (now called "Kompare") already exist. Also "KDiff3" should suggest | |
| 1228 that it can merge like the "diff3"-tool in the Diff-Tool collection. | |
| 1229 </para></answer></qandaentry> | |
| 1230 | |
| 1231 <qandaentry><question><para> | |
| 1232 Why did I release it under GPL? | |
| 1233 </para></question><answer><para> | |
| 1234 I'm using GPL programs for a very long time now and learned very much | |
| 1235 by having a look at many of the sources. Hence this is my "Thank You" | |
| 1236 to all programmers that also did so or will do the same. | |
| 1237 </para></answer></qandaentry> | |
| 1238 | |
| 1239 <qandaentry><question><para> | |
| 1240 Some buttons and functions are missing. What's wrong? | |
| 1241 </para></question><answer><para> | |
| 1242 You compiled from source but you probably didn't specify the correct KDE-prefix | |
| 1243 with configure. By default configure wants to install in /usr/local but then KDE can't | |
| 1244 find the user-interface ressource file (i.e. kdiff3ui.rc). The README-file contains | |
| 1245 more information about the correct prefix. | |
| 1246 </para></answer></qandaentry> | |
| 1247 | |
| 1248 <qandaentry><question><para> | |
| 1249 Often lines that are similar but not identical appear next to each other | |
| 1250 but sometimes not. Why? | |
| 1251 </para></question><answer><para> | |
| 1252 Lines where only the amount of white space characters is different | |
| 1253 are treated as "equal" at first, while just one different non-white character | |
| 1254 causes the lines to be "different". If similar lines appear next to each | |
| 1255 other, this actually is coincidence but this fortunately is often the case. | |
| 1256 </para></answer></qandaentry> | |
| 1257 | |
| 1258 <qandaentry><question><para> | |
| 1259 Why must all conflicts be solved before the merge result can be saved? | |
| 1260 </para></question><answer><para> | |
| 1261 For each equal or different section the editor in the merge result | |
| 1262 window remembers where it begins or ends. This is needed so that conflicts | |
| 1263 can be solved manually by simply selecting the source button (A, B or C). | |
| 1264 This information is lost while saving as text and it is too much effort to | |
| 1265 create a special file format that supports saving and restoring all necessary | |
| 1266 information. | |
| 1267 </para></answer></qandaentry> | |
| 1268 | |
| 1269 <qandaentry><question><para> | |
| 1270 Why does the editor in the merge result window not have an "undo"-function? | |
| 1271 </para></question><answer><para> | |
| 1272 This was too much effort until now. You can always | |
| 1273 restore a version from one source (A, B or C) by clicking the respective | |
| 1274 button. For big editing the use of another editor is recommended anyway. | |
| 1275 </para></answer></qandaentry> | |
| 1276 | |
| 1277 <qandaentry><question><para> | |
| 1278 When I removed some text, then suddenly "<No src line>" appeared | |
| 1279 and can't be deleted. What does that mean and how can one remove this? | |
| 1280 </para></question><answer><para> | |
| 1281 For each equal or different section the editor in the merge result | |
| 1282 window remembers where it begins or ends. "<No src line>" means | |
| 1283 that there is nothing left in a section, not even a new line character. | |
| 1284 This can happen either while merging automatically or by editing. This is | |
| 1285 no problem, since this hint won't appear in the saved file. If you want | |
| 1286 the orignal source back just select the section (click on the left summary | |
| 1287 column) and then click the source button with the needed contents (A/B or | |
| 1288 C). | |
| 1289 </para></answer></qandaentry> | |
| 1290 | |
| 1291 <qandaentry><question><para> | |
| 1292 Why doesn't KDiff3 support syntax-highlighting? | |
| 1293 </para></question><answer><para> | |
| 1294 KDiff3 already uses many colors for difference highlighting. More | |
| 1295 highlighting would be confusing. Use another editor for this. | |
| 1296 </para></answer></qandaentry> | |
| 1297 | |
| 1298 <qandaentry><question><para> | |
| 1299 There is so much information here, but your question is still not answered? | |
| 1300 </para></question><answer><para> | |
| 1301 Please send me your question. I appreciate every comment. | |
| 1302 </para></answer></qandaentry> | |
| 1303 | |
| 1304 </qandaset> | |
| 1305 </chapter> | |
| 1306 | |
| 1307 <chapter id="credits"> | |
| 1308 | |
| 1309 <title>Credits and License</title> | |
| 1310 | |
| 1311 <para> | |
| 1312 &kdiff3; - File and Directory Comparison and Merge Tool | |
| 1313 </para> | |
| 1314 <para> | |
| 1315 Program copyright 2002-2003 Joachim Eibl <email>joachim.eibl@gmx.de</email> | |
| 1316 </para> | |
| 1317 <para> | |
| 1318 Several cool ideas and bugreports came from colleagues and many people out in the Wild Wild Web. Thank you! | |
| 1319 </para> | |
| 1320 | |
| 1321 <para> | |
| 1322 Documentation Copyright © 2002-2003 Joachim Eibl <email>joachim.eibl@gmx.de</email> | |
| 1323 </para> | |
| 1324 | |
| 1325 <!-- TRANS:CREDIT_FOR_TRANSLATORS --> | |
| 1326 | |
| 1327 &underFDL; <!-- FDL: do not remove --> | |
| 1328 | |
| 1329 | |
| 1330 &underGPL; <!-- GPL License --> | |
| 1331 | |
| 1332 </chapter> | |
| 1333 | |
| 1334 <appendix id="installation"> | |
| 1335 <title>Installation</title> | |
| 1336 | |
| 1337 <sect1 id="getting-kdiff3"> | |
| 1338 <title>How to obtain &kdiff3;</title> | |
| 1339 | |
| 1340 <para> | |
| 1341 You can download the latest version of KDiff3 from its homepage <ulink url="http://kdiff3.sourceforge.net">http://kdiff3.sourceforge.net</ulink>. | |
| 1342 </para><para> | |
| 1343 KDiff3 is also available for other platforms. See the homepage for details. | |
| 1344 </para> | |
| 1345 | |
| 1346 | |
| 1347 </sect1> | |
| 1348 | |
| 1349 <sect1 id="requirements"> | |
| 1350 <title>Requirements</title> | |
| 1351 | |
| 1352 <para> | |
| 1353 In order to successfully use all features of &kdiff3;, you need &kde; >3.1. The | |
| 1354 diff-tool from the <ulink url="http://www.gnu.org/software/diffutils/diffutils.html">GNU-diff-utils</ulink> | |
| 1355 is recommended for best results. | |
| 1356 </para><para> | |
| 1357 For information about how to run KDiff3 on other platforms without KDE please see the | |
| 1358 <ulink url="http://kdiff3.sourceforge.net">homepage</ulink>. | |
| 1359 </para><para> | |
| 1360 You can find a list of changes at <ulink | |
| 1361 url="http://kdiff3.sourceforge.net/ChangeLog">http://kdiff3.sourceforge.net/ChangeLog</ulink> | |
| 1362 or in the "ChangeLog"-file of the source package. | |
| 1363 </para> | |
| 1364 </sect1> | |
| 1365 | |
| 1366 <sect1 id="compilation"> | |
| 1367 <title>Compilation and Installation</title> | |
| 1368 | |
| 1369 <para>In order to compile and install &kdiff3; on a system with KDE, type the | |
| 1370 following in the base directory of the &kdiff3; distribution:</para> | |
| 1371 | |
| 1372 <screen><prompt>%</prompt> <userinput><command>./configure --prefix=<replaceable>kde-dir</replaceable></command></userinput> | |
| 1373 <prompt>%</prompt> <userinput><command>make</command></userinput> | |
| 1374 <prompt>%</prompt> <userinput><command>make</command> install</userinput> | |
| 1375 </screen> | |
| 1376 <para> | |
| 1377 <replaceable>kde-dir</replaceable> specifies the directory | |
| 1378 containing KDE on your system. If you are not sure, read the README-file for details. | |
| 1379 </para> | |
| 1380 <para>Since &kdiff3; uses <command>autoconf</command> and | |
| 1381 <command>automake</command> you should have no trouble compiling it. Should you | |
| 1382 run into problems please report them to the &kde; mailing lists.</para> | |
| 1383 | |
| 1384 </sect1> | |
| 1385 | |
| 1386 </appendix> | |
| 1387 | |
| 1388 &documentation.index; | |
| 1389 </book> | |
| 1390 | |
| 1391 <!-- | |
| 1392 Local Variables: | |
| 1393 mode: sgml | |
| 1394 sgml-minimize-attributes:nil | |
| 1395 sgml-general-insert-case:lower | |
| 1396 sgml-indent-step:0 | |
| 1397 sgml-indent-data:nil | |
| 1398 End: | |
| 1399 | |
| 1400 vim:tabstop=2:shiftwidth=2:expandtab | |
| 1401 --> |