annotate kdiff3/doc/en/index.docbook @ 113:7bca1f1340f6 tip

Build fixes for Xcode 10 / Qt 5.12
author Chris Cannam
date Mon, 17 Dec 2018 11:13:01 +0000
parents 1184fc843210
children
rev   line source
joachim99@11 1 <?xml version="1.0" ?>
joachim99@73 2 <!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
joachim99@11 3 <!ENTITY kdiff3 "<application>KDiff3</application>">
joachim99@11 4 <!ENTITY kappname "&kdiff3;">
joachim99@69 5 <!ENTITY package "extragear-utils">
joachim99@11 6 <!ENTITY % addindex "IGNORE">
joachim99@11 7 <!ENTITY % English "INCLUDE">
joachim99@11 8 ]>
joachim99@11 9
joachim99@11 10 <book lang="&language;">
joachim99@11 11
joachim99@11 12 <!-- This header contains all of the meta-information for the document such
joachim99@11 13 as Authors, publish date, the abstract, and Keywords -->
joachim99@11 14
joachim99@11 15 <bookinfo>
joachim99@11 16 <title>The &kdiff3; Handbook</title>
joachim99@11 17
joachim99@11 18 <authorgroup>
joachim99@11 19 <author>
joachim99@11 20 <!--<personname>-->
joachim99@11 21 <firstname>Joachim</firstname>
joachim99@11 22 <surname>Eibl</surname>
joachim99@11 23 <!--</personname>-->
joachim99@11 24 <affiliation><address>
joachim99@66 25 <email>joachim.eibl at gmx.de</email>
joachim99@11 26 </address></affiliation>
joachim99@11 27 </author>
joachim99@73 28 <!-- TRANS:ROLES_OF_TRANSLATORS -->
joachim99@11 29 </authorgroup>
joachim99@11 30
joachim99@11 31 <copyright>
joachim99@77 32 <year>2002-2007</year>
joachim99@11 33 <holder>Joachim Eibl</holder>
joachim99@11 34 </copyright>
joachim99@11 35 <!-- Translators: put here the copyright notice of the translation -->
joachim99@11 36 <!-- Put here the FDL notice. Read the explanation in fdl-notice.docbook
joachim99@11 37 and in the FDL itself on how to use it. -->
joachim99@11 38 <legalnotice>&FDLNotice;</legalnotice>
joachim99@11 39
joachim99@11 40 <!-- Date and version information of the documentation
joachim99@11 41 Don't forget to include this last date and this last revision number, we
joachim99@11 42 need them for translation coordination !
joachim99@11 43 Please respect the format of the date (YYYY-MM-DD) and of the version
joachim99@11 44 (V.MM.LL), it could be used by automation scripts.
joachim99@11 45 Do NOT change these in the translation. -->
joachim99@11 46
joachim99@77 47 <date>2007-31-03</date>
joachim99@77 48 <releaseinfo>0.9.92</releaseinfo>
joachim99@11 49
joachim99@11 50
joachim99@11 51 <abstract>
joachim99@11 52 <para>
joachim99@11 53 &kdiff3; is a file and directory diff and merge tool which
joachim99@11 54 <itemizedlist>
joachim99@11 55 <listitem><para>compares and merges two or three text input files or directories,</para></listitem>
joachim99@11 56 <listitem><para>shows the differences line by line and character by character(!),</para></listitem>
joachim99@11 57 <listitem><para>provides an automatic merge-facility,</para></listitem>
joachim99@11 58 <listitem><para>has an editor for comfortable solving of merge-conflicts,</para></listitem>
joachim99@11 59 <listitem><para>provides networktransparency via KIO,</para></listitem>
joachim99@68 60 <listitem><para>has options to highlight or hide changes in white-space or comments,</para></listitem>
joachim99@69 61 <listitem><para>supports Unicode, UTF-8 and other file encodings,</para></listitem>
joachim99@69 62 <listitem><para>prints differences,</para></listitem>
joachim99@69 63 <listitem><para>supports version control keyword and history merging.</para></listitem>
joachim99@11 64 </itemizedlist>
joachim99@11 65 </para><para>
joachim99@77 66 This document describes &kdiff3;-version 0.9.92.
joachim99@11 67 </para>
joachim99@11 68 </abstract>
joachim99@11 69
joachim99@11 70 <!-- This is a set of Keywords for indexing by search engines.
joachim99@11 71 Please at least include KDE, the KDE package it is in, the name
joachim99@11 72 of your application, and a few relevant keywords. -->
joachim99@11 73
joachim99@11 74 <keywordset>
joachim99@11 75 <keyword>KDE</keyword>
joachim99@11 76 <keyword>kdeextragear</keyword>
joachim99@11 77 <keyword>kdiff3</keyword>
joachim99@11 78 <keyword>diff</keyword>
joachim99@11 79 <keyword>merge</keyword>
joachim99@11 80 <keyword>CVS</keyword>
joachim99@11 81 <keyword>triplediff</keyword>
joachim99@11 82 <keyword>compare</keyword>
joachim99@11 83 <keyword>files</keyword>
joachim99@11 84 <keyword>directories</keyword>
joachim99@11 85 <keyword>version control</keyword>
joachim99@11 86 <keyword>three-way-merge</keyword>
joachim99@11 87 <keyword>in-line-differences</keyword>
joachim99@11 88 <keyword>synchronise</keyword>
joachim99@11 89 <keyword>kpart</keyword>
joachim99@11 90 <keyword>kio</keyword>
joachim99@11 91 <keyword>networktransparent</keyword>
joachim99@11 92 <keyword>editor</keyword>
joachim99@51 93 <keyword>white space</keyword>
joachim99@51 94 <keyword>comments</keyword>
joachim99@11 95 </keywordset>
joachim99@11 96
joachim99@11 97 </bookinfo>
joachim99@11 98
joachim99@11 99 <chapter id="introduction"><title>Introduction</title>
joachim99@11 100 <sect1 id="why"><title>Yet Another Diff Frontend?</title>
joachim99@11 101 <para>
joachim99@73 102 Several graphical diff tools exist. Why choose &kdiff3;? Let me say, why I wrote it.
joachim99@11 103 </para><para>
joachim99@73 104 &kdiff3; started because I had to do a difficult merge. Merging is necessary when several
joachim99@11 105 people work on the same files in a project. A merge can be somewhat automated, when the
joachim99@11 106 merge-tool not only has the new modified files (called "branches"), but also the original file
joachim99@11 107 (called "base"). The merge tool will automatically choose any modification that was only
joachim99@11 108 done in one branch. When several contributors change the same lines, then the merge tool
joachim99@11 109 detects a conflict which must be solved manually.
joachim99@11 110 </para><para>
joachim99@11 111 The merge then was difficult because one contributor had changed many things and corrected
joachim99@11 112 the indentation in many places. Another contributor also had changed much text in the same file,
joachim99@11 113 which resulted in several merge conflicts.
joachim99@11 114 </para><para>
joachim99@11 115 The tool I used then, only showed the changed lines, but not what had changed within these
joachim99@11 116 lines. And there was no information about where only the indentation was changed. The merge
joachim99@11 117 was a little nightmare.
joachim99@11 118 </para><para>
joachim99@11 119 So this was the start. The first version could show differences within a line and showed white space differences.
joachim99@11 120 Later many other features were added to increase the usefulness.
joachim99@11 121 </para><para>
joachim99@11 122 For example if you want to compare some text quickly, then you can copy it to the clipboard and
joachim99@11 123 paste it into either diff window.
joachim99@11 124 </para><para>
joachim99@11 125 A feature that required a big effort was the directory comparison and merge facility, which turned
joachim99@11 126 the program almost into a full file browser.
joachim99@11 127 </para><para>
joachim99@73 128 I hope &kdiff3; works for you too. Have fun!
joachim99@11 129 </para><para>
joachim99@11 130 Joachim Eibl (2003)
joachim99@11 131 </para>
joachim99@11 132 </sect1>
joachim99@11 133
joachim99@11 134 <sect1 id="screenshots"><title>Screenshots and Features</title>
joachim99@11 135 <para>This screenshot shows the difference between two text files</para>
joachim99@73 136 <para>(Using an early version of &kdiff3;):</para>
joachim99@11 137 <screenshot><mediaobject>
joachim99@11 138 <imageobject><imagedata fileref="screenshot_diff.png" format="PNG"/></imageobject>
joachim99@11 139 </mediaobject></screenshot>
joachim99@11 140
joachim99@11 141 <para>
joachim99@11 142 3-way-merging is fully supported. This is useful if two people change code independently.
joachim99@73 143 The original file (the base) is used to help &kdiff3; to automatically select the correct
joachim99@11 144 changes.
joachim99@11 145 The merge-editor below the diff-windows allows you to solve conflicts, while showing you the output you will get.
joachim99@11 146 You can even edit the output.
joachim99@11 147 This screenshot shows three input files being merged:
joachim99@11 148 </para><para>
joachim99@11 149 <screenshot><mediaobject>
joachim99@11 150 <imageobject><imagedata fileref="screenshot_merge.png" format="PNG"/></imageobject>
joachim99@11 151 </mediaobject></screenshot>
joachim99@11 152 </para>
joachim99@11 153
joachim99@73 154 <para id="dirmergebigscreenshot">&kdiff3; also helps you to compare and merge complete directories.
joachim99@73 155 This screenshot shows &kdiff3; during a directory merge:
joachim99@11 156 </para><para>
joachim99@11 157 <screenshot><mediaobject>
joachim99@11 158 <imageobject><imagedata fileref="dirmergebig.png" format="PNG"/></imageobject>
joachim99@11 159 </mediaobject></screenshot>
joachim99@11 160 </para>
joachim99@11 161 </sect1>
joachim99@11 162
joachim99@11 163 <sect1 id="features"><title>More Features</title>
joachim99@11 164 <sect2><title> Line-By-Line And Char-By-Char Diff-Viewer</title>
joachim99@73 165 <para>By using the possiblities of a graphical color display &kdiff3; shows
joachim99@11 166 exactly what the difference is. When you have to do many code-reviews, you will like this.
joachim99@11 167 </para>
joachim99@11 168 <screenshot><mediaobject>
joachim99@11 169 <imageobject><imagedata fileref="letter_by_letter.png" format="PNG"/></imageobject>
joachim99@11 170 </mediaobject></screenshot>
joachim99@11 171 </sect2>
joachim99@11 172
joachim99@11 173 <sect2><title> See White-Space Differences At One Glance</title>
joachim99@11 174 <para>Spaces and tabs that differ appear visibly. When lines differ only
joachim99@11 175 in the amount of white space this can be seen at one look in the summary
joachim99@11 176 column on the left side. (No more worries when people change the indentation.)
joachim99@11 177 </para>
joachim99@11 178 <screenshot><mediaobject>
joachim99@11 179 <imageobject><imagedata fileref="white_space.png" format="PNG"/></imageobject>
joachim99@11 180 </mediaobject></screenshot>
joachim99@11 181 </sect2>
joachim99@11 182
joachim99@11 183 <sect2><title> Triple-Diff</title>
joachim99@11 184 <para> Analyze three files and see where they differ.
joachim99@11 185 </para><para>
joachim99@11 186 The left/middle/right windows are named A/B/C and have the blue/green/magenta
joachim99@11 187 color respectively.
joachim99@11 188 </para><para>
joachim99@11 189 If one file is the same and one file is different on a line then the
joachim99@11 190 color shows which file is different. The red color means that both other
joachim99@11 191 files are different.
joachim99@11 192 </para>
joachim99@11 193 <screenshot><mediaobject>
joachim99@11 194 <imageobject><imagedata fileref="triple_diff.png" format="PNG"/></imageobject>
joachim99@11 195 </mediaobject></screenshot>
joachim99@11 196 </sect2>
joachim99@11 197
joachim99@11 198 <sect2><title> Comfortable Merge Of Two Or Three Input Files</title>
joachim99@73 199 <para> &kdiff3; can be used to merge two or three input files and automatically
joachim99@11 200 merges as much as possible. The result is presented in an editable window
joachim99@11 201 where most conflicts can be solved with a single mouseclick: Select the
joachim99@11 202 buttons A/B/C from the button-bar to select the source that should be used.
joachim99@11 203 You can also select more than one source. Since this output window is an
joachim99@11 204 editor even conflicts which need further corrections can be solved here without
joachim99@11 205 requiring another tool.
joachim99@11 206 </para>
joachim99@11 207 </sect2>
joachim99@11 208
joachim99@66 209 <sect2><title>And ...</title>
joachim99@11 210 <itemizedlist>
joachim99@66 211 <listitem><para>Fast navigation via buttons.</para></listitem>
joachim99@66 212 <listitem><para>A mouse-click into a summary column sync's all windows to show the same position.</para></listitem>
joachim99@66 213 <listitem><para>Select and copy from any window and paste into the merge result window.</para></listitem>
joachim99@66 214 <listitem><para>Overview column that shows where the changes and conflicts are.</para></listitem>
joachim99@66 215 <listitem><para>The colors are adjustable to your specific preferences.</para></listitem>
joachim99@66 216 <listitem><para>Adjustable Tab size.</para></listitem>
joachim99@66 217 <listitem><para>Option to insert spaces instead of tabs.</para></listitem>
joachim99@66 218 <listitem><para>Open files comfortably via dialog or specify files on the command line.</para></listitem>
joachim99@66 219 <listitem><para>Search for strings in all text windows. Find (Ctrl-F) and Find Next (F3)</para></listitem>
joachim99@66 220 <listitem><para>Show the line numbers for each line. </para></listitem>
joachim99@66 221 <listitem><para>Paste clipboard or drag text into a diff input window.</para></listitem>
joachim99@66 222 <listitem><para>Networktransparency via KIO.</para></listitem>
joachim99@66 223 <listitem><para>Can be used as diff-viewer in KDevelop 3.</para></listitem>
joachim99@66 224 <listitem><para>Word-wrap for long lines.</para></listitem>
joachim99@68 225 <listitem><para>Support for Unicode, UTF-8 and other codecs.</para></listitem>
joachim99@68 226 <listitem><para>Support for right to left languages.</para></listitem>
joachim99@66 227 <listitem><para>...</para></listitem>
joachim99@11 228 </itemizedlist>
joachim99@11 229 </sect2>
joachim99@11 230 </sect1>
joachim99@11 231 </chapter>
joachim99@11 232
joachim99@69 233 <chapter id="documentation"><title>File Comparison And Merge</title>
joachim99@11 234
joachim99@11 235 <sect1 id="commandline"><title>Command-Line Options</title>
joachim99@11 236
joachim99@11 237 <sect2><title>Comparing 2 files: </title>
joachim99@11 238 <screen>
joachim99@11 239 <command>kdiff3</command> <replaceable>file1 file2</replaceable>
joachim99@11 240 </screen>
joachim99@11 241 </sect2>
joachim99@11 242
joachim99@11 243 <sect2><title>Merging 2 files: </title>
joachim99@11 244 <screen>
joachim99@11 245 <command>kdiff3</command> <replaceable>file1 file2</replaceable> -m
joachim99@11 246 <command>kdiff3</command> <replaceable>file1 file2</replaceable> -o <replaceable>outputfile</replaceable>
joachim99@11 247 </screen>
joachim99@11 248 </sect2>
joachim99@11 249
joachim99@11 250 <sect2><title>Comparing 3 files: </title>
joachim99@11 251 <screen>
joachim99@11 252 <command>kdiff3</command> <replaceable>file1 file2 file3</replaceable>
joachim99@11 253 </screen>
joachim99@11 254 </sect2>
joachim99@11 255
joachim99@11 256 <sect2><title>Merging 3 files: </title>
joachim99@11 257 <screen>
joachim99@11 258 <command>kdiff3</command> <replaceable>file1 file2 file3</replaceable> -m
joachim99@11 259 <command>kdiff3</command> <replaceable>file1 file2 file3</replaceable> -o <replaceable>outputfile</replaceable>
joachim99@11 260 </screen>
joachim99@11 261 <para>
joachim99@11 262 Note that <replaceable>file1</replaceable> will be treated as
joachim99@11 263 base of <replaceable>file2</replaceable> and
joachim99@11 264 <replaceable>file3</replaceable>.
joachim99@11 265 </para>
joachim99@11 266 </sect2>
joachim99@11 267
joachim99@11 268 <sect2><title>Special case: Files with the same name </title>
joachim99@11 269 <para>
joachim99@11 270 If all files have the same name but are in different directories, you can
joachim99@11 271 reduce typework by specifying the filename only for the first file. E.g.:
joachim99@11 272 </para>
joachim99@11 273 <screen>
joachim99@11 274 <command>kdiff3</command> <replaceable>dir1/filename dir2 dir3</replaceable>
joachim99@11 275 </screen>
joachim99@11 276 </sect2>
joachim99@11 277
joachim99@11 278 <sect2><title>Commandline for starting a directory comparison or merge: </title>
joachim99@11 279 <para>This is very similar, but now it's about directories.</para>
joachim99@11 280 <screen>
joachim99@11 281 <command>kdiff3</command> <replaceable>dir1 dir2</replaceable>
joachim99@11 282 <command>kdiff3</command> <replaceable>dir1 dir2</replaceable> -o <replaceable>destdir</replaceable>
joachim99@11 283 <command>kdiff3</command> <replaceable>dir1 dir2 dir3</replaceable>
joachim99@11 284 <command>kdiff3</command> <replaceable>dir1 dir2 dir3</replaceable> -o <replaceable>destdir</replaceable>
joachim99@11 285 </screen>
joachim99@11 286 <para>For directory comparison and merge you can continue to read <link linkend="dirmerge">here</link>.</para>
joachim99@11 287 </sect2>
joachim99@11 288
joachim99@69 289 <sect2><title>Other command line options</title>
joachim99@69 290 <para>To see all available command line options type</para>
joachim99@11 291 <screen>
joachim99@69 292 <command>kdiff3</command> --help
joachim99@69 293 </screen>
joachim99@69 294 <para>Example output:</para>
joachim99@69 295 <screen>
joachim99@66 296 Options:
joachim99@66 297 -m, --merge Merge the input.
joachim99@66 298 -b, --base file Explicit base file. For compatibility with certain tools.
joachim99@66 299 -o, --output file Output file. Implies -m. E.g.: -o newfile.txt
joachim99@66 300 --out file Output file, again. (For compatibility with certain tools.)
joachim99@66 301 --auto No GUI if all conflicts are auto-solvable. (Needs -o file)
joachim99@66 302 --qall Don't solve conflicts automatically. (For compatibility...)
joachim99@66 303 --L1 alias1 Visible name replacement for input file 1 (base).
joachim99@66 304 --L2 alias2 Visible name replacement for input file 2.
joachim99@66 305 --L3 alias3 Visible name replacement for input file 3.
joachim99@66 306 -L, --fname alias Alternative visible name replacement. Supply this once for every input.
joachim99@69 307 --cs string Override a config setting. Use once for every setting. E.g.: --cs "AutoAdvance=1"
joachim99@69 308 --confighelp Show list of config settings and current values.
joachim99@69 309 --config file Use a different config file.
joachim99@11 310 </screen>
joachim99@69 311 <para>The option <option>--cs</option> allows you to adjust a configuration value that is otherwise only adjustable via the configure dialogs.
joachim99@73 312 But be aware that when &kdiff3; then terminates the changed value will be stored along with the other settings.
joachim99@69 313 With <option>--confighelp</option> you can find out the names of the available items and current values.</para>
joachim99@73 314 <para>Via <option>--config</option> you can specify a different config file. When you often use &kdiff3;
joachim99@69 315 with completely different setups this allows you to easily switch between them.</para>
joachim99@69 316 </sect2>
joachim99@69 317 <sect2><title>Ignorable command line options</title>
joachim99@73 318 <para>Many people want to use &kdiff3; with some version control system.
joachim99@73 319 But when that version control system calls &kdiff3; using command line parameters that &kdiff3; doesn't recognise, then &kdiff3; terminates with an error.
joachim99@73 320 The integration settings allow to specify command line parameters that should be ignored by &kdiff3;.
joachim99@69 321 They will appear in the usage help like in this example:</para>
joachim99@69 322 <screen>
joachim99@69 323 --<replaceable>foo</replaceable> Ignored. (User defined.)
joachim99@69 324 </screen>
joachim99@69 325 <variablelist>
joachim99@69 326 <varlistentry><term><emphasis>Command line options to ignore:</emphasis></term><listitem><para>
joachim99@69 327 A list of options, separated via semicolon ';'. When one of these options appears on the commandline,
joachim99@73 328 then &kdiff3; will ignore it and run without reporting an error.
joachim99@69 329 (Default is "u;query;html;abort").</para></listitem></varlistentry>
joachim99@69 330 </variablelist>
joachim99@69 331 <para>When this isn't enough, then it is recommended to write a shell script that does the option translation.</para>
joachim99@11 332 </sect2>
joachim99@11 333
joachim99@11 334 </sect1>
joachim99@11 335
joachim99@11 336 <sect1 id="opendialog"><title>Open-Dialog</title>
joachim99@11 337 <para>
joachim99@11 338 Since many input files must be selectable, the program has a special open dialog:
joachim99@11 339 </para>
joachim99@11 340 <screenshot><mediaobject>
joachim99@11 341 <imageobject><imagedata fileref="open_dialog.png" format="PNG"/></imageobject>
joachim99@11 342 </mediaobject></screenshot>
joachim99@11 343 <para>
joachim99@11 344 The open dialog allows to edit the filenames by hand, selecting a file
joachim99@11 345 via the file-browser ("File...") or allows to choose recent files from
joachim99@11 346 the drop-down lists. If you open the dialog again, then the current names
joachim99@11 347 still remain there. The third input file is not required. If the
joachim99@11 348 entry for "C" remains empty, then only a two file diff analysis will be
joachim99@11 349 done.
joachim99@11 350 </para><para>
joachim99@11 351 You can also select a directory via "Dir...". If for A a directory is specified
joachim99@11 352 then a directory-comparison/merge starts. If A specifies a file but B, C or
joachim99@73 353 the output specify a directory, then &kdiff3; uses the filename from A in the
joachim99@11 354 specified directories.
joachim99@11 355 </para><para>
joachim99@11 356 If "Merge" is selected, then the "Output"-line becomes editable. But it
joachim99@11 357 is not required to specify the output filename immediately. You can also
joachim99@11 358 postpone this until saving.
joachim99@11 359 </para><para>
joachim99@11 360 The "Configure..."-button opens the options-dialog, so that you can set
joachim99@11 361 the options before running the analysis.
joachim99@11 362 </para>
joachim99@11 363 </sect1>
joachim99@11 364
joachim99@11 365 <sect1 id="pasteinput"><title>Paste and Drop Input</title>
joachim99@11 366 <para>
joachim99@73 367 Sometimes you want to compare parts of a text that is not an own file. &kdiff3; also
joachim99@11 368 allows you to paste text from the clipboard into the diff input window that has the focus.
joachim99@11 369 The diff analysis happens immediately then.
joachim99@11 370 In the open dialog you need not specify files then, but just close it via "Cancel".
joachim99@11 371 </para><para>
joachim99@11 372 You can also use drag and drop: Drag a file from a file manager
joachim99@11 373 or selected text from an editor and drop it onto a diff input window.
joachim99@11 374 </para><para>
joachim99@11 375 What's the idea? Sometimes a file contains two similar functions, but checking how similar
joachim99@11 376 they really are is a big effort if you first must create two files and then load them. Now
joachim99@11 377 you can simply copy, paste and compare the relevant sections.
joachim99@11 378 </para><para>
joachim99@73 379 Note: Currently you cannot drag anything from &kdiff3;. Only dropping in the diff input
joachim99@11 380 is supported.
joachim99@11 381 </para><para>
joachim99@11 382 Warning: Some editors still interpret the drag and drop into another program like cut
joachim99@11 383 (instead of copy) and paste. Your original data might be lost then.
joachim99@11 384 </para>
joachim99@11 385 </sect1>
joachim99@11 386
joachim99@69 387 <sect1 id="interpretinginformation"><title>Comparing Files And Interpreting The Information In The Input Windows</title>
joachim99@11 388 <screenshot><mediaobject>
joachim99@11 389 <imageobject><imagedata fileref="screenshot_diff.png" format="PNG"/></imageobject>
joachim99@11 390 </mediaobject></screenshot>
joachim99@69 391 <sect2><title>Info Line</title><para>
joachim99@11 392 At the top of each text window is its "info line". The info lines of
joachim99@69 393 the input windows contain a letter "A", "B" or "C", the editable filename,
joachim99@69 394 a button for browsing, and the line number of the first visible line in the window.
joachim99@69 395 (Note that window "C" is optional.) Each info line appears in a different color.
joachim99@11 396 </para><para>
joachim99@69 397 When you selected another file via browsing or finished editing the filename here
joachim99@69 398 by pressing enter, the new file will be loaded and
joachim99@69 399 compared with the already loaded file(s).
joachim99@69 400 </para></sect2><sect2><title>Coloring</title><para>
joachim99@11 401 The three input windows are assigned the letters "A", "B" and "C".
joachim99@11 402 "A" has color blue, "B" has green and "C" has magenta. (These are the
joachim99@11 403 defaults, but can be changed in the Settings-Menu.)
joachim99@11 404 </para><para>
joachim99@11 405 When a difference is detected then the color shows which input file
joachim99@11 406 differs. When both other input files differ then the color used to express
joachim99@11 407 this is red by default ("Conflict color" in the Settings).
joachim99@11 408 This colorscheme is especially useful in the case of three input files, which will be
joachim99@11 409 seen in the next section (<link linkend="merging">Merging</link>).
joachim99@69 410 </para></sect2><sect2><title>Summary Column</title><para>
joachim99@11 411 Left of each text is the "summary column". If differences occurred on a
joachim99@11 412 line then the summary column shows the respective color. For a white-space-only
joachim99@11 413 difference the summary is chequered. For programming languages where white
joachim99@11 414 space is not so important this is useful to see at one glance if anything
joachim99@11 415 of importance was modified. (In C/C++ white space is only interesting within
joachim99@11 416 strings, comments, for the preprocessor, and some only very esoteric situations.)
joachim99@11 417 </para><para>
joachim99@11 418 The vertical line separating the summary column and the text is interrupted
joachim99@66 419 if the input file had no lines there. When word-wrap is enabled then this vertical
joachim99@66 420 line appears dotted for wrapped lines.
joachim99@69 421 </para></sect2><sect2><title>Overview Column</title><para>
joachim99@11 422 On the right side a "overview"-column is visible left of the vertical scrollbar.
joachim99@11 423 It shows the compressed summary column of input "A". All the differences
joachim99@11 424 and conflicts are visible at one glance. When only two input windows are
joachim99@11 425 used, then all differences appear red here because every difference is
joachim99@11 426 also a conflict. A black rectangle frames the visible part of the inputs.
joachim99@11 427 For very long input files, when the number of input lines is bigger than
joachim99@11 428 the height of the overview column in pixels, then several input lines share
joachim99@11 429 one overview line. A conflict then has top priority over simple differences,
joachim99@11 430 which have priority over no change, so that no difference or conflict is
joachim99@11 431 lost here. By clicking into this overview column the corresponding text
joachim99@11 432 will be shown.
joachim99@69 433 </para></sect2><sect2 id="manualdiffhelp"><title>Manually Aligning Lines</title><para>
joachim99@69 434 Sometimes the algorithm places the wrong lines next to each other. Or you want to compare
joachim99@69 435 one piece of text with text at a completely different position in the other file.
joachim99@73 436 For these situations you can manually instruct &kdiff3; to align certain lines.
joachim99@69 437 Mark the text for which you want to improve the alignment with the mouse as you would
joachim99@69 438 for copy and paste in the first diff view and then choose "Add Manual Diff Alignment"
joachim99@69 439 in the "Diffview"-menu (keyboard shortcut "Ctrl-Y") . An orange bar will appear in
joachim99@69 440 the summary column next to the chosen text. Repeat this for the second and
joachim99@73 441 (if available) third diff view. &kdiff3; will immediately recalculate the differences everytime you do this.
joachim99@69 442 and will align the chosen lines. Of course some of the previously matching lines in between
joachim99@69 443 might not match anymore.
joachim99@69 444 </para><para>
joachim99@69 445 Currently merging doesn't support the use of manual diff help.
joachim99@77 446 </para></sect2><sect2 id="joinsplitsections"><title>Manually Joining and Splitting Diff Sections</title><para>
joachim99@77 447 In some cases &kdiff3; will see too many or too few diff sections for merging. In such a
joachim99@77 448 case you can join or split existing sections.
joachim99@77 449 </para><para>
joachim99@77 450 Add new sections by first selecting text in the lines that belong together in either input window (as for copying to the clipboard).
joachim99@77 451 Then choose "Split Diff At Selection" in the "Merge" menu.
joachim99@77 452 Splits will be added above the first line and below the last line of the selected text.
joachim99@77 453 If you only want to add one section, then select text beginning at another section-split.
joachim99@77 454 </para><para>
joachim99@77 455 For joining sections in either input window select something in the lines from the sections to join.
joachim99@77 456 (You can join several sections in one step too.) Then choose "Join selected Diffs" in the "Merge"-menu.
joachim99@69 457 </para></sect2>
joachim99@11 458 </sect1>
joachim99@11 459
joachim99@11 460
joachim99@11 461 <sect1 id="merging"><title>Merging And The Merge Output Editor Window</title>
joachim99@11 462 <screenshot><mediaobject>
joachim99@11 463 <imageobject><imagedata fileref="screenshot_merge.png" format="PNG"/></imageobject>
joachim99@11 464 </mediaobject></screenshot>
joachim99@11 465 <para>
joachim99@11 466 The merge output editor window (below the diff input windows) also has an info line at the top showing "Output:", the
joachim99@11 467 filename and "[Modified]" if you edited something. Usually it will contain
joachim99@11 468 some text through the automatic merge facilities, but often it will also
joachim99@11 469 contain conflicts.
joachim99@11 470 </para><para>
joachim99@11 471 !!! Saving is disabled until all conflicts are resolved !!! (Use the "Go
joachim99@11 472 to prev/next unsolved conflicts"-buttons to find the remaining conflicts.)
joachim99@11 473 </para><para>
joachim99@11 474 With only two input files every difference is also a conflict that must
joachim99@11 475 be solved manually.
joachim99@11 476 </para><para>
joachim99@11 477 With three input files the first file is treated as base, while the
joachim99@11 478 second and third input files contain modifications. When at any line only
joachim99@11 479 either input B or input C have changed but not both then the changed source
joachim99@11 480 will automatically be selected. Only when B and C have changed on the same
joachim99@11 481 lines, then the tool detects a conflict that must be solved manually.
joachim99@11 482 When B and C are the same, but not the same as A, then C is selected.
joachim99@69 483 </para><sect2><title>The Summary Column</title><para>
joachim99@11 484 The merge output editor window also has a summary column on the left. It shows the
joachim99@11 485 letter of the input from which a line was selected or nothing if all three
joachim99@11 486 sources where equal on a line. For conflicts it shows a questionmark "?"
joachim99@11 487 and the line shows "&lt;Merge Conflict&gt;", all in red. Because solving
joachim99@11 488 conflicts line by line would take very long, the lines are grouped into
joachim99@11 489 groups that have the same difference and conflict characteristics.
joachim99@11 490 But only-white-space-conflicts are separated from non-white-space-conflicts
joachim99@11 491 in order to ease the merging of files were the indentation changed for many
joachim99@11 492 lines.
joachim99@69 493 </para></sect2><sect2 id="synchronise_views"><title>Setting The Current Group And Synchronising Merge And Diff View Position</title><para>
joachim99@11 494 When clicking into the summary column with the left mouse button in either
joachim99@69 495 window then the beginning of the group belonging to that line will shown in all windows.
joachim99@11 496 This group then becomes the "current group". It is highlighted with the
joachim99@11 497 "Current range (diff) background color" and
joachim99@11 498 a black bar appears on the left side of the text.
joachim99@69 499 </para></sect2><sect2><title>Choosing Inputs A, B or C For Current Conflict And Editing</title><para>
joachim99@73 500 The button bar below the menubar contains three input selector buttons
joachim99@69 501 containing the letters "A", "B" and "C". Click the input selector
joachim99@69 502 button to insert (or remove if already inserted) the lines from the respective source.
joachim99@69 503 To choose the lines from several inputs click the respective buttons in the
joachim99@69 504 needed order. For example if you want that the lines from "B" appear before
joachim99@69 505 the lines from "A" in the output, first click "B", then "A".
joachim99@11 506 </para><para>
joachim99@69 507 If you use the auto-advance option
joachim99@69 508 (<link linkend="autoadvance">"Automatically go to next unsolved conflict after source selection"</link>),
joachim99@69 509 you should disable this before choosing lines from several inputs or if you want to
joachim99@73 510 edit the lines after your choice. Otherwise &kdiff3; will jump to the next
joachim99@69 511 conflict after choosing the first input.
joachim99@11 512 </para><para>
joachim99@69 513 It is often helpful directly edit the merge output.
joachim99@69 514 The summary column will show "m" for every line that was manually modified.
joachim99@69 515 When for instance the differences are aligned in a way that simply choosing
joachim99@69 516 the inputs won't be satisfactory, then you can mark the needed text and use
joachim99@69 517 normal <link linkend="selections">copy and paste</link> to put it into the merge output.
joachim99@11 518 </para><para>
joachim99@11 519 Sometimes, when a line is removed either by automatic merge or by editing
joachim99@11 520 and no other lines remain in that group, then the text &lt;No src line&gt;
joachim99@11 521 will appear in that line. This is just a placeholder for the group for
joachim99@11 522 when you might change your mind and select some source again. This text won't
joachim99@11 523 appear in the saved file or in any selections you want to copy and paste.
joachim99@11 524 </para><para>
joachim99@11 525 The text "&lt;Merge Conflict&gt;" will appear in the clipboard if you
joachim99@11 526 copy and paste some text containing such a line. But still be careful to
joachim99@11 527 do so.
joachim99@69 528 </para></sect2><sect2><title>Choosing Input A, B, or C for All Conflicts</title><para>
joachim99@51 529 The normal merge will start by solving simple conflicts automatically.
joachim99@51 530 But the "Merge"-menu provides some actions for other common needs.
joachim99@51 531 If you have to select the same source for most conflicts, then you can
joachim99@51 532 choose "A", "B" or "C" everywhere, or only for the remaining unsolved
joachim99@73 533 conflicts, or for unsolved white space conflicts. If you want to decide every
joachim99@51 534 single delta yourself, you can "Set deltas to conflicts". Or if you want to
joachim99@73 535 return to the automatic choices of &kdiff3; then select
joachim99@73 536 "Automatically solve simple conflicts". &kdiff3; then restarts the merge.
joachim99@73 537 For actions that change your previous modifications &kdiff3; will ask for your
joachim99@51 538 confirmation before proceeding.
joachim99@51 539 </para><para>
joachim99@73 540 Note: When choosing either source for unsolved white space conflicts and
joachim99@51 541 the options "Ignore Numbers" or "Ignore C/C++ Comments" are used then changes in
joachim99@73 542 numbers or comments will be treated like white space too.
joachim99@69 543
joachim99@69 544 </para></sect2><sect2 id="vcskeywordsmergesupport"><title>Automatic Merge of Version Control Keywords and History (Log)</title><para>
joachim99@73 545 Many version control systems support special keywords in the file. (e.g. "&#36;Date&#36;",
joachim99@73 546 "&#36;Header&#36;", "&#36;Author&#36;", "&#36;Log&#36;" etc.) During the
joachim99@69 547 check-in the version control system (VCS) changes these lines. For instance
joachim99@73 548 "&#36;Date&#36;" will turn into "&#36;Date: 2005/03/22 18:45:01 &#36;". Since this line will
joachim99@69 549 be different in every version of the file, it would require manual interaction
joachim99@69 550 during the merge.
joachim99@69 551 </para><para>
joachim99@73 552 &kdiff3; offers automatic merge for these items. For simple lines that match the
joachim99@73 553 "Auto merge regular expression"-option in all input-files &kdiff3; will choose
joachim99@69 554 the line from B or - if available - from C. (Additionally it is necessary that the lines
joachim99@69 555 in question line up in the comparison and the previous line contains no conflict.)
joachim99@69 556 This auto merge can either be run immediately after a merge starts (activate the option
joachim99@69 557 "Run regular expression auto merge on merge start") or later via the merge
joachim99@69 558 menu "Run Regular Expression Auto Merge".
joachim99@69 559 </para><para>
joachim99@69 560 Automatic merge for version control history (also called "log") is also supported.
joachim99@69 561 The history automerge can either run immediately when the merge starts by activating the
joachim99@69 562 option "Merge version control history on merge start" or later via the merge menu
joachim99@69 563 "Automatically Solve History Conflicts".
joachim99@69 564 </para><para>
joachim99@73 565 Usually the version control history begins with a line containing the keyword "&#36;Log&#36;".
joachim99@69 566 This must be matched by the "History start regular expression"-option.
joachim99@73 567 &kdiff3; detects which subsequent lines are in the history by analysing the leading characters
joachim99@77 568 that came before the "&#36;Log&#36;"-keyword. If the same "leading comment"-characters also appears in the following
joachim99@69 569 lines, then they are also included in the history.
joachim99@69 570 </para><para>
joachim99@69 571 During each check-in the VCS writes a unique line specifying version-, date- and time-information
joachim99@69 572 followed by lines with user comments.
joachim99@69 573 These lines form one history-entry. This history section grows with every check-in and the
joachim99@69 574 most recent entries appear at the top (after the history start line).
joachim99@69 575 </para><para>
joachim99@69 576 When for parallel development two or more developers check-in a branch of the file then
joachim99@69 577 the merge history will contain several entries that appear as conflicts during the merge
joachim99@73 578 of the branches. Since merging these can become very tedious, &kdiff3; offers support with two
joachim99@69 579 possible strategies: Just insert the history information from both contributors at the top
joachim99@69 580 or sort the history information by a user defined key.
joachim99@69 581 </para><para>
joachim99@73 582 The just-insert-all-entries-method is easier to configure. &kdiff3; just needs a method to
joachim99@69 583 detect, which lines belong to one history entry. Most VCS insert an empty line after each
joachim99@73 584 history entry. If there are no other empty lines, this is a sufficient criterion for &kdiff3;.
joachim99@69 585 Just set an empty "History entry start regular expression". If the empty line criterion
joachim99@69 586 isn't sufficient, you can specify a regular expression to detect the history entry start.
joachim99@69 587 </para><para>
joachim99@73 588 Note that &kdiff3; will remove duplicate history entrys. If a history entry appeared several times
joachim99@69 589 in the history of a input file, only one entry will remain in the output.
joachim99@69 590 </para><para>
joachim99@69 591 If you want to sort the history, then you have to specify how the sort key should be built.
joachim99@69 592 Use parentheses in the "History entry start regular expression" to group parts of the regular
joachim99@69 593 expression that should later be used for the sort key.
joachim99@69 594 Then specify the "History entry start sort key order" specifying a comma "," separated list of
joachim99@69 595 numbers referring to the position of the group in the regular expression.
joachim99@69 596 </para><para>
joachim99@69 597 Because this is not so easy to get right immediately, you are able to test and improve
joachim99@69 598 the regular expressions and key-generation in a dedicated dialog by pressing the
joachim99@69 599 "Test your regular expressions"-button.
joachim99@69 600 </para><para>Example: Assume a history that looks like this:
joachim99@69 601 <screen>
joachim99@69 602 /**************************************************************************
joachim99@73 603 ** HISTORY: &#36;Log: \toms_merge_main_view\MyApplication\src\complexalgorithm.cpp &#36;
joachim99@69 604 **
joachim99@69 605 ** \main\integration_branch_12 2 Apr 2001 10:45:41 tom
joachim99@69 606 ** Merged branch simon_branch_15.
joachim99@69 607 **
joachim99@69 608 ** \main\henry_bugfix_branch_7\1 30 Mar 2001 19:22:05 henry
joachim99@69 609 ** Improved the speed for subroutine convertToMesh().
joachim99@69 610 ** Fixed crash.
joachim99@69 611 **************************************************************************/
joachim99@69 612 </screen>
joachim99@73 613 The history start line matches the regular expression ".*\&#36;Log.*\&#36;.*". Then follow
joachim99@69 614 the history entries.
joachim99@69 615 </para><para>
joachim99@73 616 The line with the "&#36;Log&#36;"-keyword begins with two "*" after which follows a space.
joachim99@73 617 &kdiff3; uses the first non-white-space string as "leading comment" and assumes that
joachim99@69 618 the history ends in the first line without this leading comment. In this example the
joachim99@69 619 last line ends with a string that also starts with two "*", but instead of a space
joachim99@69 620 character more "*" follow. Hence this line ends the history.
joachim99@69 621 </para><para>
joachim99@69 622 If history sorting isn't required then the history entry start line regular expression
joachim99@69 623 could look like this. (This line is split in two because it wouldn't fit otherwise.)
joachim99@69 624 <screen>
joachim99@69 625 \s*\\main\\\S+\s+[0-9]+ (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)
joachim99@69 626 [0-9][0-9][0-9][0-9] [0-9][0-9]:[0-9][0-9]:[0-9][0-9]\s+.*
joachim99@69 627 </screen>
joachim99@69 628 For details about regular expressions please see the
joachim99@69 629 <ulink url="http://doc.trolltech.com/3.3/qregexp.html#details">regular expression documentation by Trolltech</ulink>.
joachim99@69 630 Note that "\s" (with lowercase "s") matches any white space and "\S" (with uppercase "S") matches any non-white-space.
joachim99@69 631 In our example the history entry start contains first the version info with reg. exp. "\\main\\\S+", the date consisting of day "[0-9]+", month "(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)" and year "[0-9][0-9][0-9][0-9]", the time "[0-9][0-9]:[0-9][0-9]:[0-9][0-9]" and finally the developers login name ".*".
joachim99@77 632 </para><para>
joachim99@77 633 Note that the "leading comment"-characters (in the example "**") will already be removed by &kdiff3;
joachim99@69 634 before trying to match, hence the regular expression begins with a match for none or more white-space characters "\s*".
joachim99@77 635 Because comment characters can differ in each file (e.g. C/C++ uses other comment characters than a Perl script)
joachim99@77 636 &kdiff3; takes care of the leading comment characters and you should not specify them in the regular expression.
joachim99@69 637 </para><para>
joachim99@69 638 If you require a sorted history. Then the sortkey must be calculated. For this the
joachim99@69 639 relevant parts in the regular expression must be grouped by parentheses.
joachim99@69 640 (The extra parentheses can also stay in if history sorting is disabled.)
joachim99@69 641 <screen>
joachim99@69 642 \s*\\main\\(\S+)\s+([0-9]+) (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)
joachim99@69 643 ([0-9][0-9][0-9][0-9]) ([0-9][0-9]:[0-9][0-9]:[0-9][0-9])\s+(.*)
joachim99@69 644 </screen>
joachim99@69 645 The parentheses now contain 1. version info, 2. day, 3. month, 4. year, 5. time, 6. name.
joachim99@69 646 But if we want to sort by date and time, we need to construct a key with the elements in a different order of appearance:
joachim99@69 647 First the year, followed by month, day, time, version info and name. Hence the sortkey order to specify is "4,3,2,5,1,6".
joachim99@69 648 </para><para>
joachim99@73 649 Because month names aren't good for sorting ("Apr" would be first) &kdiff3; detects in which order
joachim99@69 650 the month names were given and uses that number instead ("Apr"->"04").
joachim99@69 651 And if a pure number is found it will be transformed to a 4-digit value with leading zeros for sorting.
joachim99@69 652 Finally the resulting sort key for the first history entry start line will be:
joachim99@69 653 <screen>
joachim99@69 654 2001 04 0002 10:45:41 integration_branch_12 tom
joachim99@69 655 </screen>
joachim99@69 656 </para><para>
joachim99@77 657 For more information also see <link linkend="mergeoptions">Merge Settings</link>.
joachim99@11 658 </para>
joachim99@69 659 </sect2>
joachim99@11 660 </sect1>
joachim99@11 661
joachim99@11 662 <sect1 id="navigation"><title>Navigation And Editing</title>
joachim99@11 663 <para>
joachim99@11 664 Much navigation will be done with the scroll bars and the mouse but
joachim99@11 665 you can also navigate with the keys. If you click into either window then
joachim99@11 666 you can use the cursor buttons left, right, up, down, page up, page down,
joachim99@11 667 home, end, ctrl-home, ctrl-end as you would in other programs. The overview-column
joachim99@11 668 next to the vertical scroll bar of the input files can also be used for
joachim99@11 669 navigating by clicking into it.
joachim99@11 670 </para><para>
joachim99@11 671 You can also use the wheel mouse to scroll up and down.
joachim99@11 672 </para><para>
joachim99@11 673 In the merge output editor you can also use the other keys for editing.
joachim99@11 674 You can toggle between insert and overwrite mode with the insert key. (Default
joachim99@11 675 is insert-mode.)
joachim99@11 676 </para><para>
joachim99@11 677 A left-mouse-button-click into any summary column will synchronise all
joachim99@11 678 windows to show the beginning of the same group of lines (as explained
joachim99@69 679 in section <link linkend="synchronise_views">"Setting The Current Group And Synchronising Merge And Diff View Position"</link>).
joachim99@11 680 </para><para>
joachim99@69 681 The button bar also contains nine navigation buttons with which you can
joachim99@11 682 jump to the current/first/last difference, to the next/previous difference
joachim99@11 683 (ctrl-down/ctrl-up), to the next/previous conflict (ctrl-pgdown/ctrl-pgup),
joachim99@73 684 or to the next/previous unsolved conflict. Note that for &kdiff3; a "conflict"
joachim99@11 685 that was not automatically solved at the start of the merge stays a "conflict"
joachim99@11 686 even if it is solved. Hence the necessity to distinguish "unsolved conflicts".
joachim99@69 687 </para>
joachim99@69 688 <sect2 id="autoadvance"><title>Auto-Advance</title>
joachim99@69 689 <para>
joachim99@11 690 There also is a button "Automatically go to next unsolved conflict after
joachim99@11 691 source selection" (Auto-Advance). If you enable this, then, when one source
joachim99@73 692 is selected, &kdiff3; will jump to and select the next unsolved conflict
joachim99@11 693 automatically. This can help when you always want to choose one source only.
joachim99@11 694 When you need both sources, or you want to edit after selecting, then you
joachim99@11 695 probably want to switch this off. Before proceeding to the next unsolved conflict
joachim99@73 696 &kdiff3; shows you the effect of your choice for a short time. This delay is
joachim99@11 697 adjustable in the Diff- &amp; Merge-Settings: You can
joachim99@11 698 specify the "Auto-Advance delay" in milli seconds between 0 and 2000. Hint:
joachim99@11 699 Tired of many clicks? - Use a small Auto-Advance-delay and the shortcuts
joachim99@11 700 Ctrl-1/2/3 to select A/B/C for many conflicts.
joachim99@11 701 </para>
joachim99@69 702 </sect2>
joachim99@11 703 </sect1>
joachim99@11 704
joachim99@11 705 <sect1 id="selections"><title>Select, Copy And Paste</title>
joachim99@11 706 <para>
joachim99@11 707 The input windows don't show a cursor, so selections must be made
joachim99@11 708 with the mouse by clicking with the left mouse button at the start, holding
joachim99@11 709 down the mousebutton and moving to the end, where you release the mouse
joachim99@11 710 button again. You can also select a word by double clicking it. In the merge
joachim99@11 711 output editor you can also select via the keyboard by holding the "shift"-button
joachim99@11 712 and navigation with the cursor keys.
joachim99@11 713 </para><para>
joachim99@69 714 If the selection exceeds the visible range you can move the mouse over the
joachim99@73 715 window borders which causes &kdiff3; to scroll in that direction.
joachim99@69 716 </para><para>
joachim99@69 717 For very large selections you can also use the navigation keys while holding down
joachim99@69 718 the mouse. E.g. use page up and page down to quickly go to a certain position. At the
joachim99@69 719 end position release the mouse button.
joachim99@69 720 </para><para>
joachim99@69 721 In order to select everything in the current window use menu "Edit"->"Select All" (Ctrl-A).
joachim99@69 722 </para><para>
joachim99@11 723 To copy to the clipboard you must press the "Copy"-button (Ctrl-C or Ctrl-Insert).
joachim99@69 724 But there exists an option "Auto Copy Selection". If this is enabled,
joachim99@69 725 then whatever you select is copied immediately and you don't need to explicitely
joachim99@11 726 copy. But pay attention when using this because the contents of the clipboard
joachim99@69 727 might then be destroyed accidentally.
joachim99@11 728 </para><para>
joachim99@11 729 "Cut" (Ctrl-X or Shift-Delete) copies to the clipboard and deletes the
joachim99@69 730 selected text.
joachim99@69 731 </para><para>
joachim99@69 732 "Paste" (Ctrl-V or Shift-Insert) inserts the text in the clipboard at the
joachim99@69 733 cursorposition or over the current selection.
joachim99@69 734 If you paste to either diff input window the contents of the clipboard will
joachim99@69 735 be shown in that window and the comparison will restart immediately. This is
joachim99@69 736 useful if you want to quickly grab a piece of text from somewhere and
joachim99@69 737 compare it with something else without first creating files.
joachim99@11 738 </para>
joachim99@11 739 </sect1>
joachim99@11 740
joachim99@11 741 <sect1 id="saving"><title>Saving</title>
joachim99@11 742 <para>
joachim99@11 743 Saving will only be allowed, when all conflicts were solved. If the file
joachim99@11 744 already exists and the "Backup files"-option is enabled then the existing
joachim99@11 745 file will be renamed with an ".orig"-extension, but if such a file exists
joachim99@11 746 it will be deleted. When you exit or start another diff-analysis and data
joachim99@73 747 wasn't saved yet, then &kdiff3; will ask if you want to save, cancel or proceed
joachim99@73 748 without saving. (&kdiff3; does not catch any signals. So if you "kill" &kdiff3;
joachim99@11 749 then your data will be lost.)
joachim99@11 750 </para><para>
joachim99@11 751 Line endings are saved according to the normal method on the underlying
joachim99@11 752 operating system. For Unices each line ends with an linefeed-character "\n",
joachim99@11 753 while for Win32-based systems each line ends with a carriage-return + a linefeed
joachim99@73 754 "\r\n". &kdiff3; does not preserve the line-endings of the input files, which
joachim99@73 755 also means that you shouldn't use &kdiff3; with binary files.
joachim99@11 756 </para>
joachim99@11 757 </sect1>
joachim99@11 758
joachim99@11 759 <sect1 id="find"><title>Finding Strings</title>
joachim99@11 760 <para>
joachim99@73 761 You can search for a string in any text-window of &kdiff3;. The "Find ..."-command
joachim99@11 762 (Ctrl-F) in the Edit-menu opens a dialog that lets you specify the string
joachim99@11 763 to search for. You can also select the windows which should be searched.
joachim99@11 764 Searching will always start at the top. Use the "Find Next"-command (F3)
joachim99@69 765 to proceed to the next occurrence. If you select to search several windows then the first
joachim99@11 766 window will be searched from top to bottom before the search starts in the next
joachim99@11 767 window at the top again, etc.
joachim99@11 768 </para>
joachim99@11 769 </sect1>
joachim99@11 770
joachim99@69 771 <sect1 id="printing"><title>Printing</title>
joachim99@69 772 <para>
joachim99@73 773 &kdiff3; supports printing for textfile differences. The "Print..."-command (Ctrl-P)
joachim99@69 774 in the File-menu opens a dialog that allows you to select the printer and to adjust
joachim99@69 775 other options.
joachim99@69 776 </para><para>
joachim99@69 777 There are several possibilities to adjust the range. Due to different printing
joachim99@69 778 dialogs on different operating systems, the method to achieve certain range selections varies.
joachim99@69 779 </para>
joachim99@69 780 <variablelist>
joachim99@69 781 <varlistentry><term>All:</term><listitem><para>Print everything.</para></listitem></varlistentry>
joachim99@69 782 <varlistentry><term>Current:</term><listitem><para>Print a page starting at the first visible line in the window.
joachim99@69 783 (On systems without this option this can be achived by specifying page number 10000 for printing.)</para></listitem></varlistentry>
joachim99@69 784 <varlistentry><term>Selection:</term><listitem><para>
joachim99@69 785 Before choosing to print select text with the mouse (like for copy and paste)
joachim99@69 786 in one of the diff input windows to define the start and end line. If no text
joachim99@69 787 in one of the diff input windows was selected, then this won't be an available
joachim99@69 788 choice. (On systems without this option this can be achived by specifying page
joachim99@69 789 number 9999 for printing.)</para></listitem></varlistentry>
joachim99@69 790 <varlistentry><term>Range:</term><listitem><para>Specify the first and last page.
joachim99@69 791 </para></listitem></varlistentry>
joachim99@69 792 </variablelist>
joachim99@69 793 <para>
joachim99@69 794 Other important options for printing will be taken from the normal options:
joachim99@69 795 </para><itemizedlist>
joachim99@69 796 <listitem><para>Font, font size</para></listitem>
joachim99@69 797 <listitem><para>Show line numbers</para></listitem>
joachim99@69 798 <listitem><para>Word wrap</para></listitem>
joachim99@69 799 <listitem><para>Colors</para></listitem>
joachim99@69 800 <listitem><para>etc.</para></listitem>
joachim99@69 801 </itemizedlist>
joachim99@69 802 <para>
joachim99@69 803 Landscape formatting is also recommended for printing.
joachim99@69 804 </para>
joachim99@69 805 </sect1>
joachim99@11 806
joachim99@11 807 <sect1 id="options"><title>Options</title>
joachim99@11 808 <para>
joachim99@11 809 Options and the recent-file-list will be saved when you exit the program,
joachim99@73 810 and reloaded when you start it. (Menu Settings->Configure &kdiff3; ...)
joachim99@11 811 </para>
joachim99@11 812 <sect2><title>Font</title>
joachim99@11 813 <para>
joachim99@11 814 Select a fixed width font. (On some systems this dialog will also
joachim99@11 815 present variable width fonts, but you should not use them.)
joachim99@11 816 </para>
joachim99@11 817 <variablelist>
joachim99@11 818 <varlistentry><term><emphasis>Italic Font for Deltas:</emphasis></term><listitem><para> If you select this, then text differences
joachim99@11 819 will be drawn with the italic version of the selected font. If the font
joachim99@11 820 doesn't support italic, then this does nothing.</para>
joachim99@11 821 </listitem></varlistentry>
joachim99@11 822 </variablelist>
joachim99@11 823 </sect2>
joachim99@11 824
joachim99@11 825 <sect2><title>Colors</title>
joachim99@11 826 <variablelist>
joachim99@11 827 <varlistentry><term><emphasis>Foreground color:</emphasis></term><listitem><para> Usually black. </para></listitem></varlistentry>
joachim99@11 828 <varlistentry><term><emphasis>Background color:</emphasis></term><listitem><para> Usually white. </para></listitem></varlistentry>
joachim99@11 829 <varlistentry><term><emphasis>Diff Background color:</emphasis></term><listitem><para> Usually light gray. </para></listitem></varlistentry>
joachim99@11 830 <varlistentry><term><emphasis>Color A:</emphasis></term><listitem><para> Usually dark blue. </para></listitem></varlistentry>
joachim99@11 831 <varlistentry><term><emphasis>Color B:</emphasis></term><listitem><para> Usually dark green. </para></listitem></varlistentry>
joachim99@11 832 <varlistentry><term><emphasis>Color C:</emphasis></term><listitem><para> Usually dark magenta. </para></listitem></varlistentry>
joachim99@11 833 <varlistentry><term><emphasis>Conflict Color:</emphasis></term><listitem><para> Usually red.</para></listitem></varlistentry>
joachim99@11 834 <varlistentry><term><emphasis>Current range background color:</emphasis></term><listitem><para> Usually light yellow.</para></listitem></varlistentry>
joachim99@11 835 <varlistentry><term><emphasis>Current range diff background color:</emphasis></term><listitem><para> Usually dark yellow.</para></listitem></varlistentry>
joachim99@69 836 <varlistentry><term><emphasis>Color for manually selected diff ranges:</emphasis></term><listitem><para> Usually orange.</para></listitem></varlistentry>
joachim99@69 837 <varlistentry><term><emphasis>Newest file color in directory comparison:</emphasis></term><listitem><para> Usually green.</para></listitem></varlistentry>
joachim99@69 838 <varlistentry><term><emphasis>Oldest file color in directory comparison:</emphasis></term><listitem><para> Usually red.</para></listitem></varlistentry>
joachim99@69 839 <varlistentry><term><emphasis>Middle age file color in directory comparison:</emphasis></term><listitem><para> Usually dark yellow.</para></listitem></varlistentry>
joachim99@69 840 <varlistentry><term><emphasis>Color for missing files in directory comparison:</emphasis></term><listitem><para> Usually black.</para></listitem></varlistentry>
joachim99@11 841 </variablelist>
joachim99@11 842 <para>
joachim99@69 843 Changing the colors for directory comparison will be effective only when starting the next directory comparison.
joachim99@69 844 </para>
joachim99@69 845 <para>
joachim99@11 846 On systems with only 16 or 256 colors some colors are not available in pure
joachim99@11 847 form. On such systems the "Defaults"-button will choose a pure color.
joachim99@11 848 </para>
joachim99@11 849 </sect2>
joachim99@11 850
joachim99@11 851 <sect2><title>Editor Settings</title>
joachim99@11 852 <variablelist>
joachim99@11 853 <varlistentry><term><emphasis>Tab inserts spaces:</emphasis></term><listitem><para> If this is disabled and you press the
joachim99@11 854 tabulator key, a tab-character is inserted, otherwise the appropriate
joachim99@11 855 amount of characters is inserted.</para></listitem></varlistentry>
joachim99@11 856 <varlistentry><term><emphasis> Tab size:</emphasis></term><listitem><para> Can be adjusted for your specific needs. Default is 8. </para></listitem></varlistentry>
joachim99@11 857 <varlistentry><term><emphasis> Auto indentation:</emphasis></term><listitem><para> When pressing Enter or Return the indentation
joachim99@11 858 of the previous line is used for the new line. </para></listitem></varlistentry>
joachim99@11 859 <varlistentry><term><emphasis> Auto copy selection:</emphasis></term><listitem><para> Every selection is immediately copied
joachim99@11 860 to the clipboard when active and you needn't explicitely copy it. </para></listitem></varlistentry>
joachim99@66 861 <varlistentry><term><emphasis> Line end style:</emphasis></term><listitem><para> When saving you can select what line
joachim99@66 862 end style you prefer. The default setting is the common choice for the used operating system. </para></listitem></varlistentry>
joachim99@11 863 </variablelist>
joachim99@11 864 </sect2>
joachim99@11 865
joachim99@77 866 <sect2 id="diffoptions"><title>Diff Settings</title>
joachim99@11 867 <para>
joachim99@73 868 When comparing files, &kdiff3; first it tries to match lines that are equal
joachim99@11 869 in all input files. Only during this step it might ignore white space. The
joachim99@11 870 second step compares each line. In this step white space will not be ignored.
joachim99@11 871 Also during the merge white space will not be ignored.
joachim99@11 872 </para>
joachim99@11 873
joachim99@11 874 <variablelist>
joachim99@11 875 <varlistentry><term><emphasis>Preserve Carriage Return:</emphasis></term><listitem><para> Some editors (on some systems) save
joachim99@11 876 carriage return '\r' and linefeed '\n'-characters at the end of line, while
joachim99@73 877 others will only save the linefeed '\n'. Usually &kdiff3; ignores the carriage
joachim99@11 878 return, but then files that don't have equal sizes, look equal in side by
joachim99@11 879 side comparison. When this option is on, then the carriage return characters
joachim99@11 880 are made visible but are treated as white space. This option must be off
joachim99@11 881 during a merge. Default is off.</para></listitem></varlistentry>
joachim99@11 882 <varlistentry><term><emphasis>Ignore numbers:</emphasis></term><listitem><para> Default is off. Number characters ('0'-'9', '.', '-')
joachim99@11 883 will be ignored in the first part of the analysis in which the line matching is
joachim99@11 884 done. In the result the differences will be shown nevertheless, but they are treated
joachim99@11 885 as white space.
joachim99@11 886 </para></listitem></varlistentry>
joachim99@51 887 <varlistentry><term><emphasis>Ignore C/C++ comments:</emphasis></term><listitem><para> Default is off.
joachim99@51 888 Changes in comments will be treated like changes in white space.
joachim99@51 889 </para></listitem></varlistentry>
joachim99@66 890 <varlistentry><term><emphasis>Ignore case:</emphasis></term><listitem><para> Default is off.
joachim99@66 891 Case-differences of characters (like 'A' vs. 'a') will be treated like changes in white space.
joachim99@11 892 </para></listitem></varlistentry>
joachim99@11 893 <varlistentry><term><emphasis>Preprocessor-Command:</emphasis></term><listitem><para>
joachim99@66 894 See <link linkend="preprocessors">next section</link>.
joachim99@11 895 </para></listitem></varlistentry>
joachim99@11 896 <varlistentry><term><emphasis>Line-Matching Preprocessor-Command:</emphasis></term><listitem><para>
joachim99@66 897 See <link linkend="preprocessors">next section</link>.
joachim99@11 898 </para></listitem></varlistentry>
joachim99@51 899 <varlistentry><term><emphasis>Try Hard:</emphasis></term><listitem><para>
joachim99@51 900 Try hard to find an even smaller delta. (Default is on.) This will probably
joachim99@11 901 be effective for complicated and big files. And slow for very big files.
joachim99@11 902 </para></listitem></varlistentry>
joachim99@77 903 </variablelist>
joachim99@77 904 </sect2>
joachim99@77 905
joachim99@77 906 <sect2 id="mergeoptions"><title>Merge Settings</title>
joachim99@77 907 <variablelist>
joachim99@11 908 <varlistentry><term><emphasis>Auto Advance Delay (ms):</emphasis></term><listitem><para> When in auto-advance-mode this setting specifies
joachim99@11 909 how long to show the result of the selection before jumping to the next unsolved
joachim99@11 910 conflict.
joachim99@11 911 </para></listitem></varlistentry>
joachim99@51 912 <varlistentry><term><emphasis>White space 2/3-file merge default:</emphasis></term><listitem><para>
joachim99@51 913 Automatically solve all white-space conflict by choosing the specified file.
joachim99@73 914 (Default is manual choice.) Useful if white space really isn't important in many files.
joachim99@51 915 If you need this only occasionally better use "Choose A/B/C For All Unsolved Whitespace Conflicts"
joachim99@51 916 in the merge menu. Note that if you enable either "Ignore numbers" or "Ignore C/C++ comments"
joachim99@51 917 then this auto-choice also applies for conflicts in numbers or comments.
joachim99@51 918 </para></listitem></varlistentry>
joachim99@69 919 <varlistentry><term><emphasis>Auto merge regular expression:</emphasis></term><listitem><para>
joachim99@73 920 Regular expression for lines where &kdiff3; should automatically choose one source. See also <link linkend="vcskeywordsmergesupport">Automatic Merge ...</link>
joachim99@69 921 </para></listitem></varlistentry>
joachim99@69 922 <varlistentry><term><emphasis>Run regular expression auto merge on merge start:</emphasis></term><listitem><para>
joachim99@73 923 If activated &kdiff3; runs the automatic merge using the "Auto merge regular expression" when a merge is started.
joachim99@69 924 </para></listitem></varlistentry>
joachim99@69 925 <varlistentry><term><emphasis>History start regular expression:</emphasis></term><listitem><para>
joachim99@69 926 Regular expression for the start of the merge history entry.
joachim99@73 927 Usually this line contains the "&#36;Log&#36;"-keyword.
joachim99@73 928 Default value: ".*\&#36;Log.*\&#36;.*"
joachim99@69 929 </para></listitem></varlistentry>
joachim99@69 930 <varlistentry><term><emphasis>History entry start regular expression:</emphasis></term><listitem><para>
joachim99@69 931 A merge history entry consists of several lines.
joachim99@69 932 Specify the regular expression to detect the first line (without the leading comment).
joachim99@69 933 Use parentheses to group the keys you want to use for sorting.
joachim99@73 934 If left empty, then &kdiff3; assumes that empty lines separate history entries.
joachim99@69 935 See also <link linkend="vcskeywordsmergesupport">Automatic Merge ...</link>
joachim99@69 936 </para></listitem></varlistentry>
joachim99@69 937 <varlistentry><term><emphasis>History merge sorting:</emphasis></term><listitem><para>
joachim99@69 938 Enable version control history sorting.
joachim99@69 939 </para></listitem></varlistentry>
joachim99@69 940 <varlistentry><term><emphasis>History entry start sort key order:</emphasis></term><listitem><para>
joachim99@69 941 Each parentheses used in the regular expression for the history start entry
joachim99@69 942 groups a key that can be used for sorting.
joachim99@69 943 Specify the list of keys (that are numbered in order of occurrence
joachim99@69 944 starting with 1) using ',' as separator (e.g. "4,5,6,1,2,3,7").
joachim99@69 945 If left empty, then no sorting will be done.
joachim99@69 946 See also <link linkend="vcskeywordsmergesupport">Automatic Merge ...</link>
joachim99@69 947 </para></listitem></varlistentry>
joachim99@69 948 <varlistentry><term><emphasis>Merge version control history on merge start:</emphasis></term><listitem><para>
joachim99@73 949 If activated &kdiff3; runs the automatic history merging using aforementioned options when a merge is started.
joachim99@69 950 </para></listitem></varlistentry>
joachim99@77 951 <varlistentry><term><emphasis>Max number of history entries:</emphasis></term><listitem><para>
joachim99@77 952 &kdiff3; truncates the history list after the specified number of entries. Use -1 to avoid truncation. (Default is -1).
joachim99@77 953 </para></listitem></varlistentry>
joachim99@69 954 <varlistentry><term><emphasis>Test your regular expressions</emphasis></term><listitem><para>
joachim99@69 955 This button shows a dialog that allows you to improve and test the regular expressions above.
joachim99@69 956 Just copy the respective data from your files into the example lines. The "Match results"
joachim99@69 957 will immediately show whether the match succeeds or not.
joachim99@69 958 The "Sort key result" will display the key used for history merge sorting.
joachim99@69 959 </para></listitem></varlistentry>
joachim99@69 960 <varlistentry><term><emphasis>Irrelevant merge command:</emphasis></term><listitem><para>
joachim99@73 961 Specify a command of your own that should be called when &kdiff3; detects
joachim99@69 962 that for a three file merge the file from B doesn't contribute any
joachim99@69 963 relevant data that isn't already contained in the file from C.
joachim99@69 964 The command is called with the three filenames as parameters.
joachim99@69 965 Data matched by the "Auto merge regular expression" or in the
joachim99@69 966 history isn't considered relevant.
joachim99@69 967 </para></listitem></varlistentry>
joachim99@11 968 </variablelist>
joachim99@11 969
joachim99@11 970 </sect2>
joachim99@11 971
joachim99@11 972 <sect2><title>Directory Merge</title>
joachim99@11 973 <para>
joachim99@11 974 These options are concerned with scanning the directory and handling the
joachim99@11 975 merge: See the <link linkend="dirmergeoptions">Directory Comparison/Merge
joachim99@11 976 Docs</link> for details.
joachim99@11 977 </para><para>
joachim99@11 978 Yet there is one option here that is also relevant for saving single files:
joachim99@11 979 </para>
joachim99@11 980 <variablelist>
joachim99@11 981 <varlistentry><term><emphasis>Backup files:</emphasis></term><listitem><para> When a file is saved and an older version already
joachim99@11 982 exists, then the original version will be renamed with an ".orig" extension.
joachim99@11 983 If an old backup file with ".orig" extension already exists then this will
joachim99@11 984 be deleted without backup.
joachim99@11 985 </para></listitem></varlistentry>
joachim99@11 986 </variablelist>
joachim99@11 987 </sect2>
joachim99@11 988
joachim99@68 989 <sect2><title>Regional and Language Options</title>
joachim99@68 990 <variablelist>
joachim99@73 991 <varlistentry><term><emphasis>Language:</emphasis></term><listitem><para>Adjust the language of the user interface. Changing this option doesn't affect the running program. You have to exit and restart &kdiff3; so that the language is changed. (This option is not available in the KDE version of &kdiff3; because the language is adjustable in the global KDE settings.)
joachim99@68 992 </para></listitem></varlistentry>
joachim99@68 993 <varlistentry><term><emphasis>Use the same encoding for everything:</emphasis></term><listitem><para> The following encoding options can be adjusted separately for each item or if this option is true, all values will take the first value.
joachim99@68 994 </para></listitem></varlistentry>
joachim99@68 995 <varlistentry><term><emphasis>Local Encoding:</emphasis></term><listitem><para>Above the codec-selectors appears a note that tells you what the local encoding is. (This is not adjustable but for your information just in case you don't know your local encoding, but need to select it.)
joachim99@68 996 </para></listitem></varlistentry>
joachim99@68 997 <varlistentry><term><emphasis>File Encoding for A/B/C:</emphasis></term><listitem><para> Adjust the file encoding for input files. This has an effect on how the special characters are interpreted. Since you can adjust each codec separately you can even compare and merge files that were saved using different codecs.
joachim99@68 998 </para></listitem></varlistentry>
joachim99@68 999 <varlistentry><term><emphasis>File Encoding for Merge Output and Saving:</emphasis></term><listitem><para> When you have edited a file, then you can adjust which encoding will be used when saving to disk.
joachim99@68 1000 </para></listitem></varlistentry>
joachim99@68 1001 <varlistentry><term><emphasis>File Encoding for Preprocessor Files:</emphasis></term><listitem><para>When you define preprocessors then they might not be able to operate on your codec. (e.g.: Your files are 16-bit-unicode and your preprocessor can only take 8-bit-ascii.) With this option you can define the encoding of preprocessor output.
joachim99@68 1002 </para></listitem></varlistentry>
joachim99@73 1003 <varlistentry><term><emphasis>Right To Left Language:</emphasis></term><listitem><para>Some languages are written right to left. When this option is enabled, &kdiff3; draws the text from right to left in the diff input windows and in the merge output window. Note that if you start &kdiff3; with the command line option "--reverse" then all layouting will be done right to left too. (This is a feature provided by Qt.) This documentation was written assuming that "Right To Left Language" or reverse layout are disabled. So some references to "left" or "right" must be replaced by their respective counterpart if you use these options.
joachim99@68 1004 </para></listitem></varlistentry>
joachim99@68 1005
joachim99@68 1006 </variablelist>
joachim99@68 1007 </sect2>
joachim99@68 1008
joachim99@11 1009 <sect2><title>Miscellaneous</title>
joachim99@11 1010 <para>(These options and actions are available in menus or the buttonbar.)</para>
joachim99@11 1011 <variablelist>
joachim99@11 1012 <varlistentry><term><emphasis>Show line numbers:</emphasis></term><listitem><para> You can select if line numbers should be
joachim99@11 1013 shown for the input files.</para></listitem></varlistentry>
joachim99@11 1014 <varlistentry><term><emphasis>Show space and tabulator characters for differences:</emphasis></term><listitem><para> Sometimes
joachim99@11 1015 the visible spaces and tabs are disturbing. You can turn this off.</para></listitem></varlistentry>
joachim99@51 1016 <varlistentry><term><emphasis>Show white space:</emphasis></term><listitem><para> Turn this off to suppress
joachim99@51 1017 any highlighting of white-space-only changes in the text or overview-columns.
joachim99@51 1018 (Note that this also applies to changes in numbers or comments if the options "Ignore numbers"
joachim99@51 1019 or "Ignore C/C++ comments" are active.)</para></listitem></varlistentry>
joachim99@66 1020 <varlistentry><term><emphasis>Overview options:</emphasis></term><listitem><para>
joachim99@66 1021 These choices are only available when you compare three files. In normal mode all
joachim99@66 1022 differences are shown in one color-coded overview-column. But sometimes you are
joachim99@66 1023 especially interested in the differences between only two of these three files.
joachim99@66 1024 Selecting "A vs. B", "A vs. C" or "B vs. C"-overview will show a second overview
joachim99@66 1025 column with the required information next to the normal overview.
joachim99@66 1026 </para></listitem></varlistentry>
joachim99@66 1027 <varlistentry><term><emphasis>Word wrap diff windows:</emphasis></term><listitem><para>
joachim99@66 1028 Wrap lines when their length would exceed the width of a window.
joachim99@66 1029 </para></listitem></varlistentry>
joachim99@11 1030 <varlistentry><term><emphasis>Show Window A/B/C:</emphasis></term><listitem><para> Sometimes you want to use the space on
joachim99@11 1031 the screen better for long lines. Hide the windows that are not important.
joachim99@11 1032 (In the Windows-menu.)</para></listitem></varlistentry>
joachim99@11 1033 <varlistentry><term><emphasis>Toggle Split Orientation:</emphasis></term><listitem><para>
joachim99@11 1034 Switch between diff windows shown next to each other (A left of B left of C) or above
joachim99@11 1035 each other (A above B above C). This should also help for long lines. (In the Windows-menu.)
joachim99@11 1036 </para></listitem></varlistentry>
joachim99@51 1037 <varlistentry><term><emphasis>Start a merge quickly:</emphasis></term><listitem><para>
joachim99@51 1038 Sometimes you are viewing the deltas and decide to merge.
joachim99@51 1039 <inlinemediaobject><imageobject><imagedata fileref="merge_current.png" format="PNG"/></imageobject></inlinemediaobject>
joachim99@11 1040 "Merge current file" in the Directory-menu also works if you only compare
joachim99@11 1041 two files. A single click starts the merge and uses the filename of the last
joachim99@11 1042 input-file as the default output filename. (When this is used to restart
joachim99@11 1043 a merge, then the output filename will be preserved.)</para></listitem></varlistentry>
joachim99@11 1044 </variablelist>
joachim99@11 1045 </sect2>
joachim99@11 1046
joachim99@11 1047 <sect2 id="shortcuts"><title>Configuring Keyboard-Shortcuts</title>
joachim99@11 1048 <para>
joachim99@11 1049 Currently only the KDE-version supports user-configurable keyboard-shortcuts.
joachim99@11 1050 (Menu Settings->Configure Shortcuts...)
joachim99@11 1051 </para>
joachim99@11 1052 </sect2>
joachim99@11 1053 </sect1>
joachim99@66 1054
joachim99@66 1055 <sect1 id="preprocessors"><title>Preprocessor Commands</title>
joachim99@66 1056 <para>
joachim99@73 1057 &kdiff3; supports two preprocessor options.
joachim99@66 1058 </para><para>
joachim99@66 1059 <variablelist>
joachim99@66 1060 <varlistentry><term><emphasis>Preprocessor-Command:</emphasis></term><listitem><para>
joachim99@66 1061 When any file is read, it will be piped through this external command.
joachim99@66 1062 The output of this command will be visible instead of the original file.
joachim99@66 1063 You can write your own preprocessor that fulfills your specific needs.
joachim99@66 1064 Use this to cut away disturbing parts of the file, or to automatically
joachim99@66 1065 correct the indentation etc.
joachim99@66 1066 </para></listitem></varlistentry>
joachim99@66 1067 <varlistentry><term><emphasis>Line-Matching Preprocessor-Command:</emphasis></term><listitem><para>
joachim99@66 1068 When any file is read, it will be piped through this external command. If
joachim99@66 1069 a preprocessor-command (see above) is also specified, then the output of the
joachim99@66 1070 preprocessor is the input of the line-matching preprocessor.
joachim99@66 1071 The output will only be used during the line matching phase of the analysis.
joachim99@66 1072 You can write your own preprocessor that fulfills your specific needs.
joachim99@66 1073 Each input line must have a corresponding output line.
joachim99@66 1074 </para></listitem></varlistentry>
joachim99@66 1075 </variablelist>
joachim99@66 1076 </para>
joachim99@66 1077 <para>
joachim99@66 1078 The idea is to allow the user greater flexibility while configuring the diff-result.
joachim99@66 1079 But this requires an external program, and many users don't want to write one themselves.
joachim99@66 1080 The good news is that very often <command>sed</command> or <command>perl</command>
joachim99@66 1081 will do the job.
joachim99@66 1082 </para>
joachim99@66 1083 <para>Example: Simple testcase: Consider file a.txt (6 lines):
joachim99@66 1084 <screen>
joachim99@66 1085 aa
joachim99@66 1086 ba
joachim99@66 1087 ca
joachim99@66 1088 da
joachim99@66 1089 ea
joachim99@66 1090 fa
joachim99@66 1091 </screen>
joachim99@66 1092 And file b.txt (3 lines):
joachim99@66 1093 <screen>
joachim99@66 1094 cg
joachim99@66 1095 dg
joachim99@66 1096 eg
joachim99@66 1097 </screen>
joachim99@66 1098 Without a preprocessor the following lines would be placed next to each other:
joachim99@66 1099 <screen>
joachim99@66 1100 aa - cg
joachim99@66 1101 ba - dg
joachim99@66 1102 ca - eg
joachim99@66 1103 da
joachim99@66 1104 ea
joachim99@66 1105 fa
joachim99@66 1106 </screen>
joachim99@66 1107 This is probably not wanted since the first letter contains the actually interesting information.
joachim99@66 1108 To help the matching algorithm to ignore the second letter we can use a line matching preprocessor
joachim99@66 1109 command, that replaces 'g' with 'a':
joachim99@66 1110 <screen>
joachim99@66 1111 <command>sed</command> 's/g/a/'
joachim99@66 1112 </screen>
joachim99@66 1113 With this command the result of the comparison would be:
joachim99@66 1114 <screen>
joachim99@66 1115 aa
joachim99@66 1116 ba
joachim99@66 1117 ca - cg
joachim99@66 1118 da - dg
joachim99@66 1119 ea - eg
joachim99@66 1120 fa
joachim99@66 1121 </screen>
joachim99@66 1122 Internally the matching algorithm sees the files after running the line matching preprocessor,
joachim99@66 1123 but on the screen the file is unchanged. (The normal preprocessor would change the data also on
joachim99@66 1124 the screen.)
joachim99@66 1125 </para>
joachim99@66 1126
joachim99@66 1127 <sect2 id="sedbasics"><title><command>sed</command> Basics</title>
joachim99@66 1128 <para>
joachim99@66 1129 This section only introduces some very basic features of <command>sed</command>. For more
joachim99@66 1130 information see <ulink url="info:/sed">info:/sed</ulink> or
joachim99@66 1131 <ulink url="http://www.gnu.org/software/sed/manual/html_mono/sed.html">
joachim99@66 1132 http://www.gnu.org/software/sed/manual/html_mono/sed.html</ulink>.
joachim99@66 1133 A precompiled version for Windows can be found at <ulink url="http://unxutils.sourceforge.net">
joachim99@66 1134 http://unxutils.sourceforge.net</ulink>.
joachim99@66 1135 Note that the following examples assume that the <command>sed</command>-command is in some
joachim99@66 1136 directory in the PATH-environment variable. If this is not the case, you have to specify the full absolute
joachim99@69 1137 path for the command.
joachim99@66 1138 </para>
joachim99@69 1139 <note><para>Also note that the following examples use the single quotation mark (') which won't work for Windows.
joachim99@69 1140 On Windows you should use the double quotation marks (") instead.</para></note>
joachim99@66 1141 <para>
joachim99@66 1142 In this context only the <command>sed</command>-substitute-command is used:
joachim99@66 1143 <screen>
joachim99@66 1144 <command>sed</command> 's/<replaceable>REGEXP</replaceable>/<replaceable>REPLACEMENT</replaceable>/<replaceable>FLAGS</replaceable>'
joachim99@66 1145 </screen>
joachim99@73 1146 Before you use a new command within &kdiff3;, you should first test it in a console.
joachim99@66 1147 Here the <command>echo</command>-command is useful. Example:
joachim99@66 1148 <screen>
joachim99@66 1149 <command>echo</command> abrakadabra | <command>sed</command> 's/a/o/'
joachim99@66 1150 -> obrakadabra
joachim99@66 1151 </screen>
joachim99@66 1152 This example shows a very simple sed-command that replaces the first occurance
joachim99@66 1153 of "a" with "o". If you want to replace all occurances then you need the "g"-flag:
joachim99@66 1154 <screen>
joachim99@66 1155 <command>echo</command> abrakadabra | <command>sed</command> 's/a/o/g'
joachim99@66 1156 -> obrokodobro
joachim99@66 1157 </screen>
joachim99@66 1158 The "|"-symbol is the pipe-command that transfers the output of the previous
joachim99@66 1159 command to the input of the following command. If you want to test with a longer file
joachim99@66 1160 then you can use <command>cat</command> on Unix-like systems or <command>type</command>
joachim99@66 1161 on Windows-like systems. <command>sed</command> will do the substitution for each line.
joachim99@66 1162 <screen>
joachim99@66 1163 <command>cat</command> <replaceable>filename</replaceable> | <command>sed</command> <replaceable>options</replaceable>
joachim99@66 1164 </screen>
joachim99@66 1165 </para>
joachim99@66 1166 </sect2>
joachim99@73 1167 <sect2 id="sedforkdiff3"><title>Examples For <command>sed</command>-Use In &kdiff3;</title>
joachim99@66 1168 <sect3><title>Ignoring Other Types Of Comments</title>
joachim99@66 1169 <para>
joachim99@73 1170 Currently &kdiff3; understands only C/C++ comments. Using the
joachim99@66 1171 Line-Matching-Preprocessor-Command you can also ignore
joachim99@66 1172 other types of comments, by converting them into C/C++-comments.
joachim99@66 1173
joachim99@66 1174 Example: To ignore comments starting with "#", you would like to convert them
joachim99@66 1175 to "//". Note that you also must enable the "Ignore C/C++-Comments" option to get
joachim99@66 1176 an effect. An appropriate Line-Matching-Preprocessor-Command would be:
joachim99@66 1177
joachim99@66 1178 <screen>
joachim99@66 1179 <command>sed</command> 's/#/\/\//'
joachim99@66 1180 </screen>
joachim99@66 1181 Since for <command>sed</command> the "/"-character has a special meaning, it is necessary to place the
joachim99@66 1182 "\"-character before each "/" in the replacement-string. Sometimes the "\" is required
joachim99@66 1183 to add or remove a special meaning of certain characters. The single quotation marks (') before
joachim99@66 1184 and after the substitution-command are important now, because otherwise the shell will
joachim99@66 1185 try to interpret some special characters like '#', '$' or '\' before passing them to
joachim99@69 1186 <command>sed</command>. <emphasis>Note that on Windows you will need the double quotation marks (") here. Windows
joachim99@69 1187 substitutes other characters like '%', so you might have to experiment a little bit.</emphasis>
joachim99@66 1188 </para>
joachim99@66 1189 </sect3>
joachim99@66 1190 <sect3><title>Caseinsensitive Diff</title>
joachim99@66 1191 <para>
joachim99@66 1192 Use the following Line-Matching-Preprocessor-Command to convert all input to uppercase:
joachim99@66 1193 <screen>
joachim99@66 1194 <command>sed</command> 's/\(.*\)/\U\1/'
joachim99@66 1195 </screen>
joachim99@66 1196 Here the ".*" is a regular expression that matches any string and in this context matches
joachim99@66 1197 all characters in the line.
joachim99@66 1198 The "\1" in the replacement string refers to the matched text within the first pair of "\(" and "\)".
joachim99@66 1199 The "\U" converts the inserted text to uppercase.
joachim99@66 1200 </para>
joachim99@66 1201 </sect3>
joachim99@66 1202
joachim99@66 1203 <sect3><title>Ignoring Version Control Keywords</title>
joachim99@66 1204 <para>
joachim99@66 1205 CVS and other version control systems use several keywords to insert automatically
joachim99@66 1206 generated strings (<ulink url="info:/cvs/Keyword substitution">info:/cvs/Keyword substitution</ulink>).
joachim99@66 1207 All of them follow the pattern "$KEYWORD generated text$". We now need a
joachim99@66 1208 Line-Matching-Preprocessor-Command that removes only the generated text:
joachim99@66 1209 <screen>
joachim99@66 1210 <command>sed</command> 's/\$\(Revision\|Author\|Log\|Header\|Date\).*\$/\$\1\$/'
joachim99@66 1211 </screen>
joachim99@66 1212 The "\|" separates the possible keywords. You might want to modify this list
joachim99@66 1213 according to your needs.
joachim99@66 1214 The "\" before the "$" is necessary because otherwise the "$" matches the end of the line.
joachim99@66 1215 </para>
joachim99@66 1216 <para>
joachim99@66 1217 While experimenting with <command>sed</command> you might come to understand and even like
joachim99@66 1218 these regular expressions. They are useful because there are many other programs that also
joachim99@66 1219 support similar things.
joachim99@66 1220 </para>
joachim99@66 1221 </sect3>
joachim99@66 1222
joachim99@66 1223 <sect3><title>Ignoring Numbers</title>
joachim99@66 1224 <para>
joachim99@66 1225 Ignoring numbers actually is a built-in option. But as another example, this is how
joachim99@66 1226 it would look as a Line-Matching-Preprocessor-command.
joachim99@66 1227 <screen>
joachim99@66 1228 <command>sed</command> 's/[0123456789.-]//g'
joachim99@66 1229 </screen>
joachim99@66 1230 Any character within '[' and ']' is a match and will be replaced with nothing.
joachim99@66 1231 </para>
joachim99@66 1232 </sect3>
joachim99@66 1233
joachim99@66 1234 <sect3><title>Ignoring Certain Columns</title>
joachim99@66 1235 <para>
joachim99@66 1236 Sometimes a text is very strictly formatted, and contains columns that you always want to ignore, while there are
joachim99@66 1237 other columns you want to preserve for analysis. In the following example the first five columns (characters) are
joachim99@66 1238 ignored, the next ten columns are preserved, then again five columns are ignored and the rest of the line is preserved.
joachim99@66 1239 <screen>
joachim99@66 1240 <command>sed</command> 's/.....\(..........\).....\(.*\)/\1\2/'
joachim99@66 1241 </screen>
joachim99@66 1242 Each dot '.' matches any single character. The "\1" and "\2" in the replacement string refer to the matched text within the first
joachim99@66 1243 and second pair of "\(" and "\)" denoting the text to be preserved.
joachim99@66 1244 </para>
joachim99@66 1245 </sect3>
joachim99@66 1246
joachim99@66 1247 <sect3><title>Combining Several Substitutions</title>
joachim99@66 1248 <para>
joachim99@66 1249 Sometimes you want to apply several substitutions at once. You can then use the
joachim99@66 1250 semicolon ';' to separate these from each other. Example:
joachim99@66 1251 <screen>
joachim99@66 1252 <command>echo</command> abrakadabra | <command>sed</command> 's/a/o/g;s/\(.*\)/\U\1/'
joachim99@66 1253 -> OBROKODOBRO
joachim99@66 1254 </screen>
joachim99@66 1255 </para>
joachim99@66 1256 </sect3>
joachim99@66 1257
joachim99@66 1258 <sect3><title>Using <command>perl</command> instead of <command>sed</command></title>
joachim99@66 1259 <para>
joachim99@66 1260 Instead of <command>sed</command> you might want to use something else like
joachim99@66 1261 <command>perl</command>.
joachim99@66 1262 <screen>
joachim99@66 1263 <command>perl</command> -p -e 's/<replaceable>REGEXP</replaceable>/<replaceable>REPLACEMENT</replaceable>/<replaceable>FLAGS</replaceable>'
joachim99@66 1264 </screen>
joachim99@66 1265 But some details are different in <command>perl</command>. Note that where
joachim99@66 1266 <command>sed</command> needed "\(" and "\)" <command>perl</command>
joachim99@66 1267 requires the simpler "(" and ")" without preceding '\'. Example:
joachim99@66 1268 <screen>
joachim99@66 1269 <command>sed</command> 's/\(.*\)/\U\1/'
joachim99@66 1270 <command>perl</command> -p -e 's/(.*)/\U\1/'
joachim99@66 1271 </screen>
joachim99@66 1272 </para>
joachim99@66 1273 </sect3>
joachim99@66 1274 </sect2>
joachim99@66 1275
joachim99@66 1276 <sect2><title>Order Of Preprocessor Execution</title>
joachim99@66 1277 <para>
joachim99@66 1278 The data is piped through all internal and external preprocessors in the
joachim99@66 1279 following order:
joachim99@66 1280 </para>
joachim99@66 1281 <itemizedlist>
joachim99@66 1282 <listitem><para>Normal preprocessor,</para></listitem>
joachim99@66 1283 <listitem><para>Line-Matching-Preprocessor,</para></listitem>
joachim99@66 1284 <listitem><para>Ignore case (conversion to uppercase),</para></listitem>
joachim99@66 1285 <listitem><para>Detection of C/C++ comments,</para></listitem>
joachim99@66 1286 <listitem><para>Ignore numbers,</para></listitem>
joachim99@66 1287 <listitem><para>Ignore white space</para></listitem>
joachim99@66 1288 </itemizedlist>
joachim99@66 1289 <para>
joachim99@66 1290 The data after the normal preprocessor will be preserved for display and merging. The
joachim99@66 1291 other operations only modify the data that the line-matching-diff-algorithm sees.
joachim99@66 1292 </para><para>
joachim99@66 1293 In the rare cases where you use a normal preprocessor note that
joachim99@66 1294 the line-matching-preprocessor sees the output of the normal preprocessor as input.
joachim99@66 1295 </para>
joachim99@66 1296 </sect2>
joachim99@66 1297
joachim99@66 1298 <sect2><title>Warning</title>
joachim99@66 1299 <para>
joachim99@66 1300 The preprocessor-commands are often very useful, but as with any option that modifies
joachim99@69 1301 your texts or hides away certain differences automatically, you might accidentally overlook
joachim99@66 1302 certain differences and in the worst case destroy important data.
joachim99@66 1303 </para><para>
joachim99@73 1304 For this reason during a merge if a normal preprocessor-command is being used &kdiff3;
joachim99@66 1305 will tell you so and ask you if it should be disabled or not.
joachim99@66 1306 But it won't warn you if a Line-Matching-Preprocessor-command is active. The merge will not complete until
joachim99@66 1307 all conflicts are solved. If you disabled "Show White Space" then the differences that
joachim99@66 1308 were removed with the Line-Matching-Preprocessor-command will also be invisible. If the
joachim99@66 1309 Save-button remains disabled during a merge (because of remaining conflicts), make sure to enable
joachim99@66 1310 "Show White Space". If you don't wan't to merge these less important differences manually
joachim99@73 1311 you can select "Choose [A|B|C] For All Unsolved White space Conflicts" in the Merge-menu.
joachim99@66 1312 </para>
joachim99@66 1313 </sect2>
joachim99@66 1314 </sect1>
joachim99@11 1315 </chapter>
joachim99@11 1316
joachim99@11 1317
joachim99@73 1318 <chapter id="dirmerge"><title>Directory Comparison and Merge with &kdiff3;</title>
joachim99@69 1319 <sect1 id="dirmergeintro"><title>Introduction into Directory Comparison and Merge</title>
joachim99@11 1320 <para>
joachim99@11 1321 Often programmers must modify many files in a directory to achieve their
joachim99@73 1322 purpose. For this &kdiff3; also lets you compare and merge complete directories
joachim99@11 1323 recursively!
joachim99@11 1324 </para><para>
joachim99@11 1325 Even though comparing and merging directories seems to be quite obvious,
joachim99@11 1326 there are several details that you should know about. Most important is of
joachim99@11 1327 course the fact that now many files might be affected by each operation.
joachim99@11 1328 If you don't have backups of your original data, then it can be very hard
joachim99@11 1329 or even impossible to return to the original state. So before starting a merge,
joachim99@11 1330 make sure that your data is safe, and going back is possible. If you make
joachim99@11 1331 an archive or use some version control system is your decision, but even
joachim99@11 1332 experienced programmers and integrators need the old sources now and then.
joachim99@73 1333 And note that even though I (the author of &kdiff3;) try to do my best, I can't
joachim99@11 1334 guarantee that there are no bugs. According to the GNU-GPL there is NO WARRANTY
joachim99@11 1335 whatsoever for this program. So be humble and always keep in mind:
joachim99@11 1336 </para>
joachim99@11 1337 <blockquote><para>
joachim99@11 1338 <emphasis>To err is human, but to really mess things up you need a computer.</emphasis>
joachim99@11 1339 </para></blockquote>
joachim99@11 1340 <para>
joachim99@73 1341 So this is what this program can do for you: &kdiff3; ...
joachim99@11 1342 </para>
joachim99@11 1343 <itemizedlist>
joachim99@11 1344 <listitem><para>... reads and compares two or three directories recursively,</para></listitem>
joachim99@11 1345 <listitem><para>... takes special care of symbolic links,</para></listitem>
joachim99@11 1346 <listitem><para>... lets you browse files on mouse double click,</para></listitem>
joachim99@11 1347 <listitem><para>... for each item proposes a merge operation, which you can change
joachim99@11 1348 before starting the directory merge,</para></listitem>
joachim99@11 1349 <listitem><para>... lets you simulate the merge and lists the actions that would
joachim99@11 1350 take place, without actually doing them,</para></listitem>
joachim99@11 1351 <listitem><para>... lets you really do the merge, and lets you interact whenever
joachim99@11 1352 manual interaction is needed,</para></listitem>
joachim99@51 1353 <listitem><para>... lets you run the selected operation for all items (key F7) or the selected item (key F6),</para></listitem>
joachim99@51 1354 <listitem><para>... lets you continue the merge after manual interaction with key F7,</para></listitem>
joachim99@11 1355 <listitem><para>... optionally creates backups, with the ".orig" extension,</para></listitem>
joachim99@11 1356 <listitem><para>...</para></listitem>
joachim99@11 1357 </itemizedlist>
joachim99@11 1358 </sect1>
joachim99@11 1359
joachim99@11 1360 <sect1 id="startingdirmerge"><title>Starting Directory Comparison Or Merge</title>
joachim99@11 1361 <para>
joachim99@11 1362 This is very similar to the single file merge and comparison. You just
joachim99@11 1363 have to specify directories on the command line or in the file-open
joachim99@11 1364 dialog.
joachim99@11 1365 </para>
joachim99@11 1366 <sect2><title>Compare/Merge two directories: </title>
joachim99@11 1367 <screen>
joachim99@11 1368 <command>kdiff3</command> <replaceable>dir1 dir2</replaceable>
joachim99@11 1369 <command>kdiff3</command> <replaceable>dir1 dir2</replaceable> -o <replaceable>destdir</replaceable>
joachim99@11 1370 </screen>
joachim99@11 1371 <para>
joachim99@73 1372 If no destination directory is specified, then &kdiff3; will use <replaceable>dir2</replaceable>.
joachim99@11 1373 </para>
joachim99@11 1374 </sect2>
joachim99@11 1375
joachim99@11 1376 <sect2><title>Compare/Merge three directories: </title>
joachim99@11 1377 <screen>
joachim99@11 1378 <command>kdiff3</command> <replaceable>dir1 dir2 dir3</replaceable>
joachim99@11 1379 <command>kdiff3</command> <replaceable>dir1 dir2 dir3</replaceable> -o <replaceable>destdir</replaceable>
joachim99@11 1380 </screen>
joachim99@11 1381 <para>
joachim99@11 1382 When three directories are merged then <replaceable>dir1</replaceable>
joachim99@11 1383 is used as the base for the merge.
joachim99@73 1384 If no destination directory is specified, then &kdiff3; will use <replaceable>dir3</replaceable>
joachim99@11 1385 as the destination directory for the merge.
joachim99@11 1386 </para>
joachim99@11 1387
joachim99@11 1388 <para>
joachim99@11 1389 Note that only the comparison starts automatically, not the merge. For this you first must
joachim99@51 1390 select a menu entry or the key F7. (More details later.)
joachim99@11 1391 </para>
joachim99@11 1392 </sect2>
joachim99@11 1393 </sect1>
joachim99@11 1394
joachim99@69 1395 <sect1 id="dirmergevisible"><title>Directory Merge Visible Information</title>
joachim99@11 1396 <para>
joachim99@11 1397 While reading the directories a message-box appears that informs you of
joachim99@11 1398 the progress. If you abort the directory scan, then only files that have
joachim99@11 1399 been compared until then will be listed.
joachim99@11 1400 </para><para>
joachim99@73 1401 When the directory scan is complete then &kdiff3; will show a listbox with
joachim99@11 1402 the results left, ...
joachim99@11 1403 </para>
joachim99@11 1404 <screenshot><mediaobject>
joachim99@11 1405 <imageobject><imagedata fileref="dirbrowser.png" format="PNG"/></imageobject> <!--alt="Image of the directory browser."-->
joachim99@11 1406 </mediaobject></screenshot>
joachim99@11 1407 <para>
joachim99@11 1408 ... and details about the currently selected item on the right:
joachim99@11 1409 </para>
joachim99@11 1410 <screenshot><mediaobject>
joachim99@11 1411 <imageobject><imagedata fileref="iteminfo.png" format="PNG"/></imageobject>
joachim99@11 1412 <!--alt="Image with information about the selected item."-->
joachim99@11 1413 </mediaobject></screenshot>
joachim99@11 1414
joachim99@11 1415 <sect2 id="name"><title>The Name Column</title>
joachim99@11 1416 <para>
joachim99@11 1417 Each file and directory that was found during the scan is shown here in
joachim99@11 1418 a tree. You can select an item by clicking it with the mouse once.
joachim99@11 1419 </para><para>
joachim99@11 1420 The directories are collapsed by default. You can expand and collapse
joachim99@11 1421 them by clicking on the "+"/"-" or by double-clicking the item or
joachim99@11 1422 by using the left/right-arrow-keys. The "Directory"-menu also contains two
joachim99@11 1423 actions "Fold all subdirs" and "Unfold all subdirs" with which you can
joachim99@11 1424 collapse or expand all directories at once.
joachim99@11 1425 </para><para>
joachim99@11 1426 If you double-click a file item then the file comparison starts and the
joachim99@11 1427 file-diff-window will appear.
joachim99@11 1428 </para>
joachim99@11 1429 <para>
joachim99@11 1430 The image in the name column reflects the file type in the first
joachim99@11 1431 directory ("A"). It can be one of these:
joachim99@11 1432 </para>
joachim99@11 1433 <itemizedlist>
joachim99@11 1434 <listitem><para>Normal file</para></listitem>
joachim99@11 1435 <listitem><para>Normal directory (directory-image)</para></listitem>
joachim99@11 1436 <listitem><para>Link to a file (file-image with a link arrow)</para></listitem>
joachim99@11 1437 <listitem><para>Link to a directory (directory-image with a link arrow)</para></listitem>
joachim99@11 1438 </itemizedlist>
joachim99@11 1439 <para>
joachim99@11 1440 If the file type is different in the other directories, then this is visible
joachim99@11 1441 in the columns A/B/C and in the window that shows the details about the selected
joachim99@11 1442 item. Note that for such a case no merge operation can be selected automatically.
joachim99@11 1443 When starting the merge, then the user will be informed of problems of that
joachim99@11 1444 kind.
joachim99@11 1445 </para>
joachim99@11 1446 </sect2>
joachim99@11 1447
joachim99@11 1448 <sect2 id="coloring"><title>The Columns A/B/C and the Coloring Scheme</title>
joachim99@11 1449 <para>
joachim99@11 1450 As can be seen in the image above the colors red, green, yellow and black
joachim99@11 1451 are used in the columns A/B/C.
joachim99@11 1452 </para>
joachim99@11 1453 <itemizedlist>
joachim99@11 1454 <listitem><para>Black: This item doesn't exist in this directory.</para></listitem>
joachim99@11 1455 <listitem><para>Green: Newest item.</para></listitem>
joachim99@11 1456 <listitem><para>Yellow: Older than green, newer than red.</para></listitem>
joachim99@11 1457 <listitem><para>Red: Oldest item.</para></listitem>
joachim99@11 1458 </itemizedlist>
joachim99@11 1459 <para>
joachim99@11 1460 But for items that were identical in the comparison their color also is
joachim99@11 1461 identical even if the age is not.
joachim99@11 1462 </para><para>
joachim99@11 1463 Directories are considered equal if all items they contain are identical.
joachim99@11 1464 Then they also will have the same color. But the age of a directory is not
joachim99@11 1465 considered for its color.
joachim99@11 1466 </para><para>
joachim99@11 1467 The idea for this coloring scheme I came upon in
joachim99@11 1468 <ulink url="http://samba.org/cgi-bin/cvsweb/dirdiff">dirdiff</ulink>. The colors
joachim99@11 1469 resemble the colors of a leaf that is green when new, turns yellow later and red
joachim99@11 1470 when old.
joachim99@11 1471 </para>
joachim99@11 1472
joachim99@11 1473 </sect2><sect2 id="operation"><title>The Operation Column</title>
joachim99@11 1474 <para>
joachim99@73 1475 After comparing the directories &kdiff3; also evaluates a proposal for a
joachim99@11 1476 merge operation. This is shown in the "Operation" column. You can modify
joachim99@11 1477 the operation by clicking on the operation you want to change. A small menu
joachim99@51 1478 will popup and allows you to select an operation for that item. (You can also
joachim99@51 1479 select the most needed operations via keyboard.
joachim99@51 1480 Ctrl+1/2/3/4/Del will select A/B/C/Merge/Delete respectively if available.)
joachim99@51 1481 This operation will be executed during the merge. It depends on the item and
joachim99@51 1482 on the merge-mode you are in, what operations are available. The merge-mode is one of
joachim99@11 1483 </para>
joachim99@11 1484 <itemizedlist>
joachim99@51 1485 <listitem><para>Three directory-merge ("A" is treated as older base of both).</para></listitem>
joachim99@11 1486 <listitem><para>Two directory-merge.</para></listitem>
joachim99@11 1487 <listitem><para>Two directory-sync-mode (activate via option "Synchronize Directories").</para></listitem>
joachim99@11 1488 </itemizedlist>
joachim99@11 1489 <para>
joachim99@11 1490 In three directory merge the operation proposal will be: If for an item ...
joachim99@11 1491 </para>
joachim99@11 1492 <itemizedlist>
joachim99@11 1493 <listitem><para>... all three directories are equal: Copy from C</para></listitem>
joachim99@11 1494 <listitem><para>... A and C are equal but B is not: Copy from B (or if B does not
joachim99@11 1495 exist, delete the destination if exists)</para></listitem>
joachim99@11 1496 <listitem><para>... A and B are equal but C is not: Copy from C (or if C does not
joachim99@11 1497 exist, delete the destination if exists)</para></listitem>
joachim99@11 1498 <listitem><para>... B and C are equal but A is not: Copy from C (or if C does not
joachim99@11 1499 exist, delete the destination if exists)</para></listitem>
joachim99@11 1500 <listitem><para>... only A exists: Delete the destination (if exists)</para></listitem>
joachim99@11 1501 <listitem><para>... only B exists: Copy from B</para></listitem>
joachim99@11 1502 <listitem><para>... only C exists: Copy from C</para></listitem>
joachim99@11 1503 <listitem><para>... A, B and C are not equal: Merge</para></listitem>
joachim99@11 1504 <listitem><para>... A, B and C don't have the same file type (e.g. A is a directory,
joachim99@11 1505 B is a file): "Error: Conflicting File Types". While such items exist the
joachim99@11 1506 directory merge cannot start.</para></listitem>
joachim99@11 1507 </itemizedlist>
joachim99@11 1508 <para>
joachim99@11 1509 In two directory merge the operation proposal will be: If for an item ...
joachim99@11 1510 </para>
joachim99@11 1511 <itemizedlist>
joachim99@11 1512 <listitem><para>... both directories are equal: Copy from B</para></listitem>
joachim99@11 1513 <listitem><para>... A exists, but not B: Copy from A</para></listitem>
joachim99@11 1514 <listitem><para>... B exists, but not A: Copy from B</para></listitem>
joachim99@11 1515 <listitem><para>... A and B exist but are not equal: Merge</para></listitem>
joachim99@11 1516 <listitem><para>... A and B don't have the same file type (e.g. A is a directory,
joachim99@11 1517 B is a file): "Error: Conflicting File Types". While such items exist the
joachim99@11 1518 directory merge cannot start.</para></listitem>
joachim99@11 1519 </itemizedlist>
joachim99@11 1520 <para>
joachim99@11 1521 Sync-mode is active if only two directories and no explicit destination
joachim99@73 1522 were specified and if the option "Synchronize directories" is active. &kdiff3;
joachim99@11 1523 then selects a default operation so that both directories are the same afterwards.
joachim99@11 1524 If for an item ...
joachim99@11 1525 </para>
joachim99@11 1526 <itemizedlist>
joachim99@11 1527 <listitem><para>... both directories are equal: Nothing will be done.</para></listitem>
joachim99@11 1528 <listitem><para>... A exists, but not B: Copy A to B</para></listitem>
joachim99@11 1529 <listitem><para>... B exists, but not A: Copy B to A</para></listitem>
joachim99@11 1530 <listitem><para>... A and B exist, but are not equal: Merge and store the result
joachim99@11 1531 in both directories. (For the user the visible save-filename is B,
joachim99@73 1532 but then &kdiff3; copies B also to A.)</para></listitem>
joachim99@11 1533 <listitem><para>... A and B don't have the same file type (e.g. A is a directory,
joachim99@11 1534 B is a file): "Error: Conflicting File Types". While such items exist the
joachim99@11 1535 directory merge cannot start.</para></listitem>
joachim99@11 1536 </itemizedlist>
joachim99@11 1537 <para>
joachim99@11 1538 When two directories are merged and the option "Copy newer instead of merging" is selected,
joachim99@73 1539 then &kdiff3; looks at the dates and proposes to choose the newer file. If the files are not
joachim99@11 1540 equal but have equal dates, then the operation will contain
joachim99@11 1541 "Error: Dates are equal but files are not." While such items exist the
joachim99@11 1542 directory merge cannot start.
joachim99@11 1543 </para>
joachim99@11 1544 </sect2>
joachim99@11 1545
joachim99@11 1546 <sect2 id="status"><title>The Status Column</title>
joachim99@11 1547 <para>
joachim99@11 1548 During the merge one file after the other will be processed. The status
joachim99@11 1549 column will show "Done" for items where the merge operation has succeeded,
joachim99@11 1550 and other texts if something unexpected happened. When a merge is complete,
joachim99@11 1551 then you should make a last check to see if the status for all items is
joachim99@11 1552 agreeable.
joachim99@11 1553 </para>
joachim99@11 1554 </sect2>
joachim99@66 1555
joachim99@66 1556 <sect2 id="statisticscolulmns"><title>Statistics Columns</title>
joachim99@66 1557 <para>
joachim99@66 1558 When the file comparison mode "Full Analysis" is enabled in the options, then
joachim99@73 1559 &kdiff3; will show extra columns containing the numbers of unsolved, solved, nonwhite and whitespace
joachim99@66 1560 conflicts. (The solved-column will only show when comparing or merging three directories.)
joachim99@66 1561 </para>
joachim99@66 1562 </sect2>
joachim99@66 1563
joachim99@69 1564 <sect2 id="selectingvisiblefiles"><title>Selecting Listed Files</title>
joachim99@69 1565 <para>
joachim99@69 1566 Several options influence which files are listed here. Some are accessible in the
joachim99@69 1567 <link linkend="dirmergeoptions">settings dialog</link>. The Directory-menu contains the entries:
joachim99@69 1568 </para><para><itemizedlist>
joachim99@69 1569 <listitem><para>"Show Identical Files": Files that have been detected equal in all input directories.</para></listitem>
joachim99@69 1570 <listitem><para>"Show Different Files": Files that exist in two or more directories but are not equal.</para></listitem>
joachim99@69 1571 <listitem><para>"Show Files only in A": Files that exist only in A, but not in B or C.</para></listitem>
joachim99@69 1572 <listitem><para>"Show Files only in B": Files that exist only in B, but not in A or B.</para></listitem>
joachim99@69 1573 <listitem><para>"Show Files only in C": Files that exist only in C, but not in A or B.</para></listitem>
joachim99@69 1574 </itemizedlist></para>
joachim99@69 1575 <para>
joachim99@69 1576 Activate only the "Show"-options for the items you want listed. If for example you only want to list all items that
joachim99@69 1577 exist either in A or in B but not in both, you'll have to activate "Show Files only in A" and "Show Files only in B"
joachim99@69 1578 and deactivate all others ("Show Identical Files", "Show Different Files", "Show Files only in C").
joachim99@69 1579 The list will be updated immediately to reflect the change.
joachim99@69 1580 </para><para>
joachim99@69 1581 These options also apply for directories with one exception: Disabling "Show Different Files" will not hide
joachim99@69 1582 any complete directories. This will work only for files within.
joachim99@69 1583 </para><para>
joachim99@73 1584 Note that of these only the "Show Identical Files"-option is persistant. The others are enabled when starting &kdiff3;.
joachim99@69 1585 </para>
joachim99@69 1586 </sect2>
joachim99@69 1587
joachim99@11 1588 </sect1>
joachim99@11 1589
joachim99@11 1590
joachim99@69 1591 <sect1 id="dothemerge"><title>Doing A Directory Merge</title>
joachim99@11 1592 <para>
joachim99@51 1593 You can either merge the currently selected item (file or directory), or all items.
joachim99@11 1594 When you have made all your operation choices (in all subdirectories too)
joachim99@11 1595 then you can start the merge.
joachim99@11 1596 </para><para>
joachim99@11 1597 Be aware that if you didn't specify a destination directory explicitely,
joachim99@11 1598 then the destination will be "C" in three directory mode, "B" in two directory
joachim99@11 1599 merge mode, and in sync-mode it will be "A" or/and "B".
joachim99@11 1600 </para><para>
joachim99@11 1601 If you have specified a destination directory also check that all items
joachim99@11 1602 that should be in the output, are in the tree. There are some options that
joachim99@11 1603 cause certain items to be omitted from the directory comparison and merge.
joachim99@11 1604 Check these options to avoid unpleasant surprises:
joachim99@11 1605 </para>
joachim99@11 1606 <itemizedlist>
joachim99@11 1607 <listitem><para>"Recursive Directories": If this is off, then items in subdirectories
joachim99@11 1608 will not be found.</para></listitem>
joachim99@11 1609 <listitem><para>"Pattern"/"Anti-Pattern": Include/exclude items that match</para></listitem>
joachim99@11 1610 <listitem><para>"Exclude Hidden Files"</para></listitem>
joachim99@69 1611 <listitem><para><link linkend="selectingvisiblefiles">"Show"-options</link> (Show Identical/Different Files, Files only in A/B/C)</para></listitem>
joachim99@11 1612 </itemizedlist>
joachim99@11 1613 <para>
joachim99@69 1614 If you change the settings in order to list more files, you must do a rescan via menu "Directory"->"Rescan" yourself.
joachim99@73 1615 (The reason for this is that for faster comparison-speed &kdiff3; omits the comparison for files suppressed by these criteria.)
joachim99@69 1616 If you changed your file and dir patterns to exclude files, then the file-list will immediately be updated on closing
joachim99@69 1617 the options-dialog.
joachim99@69 1618 </para><para>
joachim99@69 1619 Note that when you write to a completely new directory then you usually also want to copy the identical files.
joachim99@69 1620 In that case enable the "Show Identical Files"-option. If your destination-directory is one of the inputs,
joachim99@69 1621 then this isn't necessary because the file is already there.
joachim99@11 1622 </para><para>
joachim99@11 1623 If you are satisfied so far, the rest is easy.
joachim99@11 1624 </para><para>
joachim99@51 1625 To merge all items: Select "Start/Continue directory merge" in the "Directory"-menu
joachim99@69 1626 or press F7 (which is the default shortcut).
joachim99@51 1627 To merge only the current item: Select "Run Operation For Current Item"
joachim99@51 1628 or press F6.
joachim99@11 1629 </para><para>
joachim99@69 1630 If due to conflicting filetypes still some items with invalid operations
joachim99@11 1631 exist, then a messagebox will appear and these items will be pointed out,
joachim99@11 1632 so you can select a valid operation for the item.
joachim99@11 1633 </para><para>
joachim99@51 1634 If you merge all items a dialog will appear giving you the options "Do it", "Simulate
joachim99@11 1635 it" and "Cancel".
joachim99@11 1636 </para>
joachim99@11 1637 <itemizedlist>
joachim99@11 1638 <listitem><para>Select "Simulate it" if you want to see what would be done without
joachim99@11 1639 actually doing it. A verbose list of all operations will be shown.</para></listitem>
joachim99@11 1640 <listitem><para>Otherwise select "Do it" to really start merging.</para></listitem>
joachim99@11 1641 </itemizedlist>
joachim99@11 1642 <para>
joachim99@73 1643 Then &kdiff3; will run the specified operation for all items. If manual
joachim99@11 1644 interaction is required (single file merge), then a merge window will open
joachim99@11 1645 (<link linkend="dirmergebigscreenshot">see the big screenshot</link>).
joachim99@11 1646 </para><para>
joachim99@69 1647 When you have finished with manually merging a file, again select "Start/Continue directory
joachim99@69 1648 merge" or the key F7. If you haven't saved it yet, a dialog will ask you to
joachim99@73 1649 do so. Then &kdiff3; will continue with the next item.
joachim99@11 1650 </para><para>
joachim99@73 1651 When &kdiff3; encounters an error, it will tell you so and will show the
joachim99@51 1652 verbose-status-information. At the bottom of this list, there will be some
joachim99@51 1653 error messages which should help you to understand the cause of the problem.
joachim99@73 1654 When you continue merging (F7 key) &kdiff3; will give you the choice to retry
joachim99@51 1655 or skip the item that caused the problem. This means that before continuing
joachim99@51 1656 you can choose another operation or solve the problem by other means.
joachim99@11 1657 </para><para>
joachim99@73 1658 When the merge is complete, then &kdiff3; will inform you via a message
joachim99@11 1659 box.
joachim99@51 1660 </para><para>
joachim99@69 1661 If some items were merged individually before running the directorymerge then
joachim99@73 1662 &kdiff3; remembers this (while this
joachim99@51 1663 merge-session goes on), and doesn't merge them again when later the merge for
joachim99@51 1664 all items is run. Even when the merge was skipped or nothing was saved these
joachim99@69 1665 items count as completed. Only when you change the merge operation the
joachim99@69 1666 "Done"-status of the item will be removed and it can be merged again.
joachim99@11 1667 </para>
joachim99@11 1668 </sect1>
joachim99@11 1669
joachim99@11 1670 <sect1 id="dirmergeoptions"><title>Options for Comparing and Merging Directories</title>
joachim99@11 1671 <para>
joachim99@73 1672 The &kdiff3;-preferences (menu "Settings"-&gt;"Configure &kdiff3;") has
joachim99@11 1673 a section called "Directory Merge" with these options:
joachim99@11 1674 </para>
joachim99@11 1675
joachim99@11 1676 <variablelist>
joachim99@11 1677 <varlistentry><term><emphasis>Recursive Directories:</emphasis></term><listitem><para> Select whether to search directories
joachim99@11 1678 recursively.</para></listitem></varlistentry>
joachim99@11 1679 <varlistentry><term><emphasis>File Pattern(s):</emphasis></term><listitem><para> Only files that match any pattern here will
joachim99@69 1680 be put in the tree. More than one pattern may be specified here by using
joachim99@11 1681 the semicolon ";" as separator. Valid wildcards: '*' and '?'. (e.g. "*.cpp;*.h").
joachim99@69 1682 Default is "*". This pattern is not used on directories.</para></listitem></varlistentry>
joachim99@69 1683 <varlistentry><term><emphasis>File Anti-Pattern(s):</emphasis></term><listitem><para> Files that match this pattern
joachim99@11 1684 will be excluded from the tree. More than one pattern may be specified here
joachim99@11 1685 via using the semicolon ";" as separator. Valid wildcards: '*' and '?'. Default
joachim99@69 1686 is "*.orig;*.o;*.obj".</para></listitem></varlistentry>
joachim99@69 1687 <varlistentry><term><emphasis>Directory Anti-Pattern(s):</emphasis></term><listitem><para> Directories that match this pattern
joachim99@69 1688 will be excluded from the tree. More than one pattern may be specified here
joachim99@69 1689 via using the semicolon ";" as separator. Valid wildcards: '*' and '?'. Default
joachim99@69 1690 is "CVS;deps;.svn".</para></listitem></varlistentry>
joachim99@11 1691 <varlistentry><term><emphasis>Use CVS-Ignore:</emphasis></term><listitem><para>
joachim99@11 1692 Ignore files and directories that would also be ignored by CVS.
joachim99@11 1693 Many automatically generated files are ignored by CVS.
joachim99@11 1694 The big advantage is that this can be directory specific via a local ".cvsignore"-file.
joachim99@11 1695 (See <ulink url="info:/cvs/cvsignore">info:/cvs/cvsignore</ulink>.)</para></listitem></varlistentry>
joachim99@73 1696 <varlistentry><term><emphasis>Find Hidden Files and Directories:</emphasis></term><listitem><para> On some file systems files
joachim99@11 1697 have an "Hidden"-attribute. On other systems a filename starting with a dot
joachim99@11 1698 "." causes it to be hidden. This option allows you to decide whether to
joachim99@11 1699 include these files in the tree or not. Default is on.</para></listitem></varlistentry>
joachim99@11 1700 <varlistentry><term><emphasis>Follow File Links:</emphasis></term><listitem><para> For links to files: When disabled, then
joachim99@11 1701 the symbolic links are compared. When enabled, then the files behind the
joachim99@11 1702 links are compared. Default is off.</para></listitem></varlistentry>
joachim99@11 1703 <varlistentry><term><emphasis>Follow Directory Links:</emphasis></term><listitem><para> For links to directories: When disabled,
joachim99@11 1704 then the symbolic links will be compared. When enabled then the link will
joachim99@11 1705 be treated like a directory and it will be scanned recursively. (Note that
joachim99@11 1706 the program doesn't check if the link is "recursive". So for example a directory
joachim99@11 1707 that contains a link to the directory would cause an infinite loop, and after
joachim99@11 1708 some time when the stack overflows or all memory is used up, crash the program.)
joachim99@11 1709 Default is off.</para></listitem></varlistentry>
joachim99@69 1710 <varlistentry><term><emphasis>Case Sensitive Filename Comparison:</emphasis></term><listitem><para>
joachim99@69 1711 Default is false on Windows, true for other operating systems.</para></listitem></varlistentry>
joachim99@66 1712 <varlistentry><term><emphasis>File Comparison Mode:</emphasis></term><listitem><para>
joachim99@66 1713 <variablelist>
joachim99@66 1714 <varlistentry><term><emphasis>Binary Comparison:</emphasis></term><listitem><para>
joachim99@66 1715 This is the default file comparison mode.
joachim99@66 1716 </para></listitem></varlistentry>
joachim99@66 1717 <varlistentry><term><emphasis>Full Analysis:</emphasis></term><listitem><para>
joachim99@66 1718 Do a full analysis of each file and show the statistics information columns.
joachim99@66 1719 (Number of solved, unsolved, nonwhite and white conflicts.)
joachim99@66 1720 The full analysis is slower than a simple binary analysis, and much
joachim99@66 1721 slower when used on files that don't contain text.
joachim99@66 1722 (Specify the appropriate file-antipatterns.)
joachim99@66 1723 </para></listitem></varlistentry>
joachim99@11 1724 <varlistentry><term><emphasis>Trust the modification date:</emphasis></term><listitem><para> If you compare big directories
joachim99@11 1725 over a slow network, it might be faster to compare the modification dates
joachim99@11 1726 and file length alone. But this speed improvement comes with the price of
joachim99@11 1727 a little uncertainty. Use this option with care. Default is off.</para></listitem></varlistentry>
joachim99@51 1728 <varlistentry><term><emphasis>Trust the size:</emphasis></term><listitem><para>
joachim99@51 1729 Similar to trusting the modification date. No real comparison happens. Two
joachim99@51 1730 files are considered equal if their file-sizes are equal. This is useful
joachim99@51 1731 when the file-copy operation didn't preserve the modification date.
joachim99@51 1732 Use this option with care. Default is off.</para></listitem></varlistentry>
joachim99@66 1733 </variablelist></para></listitem></varlistentry>
joachim99@66 1734
joachim99@11 1735 <varlistentry><term><emphasis>Synchronize Directories:</emphasis></term><listitem><para> Activates "Sync-Mode" when two directories
joachim99@11 1736 are compared and no explicit destination directory was specified. In this
joachim99@11 1737 mode the proposed operations will be chosen so that both source directories
joachim99@11 1738 are equal afterwards. Also the merge result will be written to both directories.
joachim99@11 1739 Default is off.</para></listitem></varlistentry>
joachim99@11 1740 <varlistentry><term><emphasis>Copy newer instead of merging:</emphasis></term><listitem><para> Instead of merging the proposed
joachim99@11 1741 operation will copy the newer source if changes happened. (Considered unsafe,
joachim99@69 1742 because it implies that you know, that the other file hasn't been edited
joachim99@11 1743 too. Check to make sure in every case.) Default is off.</para></listitem></varlistentry>
joachim99@11 1744 <varlistentry><term><emphasis>Backup files:</emphasis></term><listitem><para> If a file or complete directory is replaced
joachim99@11 1745 by another or is deleted then the original version will be renamed with an
joachim99@11 1746 ".orig" extension. If an old backup file with ".orig" extension already exists
joachim99@11 1747 then this will be deleted without backup. This also affects the normal merging
joachim99@11 1748 of single files, not only in directory-merge mode. Default is on.</para></listitem></varlistentry>
joachim99@11 1749 </variablelist>
joachim99@11 1750 </sect1>
joachim99@11 1751
joachim99@69 1752 <sect1 id="other"><title>Other Functions in Directory Merge Window</title>
joachim99@11 1753 <sect2><title>Split/Full Screen Mode</title>
joachim99@11 1754 <para>
joachim99@11 1755 Usually the directory merge list view remains visible while a single file
joachim99@11 1756 is compared or merged. With the mouse you can move the the splitter bar that
joachim99@11 1757 separates the file list from the text-diff windows. If you don't want this,
joachim99@11 1758 you can disable "Split Screen View" in the "Directory"-menu. Then you can
joachim99@11 1759 use "Toggle View" in the "Directory"-menu to switch between the file list
joachim99@11 1760 and the text-diff view that then occupy the full screen.
joachim99@11 1761 </para>
joachim99@11 1762 </sect2>
joachim99@11 1763 <sect2><title>Comparing or Merging a Single File</title>
joachim99@11 1764 <para>
joachim99@11 1765 Probably you will prefer a simple double mouse click on a file in order
joachim99@11 1766 to compare it. Nevertheless there also exists an entry in the "Directory"-menu.
joachim99@69 1767 You can also directly merge a single file by selecting it and
joachim99@69 1768 choosing "Merge current file" in the "Merge"-Menu. On saving the
joachim99@11 1769 result, the status will be set to done, and the file will not be merged again
joachim99@11 1770 if a directory merge is started.
joachim99@11 1771 </para><para>
joachim99@11 1772 But note that this status information will be lost when you rerun a directory
joachim99@11 1773 scan: "Directory"-menu: "Rescan"
joachim99@11 1774 </para>
joachim99@11 1775 </sect2>
joachim99@69 1776 <sect2><title>Comparing or Merging Files with Different Names</title>
joachim99@69 1777 <para>
joachim99@69 1778 Sometimes you need to compare or merge files with different names (e.g. the current
joachim99@69 1779 file and the backup in the same folder).
joachim99@69 1780 </para><para>
joachim99@69 1781 Select the exact file by clicking onto the icon in the column A, B or C. The first
joachim99@69 1782 file selected thus will be marked with an "A", the second and third with "B" and "C"
joachim99@69 1783 regardless on what column they are in. Only up to three files can be chosen like this.
joachim99@69 1784 </para><para>
joachim99@69 1785 Proceed by choosing "Compare Explicitely Selected Files" or "Merge Explicitely
joachim99@69 1786 Selected Files" from the "Directory"-menu. For your convenience these menu entries
joachim99@69 1787 also appear as context menu when you right-click the last selected file.
joachim99@69 1788 </para><para>
joachim99@69 1789 The comparison or merge of a file will happen in the same window.
joachim99@69 1790 If this method is used for directories a new window will be opened.
joachim99@69 1791 </para></sect2>
joachim99@11 1792 </sect1>
joachim99@11 1793 </chapter>
joachim99@11 1794
joachim99@11 1795 <chapter id="misc">
joachim99@11 1796 <title>Miscellaneous Topics</title>
joachim99@11 1797 <sect1 id="networktransparency">
joachim99@11 1798 <title>Networktransparency via KIO</title>
joachim99@11 1799 <sect2><title>KIO-Slaves</title>
joachim99@11 1800 <para>
joachim99@73 1801 KDE supports networktransparency via KIO-slaves. &kdiff3; uses this
joachim99@11 1802 for reading input files and for scanning directories.
joachim99@11 1803 This means that you can specify files and directories on local and
joachim99@69 1804 remote resources via URLs.
joachim99@11 1805 </para><para>
joachim99@11 1806 Example:
joachim99@11 1807 </para><para>
joachim99@11 1808 <screen>
joachim99@11 1809 <command>kdiff3</command> test.cpp ftp://ftp.faraway.org/test.cpp
joachim99@11 1810 <command>kdiff3</command> tar:/home/hacker/archive.tar.gz/dir ./dir
joachim99@11 1811 </screen>
joachim99@11 1812 </para>
joachim99@11 1813 <para>The first line compares a local file with a file on an FTP-server. The second line
joachim99@11 1814 compares a directory within an compressed archive with a local directory.
joachim99@11 1815 </para><para>
joachim99@11 1816 Other KIO-slaves that are interesting are:
joachim99@11 1817 </para>
joachim99@11 1818 <itemizedlist>
joachim99@11 1819 <listitem><para>Files from the WWW (http:),</para></listitem>
joachim99@11 1820 <listitem><para>Files from the FTP (ftp:),</para></listitem>
joachim99@11 1821 <listitem><para>Encrypted file transfer (fish:, sftp:),</para></listitem>
joachim99@11 1822 <listitem><para>Windows-ressources (smb:),</para></listitem>
joachim99@11 1823 <listitem><para>Local files (file:),</para></listitem>
joachim99@11 1824 </itemizedlist>
joachim99@11 1825 <para>
joachim99@11 1826 Other things that are possible, but probably less useful are:
joachim99@11 1827 </para>
joachim99@11 1828 <itemizedlist>
joachim99@11 1829 <listitem><para>Man-pages (man:),</para></listitem>
joachim99@11 1830 <listitem><para>Info-pages (info:),</para></listitem>
joachim99@11 1831 </itemizedlist>
joachim99@11 1832 </sect2>
joachim99@11 1833
joachim99@11 1834 <sect2><title>How To Write URLs</title>
joachim99@11 1835 <para>
joachim99@11 1836 An URL has a different syntax compared with paths for local files and directories.
joachim99@11 1837 Some things should be considered:
joachim99@11 1838 </para>
joachim99@11 1839 <itemizedlist>
joachim99@11 1840 <listitem><para>
joachim99@51 1841 A path can be relative and can contain "." or "..". This is not possible for URLs
joachim99@51 1842 which are always absolute.
joachim99@11 1843 </para></listitem><listitem><para>
joachim99@11 1844 Special characters must be written with "escaping". ("#"->"%23", space->"%20", etc.)
joachim99@11 1845 E.g. A file with the name "/#foo#" would have the URL "file:/%23foo%23".
joachim99@11 1846 </para></listitem><listitem><para>
joachim99@11 1847 When URLs don't work as expected, try to open them in Konqueror first.
joachim99@11 1848 </para></listitem>
joachim99@11 1849 </itemizedlist>
joachim99@11 1850
joachim99@11 1851 </sect2>
joachim99@11 1852
joachim99@11 1853 <sect2><title>Capabilities of KIO-Slaves</title>
joachim99@11 1854 <para>
joachim99@11 1855 Networktransparency has one drawback: Not all ressources have the same cababilities.
joachim99@11 1856 </para><para>
joachim99@73 1857 Sometimes this is due to the file system of the server, sometimes due to the protocol.
joachim99@11 1858 Here is a short list of restrictions:
joachim99@11 1859 </para>
joachim99@11 1860 <itemizedlist>
joachim99@11 1861 <listitem><para>
joachim99@11 1862 Sometimes there is no support for links.
joachim99@11 1863 </para></listitem><listitem><para>
joachim99@51 1864 Or there is no way to distinguish if a link points to a file or a directory; always
joachim99@51 1865 assuming a file. (ftp:, sftp:).
joachim99@11 1866 </para></listitem><listitem><para>
joachim99@11 1867 Can't always determine the filesize.
joachim99@11 1868 </para></listitem><listitem><para>
joachim99@11 1869 Limited support for permissions.
joachim99@11 1870 </para></listitem><listitem><para>
joachim99@51 1871 No possibility to modify permissions or modification time, so permissions or time
joachim99@51 1872 of a copy will differ from the original. (See the option "Trust the size".)
joachim99@68 1873 (To modify permissions or modification time is only possible for local files.)
joachim99@11 1874 </para></listitem>
joachim99@11 1875 </itemizedlist>
joachim99@11 1876 </sect2>
joachim99@11 1877 </sect1>
joachim99@11 1878
joachim99@11 1879 <sect1 id="kpart">
joachim99@11 1880 <title>Using &kdiff3; as a KPart</title>
joachim99@11 1881 <para>
joachim99@11 1882 &kdiff3; is a KPart. Currently it implements the KParts::ReadOnlyPart-interface.
joachim99@11 1883 </para><para>
joachim99@11 1884 It's main use is as difference-viewer in KDevelop. KDevelop always starts the
joachim99@73 1885 internal difference viewer first. To invoke &kdiff3; press the right mouse button
joachim99@11 1886 on the difference viewer window and select "Show in KDiff3Part" from the contextmenu.
joachim99@11 1887 </para><para>
joachim99@73 1888 &kdiff3; normally requires two complete files as input. When used as part &kdiff3;
joachim99@73 1889 will assume that the inputfile is a patch-file in the unified format. &kdiff3;
joachim99@11 1890 then retrieves the original filenames from the patch-file. At least one of
joachim99@73 1891 the two files must be available. &kdiff3; will then invoke <command>patch</command> to
joachim99@11 1892 recreate the second file.
joachim99@11 1893 </para><para>
joachim99@11 1894 In Konqueror you can select a patch-file and select "Preview in"-"KDiff3Part" from
joachim99@11 1895 the contextmenu. Be aware that this won't work if none of the original files are
joachim99@11 1896 available, and it is not reliable if the original file(s) have changed since the
joachim99@11 1897 patch-file was generated.
joachim99@11 1898 </para><para>
joachim99@73 1899 When run as a part &kdiff3; only provides the a two-file-diff, a very small toolbar
joachim99@11 1900 and menu. Merging or directory-comparison are not supported then.
joachim99@11 1901 </para>
joachim99@11 1902 </sect1>
joachim99@11 1903 </chapter>
joachim99@11 1904
joachim99@11 1905 <chapter id="faq">
joachim99@11 1906 <title>Questions and Answers</title>
joachim99@11 1907
joachim99@11 1908 &reporting.bugs;
joachim99@11 1909 &updating.documentation;
joachim99@11 1910
joachim99@11 1911 <qandaset id="faqlist">
joachim99@11 1912
joachim99@11 1913 <qandaentry><question><para>
joachim99@73 1914 Why is it called "&kdiff3;"?
joachim99@11 1915 </para></question><answer><para>
joachim99@11 1916 Tools named "KDiff" and "KDiff2" (now called "Kompare") already exist. Also "KDiff3" should suggest
joachim99@11 1917 that it can merge like the "diff3"-tool in the Diff-Tool collection.
joachim99@11 1918 </para></answer></qandaentry>
joachim99@11 1919
joachim99@11 1920 <qandaentry><question><para>
joachim99@11 1921 Why did I release it under GPL?
joachim99@11 1922 </para></question><answer><para>
joachim99@11 1923 I'm using GPL programs for a very long time now and learned very much
joachim99@11 1924 by having a look at many of the sources. Hence this is my "Thank You"
joachim99@11 1925 to all programmers that also did so or will do the same.
joachim99@11 1926 </para></answer></qandaentry>
joachim99@11 1927
joachim99@11 1928 <qandaentry><question><para>
joachim99@11 1929 Some buttons and functions are missing. What's wrong?
joachim99@11 1930 </para></question><answer><para>
joachim99@11 1931 You compiled from source but you probably didn't specify the correct KDE-prefix
joachim99@11 1932 with configure. By default configure wants to install in /usr/local but then KDE can't
joachim99@11 1933 find the user-interface ressource file (i.e. kdiff3ui.rc). The README-file contains
joachim99@11 1934 more information about the correct prefix.
joachim99@11 1935 </para></answer></qandaentry>
joachim99@11 1936
joachim99@11 1937 <qandaentry><question><para>
joachim99@11 1938 Often lines that are similar but not identical appear next to each other
joachim99@11 1939 but sometimes not. Why?
joachim99@11 1940 </para></question><answer><para>
joachim99@11 1941 Lines where only the amount of white space characters is different
joachim99@11 1942 are treated as "equal" at first, while just one different non-white character
joachim99@11 1943 causes the lines to be "different". If similar lines appear next to each
joachim99@11 1944 other, this actually is coincidence but this fortunately is often the case.
joachim99@69 1945 See also <link linkend="manualdiffhelp">Manual Diff Help</link>.
joachim99@11 1946 </para></answer></qandaentry>
joachim99@11 1947
joachim99@11 1948 <qandaentry><question><para>
joachim99@11 1949 Why must all conflicts be solved before the merge result can be saved?
joachim99@11 1950 </para></question><answer><para>
joachim99@11 1951 For each equal or different section the editor in the merge result
joachim99@11 1952 window remembers where it begins or ends. This is needed so that conflicts
joachim99@11 1953 can be solved manually by simply selecting the source button (A, B or C).
joachim99@11 1954 This information is lost while saving as text and it is too much effort to
joachim99@11 1955 create a special file format that supports saving and restoring all necessary
joachim99@11 1956 information.
joachim99@11 1957 </para></answer></qandaentry>
joachim99@11 1958
joachim99@11 1959 <qandaentry><question><para>
joachim99@69 1960 How can I synchronise the diff and merge views, so that all views show the same text position?
joachim99@69 1961 </para></question><answer><para>
joachim99@69 1962 Click into the summary column left of the text. (<link linkend="synchronise_views">See also here.</link>)
joachim99@69 1963 </para></answer></qandaentry>
joachim99@69 1964
joachim99@69 1965 <qandaentry><question><para>
joachim99@11 1966 Why does the editor in the merge result window not have an "undo"-function?
joachim99@11 1967 </para></question><answer><para>
joachim99@11 1968 This was too much effort until now. You can always
joachim99@11 1969 restore a version from one source (A, B or C) by clicking the respective
joachim99@11 1970 button. For big editing the use of another editor is recommended anyway.
joachim99@11 1971 </para></answer></qandaentry>
joachim99@11 1972
joachim99@11 1973 <qandaentry><question><para>
joachim99@11 1974 When I removed some text, then suddenly "&lt;No src line&gt;" appeared
joachim99@73 1975 and cannot be deleted. What does that mean and how can one remove this?
joachim99@11 1976 </para></question><answer><para>
joachim99@11 1977 For each equal or different section the editor in the merge result
joachim99@11 1978 window remembers where it begins or ends. "&lt;No src line&gt;" means
joachim99@11 1979 that there is nothing left in a section, not even a new line character.
joachim99@11 1980 This can happen either while merging automatically or by editing. This is
joachim99@11 1981 no problem, since this hint won't appear in the saved file. If you want
joachim99@11 1982 the orignal source back just select the section (click on the left summary
joachim99@11 1983 column) and then click the source button with the needed contents (A/B or
joachim99@11 1984 C).
joachim99@11 1985 </para></answer></qandaentry>
joachim99@11 1986
joachim99@11 1987 <qandaentry><question><para>
joachim99@73 1988 Why doesn't &kdiff3; support syntax-highlighting?
joachim99@11 1989 </para></question><answer><para>
joachim99@73 1990 &kdiff3; already uses many colors for difference highlighting. More
joachim99@11 1991 highlighting would be confusing. Use another editor for this.
joachim99@11 1992 </para></answer></qandaentry>
joachim99@11 1993
joachim99@11 1994 <qandaentry><question><para>
joachim99@73 1995 Can I use &kdiff3; to compare OpenOffice.Org, Word, Excel, PDF-, &etc; files?
joachim99@69 1996 </para></question><answer><para>
joachim99@73 1997 Although &kdiff3; will analyse any kind of file the result will probably
joachim99@69 1998 not be very satisfactory for you.
joachim99@69 1999 </para><para>
joachim99@73 2000 &kdiff3; was made to compare pure text files. OpenOffice, Word, Excel etc.
joachim99@69 2001 store much more information in the files (about fonts, pictures, pages,
joachim99@73 2002 colors etc.) which &kdiff3; doesn't know about. So &kdiff3; will
joachim99@69 2003 show you the contents of the file interpreted as pure text, but
joachim99@69 2004 this might be unreadable or at least it will look very odd.
joachim99@69 2005 </para><para>
joachim99@69 2006 Since most programs nowadays store their contents in XML-format, you might
joachim99@69 2007 be able to read it as pure text. So if the change was only small,
joachim99@73 2008 &kdiff3; still might help you.
joachim99@69 2009 </para><para>
joachim99@69 2010 The best solution if you only want to compare the text (without embedded
joachim99@69 2011 objects like pictures) is to use "Select All" and "Copy" in your program
joachim99@73 2012 to copy the interesting text to the clipoard and then in &kdiff3; paste the
joachim99@69 2013 text into either diff input window.
joachim99@69 2014 (See also <link linkend="selections">Select, Copy And Paste</link>.)
joachim99@69 2015 </para></answer></qandaentry>
joachim99@69 2016
joachim99@69 2017 <qandaentry><question><para>
joachim99@69 2018 Where has the the directory option "List only deltas" gone?
joachim99@69 2019 </para></question><answer><para>
joachim99@69 2020 There are now several <link linkend="selectingvisiblefiles">"Show"-options</link> in the directory menu.
joachim99@69 2021 Disabling "Show identical files" will achieve what enabling "List only deltas" used to do.
joachim99@69 2022 </para></answer></qandaentry>
joachim99@69 2023
joachim99@69 2024 <qandaentry><question><para>
joachim99@69 2025 How can I make a big selection in the diff input window
joachim99@69 2026 because scrolling takes so long?
joachim99@69 2027 </para></question><answer><para>
joachim99@69 2028 Start the selection as usual (click and hold the left mouse button).
joachim99@69 2029 Then use the navigation keys (e.g. page up, page down) while holding the left mouse button down.
joachim99@69 2030 (See also <link linkend="selections">Select, Copy And Paste</link>.)
joachim99@69 2031 </para></answer></qandaentry>
joachim99@69 2032
joachim99@69 2033 <qandaentry><question><para>
joachim99@11 2034 There is so much information here, but your question is still not answered?
joachim99@11 2035 </para></question><answer><para>
joachim99@11 2036 Please send me your question. I appreciate every comment.
joachim99@11 2037 </para></answer></qandaentry>
joachim99@11 2038
joachim99@11 2039 </qandaset>
joachim99@11 2040 </chapter>
joachim99@11 2041
joachim99@11 2042 <chapter id="credits">
joachim99@11 2043
joachim99@11 2044 <title>Credits and License</title>
joachim99@11 2045
joachim99@11 2046 <para>
joachim99@11 2047 &kdiff3; - File and Directory Comparison and Merge Tool
joachim99@11 2048 </para>
joachim99@11 2049 <para>
joachim99@77 2050 Program copyright 2002-2007 Joachim Eibl <email>joachim.eibl at gmx.de</email>
joachim99@11 2051 </para>
joachim99@11 2052 <para>
joachim99@73 2053 Several cool ideas and bugreports came from colleagues and many people out in the Wild Wild Web. Thank you!
joachim99@11 2054 </para>
joachim99@11 2055
joachim99@11 2056 <para>
joachim99@77 2057 Documentation Copyright &copy; 2002-2007 Joachim Eibl <email>joachim.eibl at gmx.de</email>
joachim99@11 2058 </para>
joachim99@11 2059
joachim99@11 2060 <!-- TRANS:CREDIT_FOR_TRANSLATORS -->
joachim99@11 2061
joachim99@11 2062 &underFDL; <!-- FDL: do not remove -->
joachim99@11 2063
joachim99@11 2064
joachim99@11 2065 &underGPL; <!-- GPL License -->
joachim99@11 2066
joachim99@11 2067 </chapter>
joachim99@11 2068
joachim99@11 2069 <appendix id="installation">
joachim99@11 2070 <title>Installation</title>
joachim99@11 2071
joachim99@11 2072 <sect1 id="getting-kdiff3">
joachim99@11 2073 <title>How to obtain &kdiff3;</title>
joachim99@11 2074
joachim99@11 2075 <para>
joachim99@73 2076 You can download the latest version of &kdiff3; from its homepage <ulink url="http://kdiff3.sourceforge.net">http://kdiff3.sourceforge.net</ulink>.
joachim99@11 2077 </para><para>
joachim99@73 2078 &kdiff3; is also available for other platforms. See the homepage for details.
joachim99@11 2079 </para>
joachim99@11 2080
joachim99@11 2081
joachim99@11 2082 </sect1>
joachim99@11 2083
joachim99@11 2084 <sect1 id="requirements">
joachim99@11 2085 <title>Requirements</title>
joachim99@11 2086
joachim99@11 2087 <para>
joachim99@66 2088 In order to successfully use all features of &kdiff3;, you need &kde; >3.1.
joachim99@11 2089 </para><para>
joachim99@73 2090 For information about how to run &kdiff3; on other platforms without KDE please see the
joachim99@11 2091 <ulink url="http://kdiff3.sourceforge.net">homepage</ulink>.
joachim99@11 2092 </para><para>
joachim99@11 2093 You can find a list of changes at <ulink
joachim99@11 2094 url="http://kdiff3.sourceforge.net/ChangeLog">http://kdiff3.sourceforge.net/ChangeLog</ulink>
joachim99@11 2095 or in the "ChangeLog"-file of the source package.
joachim99@11 2096 </para>
joachim99@11 2097 </sect1>
joachim99@11 2098
joachim99@11 2099 <sect1 id="compilation">
joachim99@11 2100 <title>Compilation and Installation</title>
joachim99@11 2101
joachim99@11 2102 <para>In order to compile and install &kdiff3; on a system with KDE, type the
joachim99@11 2103 following in the base directory of the &kdiff3; distribution:</para>
joachim99@11 2104
joachim99@11 2105 <screen><prompt>%</prompt> <userinput><command>./configure --prefix=<replaceable>kde-dir</replaceable></command></userinput>
joachim99@11 2106 <prompt>%</prompt> <userinput><command>make</command></userinput>
joachim99@11 2107 <prompt>%</prompt> <userinput><command>make</command> install</userinput>
joachim99@11 2108 </screen>
joachim99@11 2109 <para>
joachim99@11 2110 <replaceable>kde-dir</replaceable> specifies the directory
joachim99@11 2111 containing KDE on your system. If you are not sure, read the README-file for details.
joachim99@11 2112 </para>
joachim99@69 2113 <para>If you don't use KDE don't use <command>configure</command> but follow the instructions for Qt-only systems in the README file.</para>
joachim99@11 2114 <para>Since &kdiff3; uses <command>autoconf</command> and
joachim99@11 2115 <command>automake</command> you should have no trouble compiling it. Should you
joachim99@11 2116 run into problems please report them to the &kde; mailing lists.</para>
joachim99@11 2117
joachim99@11 2118 </sect1>
joachim99@11 2119
joachim99@11 2120 </appendix>
joachim99@11 2121
joachim99@11 2122 &documentation.index;
joachim99@11 2123 </book>
joachim99@11 2124
joachim99@11 2125 <!--
joachim99@11 2126 Local Variables:
joachim99@11 2127 mode: sgml
joachim99@11 2128 sgml-minimize-attributes:nil
joachim99@11 2129 sgml-general-insert-case:lower
joachim99@11 2130 sgml-indent-step:0
joachim99@11 2131 sgml-indent-data:nil
joachim99@11 2132 End:
joachim99@11 2133
joachim99@11 2134 vim:tabstop=2:shiftwidth=2:expandtab
joachim99@11 2135 -->